JavaScript (AWS SDK v3)

Fil One works with the AWS SDK for JavaScript v3 — it is S3-API compatible. Point the client at the Fil One endpoint with forcePathStyle: true and use the standard API. A few S3 operations are not supported; see S3 Compatibility for the exceptions.

The endpoint depends on your bucket's region

Examples here use eu-west-1, the default region. For a bucket in us-east-1, use https://us-east-1.s3.filonecontent.com and region: "us-east-1". The endpoint, the region, and your access key must all refer to the same region.

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.filonecontent.com",
  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

CreateBucket is region-dependent. It is not available in eu-west-1 — use the Fil One dashboard there, via Buckets → Create bucket. In us-east-1, with a key that has the CreateBucket permission:

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

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

Note that versioning and Object Lock can only be set when the bucket is created, and only from the dashboard. See Buckets.

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.