@lens-image/core 0.1.0

package/dist/esm/adapters/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEhG,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,uBAAuB;AACvB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,YAAW,cAAc;;IAClD,QAAQ,CAAC,IAAI,YAAY;gBAOb,OAAO,GAAE,oBAAyB;IAKxC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA4BvE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI3B,kCAAkC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIzC,4CAA4C;IAC5C,IAAI,IAAI,MAAM,EAAE;IAIhB,gCAAgC;IAChC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mEAAmE;IACnE,KAAK,IAAI,IAAI;CAId"}

package/dist/esm/adapters/memory.js

@@ -0,0 +1,80 @@
+/**
+ * An in-memory {@link StorageAdapter}.
+ *
+ * Ships in core on purpose: it is the reference implementation of the adapter
+ * contract (about 40 lines of real logic), and it makes every example in the
+ * README runnable without credentials or a filesystem.
+ */
+/**
+ * @example
+ * ```ts
+ * const adapter = new MemoryAdapter();
+ * const optimizer = new ImageOptimizer({ adapter });
+ *
+ * await optimizer.optimize({ source: './photo.jpg', formats: ['webp'] });
+ * adapter.keys();            // ['a1b2c3d4e5/photo-original.webp']
+ * adapter.get(key)?.data;    // the encoded bytes
+ * ```
+ */
+export class MemoryAdapter {
+    name = 'memory';
+    #files = new Map();
+    #baseUrl;
+    #failAttempts;
+    #attempts = new Map();
+    constructor(options = {}) {
+        this.#baseUrl = options.baseUrl ?? 'memory://';
+        this.#failAttempts = options.failAttempts ?? 0;
+    }
+    async upload(file, _ctx) {
+        const seen = (this.#attempts.get(file.key) ?? 0) + 1;
+        this.#attempts.set(file.key, seen);
+        if (seen <= this.#failAttempts) {
+            // Shaped like a transient network error so the default retry predicate
+            // treats it as retryable.
+            const error = new Error(`Simulated transient failure ${seen}/${this.#failAttempts}`);
+            error.code = 'ECONNRESET';
+            throw error;
+        }
+        this.#files.set(file.key, {
+            key: file.key,
+            data: file.data,
+            contentType: file.contentType,
+            ...(file.cacheControl ? { cacheControl: file.cacheControl } : {}),
+            ...(file.metadata ? { metadata: file.metadata } : {}),
+        });
+        return {
+            key: file.key,
+            url: this.getUrl(file.key),
+            size: file.data.byteLength,
+            ...(file.checksum ? { etag: file.checksum } : {}),
+        };
+    }
+    async exists(key) {
+        return this.#files.has(key);
+    }
+    async remove(key) {
+        this.#files.delete(key);
+    }
+    getUrl(key) {
+        return `${this.#baseUrl}${key}`;
+    }
+    /** Reads back a stored object. */
+    get(key) {
+        return this.#files.get(key);
+    }
+    /** Every stored key, in insertion order. */
+    keys() {
+        return [...this.#files.keys()];
+    }
+    /** Number of stored objects. */
+    get size() {
+        return this.#files.size;
+    }
+    /** Drops every object and resets the injected-failure counters. */
+    clear() {
+        this.#files.clear();
+        this.#attempts.clear();
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/esm/adapters/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/adapters/memory.ts"],"names":[],"mappings":"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"}

package/dist/esm/browser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `@lens-image/core/browser` - the part of Lens that runs anywhere.
+ *
+ * Everything re-exported here is pure computation over bytes and strings, with
+ * no `node:` imports at all. It works in a browser, a Worker, an edge runtime
+ * or React Native.
+ *
+ * ### Why this exists
+ *
+ * The main entry point imports `node:crypto` and `node:fs`, so a bundler
+ * targeting the browser either fails or ships a polyfill for them. But the
+ * *useful* half for a client is Node-free: you can identify an image and read
+ * its dimensions from its first few kilobytes, which means you can reject a
+ * 40,000 x 40,000 PNG **before** uploading it rather than after.
+ *
+ * @example Validate before the upload starts
+ * ```ts
+ * import { sniff, resolveValidation, validateImage, LensError } from '@lens-image/core/browser';
+ *
+ * const policy = resolveValidation({ maxBytes: 10_000_000, allowedFormats: ['jpeg', 'png', 'webp'] });
+ * const header = new Uint8Array(await file.slice(0, 4096).arrayBuffer());
+ *
+ * try {
+ *   validateImage({ ...sniff(header, file.size) }, policy, file.name);
+ * } catch (error) {
+ *   if (LensError.is(error)) showToast(error.message);   // the same message the server would give
+ * }
+ * ```
+ *
+ * Note the `file.slice(0, 4096)` - only the header is read, so validating a
+ * 40 MB file costs 4 KB.
+ *
+ * @packageDocumentation
+ */
+export { sniff, sniffFormat, mimeTypeFor, extensionFor, SNIFF_HEADER_BYTES } from './sniff.js';
+export { validateImage, resolveValidation, DEFAULT_MAX_BYTES, DEFAULT_MAX_PIXELS, DEFAULT_ALLOWED_FORMATS, } from './validation.js';
+export type { ResolvedValidation } from './validation.js';
+export { LensError } from './errors.js';
+export type { LensErrorCode, LensErrorDetails } from './errors.js';
+export { normalizeFormat, normalizeFormats, supportsAlpha, isLossy, defaultQuality, defaultEffort, ENCODABLE_FORMATS, } from './format.js';
+export { buildKey, joinKey, slugify, defaultLabel, DEFAULT_KEY_TEMPLATE } from './naming.js';
+export { buildSrcset, toPicture, pickVariant } from './srcset.js';
+export type { PictureData, PictureSource } from './srcset.js';
+export { formatBytes } from './bytes.js';
+export type { DetectedFormat, FitMode, FormatResult, ImageFormat, ImageFormatInput, ImageMetadata, KeyContext, LensWarning, OptimizeResult, Position, ResizeSpec, SizeSpec, ValidationOptions, Variant, } from './types.js';
+//# sourceMappingURL=browser.d.ts.map

package/dist/esm/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAG/F,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,OAAO,EACP,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAG7F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,YAAY,EACV,cAAc,EACd,OAAO,EACP,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,OAAO,GACR,MAAM,YAAY,CAAC"}

package/dist/esm/browser.js

@@ -0,0 +1,49 @@
+/**
+ * `@lens-image/core/browser` - the part of Lens that runs anywhere.
+ *
+ * Everything re-exported here is pure computation over bytes and strings, with
+ * no `node:` imports at all. It works in a browser, a Worker, an edge runtime
+ * or React Native.
+ *
+ * ### Why this exists
+ *
+ * The main entry point imports `node:crypto` and `node:fs`, so a bundler
+ * targeting the browser either fails or ships a polyfill for them. But the
+ * *useful* half for a client is Node-free: you can identify an image and read
+ * its dimensions from its first few kilobytes, which means you can reject a
+ * 40,000 x 40,000 PNG **before** uploading it rather than after.
+ *
+ * @example Validate before the upload starts
+ * ```ts
+ * import { sniff, resolveValidation, validateImage, LensError } from '@lens-image/core/browser';
+ *
+ * const policy = resolveValidation({ maxBytes: 10_000_000, allowedFormats: ['jpeg', 'png', 'webp'] });
+ * const header = new Uint8Array(await file.slice(0, 4096).arrayBuffer());
+ *
+ * try {
+ *   validateImage({ ...sniff(header, file.size) }, policy, file.name);
+ * } catch (error) {
+ *   if (LensError.is(error)) showToast(error.message);   // the same message the server would give
+ * }
+ * ```
+ *
+ * Note the `file.slice(0, 4096)` - only the header is read, so validating a
+ * 40 MB file costs 4 KB.
+ *
+ * @packageDocumentation
+ */
+// --- Format detection -------------------------------------------------------
+export { sniff, sniffFormat, mimeTypeFor, extensionFor, SNIFF_HEADER_BYTES } from './sniff.js';
+// --- Validation -------------------------------------------------------------
+export { validateImage, resolveValidation, DEFAULT_MAX_BYTES, DEFAULT_MAX_PIXELS, DEFAULT_ALLOWED_FORMATS, } from './validation.js';
+// --- Errors -----------------------------------------------------------------
+export { LensError } from './errors.js';
+// --- Formats ----------------------------------------------------------------
+export { normalizeFormat, normalizeFormats, supportsAlpha, isLossy, defaultQuality, defaultEffort, ENCODABLE_FORMATS, } from './format.js';
+// --- Key templating ---------------------------------------------------------
+export { buildKey, joinKey, slugify, defaultLabel, DEFAULT_KEY_TEMPLATE } from './naming.js';
+// --- HTML helpers -----------------------------------------------------------
+export { buildSrcset, toPicture, pickVariant } from './srcset.js';
+// --- Formatting -------------------------------------------------------------
+export { formatBytes } from './bytes.js';
+//# sourceMappingURL=browser.js.map

package/dist/esm/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,+EAA+E;AAC/E,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE/F,+EAA+E;AAC/E,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,+EAA+E;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,+EAA+E;AAC/E,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,OAAO,EACP,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE7F,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGlE,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/bytes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Byte formatting.
+ *
+ * Its own module so that `validation.ts` - and therefore the whole `./browser`
+ * entry point - does not have to import `source.ts`, which pulls in `node:fs`
+ * and `node:path` at the top level.
+ */
+/**
+ * Human-readable byte count, using binary units.
+ *
+ * @example
+ * ```ts
+ * formatBytes(900);       // '900 B'
+ * formatBytes(5_242_880); // '5.0 MiB'
+ * ```
+ */
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/esm/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/dist/esm/bytes.js

@@ -0,0 +1,28 @@
+/**
+ * Byte formatting.
+ *
+ * Its own module so that `validation.ts` - and therefore the whole `./browser`
+ * entry point - does not have to import `source.ts`, which pulls in `node:fs`
+ * and `node:path` at the top level.
+ */
+/**
+ * Human-readable byte count, using binary units.
+ *
+ * @example
+ * ```ts
+ * formatBytes(900);       // '900 B'
+ * formatBytes(5_242_880); // '5.0 MiB'
+ * ```
+ */
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return '0 B';
+    if (bytes < 1024)
+        return `${Math.round(bytes)} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+}
+//# sourceMappingURL=bytes.js.map

package/dist/esm/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../src/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACvD,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;IAClD,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IACnE,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IACnF,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAC5D,CAAC"}

package/dist/esm/cache.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Result caching.
+ *
+ * The expensive part of an optimize run is the encode, and the result is a pure
+ * function of (source bytes, options). So the cache key is a hash of both, and
+ * a hit skips encoding *and* uploading entirely.
+ *
+ * Three strategies, in increasing order of how much they trust the world:
+ *
+ * - `'memory'` - process-lifetime LRU. Fast, but a fresh deploy starts cold and
+ *   a second instance does the work again.
+ * - `'storage'` - memory, plus `adapter.exists()` so a warm bucket short-circuits
+ *   a cold process.
+ * - a {@link CacheStore} - your own Redis/SQLite, shared across instances.
+ */
+import type { CacheStore, OptimizeResult } from './types.js';
+/**
+ * A bounded LRU map.
+ *
+ * Insertion-ordered `Map` iteration gives us the eviction order for free: the
+ * first key `keys().next()` yields is the least recently used, because reads
+ * re-insert.
+ */
+export declare class MemoryCacheStore implements CacheStore {
+    #private;
+    /** @param max - Entries to keep before evicting the least recently used. */
+    constructor(max?: number);
+    get(key: string): OptimizeResult | undefined;
+    set(key: string, value: OptimizeResult): void;
+    delete(key: string): void;
+    /** Drops every entry. */
+    clear(): void;
+    /** Current entry count. Handy in tests and metrics. */
+    get size(): number;
+}
+/**
+ * A cache store that never stores anything.
+ *
+ * Lets the optimizer treat "caching off" as just another store, rather than
+ * branching on null at every call site.
+ */
+export declare const nullCacheStore: CacheStore;
+//# sourceMappingURL=cache.d.ts.map

package/dist/esm/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,UAAU;;IAIjD,4EAA4E;gBAChE,GAAG,SAAM;IAIrB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAS5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI;IAW7C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,yBAAyB;IACzB,KAAK,IAAI,IAAI;IAIb,uDAAuD;IACvD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,UAI5B,CAAC"}

package/dist/esm/cache.js

@@ -0,0 +1,73 @@
+/**
+ * Result caching.
+ *
+ * The expensive part of an optimize run is the encode, and the result is a pure
+ * function of (source bytes, options). So the cache key is a hash of both, and
+ * a hit skips encoding *and* uploading entirely.
+ *
+ * Three strategies, in increasing order of how much they trust the world:
+ *
+ * - `'memory'` - process-lifetime LRU. Fast, but a fresh deploy starts cold and
+ *   a second instance does the work again.
+ * - `'storage'` - memory, plus `adapter.exists()` so a warm bucket short-circuits
+ *   a cold process.
+ * - a {@link CacheStore} - your own Redis/SQLite, shared across instances.
+ */
+/**
+ * A bounded LRU map.
+ *
+ * Insertion-ordered `Map` iteration gives us the eviction order for free: the
+ * first key `keys().next()` yields is the least recently used, because reads
+ * re-insert.
+ */
+export class MemoryCacheStore {
+    #entries = new Map();
+    #max;
+    /** @param max - Entries to keep before evicting the least recently used. */
+    constructor(max = 500) {
+        this.#max = Math.max(1, Math.floor(max));
+    }
+    get(key) {
+        const value = this.#entries.get(key);
+        if (value === undefined)
+            return undefined;
+        // Re-insert to mark as most recently used.
+        this.#entries.delete(key);
+        this.#entries.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        if (this.#entries.has(key))
+            this.#entries.delete(key);
+        this.#entries.set(key, value);
+        while (this.#entries.size > this.#max) {
+            const oldest = this.#entries.keys().next();
+            if (oldest.done)
+                break;
+            this.#entries.delete(oldest.value);
+        }
+    }
+    delete(key) {
+        this.#entries.delete(key);
+    }
+    /** Drops every entry. */
+    clear() {
+        this.#entries.clear();
+    }
+    /** Current entry count. Handy in tests and metrics. */
+    get size() {
+        return this.#entries.size;
+    }
+}
+/**
+ * A cache store that never stores anything.
+ *
+ * Lets the optimizer treat "caching off" as just another store, rather than
+ * branching on null at every call site.
+ */
+export const nullCacheStore = {
+    get: () => undefined,
+    set: () => undefined,
+    delete: () => undefined,
+};
+//# sourceMappingURL=cache.js.map

package/dist/esm/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAClB,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC7C,IAAI,CAAS;IAEtB,4EAA4E;IAC5E,YAAY,GAAG,GAAG,GAAG;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,2CAA2C;QAC3C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAqB;QACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE9B,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,MAAM,CAAC,IAAI;gBAAE,MAAM;YACvB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,yBAAyB;IACzB,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,uDAAuD;IACvD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS;CACxB,CAAC"}

package/dist/esm/concurrency.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A ~40-line replacement for `p-map` / `p-limit`.
+ *
+ * Unbounded `Promise.all` over image encodes is how you turn a 12-variant
+ * upload into an out-of-memory crash: sharp holds the full decoded bitmap per
+ * in-flight job, so twelve 4K photos is several gigabytes of RSS.
+ */
+/** Outcome of one task in a {@link mapLimit} run. */
+export type Settled<T> = {
+    readonly status: 'fulfilled';
+    readonly value: T;
+    readonly index: number;
+} | {
+    readonly status: 'rejected';
+    readonly reason: unknown;
+    readonly index: number;
+};
+/**
+ * Runs `worker` over `items` with at most `limit` in flight, preserving input
+ * order in the output.
+ *
+ * Unlike `Promise.all`, one rejection does not discard the work that succeeded:
+ * every task settles and you get a per-item verdict. That is what makes
+ * "the AVIF encoder died but the WebP is fine" a warning instead of a failure.
+ *
+ * @example
+ * ```ts
+ * const results = await mapLimit(variants, 4, (v) => encodeAndUpload(v));
+ * const ok = results.filter((r) => r.status === 'fulfilled');
+ * ```
+ */
+export declare function mapLimit<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>, signal?: AbortSignal): Promise<Settled<R>[]>;
+/** Sleep that rejects promptly when the signal fires, instead of after the delay. */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/esm/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,qDAAqD;AACrD,MAAM,MAAM,OAAO,CAAC,CAAC,IACjB;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAkCvB;AAED,qFAAqF;AACrF,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBrE"}

package/dist/esm/concurrency.js

@@ -0,0 +1,78 @@
+/**
+ * A ~40-line replacement for `p-map` / `p-limit`.
+ *
+ * Unbounded `Promise.all` over image encodes is how you turn a 12-variant
+ * upload into an out-of-memory crash: sharp holds the full decoded bitmap per
+ * in-flight job, so twelve 4K photos is several gigabytes of RSS.
+ */
+import { LensError, throwIfAborted } from './errors.js';
+/**
+ * Runs `worker` over `items` with at most `limit` in flight, preserving input
+ * order in the output.
+ *
+ * Unlike `Promise.all`, one rejection does not discard the work that succeeded:
+ * every task settles and you get a per-item verdict. That is what makes
+ * "the AVIF encoder died but the WebP is fine" a warning instead of a failure.
+ *
+ * @example
+ * ```ts
+ * const results = await mapLimit(variants, 4, (v) => encodeAndUpload(v));
+ * const ok = results.filter((r) => r.status === 'fulfilled');
+ * ```
+ */
+export async function mapLimit(items, limit, worker, signal) {
+    if (items.length === 0)
+        return [];
+    const size = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));
+    const results = new Array(items.length);
+    let cursor = 0;
+    const runners = Array.from({ length: size }, async () => {
+        for (;;) {
+            const index = cursor++;
+            if (index >= items.length)
+                return;
+            // Stop handing out work once aborted, but let in-flight tasks settle so
+            // adapters get a chance to clean up rather than being orphaned.
+            if (signal?.aborted) {
+                results[index] = {
+                    status: 'rejected',
+                    index,
+                    reason: new LensError('ABORTED', 'Task was skipped because the run was aborted.'),
+                };
+                continue;
+            }
+            try {
+                results[index] = { status: 'fulfilled', value: await worker(items[index], index), index };
+            }
+            catch (reason) {
+                results[index] = { status: 'rejected', reason, index };
+            }
+        }
+    });
+    await Promise.all(runners);
+    throwIfAborted(signal, 'run');
+    return results;
+}
+/** Sleep that rejects promptly when the signal fires, instead of after the delay. */
+export function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new LensError('ABORTED', 'Delay was aborted.'));
+            return;
+        }
+        // Deliberately NOT unref'd. A pending retry backoff is real outstanding
+        // work: unref-ing it lets Node drain the event loop and exit (or a test
+        // runner declare the turn over) while an upload is still waiting to be
+        // retried, silently dropping it.
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(new LensError('ABORTED', 'Delay was aborted.'));
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/esm/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAOxD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAmB,EACnB,KAAa,EACb,MAA8C,EAC9C,MAAoB;IAEpB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,IAAI,KAAK,CAAa,KAAK,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE;QACtD,SAAS,CAAC;YACR,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC;YACvB,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO;YAElC,wEAAwE;YACxE,gEAAgE;YAChE,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,OAAO,CAAC,KAAK,CAAC,GAAG;oBACf,MAAM,EAAE,UAAU;oBAClB,KAAK;oBACL,MAAM,EAAE,IAAI,SAAS,CAAC,SAAS,EAAE,+CAA+C,CAAC;iBAClF,CAAC;gBACF,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;YACjG,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACzD,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,SAAS,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC;YACvD,OAAO;QACT,CAAC;QACD,wEAAwE;QACxE,wEAAwE;QACxE,uEAAuE;QACvE,iCAAiC;QACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QAEP,SAAS,OAAO;YACd,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,IAAI,SAAS,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/engines/index.d.ts

@@ -0,0 +1,20 @@
+/** Engine selection. */
+import type { ImageEngine } from './../types.js';
+export { createSharpEngine, resetSharpCache, type SharpEngineOptions } from './sharp.js';
+export { createPassthroughEngine, type PassthroughEngineOptions } from './passthrough.js';
+/**
+ * Picks the best engine available in this process.
+ *
+ * Returns the sharp engine when sharp can be imported, otherwise the
+ * passthrough engine. Detection happens once and is memoised - an optimizer
+ * constructed at module scope should not pay for a dynamic import on every call.
+ *
+ * Note that the passthrough fallback is not silent: it throws a message naming
+ * sharp the first time you ask it to actually resize something. The goal is
+ * that "I forgot to install sharp" surfaces as one clear error rather than as
+ * mysteriously unprocessed images.
+ */
+export declare function detectEngine(): Promise<ImageEngine>;
+/** Test seam: forget the memoised engine detection. */
+export declare function resetEngineDetection(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/engines/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engines/index.ts"],"names":[],"mappings":"AAAA,wBAAwB;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,uBAAuB,EAAE,KAAK,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAI1F;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC,CAMzD;AAED,uDAAuD;AACvD,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/esm/engines/index.js

@@ -0,0 +1,30 @@
+/** Engine selection. */
+import { createPassthroughEngine } from './passthrough.js';
+import { createSharpEngine } from './sharp.js';
+export { createSharpEngine, resetSharpCache } from './sharp.js';
+export { createPassthroughEngine } from './passthrough.js';
+let detected;
+/**
+ * Picks the best engine available in this process.
+ *
+ * Returns the sharp engine when sharp can be imported, otherwise the
+ * passthrough engine. Detection happens once and is memoised - an optimizer
+ * constructed at module scope should not pay for a dynamic import on every call.
+ *
+ * Note that the passthrough fallback is not silent: it throws a message naming
+ * sharp the first time you ask it to actually resize something. The goal is
+ * that "I forgot to install sharp" surfaces as one clear error rather than as
+ * mysteriously unprocessed images.
+ */
+export async function detectEngine() {
+    detected ??= (async () => {
+        const sharp = createSharpEngine();
+        return (await sharp.supports('webp')) ? sharp : createPassthroughEngine();
+    })();
+    return detected;
+}
+/** Test seam: forget the memoised engine detection. */
+export function resetEngineDetection() {
+    detected = undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/engines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engines/index.ts"],"names":[],"mappings":"AAAA,wBAAwB;AAExB,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAA2B,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,uBAAuB,EAAiC,MAAM,kBAAkB,CAAC;AAE1F,IAAI,QAA0C,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,QAAQ,KAAK,CAAC,KAAK,IAAI,EAAE;QACvB,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,uBAAuB,EAAE,CAAC;IAC5E,CAAC,CAAC,EAAE,CAAC;IACL,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,oBAAoB;IAClC,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC"}

package/dist/esm/engines/passthrough.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A codec-free {@link ImageEngine}.
+ *
+ * It cannot resize or transcode - it has no decoder. What it *can* do is read
+ * dimensions from the header and hand the original bytes back unchanged, which
+ * covers three real cases:
+ *
+ * 1. **Tests.** Deterministic, instant, no native binary in CI.
+ * 2. **Store-only pipelines.** Validate, content-hash, key and upload an image
+ *    without re-encoding it.
+ * 3. **Graceful degradation.** When sharp is missing, the optimizer can still
+ *    store the original rather than failing the whole request - the user's
+ *    upload survives, just unoptimised.
+ */
+import type { ImageEngine } from './../types.js';
+/** Options for {@link createPassthroughEngine}. */
+export interface PassthroughEngineOptions {
+    /**
+     * What to do when asked for work it cannot do.
+     *
+     * - `'throw'` (default) - a clear `ENCODE_FAILED`, so the optimizer records a
+     *   warning and moves to the next format.
+     * - `'ignore'` - return the original bytes with their true dimensions. Honest
+     *   about what happened, because the result reports the real output size.
+     */
+    readonly onUnsupported?: 'throw' | 'ignore';
+}
+/**
+ * Creates the passthrough engine.
+ *
+ * @example
+ * ```ts
+ * // Validate and store originals, no codec required.
+ * const optimizer = new ImageOptimizer({
+ *   engine: createPassthroughEngine(),
+ *   adapter: new LocalAdapter({ root: './uploads' }),
+ * });
+ * ```
+ */
+export declare function createPassthroughEngine(options?: PassthroughEngineOptions): ImageEngine;
+//# sourceMappingURL=passthrough.d.ts.map

package/dist/esm/engines/passthrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passthrough.d.ts","sourceRoot":"","sources":["../../../src/engines/passthrough.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAgB,WAAW,EAA2C,MAAM,eAAe,CAAC;AAExG,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,WAAW,CA4C3F"}