@lens-image/core 0.1.0

package/dist/cjs/engines/sharp.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * The sharp-backed {@link ImageEngine}.
+ *
+ * ### Why this is not a dependency
+ *
+ * `@lens-image/core` declares sharp as an *optional peer*. Nothing in this file is
+ * evaluated until you actually call the engine, and the import is dynamic, so
+ * `npm install @lens-image/core` pulls in zero packages and installs zero native
+ * binaries. If you never resize an image - you only validate and re-key, say -
+ * you never need sharp at all.
+ *
+ * The moment you do need it, you run `npm install sharp` yourself, which means
+ * the native binary, its platform matrix and its release cadence are all
+ * visible in *your* lockfile rather than smuggled in under ours.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSharpEngine = createSharpEngine;
+exports.resetSharpCache = resetSharpCache;
+const errors_js_1 = require("./../errors.js");
+const format_js_1 = require("./../format.js");
+/**
+ * Formats whose capability is reported under a different key.
+ *
+ * sharp reports support per *container*, and AVIF is not one of its containers:
+ * AVIF is HEIF with AV1 compression, so `sharp.format.avif` is `undefined` even
+ * on builds that encode AVIF perfectly well. Checking only the literal name
+ * makes every AVIF request degrade to JPEG for no reason - the exact failure
+ * the fallback exists to handle, triggered by a bug rather than a real
+ * limitation.
+ *
+ * The first entry that reports an encoder wins.
+ */
+const CAPABILITY_KEYS = {
+    avif: ['avif', 'heif'],
+};
+let cached;
+/**
+ * Resolves sharp, memoising both success and failure.
+ *
+ * The error message is the one a developer will actually read when their
+ * deploy breaks, so it says what to install rather than echoing
+ * `ERR_MODULE_NOT_FOUND`.
+ */
+async function loadSharp() {
+    cached ??= (async () => {
+        try {
+            // The template literal defeats bundler static analysis, so tools like
+            // webpack and esbuild do not try to resolve sharp at build time in
+            // projects that never use it.
+            const specifier = 'sharp';
+            const mod = (await Promise.resolve(`${`${specifier}`}`).then(s => __importStar(require(s))));
+            return ('default' in mod ? mod.default : mod);
+        }
+        catch (error) {
+            throw new errors_js_1.LensError('ENGINE_UNAVAILABLE', 'Image processing needs sharp, which is not installed. Run `npm install sharp`. ' +
+                'It is an optional peer dependency of @lens-image/core so that installing the core ' +
+                'library never pulls in a native binary you might not need.', { cause: error, details: { engine: 'sharp' } });
+        }
+    })();
+    return cached;
+}
+/**
+ * Creates an {@link ImageEngine} backed by sharp.
+ *
+ * @example
+ * ```ts
+ * const optimizer = new ImageOptimizer({
+ *   engine: createSharpEngine({ threads: 1 }),  // we do our own parallelism
+ *   adapter,
+ * });
+ * ```
+ */
+function createSharpEngine(options = {}) {
+    const { cache = false, threads, pixelLimit = 100_000_000, animated = false } = options;
+    let configured = false;
+    async function sharp() {
+        const mod = await loadSharp();
+        if (!configured) {
+            configured = true;
+            mod.cache?.(cache);
+            if (threads !== undefined)
+                mod.concurrency?.(threads);
+        }
+        return mod;
+    }
+    return {
+        name: 'sharp',
+        async supports(format) {
+            try {
+                const mod = await sharp();
+                // Capability depends on how libvips was built - AVIF in particular is
+                // missing from some prebuilt binaries - so this asks sharp rather than
+                // assuming. See CAPABILITY_KEYS for why the name is not always literal.
+                const keys = CAPABILITY_KEYS[format] ?? [format];
+                return keys.some((key) => Boolean(mod.format[key]?.output));
+            }
+            catch {
+                return false;
+            }
+        },
+        async probe(input) {
+            const mod = await sharp();
+            try {
+                const meta = (await mod(input, { limitInputPixels: pixelLimit }).metadata());
+                return {
+                    format: meta.format ?? 'unknown',
+                    width: meta.width ?? 0,
+                    height: meta.height ?? 0,
+                    size: meta.size ?? input.byteLength,
+                    hasAlpha: meta.hasAlpha ?? false,
+                    isAnimated: (meta.pages ?? 1) > 1,
+                    ...(meta.orientation !== undefined ? { orientation: meta.orientation } : {}),
+                    ...(meta.space !== undefined ? { space: meta.space } : {}),
+                };
+            }
+            catch (error) {
+                throw (0, errors_js_1.wrapError)('UNSUPPORTED_INPUT', 'sharp could not read this image', error, {
+                    engine: 'sharp',
+                });
+            }
+        },
+        async transform(input, op) {
+            const mod = await sharp();
+            try {
+                let pipeline = mod(input, { limitInputPixels: pixelLimit, animated });
+                // Auto-orient first: rotating after a resize would resize against the
+                // wrong axis for any photo shot in portrait on a phone.
+                if (op.autoOrient)
+                    pipeline = pipeline.rotate();
+                if (op.resize) {
+                    pipeline = pipeline.resize({
+                        ...(op.resize.width !== undefined ? { width: op.resize.width } : {}),
+                        ...(op.resize.height !== undefined ? { height: op.resize.height } : {}),
+                        fit: op.resize.fit ?? 'cover',
+                        position: op.resize.position ?? 'center',
+                        withoutEnlargement: op.resize.withoutEnlargement ?? true,
+                        ...(op.resize.background ? { background: op.resize.background } : {}),
+                    });
+                }
+                pipeline = pipeline.toFormat(op.format, encoderOptions(op));
+                // sharp strips metadata unless asked; `withMetadata()` keeps EXIF/ICC.
+                if (op.preserveMetadata)
+                    pipeline = pipeline.withMetadata();
+                const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+                return {
+                    data,
+                    format: op.format,
+                    width: info.width,
+                    height: info.height,
+                    size: info.size ?? data.byteLength,
+                };
+            }
+            catch (error) {
+                throw (0, errors_js_1.wrapError)('ENCODE_FAILED', `sharp failed to encode ${op.format}`, error, { engine: 'sharp', format: op.format });
+            }
+        },
+    };
+}
+/** Maps a {@link TransformOp} onto sharp's per-format encoder options. */
+function encoderOptions(op) {
+    const effort = op.effort ?? (0, format_js_1.defaultEffort)(op.format);
+    const base = { quality: op.quality };
+    switch (op.format) {
+        case 'jpeg':
+            return {
+                ...base,
+                progressive: op.progressive ?? true,
+                // 4:4:4 avoids the colour smearing that 4:2:0 causes on saturated reds
+                // and fine text, which is exactly what high-quality output is for.
+                chromaSubsampling: op.chromaSubsampling ?? (op.quality >= 90 ? '4:4:4' : '4:2:0'),
+                mozjpeg: true,
+            };
+        case 'png':
+            return {
+                progressive: op.progressive ?? false,
+                compressionLevel: 9,
+                // Palette quantisation is where PNG size actually comes from; without
+                // it `quality` is ignored entirely and output is often larger than input.
+                palette: true,
+                quality: op.quality,
+                effort: effort ?? 7,
+            };
+        case 'webp':
+            return {
+                ...base,
+                ...(op.lossless !== undefined ? { lossless: op.lossless } : {}),
+                ...(effort !== undefined ? { effort } : {}),
+                smartSubsample: true,
+            };
+        case 'avif':
+            return {
+                ...base,
+                ...(op.lossless !== undefined ? { lossless: op.lossless } : {}),
+                ...(effort !== undefined ? { effort } : {}),
+                chromaSubsampling: op.chromaSubsampling ?? '4:4:4',
+            };
+        case 'gif':
+            return { ...(effort !== undefined ? { effort } : {}) };
+        case 'tiff':
+            return { ...base, compression: 'lzw' };
+        default:
+            return base;
+    }
+}
+/** Test seam: forget the memoised sharp module. */
+function resetSharpCache() {
+    cached = undefined;
+}
+//# sourceMappingURL=sharp.js.map

package/dist/cjs/engines/sharp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharp.js","sourceRoot":"","sources":["../../../src/engines/sharp.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8GH,8CAuGC;AAmDD,0CAEC;AAxQD,8CAAsD;AACtD,8CAA+C;AAoB/C;;;;;;;;;;;GAWG;AACH,MAAM,eAAe,GAAoD;IACvE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,IAAI,MAAwC,CAAC;AAE7C;;;;;;GAMG;AACH,KAAK,UAAU,SAAS;IACtB,MAAM,KAAK,CAAC,KAAK,IAAI,EAAE;QACrB,IAAI,CAAC;YACH,sEAAsE;YACtE,mEAAmE;YACnE,8BAA8B;YAC9B,MAAM,SAAS,GAAG,OAAO,CAAC;YAC1B,MAAM,GAAG,GAAG,CAAC,yBAAgC,GAAG,SAAS,EAAE,uCAAC,CAEhC,CAAC;YAC7B,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAgB,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,qBAAS,CACjB,oBAAoB,EACpB,iFAAiF;gBAC/E,oFAAoF;gBACpF,4DAA4D,EAC9D,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,CAC/C,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IACL,OAAO,MAAM,CAAC;AAChB,CAAC;AA6BD;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAAC,UAA8B,EAAE;IAChE,MAAM,EAAE,KAAK,GAAG,KAAK,EAAE,OAAO,EAAE,UAAU,GAAG,WAAW,EAAE,QAAQ,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IACvF,IAAI,UAAU,GAAG,KAAK,CAAC;IAEvB,KAAK,UAAU,KAAK;QAClB,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,UAAU,GAAG,IAAI,CAAC;YAClB,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;YACnB,IAAI,OAAO,KAAK,SAAS;gBAAE,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO;QACL,IAAI,EAAE,OAAO;QAEb,KAAK,CAAC,QAAQ,CAAC,MAAmB;YAChC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,KAAK,EAAE,CAAC;gBAC1B,sEAAsE;gBACtE,uEAAuE;gBACvE,wEAAwE;gBACxE,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACjD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;YAC9D,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,KAAiB;YAC3B,MAAM,GAAG,GAAG,MAAM,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,CAAC,QAAQ,EAAE,CAS1E,CAAC;gBACF,OAAO;oBACL,MAAM,EAAG,IAAI,CAAC,MAAkC,IAAI,SAAS;oBAC7D,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC;oBACtB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC;oBACxB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,UAAU;oBACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK;oBAChC,UAAU,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC;oBACjC,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC5E,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC3D,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAA,qBAAS,EAAC,mBAAmB,EAAE,iCAAiC,EAAE,KAAK,EAAE;oBAC7E,MAAM,EAAE,OAAO;iBAChB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,KAAiB,EAAE,EAAe;YAChD,MAAM,GAAG,GAAG,MAAM,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,IAAI,QAAQ,GAAG,GAAG,CAAC,KAAK,EAAE,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;gBAEtE,sEAAsE;gBACtE,wDAAwD;gBACxD,IAAI,EAAE,CAAC,UAAU;oBAAE,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAEhD,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;oBACd,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC;wBACzB,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACpE,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACvE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,OAAO;wBAC7B,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,IAAI,QAAQ;wBACxC,kBAAkB,EAAE,EAAE,CAAC,MAAM,CAAC,kBAAkB,IAAI,IAAI;wBACxD,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBACtE,CAAC,CAAC;gBACL,CAAC;gBAED,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC;gBAE5D,uEAAuE;gBACvE,IAAI,EAAE,CAAC,gBAAgB;oBAAE,QAAQ,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;gBAE5D,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC5E,OAAO;oBACL,IAAI;oBACJ,MAAM,EAAE,EAAE,CAAC,MAAM;oBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU;iBACnC,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAA,qBAAS,EACb,eAAe,EACf,0BAA0B,EAAE,CAAC,MAAM,EAAE,EACrC,KAAK,EACL,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CACvC,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAS,cAAc,CAAC,EAAe;IACrC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,IAAI,IAAA,yBAAa,EAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IACrD,MAAM,IAAI,GAA4B,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC;IAE9D,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC;QAClB,KAAK,MAAM;YACT,OAAO;gBACL,GAAG,IAAI;gBACP,WAAW,EAAE,EAAE,CAAC,WAAW,IAAI,IAAI;gBACnC,uEAAuE;gBACvE,mEAAmE;gBACnE,iBAAiB,EAAE,EAAE,CAAC,iBAAiB,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;gBACjF,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,KAAK,KAAK;YACR,OAAO;gBACL,WAAW,EAAE,EAAE,CAAC,WAAW,IAAI,KAAK;gBACpC,gBAAgB,EAAE,CAAC;gBACnB,sEAAsE;gBACtE,0EAA0E;gBAC1E,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,EAAE,CAAC,OAAO;gBACnB,MAAM,EAAE,MAAM,IAAI,CAAC;aACpB,CAAC;QACJ,KAAK,MAAM;YACT,OAAO;gBACL,GAAG,IAAI;gBACP,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,cAAc,EAAE,IAAI;aACrB,CAAC;QACJ,KAAK,MAAM;YACT,OAAO;gBACL,GAAG,IAAI;gBACP,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,iBAAiB,EAAE,EAAE,CAAC,iBAAiB,IAAI,OAAO;aACnD,CAAC;QACJ,KAAK,KAAK;YACR,OAAO,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QACzD,KAAK,MAAM;YACT,OAAO,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QACzC;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,SAAgB,eAAe;IAC7B,MAAM,GAAG,SAAS,CAAC;AACrB,CAAC"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Error taxonomy.
+ *
+ * Every error Lens throws is a {@link LensError} with a stable `code`, so you
+ * can branch on failure without string-matching messages. Messages are written
+ * for the developer reading a stack trace at 2am: they say what was expected,
+ * what happened, and what to do about it.
+ */
+import type { DetectedFormat, ImageFormat } from './types.js';
+/** Stable, machine-readable failure codes. */
+export type LensErrorCode = 
+/** The `source` value was not a shape Lens understands. */
+'INVALID_SOURCE'
+/** The file could not be read from disk or the network. */
+ | 'SOURCE_UNREADABLE'
+/** Bytes were read but are not a recognisable image. */
+ | 'UNSUPPORTED_INPUT'
+/** Input failed a `validate` rule (size, dimensions, format allowlist). */
+ | 'VALIDATION_FAILED'
+/** No codec is available to do the work. Usually: sharp is not installed. */
+ | 'ENGINE_UNAVAILABLE'
+/** The codec threw while encoding. */
+ | 'ENCODE_FAILED'
+/** Every requested format failed, including the fallback. */
+ | 'ALL_FORMATS_FAILED'
+/** The storage adapter threw, after exhausting retries. */
+ | 'UPLOAD_FAILED'
+/** An adapter was required for the operation but none was configured. */
+ | 'ADAPTER_REQUIRED'
+/** The adapter does not implement an optional method this call needed. */
+ | 'ADAPTER_UNSUPPORTED'
+/** Adapter constructor received bad or missing configuration. */
+ | 'ADAPTER_MISCONFIGURED'
+/** The caller's `AbortSignal` fired. */
+ | 'ABORTED'
+/** Option values were contradictory or out of range. */
+ | 'INVALID_OPTIONS';
+/** Extra context carried on a {@link LensError}. */
+export interface LensErrorDetails {
+    readonly format?: ImageFormat;
+    readonly detected?: DetectedFormat;
+    readonly key?: string;
+    readonly adapter?: string;
+    readonly engine?: string;
+    readonly limit?: number;
+    readonly actual?: number;
+    readonly attempts?: number;
+    readonly [key: string]: unknown;
+}
+/**
+ * Base error for everything this library throws.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await optimizer.optimize({ source: buf });
+ * } catch (err) {
+ *   if (LensError.is(err, 'VALIDATION_FAILED')) return res.status(400).json({ error: err.message });
+ *   throw err;
+ * }
+ * ```
+ */
+export declare class LensError extends Error {
+    /** Stable failure code. Branch on this, not on `message`. */
+    readonly code: LensErrorCode;
+    /** Structured context: limits, keys, formats involved. */
+    readonly details: LensErrorDetails;
+    /** A suggested HTTP status, so route handlers do not have to map codes. */
+    readonly status: number;
+    constructor(code: LensErrorCode, message: string, options?: {
+        cause?: unknown;
+        details?: LensErrorDetails;
+    });
+    /**
+     * Type guard. Pass a `code` to narrow further.
+     *
+     * @example `if (LensError.is(err, 'UPLOAD_FAILED')) ...`
+     */
+    static is(error: unknown, code?: LensErrorCode): error is LensError;
+    /** JSON-safe representation, suitable for logs and API responses. */
+    toJSON(): Record<string, unknown>;
+}
+/** Throws `ABORTED` if the signal has already fired. Cheap enough to call often. */
+export declare function throwIfAborted(signal: AbortSignal | undefined, what?: string): void;
+/**
+ * Wraps a non-Lens error, preserving the original as `cause`.
+ * Existing {@link LensError}s pass through untouched so codes are not lost.
+ */
+export declare function wrapError(code: LensErrorCode, message: string, cause: unknown, details?: LensErrorDetails): LensError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,8CAA8C;AAC9C,MAAM,MAAM,aAAa;AACvB,2DAA2D;AACzD,gBAAgB;AAClB,2DAA2D;GACzD,mBAAmB;AACrB,wDAAwD;GACtD,mBAAmB;AACrB,2EAA2E;GACzE,mBAAmB;AACrB,6EAA6E;GAC3E,oBAAoB;AACtB,sCAAsC;GACpC,eAAe;AACjB,6DAA6D;GAC3D,oBAAoB;AACtB,2DAA2D;GACzD,eAAe;AACjB,yEAAyE;GACvE,kBAAkB;AACpB,0EAA0E;GACxE,qBAAqB;AACvB,iEAAiE;GAC/D,uBAAuB;AACzB,wCAAwC;GACtC,SAAS;AACX,wDAAwD;GACtD,iBAAiB,CAAC;AAEtB,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IAEnC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGtB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;KAAO;IAU/D;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,KAAK,IAAI,SAAS;IAKnE,qEAAqE;IACrE,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC;AAkBD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,SAAc,GAAG,IAAI,CAMxF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,gBAAgB,GACzB,SAAS,CAIX"}

package/dist/cjs/errors.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Error taxonomy.
+ *
+ * Every error Lens throws is a {@link LensError} with a stable `code`, so you
+ * can branch on failure without string-matching messages. Messages are written
+ * for the developer reading a stack trace at 2am: they say what was expected,
+ * what happened, and what to do about it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LensError = void 0;
+exports.throwIfAborted = throwIfAborted;
+exports.wrapError = wrapError;
+/**
+ * Base error for everything this library throws.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await optimizer.optimize({ source: buf });
+ * } catch (err) {
+ *   if (LensError.is(err, 'VALIDATION_FAILED')) return res.status(400).json({ error: err.message });
+ *   throw err;
+ * }
+ * ```
+ */
+class LensError extends Error {
+    /** Stable failure code. Branch on this, not on `message`. */
+    code;
+    /** Structured context: limits, keys, formats involved. */
+    details;
+    /** A suggested HTTP status, so route handlers do not have to map codes. */
+    status;
+    constructor(code, message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'LensError';
+        this.code = code;
+        this.details = options.details ?? {};
+        this.status = STATUS_BY_CODE[code] ?? 500;
+        Error.captureStackTrace?.(this, LensError);
+    }
+    /**
+     * Type guard. Pass a `code` to narrow further.
+     *
+     * @example `if (LensError.is(err, 'UPLOAD_FAILED')) ...`
+     */
+    static is(error, code) {
+        if (!(error instanceof LensError))
+            return false;
+        return code === undefined || error.code === code;
+    }
+    /** JSON-safe representation, suitable for logs and API responses. */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            status: this.status,
+            details: this.details,
+        };
+    }
+}
+exports.LensError = LensError;
+const STATUS_BY_CODE = {
+    INVALID_SOURCE: 400,
+    SOURCE_UNREADABLE: 400,
+    UNSUPPORTED_INPUT: 415,
+    VALIDATION_FAILED: 422,
+    INVALID_OPTIONS: 400,
+    ABORTED: 499,
+    ENGINE_UNAVAILABLE: 500,
+    ENCODE_FAILED: 500,
+    ALL_FORMATS_FAILED: 500,
+    UPLOAD_FAILED: 502,
+    ADAPTER_REQUIRED: 500,
+    ADAPTER_UNSUPPORTED: 501,
+    ADAPTER_MISCONFIGURED: 500,
+};
+/** Throws `ABORTED` if the signal has already fired. Cheap enough to call often. */
+function throwIfAborted(signal, what = 'operation') {
+    if (signal?.aborted) {
+        throw new LensError('ABORTED', `Lens ${what} was aborted by the caller's AbortSignal.`, {
+            cause: signal.reason,
+        });
+    }
+}
+/**
+ * Wraps a non-Lens error, preserving the original as `cause`.
+ * Existing {@link LensError}s pass through untouched so codes are not lost.
+ */
+function wrapError(code, message, cause, details) {
+    if (LensError.is(cause))
+        return cause;
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return new LensError(code, `${message} (${reason})`, { cause, details });
+}
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAyHH,wCAMC;AAMD,8BASC;AAhGD;;;;;;;;;;;;GAYG;AACH,MAAa,SAAU,SAAQ,KAAK;IAClC,6DAA6D;IACpD,IAAI,CAAgB;IAE7B,0DAA0D;IACjD,OAAO,CAAmB;IAEnC,2EAA2E;IAClE,MAAM,CAAS;IAExB,YACE,IAAmB,EACnB,OAAe,EACf,UAA2D,EAAE;QAE7D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;QAC1C,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAc,EAAE,IAAoB;QAC5C,IAAI,CAAC,CAAC,KAAK,YAAY,SAAS,CAAC;YAAE,OAAO,KAAK,CAAC;QAChD,OAAO,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;IACnD,CAAC;IAED,qEAAqE;IACrE,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;CACF;AA3CD,8BA2CC;AAED,MAAM,cAAc,GAA2C;IAC7D,cAAc,EAAE,GAAG;IACnB,iBAAiB,EAAE,GAAG;IACtB,iBAAiB,EAAE,GAAG;IACtB,iBAAiB,EAAE,GAAG;IACtB,eAAe,EAAE,GAAG;IACpB,OAAO,EAAE,GAAG;IACZ,kBAAkB,EAAE,GAAG;IACvB,aAAa,EAAE,GAAG;IAClB,kBAAkB,EAAE,GAAG;IACvB,aAAa,EAAE,GAAG;IAClB,gBAAgB,EAAE,GAAG;IACrB,mBAAmB,EAAE,GAAG;IACxB,qBAAqB,EAAE,GAAG;CAC3B,CAAC;AAEF,oFAAoF;AACpF,SAAgB,cAAc,CAAC,MAA+B,EAAE,IAAI,GAAG,WAAW;IAChF,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,SAAS,EAAE,QAAQ,IAAI,2CAA2C,EAAE;YACtF,KAAK,EAAE,MAAM,CAAC,MAAM;SACrB,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,SAAS,CACvB,IAAmB,EACnB,OAAe,EACf,KAAc,EACd,OAA0B;IAE1B,IAAI,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtE,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,GAAG,OAAO,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/cjs/format.d.ts

@@ -0,0 +1,33 @@
+/** Format normalisation and per-format encoding defaults. */
+import type { ImageFormat, ImageFormatInput } from './types.js';
+/** Every format Lens can encode to. */
+export declare const ENCODABLE_FORMATS: readonly ImageFormat[];
+/**
+ * Maps a user-supplied format name onto its canonical form.
+ *
+ * `'jpg'` and `'JPEG'` both become `'jpeg'` so results are keyed consistently
+ * no matter how the caller spelled it.
+ *
+ * @throws {LensError} `INVALID_OPTIONS` for an unknown name.
+ */
+export declare function normalizeFormat(input: ImageFormatInput | string): ImageFormat;
+/** Normalises a list, dropping duplicates while preserving the caller's order. */
+export declare function normalizeFormats(inputs: readonly (ImageFormatInput | string)[]): readonly ImageFormat[];
+/** True when the format stores an alpha channel. */
+export declare function supportsAlpha(format: ImageFormat): boolean;
+/** True when `quality` has any effect on the encode. */
+export declare function isLossy(format: ImageFormat): boolean;
+/**
+ * Sensible per-format encoder defaults.
+ *
+ * AVIF gets a lower quality number than JPEG on purpose: the scales are not
+ * comparable, and AVIF at q80 is wastefully large for the same perceived
+ * result. Callers who pass an explicit quality always win over this.
+ */
+export declare function defaultQuality(format: ImageFormat): number;
+/**
+ * Default encoder effort. AVIF is slow enough that the top setting is a
+ * production hazard, so we sit mid-scale.
+ */
+export declare function defaultEffort(format: ImageFormat): number | undefined;
+//# sourceMappingURL=format.d.ts.map

package/dist/cjs/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/format.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAG7D,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAchE,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,EAAE,SAAS,WAAW,EAOnD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,GAAG,WAAW,CAW7E;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,CAAC,gBAAgB,GAAG,MAAM,CAAC,EAAE,GAC7C,SAAS,WAAW,EAAE,CAWxB;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE1D;AAED,wDAAwD;AACxD,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAW1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CASrE"}

package/dist/cjs/format.js

@@ -0,0 +1,102 @@
+"use strict";
+/** Format normalisation and per-format encoding defaults. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENCODABLE_FORMATS = void 0;
+exports.normalizeFormat = normalizeFormat;
+exports.normalizeFormats = normalizeFormats;
+exports.supportsAlpha = supportsAlpha;
+exports.isLossy = isLossy;
+exports.defaultQuality = defaultQuality;
+exports.defaultEffort = defaultEffort;
+const errors_js_1 = require("./errors.js");
+const ALIASES = {
+    jpg: 'jpeg',
+    jpeg: 'jpeg',
+    jpe: 'jpeg',
+    png: 'png',
+    webp: 'webp',
+    avif: 'avif',
+    gif: 'gif',
+    tif: 'tiff',
+    tiff: 'tiff',
+};
+/** Every format Lens can encode to. */
+exports.ENCODABLE_FORMATS = [
+    'jpeg',
+    'png',
+    'webp',
+    'avif',
+    'gif',
+    'tiff',
+];
+/**
+ * Maps a user-supplied format name onto its canonical form.
+ *
+ * `'jpg'` and `'JPEG'` both become `'jpeg'` so results are keyed consistently
+ * no matter how the caller spelled it.
+ *
+ * @throws {LensError} `INVALID_OPTIONS` for an unknown name.
+ */
+function normalizeFormat(input) {
+    const key = String(input).trim().toLowerCase().replace(/^\./, '');
+    const format = ALIASES[key];
+    if (!format) {
+        throw new errors_js_1.LensError('INVALID_OPTIONS', `Unknown output format "${input}". Supported: ${exports.ENCODABLE_FORMATS.join(', ')} (and the alias "jpg").`, { details: { actual: input } });
+    }
+    return format;
+}
+/** Normalises a list, dropping duplicates while preserving the caller's order. */
+function normalizeFormats(inputs) {
+    const seen = new Set();
+    const out = [];
+    for (const input of inputs) {
+        const format = normalizeFormat(input);
+        if (!seen.has(format)) {
+            seen.add(format);
+            out.push(format);
+        }
+    }
+    return out;
+}
+/** True when the format stores an alpha channel. */
+function supportsAlpha(format) {
+    return format !== 'jpeg';
+}
+/** True when `quality` has any effect on the encode. */
+function isLossy(format) {
+    return format === 'jpeg' || format === 'webp' || format === 'avif';
+}
+/**
+ * Sensible per-format encoder defaults.
+ *
+ * AVIF gets a lower quality number than JPEG on purpose: the scales are not
+ * comparable, and AVIF at q80 is wastefully large for the same perceived
+ * result. Callers who pass an explicit quality always win over this.
+ */
+function defaultQuality(format) {
+    switch (format) {
+        case 'avif':
+            return 60;
+        case 'webp':
+            return 80;
+        case 'jpeg':
+            return 82;
+        default:
+            return 80;
+    }
+}
+/**
+ * Default encoder effort. AVIF is slow enough that the top setting is a
+ * production hazard, so we sit mid-scale.
+ */
+function defaultEffort(format) {
+    switch (format) {
+        case 'avif':
+            return 4;
+        case 'webp':
+            return 4;
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=format.js.map

package/dist/cjs/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/format.ts"],"names":[],"mappings":";AAAA,6DAA6D;;;AAmC7D,0CAWC;AAGD,4CAaC;AAGD,sCAEC;AAGD,0BAEC;AASD,wCAWC;AAMD,sCASC;AAzGD,2CAAwC;AAGxC,MAAM,OAAO,GAAgC;IAC3C,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,uCAAuC;AAC1B,QAAA,iBAAiB,GAA2B;IACvD,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;CACP,CAAC;AAEF;;;;;;;GAOG;AACH,SAAgB,eAAe,CAAC,KAAgC;IAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,qBAAS,CACjB,iBAAiB,EACjB,0BAA0B,KAAK,iBAAiB,yBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,yBAAyB,EACrG,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAA0B,EAAE,EAAE,CACpD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,kFAAkF;AAClF,SAAgB,gBAAgB,CAC9B,MAA8C;IAE9C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAe,CAAC;IACpC,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACjB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oDAAoD;AACpD,SAAgB,aAAa,CAAC,MAAmB;IAC/C,OAAO,MAAM,KAAK,MAAM,CAAC;AAC3B,CAAC;AAED,wDAAwD;AACxD,SAAgB,OAAO,CAAC,MAAmB;IACzC,OAAO,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,CAAC;AACrE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,MAAmB;IAChD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,EAAE,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,EAAE,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,EAAE,CAAC;QACZ;YACE,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,MAAmB;IAC/C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,CAAC,CAAC;QACX,KAAK,MAAM;YACT,OAAO,CAAC,CAAC;QACX;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/cjs/hash.d.ts

@@ -0,0 +1,19 @@
+/** Content hashing, via `node:crypto`. Used for cache keys, ETags and filenames. */
+/** Full lowercase hex SHA-256 of some bytes. */
+export declare function sha256(data: Uint8Array): string;
+/**
+ * Short hash for use in URLs and filenames.
+ *
+ * 10 hex characters is 40 bits. For content-addressed asset names that is a
+ * ~1-in-a-million collision chance at a million distinct images, which is the
+ * same trade-off webpack and friends make for chunk hashes.
+ */
+export declare function shortHash(data: Uint8Array | string, length?: number): string;
+/**
+ * Stable hash of an arbitrary options object.
+ *
+ * Object keys are sorted so `{ a, b }` and `{ b, a }` produce the same cache
+ * key - otherwise property order would silently fragment the cache.
+ */
+export declare function hashOptions(value: unknown): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/cjs/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/hash.ts"],"names":[],"mappings":"AAAA,oFAAoF;AAIpF,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAGxE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD"}

package/dist/cjs/hash.js

@@ -0,0 +1,43 @@
+"use strict";
+/** Content hashing, via `node:crypto`. Used for cache keys, ETags and filenames. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256 = sha256;
+exports.shortHash = shortHash;
+exports.hashOptions = hashOptions;
+const node_crypto_1 = require("node:crypto");
+/** Full lowercase hex SHA-256 of some bytes. */
+function sha256(data) {
+    return (0, node_crypto_1.createHash)('sha256').update(data).digest('hex');
+}
+/**
+ * Short hash for use in URLs and filenames.
+ *
+ * 10 hex characters is 40 bits. For content-addressed asset names that is a
+ * ~1-in-a-million collision chance at a million distinct images, which is the
+ * same trade-off webpack and friends make for chunk hashes.
+ */
+function shortHash(data, length = 10) {
+    const hash = typeof data === 'string' ? (0, node_crypto_1.createHash)('sha256').update(data).digest('hex') : sha256(data);
+    return hash.slice(0, length);
+}
+/**
+ * Stable hash of an arbitrary options object.
+ *
+ * Object keys are sorted so `{ a, b }` and `{ b, a }` produce the same cache
+ * key - otherwise property order would silently fragment the cache.
+ */
+function hashOptions(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(stableStringify(value)).digest('hex').slice(0, 16);
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+//# sourceMappingURL=hash.js.map