@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.

Part of AntelopeJS. Used by AntelopeJS DMS, the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.

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

| Module | Notes | | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | @antelopejs/file-storage-s3 | S3-compatible object storage (AWS S3, Cloudflare R2) | | @antelopejs/file-storage-local | Local filesystem, for development and single-instance deployments |

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

| Package | Supported | Tested with | | ---------------------------- | ---------------- | ----------- | | @antelopejs/interface-core | >=0.2.4 <1.0.0 | 0.4.0 |

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