@lens-image/core 0.1.0

package/dist/esm/types.d.ts

@@ -0,0 +1,441 @@
+/**
+ * The public type surface of `@lens-image/core`.
+ *
+ * Everything in this file is an interface or a plain data shape - there is no
+ * runtime code here, so adapter and engine authors can depend on these types
+ * without pulling in any of the implementation.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Canonical image formats Lens understands.
+ *
+ * Note that `jpg` is not a member: it is accepted everywhere as an *input*
+ * alias and normalised to `jpeg`. Results are always keyed by the canonical
+ * name so `result.formats.jpeg` is the only place you have to look.
+ *
+ * @see {@link normalizeFormat}
+ */
+export type ImageFormat = 'jpeg' | 'png' | 'webp' | 'avif' | 'gif' | 'tiff';
+/** Anything accepted where a {@link ImageFormat} is expected. */
+export type ImageFormatInput = ImageFormat | 'jpg' | 'tif';
+/**
+ * Formats Lens can detect but never encodes to. Useful for validation
+ * (`allowedFormats`) and for reporting what was actually uploaded.
+ */
+export type DetectedFormat = ImageFormat | 'svg' | 'bmp' | 'ico' | 'heic' | 'unknown';
+/**
+ * Anything you can hand to {@link ImageOptimizer.optimize} as `source`.
+ *
+ * - `string` - an absolute or relative filesystem path.
+ * - `Uint8Array` / `Buffer` - raw bytes already in memory.
+ * - `URL` - a `file:` URL, or an `http(s):` URL when `allowRemote` is enabled.
+ * - `AsyncIterable<Uint8Array>` - a Node stream, a web stream, a multipart part.
+ * - `{ data, filename }` - bytes plus the original filename, which is used for
+ *   output naming when it would otherwise be a content hash.
+ */
+export type ImageSource = string | URL | Uint8Array | AsyncIterable<Uint8Array> | {
+    data: Uint8Array | AsyncIterable<Uint8Array>;
+    filename?: string;
+    contentType?: string;
+};
+/** What Lens knows about an image before it touches a codec. */
+export interface ImageMetadata {
+    /** Detected container format. */
+    readonly format: DetectedFormat;
+    /** Pixel width, or `0` when the format carries no readable dimensions. */
+    readonly width: number;
+    /** Pixel height, or `0` when the format carries no readable dimensions. */
+    readonly height: number;
+    /** Byte length of the encoded image. */
+    readonly size: number;
+    /** True when the source declares an alpha channel. */
+    readonly hasAlpha?: boolean;
+    /** True for animated GIF / WebP. Animated sources skip resizing by default. */
+    readonly isAnimated?: boolean;
+    /** EXIF orientation (1-8) when present. */
+    readonly orientation?: number;
+    /** Colour space reported by the codec, when the engine can supply it. */
+    readonly space?: string;
+}
+/** How a resize should fill the requested box. Mirrors the familiar CSS names. */
+export type FitMode = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+/** Gravity used when `fit: 'cover'` has to crop. */
+export type Position = 'center' | 'top' | 'right' | 'bottom' | 'left' | 'entropy' | 'attention';
+/** A single resize instruction. At least one of `width` / `height` is required. */
+export interface ResizeSpec {
+    readonly width?: number;
+    readonly height?: number;
+    /** Default `'cover'`. */
+    readonly fit?: FitMode;
+    /** Default `'center'`. */
+    readonly position?: Position;
+    /** Never scale an image above its intrinsic size. Default `true`. */
+    readonly withoutEnlargement?: boolean;
+    /** Flat background for `contain` letterboxing, as `#rrggbb` or `#rrggbbaa`. */
+    readonly background?: string;
+}
+/** A fully resolved instruction handed to an {@link ImageEngine}. */
+export interface TransformOp {
+    /** Omitted for a straight re-encode at native size. */
+    readonly resize?: ResizeSpec;
+    /** Target output format. */
+    readonly format: ImageFormat;
+    /** 1-100. Ignored by lossless formats. */
+    readonly quality: number;
+    /** Keep EXIF / ICC / XMP in the output. Default `false`. */
+    readonly preserveMetadata: boolean;
+    /** Apply EXIF orientation and drop the tag. Default `true`. */
+    readonly autoOrient: boolean;
+    /** Encode losslessly where the format supports it (webp, avif). */
+    readonly lossless?: boolean;
+    /** Progressive / interlaced encode where supported (jpeg, png). */
+    readonly progressive?: boolean;
+    /** Encoder effort, 0-9. Higher is slower and smaller. */
+    readonly effort?: number;
+    /** Chroma subsampling override, e.g. `'4:4:4'`. */
+    readonly chromaSubsampling?: string;
+}
+/** The bytes an engine produced, plus what they turned out to be. */
+export interface EncodedImage {
+    readonly data: Uint8Array;
+    readonly format: ImageFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly size: number;
+}
+/**
+ * A codec backend. Implement this to swap sharp for squoosh, an ImageMagick
+ * shell-out, a WASM codec, or a stub in tests.
+ *
+ * Engines are expected to be stateless and safe to call concurrently.
+ */
+export interface ImageEngine {
+    /** Short identifier, surfaced in errors and results (e.g. `'sharp'`). */
+    readonly name: string;
+    /**
+     * Whether this engine can *encode* the given format. Lens calls this before
+     * planning work so it can degrade gracefully instead of failing mid-run.
+     */
+    supports(format: ImageFormat): boolean | Promise<boolean>;
+    /**
+     * Read dimensions and metadata. Engines may return richer data than the
+     * built-in header sniffer, and Lens prefers the engine's answer when present.
+     */
+    probe(input: Uint8Array): Promise<ImageMetadata>;
+    /** Resize and/or re-encode. Must not mutate `input`. */
+    transform(input: Uint8Array, op: TransformOp): Promise<EncodedImage>;
+}
+/** One object about to be written to storage. */
+export interface StorageFile {
+    /** Storage key / relative path, already templated. No leading slash. */
+    readonly key: string;
+    readonly data: Uint8Array;
+    /** MIME type, e.g. `image/webp`. */
+    readonly contentType: string;
+    /** Suggested `Cache-Control`. Adapters may override from their own config. */
+    readonly cacheControl?: string;
+    /** Arbitrary key/value metadata. Adapters map this to their native concept. */
+    readonly metadata?: Readonly<Record<string, string>>;
+    /** Hex content hash of `data`, handy for ETags and dedupe. */
+    readonly checksum?: string;
+}
+/** Context passed alongside every upload so adapters can log or route. */
+export interface StorageContext {
+    /** Abort signal propagated from `optimize({ signal })`. */
+    readonly signal?: AbortSignal;
+    /** Which attempt this is, starting at 1. Set by the retry wrapper. */
+    readonly attempt: number;
+    /** The optimize run this upload belongs to. */
+    readonly runId: string;
+}
+/** What an adapter reports back after a successful write. */
+export interface StorageObject {
+    /** The key actually written - adapters may prefix or rewrite it. */
+    readonly key: string;
+    /** Publicly reachable URL, or a best-effort local URL. */
+    readonly url: string;
+    /** Bytes written. */
+    readonly size: number;
+    readonly etag?: string;
+    /** Adapter-specific extras (S3 versionId, Cloudinary public_id, ...). */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A storage backend.
+ *
+ * Only {@link StorageAdapter.upload} is required. Implementing `exists` unlocks
+ * cache short-circuiting; implementing `remove` unlocks
+ * {@link ImageOptimizer.delete}.
+ *
+ * @example A minimal in-memory adapter
+ * ```ts
+ * const files = new Map<string, Uint8Array>();
+ *
+ * const adapter: StorageAdapter = {
+ *   name: 'memory',
+ *   async upload(file) {
+ *     files.set(file.key, file.data);
+ *     return { key: file.key, url: `memory://${file.key}`, size: file.data.byteLength };
+ *   },
+ * };
+ * ```
+ */
+export interface StorageAdapter {
+    /** Short identifier, surfaced in errors (e.g. `'s3'`). */
+    readonly name: string;
+    /** Write one object. Should throw on failure; Lens handles the retries. */
+    upload(file: StorageFile, ctx: StorageContext): Promise<StorageObject>;
+    /** Cheap existence probe. Enables `cache: 'storage'`. */
+    exists?(key: string, ctx?: Partial<StorageContext>): Promise<boolean>;
+    /** Delete one object. Enables {@link ImageOptimizer.delete}. */
+    remove?(key: string, ctx?: Partial<StorageContext>): Promise<void>;
+    /** Public URL for a key without performing a write. */
+    getUrl?(key: string): string;
+    /** Release sockets, flush buffers. Called by {@link ImageOptimizer.dispose}. */
+    dispose?(): Promise<void> | void;
+}
+/** One requested output size. */
+export interface SizeSpec extends ResizeSpec {
+    /**
+     * Name used in the output key and in `formats[f].urls`. Defaults to
+     * `"<width>w"`, or `"<height>h"` when only a height is given.
+     */
+    readonly label?: string;
+    /** Per-size quality override. */
+    readonly quality?: number;
+}
+/** Validation limits applied before any pixels are decoded. */
+export interface ValidationOptions {
+    /** Reject sources larger than this many bytes. Default 25 MiB. */
+    readonly maxBytes?: number;
+    /** Reject sources whose `width * height` exceeds this. Default 100 megapixels. */
+    readonly maxPixels?: number;
+    /** Allowed input formats. Default: every format the engine can decode. */
+    readonly allowedFormats?: readonly DetectedFormat[];
+    /** Reject images narrower than this. */
+    readonly minWidth?: number;
+    /** Reject images shorter than this. */
+    readonly minHeight?: number;
+}
+/** Retry policy for adapter writes. */
+export interface RetryOptions {
+    /** Total attempts including the first. Default 3. Set to 1 to disable. */
+    readonly attempts?: number;
+    /** Delay before the second attempt, in ms. Default 200. */
+    readonly baseDelayMs?: number;
+    /** Ceiling for the exponential backoff, in ms. Default 5000. */
+    readonly maxDelayMs?: number;
+    /**
+     * Decide whether an error is worth retrying. Default: retry network-ish and
+     * 5xx errors, never 4xx.
+     */
+    readonly isRetryable?: (error: unknown) => boolean;
+    /** Called before each sleep. Useful for logging and tests. */
+    readonly onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }) => void;
+}
+/** Where processed-output bookkeeping lives. */
+export interface CacheStore {
+    get(key: string): Promise<OptimizeResult | undefined> | OptimizeResult | undefined;
+    set(key: string, value: OptimizeResult): Promise<void> | void;
+    delete?(key: string): Promise<void> | void;
+}
+/** Tokens available to a key template or key function. */
+export interface KeyContext {
+    /** Source basename without extension, slugified. */
+    readonly name: string;
+    /** Short content hash of the source bytes. */
+    readonly hash: string;
+    /** Full content hash of the source bytes. */
+    readonly fullHash: string;
+    readonly format: ImageFormat;
+    /** File extension without the dot - `jpg` for `jpeg`. */
+    readonly ext: string;
+    readonly width: number;
+    readonly height: number;
+    readonly quality: number;
+    /** Size label, e.g. `1200w` or `thumb`. */
+    readonly label: string;
+}
+/** Everything `new ImageOptimizer(...)` accepts. */
+export interface ImageOptimizerOptions {
+    /**
+     * Where output goes. Omit to run in "process only" mode: results carry bytes
+     * in `variant.data` and no URLs.
+     */
+    readonly adapter?: StorageAdapter;
+    /**
+     * Codec backend. Defaults to sharp when it is installed, otherwise a
+     * passthrough engine that can re-key and validate but not resize.
+     */
+    readonly engine?: ImageEngine;
+    /** Default quality for every output. 1-100. Default 80. */
+    readonly quality?: number;
+    /** Default formats when a call does not specify any. Default `['webp']`. */
+    readonly formats?: readonly ImageFormatInput[];
+    /** Default sizes when a call does not specify any. Default: original size. */
+    readonly sizes?: readonly SizeSpec[];
+    /**
+     * Format to fall back to when a requested format cannot be produced.
+     * Default `'jpeg'`. Set to `null` to disable fallback entirely.
+     */
+    readonly fallbackFormat?: ImageFormatInput | null;
+    /**
+     * Output key template, or a function. Tokens: `{name} {hash} {fullHash}
+     * {format} {ext} {width} {height} {quality} {label}`.
+     *
+     * Default: `'{hash}/{name}-{label}.{ext}'`.
+     */
+    readonly key?: string | ((ctx: KeyContext) => string);
+    /** Prepended to every key. A trailing slash is added if missing. */
+    readonly prefix?: string;
+    /** Keep EXIF / ICC / XMP. Default `false` - metadata is stripped. */
+    readonly preserveMetadata?: boolean;
+    /** Apply EXIF orientation before resizing. Default `true`. */
+    readonly autoOrient?: boolean;
+    /** How many encode+upload pipelines run at once. Default 4. */
+    readonly concurrency?: number;
+    /** Validation limits. */
+    readonly validate?: ValidationOptions | false;
+    /** Retry policy for adapter writes. */
+    readonly retry?: RetryOptions;
+    /**
+     * Result caching.
+     * - `false` (default) - always reprocess.
+     * - `'memory'` - process-lifetime LRU keyed by source hash + options.
+     * - `'storage'` - `'memory'`, plus skip work when `adapter.exists` says the
+     *   keys are already there.
+     * - a {@link CacheStore} - bring your own (Redis, SQLite, ...).
+     */
+    readonly cache?: false | 'memory' | 'storage' | CacheStore;
+    /** Entries kept by the built-in memory cache. Default 500. */
+    readonly cacheSize?: number;
+    /** `Cache-Control` applied to every upload. Default `public, max-age=31536000, immutable`. */
+    readonly cacheControl?: string;
+    /** Allow `http(s):` sources. Off by default - it is an SSRF surface. */
+    readonly allowRemote?: boolean;
+    /** Called for every non-fatal degradation. Default: silent. */
+    readonly onWarning?: (warning: LensWarning) => void;
+}
+/** Per-call options. Anything omitted falls back to the constructor value. */
+export interface OptimizeOptions extends Pick<ImageOptimizerOptions, 'quality' | 'formats' | 'sizes' | 'fallbackFormat' | 'key' | 'prefix' | 'preserveMetadata' | 'autoOrient' | 'concurrency' | 'validate' | 'retry' | 'cacheControl' | 'onWarning'> {
+    /** The image to process. */
+    readonly source: ImageSource;
+    /** Overrides the filename derived from `source`. */
+    readonly filename?: string;
+    /**
+     * Also emit a small square-ish preview.
+     * `true` means 256px wide in the first requested format.
+     */
+    readonly thumbnail?: boolean | ThumbnailSpec;
+    /** Metadata attached to every uploaded object. */
+    readonly metadata?: Readonly<Record<string, string>>;
+    /** Keep encoded bytes on each variant. Default `true` without an adapter. */
+    readonly keepData?: boolean;
+    /** Cancel in-flight encodes and uploads. */
+    readonly signal?: AbortSignal;
+    /** Skip the cache for this call only. */
+    readonly force?: boolean;
+}
+/** Thumbnail configuration. */
+export interface ThumbnailSpec extends ResizeSpec {
+    /** Default 256. */
+    readonly width?: number;
+    readonly height?: number;
+    /** Defaults to the first requested output format. */
+    readonly format?: ImageFormatInput;
+    /** Defaults to the run quality. */
+    readonly quality?: number;
+    /** Default `'thumb'`. */
+    readonly label?: string;
+}
+/** One generated file. */
+export interface Variant {
+    readonly format: ImageFormat;
+    readonly label: string;
+    readonly width: number;
+    readonly height: number;
+    /** Bytes of the encoded output. */
+    readonly size: number;
+    readonly quality: number;
+    /** Storage key, or the templated key when running without an adapter. */
+    readonly key: string;
+    /** Public URL. Empty string when running without an adapter. */
+    readonly url: string;
+    readonly contentType: string;
+    /** Hex content hash of the encoded bytes. */
+    readonly checksum: string;
+    /** Present when `keepData` is on, or when there is no adapter. */
+    readonly data?: Uint8Array;
+    /** True when this variant was produced by the fallback format. */
+    readonly isFallback?: boolean;
+    /** True for the variant generated by the `thumbnail` option. */
+    readonly isThumbnail?: boolean;
+    /** ETag reported by the adapter, when it supplies one. */
+    readonly etag?: string;
+    /** Adapter extras. */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/** All variants of one format, grouped for convenient template access. */
+export interface FormatResult {
+    readonly format: ImageFormat;
+    /** `{ '1200w': 'https://...', '600w': 'https://...' }` */
+    readonly urls: Readonly<Record<string, string>>;
+    readonly variants: readonly Variant[];
+    /** Total bytes across every variant of this format. */
+    readonly size: number;
+    /** Ready-to-use `srcset` attribute value. Empty when URLs are unavailable. */
+    readonly srcset: string;
+    /** The widest variant - a sensible `src` fallback. */
+    readonly largest: Variant;
+    /** The narrowest variant. */
+    readonly smallest: Variant;
+}
+/** A non-fatal degradation. */
+export interface LensWarning {
+    /** Machine-readable reason, e.g. `'format_unsupported'`. */
+    readonly code: string;
+    readonly message: string;
+    /** Format the warning relates to, when applicable. */
+    readonly format?: ImageFormat;
+    readonly label?: string;
+    /** The underlying error, when the warning came from a thrown exception. */
+    readonly cause?: unknown;
+}
+/** What {@link ImageOptimizer.optimize} resolves to. */
+export interface OptimizeResult {
+    /** Stable id for this source + options combination. Also the cache key. */
+    readonly id: string;
+    /** Unique per call, even on a cache hit. Correlates logs. */
+    readonly runId: string;
+    /** What the input turned out to be. */
+    readonly source: ImageMetadata & {
+        readonly filename: string;
+        readonly checksum: string;
+    };
+    /** Grouped by canonical format name: `result.formats.webp.urls['600w']`. */
+    readonly formats: Readonly<Partial<Record<ImageFormat, FormatResult>>>;
+    /** Every variant, in plan order. */
+    readonly variants: readonly Variant[];
+    /** Present when `thumbnail` was requested and succeeded. */
+    readonly thumbnail?: Variant;
+    /** Non-fatal degradations - unsupported formats, fallbacks taken. */
+    readonly warnings: readonly LensWarning[];
+    /** Total output bytes across every variant. */
+    readonly totalSize: number;
+    /** `1 - totalSize / source.size`, clamped to 0. Negative savings report 0. */
+    readonly savings: number;
+    /** Wall-clock duration in ms. */
+    readonly durationMs: number;
+    /** True when the result came from cache rather than fresh work. */
+    readonly cached: boolean;
+    /** Engine that produced the output. */
+    readonly engine: string;
+    /** Adapter that stored it, or `null` in process-only mode. */
+    readonly adapter: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/esm/types.js

@@ -0,0 +1,11 @@
+/**
+ * The public type surface of `@lens-image/core`.
+ *
+ * Everything in this file is an interface or a plain data shape - there is no
+ * runtime code here, so adapter and engine authors can depend on these types
+ * without pulling in any of the implementation.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/esm/validation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Input validation, run against the sniffed header before any decode happens.
+ */
+import type { DetectedFormat, ImageMetadata, ValidationOptions } from './types.js';
+/** 25 MiB. Large enough for a phone photo, small enough to bound memory. */
+export declare const DEFAULT_MAX_BYTES: number;
+/**
+ * 100 megapixels. A 10,000 x 10,000 image is already 400 MB decoded at
+ * 4 bytes/pixel, so this is the line between "big photo" and "denial of service".
+ */
+export declare const DEFAULT_MAX_PIXELS = 100000000;
+/** Formats accepted as input unless the caller narrows the list. */
+export declare const DEFAULT_ALLOWED_FORMATS: readonly DetectedFormat[];
+/** A fully-resolved validation policy. */
+export interface ResolvedValidation {
+    readonly maxBytes: number;
+    readonly maxPixels: number;
+    readonly allowedFormats: readonly DetectedFormat[];
+    readonly minWidth: number;
+    readonly minHeight: number;
+}
+/** Fills in defaults for anything the caller left out. */
+export declare function resolveValidation(options: ValidationOptions | false | undefined): ResolvedValidation | null;
+/**
+ * Applies a resolved policy to sniffed metadata.
+ *
+ * @throws {LensError} `VALIDATION_FAILED` or `UNSUPPORTED_INPUT`, with the limit
+ *   and the actual value on `error.details` so callers can build a useful
+ *   response without re-deriving them.
+ *
+ * @example
+ * ```ts
+ * const policy = resolveValidation({ maxBytes: 5_000_000, allowedFormats: ['jpeg', 'png'] });
+ * validateImage(sniff(bytes), policy, 'avatar.png');
+ * ```
+ */
+export declare function validateImage(meta: ImageMetadata, policy: ResolvedValidation | null, filename?: string): void;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnF,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAmB,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,YAAc,CAAC;AAE9C,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,EAAE,SAAS,cAAc,EAO5D,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,SAAS,cAAc,EAAE,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,GAAG,kBAAkB,GAAG,IAAI,CAS3G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,QAAQ,SAAU,GACjB,IAAI,CAoDN"}

package/dist/esm/validation.js

@@ -0,0 +1,74 @@
+/**
+ * Input validation, run against the sniffed header before any decode happens.
+ */
+import { LensError } from './errors.js';
+import { formatBytes } from './bytes.js';
+/** 25 MiB. Large enough for a phone photo, small enough to bound memory. */
+export const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+/**
+ * 100 megapixels. A 10,000 x 10,000 image is already 400 MB decoded at
+ * 4 bytes/pixel, so this is the line between "big photo" and "denial of service".
+ */
+export const DEFAULT_MAX_PIXELS = 100_000_000;
+/** Formats accepted as input unless the caller narrows the list. */
+export const DEFAULT_ALLOWED_FORMATS = [
+    'jpeg',
+    'png',
+    'webp',
+    'avif',
+    'gif',
+    'tiff',
+];
+/** Fills in defaults for anything the caller left out. */
+export function resolveValidation(options) {
+    if (options === false)
+        return null;
+    return {
+        maxBytes: options?.maxBytes ?? DEFAULT_MAX_BYTES,
+        maxPixels: options?.maxPixels ?? DEFAULT_MAX_PIXELS,
+        allowedFormats: options?.allowedFormats ?? DEFAULT_ALLOWED_FORMATS,
+        minWidth: options?.minWidth ?? 0,
+        minHeight: options?.minHeight ?? 0,
+    };
+}
+/**
+ * Applies a resolved policy to sniffed metadata.
+ *
+ * @throws {LensError} `VALIDATION_FAILED` or `UNSUPPORTED_INPUT`, with the limit
+ *   and the actual value on `error.details` so callers can build a useful
+ *   response without re-deriving them.
+ *
+ * @example
+ * ```ts
+ * const policy = resolveValidation({ maxBytes: 5_000_000, allowedFormats: ['jpeg', 'png'] });
+ * validateImage(sniff(bytes), policy, 'avatar.png');
+ * ```
+ */
+export function validateImage(meta, policy, filename = 'image') {
+    if (!policy)
+        return;
+    if (meta.format === 'unknown') {
+        throw new LensError('UNSUPPORTED_INPUT', `"${filename}" is not a recognisable image. The first bytes match no known image container.`, { details: { detected: 'unknown' } });
+    }
+    if (!policy.allowedFormats.includes(meta.format)) {
+        throw new LensError('VALIDATION_FAILED', `"${filename}" is ${meta.format}, which is not in the allowed list (${policy.allowedFormats.join(', ')}).`, { details: { detected: meta.format, allowed: policy.allowedFormats } });
+    }
+    if (meta.size > policy.maxBytes) {
+        throw new LensError('VALIDATION_FAILED', `"${filename}" is ${formatBytes(meta.size)}, over the ${formatBytes(policy.maxBytes)} limit.`, { details: { limit: policy.maxBytes, actual: meta.size } });
+    }
+    const pixels = meta.width * meta.height;
+    if (pixels > policy.maxPixels) {
+        throw new LensError('VALIDATION_FAILED', `"${filename}" is ${meta.width}x${meta.height} (${formatMegapixels(pixels)}), over the ` +
+            `${formatMegapixels(policy.maxPixels)} limit. This guard exists to stop decompression bombs.`, { details: { limit: policy.maxPixels, actual: pixels } });
+    }
+    if (policy.minWidth > 0 && meta.width > 0 && meta.width < policy.minWidth) {
+        throw new LensError('VALIDATION_FAILED', `"${filename}" is ${meta.width}px wide, under the ${policy.minWidth}px minimum.`, { details: { limit: policy.minWidth, actual: meta.width } });
+    }
+    if (policy.minHeight > 0 && meta.height > 0 && meta.height < policy.minHeight) {
+        throw new LensError('VALIDATION_FAILED', `"${filename}" is ${meta.height}px tall, under the ${policy.minHeight}px minimum.`, { details: { limit: policy.minHeight, actual: meta.height } });
+    }
+}
+function formatMegapixels(pixels) {
+    return `${(pixels / 1_000_000).toFixed(1)}MP`;
+}
+//# sourceMappingURL=validation.js.map

package/dist/esm/validation.js.map

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