Archil

Archil disks via the S3-compatible API. The disk id is the bucket and the endpoint is derived from the Archil region. Supports branch-scoped access.

Installation

@aws-sdk/client-s3, @aws-sdk/s3-presigned-post, and @aws-sdk/s3-request-presigner are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime. The disk package is also optional - install it only if you pass a Disk instance to reach Archil-native operations.

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

yarn add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

bun add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

Usage

import { Files } from "files-sdk";
import { archil } from "files-sdk/archil";

const files = new Files({
  adapter: archil({
    bucket: "dsk-0123456789abcdef", // your Archil disk id
    region: "aws-us-east-1",
    // accessKeyId / secretAccessKey auto-loaded from
    // ARCHIL_S3_ACCESS_KEY_ID / ARCHIL_S3_SECRET_ACCESS_KEY
  }),
});

Archil disks via their S3-compatible API. A thin wrapper around the S3 adapter - the disk id is the path-style bucket, the endpoint is derived from the Archil region (aws-us-east-1, gcp-us-central1, …), and SigV4 signs every request, so byte ranges, multipart uploads, and presigned url() / signedUploadUrl() all work. Auto-loads ARCHIL_S3_ACCESS_KEY_ID, ARCHIL_S3_SECRET_ACCESS_KEY, and ARCHIL_REGION.

Branches

Set branch to scope the whole unified surface to a branch of the disk - upload, download, list, and presigned URLs all read and write that branch:

const preview = new Files({
  adapter: archil({
    branch: "preview",
    bucket: "dsk-0123456789abcdef",
    region: "aws-us-east-1",
  }),
});

Archil-native operations

The unified surface covers object storage. For Archil-native operations that aren’t object storage - exec, grep, appendObject, share - pass a Disk instance (from the disk package); it’s exposed at files.adapter.disk, and bucket / region are inferred from it:

import { getDisk } from "disk";

const disk = await getDisk("dsk-0123456789abcdef");
const files = new Files({ adapter: archil({ disk }) });

await files.upload("src/app.ts", code); // unified surface
await files.adapter.disk?.exec("tsc --noEmit"); // Archil-native

Options

PropType

accessKeyId?string

Archil S3 access key id. Falls back to `ARCHIL_S3_ACCESS_KEY_ID`.

Typestring

bucket?string

The disk id to scope operations to — Archil's equivalent of a bucket. Optional only when a `disk` instance is passed instead.

Typestring

branch?string

Scope every operation to a branch of the disk instead of its main view. Archil selects the branch via the bucket, so the entire unified surface — `upload`, `download`, `list`, `url`, presigned uploads — transparently reads and writes that branch. Omit for the disk's default branch. Must be non-empty and contain no `/`.

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for presigned URLs from `url()` when `publicBaseUrl` is not set. Defaults to 3600.

Typenumber

disk?Disk

An Archil {@link Disk} (from the `disk` package). When provided, `bucket` and `region` default to the instance's `id` and `region`, and it is exposed at {@link ArchilAdapter.disk} — the door to Archil-native operations (`exec`, `grep`, `appendObject`, `share`) that the S3 `raw` client can't reach. Requires the optional `disk` peer dependency.

TypeDisk

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` unsigned; otherwise `url()` mints a SigV4 presigned GetObject.

Typestring

region?string

Archil region, e.g. `aws-us-east-1` or `gcp-us-central1`. Defaults to the `disk` instance's region when one is passed, else falls back to `ARCHIL_REGION`. Selects which Archil endpoint the adapter talks to.

Typestring

secretAccessKey?string

Archil S3 secret access key. Falls back to `ARCHIL_S3_SECRET_ACCESS_KEY`.

Typestring

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	✅
`search`	✅
`head`	✅
`exists`	✅
`copy`	✅
`url`	✅	SigV4 presigned, or `publicBaseUrl` when set.
`signedUploadUrl`	✅