JavaScript (AWS SDK v3)

Fil One is fully compatible with the AWS SDK for JavaScript v3. Point the client at the Fil One endpoint and use the standard API.

Installation

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Client configuration

import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://eu-west-1.s3.fil.one",
  region: "eu-west-1",
  credentials: {
    accessKeyId: process.env.FIL_ACCESS_KEY,
    secretAccessKey: process.env.FIL_SECRET_KEY,
  },
  forcePathStyle: true,
});

Set FIL_ACCESS_KEY and FIL_SECRET_KEY as environment variables. Never hardcode credentials in source code.

Core operations

Create a bucket

import { CreateBucketCommand } from "@aws-sdk/client-s3";

await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" }));

Upload an object

import { PutObjectCommand } from "@aws-sdk/client-s3";
import { readFileSync } from "fs";

// Upload a buffer
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "data/file.json",
  Body: JSON.stringify({ key: "value" }),
  ContentType: "application/json",
}));

// Upload a file
await s3.send(new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "reports/report.pdf",
  Body: readFileSync("report.pdf"),
  ContentType: "application/pdf",
}));

Download an object

import { GetObjectCommand } from "@aws-sdk/client-s3";
import { writeFileSync } from "fs";

const response = await s3.send(new GetObjectCommand({
  Bucket: "my-bucket",
  Key: "reports/report.pdf",
}));

// Convert stream to buffer
const chunks = [];
for await (const chunk of response.Body) {
  chunks.push(chunk);
}
writeFileSync("local-report.pdf", Buffer.concat(chunks));

List objects

import { ListObjectsV2Command } from "@aws-sdk/client-s3";

let continuationToken;
do {
  const response = await s3.send(new ListObjectsV2Command({
    Bucket: "my-bucket",
    ContinuationToken: continuationToken,
  }));
  for (const obj of response.Contents ?? []) {
    console.log(obj.Key, obj.Size);
  }
  continuationToken = response.NextContinuationToken;
} while (continuationToken);

Delete an object

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteObjectCommand({
  Bucket: "my-bucket",
  Key: "reports/report.pdf",
}));

Presigned URLs

import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";

// Download URL valid for 1 hour
const downloadUrl = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: "my-bucket", Key: "reports/report.pdf" }),
  { expiresIn: 3600 }
);

// Upload URL valid for 15 minutes
const uploadUrl = await getSignedUrl(
  s3,
  new PutObjectCommand({ Bucket: "my-bucket", Key: "uploads/new-file.txt" }),
  { expiresIn: 900 }
);

Error handling

import { S3ServiceException } from "@aws-sdk/client-s3";

try {
  await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "missing.txt" }));
} catch (err) {
  if (err instanceof S3ServiceException) {
    console.error(err.name, err.message); // e.g. "NoSuchKey"
  } else {
    throw err;
  }
}

See the Error Reference for a full list of error codes.