@lens-image/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lens contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+<p align="center">
+  <a href="https://lens-image.vercel.app">
+    <img src="https://raw.githubusercontent.com/Sthabiso10/lens-image/main/docs/media/logo.png" alt="Lens" width="300" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lens-image/core"><img alt="npm" src="https://img.shields.io/npm/v/@lens-image%2Fcore.svg?color=cb3837" /></a>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6.svg" />
+  <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg" />
+</p>
+
+# @lens-image/core
+
+**Zero-dependency image optimization engine for Node.js.** Resize, compress, convert formats, and hand the results to any storage backend.
+
+```bash
+npm install @lens-image/core sharp
+```
+
+`sharp` is an [optional peer dependency](#the-engine). `@lens-image/core` itself installs **zero packages**.
+
+---
+
+## Quick start
+
+```ts
+import { ImageOptimizer, MemoryAdapter } from '@lens-image/core';
+
+const optimizer = new ImageOptimizer({ adapter: new MemoryAdapter() });
+
+const result = await optimizer.optimize({
+  source: './photo.jpg',
+  formats: ['webp', 'jpg'],
+  sizes: [{ width: 1200 }, { width: 600 }, { width: 300 }],
+});
+
+result.formats.webp.srcset;
+```
+
+Swap `MemoryAdapter` for [`@lens-image/adapter-s3`](../adapter-s3), [`@lens-image/adapter-local`](../adapter-local) or [`@lens-image/adapter-cloudinary`](../adapter-cloudinary) when you want the bytes to go somewhere real.
+
+---
+
+## `new ImageOptimizer(options)`
+
+| Option | Type | Default | |
+|---|---|---|---|
+| `adapter` | `StorageAdapter` |, | Where output goes. Omit for process-only mode. |
+| `engine` | `ImageEngine` | auto | Codec backend. Defaults to sharp if installed. |
+| `quality` | `number` | per-format | 1-100. |
+| `formats` | `ImageFormat[]` | `['webp']` | Default output formats. |
+| `sizes` | `SizeSpec[]` | original | Default responsive sizes. |
+| `fallbackFormat` | `ImageFormat \| null` | `'jpeg'` | Used when everything else fails. `null` disables. |
+| `key` | `string \| fn` | `'{hash}/{name}-{label}.{ext}'` | Output key template. |
+| `prefix` | `string` | `''` | Prepended to every key. |
+| `preserveMetadata` | `boolean` | `false` | Keep EXIF/ICC/XMP. |
+| `autoOrient` | `boolean` | `true` | Apply EXIF orientation before resizing. |
+| `concurrency` | `number` | `4` | Parallel encode+upload pipelines. |
+| `validate` | `ValidationOptions \| false` | see below | Input limits. |
+| `retry` | `RetryOptions` | 3 attempts | Adapter write retries. |
+| `cache` | `false \| 'memory' \| 'storage' \| CacheStore` | `false` | Result caching. |
+| `cacheControl` | `string` | `public, max-age=31536000, immutable` | Applied to uploads. |
+| `allowRemote` | `boolean` | `false` | Permit `http(s):` sources. |
+| `onWarning` | `(w) => void` |, | Called per degradation. |
+
+Everything except `adapter`, `engine`, `cache` and `allowRemote` can be overridden per call.
+
+---
+
+## `optimizer.optimize(options)`
+
+```ts
+await optimizer.optimize({
+  source: './photo.jpg',
+  formats: ['avif', 'webp', 'jpg'],
+  sizes: [{ width: 1200 }, { width: 600, fit: 'contain' }],
+  thumbnail: { width: 128, format: 'webp' },
+  metadata: { uploadedBy: 'user-42' },
+  signal: controller.signal,
+});
+```
+
+### `source` accepts
+
+| | |
+|---|---|
+| `string` | Filesystem path |
+| `Uint8Array` / `Buffer` | Raw bytes |
+| `URL` | `file:`, or `http(s):` with `allowRemote` |
+| `AsyncIterable<Uint8Array>` | Node or web stream, multipart part |
+| `{ data, filename }` | Bytes plus a name for key generation |
+
+### Sizes
+
+```ts
+sizes: [
+  { width: 1200 },                                    // → label '1200w'
+  { width: 400, height: 400, fit: 'cover' },          // → label '400x400'
+  { width: 800, label: 'hero', quality: 90 },         // explicit label
+]
+```
+
+`fit` is `'cover' | 'contain' | 'fill' | 'inside' | 'outside'`. The familiar CSS names. Images are never upscaled unless you set `withoutEnlargement: false`.
+
+> Two sizes that produce the same label within one format throw `INVALID_OPTIONS`, because they'd map to the same key and one would silently overwrite the other.
+
+---
+
+## The result
+
+```ts
+interface OptimizeResult {
+  id: string;             // stable per (source, options), also the cache key
+  runId: string;          // unique per call, for log correlation
+  source: ImageMetadata & { filename: string; checksum: string };
+  formats: { webp?: FormatResult; jpeg?: FormatResult; /* … */ };
+  variants: Variant[];    // flat, in plan order
+  thumbnail?: Variant;
+  warnings: LensWarning[];
+  totalSize: number;
+  savings: number;        // 0-1, vs the largest single output
+  durationMs: number;
+  cached: boolean;
+  engine: string;
+  adapter: string | null;
+}
+```
+
+Each `FormatResult` carries `urls` (keyed by label), `variants`, `srcset`, `size`, `largest` and `smallest`.
+
+> **Note on `jpg`.** It's accepted everywhere as an input alias and normalised to `jpeg`, so results are always keyed `result.formats.jpeg`. File extensions still come out as `.jpg`.
+
+---
+
+## Other methods
+
+```ts
+await optimizer.inspect(source);              // metadata only, no processing
+await optimizer.optimizeMany([a, b], opts);   // sequential, bounded memory
+await optimizer.delete(result);               // remove every variant
+await optimizer.dispose();                    // release adapter resources
+```
+
+---
+
+## Validation
+
+Runs against the **file header**, before any decoder sees the bytes.
+
+```ts
+validate: {
+  maxBytes: 25 * 1024 * 1024,     // default
+  maxPixels: 100_000_000,         // default, decompression-bomb guard
+  allowedFormats: ['jpeg', 'png', 'webp', 'avif', 'gif', 'tiff'],
+  minWidth: 200,
+  minHeight: 200,
+}
+```
+
+Set `validate: false` to disable. The `maxPixels` guard matters: a 40,000 × 40,000 PNG compresses to a few hundred KB and expands to roughly 6 GB in memory.
+
+---
+
+## The engine
+
+The codec is an interface, not a hard dependency:
+
+```ts
+interface ImageEngine {
+  readonly name: string;
+  supports(format: ImageFormat): boolean | Promise<boolean>;
+  probe(input: Uint8Array): Promise<ImageMetadata>;
+  transform(input: Uint8Array, op: TransformOp): Promise<EncodedImage>;
+}
+```
+
+| Engine | |
+|---|---|
+| `createSharpEngine(opts)` | sharp-backed. Lazy dynamic import, nothing loads until you encode. |
+| `createPassthroughEngine()` | No codec. Validates, hashes, keys and stores originals. Ideal for tests. |
+| `detectEngine()` | sharp if available, otherwise passthrough. The default. |
+
+```ts
+import { createSharpEngine } from '@lens-image/core';
+
+new ImageOptimizer({
+  engine: createSharpEngine({
+    threads: 1,      // we already parallelise; 4 Lens jobs × 4 libvips threads = 16
+    cache: false,    // libvips' global cache is a leak in a long-lived server
+  }),
+});
+```
+
+---
+
+## Upload handler
+
+A `Request → Response` function built only on web standards, so it drops into Next.js, Remix, Hono, Bun or Deno unmodified.
+
+```ts
+export const POST = createUploadHandler({
+  optimizer,
+  fieldName: 'file',
+  maxFiles: 5,
+  authorize: async (req) => (await auth(req)) ? undefined : new Response('no', { status: 401 }),
+  options: async (req) => ({ prefix: `users/${(await auth(req)).id}` }),
+  onError: (error) => logger.error(error),
+});
+```
+
+Errors map to their `LensError.status` automatically. A too-large file is a 422, not a 500. Unexpected errors return a generic message; the real one goes to `onError`.
+
+---
+
+## HTML helpers
+
+```ts
+import { toPicture, pickVariant, buildSrcset } from '@lens-image/core';
+
+const pic = toPicture(result, { alt: 'Cabin', sizes: '(max-width: 768px) 100vw, 50vw' });
+const best = pickVariant(result, 800, 'webp');   // smallest variant ≥ 800px
+```
+
+---
+
+## Exports for adapter authors
+
+```ts
+import {
+  sniff, mimeTypeFor, extensionFor,        // format detection
+  buildKey, joinKey, slugify,              // key templating
+  withRetry, isRetryableError,             // retry
+  mapLimit,                                // bounded concurrency
+  sha256, shortHash,                       // hashing
+  LensError,                               // error taxonomy
+} from '@lens-image/core';
+```
+
+---
+
+## License
+
+MIT

package/dist/cjs/adapters/memory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+import type { StorageAdapter, StorageContext, StorageFile, StorageObject } from './../types.js';
+/** Options for {@link MemoryAdapter}. */
+export interface MemoryAdapterOptions {
+    /** URL scheme used for generated URLs. Default `'memory://'`. */
+    readonly baseUrl?: string;
+    /**
+     * Inject a failure for the first N attempts on any key. Test-only, and the
+     * reason retry behaviour is easy to verify without mocking a network.
+     */
+    readonly failAttempts?: number;
+}
+/** A stored object. */
+export interface MemoryEntry {
+    readonly key: string;
+    readonly data: Uint8Array;
+    readonly contentType: string;
+    readonly cacheControl?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/**
+ * @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 declare class MemoryAdapter implements StorageAdapter {
+    #private;
+    readonly name = "memory";
+    constructor(options?: MemoryAdapterOptions);
+    upload(file: StorageFile, _ctx: StorageContext): Promise<StorageObject>;
+    exists(key: string): Promise<boolean>;
+    remove(key: string): Promise<void>;
+    getUrl(key: string): string;
+    /** Reads back a stored object. */
+    get(key: string): MemoryEntry | undefined;
+    /** Every stored key, in insertion order. */
+    keys(): string[];
+    /** Number of stored objects. */
+    get size(): number;
+    /** Drops every object and resets the injected-failure counters. */
+    clear(): void;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/cjs/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/cjs/adapters/memory.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryAdapter = void 0;
+/**
+ * @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
+ * ```
+ */
+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();
+    }
+}
+exports.MemoryAdapter = MemoryAdapter;
+//# sourceMappingURL=memory.js.map

package/dist/cjs/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/cjs/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/cjs/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/cjs/browser.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * `@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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatBytes = exports.pickVariant = exports.toPicture = exports.buildSrcset = exports.DEFAULT_KEY_TEMPLATE = exports.defaultLabel = exports.slugify = exports.joinKey = exports.buildKey = exports.ENCODABLE_FORMATS = exports.defaultEffort = exports.defaultQuality = exports.isLossy = exports.supportsAlpha = exports.normalizeFormats = exports.normalizeFormat = exports.LensError = exports.DEFAULT_ALLOWED_FORMATS = exports.DEFAULT_MAX_PIXELS = exports.DEFAULT_MAX_BYTES = exports.resolveValidation = exports.validateImage = exports.SNIFF_HEADER_BYTES = exports.extensionFor = exports.mimeTypeFor = exports.sniffFormat = exports.sniff = void 0;
+// --- Format detection -------------------------------------------------------
+var sniff_js_1 = require("./sniff.js");
+Object.defineProperty(exports, "sniff", { enumerable: true, get: function () { return sniff_js_1.sniff; } });
+Object.defineProperty(exports, "sniffFormat", { enumerable: true, get: function () { return sniff_js_1.sniffFormat; } });
+Object.defineProperty(exports, "mimeTypeFor", { enumerable: true, get: function () { return sniff_js_1.mimeTypeFor; } });
+Object.defineProperty(exports, "extensionFor", { enumerable: true, get: function () { return sniff_js_1.extensionFor; } });
+Object.defineProperty(exports, "SNIFF_HEADER_BYTES", { enumerable: true, get: function () { return sniff_js_1.SNIFF_HEADER_BYTES; } });
+// --- Validation -------------------------------------------------------------
+var validation_js_1 = require("./validation.js");
+Object.defineProperty(exports, "validateImage", { enumerable: true, get: function () { return validation_js_1.validateImage; } });
+Object.defineProperty(exports, "resolveValidation", { enumerable: true, get: function () { return validation_js_1.resolveValidation; } });
+Object.defineProperty(exports, "DEFAULT_MAX_BYTES", { enumerable: true, get: function () { return validation_js_1.DEFAULT_MAX_BYTES; } });
+Object.defineProperty(exports, "DEFAULT_MAX_PIXELS", { enumerable: true, get: function () { return validation_js_1.DEFAULT_MAX_PIXELS; } });
+Object.defineProperty(exports, "DEFAULT_ALLOWED_FORMATS", { enumerable: true, get: function () { return validation_js_1.DEFAULT_ALLOWED_FORMATS; } });
+// --- Errors -----------------------------------------------------------------
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "LensError", { enumerable: true, get: function () { return errors_js_1.LensError; } });
+// --- Formats ----------------------------------------------------------------
+var format_js_1 = require("./format.js");
+Object.defineProperty(exports, "normalizeFormat", { enumerable: true, get: function () { return format_js_1.normalizeFormat; } });
+Object.defineProperty(exports, "normalizeFormats", { enumerable: true, get: function () { return format_js_1.normalizeFormats; } });
+Object.defineProperty(exports, "supportsAlpha", { enumerable: true, get: function () { return format_js_1.supportsAlpha; } });
+Object.defineProperty(exports, "isLossy", { enumerable: true, get: function () { return format_js_1.isLossy; } });
+Object.defineProperty(exports, "defaultQuality", { enumerable: true, get: function () { return format_js_1.defaultQuality; } });
+Object.defineProperty(exports, "defaultEffort", { enumerable: true, get: function () { return format_js_1.defaultEffort; } });
+Object.defineProperty(exports, "ENCODABLE_FORMATS", { enumerable: true, get: function () { return format_js_1.ENCODABLE_FORMATS; } });
+// --- Key templating ---------------------------------------------------------
+var naming_js_1 = require("./naming.js");
+Object.defineProperty(exports, "buildKey", { enumerable: true, get: function () { return naming_js_1.buildKey; } });
+Object.defineProperty(exports, "joinKey", { enumerable: true, get: function () { return naming_js_1.joinKey; } });
+Object.defineProperty(exports, "slugify", { enumerable: true, get: function () { return naming_js_1.slugify; } });
+Object.defineProperty(exports, "defaultLabel", { enumerable: true, get: function () { return naming_js_1.defaultLabel; } });
+Object.defineProperty(exports, "DEFAULT_KEY_TEMPLATE", { enumerable: true, get: function () { return naming_js_1.DEFAULT_KEY_TEMPLATE; } });
+// --- HTML helpers -----------------------------------------------------------
+var srcset_js_1 = require("./srcset.js");
+Object.defineProperty(exports, "buildSrcset", { enumerable: true, get: function () { return srcset_js_1.buildSrcset; } });
+Object.defineProperty(exports, "toPicture", { enumerable: true, get: function () { return srcset_js_1.toPicture; } });
+Object.defineProperty(exports, "pickVariant", { enumerable: true, get: function () { return srcset_js_1.pickVariant; } });
+// --- Formatting -------------------------------------------------------------
+var bytes_js_1 = require("./bytes.js");
+Object.defineProperty(exports, "formatBytes", { enumerable: true, get: function () { return bytes_js_1.formatBytes; } });
+//# sourceMappingURL=browser.js.map

package/dist/cjs/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,uCAA+F;AAAtF,iGAAA,KAAK,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,wGAAA,YAAY,OAAA;AAAE,8GAAA,kBAAkB,OAAA;AAE1E,+EAA+E;AAC/E,iDAMyB;AALvB,8GAAA,aAAa,OAAA;AACb,kHAAA,iBAAiB,OAAA;AACjB,kHAAA,iBAAiB,OAAA;AACjB,mHAAA,kBAAkB,OAAA;AAClB,wHAAA,uBAAuB,OAAA;AAIzB,+EAA+E;AAC/E,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAGlB,+EAA+E;AAC/E,yCAQqB;AAPnB,4GAAA,eAAe,OAAA;AACf,6GAAA,gBAAgB,OAAA;AAChB,0GAAA,aAAa,OAAA;AACb,oGAAA,OAAO,OAAA;AACP,2GAAA,cAAc,OAAA;AACd,0GAAA,aAAa,OAAA;AACb,8GAAA,iBAAiB,OAAA;AAGnB,+EAA+E;AAC/E,yCAA6F;AAApF,qGAAA,QAAQ,OAAA;AAAE,oGAAA,OAAO,OAAA;AAAE,oGAAA,OAAO,OAAA;AAAE,yGAAA,YAAY,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAEvE,+EAA+E;AAC/E,yCAAkE;AAAzD,wGAAA,WAAW,OAAA;AAAE,sGAAA,SAAS,OAAA;AAAE,wGAAA,WAAW,OAAA;AAG5C,+EAA+E;AAC/E,uCAAyC;AAAhC,uGAAA,WAAW,OAAA"}

package/dist/cjs/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/cjs/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/cjs/bytes.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatBytes = formatBytes;
+/**
+ * Human-readable byte count, using binary units.
+ *
+ * @example
+ * ```ts
+ * formatBytes(900);       // '900 B'
+ * formatBytes(5_242_880); // '5.0 MiB'
+ * ```
+ */
+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/cjs/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../src/bytes.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAWH,kCAMC;AAfD;;;;;;;;GAQG;AACH,SAAgB,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/cjs/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/cjs/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"}