YATTA
Docs
API reference

yatta/storage

Local and S3 disks, uploads, signed URLs, streaming.

49 exported symbols and 184 members, read from src/types/storage.ts.

Construct

createStorage

function

Factory function creating and registering a configured instance.

createStorage(config?: StorageConfig): StorageManager
config
Single disk or multi-disk configuration options.

Returns Configured instance.

tsts
import { createStorage } from "./storage"; export const storage = createStorage({  default: "local",  disks: {    local: { driver: "local", baseDir: "./uploads" },  },});

escapeHtml

function

Escapes HTML control characters to prevent XSS in the embedded explorer UI.

escapeHtml(str: string): string
str
Unsafe input string.

Returns HTML-safe escaped string.

guessContentType

function

Infers an appropriate MIME type from a filename extension.

guessContentType(filename: string): string
filename
File name or key.

Returns Inferred MIME type, or `"application/octet-stream"` as fallback.

matchMime

function

Evaluates whether a MIME type matches a pattern (supports exact and wildcards like `image/*` or `*`).

matchMime(type: string, pattern: string): boolean
type
Actual MIME type (e.g. `"image/png"`).
pattern
Filter pattern (e.g. `"image/*"`, `"*\/*"`).

Returns `true` if matched; otherwise `false`.

parseDuration

function

Parses a human-readable duration string into **seconds**.

parseDuration(val?: HumanTime): number
val
Duration string (e.g. `"30s"`, `"15m"`, `"1h"`, `"7d"`) or numeric seconds.

Returns Duration in seconds (defaults to 3600 if undefined or invalid).

tsts
parseDuration("1h");  // 3600parseDuration("30m"); // 1800parseDuration(120);   // 120

parseSize

function

Parses a human-readable size string into raw **bytes**.

parseSize(val?: HumanSize): number
val
Human size string (e.g. `"10MB"`, `"500KB"`, `"2GB"`) or numeric bytes.

Returns Number of bytes (defaults to 104,857,600 / 100MB if undefined).

tsts
parseSize("1KB");  // 1024parseSize("5MB");  // 5242880parseSize("1GB");  // 1073741824

resolveSigningSecret

function

Resolves the HMAC signing secret from config, environment variables, or generates

resolveSigningSecret(configuredSecret?: string): string
configuredSecret
Optional explicit secret provided in disk configuration.

Returns 32+ character signing secret.

safeConstantTimeEqual

function

Compares two strings in constant time to prevent side-channel timing attacks on signatures.

safeConstantTimeEqual(a: string, b: string): boolean
a
First string.
b
Second string.

Returns `true` if strings are identical; otherwise `false`.

sanitizeKey

function

Sanitizes a storage key, preventing directory traversal attacks (`../`),

sanitizeKey(key: string): string
key
Raw key input.

Returns Clean posix path.

verifyMagicBytes

function

Deep magic byte inspection across common file formats (JPEG, PNG, GIF, WEBP, PDF, ZIP, MP4, WebM, MP3, OGG).

verifyMagicBytes(buffer: Uint8Array, declaredMime: string): boolean
buffer
Byte slice from the file header.
declaredMime
Declared MIME type to verify against.

Returns `true` if valid or non-verifiable format; `false` on signature mismatch.

FileAlreadyExistsError

class

Thrown when an upload target already exists and overwrite policy is set to `"error"`.

class FileAlreadyExistsError extends StorageError

FileNotFoundError

class

Thrown when attempting to access, read, or manipulate a non-existent file key.

class FileNotFoundError extends StorageError

FileRef

class

Fluent reference targeting a specific file key on a .

class FileRef

23 members

  • write
    write(data: UploadInput, options?: UploadOptions): Promise<FileMetadata>

    Writes data to this file key.

    data
    Upload payload (Buffer, File, Stream, Object, etc.).
    options
    Upload options (MIME, size cap, overwrite policy).
  • put
    put(data: UploadInput, options?: UploadOptions): Promise<FileMetadata>

    Alias for .

  • read
    read(): Promise<StorageFile>

    Downloads and returns a instance for reading and streaming.

  • get
    get(): Promise<StorageFile>

    Alias for .

  • head
    head(): Promise<FileMetadata>

    Retrieves file metadata without downloading the body.

  • stat
    stat(): Promise<FileMetadata>

    Alias for .

  • exists
    exists(): Promise<boolean>

    Checks whether this file exists on disk.

  • ensureExists
    ensureExists(): Promise<this>

    Asserts that the file exists, throwing if missing.

    Returns `this` for chaining.

  • ensureNotExists
    ensureNotExists(): Promise<this>

    Asserts that the file does not exist, throwing if present.

    Returns `this` for chaining.

  • text
    text(): Promise<string>

    Reads and decodes file contents as a UTF-8 text string.

  • json
    json<T = unknown>(): Promise<T>

    Reads, decodes, and parses file contents as JSON.

  • buffer
    buffer(): Promise<Buffer>

    Reads file contents into a Node.js / Bun `Buffer`.

  • arrayBuffer
    arrayBuffer(): Promise<ArrayBuffer>

    Reads file contents into an `ArrayBuffer`.

  • stream
    stream(): Promise<ReadableStream<Uint8Array>>

    Opens a readable byte stream (`ReadableStream<Uint8Array>`) for this file.

  • blob
    blob(): Promise<Blob>

    Reads and returns file contents wrapped in a `Blob`.

  • delete
    delete(): Promise<void>

    Deletes this file from storage.

  • copyTo
    copyTo(destinationKey: string): Promise<FileMetadata>

    Copies this file to a new destination key.

    destinationKey
    Destination storage key.
  • moveTo
    moveTo(destinationKey: string): Promise<FileMetadata>

    Moves / renames this file to a new destination key.

    destinationKey
    Destination storage key.
  • url
    url(): string

    Returns the publicly accessible URL for this file.

  • expiresIn
    expiresIn(time: HumanTime): SignBuilder

    Initializes a configured with an expiration duration.

    time
    Expiration duration (e.g. `"1h"`, `"15m"`, or seconds).
  • sign
    sign(expiresIn?: HumanTime, method?: "GET" | "PUT"): Promise<string>

    Directly generates a time-limited signed URL for this file.

    expiresIn
    Expiration duration (defaults to `"1h"`).
    method
    Allowed HTTP method (`"GET"` or `"PUT"`).
  • serve
    serve(request?: Request | null, options?: ServeOptions): Promise<Response>

    Streams this file as an HTTP Response supporting RFC 9110 Range headers and conditional 304s.

    request
    Incoming HTTP `Request` or null.
    options
    Delivery options (cache control, headers, disposition).
  • download
    download(options?: { filename?: string; }): Promise<Response>

    Delivers this file as a downloadable attachment (`Content-Disposition: attachment`).

    options
    Download options including optional custom download filename.

FolderRef

class

Virtual directory handle scoping all operations under a given path prefix.

class FolderRef

6 members

  • prefixproperty
    prefix: string

    Normalized directory prefix without trailing slash.

  • file
    file(name: string): FileRef

    Returns a scoped within this folder.

    name
    File name or relative subpath.
  • put
    put(name: string): PutBuilder

    Returns a for writing a file scoped within this folder.

    name
    File name or relative subpath.
  • folder
    folder(subfolder: string): FolderRef

    Returns a nested subfolder .

    subfolder
    Child folder name.
  • list
    list(options?: Omit<ListOptions, "prefix">): Promise<FileMetadata[]>

    Lists all files residing under this folder prefix.

  • delete
    delete(): Promise<void>

    Deletes all files residing under this folder prefix (up to 10,000 files).

LocalStorageDriver

class

Storage driver operating directly on the local filesystem using Bun primitives (`Bun.file`, `Bun.write`).

class LocalStorageDriver implements IStorageDriver

16 members

  • baseDirproperty
    baseDir: string

    Resolved root directory path.

  • secretproperty
    secret: string
  • publicBaseUrlproperty
    publicBaseUrl: string
  • resolvePath
    resolvePath(key: string): string
  • upload
    upload(key: string, data: UploadInput, options?: UploadOptions): Promise<FileMetadata>
  • download
    download(key: string): Promise<StorageFile>
  • head
    head(key: string): Promise<FileMetadata>
  • delete
    delete(key: string): Promise<void>
  • deleteMany
    deleteMany(keys: string[]): Promise<void>
  • copy
    copy(sourceKey: string, destKey: string): Promise<FileMetadata>
  • move
    move(sourceKey: string, destKey: string): Promise<FileMetadata>
  • exists
    exists(key: string): Promise<boolean>
  • list
    list(options?: ListOptions): Promise<FileMetadata[]>
  • signedUrl
    signedUrl(key: string, options?: SignedUrlOptions): Promise<string>
  • verifySignedUrl
    verifySignedUrl(key: string, exp: number, sig: string, method?: ): boolean

    Verifies an HMAC signature and expiration timestamp for a local file request.

    key
    Target file key.
    exp
    Expiration epoch timestamp (in seconds).
    sig
    HMAC-SHA256 signature token.
    method
    Expected HTTP method (`"GET"` or `"PUT"`).

    Returns `true` if signature matches and is not expired; otherwise `false`.

  • publicUrl
    publicUrl(key: string): string

PreconditionFailedError

class

Thrown when an HTTP conditional precondition (`If-Match` or `If-None-Match`) fails.

class PreconditionFailedError extends StorageError

PutBuilder

class

Fluent builder for complex file upload configurations, content-addressed hashing,

class PutBuilder

15 members

  • from
    from(data: UploadInput): this

    Supplies the payload data to be stored.

    data
    Upload data (File, Buffer, Stream, Object, etc.).
  • withContentType
    withContentType(type: string): this

    Declares an explicit MIME Content-Type.

  • withMetadata
    withMetadata(meta: Record<string, string>): this

    Attaches custom user metadata key-values.

  • asPublic
    asPublic(): this

    Marks the upload as publicly readable (`acl: "public-read"`).

  • asPrivate
    asPrivate(): this

    Marks the upload as private (`acl: "private"`).

  • maxSize
    maxSize(limit: HumanSize): this

    Sets a maximum allowed byte size threshold.

  • verifyMagic
    verifyMagic(): this

    Enables binary header magic byte validation against the declared MIME type.

  • ifExists
    ifExists(policy: OverwritePolicy): this

    Configures overwrite handling (`"replace"`, `"error"`, or `"skip"`).

  • overwrite
    overwrite(allowed?: ): this

    Controls whether an existing file can be overwritten.

    allowed
    If `true`, replaces existing file; if `false`, throws error on collision.
  • noOverwrite
    noOverwrite(): this

    Disallows overwriting an existing file (throws on collision).

  • ifMatch
    ifMatch(etag: string): this

    Sets an `If-Match` ETag precondition for atomic updates.

  • ifNoneMatch
    ifNoneMatch(pattern?: ): this

    Sets an `If-None-Match` precondition (use `"*"` to ensure the file does not already exist).

  • unique
    unique(): this

    Generates a collision-free filename by appending a timestamp and random hex suffix.

  • hashName
    hashName(): this

    Enables content-addressed storage: names the file using its SHA-256 hash in a sharded folder (`sha256/xx/yy/<hash>.ext`).

  • save
    save(): Promise<FileMetadata>

    Executes the upload and returns file metadata.

S3StorageDriver

class

Storage driver connecting directly to AWS S3, Cloudflare R2, or MinIO via `Bun.S3Client`.

class S3StorageDriver implements IStorageDriver

14 members

  • clientproperty
    client: S3Client
  • bucketproperty
    bucket: string
  • customPublicUrlproperty
    customPublicUrl?: string
  • upload
    upload(key: string, data: UploadInput, options?: UploadOptions): Promise<FileMetadata>
  • download
    download(key: string): Promise<StorageFile>
  • head
    head(key: string): Promise<FileMetadata>
  • delete
    delete(key: string): Promise<void>
  • deleteMany
    deleteMany(keys: string[]): Promise<void>
  • copy
    copy(sourceKey: string, destKey: string): Promise<FileMetadata>
  • move
    move(sourceKey: string, destKey: string): Promise<FileMetadata>
  • exists
    exists(key: string): Promise<boolean>
  • list
    list(options?: ListOptions): Promise<FileMetadata[]>
  • signedUrl
    signedUrl(key: string, options?: SignedUrlOptions): Promise<string>
  • publicUrl
    publicUrl(key: string): string

SignBuilder

class

Fluent builder for generating signed URLs.

class SignBuilder

5 members

  • expiresIn
    expiresIn(time: HumanTime): this

    Sets the validity period of the signed URL.

    time
    Duration string (e.g. `"15m"`, `"2h"`, `"7d"`) or raw seconds.
  • forUpload
    forUpload(contentType?: string): this

    Configures the signed URL for uploading files via HTTP PUT.

    contentType
    Expected MIME type of the uploaded file.
  • forDownload
    forDownload(): this

    Configures the signed URL for downloading files via HTTP GET (default).

  • get
    get(): Promise<string>

    Generates and returns the cryptographic signed URL.

  • signed
    signed(): Promise<string>

    Alias for .

StorageDisk

class

Primary storage disk instance managing file storage, validation, security, and streaming.

class StorageDisk

17 members

  • file
    file(key: string): FileRef

    Returns a fluent targeting a specific file key.

  • put
    put(key: string): PutBuilder

    Returns a to upload and configure a file.

  • sign
    sign(key: string): SignBuilder

    Returns a to generate a signed URL for a key.

  • folder
    folder(prefix: string): FolderRef

    Returns a scoping operations to a virtual directory prefix.

  • upload
    upload(key: string, data: UploadInput, options?: UploadOptions): Promise<FileMetadata>

    Uploads and stores a file, applying MIME checking, size limits, magic-byte inspection,

    Processing Pipeline: 1. MIME resolution and pattern validation. 2. Size limit checks and proactive stream capping. 3. Non-destructive binary magic-byte verification (rewinds stream on completion). 4. Overwrite policy and HTTP precondition evaluation (`If-Match`, `If-None-Match`).

    key
    Target storage key.
    data
    Payload data.
    options
    Upload options.

    Returns Metadata for the stored file.

  • download
    download(key: string): Promise<StorageFile>

    Downloads a file and returns a instance for reading or streaming.

    key
    Target storage key.
  • head
    head(key: string): Promise<FileMetadata>

    Retrieves file metadata without downloading the body content.

    key
    Target storage key.
  • stat
    stat(key: string): Promise<FileMetadata>

    Alias for .

  • delete
    delete(key: string): Promise<void>

    Deletes a file by key.

  • deleteMany
    deleteMany(keys: string[]): Promise<void>

    Deletes multiple files concurrently.

  • copy
    copy(source: string, destination: string): Promise<FileMetadata>

    Copies a file to a new destination key.

  • move
    move(source: string, destination: string): Promise<FileMetadata>

    Moves / renames a file to a new destination key.

  • exists
    exists(key: string): Promise<boolean>

    Checks whether a file exists.

  • list
    list(options?: ListOptions): Promise<FileMetadata[]>

    Lists files matching optional prefix constraints.

  • search
    search(options: SearchOptions): Promise<FileMetadata[]>

    Searches for files by prefix, MIME type, and size range.

  • signedUrl
    signedUrl(key: string, options?: SignedUrlOptions): Promise<string>

    Generates a time-limited cryptographic signed URL for temporary file access.

  • publicUrl
    publicUrl(key: string): string

    Returns the public HTTP URL for the given key.

StorageError

class

Base error class thrown by Yatta Storage operations.

class StorageError extends Error

StorageFile

class

High-performance file handle providing reading, parsing, and RFC 9110 compliant HTTP delivery.

class StorageFile

8 members

  • stream
    stream(): ReadableStream<Uint8Array>

    Returns a fresh `ReadableStream<Uint8Array>` of the file contents.

  • arrayBuffer
    arrayBuffer(): Promise<ArrayBuffer>

    Reads and resolves the entire file as an `ArrayBuffer`.

  • buffer
    buffer(): Promise<Buffer>

    Reads and resolves the entire file as a Node.js / Bun `Buffer`.

  • text
    text(): Promise<string>

    Reads and decodes the entire file as a UTF-8 text string.

  • json
    json<T = unknown>(): Promise<T>

    Reads, decodes, and parses the file contents as JSON.

  • blob
    blob(): Promise<Blob>

    Reads and wraps the file contents as a WHATWG `Blob` with the correct MIME type.

  • serve
    serve(requestOrRange?: Request | string | null, options?: ServeOptions): Response

    Generates a fully compliant WHATWG HTTP `Response` implementing RFC 9110 HTTP streaming.

    Handles: - `200 OK`: Standard full-body delivery. - `206 Partial Content`: Byte-range requests (`Range: bytes=start-end`, suffix ranges). - `304 Not Modified`: Conditional checks (`If-None-Match`, `If-Modified-Since`). - `416 Range Not Satisfiable`: Out-of-bounds byte ranges. - `HEAD`: Validates metadata and headers without streaming body content.

    requestOrRange
    Incoming `Request` object, raw `Range` header string, or `null`.
    options
    Delivery options (cache control, content disposition, download name).

    Returns Configured WHATWG `Response`.

  • toResponse
    toResponse(requestOrRange?: Request | string | null, init?: ResponseInit): Response

    Convenience alias for `.serve(requestOrRange, { headers: init.headers })`.

    requestOrRange
    Incoming `Request` or range header.
    init
    Standard `ResponseInit` headers.

    Returns Configured WHATWG `Response`.

StorageManager

class

Multi-disk manager coordinating local filesystems, S3/R2 cloud storage,

class StorageManager

13 members

  • disksproperty
    disks:
  • defaultDiskNameproperty
    defaultDiskName:
  • authorizerproperty
    authorizer?: StorageAuthorizer
  • createDisk
    createDisk(cfg: DriverConfig, security?: StorageSecurityConfig, fallbackSecret?: string): StorageDisk
  • disk
    disk<D extends RegisteredDisks = RegisteredDisks>(name?: D): StorageDisk

    Selects a configured storage disk by name.

    name
    Name of the target disk. Defaults to the configured default disk.

    Returns The corresponding .

  • defaultDiskgetter
    defaultDisk: StorageDisk

    Returns the primary default storage disk.

  • file
    file(key: string): FileRef

    Returns a targeting a key on the default disk.

  • put
    put(key: string): PutBuilder

    Returns a for writing a file on the default disk.

  • sign
    sign(key: string): SignBuilder

    Returns a for generating a signed URL on the default disk.

  • folder
    folder(prefix: string): FolderRef

    Returns a scoping operations to a virtual directory on the default disk.

  • search
    search(options: SearchOptions): Promise<FileMetadata[]>

    Searches for files matching criteria on the default disk.

  • renderUI
    renderUI(options?: { title?: string; mountPath?: string; }): Response

    Renders the embedded zero-dependency Storage Explorer web dashboard.

    options
    Optional page title and mount path.

    Returns Complete HTML `Response`.

  • handleRequest
    handleRequest(req: Request, prefix?: ): Promise<Response>

    High-Performance Unified Request Router.

    Routes handled: - `GET <prefix>/`: Renders the Storage Explorer UI. - `GET <prefix>/api/files`: Lists files on the default disk. - `POST <prefix>/api/upload`: Handles multipart form file uploads. - `DELETE <prefix>/api/files?path=<key>`: Deletes a file. - `GET <prefix>/api/signed?path=<key>`: Generates a temporary signed URL. - `GET <prefix>/files/signed`: Serves files verified against cryptographic signed URLs. - `GET <prefix>/files/<key>`: Direct HTTP streaming delivery with byte-range support.

    req
    Incoming HTTP `Request`.
    prefix
    URL prefix mount path (defaults to `"/storage"`).

    Returns Generated WHATWG `Response`.

StorageSecurityError

class

Thrown when a path traversal attempt, null byte injection, or unauthorized access is detected.

class StorageSecurityError extends StorageError

Types

BaseDriverConfig

interface

Common configuration shared across all storage drivers.

interface BaseDriverConfig

1 member

  • publicUrlproperty
    publicUrl?: string

    Public base URL prefix used to generate public access URLs (e.g. `"/storage/files"`).

FileMetadata

interface

Standard file metadata contract returned by storage operations.

interface FileMetadata

7 members

  • pathproperty
    path: string

    Relative storage key (e.g. `"avatars/user.png"`).

  • sizeproperty
    size: number

    Total file size in bytes.

  • contentTypeproperty
    contentType: string

    Resolved or declared MIME type (e.g. `"image/png"`).

  • lastModifiedproperty
    lastModified: Date

    Timestamp when the file was last modified.

  • etagproperty
    etag?: string

    HTTP entity tag for caching and concurrency control.

  • urlproperty
    url: string

    Publicly resolvable URL to access the file.

  • metadataproperty
    metadata?: Record<string, string>

    Optional custom user-defined metadata key-value pairs.

IStorageDriver

interface

Common driver interface implemented by all storage backends (Local Disk, S3, R2, MinIO).

interface IStorageDriver

11 members

  • upload
    upload(key: string, data: UploadInput, options?: UploadOptions): Promise<FileMetadata>

    Uploads and stores a file.

  • download
    download(key: string): Promise<StorageFile>

    Downloads and returns a file handle.

  • head
    head(key: string): Promise<FileMetadata>

    Retrieves file metadata without downloading the body.

  • delete
    delete(key: string): Promise<void>

    Deletes a single file by key.

  • deleteMany
    deleteMany(keys: string[]): Promise<void>

    Deletes multiple files concurrently.

  • copy
    copy(sourceKey: string, destKey: string): Promise<FileMetadata>

    Copies a file from source key to destination key.

  • move
    move(sourceKey: string, destKey: string): Promise<FileMetadata>

    Moves a file from source key to destination key.

  • exists
    exists(key: string): Promise<boolean>

    Checks if a file exists.

  • list
    list(options?: ListOptions): Promise<FileMetadata[]>

    Lists files matching optional prefix constraints.

  • signedUrl
    signedUrl(key: string, options?: SignedUrlOptions): Promise<string>

    Generates a time-limited signed URL for temporary access.

  • publicUrl
    publicUrl(key: string): string

    Generates the public HTTP URL for the file key.

ListOptions

interface

Options for directory and prefix listings.

interface ListOptions

3 members

  • prefixproperty
    prefix?: string

    Filter results to keys starting with this prefix.

  • limitproperty
    limit?: number

    Maximum number of files to return (defaults to 1000).

  • cursorproperty
    cursor?: string

    Pagination continuation token.

LocalDriverConfig

interface

Configuration options for the local filesystem storage driver.

interface LocalDriverConfig

3 members

  • driverproperty
    driver: "local"

    Storage driver discriminant.

  • baseDirproperty
    baseDir: string

    Root directory on the local filesystem where files will be stored.

  • secretproperty
    secret?: string

    Secret key used to sign and verify HMAC URLs for this disk.

MultiDiskStorageConfig

interface

Multi-disk storage configuration contract.

interface MultiDiskStorageConfig

5 members

  • defaultproperty
    default?: string

    Name of the default disk used when none is specified.

  • disksproperty
    disks: Record<string, DriverConfig>

    Named map of configured storage disks.

  • securityproperty
    security?: StorageSecurityConfig

    Global security policy applied across all disks.

  • secretproperty
    secret?: string

    Fallback cryptographic secret for URL signing.

  • authorizeproperty
    authorize?: StorageAuthorizer

    Global authorization guard for request handling.

S3DriverConfig

interface

Configuration options for the S3 / Cloudflare R2 / MinIO storage driver.

interface S3DriverConfig

7 members

  • driverproperty
    driver: "s3"

    Storage driver discriminant.

  • bucketproperty
    bucket: string

    Target S3 bucket name.

  • accessKeyIdproperty
    accessKeyId?: string

    AWS or S3 access key ID.

  • secretAccessKeyproperty
    secretAccessKey?: string

    AWS or S3 secret access key.

  • endpointproperty
    endpoint?: string

    Custom endpoint URL for MinIO, Cloudflare R2, or Wasabi (e.g. `https://<account>.r2.cloudflarestorage.com`).

  • regionproperty
    region?: string

    AWS region (defaults to `"us-east-1"`).

  • sessionTokenproperty
    sessionToken?: string

    Optional AWS STS session token.

SearchOptions

interface

Filter criteria for disk search operations.

interface SearchOptions

5 members

  • prefixproperty
    prefix?: string

    Search within this prefix / directory path.

  • typeproperty
    type?: string

    MIME type pattern filter (e.g. `"image/*"`, `"video/mp4"`).

  • minSizeproperty
    minSize?: HumanSize

    Minimum file size threshold (e.g. `"1MB"`).

  • maxSizeproperty
    maxSize?: HumanSize

    Maximum file size threshold (e.g. `"50MB"`).

  • limitproperty
    limit?: number

    Maximum result count limit (defaults to 1000).

ServeOptions

interface

Options for rendering HTTP streaming responses via `.serve()`.

interface ServeOptions

4 members

  • cacheControlproperty
    cacheControl?: string

    HTTP `Cache-Control` header directive (e.g. `"public, max-age=31536000, immutable"`).

  • dispositionproperty
    disposition?: "inline" | "attachment"

    HTTP `Content-Disposition` delivery mode (`"inline"` or `"attachment"`).

  • downloadNameproperty
    downloadName?: string

    Custom filename supplied for downloads. Defaults to the key's base filename.

  • headersproperty
    headers?: HeadersInit

    Additional custom response headers to merge.

SignedUrlOptions

interface

Options for generating temporary cryptographic signed URLs.

interface SignedUrlOptions

3 members

  • expiresInproperty
    expiresIn?: HumanTime

    Lifetime of the URL before expiring. Defaults to `"1h"`.

  • methodproperty
    method?: "GET" | "PUT"

    HTTP method permitted by this signed URL (`"GET"` or `"PUT"`). Defaults to `"GET"`.

  • contentTypeproperty
    contentType?: string

    Required Content-Type for PUT upload signatures.

StorageAuthContext

interface

Context payload passed to callbacks for access control checks.

interface StorageAuthContext

4 members

  • requestproperty
    request: Request

    Incoming HTTP request triggering the action.

  • actionproperty
    action: StorageAction

    Action being attempted.

  • keyproperty
    key?: string

    Target file key or path, if applicable.

  • diskproperty
    disk?: string

    Target disk identifier.

StorageRegister

interface

Augment this interface in application code for strict autocomplete across named disks:

interface StorageRegister
tsts
declare module "./storage" {  interface StorageRegister {    disks: "local" | "s3" | "backups" | "uploads";  }}

StorageSecurityConfig

interface

Global disk security and validation constraints.

interface StorageSecurityConfig

5 members

  • maxUploadSizeproperty
    maxUploadSize?: HumanSize

    Global maximum upload size cap.

  • allowedTypesproperty
    allowedTypes?: string[]

    Whitelisted MIME types or patterns allowed for upload.

  • verifyMimeproperty
    verifyMime?: boolean

    Globally enforce magic-byte signature validation on uploads.

  • rejectUnknownMimeproperty
    rejectUnknownMime?: boolean

    Automatically reject generic `"application/octet-stream"` uploads.

  • signedUrlsproperty
    signedUrls?: boolean

    Restrict file access strictly to signed URLs.

UploadOptions

interface

Options for configuring upload operations.

interface UploadOptions

9 members

  • contentTypeproperty
    contentType?: string

    Explicit MIME type override. Defaults to auto-detection from file extension or content.

  • metadataproperty
    metadata?: Record<string, string>

    Arbitrary string metadata key-values attached to the file.

  • maxSizeproperty
    maxSize?: HumanSize

    Upper bound size limit (e.g. `"10MB"`, `5242880`). Breaching throws a 413 error.

  • allowedTypesproperty
    allowedTypes?: string[]

    List of permitted MIME types or wildcards (e.g. `["image/*", "application/pdf"]`).

  • aclproperty
    acl?: "public-read" | "private"

    S3 Access Control List setting.

  • verifyMagicBytesproperty
    verifyMagicBytes?: boolean

    Perform non-destructive binary header inspection to verify MIME authenticity.

  • ifExistsproperty
    ifExists?: OverwritePolicy

    Action taken if destination key exists: `"replace"`, `"error"`, or `"skip"`.

  • ifMatchproperty
    ifMatch?: string

    Perform conditional write only if destination ETag matches this value.

  • ifNoneMatchproperty
    ifNoneMatch?: string

    Perform conditional write only if destination does not match (e.g. `"*"` to forbid overwrite).

DriverConfig

type

Union of driver configuration types.

type DriverConfig = LocalDriverConfig | S3DriverConfig

HumanSize

type

Human-readable byte size string or raw size in bytes.

Supported units: - `"B"`: Bytes - `"KB"`: Kilobytes (1024 B) - `"MB"`: Megabytes (1024 KB) - `"GB"`: Gigabytes (1024 MB) - `"TB"`: Terabytes (1024 GB)

type HumanSize = `${number}${"B" | "KB" | "MB" | "GB" | "TB"}` | number

HumanTime

type

Human-readable duration string or raw duration in **seconds**.

Supported units: - `"s"`: Seconds - `"m"`: Minutes - `"h"`: Hours - `"d"`: Days - `"w"`: Weeks

type HumanTime = `${number}${"s" | "m" | "h" | "d" | "w"}` | number

OverwritePolicy

type

Strategy applied when writing to a key that already exists:

type OverwritePolicy = "replace" | "error" | "skip"

Prettify

type

Helper type to flatten complex intersected types for cleaner IDE hover tooltips.

type Prettify<T> = { [K in keyof T]: T[K]; } & {}

RegisteredDisks

type

Resolves the union of configured disk names from , or falls back to generic `string`.

type RegisteredDisks = StorageRegister extends { disks: infer D extends string; } ? D : string

StorageAction

type

Granular storage operations checked during authorization hooks.

type StorageAction = "read" | "write" | "delete" | "list" | "sign"

StorageAuthorizer

type

Authorization guard function returning `true` to allow or `false` to deny storage actions.

type StorageAuthorizer = (ctx: StorageAuthContext) => Promise<boolean> | boolean

StorageConfig

type

Combined configuration accepted by `createStorage`.

type StorageConfig = DriverConfig | (MultiDiskStorageConfig & { driver?: never; })

StorageProxy

type

Ambient proxy type combining and methods.

type StorageProxy = StorageManager & StorageDisk

UploadInput

type

Permitted input types for upload operations.

type UploadInput = File | Blob | Uint8Array | ArrayBuffer | Buffer | ReadableStream<Uint8Array> | string | Record<string, unknown> | unknown[]
Tip
Most of the types above are inferred. You rarely import AuthConfig or JobPayload — declaring your schema once is enough for the rest to follow. See Typed keys.