@antelopejs/interface-file-storage

The AntelopeJS contract for file storage. Clients upload and download files directly with presigned URLs, and your module signs the URLs and manages the stored objects.

What it offers

• CreateUploadUrl signs a direct upload and checks its size and MIME type against your constraints.
• CreateReadUrl returns a permanent URL for a public file and an expiring one for a private file.
• WriteFile stores bytes the server already holds, without a presigned URL.
• ReadFile streams a file's bytes to the server itself, which may not reach the storage's public address.
• FileExists, GetFileMetadata, MoveFile and DeleteFile manage stored objects.
• Staged uploads stay under a staging prefix until PromoteFile confirms them, so abandoned uploads can expire.
• An optional storage name on each storage operation selects one of several buckets.
• Key helpers inspect or transform staging keys without accessing storage.

Implementations

Install

Add the interface to the module that handles files:

pnpm add @antelopejs/interface-file-storage

Then add an implementation to the project:

ajs project modules add @antelopejs/file-storage-s3

Quick start

import {
  CreateReadUrl,
  CreateUploadUrl,
} from "@antelopejs/interface-file-storage";

const MAX_AVATAR_BYTES = 2 * 1024 * 1024;

export async function prepareAvatarUpload(size: number) {
  const { uploadUrl, headers, resourceKey } = await CreateUploadUrl(
    { filename: "avatar.png", size, mimetype: "image/png", path: "avatars" },
    { maxSize: MAX_AVATAR_BYTES, allowedMimetypes: ["image/png"] },
  );
  return { uploadUrl, headers, resourceKey };
}

export async function avatarUrl(resourceKey: string) {
  const { url } = await CreateReadUrl(resourceKey, 3600);
  return url;
}

The client sends the file with a PUT to uploadUrl, including headers. Keep resourceKey to read, move or delete the file later.

Documentation

• Introduction
• File operations
• Provider promotion contract

Compatibility

The table lists the peer dependencies from package.json. @antelopejs/core is a development dependency, not a peer. Check the requirements of the implementing module too.

Contributing

Read CONTRIBUTING.md before you open a pull request. The local checks are:

pnpm install
pnpm lint
pnpm test

License

Apache-2.0