zerobucket 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1245 @@
+"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,
+  PDFValidator: () => PDFValidator,
+  PostgresBackend: () => PostgresBackend,
+  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_crypto = 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/postgres.ts
+var DEFAULT_STREAM_CHUNK_SIZE = 1024 * 1024;
+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 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);
+}
+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;
+  }
+  opts;
+  pool;
+  ownsPool;
+  readyPromise;
+  closed = false;
+  maxRetries;
+  retryBaseDelayMs;
+  autoMigrate;
+  // ---- 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(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) {
+      const start2 = performance.now();
+      try {
+        const result = 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));
+    }
+  }
+  // ---- StorageBackend --------------------------------------------------
+  async put(row, { connection } = {}) {
+    try {
+      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 {
+      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(SELECT_FULL, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image", exc);
+    }
+    return row ? this.toRecord(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(SELECT_MANY, [valid])).rows
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image batch", exc);
+    }
+    return rows.map((r) => this.toRecord(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(SELECT_METADATA, [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(SELECT_STREAM_INFO, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!info) return null;
+    if (info.storage_backend === "object_storage")
+      throw this.tieredWithoutStorage(id, info.object_storage_key);
+    const totalSize = info.size_bytes;
+    const start = opts.range?.start ?? 0;
+    const end = Math.min(opts.range?.end ?? totalSize - 1, totalSize - 1);
+    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(SELECT_CHUNK, [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;
+    try {
+      const row = await this.run(
+        "delete",
+        connection,
+        async (q) => (await q.query(DELETE_RETURNING, [id])).rows[0]
+      );
+      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 [];
+    try {
+      const rows = await this.run(
+        "delete_many",
+        connection,
+        async (q) => (await q.query(DELETE_MANY, [valid])).rows
+      );
+      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(EXISTS, [id])).rowCount ?? 0) > 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", exc);
+    }
+  }
+  // ---- helpers ---------------------------------------------------------
+  toRecord(row, id) {
+    if (row.storage_backend === "object_storage")
+      throw this.tieredWithoutStorage(id, row.object_storage_key);
+    return {
+      id: String(row.id),
+      data: row.data,
+      mimeType: row.mime_type,
+      originalFilename: row.original_filename,
+      sizeBytes: row.size_bytes,
+      width: row.width,
+      height: row.height,
+      checksumSha256: row.checksum_sha256
+    };
+  }
+  tieredWithoutStorage(id, key) {
+    return new StorageError(
+      `Image ${JSON.stringify(id)} is stored in object storage (key=${JSON.stringify(key)}) but object-storage tiering is not available in this version of the npm package yet. Read it from the Python package (configured with the same bucket), or wait for npm tiering support.`
+    );
+  }
+};
+function rowParams(r) {
+  return [
+    r.data,
+    r.mimeType,
+    r.originalFilename,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    r.checksumSha256
+  ];
+}
+function wrap(prefix, exc) {
+  return exc instanceof StorageError ? exc : new StorageError(`${prefix}: ${msg(exc)}`, { cause: exc });
+}
+function msg(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// 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 = {}) {
+    this.backend = options.backend ?? 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
+    });
+    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_crypto.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 mapLimit(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
+    }));
+  }
+  /** 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 mapLimit(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/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,
+  PDFValidator,
+  PostgresBackend,
+  SUPPORTED_FORMATS,
+  StorageError,
+  UnsupportedFormatError,
+  ZeroBucket,
+  ZeroBucketError,
+  optimizeImage,
+  readInput,
+  validateImage
+});
+//# sourceMappingURL=index.cjs.map