@lens-image/core 0.1.0

package/dist/esm/format.js

@@ -0,0 +1,93 @@
+/** Format normalisation and per-format encoding defaults. */
+import { LensError } from './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. */
+export const 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.
+ */
+export function normalizeFormat(input) {
+    const key = String(input).trim().toLowerCase().replace(/^\./, '');
+    const format = ALIASES[key];
+    if (!format) {
+        throw new LensError('INVALID_OPTIONS', `Unknown output format "${input}". Supported: ${ENCODABLE_FORMATS.join(', ')} (and the alias "jpg").`, { details: { actual: input } });
+    }
+    return format;
+}
+/** Normalises a list, dropping duplicates while preserving the caller's order. */
+export 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. */
+export function supportsAlpha(format) {
+    return format !== 'jpeg';
+}
+/** True when `quality` has any effect on the encode. */
+export 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.
+ */
+export 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.
+ */
+export function defaultEffort(format) {
+    switch (format) {
+        case 'avif':
+            return 4;
+        case 'webp':
+            return 4;
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=format.js.map

package/dist/esm/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/format.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;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;AACvC,MAAM,CAAC,MAAM,iBAAiB,GAA2B;IACvD,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;CACP,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,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,SAAS,CACjB,iBAAiB,EACjB,0BAA0B,KAAK,iBAAiB,iBAAiB,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,MAAM,UAAU,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,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,OAAO,MAAM,KAAK,MAAM,CAAC;AAC3B,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,OAAO,CAAC,MAAmB;IACzC,OAAO,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,CAAC;AACrE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,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,MAAM,UAAU,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/esm/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/esm/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/esm/hash.js

@@ -0,0 +1,38 @@
+/** Content hashing, via `node:crypto`. Used for cache keys, ETags and filenames. */
+import { createHash } from 'node:crypto';
+/** Full lowercase hex SHA-256 of some bytes. */
+export function sha256(data) {
+    return 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.
+ */
+export function shortHash(data, length = 10) {
+    const hash = typeof data === 'string' ? 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.
+ */
+export function hashOptions(value) {
+    return 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

package/dist/esm/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/hash.ts"],"names":[],"mappings":"AAAA,oFAAoF;AAEpF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,gDAAgD;AAChD,MAAM,UAAU,MAAM,CAAC,IAAgB;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAyB,EAAE,MAAM,GAAG,EAAE;IAC9D,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvG,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACxF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC7E,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;SAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClC,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `@lens-image/core` - composable image optimization for Node.js.
+ *
+ * Zero runtime dependencies. The codec (sharp) and the storage backend are both
+ * injected interfaces, so the core is testable, swappable and installs nothing
+ * you did not ask for.
+ *
+ * @example
+ * ```ts
+ * import { ImageOptimizer } from '@lens-image/core';
+ * import { LocalAdapter } from '@lens-image/adapter-local';
+ *
+ * const optimizer = new ImageOptimizer({
+ *   adapter: new LocalAdapter({ root: './public/images', baseUrl: '/images' }),
+ *   quality: 80,
+ * });
+ *
+ * const result = await optimizer.optimize({
+ *   source: './photo.jpg',
+ *   formats: ['webp', 'jpg'],
+ *   sizes: [{ width: 1200 }, { width: 600 }, { width: 300 }],
+ * });
+ *
+ * console.log(result.formats.webp.srcset);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ImageOptimizer, DEFAULT_CACHE_CONTROL } from './optimizer.js';
+export { LensError, throwIfAborted, wrapError } from './errors.js';
+export type { LensErrorCode, LensErrorDetails } from './errors.js';
+export { createSharpEngine, createPassthroughEngine, detectEngine, resetEngineDetection, resetSharpCache, } from './engines/index.js';
+export type { SharpEngineOptions, PassthroughEngineOptions } from './engines/index.js';
+export { MemoryAdapter } from './adapters/memory.js';
+export type { MemoryAdapterOptions, MemoryEntry } from './adapters/memory.js';
+export { MemoryCacheStore, nullCacheStore } from './cache.js';
+export { createUploadHandler, serializeResult } from './server/handler.js';
+export type { UploadHandlerOptions } from './server/handler.js';
+export { buildSrcset, toPicture, pickVariant } from './srcset.js';
+export type { PictureData, PictureSource } from './srcset.js';
+export { sniff, sniffFormat, mimeTypeFor, extensionFor, SNIFF_HEADER_BYTES } from './sniff.js';
+export { resolveSource, stem, formatBytes } from './source.js';
+export type { ResolvedSource, ResolveOptions } from './source.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 { validateImage, resolveValidation, DEFAULT_MAX_BYTES, DEFAULT_MAX_PIXELS, DEFAULT_ALLOWED_FORMATS, } from './validation.js';
+export type { ResolvedValidation } from './validation.js';
+export { withRetry, resolveRetry, backoffDelay, isRetryableError } from './retry.js';
+export type { ResolvedRetry } from './retry.js';
+export { mapLimit, delay } from './concurrency.js';
+export type { Settled } from './concurrency.js';
+export { sha256, shortHash, hashOptions } from './hash.js';
+export type { CacheStore, DetectedFormat, EncodedImage, FitMode, FormatResult, ImageEngine, ImageFormat, ImageFormatInput, ImageMetadata, ImageOptimizerOptions, ImageSource, KeyContext, LensWarning, OptimizeOptions, OptimizeResult, Position, ResizeSpec, RetryOptions, SizeSpec, StorageAdapter, StorageContext, StorageFile, StorageObject, ThumbnailSpec, TransformOp, ValidationOptions, Variant, } from './types.js';
+/** The version of `@lens-image/core`, useful in `User-Agent` strings and bug reports. */
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,YAAY,EACZ,oBAAoB,EACpB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAGvF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3E,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,OAAO,EACP,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrF,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG3D,YAAY,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,WAAW,EACX,eAAe,EACf,cAAc,EACd,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,OAAO,GACR,MAAM,YAAY,CAAC;AAEpB,yFAAyF;AACzF,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,54 @@
+/**
+ * `@lens-image/core` - composable image optimization for Node.js.
+ *
+ * Zero runtime dependencies. The codec (sharp) and the storage backend are both
+ * injected interfaces, so the core is testable, swappable and installs nothing
+ * you did not ask for.
+ *
+ * @example
+ * ```ts
+ * import { ImageOptimizer } from '@lens-image/core';
+ * import { LocalAdapter } from '@lens-image/adapter-local';
+ *
+ * const optimizer = new ImageOptimizer({
+ *   adapter: new LocalAdapter({ root: './public/images', baseUrl: '/images' }),
+ *   quality: 80,
+ * });
+ *
+ * const result = await optimizer.optimize({
+ *   source: './photo.jpg',
+ *   formats: ['webp', 'jpg'],
+ *   sizes: [{ width: 1200 }, { width: 600 }, { width: 300 }],
+ * });
+ *
+ * console.log(result.formats.webp.srcset);
+ * ```
+ *
+ * @packageDocumentation
+ */
+// --- The main entry point ---------------------------------------------------
+export { ImageOptimizer, DEFAULT_CACHE_CONTROL } from './optimizer.js';
+// --- Errors -----------------------------------------------------------------
+export { LensError, throwIfAborted, wrapError } from './errors.js';
+// --- Engines ----------------------------------------------------------------
+export { createSharpEngine, createPassthroughEngine, detectEngine, resetEngineDetection, resetSharpCache, } from './engines/index.js';
+// --- Built-in adapters ------------------------------------------------------
+export { MemoryAdapter } from './adapters/memory.js';
+// --- Caching ----------------------------------------------------------------
+export { MemoryCacheStore, nullCacheStore } from './cache.js';
+// --- Server helpers ---------------------------------------------------------
+export { createUploadHandler, serializeResult } from './server/handler.js';
+// --- HTML helpers -----------------------------------------------------------
+export { buildSrcset, toPicture, pickVariant } from './srcset.js';
+// --- Utilities, exported because adapter authors need them ------------------
+export { sniff, sniffFormat, mimeTypeFor, extensionFor, SNIFF_HEADER_BYTES } from './sniff.js';
+export { resolveSource, stem, formatBytes } from './source.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 { validateImage, resolveValidation, DEFAULT_MAX_BYTES, DEFAULT_MAX_PIXELS, DEFAULT_ALLOWED_FORMATS, } from './validation.js';
+export { withRetry, resolveRetry, backoffDelay, isRetryableError } from './retry.js';
+export { mapLimit, delay } from './concurrency.js';
+export { sha256, shortHash, hashOptions } from './hash.js';
+/** The version of `@lens-image/core`, useful in `User-Agent` strings and bug reports. */
+export const VERSION = '0.1.0';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,+EAA+E;AAC/E,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvE,+EAA+E;AAC/E,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGnE,+EAA+E;AAC/E,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,YAAY,EACZ,oBAAoB,EACpB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAG5B,+EAA+E;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9D,+EAA+E;AAC/E,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3E,+EAA+E;AAC/E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGlE,+EAA+E;AAC/E,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,OAAO,EACP,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAErF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAiC3D,yFAAyF;AACzF,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/esm/naming.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Output key templating.
+ *
+ * Keys are how everything downstream addresses a variant - the S3 object key,
+ * the path under a local root, the public URL. They must be deterministic
+ * (so caching works), URL-safe (so nobody has to think about encoding), and
+ * predictable enough that a developer can eyeball a bucket listing.
+ */
+import type { KeyContext } from './types.js';
+/** `{hash}/{name}-{label}.{ext}` - content-addressed and cacheable forever. */
+export declare const DEFAULT_KEY_TEMPLATE = "{hash}/{name}-{label}.{ext}";
+/**
+ * Makes a string safe for a URL path segment.
+ *
+ * Lowercases, strips diacritics, collapses anything non-alphanumeric to a
+ * single dash. Empty input becomes `'image'` so a key is never malformed.
+ *
+ * @example
+ * ```ts
+ * slugify('Café Photo (2).JPG'); // 'cafe-photo-2-jpg'
+ * ```
+ */
+export declare function slugify(input: string): string;
+/**
+ * Renders a key template, or calls a key function.
+ *
+ * Tokens: `{name} {hash} {fullHash} {format} {ext} {width} {height}
+ * {quality} {label}`.
+ *
+ * @throws {LensError} `INVALID_OPTIONS` when the template references an unknown
+ *   token, or a key function returns something unusable. Failing loudly here
+ *   beats silently uploading a file called `undefined.webp`.
+ *
+ * @example
+ * ```ts
+ * buildKey('{name}/{width}x{height}.{ext}', ctx);  // 'hero/1200x800.webp'
+ * buildKey((c) => `${c.format}/${c.hash}.${c.ext}`, ctx);
+ * ```
+ */
+export declare function buildKey(template: string | ((ctx: KeyContext) => string), ctx: KeyContext, prefix?: string): string;
+/** Joins a prefix and a key, normalising slashes and stripping `..` segments. */
+export declare function joinKey(prefix: string, key: string): string;
+/**
+ * Default label for a size spec: `1200w`, `800h`, or `1200x800` when both
+ * dimensions are pinned.
+ */
+export declare function defaultLabel(width?: number, height?: number): string;
+//# sourceMappingURL=naming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAIlE;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,CAAC,EAChD,GAAG,EAAE,UAAU,EACf,MAAM,SAAK,GACV,MAAM,CAWR;AAeD,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAKpE"}

package/dist/esm/naming.js

@@ -0,0 +1,88 @@
+/**
+ * Output key templating.
+ *
+ * Keys are how everything downstream addresses a variant - the S3 object key,
+ * the path under a local root, the public URL. They must be deterministic
+ * (so caching works), URL-safe (so nobody has to think about encoding), and
+ * predictable enough that a developer can eyeball a bucket listing.
+ */
+import { LensError } from './errors.js';
+/** `{hash}/{name}-{label}.{ext}` - content-addressed and cacheable forever. */
+export const DEFAULT_KEY_TEMPLATE = '{hash}/{name}-{label}.{ext}';
+const TOKEN = /\{(\w+)\}/g;
+/**
+ * Makes a string safe for a URL path segment.
+ *
+ * Lowercases, strips diacritics, collapses anything non-alphanumeric to a
+ * single dash. Empty input becomes `'image'` so a key is never malformed.
+ *
+ * @example
+ * ```ts
+ * slugify('Café Photo (2).JPG'); // 'cafe-photo-2-jpg'
+ * ```
+ */
+export function slugify(input) {
+    const slug = input
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 100);
+    return slug.length > 0 ? slug : 'image';
+}
+/**
+ * Renders a key template, or calls a key function.
+ *
+ * Tokens: `{name} {hash} {fullHash} {format} {ext} {width} {height}
+ * {quality} {label}`.
+ *
+ * @throws {LensError} `INVALID_OPTIONS` when the template references an unknown
+ *   token, or a key function returns something unusable. Failing loudly here
+ *   beats silently uploading a file called `undefined.webp`.
+ *
+ * @example
+ * ```ts
+ * buildKey('{name}/{width}x{height}.{ext}', ctx);  // 'hero/1200x800.webp'
+ * buildKey((c) => `${c.format}/${c.hash}.${c.ext}`, ctx);
+ * ```
+ */
+export function buildKey(template, ctx, prefix = '') {
+    const raw = typeof template === 'function' ? template(ctx) : renderTemplate(template, ctx);
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        throw new LensError('INVALID_OPTIONS', 'The key function must return a non-empty string. ' +
+            `Received ${raw === undefined ? 'undefined' : JSON.stringify(raw)}.`);
+    }
+    return joinKey(prefix, raw);
+}
+function renderTemplate(template, ctx) {
+    return template.replace(TOKEN, (_match, token) => {
+        if (!(token in ctx)) {
+            throw new LensError('INVALID_OPTIONS', `Unknown token "{${token}}" in key template "${template}". ` +
+                `Available: ${Object.keys(ctx).map((k) => `{${k}}`).join(' ')}.`);
+        }
+        return String(ctx[token]);
+    });
+}
+/** Joins a prefix and a key, normalising slashes and stripping `..` segments. */
+export function joinKey(prefix, key) {
+    const parts = `${prefix}/${key}`
+        .split('/')
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0 && segment !== '.' && segment !== '..');
+    return parts.join('/');
+}
+/**
+ * Default label for a size spec: `1200w`, `800h`, or `1200x800` when both
+ * dimensions are pinned.
+ */
+export function defaultLabel(width, height) {
+    if (width && height)
+        return `${width}x${height}`;
+    if (width)
+        return `${width}w`;
+    if (height)
+        return `${height}h`;
+    return 'original';
+}
+//# sourceMappingURL=naming.js.map

package/dist/esm/naming.js.map

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

package/dist/esm/optimizer.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The orchestrator: validate, plan, encode, upload, assemble.
+ *
+ * Deliberately the only stateful class in the library. Everything it calls -
+ * sniffing, validation, key building, retry, the engine, the adapter - is a
+ * pure function or an injected interface, which is what makes the whole thing
+ * testable without a codec or a network.
+ */
+import type { ImageEngine, ImageMetadata, ImageOptimizerOptions, OptimizeOptions, OptimizeResult, StorageAdapter } from './types.js';
+/** `public, max-age=31536000, immutable` - safe because keys are content-addressed. */
+export declare const DEFAULT_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/**
+ * Optimizes images and hands them to a storage backend.
+ *
+ * Construct one per configuration and reuse it - it memoises engine detection
+ * and owns the result cache, so a fresh instance per request throws both away.
+ *
+ * @example Upload responsive WebP + JPEG to S3
+ * ```ts
+ * import { ImageOptimizer } from '@lens-image/core';
+ * import { S3Adapter } from '@lens-image/adapter-s3';
+ *
+ * const optimizer = new ImageOptimizer({
+ *   adapter: new S3Adapter({ bucket: 'my-images', region: 'us-east-1' }),
+ *   quality: 80,
+ * });
+ *
+ * const result = await optimizer.optimize({
+ *   source: '/path/to/image.jpg',
+ *   formats: ['webp', 'jpg'],
+ *   sizes: [{ width: 1200 }, { width: 600 }, { width: 300 }],
+ * });
+ *
+ * result.formats.webp.urls['600w'];  // 'https://my-images.s3.amazonaws.com/…-600w.webp'
+ * result.formats.webp.srcset;        // ready for <source srcset={…}>
+ * ```
+ *
+ * @example Process without storing
+ * ```ts
+ * const optimizer = new ImageOptimizer();          // no adapter
+ * const { variants } = await optimizer.optimize({ source: bytes, formats: ['webp'] });
+ * await writeFile('out.webp', variants[0].data!);  // bytes come back on the variant
+ * ```
+ */
+export declare class ImageOptimizer {
+    #private;
+    constructor(options?: ImageOptimizerOptions);
+    /** The storage backend, or `null` in process-only mode. */
+    get adapter(): StorageAdapter | null;
+    /** Resolves the codec backend, running detection on first use. */
+    engine(): Promise<ImageEngine>;
+    /**
+     * Processes one image into every requested format and size.
+     *
+     * Formats are independent: if AVIF encoding fails, the WebP and JPEG outputs
+     * still resolve and the failure is reported on `result.warnings` rather than
+     * thrown. Only a total failure - nothing at all was produced - rejects.
+     *
+     * @throws {LensError} `VALIDATION_FAILED`, `UNSUPPORTED_INPUT`,
+     *   `ALL_FORMATS_FAILED`, `UPLOAD_FAILED`, `ABORTED`.
+     */
+    optimize(options: OptimizeOptions): Promise<OptimizeResult>;
+    /**
+     * Optimizes several images with the same options.
+     *
+     * Runs sequentially by design. Each `optimize` call already parallelises its
+     * own variants, so overlapping whole images multiplies peak memory by the
+     * number of images - and decoded bitmaps, not encoded files, are what fills
+     * the heap. Wrap in your own queue if you have the headroom.
+     */
+    optimizeMany(sources: readonly OptimizeOptions['source'][], options?: Omit<OptimizeOptions, 'source'>): Promise<OptimizeResult[]>;
+    /**
+     * Reads an image's metadata without producing anything.
+     *
+     * Uses the engine when one is available and falls back to header sniffing,
+     * so it works with or without sharp installed.
+     */
+    inspect(source: OptimizeOptions['source']): Promise<ImageMetadata>;
+    /**
+     * Deletes every variant of a previous result from storage.
+     *
+     * @throws {LensError} `ADAPTER_REQUIRED` with no adapter configured,
+     *   `ADAPTER_UNSUPPORTED` when the adapter cannot delete.
+     */
+    delete(result: OptimizeResult): Promise<void>;
+    /** Releases adapter resources. Safe to call more than once. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=optimizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../src/optimizer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,OAAO,KAAK,EAGV,WAAW,EAEX,aAAa,EACb,qBAAqB,EAGrB,eAAe,EACf,cAAc,EAGd,cAAc,EAKf,MAAM,YAAY,CAAC;AAEpB,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,wCAAwC,CAAC;AAW3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,cAAc;;gBAMb,OAAO,GAAE,qBAA0B;IAkB/C,2DAA2D;IAC3D,IAAI,OAAO,IAAI,cAAc,GAAG,IAAI,CAEnC;IAED,kEAAkE;IAC5D,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC;IAKpC;;;;;;;;;OASG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAmJjE;;;;;;;OAOG;IACG,YAAY,CAChB,OAAO,EAAE,SAAS,eAAe,CAAC,QAAQ,CAAC,EAAE,EAC7C,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAM,GAC5C,OAAO,CAAC,cAAc,EAAE,CAAC;IAQ5B;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAOxE;;;;;OAKG;IACG,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnD,+DAA+D;IACzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAqa/B"}