S3

S3-compatible object storage client. Exposed as Rong.S3Client.

Quick Start

const client = new Rong.S3Client({
  accessKeyId: "your-access-key",
  secretAccessKey: "your-secret-key",
  bucket: "my-bucket",
  endpoint: "https://s3.us-east-1.amazonaws.com",
});

await client.write("hello.txt", "Hello World!");

const file = client.file("hello.txt");
const text = await file.text();

await client.delete("hello.txt");

Rong.S3Client

Constructor

const client = new Rong.S3Client({
  accessKeyId: "...",
  secretAccessKey: "...",
  bucket: "my-bucket",
  region: "us-east-1",
  endpoint: "https://...",
  sessionToken: "...",
  acl: "public-read",
  virtualHostedStyle: true,
});

All constructor options are optional at construction time, but actual requests require accessKeyId, secretAccessKey, and bucket.

Methods

`client.file(path, options?)`

Returns a lazy S3File reference. This does not perform any network request.

const file = client.file("data/report.json");
const file2 = client.file("other.txt", { bucket: "other-bucket" });

options uses the same config shape as the constructor and overrides the client config for that file handle.

`await client.write(path, data, options?)`

Upload data and return the number of bytes written.

await client.write("file.txt", "Hello World!");
await client.write("data.json", JSON.stringify(obj), {
  type: "application/json",
});

Accepted data types:

string
ArrayBuffer
Uint8Array

options.type overrides the content type. Other config fields in options override the client config for this request.

`await client.delete(path)` / `await client.unlink(path)`

Delete an object.

await client.delete("old-file.txt");

`await client.exists(path)`

Check whether an object exists.

const ok = await client.exists("config.json");

`await client.size(path)`

Get the object size in bytes.

const bytes = await client.size("large-file.bin");

`await client.stat(path)`

Get object metadata.

const stat = await client.stat("file.txt");
// {
//   etag: "\"abc123...\"",
//   lastModified: "...",
//   size: 1024,
//   type: "text/plain"
// }

`await client.presign(path, options?)`

Generate a presigned URL.

const getUrl = await client.presign("file.txt");
const putUrl = await client.presign("upload.bin", {
  expiresIn: 3600,
  method: "PUT",
});

Supported methods:

"GET"
"PUT"
"DELETE"

`await client.list(options?)`

List objects in the bucket.

const result = await client.list({
  prefix: "uploads/",
  maxKeys: 100,
  startAfter: "uploads/last-key",
});

// result.contents = [{ key, size, lastModified, etag? }, ...]
// result.isTruncated = boolean

list() currently fetches bucket pages from the backend and then applies startAfter and maxKeys on the returned results.

S3File

Lazy reference to an S3 object. Create it via client.file(). new S3File() is not allowed.

Reading

const file = client.file("data.json");

const text = await file.text();
const data = await file.json();
const buffer = await file.bytes();       // ArrayBuffer
const ab = await file.arrayBuffer();     // alias

Writing

await file.write("new content");
await file.write(JSON.stringify(data), { type: "application/json" });

Accepted write payloads:

string
ArrayBuffer
Uint8Array

Partial Reads

const first1k = file.slice(0, 1024);
const header = await first1k.text();

Metadata

file.name;             // "data.json"
file.size;             // NaN
await file.exists();   // boolean
await file.stat();     // { etag?, lastModified?, size, type? }

file.size is always NaN because S3 objects do not have synchronous size metadata; use await file.stat() or await client.size(path) instead.

Delete

await file.delete();
await file.unlink();

Presigned URL

const url = await file.presign({ expiresIn: 3600 });
const putUrl = await file.presign({ method: "PUT" });

Error Handling

try {
  await client.write("file.txt", data);
} catch (e) {
  // e.name === "S3Error"
}

Error codes:

ERR_S3_MISSING_CREDENTIALS
ERR_S3_INVALID_METHOD
ERR_S3

S3