@lens-image/core 0.1.0

package/dist/esm/source.js

@@ -0,0 +1,183 @@
+/**
+ * Turning the many shapes of "an image" into bytes plus a filename.
+ *
+ * Node builtins only - `node:fs/promises` for paths, global `fetch` for remote
+ * URLs (Node 18+), and manual concatenation for async iterables.
+ */
+import { basename, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { formatBytes } from './bytes.js';
+import { LensError, wrapError } from './errors.js';
+const isAsyncIterable = (value) => typeof value === 'object' && value !== null && Symbol.asyncIterator in value;
+/**
+ * Normalises any {@link ImageSource} into a buffer.
+ *
+ * @throws {LensError} `INVALID_SOURCE` for an unrecognised shape,
+ *   `SOURCE_UNREADABLE` when the read itself fails,
+ *   `VALIDATION_FAILED` when `maxBytes` is exceeded mid-read.
+ *
+ * @example
+ * ```ts
+ * await resolveSource('./photo.jpg');
+ * await resolveSource(request.body, { filename: 'upload.png', maxBytes: 5_000_000 });
+ * ```
+ */
+export async function resolveSource(source, options = {}) {
+    const { filename: override } = options;
+    // { data, filename } wrapper - unwrap and recurse, keeping the inner filename
+    // unless the caller supplied an explicit override.
+    if (typeof source === 'object' &&
+        source !== null &&
+        !(source instanceof URL) &&
+        !ArrayBuffer.isView(source) &&
+        !isAsyncIterable(source) &&
+        'data' in source) {
+        const wrapper = source;
+        const inner = await resolveSource(wrapper.data, {
+            ...options,
+            filename: override ?? wrapper.filename,
+        });
+        return wrapper.contentType ? { ...inner, contentType: wrapper.contentType } : inner;
+    }
+    if (typeof source === 'string') {
+        return readPath(source, override, options);
+    }
+    if (source instanceof URL) {
+        if (source.protocol === 'file:') {
+            return readPath(fileURLToPath(source), override, options);
+        }
+        if (source.protocol === 'http:' || source.protocol === 'https:') {
+            return readRemote(source, override, options);
+        }
+        throw new LensError('INVALID_SOURCE', `Unsupported URL protocol "${source.protocol}". Use a file:, http: or https: URL.`);
+    }
+    if (ArrayBuffer.isView(source)) {
+        const data = toUint8(source);
+        assertUnderLimit(data.byteLength, options.maxBytes);
+        return { data, filename: normalizeFilename(override ?? 'image'), origin: 'buffer' };
+    }
+    if (isAsyncIterable(source)) {
+        const data = await collect(source, options.maxBytes, options.signal);
+        return { data, filename: normalizeFilename(override ?? 'image'), origin: 'stream' };
+    }
+    throw new LensError('INVALID_SOURCE', 'source must be a file path, URL, Uint8Array, async iterable of chunks, or { data, filename }. ' +
+        `Received ${describe(source)}.`);
+}
+async function readPath(path, override, options) {
+    const { readFile, stat } = await import('node:fs/promises');
+    try {
+        if (options.maxBytes !== undefined) {
+            // Check the size before reading so an oversized file never lands in memory.
+            const info = await stat(path);
+            assertUnderLimit(info.size, options.maxBytes, path);
+        }
+        const buffer = await readFile(path, options.signal ? { signal: options.signal } : undefined);
+        return {
+            data: toUint8(buffer),
+            filename: normalizeFilename(override ?? basename(path)),
+            origin: 'path',
+        };
+    }
+    catch (error) {
+        if (LensError.is(error))
+            throw error;
+        if (error?.name === 'AbortError') {
+            throw new LensError('ABORTED', `Reading "${path}" was aborted.`, { cause: error });
+        }
+        throw wrapError('SOURCE_UNREADABLE', `Could not read image at "${path}"`, error, { path });
+    }
+}
+async function readRemote(url, override, options) {
+    if (!options.allowRemote) {
+        throw new LensError('INVALID_SOURCE', `Refusing to fetch "${url.href}". Remote sources are disabled by default because they are ` +
+            'an SSRF surface; pass `allowRemote: true` to the optimizer once you have validated the host.', { details: { url: url.href } });
+    }
+    let response;
+    try {
+        response = await fetch(url, options.signal ? { signal: options.signal } : {});
+    }
+    catch (error) {
+        throw wrapError('SOURCE_UNREADABLE', `Fetching "${url.href}" failed`, error, { url: url.href });
+    }
+    if (!response.ok) {
+        throw new LensError('SOURCE_UNREADABLE', `Fetching "${url.href}" returned HTTP ${response.status} ${response.statusText}.`, { details: { url: url.href, status: response.status } });
+    }
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > 0) {
+        assertUnderLimit(declared, options.maxBytes, url.href);
+    }
+    const data = toUint8(new Uint8Array(await response.arrayBuffer()));
+    assertUnderLimit(data.byteLength, options.maxBytes, url.href);
+    const contentType = response.headers.get('content-type') ?? undefined;
+    const derived = basename(url.pathname) || 'image';
+    return {
+        data,
+        filename: normalizeFilename(override ?? derived),
+        ...(contentType ? { contentType } : {}),
+        origin: 'url',
+    };
+}
+/** Drains an async iterable into one buffer, enforcing `maxBytes` as it goes. */
+async function collect(stream, maxBytes, signal) {
+    const chunks = [];
+    let total = 0;
+    try {
+        for await (const chunk of stream) {
+            if (signal?.aborted) {
+                throw new LensError('ABORTED', 'Reading the source stream was aborted.');
+            }
+            const bytes = toUint8(chunk);
+            total += bytes.byteLength;
+            assertUnderLimit(total, maxBytes);
+            chunks.push(bytes);
+        }
+    }
+    catch (error) {
+        throw wrapError('SOURCE_UNREADABLE', 'Reading the source stream failed', error);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function assertUnderLimit(size, maxBytes, what) {
+    if (maxBytes !== undefined && size > maxBytes) {
+        throw new LensError('VALIDATION_FAILED', `Image is ${formatBytes(size)}${what ? ` ("${what}")` : ''}, over the ${formatBytes(maxBytes)} limit.`, { details: { limit: maxBytes, actual: size } });
+    }
+}
+/**
+ * Views any ArrayBufferView as a Uint8Array without copying.
+ *
+ * The byteOffset/byteLength dance matters: Node often hands you a Buffer that
+ * is a window onto a larger pooled allocation, and ignoring that ships the
+ * neighbouring bytes too.
+ */
+function toUint8(view) {
+    return view instanceof Uint8Array && view.byteOffset === 0 && view.byteLength === view.buffer.byteLength
+        ? view
+        : new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+}
+/** Strips directory separators and control characters from a filename. */
+function normalizeFilename(name) {
+    const cleaned = name.split(/[\\/]/).pop() ?? 'image';
+    // eslint-disable-next-line no-control-regex
+    const safe = cleaned.replace(/[\x00-\x1f\x7f]/g, '').trim();
+    return safe.length > 0 ? safe : 'image';
+}
+/** Filename without its extension. */
+export function stem(filename) {
+    const ext = extname(filename);
+    return ext ? filename.slice(0, -ext.length) : filename;
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return typeof value;
+}
+export { formatBytes };
+//# sourceMappingURL=source.js.map

package/dist/esm/source.js.map

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

package/dist/esm/srcset.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Helpers for getting an {@link OptimizeResult} into HTML.
+ *
+ * These are pure functions over the result object, deliberately framework-free
+ * so they work in Express templates, Next.js, Astro or a string concatenation
+ * in a cron job.
+ */
+import type { ImageFormat, OptimizeResult, Variant } from './types.js';
+/**
+ * Builds a `srcset` attribute value from variants.
+ *
+ * Variants without a URL (process-only mode) and zero-width variants are
+ * skipped, and the list is sorted ascending so browsers pick sensibly.
+ *
+ * @example
+ * ```ts
+ * buildSrcset(result.formats.webp!.variants);
+ * // 'https://cdn/…-300w.webp 300w, https://cdn/…-600w.webp 600w'
+ * ```
+ */
+export declare function buildSrcset(variants: readonly Variant[]): string;
+/** One `<source>` element's worth of data. */
+export interface PictureSource {
+    readonly type: string;
+    readonly srcset: string;
+    readonly sizes?: string;
+}
+/** Everything needed to render a `<picture>`. */
+export interface PictureData {
+    /** In the order given to `optimize`, which is the order they should be tried. */
+    readonly sources: readonly PictureSource[];
+    /** `src` for the `<img>` fallback - the widest variant of the last format. */
+    readonly src: string;
+    readonly width: number;
+    readonly height: number;
+    readonly alt: string;
+}
+/**
+ * Reshapes a result into `<picture>`-ready data.
+ *
+ * Source order is the order formats were requested, which matters: the browser
+ * takes the first `<source>` it supports. Request `['avif', 'webp', 'jpeg']`
+ * and you get exactly the progressive-enhancement ladder you wanted.
+ *
+ * @example
+ * ```tsx
+ * const pic = toPicture(result, { alt: 'Cabin at dusk', sizes: '(max-width: 768px) 100vw, 50vw' });
+ *
+ * <picture>
+ *   {pic.sources.map((s) => <source key={s.type} type={s.type} srcSet={s.srcset} sizes={s.sizes} />)}
+ *   <img src={pic.src} width={pic.width} height={pic.height} alt={pic.alt} loading="lazy" />
+ * </picture>
+ * ```
+ */
+export declare function toPicture(result: OptimizeResult, options?: {
+    alt?: string;
+    sizes?: string;
+}): PictureData;
+/**
+ * Picks the variant closest to a target width without going under it, so the
+ * rendered image is never upscaled.
+ *
+ * @example `pickVariant(result, 800, 'webp')`
+ */
+export declare function pickVariant(result: OptimizeResult, targetWidth: number, format?: ImageFormat): Variant | undefined;
+//# sourceMappingURL=srcset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"srcset.d.ts","sourceRoot":"","sources":["../../src/srcset.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAgB,WAAW,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAMhE;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,WAAW,CAsBb;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,GAAG,SAAS,CAIrB"}

package/dist/esm/srcset.js

@@ -0,0 +1,76 @@
+/**
+ * Helpers for getting an {@link OptimizeResult} into HTML.
+ *
+ * These are pure functions over the result object, deliberately framework-free
+ * so they work in Express templates, Next.js, Astro or a string concatenation
+ * in a cron job.
+ */
+import { mimeTypeFor } from './sniff.js';
+/**
+ * Builds a `srcset` attribute value from variants.
+ *
+ * Variants without a URL (process-only mode) and zero-width variants are
+ * skipped, and the list is sorted ascending so browsers pick sensibly.
+ *
+ * @example
+ * ```ts
+ * buildSrcset(result.formats.webp!.variants);
+ * // 'https://cdn/…-300w.webp 300w, https://cdn/…-600w.webp 600w'
+ * ```
+ */
+export function buildSrcset(variants) {
+    return [...variants]
+        .filter((v) => v.url && v.width > 0)
+        .sort((a, b) => a.width - b.width)
+        .map((v) => `${v.url} ${v.width}w`)
+        .join(', ');
+}
+/**
+ * Reshapes a result into `<picture>`-ready data.
+ *
+ * Source order is the order formats were requested, which matters: the browser
+ * takes the first `<source>` it supports. Request `['avif', 'webp', 'jpeg']`
+ * and you get exactly the progressive-enhancement ladder you wanted.
+ *
+ * @example
+ * ```tsx
+ * const pic = toPicture(result, { alt: 'Cabin at dusk', sizes: '(max-width: 768px) 100vw, 50vw' });
+ *
+ * <picture>
+ *   {pic.sources.map((s) => <source key={s.type} type={s.type} srcSet={s.srcset} sizes={s.sizes} />)}
+ *   <img src={pic.src} width={pic.width} height={pic.height} alt={pic.alt} loading="lazy" />
+ * </picture>
+ * ```
+ */
+export function toPicture(result, options = {}) {
+    const groups = Object.values(result.formats).filter(Boolean);
+    const sources = groups
+        .filter((group) => group.srcset.length > 0)
+        .map((group) => ({
+        type: mimeTypeFor(group.format),
+        srcset: group.srcset,
+        ...(options.sizes ? { sizes: options.sizes } : {}),
+    }));
+    // The <img> fallback should be the most compatible format available, which is
+    // the last one requested in a properly ordered format list.
+    const fallback = groups[groups.length - 1]?.largest;
+    return {
+        sources,
+        src: fallback?.url ?? '',
+        width: fallback?.width ?? result.source.width,
+        height: fallback?.height ?? result.source.height,
+        alt: options.alt ?? '',
+    };
+}
+/**
+ * Picks the variant closest to a target width without going under it, so the
+ * rendered image is never upscaled.
+ *
+ * @example `pickVariant(result, 800, 'webp')`
+ */
+export function pickVariant(result, targetWidth, format) {
+    const pool = format ? (result.formats[format]?.variants ?? []) : result.variants;
+    const sorted = [...pool].sort((a, b) => a.width - b.width);
+    return sorted.find((v) => v.width >= targetWidth) ?? sorted[sorted.length - 1];
+}
+//# sourceMappingURL=srcset.js.map

package/dist/esm/srcset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"srcset.js","sourceRoot":"","sources":["../../src/srcset.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,QAA4B;IACtD,OAAO,CAAC,GAAG,QAAQ,CAAC;SACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;SACnC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC;SAClC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAoBD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAAsB,EACtB,UAA4C,EAAE;IAE9C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAmB,CAAC;IAE/E,MAAM,OAAO,GAAG,MAAM;SACnB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;SAC1C,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACf,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;QAC/B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC,CAAC,CAAC;IAEN,8EAA8E;IAC9E,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC;IAEpD,OAAO;QACL,OAAO;QACP,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE;QACxB,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK;QAC7C,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM;QAChD,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE;KACvB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,MAAsB,EACtB,WAAmB,EACnB,MAAoB;IAEpB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;IACjF,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC3D,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,WAAW,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjF,CAAC"}