zerobucket 0.0.0-stage → 0.4.0

package/dist/index.cjs

@@ -0,0 +1,2559 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AccessDeniedError: () => AccessDeniedError,
+  ContentValidationError: () => ContentValidationError,
+  CorruptedImageError: () => CorruptedImageError,
+  DEFAULT_MAX_BYTES: () => DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_PIXELS: () => DEFAULT_MAX_PIXELS,
+  DEFAULT_STREAM_CHUNK_SIZE: () => DEFAULT_STREAM_CHUNK_SIZE,
+  ImageNotFoundError: () => ImageNotFoundError,
+  ImageTooLargeError: () => ImageTooLargeError,
+  ImageValidationError: () => ImageValidationError,
+  ObjectStorage: () => ObjectStorage,
+  PDFValidator: () => PDFValidator,
+  PostgresBackend: () => PostgresBackend,
+  SQLiteBackend: () => SQLiteBackend,
+  SUPPORTED_FORMATS: () => SUPPORTED_FORMATS,
+  StorageError: () => StorageError,
+  UnsupportedFormatError: () => UnsupportedFormatError,
+  ZeroBucket: () => ZeroBucket,
+  ZeroBucketError: () => ZeroBucketError,
+  optimizeImage: () => optimizeImage,
+  readInput: () => readInput,
+  validateImage: () => validateImage
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/client.ts
+var import_node_crypto2 = require("crypto");
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+
+// 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;
+};
+
+// src/adapters/shared.ts
+var DEFAULT_STREAM_CHUNK_SIZE = 1024 * 1024;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isValidId(id) {
+  return typeof id === "string" && UUID_RE.test(id);
+}
+function msg(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+function wrap(prefix, exc) {
+  return exc instanceof StorageError ? exc : new StorageError(`${prefix}: ${msg(exc)}`, { cause: exc });
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (next < items.length) {
+        const i = next++;
+        out[i] = await fn(items[i]);
+      }
+    })
+  );
+  return out;
+}
+function tieredWithoutStorage(id, key) {
+  return new StorageError(
+    `Image ${JSON.stringify(id)} is stored in object storage (key=${JSON.stringify(key)}) but this ZeroBucket was constructed without \`objectStorage\`. Configure it with the same bucket and credentials that were used to tier this image.`
+  );
+}
+async function hydrateRow(row, id, os) {
+  let data;
+  if (row.storage_backend === "object_storage") {
+    if (!os) throw tieredWithoutStorage(id, row.object_storage_key);
+    data = await os.download(row.object_storage_key);
+    if (data.length !== row.size_bytes) {
+      throw new StorageError(
+        `Object ${JSON.stringify(row.object_storage_key)} for image ${JSON.stringify(id)} has ${data.length} bytes but the database records ${row.size_bytes}. The stored object is corrupted or was replaced.`
+      );
+    }
+  } else {
+    data = row.data;
+  }
+  return {
+    id: String(row.id),
+    data,
+    mimeType: row.mime_type,
+    originalFilename: row.original_filename,
+    sizeBytes: row.size_bytes,
+    width: row.width,
+    height: row.height,
+    checksumSha256: row.checksum_sha256
+  };
+}
+async function* streamFromObjectStorage(os, id, key, start, end, chunkSize) {
+  let offset = start;
+  while (offset <= end) {
+    const last = Math.min(offset + chunkSize - 1, end);
+    const expected = last - offset + 1;
+    const chunk = await os.downloadRange(key, offset, last);
+    if (chunk.length !== expected) {
+      throw new StorageError(
+        `Object ${JSON.stringify(key)} for image ${JSON.stringify(id)} returned ${chunk.length} bytes for a ${expected}-byte range; the stored object is shorter than the database records.`
+      );
+    }
+    yield chunk;
+    offset = last + 1;
+  }
+}
+
+// src/adapters/postgres.ts
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS zerobucket_images (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    data                BYTEA NOT NULL,
+    mime_type           TEXT NOT NULL,
+    original_filename   TEXT,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    checksum_sha256     CHAR(64) NOT NULL,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_checksum ON zerobucket_images (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_created_at ON zerobucket_images (created_at);
+
+-- Object-storage tiering columns (additive; identical to the Python package).
+ALTER TABLE zerobucket_images ALTER COLUMN data DROP NOT NULL;
+ALTER TABLE zerobucket_images
+    ADD COLUMN IF NOT EXISTS storage_backend TEXT NOT NULL DEFAULT 'postgres';
+ALTER TABLE zerobucket_images ADD COLUMN IF NOT EXISTS object_storage_bucket TEXT;
+ALTER TABLE zerobucket_images ADD COLUMN IF NOT EXISTS object_storage_key TEXT;
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint WHERE conname = 'zerobucket_storage_location_check'
+    ) THEN
+        ALTER TABLE zerobucket_images ADD CONSTRAINT zerobucket_storage_location_check
+        CHECK (
+            (storage_backend = 'postgres'
+                AND data IS NOT NULL
+                AND object_storage_key IS NULL
+                AND object_storage_bucket IS NULL)
+            OR
+            (storage_backend = 'object_storage'
+                AND data IS NULL
+                AND object_storage_key IS NOT NULL
+                AND object_storage_bucket IS NOT NULL)
+        );
+    END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS idx_zerobucket_storage_backend
+    ON zerobucket_images (storage_backend) WHERE storage_backend != 'postgres';
+`;
+var INSERT = `
+INSERT INTO zerobucket_images
+    (data, mime_type, original_filename, size_bytes, width, height, checksum_sha256)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+RETURNING id;`;
+var SELECT_FULL = `
+SELECT id, data, mime_type, original_filename, size_bytes, width, height,
+       checksum_sha256, storage_backend, object_storage_bucket, object_storage_key
+FROM zerobucket_images WHERE id = $1;`;
+var SELECT_MANY = `
+SELECT id, data, mime_type, original_filename, size_bytes, width, height,
+       checksum_sha256, storage_backend, object_storage_bucket, object_storage_key
+FROM zerobucket_images WHERE id = ANY($1::uuid[]);`;
+var SELECT_METADATA = `
+SELECT id, mime_type, original_filename, size_bytes, width, height, checksum_sha256
+FROM zerobucket_images WHERE id = $1;`;
+var SELECT_CHUNK = `SELECT substring(data FROM $1::int FOR $2::int) AS chunk FROM zerobucket_images WHERE id = $3;`;
+var SELECT_STREAM_INFO = `SELECT size_bytes, storage_backend, object_storage_key FROM zerobucket_images WHERE id = $1;`;
+var DELETE_RETURNING = `DELETE FROM zerobucket_images WHERE id = $1 RETURNING storage_backend, object_storage_key;`;
+var DELETE_MANY = `DELETE FROM zerobucket_images WHERE id = ANY($1::uuid[]) RETURNING id, storage_backend, object_storage_key;`;
+var EXISTS = `SELECT 1 FROM zerobucket_images WHERE id = $1;`;
+var SELECT_FOR_TIERING = `SELECT data, mime_type, size_bytes, storage_backend FROM zerobucket_images WHERE id = $1 FOR UPDATE;`;
+var UPDATE_AFTER_TIERING = `UPDATE zerobucket_images SET data = NULL, storage_backend = 'object_storage', object_storage_bucket = $1, object_storage_key = $2, updated_at = now() WHERE id = $3;`;
+var DEDUP_SCHEMA = `
+CREATE TABLE IF NOT EXISTS zerobucket_blobs (
+    checksum_sha256     CHAR(64) PRIMARY KEY,
+    data                BYTEA NOT NULL,
+    mime_type           TEXT NOT NULL,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    ref_count           INTEGER NOT NULL DEFAULT 0,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS zerobucket_image_refs (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    checksum_sha256     CHAR(64) NOT NULL REFERENCES zerobucket_blobs(checksum_sha256),
+    original_filename   TEXT,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_checksum ON zerobucket_image_refs (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_created_at ON zerobucket_image_refs (created_at);
+`;
+var D_UPSERT_BLOB = `
+INSERT INTO zerobucket_blobs (checksum_sha256, data, mime_type, size_bytes, width, height, ref_count)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+ON CONFLICT (checksum_sha256) DO UPDATE SET ref_count = zerobucket_blobs.ref_count + EXCLUDED.ref_count;`;
+var D_INSERT_REF = `INSERT INTO zerobucket_image_refs (checksum_sha256, original_filename) VALUES ($1, $2) RETURNING id;`;
+var D_COLS = `r.id, b.data, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256,
+       'postgres'::text AS storage_backend, NULL::text AS object_storage_bucket, NULL::text AS object_storage_key`;
+var D_FROM = `FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256`;
+var D_DELETE_REF = `DELETE FROM zerobucket_image_refs WHERE id = $1 RETURNING checksum_sha256;`;
+var D_DELETE_REFS = `DELETE FROM zerobucket_image_refs WHERE id = ANY($1::uuid[]) RETURNING id, checksum_sha256;`;
+var D_DECREMENT = `UPDATE zerobucket_blobs SET ref_count = ref_count - $1 WHERE checksum_sha256 = $2 RETURNING ref_count;`;
+var D_DELETE_EMPTY = `DELETE FROM zerobucket_blobs WHERE checksum_sha256 = ANY($1::text[]) AND ref_count <= 0;`;
+var CLASSIC_SQL = {
+  schema: SCHEMA,
+  selectFull: SELECT_FULL,
+  selectMany: SELECT_MANY,
+  selectMetadata: SELECT_METADATA,
+  selectStreamInfo: SELECT_STREAM_INFO,
+  selectChunk: SELECT_CHUNK,
+  exists: EXISTS
+};
+var DEDUP_SQL = {
+  schema: DEDUP_SCHEMA,
+  selectFull: `SELECT ${D_COLS} ${D_FROM} WHERE r.id = $1;`,
+  selectMany: `SELECT ${D_COLS} ${D_FROM} WHERE r.id = ANY($1::uuid[]);`,
+  selectMetadata: `SELECT r.id, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256 ${D_FROM} WHERE r.id = $1;`,
+  selectStreamInfo: `SELECT b.size_bytes, 'postgres'::text AS storage_backend, NULL::text AS object_storage_key ${D_FROM} WHERE r.id = $1;`,
+  selectChunk: `SELECT substring(b.data FROM $1::int FOR $2::int) AS chunk ${D_FROM} WHERE r.id = $3;`,
+  exists: `SELECT 1 FROM zerobucket_image_refs WHERE id = $1;`
+};
+var RETRYABLE_SQLSTATES = /* @__PURE__ */ new Set([
+  "40001",
+  // serialization_failure
+  "40P01",
+  // deadlock_detected
+  "08000",
+  // connection_exception
+  "08003",
+  // connection_does_not_exist
+  "08006",
+  // connection_failure
+  "08001",
+  // sqlclient_unable_to_establish_sqlconnection
+  "08004",
+  // sqlserver_rejected_establishment_of_sqlconnection
+  "57P01",
+  // admin_shutdown
+  "57P02",
+  // crash_shutdown
+  "57P03",
+  // cannot_connect_now
+  "53000",
+  // insufficient_resources
+  "53300"
+  // too_many_connections
+]);
+var RETRYABLE_NODE_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EPIPE",
+  "ECONNABORTED"
+]);
+var CONNECTION_MESSAGE_RE = /connection terminated|connection timeout|timeout exceeded when trying to connect|client has encountered a connection error/i;
+function isRetryable(exc) {
+  if (!(exc instanceof Error)) return false;
+  const code = exc.code;
+  if (typeof code === "string") {
+    if (RETRYABLE_SQLSTATES.has(code) || RETRYABLE_NODE_CODES.has(code))
+      return true;
+  }
+  return CONNECTION_MESSAGE_RE.test(exc.message);
+}
+function isConnectionLevel(exc) {
+  if (!(exc instanceof Error)) return false;
+  const code = exc.code;
+  if (typeof code === "string" && (RETRYABLE_NODE_CODES.has(code) || code.startsWith("08") || code.startsWith("57"))) {
+    return true;
+  }
+  return CONNECTION_MESSAGE_RE.test(exc.message);
+}
+var MAX_BACKOFF_MS = 2e3;
+function backoffDelayMs(attempt, baseDelayMs) {
+  const exponential = baseDelayMs * 2 ** (attempt - 1);
+  const jitter = Math.random() * baseDelayMs;
+  return Math.min(exponential + jitter, MAX_BACKOFF_MS);
+}
+var PostgresBackend = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.connectionString && !opts.pool) {
+      throw new TypeError(
+        "PostgresBackend requires either `connectionString` or `pool`"
+      );
+    }
+    this.ownsPool = !opts.pool;
+    this.pool = opts.pool;
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 100;
+    this.autoMigrate = opts.autoMigrate ?? true;
+    this.dedup = opts.dedup ?? false;
+    if (this.dedup && opts.objectStorage) {
+      throw new TypeError(
+        "objectStorage is not supported together with dedup: true (same restriction as the Python package). Tiering moves one image's bytes, but a deduplicated blob can be shared by many images."
+      );
+    }
+    this.sql = this.dedup ? DEDUP_SQL : CLASSIC_SQL;
+  }
+  opts;
+  pool;
+  ownsPool;
+  readyPromise;
+  closed = false;
+  maxRetries;
+  retryBaseDelayMs;
+  autoMigrate;
+  dedup;
+  sql;
+  // ---- lifecycle -------------------------------------------------------
+  ready() {
+    if (this.closed)
+      return Promise.reject(
+        new StorageError("This ZeroBucket instance has been closed")
+      );
+    this.readyPromise ??= this.init().catch((exc) => {
+      this.readyPromise = void 0;
+      throw exc;
+    });
+    return this.readyPromise;
+  }
+  async init() {
+    if (!this.pool) {
+      let pg;
+      try {
+        const mod = await import("pg");
+        pg = mod.default ?? mod;
+      } catch (cause) {
+        throw new StorageError(
+          "PostgresBackend requires the 'pg' package. Install it with: npm install pg",
+          { cause }
+        );
+      }
+      const config = {
+        connectionString: this.opts.connectionString,
+        min: this.opts.poolMinSize ?? 1,
+        max: this.opts.poolMaxSize ?? 5,
+        connectionTimeoutMillis: this.opts.poolTimeoutMs ?? 1e4
+      };
+      this.pool = new pg.Pool(config);
+      this.pool.on("error", () => {
+      });
+    }
+    try {
+      if (this.autoMigrate) await this.migrate();
+      else await this.pool.query("SELECT 1");
+    } catch (exc) {
+      if (this.ownsPool) {
+        await this.pool.end().catch(() => {
+        });
+        this.pool = void 0;
+      }
+      throw exc instanceof StorageError ? exc : new StorageError(`Could not connect to PostgreSQL: ${msg(exc)}`, {
+        cause: exc
+      });
+    }
+  }
+  /** Create the schema if missing. Serialized across processes with an advisory lock. */
+  async migrate() {
+    const pool = this.pool;
+    let client;
+    try {
+      client = await pool.connect();
+    } catch (exc) {
+      throw new StorageError(`Could not connect to PostgreSQL: ${msg(exc)}`, {
+        cause: exc
+      });
+    }
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtext('zerobucket_migrate'))"
+      );
+      await client.query(this.sql.schema);
+      await client.query("COMMIT");
+      client.release();
+    } catch (exc) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      client.release(true);
+      throw new StorageError(`Migration failed: ${msg(exc)}`, { cause: exc });
+    }
+  }
+  async close() {
+    this.closed = true;
+    const pool = this.pool;
+    this.pool = void 0;
+    this.readyPromise = void 0;
+    if (pool && this.ownsPool) await pool.end();
+  }
+  // ---- execution core --------------------------------------------------
+  emit(operation, start, success, error, retryCount) {
+    const cb = this.opts.onOperation;
+    if (!cb) return;
+    try {
+      cb({
+        operation,
+        durationMs: performance.now() - start,
+        success,
+        error,
+        retryCount
+      });
+    } catch {
+    }
+  }
+  /**
+   * Run `work` and return its result, emitting exactly one OperationEvent.
+   *
+   * connection given  -> run once on it, no BEGIN/COMMIT, no retry.
+   * connection absent -> pooled; `tx` wraps the work in BEGIN/COMMIT; transient
+   *                      failures retry the WHOLE closure on a fresh connection.
+   */
+  async run(operation, connection, work, { tx = false } = {}) {
+    if (connection) {
+      if (!isQueryable(connection)) {
+        throw new TypeError(
+          "PostgresBackend expects a pg client/pool client as `connection` (an object with query()), not a SQLite Database."
+        );
+      }
+      const start2 = performance.now();
+      try {
+        const result = tx ? await this.atomic(connection, work) : await work(connection);
+        this.emit(operation, start2, true, null, 0);
+        return result;
+      } catch (exc) {
+        this.emit(operation, start2, false, msg(exc), 0);
+        throw exc;
+      }
+    }
+    await this.ready();
+    const start = performance.now();
+    let attempt = 0;
+    for (; ; ) {
+      let client;
+      let destroy = false;
+      try {
+        client = await this.pool.connect();
+        if (tx) await client.query("BEGIN");
+        const result = await work(client);
+        if (tx) await client.query("COMMIT");
+        this.emit(operation, start, true, null, attempt);
+        return result;
+      } catch (exc) {
+        if (client && tx) {
+          try {
+            await client.query("ROLLBACK");
+          } catch {
+            destroy = true;
+          }
+        }
+        if (isConnectionLevel(exc)) destroy = true;
+        attempt += 1;
+        if (attempt > this.maxRetries || !isRetryable(exc)) {
+          this.emit(operation, start, false, msg(exc), attempt - 1);
+          throw exc;
+        }
+      } finally {
+        client?.release(destroy);
+      }
+      await sleep(backoffDelayMs(attempt, this.retryBaseDelayMs));
+    }
+  }
+  /**
+   * Make multi-statement work all-or-nothing on a CALLER-supplied connection.
+   *  - Caller has an open transaction -> SAVEPOINT: a failure rolls back only our work and the
+   *    caller's transaction stays usable; success joins their transaction.
+   *  - No open transaction (an autocommit pg.Client) -> open and commit our own, so a failure
+   *    can never leave half-applied state (e.g. an inflated dedup ref_count).
+   */
+  async atomic(conn, work) {
+    let ownTx = false;
+    try {
+      await conn.query("SAVEPOINT zerobucket_atomic");
+    } catch (exc) {
+      if (exc.code !== "25P01") throw exc;
+      ownTx = true;
+      await conn.query("BEGIN");
+    }
+    try {
+      const result = await work(conn);
+      await conn.query(
+        ownTx ? "COMMIT" : "RELEASE SAVEPOINT zerobucket_atomic"
+      );
+      return result;
+    } catch (exc) {
+      try {
+        await conn.query(
+          ownTx ? "ROLLBACK" : "ROLLBACK TO SAVEPOINT zerobucket_atomic"
+        );
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  // ---- StorageBackend --------------------------------------------------
+  async put(row, { connection } = {}) {
+    try {
+      if (this.dedup) {
+        return await this.run(
+          "put",
+          connection,
+          async (q) => {
+            await q.query(D_UPSERT_BLOB, blobParams(row, 1));
+            return String(
+              (await q.query(D_INSERT_REF, [
+                row.checksumSha256,
+                row.originalFilename
+              ])).rows[0].id
+            );
+          },
+          { tx: true }
+        );
+      }
+      return await this.run("put", connection, async (q) => {
+        const res = await q.query(INSERT, rowParams(row));
+        return String(res.rows[0].id);
+      });
+    } catch (exc) {
+      throw wrap("Failed to store image", exc);
+    }
+  }
+  async putMany(rows, { connection } = {}) {
+    if (rows.length === 0) return [];
+    try {
+      if (this.dedup) {
+        return await this.run(
+          "put_many",
+          connection,
+          async (q) => {
+            const groups = /* @__PURE__ */ new Map();
+            for (const r of rows) {
+              const g = groups.get(r.checksumSha256);
+              if (g) g.n += 1;
+              else groups.set(r.checksumSha256, { row: r, n: 1 });
+            }
+            for (const checksum of [...groups.keys()].sort()) {
+              const g = groups.get(checksum);
+              await q.query(D_UPSERT_BLOB, blobParams(g.row, g.n));
+            }
+            const ids = [];
+            for (const r of rows) {
+              ids.push(
+                String(
+                  (await q.query(D_INSERT_REF, [
+                    r.checksumSha256,
+                    r.originalFilename
+                  ])).rows[0].id
+                )
+              );
+            }
+            return ids;
+          },
+          { tx: true }
+        );
+      }
+      return await this.run(
+        "put_many",
+        connection,
+        async (q) => {
+          const ids = [];
+          for (const r of rows)
+            ids.push(String((await q.query(INSERT, rowParams(r))).rows[0].id));
+          return ids;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to store image batch", exc);
+    }
+  }
+  async get(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.run(
+        "get",
+        connection,
+        async (q) => (await q.query(this.sql.selectFull, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image", exc);
+    }
+    return row ? this.hydrate(row, id) : null;
+  }
+  async getMany(ids, { connection } = {}) {
+    const valid = ids.filter(isValidId);
+    if (valid.length === 0) return [];
+    let rows;
+    try {
+      rows = await this.run(
+        "get_many",
+        connection,
+        async (q) => (await q.query(this.sql.selectMany, [valid])).rows
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image batch", exc);
+    }
+    return mapLimit(rows, 4, (r) => this.hydrate(r, String(r.id)));
+  }
+  async getMetadata(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.run(
+        "get_metadata",
+        connection,
+        async (q) => (await q.query(this.sql.selectMetadata, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!row) return null;
+    return {
+      id: String(row.id),
+      mimeType: row.mime_type,
+      originalFilename: row.original_filename,
+      sizeBytes: row.size_bytes,
+      width: row.width,
+      height: row.height,
+      checksumSha256: row.checksum_sha256
+    };
+  }
+  async getStream(id, opts) {
+    if (!isValidId(id)) return null;
+    const { connection, chunkSize } = opts;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0)
+      throw new RangeError("chunkSize must be a positive integer");
+    let info;
+    try {
+      info = await this.run(
+        "get_metadata",
+        connection,
+        async (q) => (await q.query(this.sql.selectStreamInfo, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!info) return null;
+    const totalSize = info.size_bytes;
+    const start = opts.range?.start ?? 0;
+    const end = Math.min(opts.range?.end ?? totalSize - 1, totalSize - 1);
+    if (info.storage_backend === "object_storage") {
+      const os = this.opts.objectStorage;
+      if (!os) throw tieredWithoutStorage(id, info.object_storage_key);
+      return streamFromObjectStorage(
+        os,
+        id,
+        info.object_storage_key,
+        start,
+        end,
+        chunkSize
+      );
+    }
+    const self = this;
+    async function* generate() {
+      let offset = start;
+      let delivered = 0;
+      const wanted = Math.max(0, end - start + 1);
+      while (delivered < wanted) {
+        const length = Math.min(chunkSize, wanted - delivered);
+        let row;
+        try {
+          row = await self.run(
+            "get_stream",
+            connection,
+            async (q) => (await q.query(self.sql.selectChunk, [offset + 1, length, id])).rows[0]
+          );
+        } catch (exc) {
+          throw wrap("Failed to stream image", exc);
+        }
+        if (!row) {
+          throw new StorageError(
+            `Image ${JSON.stringify(id)} was deleted while streaming (delivered ${delivered} of ${wanted} bytes). Pass connection with your own open transaction if you need a consistent read across concurrent writers.`
+          );
+        }
+        const chunk = row.chunk;
+        if (!chunk || chunk.length === 0) {
+          throw new StorageError(
+            `Image ${JSON.stringify(id)} ended early while streaming (delivered ${delivered} of ${wanted} bytes).`
+          );
+        }
+        yield chunk;
+        offset += chunk.length;
+        delivered += chunk.length;
+      }
+    }
+    return generate();
+  }
+  async delete(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    if (this.dedup) return this.deleteDedup(id, connection);
+    try {
+      const row = await this.run(
+        "delete",
+        connection,
+        async (q) => (await q.query(DELETE_RETURNING, [id])).rows[0]
+      );
+      if (row?.storage_backend === "object_storage")
+        await this.cleanupObject([row.object_storage_key], connection);
+      return row !== void 0;
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteMany(ids, { connection } = {}) {
+    const valid = ids.filter(isValidId);
+    if (valid.length === 0) return [];
+    if (this.dedup) return this.deleteManyDedup(valid, connection);
+    try {
+      const rows = await this.run(
+        "delete_many",
+        connection,
+        async (q) => (await q.query(DELETE_MANY, [valid])).rows
+      );
+      await this.cleanupObject(
+        rows.filter((r) => r.storage_backend === "object_storage").map((r) => r.object_storage_key),
+        connection
+      );
+      return rows.map((r) => String(r.id));
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  async exists(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    try {
+      return await this.run(
+        "exists",
+        connection,
+        async (q) => ((await q.query(this.sql.exists, [id])).rowCount ?? 0) > 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", exc);
+    }
+  }
+  // ---- dedup deletes / migration ---------------------------------------
+  async deleteDedup(id, connection) {
+    try {
+      return await this.run(
+        "delete",
+        connection,
+        async (q) => {
+          const ref = (await q.query(D_DELETE_REF, [id])).rows[0];
+          if (!ref) return false;
+          const checksum = ref.checksum_sha256;
+          const dec = (await q.query(D_DECREMENT, [1, checksum])).rows[0];
+          if (dec && dec.ref_count <= 0)
+            await q.query(D_DELETE_EMPTY, [[checksum]]);
+          return true;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteManyDedup(ids, connection) {
+    try {
+      return await this.run(
+        "delete_many",
+        connection,
+        async (q) => {
+          const deleted = (await q.query(D_DELETE_REFS, [ids])).rows;
+          if (deleted.length === 0) return [];
+          const counts = /* @__PURE__ */ new Map();
+          for (const r of deleted)
+            counts.set(
+              r.checksum_sha256,
+              (counts.get(r.checksum_sha256) ?? 0) + 1
+            );
+          const emptied = [];
+          for (const checksum of [...counts.keys()].sort()) {
+            const dec = (await q.query(D_DECREMENT, [counts.get(checksum), checksum])).rows[0];
+            if (dec && dec.ref_count <= 0) emptied.push(checksum);
+          }
+          if (emptied.length > 0) await q.query(D_DELETE_EMPTY, [emptied]);
+          return deleted.map((r) => String(r.id));
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  /**
+   * One-time, NON-DESTRUCTIVE copy of every row in the classic `zerobucket_images` table into this
+   * dedup instance's tables, preserving every id (external references keep working) and
+   * deduplicating identical content on the way. The classic table is never modified.
+   *
+   * Differences from the Python version, all deliberate: rows are copied in small batches (bounded
+   * memory instead of loading the whole table); re-running is safe (already-migrated ids are
+   * skipped and reported, not an error); and classic rows already tiered to object storage are
+   * refused up front with a clear message (their bytes are not in the database to copy).
+   * Still all-or-nothing: one transaction.
+   */
+  async migrateClassicToDedup() {
+    if (!this.dedup) {
+      throw new StorageError(
+        "migrateClassicToDedup() must be called on an instance created with dedup: true."
+      );
+    }
+    await this.ready();
+    const client = await this.pool.connect();
+    let destroy = false;
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtext('zerobucket_migrate_dedup'))"
+      );
+      if (!(await client.query("SELECT to_regclass('zerobucket_images') AS t")).rows[0].t) {
+        throw new StorageError(
+          "No classic zerobucket_images table found in this database -- nothing to migrate."
+        );
+      }
+      const hasTierCol = (await client.query(
+        "SELECT 1 FROM information_schema.columns WHERE table_name = 'zerobucket_images' AND column_name = 'storage_backend'"
+      )).rowCount;
+      if (hasTierCol) {
+        const tiered = (await client.query(
+          "SELECT count(*)::int AS n FROM zerobucket_images WHERE storage_backend <> 'postgres'"
+        )).rows[0].n;
+        if (tiered > 0) {
+          throw new StorageError(
+            `${tiered} classic image(s) are tiered to object storage, so their bytes are not in the database to migrate. Dedup mode does not support tiering. Migrate only an un-tiered table, or bring those images back first.`
+          );
+        }
+      }
+      const seen = /* @__PURE__ */ new Set();
+      let migrated = 0;
+      let already = 0;
+      let cursor = null;
+      const BATCH = 20;
+      for (; ; ) {
+        const page = cursor ? await client.query(
+          `SELECT id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at::text AS created_at_txt
+               FROM zerobucket_images WHERE (created_at, id) > ($1::timestamptz, $2::uuid) ORDER BY created_at, id LIMIT ${BATCH}`,
+          [cursor.createdAt, cursor.id]
+        ) : await client.query(
+          `SELECT id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at::text AS created_at_txt
+               FROM zerobucket_images ORDER BY created_at, id LIMIT ${BATCH}`
+        );
+        if (page.rows.length === 0) break;
+        const last = page.rows[page.rows.length - 1];
+        if (cursor && cursor.createdAt === last.created_at_txt && cursor.id === last.id) {
+          throw new StorageError(
+            "Migration made no progress (keyset cursor did not advance); aborting instead of looping."
+          );
+        }
+        cursor = { createdAt: last.created_at_txt, id: last.id };
+        const have = new Set(
+          (await client.query(
+            "SELECT id FROM zerobucket_image_refs WHERE id = ANY($1::uuid[])",
+            [page.rows.map((r) => r.id)]
+          )).rows.map((r) => String(r.id))
+        );
+        const fresh = page.rows.filter((r) => !have.has(String(r.id)));
+        already += page.rows.length - fresh.length;
+        const groups = /* @__PURE__ */ new Map();
+        for (const r of fresh) {
+          const g = groups.get(r.checksum_sha256);
+          if (g) g.n += 1;
+          else groups.set(r.checksum_sha256, { row: r, n: 1 });
+        }
+        for (const checksum of [...groups.keys()].sort()) {
+          const { row, n } = groups.get(checksum);
+          await client.query(D_UPSERT_BLOB, [
+            checksum,
+            row.data,
+            row.mime_type,
+            row.size_bytes,
+            row.width,
+            row.height,
+            n
+          ]);
+        }
+        for (const r of fresh) {
+          await client.query(
+            "INSERT INTO zerobucket_image_refs (id, checksum_sha256, original_filename, created_at) VALUES ($1, $2, $3, $4::timestamptz)",
+            [r.id, r.checksum_sha256, r.original_filename, r.created_at_txt]
+          );
+          seen.add(r.checksum_sha256);
+          migrated += 1;
+        }
+      }
+      await client.query("COMMIT");
+      return {
+        imagesMigrated: migrated,
+        distinctBlobsCreated: seen.size,
+        duplicateReferencesFound: migrated - seen.size,
+        alreadyMigrated: already
+      };
+    } catch (exc) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+        destroy = true;
+      }
+      throw exc instanceof StorageError ? exc : new StorageError(`Migration to dedup failed: ${msg(exc)}`, {
+        cause: exc
+      });
+    } finally {
+      client.release(destroy);
+    }
+  }
+  // ---- helpers ---------------------------------------------------------
+  hydrate(row, id) {
+    return hydrateRow(row, id, this.opts.objectStorage);
+  }
+  /**
+   * Remove tiered objects AFTER their rows are gone. Ordering is deliberate:
+   * once the row is deleted the image is correctly "not found" to everyone, so
+   * a failed object delete only leaves a harmless orphan, whereas deleting the
+   * object first and then failing the row delete would leave a row pointing at nothing.
+   *
+   * Never runs inside a caller-owned transaction (`connection`): we cannot know
+   * whether it will commit, and destroying data before the commit outcome is known
+   * could leave a rolled-back row pointing at a deleted object. In that case the
+   * object stays until you remove it yourself after committing (objectStorage.delete(id)).
+   * Failures are reported through onOperation and never fail the delete itself.
+   */
+  async cleanupObject(keys, connection) {
+    const os = this.opts.objectStorage;
+    if (!os || connection || keys.length === 0) return;
+    await Promise.all(
+      keys.map(async (key) => {
+        const start = performance.now();
+        try {
+          await os.delete(key);
+          this.emit("object_storage_delete", start, true, null, 0);
+        } catch (exc) {
+          this.emit("object_storage_delete", start, false, msg(exc), 0);
+        }
+      })
+    );
+  }
+  /**
+   * Move an image's bytes out of Postgres into object storage, replacing the
+   * row's `data` with a pointer. Returns:
+   *   null  - no such image
+   *   false - already tiered (a safe no-op, so backfills can be re-run)
+   *   true  - tiered just now
+   *
+   * SAFETY: the upload happens INSIDE the same transaction as the row lock
+   * (SELECT ... FOR UPDATE) and the UPDATE that flips the row. If the upload
+   * fails, the transaction rolls back and the row is untouched: there is no
+   * moment when the bytes exist nowhere, or when a row claims to be tiered
+   * without a completed upload.
+   *
+   * TRADEOFF: the row lock is held for the whole upload. Concurrent writes
+   * to THIS image (delete, tier) wait; every other row is unaffected, and plain
+   * reads are never blocked (Postgres MVCC). Meant for explicit maintenance, not hot paths.
+   *
+   * Retry is safe: a transient error replays the whole closure, and the
+   * deterministic key (the image id) makes the re-upload an idempotent overwrite.
+   */
+  async tierToObjectStorage(id, { connection } = {}) {
+    if (this.dedup) {
+      throw new StorageError(
+        "tierToObjectStorage() is not supported in dedup mode (a blob may be shared by many images)."
+      );
+    }
+    const os = this.opts.objectStorage;
+    if (!os) {
+      throw new StorageError(
+        "tierToObjectStorage() requires objectStorage to be configured (new ZeroBucket({ objectStorage: new ObjectStorage({ bucket }) }))."
+      );
+    }
+    if (!isValidId(id)) return null;
+    const key = id.toLowerCase();
+    try {
+      return await this.run(
+        "tier_to_object_storage",
+        connection,
+        async (q) => {
+          const row = (await q.query(SELECT_FOR_TIERING, [id])).rows[0];
+          if (!row) return null;
+          if (row.storage_backend !== "postgres") return false;
+          await os.upload(key, row.data, { mimeType: row.mime_type });
+          await q.query(UPDATE_AFTER_TIERING, [os.bucket, key, id]);
+          return true;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to tier image to object storage", exc);
+    }
+  }
+};
+function blobParams(r, refs) {
+  return [
+    r.checksumSha256,
+    r.data,
+    r.mimeType,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    refs
+  ];
+}
+function rowParams(r) {
+  return [
+    r.data,
+    r.mimeType,
+    r.originalFilename,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    r.checksumSha256
+  ];
+}
+function isQueryable(c) {
+  return typeof c.query === "function";
+}
+
+// src/adapters/sqlite.ts
+var import_node_crypto = require("crypto");
+var SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS zerobucket_images (
+    id                  TEXT PRIMARY KEY,
+    data                BLOB,
+    mime_type           TEXT NOT NULL,
+    original_filename   TEXT,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    checksum_sha256     TEXT NOT NULL,
+    created_at          TEXT NOT NULL,
+    updated_at          TEXT NOT NULL,
+    storage_backend     TEXT NOT NULL DEFAULT 'sqlite',
+    object_storage_bucket TEXT,
+    object_storage_key  TEXT,
+    CHECK (
+        (storage_backend = 'sqlite'
+            AND data IS NOT NULL
+            AND object_storage_key IS NULL
+            AND object_storage_bucket IS NULL)
+        OR
+        (storage_backend = 'object_storage'
+            AND data IS NULL
+            AND object_storage_key IS NOT NULL
+            AND object_storage_bucket IS NOT NULL)
+    )
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_checksum ON zerobucket_images (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_created_at ON zerobucket_images (created_at);
+`;
+var DEDUP_SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS zerobucket_blobs (
+    checksum_sha256     TEXT PRIMARY KEY,
+    data                BLOB NOT NULL,
+    mime_type           TEXT NOT NULL,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    ref_count           INTEGER NOT NULL DEFAULT 0,
+    created_at          TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS zerobucket_image_refs (
+    id                  TEXT PRIMARY KEY,
+    checksum_sha256     TEXT NOT NULL REFERENCES zerobucket_blobs(checksum_sha256),
+    original_filename   TEXT,
+    created_at          TEXT NOT NULL,
+    updated_at          TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_checksum ON zerobucket_image_refs (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_created_at ON zerobucket_image_refs (created_at);
+`;
+var COLS = `id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, storage_backend, object_storage_bucket, object_storage_key`;
+var INSERT2 = `INSERT INTO zerobucket_images (id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+var SELECT_FULL2 = `SELECT ${COLS} FROM zerobucket_images WHERE id = ?`;
+var selectMany = (n) => `SELECT ${COLS} FROM zerobucket_images WHERE id IN (${placeholders(n)})`;
+var SELECT_METADATA2 = `SELECT id, mime_type, original_filename, size_bytes, width, height, checksum_sha256 FROM zerobucket_images WHERE id = ?`;
+var STREAM_INFO = `SELECT size_bytes, storage_backend, object_storage_key FROM zerobucket_images WHERE id = ?`;
+var CHUNK = `SELECT substr(data, ?, ?) AS chunk FROM zerobucket_images WHERE id = ?`;
+var EXISTS2 = `SELECT 1 FROM zerobucket_images WHERE id = ?`;
+var DELETE_ONE = `DELETE FROM zerobucket_images WHERE id = ? RETURNING storage_backend, object_storage_key`;
+var deleteMany = (n) => `DELETE FROM zerobucket_images WHERE id IN (${placeholders(n)}) RETURNING id, storage_backend, object_storage_key`;
+var SELECT_FOR_TIERING2 = `SELECT data, mime_type, size_bytes, storage_backend FROM zerobucket_images WHERE id = ?`;
+var UPDATE_AFTER_TIERING2 = `UPDATE zerobucket_images SET data = NULL, storage_backend = 'object_storage', object_storage_bucket = ?, object_storage_key = ?, updated_at = ? WHERE id = ?`;
+var D_FROM2 = `FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256`;
+var D_COLS2 = `r.id AS id, b.data AS data, b.mime_type AS mime_type, r.original_filename AS original_filename, b.size_bytes AS size_bytes, b.width AS width, b.height AS height, r.checksum_sha256 AS checksum_sha256, 'sqlite' AS storage_backend, NULL AS object_storage_bucket, NULL AS object_storage_key`;
+var D_UPSERT = `INSERT INTO zerobucket_blobs (checksum_sha256, data, mime_type, size_bytes, width, height, ref_count, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (checksum_sha256) DO UPDATE SET ref_count = ref_count + excluded.ref_count`;
+var D_INSERT_REF2 = `INSERT INTO zerobucket_image_refs (id, checksum_sha256, original_filename, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`;
+var D_SELECT_FULL = `SELECT ${D_COLS2} ${D_FROM2} WHERE r.id = ?`;
+var dSelectMany = (n) => `SELECT ${D_COLS2} ${D_FROM2} WHERE r.id IN (${placeholders(n)})`;
+var D_SELECT_METADATA = `SELECT r.id AS id, b.mime_type AS mime_type, r.original_filename AS original_filename, b.size_bytes AS size_bytes, b.width AS width, b.height AS height, r.checksum_sha256 AS checksum_sha256 ${D_FROM2} WHERE r.id = ?`;
+var D_STREAM_INFO = `SELECT b.size_bytes AS size_bytes, 'sqlite' AS storage_backend, NULL AS object_storage_key ${D_FROM2} WHERE r.id = ?`;
+var D_CHUNK = `SELECT substr(b.data, ?, ?) AS chunk ${D_FROM2} WHERE r.id = ?`;
+var D_EXISTS = `SELECT 1 FROM zerobucket_image_refs WHERE id = ?`;
+var D_DELETE_REF2 = `DELETE FROM zerobucket_image_refs WHERE id = ? RETURNING checksum_sha256`;
+var dDeleteRefs = (n) => `DELETE FROM zerobucket_image_refs WHERE id IN (${placeholders(n)}) RETURNING id, checksum_sha256`;
+var D_DECREMENT2 = `UPDATE zerobucket_blobs SET ref_count = ref_count - ? WHERE checksum_sha256 = ? RETURNING ref_count`;
+var D_DELETE_EMPTY2 = `DELETE FROM zerobucket_blobs WHERE checksum_sha256 = ? AND ref_count <= 0`;
+var IN_CHUNK = 500;
+var ATTEMPT_BUSY_MS = 25;
+var DEFAULT_BUSY_TIMEOUT_MS = 1e4;
+function placeholders(n) {
+  return Array.from({ length: n }, () => "?").join(", ");
+}
+function isoNow() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace("Z", "000+00:00");
+}
+function isBusy(exc) {
+  const code = exc?.code;
+  return typeof code === "string" && (code.startsWith("SQLITE_BUSY") || code.startsWith("SQLITE_LOCKED"));
+}
+var Mutex = class {
+  tail = Promise.resolve();
+  run(fn) {
+    const prev = this.tail;
+    let release;
+    this.tail = new Promise((r) => release = r);
+    return prev.then(fn).finally(release);
+  }
+};
+var SQLiteBackend = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.path)
+      throw new TypeError(
+        'SQLiteBackend requires a `path` (a file path or ":memory:")'
+      );
+    this.dedup = opts.dedup ?? false;
+    this.busyTimeoutMs = opts.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+    if (this.dedup && opts.objectStorage) {
+      throw new TypeError(
+        "objectStorage is not supported together with dedup: true (same restriction as the Python package). Tiering moves one image's bytes, but a deduplicated blob can be shared by many images."
+      );
+    }
+  }
+  opts;
+  db;
+  Database;
+  readyPromise;
+  closed = false;
+  dedup;
+  busyTimeoutMs;
+  writeLock = new Mutex();
+  // ---- lifecycle -------------------------------------------------------
+  ready() {
+    if (this.closed)
+      return Promise.reject(
+        new StorageError("This ZeroBucket instance has been closed")
+      );
+    this.readyPromise ??= this.init().catch((exc) => {
+      this.readyPromise = void 0;
+      throw exc;
+    });
+    return this.readyPromise;
+  }
+  async init() {
+    try {
+      const mod = await import("better-sqlite3");
+      this.Database = mod.default ?? mod;
+    } catch (cause) {
+      throw new StorageError(
+        "SQLiteBackend requires the 'better-sqlite3' package. Install it with: npm install better-sqlite3",
+        { cause }
+      );
+    }
+    const db = new this.Database(this.opts.path, { timeout: ATTEMPT_BUSY_MS });
+    try {
+      await this.retrying(() => {
+        if (this.opts.path !== ":memory:" && db.pragma("journal_mode", { simple: true }) !== "wal") {
+          db.pragma("journal_mode = WAL");
+        }
+        db.pragma("foreign_keys = ON");
+        if (this.opts.autoMigrate ?? true)
+          db.exec(this.dedup ? DEDUP_SCHEMA2 : SCHEMA2);
+      });
+    } catch (exc) {
+      try {
+        db.close();
+      } catch {
+      }
+      throw new StorageError(
+        `Could not open SQLite database ${JSON.stringify(this.opts.path)}: ${msg(exc)}`,
+        { cause: exc }
+      );
+    }
+    this.db = db;
+  }
+  async close() {
+    this.closed = true;
+    const db = this.db;
+    this.db = void 0;
+    this.readyPromise = void 0;
+    await this.writeLock.run(async () => {
+      db?.close();
+    });
+  }
+  // ---- execution core --------------------------------------------------
+  emit(operation, start, success, error, retryCount) {
+    const cb = this.opts.onOperation;
+    if (!cb) return;
+    try {
+      cb({
+        operation,
+        durationMs: performance.now() - start,
+        success,
+        error,
+        retryCount
+      });
+    } catch {
+    }
+  }
+  /** Re-run `fn` while another connection holds a lock, sleeping asynchronously between attempts. `fn` must be atomic. */
+  async retrying(fn, onRetry) {
+    const deadline = performance.now() + this.busyTimeoutMs;
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return fn();
+      } catch (exc) {
+        if (!isBusy(exc) || performance.now() >= deadline) throw exc;
+        attempt += 1;
+        onRetry?.(attempt);
+        await sleep(
+          Math.min(5 * 2 ** Math.min(attempt, 5), 100) + Math.random() * 5
+        );
+      }
+    }
+  }
+  /** BEGIN IMMEDIATE takes the write lock up front, so a BUSY comes before any work and the whole unit is safely re-runnable. */
+  tx(db, work) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      const result = work(db);
+      db.exec("COMMIT");
+      return result;
+    } catch (exc) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  /**
+   * All-or-nothing work on a CALLER-supplied handle. SAVEPOINT works whether or not the caller has an open
+   * transaction: inside one it nests (a failure rolls back only our work); outside one it begins and, on
+   * RELEASE, commits.
+   */
+  atomic(db, work) {
+    db.exec("SAVEPOINT zerobucket_atomic");
+    try {
+      const result = work(db);
+      db.exec("RELEASE SAVEPOINT zerobucket_atomic");
+      return result;
+    } catch (exc) {
+      try {
+        db.exec("ROLLBACK TO SAVEPOINT zerobucket_atomic");
+        db.exec("RELEASE SAVEPOINT zerobucket_atomic");
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  async execute(operation, connection, mode, work) {
+    const start = performance.now();
+    let retries = 0;
+    try {
+      let result;
+      if (connection) {
+        if (typeof connection.prepare !== "function") {
+          throw new TypeError(
+            "SQLiteBackend expects a better-sqlite3 Database as `connection` (an object with prepare()), not a pg client."
+          );
+        }
+        const db = connection;
+        result = mode === "write" ? this.atomic(db, work) : work(db);
+      } else {
+        await this.ready();
+        const db = this.db;
+        const onRetry = (n) => retries = n;
+        result = mode === "write" ? await this.writeLock.run(
+          () => this.retrying(() => this.tx(db, work), onRetry)
+        ) : await this.retrying(() => work(db), onRetry);
+      }
+      this.emit(operation, start, true, null, retries);
+      return result;
+    } catch (exc) {
+      this.emit(operation, start, false, msg(exc), retries);
+      throw exc;
+    }
+  }
+  // ---- StorageBackend --------------------------------------------------
+  async put(row, { connection } = {}) {
+    try {
+      return await this.execute(
+        "put",
+        connection,
+        "write",
+        (db) => this.insertOne(db, row)
+      );
+    } catch (exc) {
+      throw wrap("Failed to store image", exc);
+    }
+  }
+  insertOne(db, r) {
+    const id = (0, import_node_crypto.randomUUID)();
+    const now = isoNow();
+    if (this.dedup) {
+      db.prepare(D_UPSERT).run(
+        r.checksumSha256,
+        r.data,
+        r.mimeType,
+        r.sizeBytes,
+        r.width,
+        r.height,
+        1,
+        now
+      );
+      db.prepare(D_INSERT_REF2).run(
+        id,
+        r.checksumSha256,
+        r.originalFilename,
+        now,
+        now
+      );
+    } else {
+      db.prepare(INSERT2).run(
+        id,
+        r.data,
+        r.mimeType,
+        r.originalFilename,
+        r.sizeBytes,
+        r.width,
+        r.height,
+        r.checksumSha256,
+        now,
+        now
+      );
+    }
+    return id;
+  }
+  async putMany(rows, { connection } = {}) {
+    if (rows.length === 0) return [];
+    try {
+      return await this.execute("put_many", connection, "write", (db) => {
+        if (!this.dedup) return rows.map((r) => this.insertOne(db, r));
+        const now = isoNow();
+        const groups = /* @__PURE__ */ new Map();
+        for (const r of rows) {
+          const g = groups.get(r.checksumSha256);
+          if (g) g.n += 1;
+          else groups.set(r.checksumSha256, { row: r, n: 1 });
+        }
+        for (const [checksum, { row, n }] of groups) {
+          db.prepare(D_UPSERT).run(
+            checksum,
+            row.data,
+            row.mimeType,
+            row.sizeBytes,
+            row.width,
+            row.height,
+            n,
+            now
+          );
+        }
+        return rows.map((r) => {
+          const id = (0, import_node_crypto.randomUUID)();
+          db.prepare(D_INSERT_REF2).run(
+            id,
+            r.checksumSha256,
+            r.originalFilename,
+            now,
+            now
+          );
+          return id;
+        });
+      });
+    } catch (exc) {
+      throw wrap("Failed to store image batch", exc);
+    }
+  }
+  async get(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
+    let row;
+    try {
+      row = await this.execute(
+        "get",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_SELECT_FULL : SELECT_FULL2).get(norm)
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image", exc);
+    }
+    return row ? hydrateRow(row, norm, this.opts.objectStorage) : null;
+  }
+  async getMany(ids, { connection } = {}) {
+    const valid = [
+      ...new Set(ids.filter(isValidId).map((i) => i.toLowerCase()))
+    ];
+    if (valid.length === 0) return [];
+    let rows;
+    try {
+      rows = await this.execute("get_many", connection, "read", (db) => {
+        const out = [];
+        for (let i = 0; i < valid.length; i += IN_CHUNK) {
+          const part = valid.slice(i, i + IN_CHUNK);
+          out.push(
+            ...db.prepare(
+              this.dedup ? dSelectMany(part.length) : selectMany(part.length)
+            ).all(...part)
+          );
+        }
+        return out;
+      });
+    } catch (exc) {
+      throw wrap("Failed to retrieve image batch", exc);
+    }
+    return mapLimit(
+      rows,
+      4,
+      (r) => hydrateRow(r, String(r.id), this.opts.objectStorage)
+    );
+  }
+  async getMetadata(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.execute(
+        "get_metadata",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_SELECT_METADATA : SELECT_METADATA2).get(id.toLowerCase())
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!row) return null;
+    return {
+      id: String(row.id),
+      mimeType: row.mime_type,
+      originalFilename: row.original_filename,
+      sizeBytes: row.size_bytes,
+      width: row.width,
+      height: row.height,
+      checksumSha256: row.checksum_sha256
+    };
+  }
+  async getStream(id, opts) {
+    if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
+    const { connection, chunkSize } = opts;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0)
+      throw new RangeError("chunkSize must be a positive integer");
+    let info;
+    try {
+      info = await this.execute(
+        "get_metadata",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_STREAM_INFO : STREAM_INFO).get(norm)
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!info) return null;
+    const totalSize = info.size_bytes;
+    const start = opts.range?.start ?? 0;
+    const end = Math.min(opts.range?.end ?? totalSize - 1, totalSize - 1);
+    if (info.storage_backend === "object_storage") {
+      const os = this.opts.objectStorage;
+      if (!os) throw tieredWithoutStorage(norm, info.object_storage_key);
+      return streamFromObjectStorage(
+        os,
+        norm,
+        info.object_storage_key,
+        start,
+        end,
+        chunkSize
+      );
+    }
+    const self = this;
+    async function* generate() {
+      let offset = start;
+      let delivered = 0;
+      const wanted = Math.max(0, end - start + 1);
+      while (delivered < wanted) {
+        const length = Math.min(chunkSize, wanted - delivered);
+        let row;
+        try {
+          row = await self.execute(
+            "get_stream",
+            connection,
+            "read",
+            (db) => db.prepare(self.dedup ? D_CHUNK : CHUNK).get(offset + 1, length, norm)
+          );
+        } catch (exc) {
+          throw wrap("Failed to stream image", exc);
+        }
+        if (!row) {
+          throw new StorageError(
+            `Image ${JSON.stringify(norm)} was deleted while streaming (delivered ${delivered} of ${wanted} bytes). Pass connection with your own open transaction if you need a consistent read across concurrent writers.`
+          );
+        }
+        const chunk = row.chunk;
+        if (!chunk || chunk.length === 0) {
+          throw new StorageError(
+            `Image ${JSON.stringify(norm)} ended early while streaming (delivered ${delivered} of ${wanted} bytes).`
+          );
+        }
+        yield chunk;
+        offset += chunk.length;
+        delivered += chunk.length;
+      }
+    }
+    return generate();
+  }
+  async delete(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    const norm = id.toLowerCase();
+    try {
+      if (this.dedup) {
+        return await this.execute("delete", connection, "write", (db) => {
+          const ref = db.prepare(D_DELETE_REF2).get(norm);
+          if (!ref) return false;
+          const dec = db.prepare(D_DECREMENT2).get(1, ref.checksum_sha256);
+          if (dec && dec.ref_count <= 0)
+            db.prepare(D_DELETE_EMPTY2).run(ref.checksum_sha256);
+          return true;
+        });
+      }
+      const row = await this.execute(
+        "delete",
+        connection,
+        "write",
+        (db) => db.prepare(DELETE_ONE).get(norm)
+      );
+      if (row?.storage_backend === "object_storage")
+        await this.cleanupObjects([row.object_storage_key], connection);
+      return row !== void 0;
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteMany(ids, { connection } = {}) {
+    const valid = [
+      ...new Set(ids.filter(isValidId).map((i) => i.toLowerCase()))
+    ];
+    if (valid.length === 0) return [];
+    try {
+      if (this.dedup) {
+        return await this.execute("delete_many", connection, "write", (db) => {
+          const deleted = [];
+          for (let i = 0; i < valid.length; i += IN_CHUNK) {
+            const part = valid.slice(i, i + IN_CHUNK);
+            deleted.push(...db.prepare(dDeleteRefs(part.length)).all(...part));
+          }
+          const counts = /* @__PURE__ */ new Map();
+          for (const r of deleted)
+            counts.set(
+              r.checksum_sha256,
+              (counts.get(r.checksum_sha256) ?? 0) + 1
+            );
+          for (const [checksum, n] of counts) {
+            const dec = db.prepare(D_DECREMENT2).get(n, checksum);
+            if (dec && dec.ref_count <= 0)
+              db.prepare(D_DELETE_EMPTY2).run(checksum);
+          }
+          return deleted.map((r) => String(r.id));
+        });
+      }
+      const rows = await this.execute(
+        "delete_many",
+        connection,
+        "write",
+        (db) => {
+          const out = [];
+          for (let i = 0; i < valid.length; i += IN_CHUNK) {
+            const part = valid.slice(i, i + IN_CHUNK);
+            out.push(...db.prepare(deleteMany(part.length)).all(...part));
+          }
+          return out;
+        }
+      );
+      await this.cleanupObjects(
+        rows.filter((r) => r.storage_backend === "object_storage").map((r) => r.object_storage_key),
+        connection
+      );
+      return rows.map((r) => String(r.id));
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  async exists(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    try {
+      return await this.execute(
+        "exists",
+        connection,
+        "read",
+        (db) => db.prepare(this.dedup ? D_EXISTS : EXISTS2).get(id.toLowerCase()) !== void 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", exc);
+    }
+  }
+  /**
+   * Remove tiered objects AFTER their rows are gone (a failed object delete leaves a harmless orphan; the
+   * reverse order could leave a row pointing at nothing). Skipped inside a caller-owned transaction, since the
+   * commit outcome is unknown. Failures never fail the delete; they are reported through onOperation.
+   */
+  async cleanupObjects(keys, connection) {
+    const os = this.opts.objectStorage;
+    if (!os || connection || keys.length === 0) return;
+    await Promise.all(
+      keys.map(async (key) => {
+        const start = performance.now();
+        try {
+          await os.delete(key);
+          this.emit("object_storage_delete", start, true, null, 0);
+        } catch (exc) {
+          this.emit("object_storage_delete", start, false, msg(exc), 0);
+        }
+      })
+    );
+  }
+  /**
+   * Move an image's bytes into object storage. null = no such image, false = already tiered, true = tiered now.
+   *
+   * SAFETY (same guarantee as Postgres): the upload happens INSIDE a BEGIN IMMEDIATE transaction; if it fails the
+   * transaction rolls back and the row is untouched.
+   *
+   * TRADEOFF (coarser than Postgres): SQLite has no row locks, so BEGIN IMMEDIATE locks the WHOLE DATABASE for the
+   * upload. Other processes' writes wait; this process's writes queue behind an async lock; reads are not blocked.
+   */
+  async tierToObjectStorage(id, { connection } = {}) {
+    if (this.dedup)
+      throw new StorageError(
+        "tierToObjectStorage() is not supported in dedup mode (a blob may be shared by many images)."
+      );
+    const os = this.opts.objectStorage;
+    if (!os) {
+      throw new StorageError(
+        "tierToObjectStorage() requires objectStorage to be configured (new ZeroBucket({ sqlite, objectStorage: new ObjectStorage({ bucket }) }))."
+      );
+    }
+    if (connection) {
+      throw new StorageError(
+        "tierToObjectStorage() does not accept `connection` on SQLite: it needs its own dedicated connection for the BEGIN IMMEDIATE transaction."
+      );
+    }
+    if (this.opts.path === ":memory:") {
+      throw new StorageError(
+        "tierToObjectStorage() needs a database file: an in-memory SQLite database cannot be shared with its dedicated tiering connection."
+      );
+    }
+    if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
+    const start = performance.now();
+    let retries = 0;
+    try {
+      await this.ready();
+      const result = await this.writeLock.run(async () => {
+        const tdb = new this.Database(this.opts.path, {
+          timeout: ATTEMPT_BUSY_MS
+        });
+        try {
+          await this.retrying(
+            () => tdb.exec("BEGIN IMMEDIATE"),
+            (n) => retries = n
+          );
+          try {
+            const row = tdb.prepare(SELECT_FOR_TIERING2).get(norm);
+            if (!row) {
+              tdb.exec("ROLLBACK");
+              return null;
+            }
+            if (row.storage_backend !== "sqlite") {
+              tdb.exec("ROLLBACK");
+              return false;
+            }
+            await os.upload(norm, row.data, {
+              mimeType: row.mime_type
+            });
+            tdb.prepare(UPDATE_AFTER_TIERING2).run(os.bucket, norm, isoNow(), norm);
+            tdb.exec("COMMIT");
+            return true;
+          } catch (exc) {
+            try {
+              tdb.exec("ROLLBACK");
+            } catch {
+            }
+            throw exc;
+          }
+        } finally {
+          tdb.close();
+        }
+      });
+      this.emit("tier_to_object_storage", start, true, null, retries);
+      return result;
+    } catch (exc) {
+      this.emit("tier_to_object_storage", start, false, msg(exc), retries);
+      throw wrap("Failed to tier image to object storage", exc);
+    }
+  }
+};
+
+// src/validation.ts
+var FORMAT_TO_MIME = {
+  jpeg: "image/jpeg",
+  png: "image/png",
+  webp: "image/webp"
+};
+var SUPPORTED_FORMATS = Object.keys(FORMAT_TO_MIME);
+var DEFAULT_MAX_PIXELS = 89e6;
+var sharpPromise;
+function loadSharp() {
+  sharpPromise ??= import("sharp").then(
+    // ESM gives { default: sharp }; some CJS interop gives sharp directly.
+    (m) => m.default ?? m,
+    (cause) => {
+      sharpPromise = void 0;
+      throw new StorageError(
+        "Image validation requires the optional dependency 'sharp'. Install it with: npm install sharp",
+        { cause }
+      );
+    }
+  );
+  return sharpPromise;
+}
+async function validateImage(data, opts) {
+  const {
+    maxBytes,
+    maxPixels = DEFAULT_MAX_PIXELS,
+    allowedFormats = SUPPORTED_FORMATS
+  } = opts;
+  const sizeBytes = data.length;
+  if (sizeBytes > maxBytes) throw new ImageTooLargeError(sizeBytes, maxBytes);
+  if (sizeBytes === 0) throw new CorruptedImageError("Image data is empty");
+  const sharp = await loadSharp();
+  const make = () => sharp(data, { limitInputPixels: maxPixels, failOn: "error" });
+  let format;
+  let width;
+  let height;
+  try {
+    const meta = await make().metadata();
+    format = meta.format;
+    width = meta.width;
+    height = meta.height;
+  } catch (exc) {
+    if (isPixelLimit(exc)) throw new ImageTooLargeError(sizeBytes, maxBytes);
+    throw new CorruptedImageError(
+      `Could not decode image: ${errMessage(exc)}`,
+      { cause: exc }
+    );
+  }
+  if (!format || !allowedFormats.includes(format) || !(format in FORMAT_TO_MIME)) {
+    throw new UnsupportedFormatError(format ?? null, allowedFormats);
+  }
+  if (!width || !height)
+    throw new CorruptedImageError("Image has no readable dimensions");
+  try {
+    await make().stats();
+  } catch (exc) {
+    if (isPixelLimit(exc)) throw new ImageTooLargeError(sizeBytes, maxBytes);
+    throw new CorruptedImageError(
+      `Image data is truncated or corrupted: ${errMessage(exc)}`,
+      {
+        cause: exc
+      }
+    );
+  }
+  return { mimeType: FORMAT_TO_MIME[format], width, height, sizeBytes };
+}
+function isPixelLimit(exc) {
+  return /pixel limit/i.test(errMessage(exc));
+}
+function errMessage(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+
+// src/optimize.ts
+var DEFAULT_JPEG_QUALITY = 90;
+var DEFAULT_WEBP_QUALITY = 88;
+var FORMAT_ALIASES = { jpg: "jpeg" };
+async function optimizeImage(data, opts) {
+  const { maxWidth, quality, maxBytes, maxPixels = DEFAULT_MAX_PIXELS } = opts;
+  const sharp = await loadSharp();
+  const originalSizeBytes = data.length;
+  const base = sharp(data, { limitInputPixels: maxPixels, failOn: "error" });
+  const meta = await base.metadata();
+  const requested = (opts.format ?? meta.format ?? "jpeg").toLowerCase();
+  const target = FORMAT_ALIASES[requested] ?? requested;
+  if (!SUPPORTED_FORMATS.includes(target)) {
+    throw new ImageValidationError(
+      `Cannot re-encode to unsupported format ${JSON.stringify(target)}. Supported: ${JSON.stringify(
+        [...SUPPORTED_FORMATS].sort()
+      )}`
+    );
+  }
+  let pipeline = sharp(data, {
+    limitInputPixels: maxPixels,
+    failOn: "error"
+  }).rotate();
+  if (maxWidth !== void 0) {
+    pipeline = pipeline.resize({
+      width: maxWidth,
+      fit: "inside",
+      withoutEnlargement: true,
+      kernel: "lanczos3"
+    });
+  }
+  if (target === "jpeg") {
+    pipeline = pipeline.flatten({ background: "#ffffff" }).jpeg({
+      quality: quality ?? DEFAULT_JPEG_QUALITY,
+      mozjpeg: true,
+      progressive: true
+    });
+  } else if (target === "webp") {
+    pipeline = pipeline.webp({
+      quality: quality ?? DEFAULT_WEBP_QUALITY,
+      effort: 6
+    });
+  } else {
+    pipeline = pipeline.png({ compressionLevel: 9 });
+  }
+  const out = await pipeline.toBuffer();
+  const revalidated = await validateImage(out, { maxBytes, maxPixels });
+  return {
+    data: out,
+    mimeType: revalidated.mimeType,
+    width: revalidated.width,
+    height: revalidated.height,
+    sizeBytes: revalidated.sizeBytes,
+    originalSizeBytes
+  };
+}
+
+// src/client.ts
+var DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+var PREPARE_CONCURRENCY = 4;
+var ZeroBucket = class _ZeroBucket {
+  backend;
+  maxBytes;
+  maxPixels;
+  allowedFormats;
+  beforeGet;
+  beforePut;
+  constructor(options = {}) {
+    if (options.sqlite !== void 0 && (options.connectionString || options.pool)) {
+      throw new TypeError(
+        "Choose one database: `sqlite` OR `connectionString`/`pool`, not both."
+      );
+    }
+    this.backend = options.backend ?? (options.sqlite !== void 0 ? new SQLiteBackend({
+      path: options.sqlite,
+      autoMigrate: options.autoMigrate,
+      dedup: options.dedup,
+      objectStorage: options.objectStorage,
+      onOperation: options.onOperation
+    }) : new PostgresBackend({
+      connectionString: options.connectionString,
+      pool: options.pool,
+      autoMigrate: options.autoMigrate,
+      maxRetries: options.maxRetries,
+      retryBaseDelayMs: options.retryBaseDelayMs,
+      poolMinSize: options.poolMinSize,
+      poolMaxSize: options.poolMaxSize,
+      poolTimeoutMs: options.poolTimeoutMs,
+      onOperation: options.onOperation,
+      objectStorage: options.objectStorage,
+      dedup: options.dedup
+    }));
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.maxPixels = options.maxPixels ?? DEFAULT_MAX_PIXELS;
+    this.allowedFormats = options.allowedFormats ?? SUPPORTED_FORMATS;
+    this.beforeGet = options.beforeGet;
+    this.beforePut = options.beforePut;
+  }
+  /** Construct AND connect/migrate immediately, so a bad DATABASE_URL fails at startup, not on first request. */
+  static async connect(options = {}) {
+    const zb = new _ZeroBucket(options);
+    await zb.ready();
+    return zb;
+  }
+  /** Resolves once connected and migrated. Called automatically on first use. */
+  ready() {
+    return this.backend.ready();
+  }
+  // ---- hooks -----------------------------------------------------------
+  async checkBeforeGet(imageId, context) {
+    if (!this.beforeGet) return;
+    if (!await this.beforeGet(imageId, context))
+      throw new AccessDeniedError("get", imageId);
+  }
+  async checkBeforePut(context) {
+    if (!this.beforePut) return;
+    if (!await this.beforePut(context)) throw new AccessDeniedError("put");
+  }
+  // ---- write path ------------------------------------------------------
+  async prepareRow(image, o) {
+    const { data, filename } = await readInput(
+      image,
+      o.filename ?? void 0,
+      this.maxBytes
+    );
+    let finalData;
+    let mimeType;
+    let width;
+    let height;
+    let sizeBytes;
+    if (o.validator) {
+      if (o.optimize) {
+        throw new ImageValidationError(
+          "optimize is not supported together with a custom validator: the optimize pipeline (resize/re-encode) is image-specific. Validate/transform custom content types yourself before put()."
+        );
+      }
+      const v = await o.validator.validate(data, { maxBytes: this.maxBytes });
+      finalData = data;
+      mimeType = v.mimeType;
+      width = v.width ?? null;
+      height = v.height ?? null;
+      sizeBytes = v.sizeBytes;
+    } else {
+      const validated = await validateImage(data, {
+        maxBytes: this.maxBytes,
+        maxPixels: this.maxPixels,
+        allowedFormats: this.allowedFormats
+      });
+      if (o.optimize) {
+        const opts = o.optimize === true ? {} : o.optimize;
+        const r = await optimizeImage(data, {
+          ...opts,
+          maxBytes: this.maxBytes,
+          maxPixels: this.maxPixels
+        });
+        finalData = r.data;
+        mimeType = r.mimeType;
+        width = r.width;
+        height = r.height;
+        sizeBytes = r.sizeBytes;
+      } else {
+        finalData = data;
+        mimeType = validated.mimeType;
+        width = validated.width;
+        height = validated.height;
+        sizeBytes = validated.sizeBytes;
+      }
+    }
+    return {
+      data: finalData,
+      mimeType,
+      originalFilename: filename ?? null,
+      sizeBytes,
+      width,
+      height,
+      checksumSha256: (0, import_node_crypto2.createHash)("sha256").update(finalData).digest("hex")
+    };
+  }
+  /** Validate, optionally optimize, checksum and store one image. Returns its id (a UUID). */
+  async put(image, options = {}) {
+    await this.checkBeforePut(options.context);
+    const row = await this.prepareRow(image, options);
+    return this.backend.put(row, { connection: options.connection });
+  }
+  /**
+   * 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.
+   */
+  async putMany(images, options = {}) {
+    const { filenames } = options;
+    if (filenames && filenames.length !== images.length) {
+      throw new RangeError(
+        "filenames must be the same length as images if provided"
+      );
+    }
+    const fail = (index, error) => ({
+      index,
+      imageId: null,
+      error,
+      success: false
+    });
+    if (this.beforePut) {
+      try {
+        if (!await this.beforePut(options.context))
+          return images.map((_, i) => fail(i, "access denied"));
+      } catch (exc) {
+        return images.map((_, i) => fail(i, errText(exc)));
+      }
+    }
+    const results = new Array(images.length);
+    const prepared = [];
+    await mapLimit2(images, PREPARE_CONCURRENCY, async (image, i) => {
+      try {
+        const row = await this.prepareRow(image, {
+          ...options,
+          filename: filenames?.[i] ?? void 0
+        });
+        prepared.push({ index: i, row });
+      } catch (exc) {
+        results[i] = fail(i, errText(exc));
+      }
+    });
+    prepared.sort((a, b) => a.index - b.index);
+    if (prepared.length > 0) {
+      try {
+        const ids = await this.backend.putMany(
+          prepared.map((p) => p.row),
+          { connection: options.connection }
+        );
+        prepared.forEach((p, n) => {
+          results[p.index] = {
+            index: p.index,
+            imageId: ids[n],
+            error: null,
+            success: true
+          };
+        });
+      } catch (exc) {
+        for (const p of prepared)
+          results[p.index] = fail(p.index, errText(exc));
+      }
+    }
+    return results;
+  }
+  // ---- read path -------------------------------------------------------
+  /** Retrieve a full image including bytes. Throws ImageNotFoundError if missing. */
+  async get(imageId, options = {}) {
+    await this.checkBeforeGet(imageId, options.context);
+    const record = await this.backend.get(imageId, {
+      connection: options.connection
+    });
+    if (!record) throw new ImageNotFoundError(imageId);
+    return {
+      data: record.data,
+      mimeType: record.mimeType,
+      filename: record.originalFilename,
+      sizeBytes: record.sizeBytes,
+      width: record.width,
+      height: record.height,
+      checksumSha256: record.checksumSha256
+    };
+  }
+  /**
+   * 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.
+   */
+  async getMany(imageIds, options = {}) {
+    const results = new Array(imageIds.length);
+    const allowedIdx = [];
+    for (let i = 0; i < imageIds.length; i++) {
+      const imageId = imageIds[i];
+      if (this.beforeGet) {
+        try {
+          if (!await this.beforeGet(imageId, options.context)) {
+            results[i] = {
+              imageId,
+              image: null,
+              error: "access denied",
+              success: false
+            };
+            continue;
+          }
+        } catch (exc) {
+          results[i] = {
+            imageId,
+            image: null,
+            error: errText(exc),
+            success: false
+          };
+          continue;
+        }
+      }
+      allowedIdx.push(i);
+    }
+    if (allowedIdx.length > 0) {
+      const records = await this.backend.getMany(
+        allowedIdx.map((i) => imageIds[i]),
+        { connection: options.connection }
+      );
+      const byId = new Map(records.map((r) => [r.id.toLowerCase(), r]));
+      for (const i of allowedIdx) {
+        const imageId = imageIds[i];
+        const r = byId.get(imageId.toLowerCase());
+        results[i] = r ? {
+          imageId,
+          image: {
+            data: r.data,
+            mimeType: r.mimeType,
+            filename: r.originalFilename,
+            sizeBytes: r.sizeBytes,
+            width: r.width,
+            height: r.height,
+            checksumSha256: r.checksumSha256
+          },
+          error: null,
+          success: true
+        } : { imageId, image: null, error: "not found", success: false };
+      }
+    }
+    return results;
+  }
+  /**
+   * 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).
+   */
+  async getStream(imageId, options = {}) {
+    await this.checkBeforeGet(imageId, options.context);
+    const { range } = options;
+    if (range) {
+      if (!Number.isInteger(range.start) || range.start < 0 || range.end !== void 0 && (!Number.isInteger(range.end) || range.end < range.start)) {
+        throw new RangeError(
+          "range must be { start >= 0, end >= start } with integer values"
+        );
+      }
+    }
+    const stream = await this.backend.getStream(imageId, {
+      chunkSize: options.chunkSize ?? DEFAULT_STREAM_CHUNK_SIZE,
+      connection: options.connection,
+      range: range ? { start: range.start, end: range.end ?? Number.MAX_SAFE_INTEGER } : void 0
+    });
+    if (!stream) throw new ImageNotFoundError(imageId);
+    return stream;
+  }
+  /** Same as getStream(), as a Web `ReadableStream` you can hand straight to `new Response(...)`. */
+  async toWebStream(imageId, options = {}) {
+    const iterable = await this.getStream(imageId, options);
+    const iterator = iterable[Symbol.asyncIterator]();
+    return new ReadableStream({
+      async pull(controller) {
+        try {
+          const { value, done } = await iterator.next();
+          if (done) controller.close();
+          else
+            controller.enqueue(
+              new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+            );
+        } catch (exc) {
+          controller.error(exc);
+        }
+      },
+      async cancel() {
+        await iterator.return?.();
+      }
+    });
+  }
+  /** Write an image to `destination` chunk by chunk (honouring backpressure). Returns bytes written. Does not end the destination. */
+  async streamTo(imageId, destination, options = {}) {
+    let total = 0;
+    for await (const chunk of await this.getStream(imageId, options)) {
+      const result = destination.write(chunk);
+      if (result === false && typeof destination.once === "function") {
+        await new Promise(
+          (resolve) => destination.once("drain", resolve)
+        );
+      } else if (result && typeof result.then === "function") {
+        await result;
+      }
+      total += chunk.length;
+    }
+    return total;
+  }
+  /** Metadata without pulling the bytes. Gated by the same beforeGet hook as get(). */
+  async metadata(imageId, options = {}) {
+    await this.checkBeforeGet(imageId, options.context);
+    const r = await this.backend.getMetadata(imageId, {
+      connection: options.connection
+    });
+    if (!r) throw new ImageNotFoundError(imageId);
+    return {
+      imageId: r.id,
+      mimeType: r.mimeType,
+      filename: r.originalFilename,
+      sizeBytes: r.sizeBytes,
+      width: r.width,
+      height: r.height,
+      checksumSha256: r.checksumSha256
+    };
+  }
+  /** Whether an image exists. Deliberately NOT gated by beforeGet (returns no data or metadata). */
+  exists(imageId, options = {}) {
+    return this.backend.exists(imageId, options);
+  }
+  /** Delete an image. Returns true if it existed. */
+  delete(imageId, options = {}) {
+    return this.backend.delete(imageId, options);
+  }
+  /** Delete many in one query. Results are in input order; a missing id is `deleted: false`, not an error. */
+  async deleteMany(imageIds, options = {}) {
+    if (imageIds.length === 0) return [];
+    const deleted = new Set(
+      (await this.backend.deleteMany(imageIds, options)).map(
+        (id) => id.toLowerCase()
+      )
+    );
+    return imageIds.map((imageId) => ({
+      imageId,
+      deleted: deleted.has(imageId.toLowerCase()),
+      error: null,
+      success: true
+    }));
+  }
+  /**
+   * 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).
+   */
+  async tierToObjectStorage(imageId, options = {}) {
+    const result = await this.backend.tierToObjectStorage(imageId, options);
+    if (result === null) throw new ImageNotFoundError(imageId);
+    return result;
+  }
+  /**
+   * 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.
+   */
+  async migrateClassicToDedup() {
+    if (!this.backend.migrateClassicToDedup) {
+      throw new StorageError(
+        "This backend does not support migrateClassicToDedup()."
+      );
+    }
+    return this.backend.migrateClassicToDedup();
+  }
+  /** Release the pool (if ZeroBucket created it). */
+  close() {
+    return this.backend.close();
+  }
+};
+async function readInput(image, filename, maxBytes) {
+  if (typeof image === "string") {
+    const size = (await (0, import_promises.stat)(image)).size;
+    if (size > maxBytes) throw new ImageTooLargeError(size, maxBytes);
+    return {
+      data: await (0, import_promises.readFile)(image),
+      filename: filename ?? (0, import_node_path.basename)(image)
+    };
+  }
+  if (Buffer.isBuffer(image)) return { data: image, filename };
+  if (image instanceof Uint8Array)
+    return {
+      data: Buffer.from(image.buffer, image.byteOffset, image.byteLength),
+      filename
+    };
+  if (image instanceof ArrayBuffer)
+    return { data: Buffer.from(image), filename };
+  if (typeof Blob !== "undefined" && image instanceof Blob) {
+    if (image.size > maxBytes)
+      throw new ImageTooLargeError(image.size, maxBytes);
+    const name = image.name;
+    return {
+      data: Buffer.from(await image.arrayBuffer()),
+      filename: filename ?? (typeof name === "string" ? name : void 0)
+    };
+  }
+  if (image && typeof image[Symbol.asyncIterator] === "function") {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of image) {
+      const buf = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+      total += buf.length;
+      if (total > maxBytes) {
+        image.destroy?.();
+        throw new ImageTooLargeError(total, maxBytes);
+      }
+      chunks.push(buf);
+    }
+    const p = image.path;
+    return {
+      data: Buffer.concat(chunks, total),
+      filename: filename ?? (typeof p === "string" ? (0, import_node_path.basename)(p) : void 0)
+    };
+  }
+  throw new TypeError(
+    "Unsupported image input. Pass a Buffer, Uint8Array, file path string, Blob/File, or a readable stream."
+  );
+}
+async function mapLimit2(items, limit, fn) {
+  let next = 0;
+  const workers = Array.from(
+    { length: Math.min(limit, items.length) },
+    async () => {
+      while (next < items.length) {
+        const i = next++;
+        await fn(items[i], i);
+      }
+    }
+  );
+  await Promise.all(workers);
+}
+function errText(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+
+// src/object-storage.ts
+var ObjectStorage = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.bucket)
+      throw new TypeError("ObjectStorage requires a bucket name");
+    this.bucket = opts.bucket;
+  }
+  opts;
+  bucket;
+  clientPromise;
+  connection() {
+    this.clientPromise ??= (async () => {
+      let sdk;
+      try {
+        sdk = await import("@aws-sdk/client-s3");
+      } catch (cause) {
+        throw new StorageError(
+          "Object-storage tiering requires the optional dependency '@aws-sdk/client-s3'. Install it with: npm install @aws-sdk/client-s3",
+          { cause }
+        );
+      }
+      const o = this.opts;
+      const client = o.client ?? new sdk.S3Client({
+        endpoint: o.endpoint,
+        region: o.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1",
+        credentials: o.credentials,
+        forcePathStyle: o.forcePathStyle ?? o.endpoint !== void 0
+      });
+      return { sdk, client };
+    })().catch((exc) => {
+      this.clientPromise = void 0;
+      throw exc;
+    });
+    return this.clientPromise;
+  }
+  async upload(key, data, { mimeType }) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: data,
+          ContentType: mimeType
+        })
+      );
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to upload ${JSON.stringify(key)} to bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async download(key) {
+    return this.get(key, void 0);
+  }
+  async downloadRange(key, start, endInclusive) {
+    return this.get(key, `bytes=${start}-${endInclusive}`);
+  }
+  async get(key, range) {
+    const { sdk, client } = await this.connection();
+    try {
+      const res = await client.send(
+        new sdk.GetObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Range: range
+        })
+      );
+      return Buffer.from(await res.Body.transformToByteArray());
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to download ${JSON.stringify(key)} from bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async delete(key) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: key })
+      );
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to delete ${JSON.stringify(key)} from bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async exists(key) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.HeadObjectCommand({ Bucket: this.bucket, Key: key })
+      );
+      return true;
+    } catch (exc) {
+      const e = exc;
+      if (e.name === "NotFound" || e.name === "NoSuchKey" || e.$metadata?.httpStatusCode === 404)
+        return false;
+      throw new StorageError(
+        `Failed to check ${JSON.stringify(key)} in bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+};
+function msg2(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+
+// src/validators/pdf.ts
+var DEFAULT_MAX_PDF_BYTES = 20 * 1024 * 1024;
+var PDFValidator = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  opts;
+  validate(data, { maxBytes }) {
+    const effectiveMax = Math.min(
+      maxBytes,
+      this.opts.maxBytes ?? DEFAULT_MAX_PDF_BYTES
+    );
+    if (data.length === 0)
+      throw new ContentValidationError("PDF data is empty");
+    if (data.length > effectiveMax) {
+      throw new ContentValidationError(
+        `PDF is ${data.length} bytes, exceeds the maximum of ${effectiveMax} bytes`
+      );
+    }
+    if (!data.subarray(0, 1024).includes("%PDF-")) {
+      throw new ContentValidationError(
+        "This does not look like a valid PDF (missing '%PDF-' header). Content is checked by inspecting the actual bytes, not the filename or any client-supplied content type."
+      );
+    }
+    return {
+      mimeType: "application/pdf",
+      sizeBytes: data.length,
+      width: null,
+      height: null
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AccessDeniedError,
+  ContentValidationError,
+  CorruptedImageError,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_PIXELS,
+  DEFAULT_STREAM_CHUNK_SIZE,
+  ImageNotFoundError,
+  ImageTooLargeError,
+  ImageValidationError,
+  ObjectStorage,
+  PDFValidator,
+  PostgresBackend,
+  SQLiteBackend,
+  SUPPORTED_FORMATS,
+  StorageError,
+  UnsupportedFormatError,
+  ZeroBucket,
+  ZeroBucketError,
+  optimizeImage,
+  readInput,
+  validateImage
+});
+//# sourceMappingURL=index.cjs.map