zerobucket 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,228 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# zerobucket (npm)
+
+**Database-native image storage for Node.js. Your database. Your images. Zero buckets.**
+
+Store small-to-medium image collections (avatars, product photos, uploads) as ordinary
+Postgres rows, with validation, optimization, streaming, range requests and access
+control built in, and no S3 account to provision for the common case.
+
+This is the Node.js/TypeScript sibling of the [Python package](https://pypi.org/project/zerobucket/).
+**It uses the exact same table**, so a Node service and a Python service can share one database
+and read each other's images.
+
+> **Status: 0.1.0.** PostgreSQL, classic mode. Dedup, object-storage tiering, SQLite and MySQL
+> are on the roadmap (see [What's not here yet](#whats-not-here-yet)).
+
+## Install
+
+```bash
+npm install zerobucket pg sharp
+```
+
+`pg` (the Postgres driver) and `sharp` (image decoding/optimizing) are peer dependencies, so you
+control their versions. If you only store PDFs through a custom validator, `sharp` is not needed.
+Requires Node 20+. Ships ESM and CommonJS with full types.
+
+## Quick start
+
+```ts
+import { ZeroBucket } from "zerobucket";
+
+const images = await ZeroBucket.connect({
+  connectionString: process.env.DATABASE_URL,
+});
+// connect() runs the migration up front, so a bad DATABASE_URL fails at startup, not on the first request.
+// `new ZeroBucket({...})` also works and connects lazily on first use.
+
+const id = await images.put(fileBuffer, { filename: "avatar.jpg" }); // returns a UUID
+const image = await images.get(id); // { data: Buffer, mimeType, width, height, checksumSha256, ... }
+const meta = await images.metadata(id); // no bytes pulled
+await images.delete(id);
+```
+
+The format is detected from the **bytes** (decoded with libvips), never from the filename or a
+client-supplied MIME type. Truncated files, decompression bombs (`maxPixels`), and oversized
+uploads (`maxBytes`, default 8 MiB) are rejected with specific error classes.
+
+## Serve images over HTTP (full-stack use)
+
+`zerobucket/http` turns a bucket into a standard `(Request) => Response` handler with
+**ETag / 304, Range / 206, If-Range, 416, HEAD**, streamed from the database in chunks.
+
+### Next.js (App Router)
+
+```ts
+// app/images/[id]/route.ts
+import { createImageHandler } from "zerobucket/http";
+import { images } from "@/lib/images";
+
+const handler = createImageHandler(images, {
+  getContext: async (req) => ({ userId: await currentUserId(req) }), // for your beforeGet hook
+});
+
+export async function GET(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  return handler(req, { id: (await params).id });
+}
+export { GET as HEAD };
+```
+
+Then `<img src="/images/{id}">`. Browsers get proper caching and video-style seeking for free.
+
+### Express / Fastify / `node:http`
+
+```ts
+import { createImageHandler, toNodeHandler } from "zerobucket/http";
+const serve = toNodeHandler(createImageHandler(images));
+app.get("/images/:id", (req, res) => serve(req, res, { id: req.params.id }));
+```
+
+### Uploads
+
+```ts
+// Next.js route handler
+export async function POST(req: Request) {
+  const form = await req.formData();
+  const file = form.get("file") as File; // File/Blob accepted directly; size-checked before reading
+  const id = await images.put(file, {
+    optimize: { maxWidth: 1600, format: "webp" },
+  });
+  return Response.json({ id });
+}
+```
+
+`put()` accepts a `Buffer`/`Uint8Array`, a file **path** string, a `Blob`/`File`, or a Node/web
+stream (read in bounded chunks and rejected as soon as it passes `maxBytes`).
+
+**Cache-Control** defaults to `private, no-cache` (always revalidate; the ETag makes that a cheap
+304), which is safe for access-controlled images. For public images pass
+`cacheControl: "public, max-age=31536000, immutable"`.
+
+## Access control
+
+```ts
+const images = new ZeroBucket<{ userId: string }>({
+  connectionString,
+  beforeGet: async (imageId, ctx) => (await owner(imageId)) === ctx?.userId,
+  beforePut: (ctx) => !!ctx?.userId,
+});
+await images.get(id, { context: { userId } }); // throws AccessDeniedError if the hook returns false
+```
+
+**A hook that throws fails closed**: the original exception propagates; it is never treated as
+"allow". Denied calls never reach the database. `exists()` is deliberately not gated.
+
+## Streaming and ranges
+
+```ts
+for await (const chunk of await images.getStream(id, { chunkSize: 256 * 1024 })) { ... }
+await images.streamTo(id, res);                                  // honours backpressure
+const web = await images.toWebStream(id);                        // → new Response(web)
+await images.getStream(id, { range: { start: 0, end: 1023 } });  // server-side byte range
+```
+
+Not-found is checked eagerly (the promise rejects before any chunk). A row deleted mid-stream makes
+iteration throw `StorageError` rather than silently truncating. Pass your own transaction as
+`connection` for a snapshot-consistent read. This lowers **Node-side** memory; Postgres still
+handles the whole `BYTEA` value per chunk request.
+
+## Transactions
+
+Pass any `pg` client to make a call part of **your** transaction. ZeroBucket then does not commit,
+roll back or retry:
+
+```ts
+const client = await pool.connect();
+try {
+  await client.query("BEGIN");
+  const avatarId = await images.put(buf, { connection: client });
+  await client.query("UPDATE users SET avatar_id = $1 WHERE id = $2", [
+    avatarId,
+    userId,
+  ]);
+  await client.query("COMMIT"); // row + image commit (or roll back) together
+} catch (e) {
+  await client.query("ROLLBACK");
+  throw e;
+} finally {
+  client.release();
+}
+```
+
+## Batches
+
+`putMany` / `getMany` / `deleteMany` are best-effort per item (one bad file doesn't abort the rest):
+check each result's `success` / `error`. `putMany` inserts all valid items in one transaction.
+
+## Optimize pipeline, custom validators
+
+```ts
+await images.put(buf, {
+  optimize: { maxWidth: 1200, format: "webp", quality: 80 },
+});
+
+import { PDFValidator } from "zerobucket";
+await images.put(pdfBuf, { validator: new PDFValidator() }); // any ContentValidator works
+```
+
+Optimize strips metadata, applies EXIF orientation first, never upscales, and re-validates its own
+output. Implement `ContentValidator` (`validate(data, { maxBytes })`) to store other content types.
+
+## Reliability and observability
+
+- Pooling: `poolMinSize` (1), `poolMaxSize` (5), `poolTimeoutMs` (10000), or pass your own `pool`
+  (e.g. a tiny pool for serverless).
+- Automatic retry (`maxRetries` 3, `retryBaseDelayMs` 100, exponential backoff with jitter) for
+  transient errors only (deadlocks, serialization failures, connection loss). A retry **re-runs the
+  whole transaction** on a fresh connection; permanent errors are never retried.
+  Caveat shared with the Python package: if a connection drops _after_ the server committed a plain
+  `put()` but before the reply arrived, a retry can store a duplicate row.
+- `onOperation(event)` receives `{ operation, durationMs, success, error, retryCount }` for every
+  operation (and once per chunk when streaming). Exceptions in your callback are swallowed.
+- The schema migration is serialized with an advisory lock, so many processes starting at once is safe.
+
+## Shared database with the Python package
+
+Same table (`zerobucket_images`), same checksum (SHA-256 hex of the stored bytes), same tiering
+columns and CHECK constraint. A repeatable [conformance harness](./conformance) checks both
+directions (Node writes → Python reads, and the reverse) and that both packages accept/reject the
+same corpus of valid and corrupt files identically.
+
+## Differences from the Python package
+
+|                        | Python                             | npm                                                                                                |
+| ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- |
+| API                    | sync + async clients               | one async client                                                                                   |
+| Malformed id (`"abc"`) | `StorageError` from Postgres       | treated as not found (`ImageNotFoundError`, no DB round trip), friendlier for `/images/:id` routes |
+| `optimize`             | Pillow; EXIF stripped, not applied | sharp; EXIF **applied then stripped**; transparency → **white** for JPEG                           |
+| `putMany` inserts      | pipelined                          | one transaction, statements run sequentially                                                       |
+| Formats                | JPEG, PNG, WebP, HEIC (extra)      | JPEG, PNG, WebP (HEIC not yet)                                                                     |
+| Event duration         | `duration_seconds`                 | `durationMs`                                                                                       |
+| Options                | snake_case kwargs                  | camelCase options object                                                                           |
+
+## What's not here yet
+
+Planned, in order: object-storage **tiering** (S3-compatible), **dedup** mode, **SQLite**, **MySQL/MariaDB**.
+Until tiering lands: reading a row that the Python package tiered to S3 throws a clear `StorageError`
+(never wrong data), and **deleting** such a row from Node removes the database row but leaves the S3
+object behind (the same documented orphan behaviour as Python without `object_storage`).
+Delete tiered images from Python if you use tiering.
+
+## Runtime notes
+
+Node 20+. Bun/Deno: expected to work, not yet tested. Edge runtimes (Cloudflare Workers, Vercel Edge) cannot open raw
+Postgres TCP connections through `pg` without a proxy such as Hyperdrive; use the Node runtime for these routes.
+In serverless, keep `poolMaxSize` small (1-2) or inject a pool shared across invocations.
+
+## Security
+
+Content is validated by decoding, never by trusting names or headers; responses carry
+`X-Content-Type-Options: nosniff`; 500 responses never leak internals (use `onError` to log). The
+`PDFValidator` is a sanity gate (magic bytes + size), not a PDF sanitizer. See the main repo's
+`SECURITY.md`.
+
+## License
+
+MIT

package/dist/chunk-W2C37XYV.js

@@ -0,0 +1,68 @@
+// src/errors.ts
+var ZeroBucketError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var ContentValidationError = class extends ZeroBucketError {
+};
+var ImageValidationError = class extends ContentValidationError {
+};
+var ImageTooLargeError = class extends ImageValidationError {
+  constructor(sizeBytes, maxBytes) {
+    super(
+      `Image is ${sizeBytes} bytes, which exceeds the maximum of ${maxBytes} bytes`
+    );
+    this.sizeBytes = sizeBytes;
+    this.maxBytes = maxBytes;
+  }
+  sizeBytes;
+  maxBytes;
+};
+var UnsupportedFormatError = class extends ImageValidationError {
+  constructor(detectedFormat, allowed) {
+    super(
+      `Detected format ${JSON.stringify(detectedFormat)} is not supported. Allowed formats: ${JSON.stringify([...allowed].sort())}`
+    );
+    this.detectedFormat = detectedFormat;
+    this.allowed = allowed;
+  }
+  detectedFormat;
+  allowed;
+};
+var CorruptedImageError = class extends ImageValidationError {
+};
+var ImageNotFoundError = class extends ZeroBucketError {
+  constructor(imageId) {
+    super(`No image found with id ${JSON.stringify(imageId)}`);
+    this.imageId = imageId;
+  }
+  imageId;
+};
+var StorageError = class extends ZeroBucketError {
+};
+var AccessDeniedError = class extends ZeroBucketError {
+  constructor(operation, imageId) {
+    super(
+      imageId !== void 0 ? `${operation} denied for image ${JSON.stringify(imageId)} by the beforeGet hook` : `${operation} denied by the beforePut hook`
+    );
+    this.operation = operation;
+    this.imageId = imageId;
+  }
+  operation;
+  imageId;
+};
+
+export {
+  ZeroBucketError,
+  ContentValidationError,
+  ImageValidationError,
+  ImageTooLargeError,
+  UnsupportedFormatError,
+  CorruptedImageError,
+  ImageNotFoundError,
+  StorageError,
+  AccessDeniedError
+};
+//# sourceMappingURL=chunk-W2C37XYV.js.map

package/dist/chunk-W2C37XYV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\r\n * Error hierarchy for ZeroBucket. Mirrors the Python package's exceptions\r\n * one-to-one so behaviour is portable across languages.\r\n *\r\n * Catch broadly with `instanceof ZeroBucketError`, or narrowly with a\r\n * subclass such as `ImageNotFoundError`.\r\n */\r\n\r\nexport class ZeroBucketError extends Error {\r\n  constructor(message: string, options?: { cause?: unknown }) {\r\n    super(message, options);\r\n    this.name = new.target.name;\r\n  }\r\n}\r\n\r\n/** Any content (image or custom-validated) failed validation. */\r\nexport class ContentValidationError extends ZeroBucketError {}\r\n\r\n/** An image failed validation (bad format, too large, corrupted, ...). */\r\nexport class ImageValidationError extends ContentValidationError {}\r\n\r\nexport class ImageTooLargeError extends ImageValidationError {\r\n  constructor(\r\n    public readonly sizeBytes: number,\r\n    public readonly maxBytes: number,\r\n  ) {\r\n    super(\r\n      `Image is ${sizeBytes} bytes, which exceeds the maximum of ${maxBytes} bytes`,\r\n    );\r\n  }\r\n}\r\n\r\nexport class UnsupportedFormatError extends ImageValidationError {\r\n  constructor(\r\n    public readonly detectedFormat: string | null,\r\n    public readonly allowed: readonly string[],\r\n  ) {\r\n    super(\r\n      `Detected format ${JSON.stringify(detectedFormat)} is not supported. ` +\r\n        `Allowed formats: ${JSON.stringify([...allowed].sort())}`,\r\n    );\r\n  }\r\n}\r\n\r\n/** Image bytes could not be decoded despite a recognizable header. */\r\nexport class CorruptedImageError extends ImageValidationError {}\r\n\r\n/** `get()`, `getStream()` or `metadata()` was called with an id that does not exist. */\r\nexport class ImageNotFoundError extends ZeroBucketError {\r\n  constructor(public readonly imageId: string) {\r\n    super(`No image found with id ${JSON.stringify(imageId)}`);\r\n  }\r\n}\r\n\r\n/** Underlying storage / database failure not covered above. */\r\nexport class StorageError extends ZeroBucketError {}\r\n\r\n/**\r\n * A `beforeGet` / `beforePut` hook denied the operation by returning false.\r\n *\r\n * If the hook itself throws, that exception propagates unchanged: it is NOT\r\n * wrapped in AccessDeniedError and NOT treated as an implicit allow. A broken\r\n * authorization check must fail closed, never open.\r\n */\r\nexport class AccessDeniedError extends ZeroBucketError {\r\n  constructor(\r\n    public readonly operation: string,\r\n    public readonly imageId?: string,\r\n  ) {\r\n    super(\r\n      imageId !== undefined\r\n        ? `${operation} denied for image ${JSON.stringify(imageId)} by the beforeGet hook`\r\n        : `${operation} denied by the beforePut hook`,\r\n    );\r\n  }\r\n}\r\n"],"mappings":";AAQO,IAAM,kBAAN,cAA8B,MAAM;AAAA,EACzC,YAAY,SAAiB,SAA+B;AAC1D,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO,WAAW;AAAA,EACzB;AACF;AAGO,IAAM,yBAAN,cAAqC,gBAAgB;AAAC;AAGtD,IAAM,uBAAN,cAAmC,uBAAuB;AAAC;AAE3D,IAAM,qBAAN,cAAiC,qBAAqB;AAAA,EAC3D,YACkB,WACA,UAChB;AACA;AAAA,MACE,YAAY,SAAS,wCAAwC,QAAQ;AAAA,IACvE;AALgB;AACA;AAAA,EAKlB;AAAA,EANkB;AAAA,EACA;AAMpB;AAEO,IAAM,yBAAN,cAAqC,qBAAqB;AAAA,EAC/D,YACkB,gBACA,SAChB;AACA;AAAA,MACE,mBAAmB,KAAK,UAAU,cAAc,CAAC,uCAC3B,KAAK,UAAU,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,CAAC;AAAA,IAC3D;AANgB;AACA;AAAA,EAMlB;AAAA,EAPkB;AAAA,EACA;AAOpB;AAGO,IAAM,sBAAN,cAAkC,qBAAqB;AAAC;AAGxD,IAAM,qBAAN,cAAiC,gBAAgB;AAAA,EACtD,YAA4B,SAAiB;AAC3C,UAAM,0BAA0B,KAAK,UAAU,OAAO,CAAC,EAAE;AAD/B;AAAA,EAE5B;AAAA,EAF4B;AAG9B;AAGO,IAAM,eAAN,cAA2B,gBAAgB;AAAC;AAS5C,IAAM,oBAAN,cAAgC,gBAAgB;AAAA,EACrD,YACkB,WACA,SAChB;AACA;AAAA,MACE,YAAY,SACR,GAAG,SAAS,qBAAqB,KAAK,UAAU,OAAO,CAAC,2BACxD,GAAG,SAAS;AAAA,IAClB;AAPgB;AACA;AAAA,EAOlB;AAAA,EARkB;AAAA,EACA;AAQpB;","names":[]}

package/dist/client-C_W0t8My.d.cts

@@ -0,0 +1,319 @@
+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 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?: Queryable;
+}
+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>;
+    close(): Promise<void>;
+}
+
+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;
+    /** Advanced: inject a custom StorageBackend instead of building a PostgresBackend. */
+    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;
+    /**
+     * 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?: Queryable;
+    /** 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?: Queryable;
+    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[]>;
+    /** 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 StoredRecord as a, type StoredRecordMetadata as b, type StreamOptions$1 as c, type ContentValidator as d, type BatchGetResult as e, type BatchPutResult as f, type BeforeGetHook as g, type BeforePutHook as h, type ImageInput as i, type ImageMetadata as j, type OptimizationResult as k, type OptimizeOptions as l, type PutManyOptions as m, type PutOptions as n, type StreamOptions as o, type ZeroBucketOptions as p, optimizeImage as q, readInput as r };