zerobucket 0.0.0-stage → 0.4.0

package/dist/client-WZ4VRCPi.d.cts

@@ -0,0 +1,425 @@
+import { Pool } from 'pg';
+
+/** Public data types returned by the ZeroBucket SDK. */
+/** A retrieved image, ready to be served or written to disk. `data` is raw bytes, never Base64. */
+interface Image {
+    data: Buffer;
+    mimeType: string;
+    filename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+/** Metadata about a stored image, without the pixel data. */
+interface ImageMetadata {
+    imageId: string;
+    mimeType: string;
+    filename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+/** Outcome of one item in a `putMany()` call. Batches are best-effort, not all-or-nothing. */
+interface BatchPutResult {
+    /** Position in the input array. */
+    index: number;
+    imageId: string | null;
+    error: string | null;
+    success: boolean;
+}
+/** Outcome of one id in a `getMany()` call. A missing id is not an exception here. */
+interface BatchGetResult {
+    imageId: string;
+    image: Image | null;
+    error: string | null;
+    success: boolean;
+}
+/** Outcome of one id in a `deleteMany()` call. `deleted: false` with no error means "did not exist". */
+interface BatchDeleteResult {
+    imageId: string;
+    deleted: boolean;
+    error: string | null;
+    success: boolean;
+}
+/** Emitted to `onOperation` after every storage operation (success or failure). */
+interface OperationEvent {
+    operation: string;
+    durationMs: number;
+    success: boolean;
+    error: string | null;
+    retryCount: number;
+}
+/**
+ * Anything with a pg-style `query()`: a `pg.Client`, a `pg.PoolClient`, or a
+ * transaction handle from a wrapper. Pass one as `connection` to make a
+ * ZeroBucket call participate in YOUR transaction. ZeroBucket then neither
+ * commits, rolls back, nor retries.
+ */
+interface Queryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+}
+/**
+ * The slice of a `better-sqlite3` Database that ZeroBucket's SQLite backend uses. Pass your own
+ * Database handle as `connection` to make a call part of YOUR SQLite transaction.
+ */
+interface SqliteDatabaseLike {
+    prepare(sql: string): {
+        all(...params: unknown[]): any[];
+        get(...params: unknown[]): any;
+        run(...params: unknown[]): {
+            changes: number;
+        };
+    };
+    exec(sql: string): unknown;
+}
+/** What `connection` accepts: a `pg` client for the Postgres backend, a `better-sqlite3` Database for SQLite. */
+type Connection = Queryable | SqliteDatabaseLike;
+/** The row shape a storage backend persists (after validation and checksumming). */
+interface PreparedRow {
+    data: Buffer;
+    mimeType: string;
+    originalFilename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+
+/**
+ * Storage backend interface.
+ *
+ * CRITICAL DESIGN RULE (same as the Python package): backends know nothing about
+ * images. They store and retrieve rows of bytes + metadata columns. All
+ * image-specific logic (validation, optimization, checksums) lives in client.ts.
+ *
+ * Every method accepts an optional `connection`. When omitted, the backend uses
+ * its own pool: each call commits independently and transient failures are
+ * retried. When provided, the backend uses it directly and does NOT commit,
+ * roll back or retry. That is what lets a call join the caller's transaction.
+ */
+
+interface StoredRecord {
+    id: string;
+    data: Buffer;
+    mimeType: string;
+    originalFilename: string | null;
+    sizeBytes: number;
+    width: number | null;
+    height: number | null;
+    checksumSha256: string;
+}
+type StoredRecordMetadata = Omit<StoredRecord, "data">;
+interface CallOptions {
+    connection?: Connection;
+}
+interface StreamOptions$1 extends CallOptions {
+    chunkSize: number;
+    /** Inclusive byte range [start, end]; `end` is clamped to the object size. Omit for the whole object. */
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+interface StorageBackend {
+    /** Resolve once the backend is connected and migrated. Safe to call repeatedly. */
+    ready(): Promise<void>;
+    put(row: PreparedRow, opts?: CallOptions): Promise<string>;
+    putMany(rows: PreparedRow[], opts?: CallOptions): Promise<string[]>;
+    get(id: string, opts?: CallOptions): Promise<StoredRecord | null>;
+    /** Missing ids are simply absent. Result order is NOT guaranteed to match input. */
+    getMany(ids: string[], opts?: CallOptions): Promise<StoredRecord[]>;
+    getMetadata(id: string, opts?: CallOptions): Promise<StoredRecordMetadata | null>;
+    /**
+     * Resolves to null if the id does not exist (checked eagerly, before any
+     * chunk is read). A row deleted mid-stream makes iteration throw
+     * StorageError rather than silently truncating.
+     */
+    getStream(id: string, opts: StreamOptions$1): Promise<AsyncIterable<Buffer> | null>;
+    delete(id: string, opts?: CallOptions): Promise<boolean>;
+    /** Returns the ids that were actually deleted. */
+    deleteMany(ids: string[], opts?: CallOptions): Promise<string[]>;
+    exists(id: string, opts?: CallOptions): Promise<boolean>;
+    /** null = no such image, false = already tiered (no-op), true = tiered now. Needs object storage configured. */
+    tierToObjectStorage(id: string, opts?: CallOptions): Promise<boolean | null>;
+    /** Dedup-mode instances only: copy the classic table into the dedup tables (non-destructive). */
+    migrateClassicToDedup?(): Promise<{
+        imagesMigrated: number;
+        distinctBlobsCreated: number;
+        duplicateReferencesFound: number;
+        alreadyMigrated: number;
+    }>;
+    close(): Promise<void>;
+}
+
+/** The surface the Postgres adapter needs. Implement this to plug in a non-S3 store (or a test double). */
+interface ObjectStorageLike {
+    readonly bucket: string;
+    upload(key: string, data: Buffer, opts: {
+        mimeType: string;
+    }): Promise<void>;
+    download(key: string): Promise<Buffer>;
+    /** Inclusive byte range, fetched with a real HTTP Range request. */
+    downloadRange(key: string, start: number, endInclusive: number): Promise<Buffer>;
+    /** Idempotent: deleting a missing key is not an error. */
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+interface ObjectStorageOptions {
+    /** Must already exist. */
+    bucket: string;
+    /** Set for anything that is not AWS S3 itself (MinIO, R2, B2, Spaces, ...). */
+    endpoint?: string;
+    /** Default: AWS_REGION / AWS_DEFAULT_REGION, else "us-east-1". Many S3-compatible services ignore it but the SDK requires one. */
+    region?: string;
+    /** Default: the SDK's standard chain (env vars, shared config, IAM role, ...). */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    /** Path-style addressing (`endpoint/bucket/key`). Default: true when `endpoint` is set, else false. */
+    forcePathStyle?: boolean;
+    /** Bring your own configured S3Client (advanced). */
+    client?: unknown;
+}
+declare class ObjectStorage implements ObjectStorageLike {
+    private readonly opts;
+    readonly bucket: string;
+    private clientPromise;
+    constructor(opts: ObjectStorageOptions);
+    private connection;
+    upload(key: string, data: Buffer, { mimeType }: {
+        mimeType: string;
+    }): Promise<void>;
+    download(key: string): Promise<Buffer>;
+    downloadRange(key: string, start: number, endInclusive: number): Promise<Buffer>;
+    private get;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+
+interface OptimizeOptions {
+    /** Downscale (aspect ratio preserved, Lanczos) if wider than this. Never upscales. */
+    maxWidth?: number;
+    /** "jpeg" | "png" | "webp". Defaults to the source format. */
+    format?: string;
+    /** 1-100, JPEG/WebP only (ignored for PNG). */
+    quality?: number;
+}
+interface OptimizationResult {
+    data: Buffer;
+    mimeType: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    originalSizeBytes: number;
+}
+declare function optimizeImage(data: Buffer, opts: OptimizeOptions & {
+    maxBytes: number;
+    maxPixels?: number;
+}): Promise<OptimizationResult>;
+
+/** Pluggable content validation (the npm equivalent of Python's ContentValidator). */
+interface ValidatedContent {
+    mimeType: string;
+    sizeBytes: number;
+    width?: number | null;
+    height?: number | null;
+}
+/**
+ * Implement this to let `put()` / `putMany()` accept a content type ZeroBucket
+ * does not natively understand. It must throw (ideally a
+ * `ContentValidationError`) when the content is invalid, and must trust nothing
+ * but the bytes themselves.
+ */
+interface ContentValidator {
+    validate(data: Buffer, opts: {
+        maxBytes: number;
+    }): ValidatedContent | Promise<ValidatedContent>;
+}
+
+/** 8 MiB: a practical ceiling for "small app" images. Override with `maxBytes`. */
+declare const DEFAULT_MAX_BYTES: number;
+/**
+ * What put() accepts:
+ *  - Buffer / Uint8Array / ArrayBuffer: the bytes themselves
+ *  - string: a filesystem PATH (never raw content)
+ *  - Blob / File (e.g. from `request.formData()`)
+ *  - Node Readable or web ReadableStream (read in bounded chunks)
+ */
+type ImageInput = Buffer | Uint8Array | ArrayBuffer | string | Blob | AsyncIterable<Uint8Array | string>;
+type BeforeGetHook<C = unknown> = (imageId: string, context: C | undefined) => boolean | Promise<boolean>;
+type BeforePutHook<C = unknown> = (context: C | undefined) => boolean | Promise<boolean>;
+interface ZeroBucketOptions<C = unknown> {
+    /** PostgreSQL connection string. */
+    connectionString?: string;
+    /** Bring your own pg.Pool. It is NOT closed by close(). */
+    pool?: Pool;
+    /**
+     * Use SQLite instead of PostgreSQL: a database file path (or ":memory:"). Needs `npm install better-sqlite3`.
+     * `dedup`, `objectStorage`, `autoMigrate` and `onOperation` apply to it too. Same file format as the Python
+     * package's SQLiteBackend, so both can share one `.db` file.
+     */
+    sqlite?: string;
+    /** Advanced: inject a custom StorageBackend instead of building one from `connectionString` / `pool` / `sqlite`. */
+    backend?: StorageBackend;
+    /** Max accepted size in bytes. Default 8 MiB. */
+    maxBytes?: number;
+    /** Decoded-pixel ceiling that rejects decompression bombs. Default ~89 MP. */
+    maxPixels?: number;
+    /** Accepted image formats. Default ["jpeg", "png", "webp"]. */
+    allowedFormats?: readonly string[];
+    autoMigrate?: boolean;
+    maxRetries?: number;
+    retryBaseDelayMs?: number;
+    poolMinSize?: number;
+    poolMaxSize?: number;
+    poolTimeoutMs?: number;
+    /** Fire-and-forget observability. Exceptions thrown inside it are swallowed. */
+    onOperation?: (event: OperationEvent) => void;
+    /**
+     * S3-compatible object storage, enabling `tierToObjectStorage()` and transparent
+     * reads of images the Python or Node package tiered. Configure it with the same
+     * bucket and credentials used to tier. Without it, reading a tiered image throws
+     * a clear StorageError.
+     */
+    objectStorage?: ObjectStorageLike;
+    /**
+     * Content-addressed mode: identical bytes are stored once and shared by reference, each image
+     * keeping its own id and filename. Cannot be combined with `objectStorage`. Uses separate tables
+     * (zerobucket_blobs / zerobucket_image_refs); see `migrateClassicToDedup()` for existing data.
+     */
+    dedup?: boolean;
+    /**
+     * Authorization hook for get / getMany (per id) / getStream / streamTo / metadata.
+     * Return false to deny. A hook that THROWS fails closed: the exception
+     * propagates (or is captured per item in getMany) and is never treated as allow.
+     * NOT called for exists().
+     */
+    beforeGet?: BeforeGetHook<C>;
+    /** Authorization hook for put / putMany (evaluated once per call). Same fail-closed rule. */
+    beforePut?: BeforePutHook<C>;
+}
+interface PutBase<C> {
+    /** Display filename stored in metadata (never used for validation). */
+    filename?: string;
+    /** `true` = strip metadata only; or pass { maxWidth, format, quality } to resize/re-encode. */
+    optimize?: boolean | OptimizeOptions;
+    /** Store non-image content through the same machinery. Incompatible with `optimize`. */
+    validator?: ContentValidator;
+    /** Join your own transaction. ZeroBucket then does not commit, roll back or retry. */
+    connection?: Connection;
+    /** Passed to beforePut. */
+    context?: C;
+}
+type PutOptions<C = unknown> = PutBase<C>;
+interface PutManyOptions<C = unknown> extends Omit<PutBase<C>, "filename"> {
+    /** Same length as `images`; use null/undefined entries to fall back to each input's own name. */
+    filenames?: (string | null | undefined)[];
+}
+interface GetOptions<C = unknown> {
+    connection?: Connection;
+    context?: C;
+}
+interface StreamOptions<C = unknown> extends GetOptions<C> {
+    /** Bytes per chunk. Default 1 MiB. */
+    chunkSize?: number;
+    /** Inclusive byte range, e.g. { start: 0, end: 1023 }. `end` is clamped to the object size. */
+    range?: {
+        start: number;
+        end?: number;
+    };
+}
+/** Anything with write(); e.g. fs.WriteStream, http.ServerResponse, or a custom sink. Backpressure is honoured. */
+interface WritableLike {
+    write(chunk: Buffer): boolean | void | Promise<void>;
+    once?(event: "drain", listener: () => void): unknown;
+}
+declare class ZeroBucket<C = unknown> {
+    private readonly backend;
+    private readonly maxBytes;
+    private readonly maxPixels;
+    private readonly allowedFormats;
+    private readonly beforeGet;
+    private readonly beforePut;
+    constructor(options?: ZeroBucketOptions<C>);
+    /** Construct AND connect/migrate immediately, so a bad DATABASE_URL fails at startup, not on first request. */
+    static connect<C = unknown>(options?: ZeroBucketOptions<C>): Promise<ZeroBucket<C>>;
+    /** Resolves once connected and migrated. Called automatically on first use. */
+    ready(): Promise<void>;
+    private checkBeforeGet;
+    private checkBeforePut;
+    private prepareRow;
+    /** Validate, optionally optimize, checksum and store one image. Returns its id (a UUID). */
+    put(image: ImageInput, options?: PutOptions<C>): Promise<string>;
+    /**
+     * Store many images. Best-effort, not all-or-nothing: one bad image does not
+     * abort the rest. Check each result's `success` / `error`. Settings apply to
+     * every item. Valid items are inserted in ONE transaction.
+     */
+    putMany(images: ImageInput[], options?: PutManyOptions<C>): Promise<BatchPutResult[]>;
+    /** Retrieve a full image including bytes. Throws ImageNotFoundError if missing. */
+    get(imageId: string, options?: GetOptions<C>): Promise<Image>;
+    /**
+     * Retrieve many images in one query. Results come back in input order; a
+     * missing id is `error: "not found"`, not an exception. A hook denial or hook
+     * exception affects only that id.
+     */
+    getMany(imageIds: string[], options?: GetOptions<C>): Promise<BatchGetResult[]>;
+    /**
+     * Stream an image's bytes in chunks without holding the whole image in memory.
+     * Not-found is checked eagerly: the returned promise rejects before any chunk
+     * is read. A concurrent delete mid-stream makes iteration throw StorageError
+     * rather than silently truncating. Pass `range` for partial reads.
+     *
+     * Honest limitation: reduces Node-side memory, not Postgres-side (the server
+     * still handles the full BYTEA value per chunk request).
+     */
+    getStream(imageId: string, options?: StreamOptions<C>): Promise<AsyncIterable<Buffer>>;
+    /** Same as getStream(), as a Web `ReadableStream` you can hand straight to `new Response(...)`. */
+    toWebStream(imageId: string, options?: StreamOptions<C>): Promise<ReadableStream<Uint8Array>>;
+    /** Write an image to `destination` chunk by chunk (honouring backpressure). Returns bytes written. Does not end the destination. */
+    streamTo(imageId: string, destination: WritableLike, options?: StreamOptions<C>): Promise<number>;
+    /** Metadata without pulling the bytes. Gated by the same beforeGet hook as get(). */
+    metadata(imageId: string, options?: GetOptions<C>): Promise<ImageMetadata>;
+    /** Whether an image exists. Deliberately NOT gated by beforeGet (returns no data or metadata). */
+    exists(imageId: string, options?: Pick<CallOptions, "connection">): Promise<boolean>;
+    /** Delete an image. Returns true if it existed. */
+    delete(imageId: string, options?: Pick<CallOptions, "connection">): Promise<boolean>;
+    /** Delete many in one query. Results are in input order; a missing id is `deleted: false`, not an error. */
+    deleteMany(imageIds: string[], options?: Pick<CallOptions, "connection">): Promise<BatchDeleteResult[]>;
+    /**
+     * Move an image's bytes from Postgres into object storage; reads, streams and
+     * deletes keep working transparently. Returns true if tiered now, false if it was
+     * already tiered (safe to re-run in a backfill). Throws ImageNotFoundError if missing.
+     *
+     * The upload runs inside the database transaction: if it fails, the row is left
+     * completely untouched. Explicit and opt-in: put() never tiers automatically.
+     * Not gated by beforeGet/beforePut (it is a maintenance operation, as in the Python package).
+     */
+    tierToObjectStorage(imageId: string, options?: Pick<CallOptions, "connection">): Promise<boolean>;
+    /**
+     * One-time, non-destructive copy of classic-mode images into a dedup instance's tables, keeping every
+     * id. Call it on an instance created with `dedup: true`. Safe to re-run. See PostgresBackend for details.
+     */
+    migrateClassicToDedup(): ReturnType<NonNullable<StorageBackend["migrateClassicToDedup"]>>;
+    /** Release the pool (if ZeroBucket created it). */
+    close(): Promise<void>;
+}
+/**
+ * Read any supported input into a Buffer. Streams are consumed in bounded
+ * chunks and rejected as soon as they pass maxBytes (reported size is then a
+ * lower bound), rather than buffering an arbitrarily large upload first.
+ * Files and Blobs are size-checked BEFORE their bytes are read.
+ */
+declare function readInput(image: ImageInput, filename: string | undefined, maxBytes: number): Promise<{
+    data: Buffer;
+    filename: string | undefined;
+}>;
+
+export { type BatchDeleteResult as B, type CallOptions as C, DEFAULT_MAX_BYTES as D, type GetOptions as G, type Image as I, type OperationEvent as O, type PreparedRow as P, type Queryable as Q, type StorageBackend as S, type ValidatedContent as V, type WritableLike as W, ZeroBucket as Z, type ObjectStorageLike as a, type StoredRecord as b, type StoredRecordMetadata as c, type StreamOptions$1 as d, type ContentValidator as e, type BatchGetResult as f, type BatchPutResult as g, type BeforeGetHook as h, type BeforePutHook as i, type Connection as j, type ImageInput as k, type ImageMetadata as l, ObjectStorage as m, type ObjectStorageOptions as n, type OptimizationResult as o, type OptimizeOptions as p, type PutManyOptions as q, type PutOptions as r, type SqliteDatabaseLike as s, type StreamOptions as t, type ZeroBucketOptions as u, optimizeImage as v, readInput as w };