js/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.
Writers snapshot accepted bytes, so callers can reuse their buffers before
flush() uploads the accumulated object.
Constructors
constructor(
readonly client: S3Client,
readonly prefix = '',
)
Create an async filesystem view over an S3 key prefix.