storage
js/storage.ts
fino:storage - S3-compatible object storage and an async filesystem adapter.
AWS Signature Version 4 reference: https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html
The module signs S3-compatible HTTP requests, creates presigned URLs, exposes
a small object client, and maps object keys onto the FileSystem provider
contract. The filesystem is async and object-store-shaped; it does not claim
SQLite VFS compatibility because that path currently requires synchronous
provider methods.
Interfaces
interface S3Credentials {
Properties
accessKeyId: string
Access key id used in the SigV4 credential scope.
secretAccessKey: string
Secret access key used to derive the SigV4 signing key.
sessionToken?: string
Optional temporary-session token sent as x-amz-security-token.
interface S3ObjectHead {
Object metadata returned by headObject().
Properties
size: number
Object size in bytes from the Content-Length header.
etag: string | null
Entity tag returned by the service, or null when omitted.
interface S3ObjectSummary {
One object summary returned by listObjectsV2().
Properties
key: string
Object key relative to the bucket.
size: number
Object size in bytes.
etag?: string
Entity tag returned by the service.
lastModified?: string
Last-modified timestamp string returned by the service.
interface S3MultipartUpload {
Result of an S3 multipart upload creation.
Properties
key: string
Object key being uploaded.
uploadId: string
Provider upload id passed to subsequent multipart calls.
interface S3UploadedPart {
One uploaded multipart part.
Properties
partNumber: number
1-based multipart part number.
etag: string
Entity tag returned by the service for this part.
interface S3SignOptions {
Options for signing an S3-compatible request with SigV4.
Properties
region: string
AWS region used in the credential scope.
service?: string
SigV4 service name. Defaults to s3.
credentials: S3Credentials
Credentials used to derive the signature.
now?: Date
Signing timestamp. Defaults to the current time.
payloadHash?: string
Payload hash to sign. Defaults to UNSIGNED-PAYLOAD.
interface S3PresignOptions {
Options for creating a presigned S3-compatible URL.
Properties
region: string
AWS region used in the credential scope.
service?: string
SigV4 service name. Defaults to s3.
credentials: S3Credentials
Credentials used to derive the URL signature.
now?: Date
Signing timestamp. Defaults to the current time.
expiresIn?: number
URL lifetime in seconds. Defaults to 900.
interface S3ClientOptions {
Options for constructing an S3Client.
Properties
endpoint?: string
S3-compatible endpoint. Defaults to https://s3.amazonaws.com.
region: string
AWS region used when signing requests.
bucket?: string
Optional bucket name applied to object requests.
credentials: S3Credentials
Credentials used for all signed requests.
forcePathStyle?: boolean
Force path-style bucket addressing instead of virtual-host addressing.
fetch?: typeof fetch
Fetch implementation used for HTTP requests.
clock?: () => Date
Clock hook used for deterministic signing in tests.
interface S3ListObjectsOptions {
Options for S3Client.listObjectsV2().
Properties
prefix?: string
Prefix used to filter returned keys.
continuationToken?: string
Continuation token returned by a previous truncated response.
maxKeys?: number
Maximum number of keys requested from the service.
interface S3ListObjectsResult {
Result returned by S3Client.listObjectsV2().
Properties
objects: S3ObjectSummary[]
Object summaries in the current page.
isTruncated: boolean
Whether another page is available.
nextContinuationToken?: string
Token to pass as continuationToken for the next page.
Functions
async function signS3Request(input: Request, options: S3SignOptions): Promise<Request>
Sign an S3-compatible HTTP request with AWS Signature Version 4.
The input request is updated in place with host, x-amz-date,
x-amz-content-sha256, optional session-token, and authorization headers,
then returned for convenience.
async function presignS3Url(
method: string,
urlInput: string | URL,
options: S3PresignOptions
): Promise<URL>
Create a presigned S3 URL for browser or third-party upload/download flows.
The returned URL contains the SigV4 query parameters needed to authorize a single request with the supplied method and expiration window.
Classes
class S3Error extends Error {
Error raised for non-success S3 responses.
Constructors
constructor(message: string, readonly status: number)
Create an error with the failing HTTP status code.
class S3Client {
Minimal S3-compatible object client.
The client signs every request with SigV4 and supports common object, listing, and multipart-upload operations. It accepts any endpoint that speaks the S3 HTTP API closely enough for those operations.
Constructors
constructor(options: S3ClientOptions)
Create an S3-compatible client with injectable fetch and clock hooks.
Methods
async headObject(key: string): Promise<S3ObjectHead>
Load object metadata with HEAD.
async getObject(key: string): Promise<Response>
Download an object as a standard Response.
async putObject(key: string, body: BodyInit): Promise<void>
Upload or replace an object.
async deleteObject(key: string): Promise<void>
Delete an object if it exists.
async listObjectsV2(options: S3ListObjectsOptions = {}): Promise<S3ListObjectsResult>
List objects with the S3 ListObjectsV2 API.
async createMultipartUpload(key: string): Promise<S3MultipartUpload>
Start a multipart upload and return its upload id.
async uploadPart(
key: string,
uploadId: string,
partNumber: number,
body: BodyInit
): Promise<S3UploadedPart>
Upload one multipart part.
async completeMultipartUpload(
key: string,
uploadId: string,
parts: readonly S3UploadedPart[]
): Promise<void>
Complete a multipart upload with uploaded part metadata.
async abortMultipartUpload(key: string, uploadId: string): Promise<void>
Abort a multipart upload.
async multipartUpload(key: string, chunks: readonly BodyInit[]): Promise<void>
Convenience multipart upload using fixed-size chunks.
class S3FileSystem extends FileSystem {
Async FileSystem adapter backed by an S3 key prefix.
The adapter maps paths to object keys and supports object-shaped operations such as open, read, write, stat, and unlink. Directory handles, symlinks, rename, truncate, and positional writes are intentionally unsupported.
Constructors
constructor(readonly client: S3Client, readonly prefix = '')
Create an async filesystem view over an S3 key prefix.