format-png 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,370 +1,3 @@
-import initWasm, * as wasm from "./wasm/format_png_wasm.js";
-import wasmBase64 from "./wasm/format_png_wasm_bg.wasm.base64.js";
-/** Thrown for malformed PNGs; `message` says what's wrong. */
-export class PngError extends Error {
-    name = "PngError";
-}
-let ready;
-let initialized = false;
-/**
- * Loads the WebAssembly module. Call it once before anything else; later calls
- * return the same promise.
- *
- * With no argument it uses the copy embedded in this package, in browsers,
- * bundlers and Node alike: nothing is fetched. You can instead pass a
- * `WebAssembly.Module` compiled from it, for example one a page compiled once
- * and posted to its workers.
- */
-export function init(source) {
-    ready ??= initWasm({ module_or_path: source ?? decodeBase64(wasmBase64) })
-        .then(() => {
-        initialized = true;
-    })
-        .catch((error) => {
-        ready = undefined; // allow a retry
-        throw error;
-    });
-    return ready;
-}
-function decodeBase64(text) {
-    const binary = atob(text);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return bytes;
-}
-function call(fn) {
-    if (!initialized)
-        throw new PngError("format-png: call init() first");
-    try {
-        return fn();
-    }
-    catch (error) {
-        throw new PngError(error instanceof Error ? error.message : String(error));
-    }
-}
-function decoderArgs(options) {
-    return [
-        options.validateCrc ?? true,
-        options.preserveMetadata ?? false,
-        options.preserveChunks ?? false,
-        options.strictAncillary ?? false,
-    ];
-}
-function toText(source) {
-    try {
-        return {
-            keyword: source.keyword,
-            text: source.text,
-            languageTag: source.languageTag,
-            translatedKeyword: source.translatedKeyword,
-            chunkType: source.chunkType,
-            compressed: source.compressed,
-        };
-    }
-    finally {
-        source.free();
-    }
-}
-function toMetadata(source) {
-    const metadata = { text: source.text().map(toText) };
-    if (source.gamma !== undefined)
-        metadata.gamma = source.gamma;
-    if (source.srgb !== undefined)
-        metadata.srgb = source.srgb;
-    const c = source.chromaticities;
-    if (c) {
-        metadata.chromaticities = {
-            white: { x: c[0], y: c[1] },
-            red: { x: c[2], y: c[3] },
-            green: { x: c[4], y: c[5] },
-            blue: { x: c[6], y: c[7] },
-        };
-    }
-    const physical = source.physicalPixelsPerUnit;
-    if (physical) {
-        metadata.physicalDimensions = {
-            x: physical[0],
-            y: physical[1],
-            unit: source.physicalUnit,
-        };
-    }
-    const t = source.time;
-    if (t)
-        metadata.time = { year: t[0], month: t[1], day: t[2], hour: t[3], minute: t[4], second: t[5] };
-    const profile = source.iccProfile;
-    if (profile)
-        metadata.iccProfile = { name: source.iccProfileName, profile };
-    const cicp = source.cicp;
-    if (cicp) {
-        metadata.cicp = { colorPrimaries: cicp[0], transferFunction: cicp[1], matrixCoefficients: cicp[2], fullRange: cicp[3] === 1 };
-    }
-    const exif = source.exif;
-    if (exif)
-        metadata.exif = { data: exif, byteOrder: source.exifByteOrder };
-    return metadata;
-}
-function toChunk(chunk) {
-    const { chunkType: type, position } = chunk;
-    return { type, position: position, data: chunk.intoData() }; // `intoData` frees `chunk`
-}
-/** Reads `source.metadata()` and frees the wasm copy. */
-function takeMetadata(source) {
-    const metadata = source.metadata();
-    try {
-        return toMetadata(metadata);
-    }
-    finally {
-        metadata.free();
-    }
-}
-function toHeader(header) {
-    try {
-        return {
-            width: header.width,
-            height: header.height,
-            bitDepth: header.bitDepth,
-            colorType: header.colorType,
-            interlaced: header.interlaced,
-        };
-    }
-    finally {
-        header.free();
-    }
-}
-function toTransparency(kind, values) {
-    switch (kind) {
-        case "gray":
-            return { kind, value: values[0] };
-        case "rgb":
-            return { kind, value: [values[0], values[1], values[2]] };
-        default:
-            return { kind: "palette", alpha: Uint8Array.from(values) };
-    }
-}
-const isUpper = (char) => char >= "A" && char <= "Z";
-function toChunks(list, bytes) {
-    try {
-        const { types, offsets, lengths, crcs, known, palette, transparencyKind, transparencyValues } = list;
-        const result = {
-            header: toHeader(list.header()),
-            metadata: takeMetadata(list),
-            chunks: Array.from(offsets, (offset, i) => {
-                const type = types.slice(i * 4, i * 4 + 4);
-                return {
-                    type,
-                    offset,
-                    data: bytes.subarray(offset + 8, offset + 8 + lengths[i]),
-                    crc: crcs[i],
-                    known: known[i] === 1,
-                    critical: isUpper(type[0]),
-                    public: isUpper(type[1]),
-                    safeToCopy: !isUpper(type[3]),
-                };
-            }),
-        };
-        if (palette)
-            result.palette = toPalette(palette);
-        if (transparencyKind && transparencyValues)
-            result.transparency = toTransparency(transparencyKind, transparencyValues);
-        return result;
-    }
-    finally {
-        list.free();
-    }
-}
-function toImage(decoded) {
-    const { width, height } = decoded;
-    const metadata = takeMetadata(decoded);
-    const chunks = decoded.takeChunks().map(toChunk);
-    const pixels = decoded.intoPixels(); // copies out of wasm memory and frees `decoded`
-    // A fresh ArrayBuffer, so viewing it as clamped bytes copies nothing.
-    const data = new Uint8ClampedArray(pixels.buffer, pixels.byteOffset, pixels.byteLength);
-    return { width, height, data, metadata, chunks };
-}
-/** Turns a flat `r, g, b, …` array into `[r, g, b]` entries. */
-function toPalette(flat) {
-    return Array.from({ length: flat.length / 3 }, (_, i) => [flat[i * 3], flat[i * 3 + 1], flat[i * 3 + 2]]);
-}
-function toRawImage(decoded) {
-    const header = toHeader(decoded.header());
-    const { palette, transparencyKind, transparencyValues } = decoded;
-    const metadata = takeMetadata(decoded);
-    const chunks = decoded.takeChunks().map(toChunk);
-    const data = decoded.intoData(); // copies out of wasm memory and frees `decoded`
-    const image = { header, data, metadata, chunks };
-    if (palette)
-        image.palette = toPalette(palette);
-    if (transparencyKind && transparencyValues)
-        image.transparency = toTransparency(transparencyKind, transparencyValues);
-    return image;
-}
-/**
- * Decodes a PNG in its own format, without conversion: every bit depth and
- * color type as stored, with its palette and transparency. Pass the result to
- * `encode` to re-encode it losslessly. Use `decodeRgba8` to display it.
- */
-export function decode(bytes, options = {}) {
-    return call(() => toRawImage(wasm.decode(bytes, ...decoderArgs(options))));
-}
-/** Decodes a PNG to 8-bit RGBA. Pass options to also read metadata or raw chunks. */
-export function decodeRgba8(bytes, options = {}) {
-    return call(() => toImage(wasm.decodeRgba8(bytes, ...decoderArgs(options))));
-}
-/**
- * Reads and parses every chunk without decompressing the image data, which is
- * much faster than decoding. Known chunks are parsed; every chunk, including
- * private and unknown ones, is also returned raw in file order.
- */
-export function readChunks(bytes, options = {}) {
-    return call(() => toChunks(wasm.readChunks(bytes, options.validateCrc ?? true, options.strictAncillary ?? false), bytes));
-}
-/** Parses the data of a `tEXt`, `zTXt` or `iTXt` chunk on its own, for example one from `readChunks`. */
-export function parseText(type, data) {
-    return call(() => toText(wasm.parseText(type, data)));
-}
-/** Pixels per inch from `pHYs`, or undefined if its unit isn't meters. */
-export function pixelsPerInch(dimensions) {
-    if (dimensions.unit !== "meter")
-        return undefined;
-    return { x: dimensions.x * 0.0254, y: dimensions.y * 0.0254 };
-}
-/** Reads the image header without decoding pixels. */
-export function readHeader(bytes) {
-    return call(() => toHeader(wasm.readHeader(bytes)));
-}
-function encoderArgs(options) {
-    return [
-        options.compression ?? 6,
-        options.compressionStrategy ?? "dynamic",
-        options.filter ?? "adaptive",
-        options.keepUnsafeChunks ?? false,
-        options.palette ?? "keep",
-        options.strip ?? "keep",
-    ];
-}
-function toEncodeImage(image) {
-    const { header, data, palette, transparency, metadata, chunks = [] } = image;
-    const target = new wasm.EncodeImage(header.width, header.height, header.bitDepth, header.colorType, header.interlaced, data);
-    try {
-        if (palette)
-            target.setPalette(Uint8Array.from(palette.flat()));
-        if (transparency) {
-            const values = transparency.kind === "palette" ? transparency.alpha : transparency.kind === "gray" ? [transparency.value] : transparency.value;
-            target.setTransparency(transparency.kind, Uint16Array.from(values));
-        }
-        if (metadata) {
-            const { gamma, chromaticities: c, srgb, physicalDimensions: p, time: t, text = [], iccProfile, cicp, exif } = metadata;
-            if (cicp)
-                target.setCicp(cicp.colorPrimaries, cicp.transferFunction, cicp.matrixCoefficients, cicp.fullRange);
-            if (iccProfile)
-                target.setIccProfile(iccProfile.name, iccProfile.profile);
-            if (exif)
-                target.setExif(exif.data);
-            if (gamma !== undefined)
-                target.setGamma(gamma);
-            if (c)
-                target.setChromaticities(new Float64Array([c.white.x, c.white.y, c.red.x, c.red.y, c.green.x, c.green.y, c.blue.x, c.blue.y]));
-            if (srgb)
-                target.setSrgb(srgb);
-            if (p)
-                target.setPhysicalDimensions(p.x, p.y, p.unit);
-            if (t)
-                target.setTime(t.year, t.month, t.day, t.hour, t.minute, t.second);
-            for (const entry of text) {
-                target.addText(entry.chunkType ?? "tEXt", entry.keyword, entry.text, entry.languageTag ?? "", entry.translatedKeyword ?? "", entry.compressed ?? false);
-            }
-        }
-        for (const chunk of chunks)
-            target.addChunk(chunk.type, chunk.data, chunk.position);
-        return target;
-    }
-    catch (error) {
-        target.free();
-        throw error;
-    }
-}
-function rgbaToPngImage(image) {
-    const { width, height, data, metadata, chunks, interlaced = false } = image;
-    return {
-        header: { width, height, bitDepth: 8, colorType: "rgba", interlaced },
-        // A view of the same bytes, so a Uint8ClampedArray isn't copied here.
-        data: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
-        metadata,
-        chunks,
-    };
-}
-/** Encodes `image`, then frees the wasm copy of it. */
-function encodeWith(image, encode) {
-    const target = toEncodeImage(image);
-    try {
-        return encode(target);
-    }
-    finally {
-        target.free();
-    }
-}
-/**
- * Encodes an image in any PNG pixel format, with its palette, transparency,
- * metadata and raw chunks.
- */
-export function encode(image, options = {}) {
-    return call(() => encodeWith(image, (target) => wasm.encode(target, ...encoderArgs(options))));
-}
-/**
- * Encodes 8-bit RGBA pixels: the reverse of `decodeRgba8`. Pass a decoded
- * `RgbaImage` to re-encode it with its metadata and chunks, or the `ImageData`
- * of a canvas.
- */
-export function encodeRgba8(image, options = {}) {
-    return encode(rgbaToPngImage(image), options);
-}
-/** Wraps an image for `CanvasRenderingContext2D.putImageData`. Browser only. */
-export function toImageData(image) {
-    return new ImageData(image.data, image.width, image.height);
-}
-/**
- * A decoder for many images: it keeps its buffers in wasm memory between calls.
- * Call `free()` when you're done with it.
- */
-export class PngDecoder {
-    #inner;
-    constructor(options = {}) {
-        this.#inner = call(() => new wasm.Decoder(...decoderArgs(options)));
-    }
-    decodeRgba8(bytes) {
-        return call(() => toImage(this.#inner.decodeRgba8(bytes)));
-    }
-    /** Like the `decode` function. */
-    decode(bytes) {
-        return call(() => toRawImage(this.#inner.decode(bytes)));
-    }
-    /** Like the `readChunks` function. Only the `validateCrc` and `strictAncillary` options apply. */
-    readChunks(bytes) {
-        return call(() => toChunks(this.#inner.readChunks(bytes), bytes));
-    }
-    free() {
-        this.#inner.free();
-    }
-}
-/**
- * An encoder for many images: it keeps its compressor and buffers in wasm
- * memory between calls. Call `free()` when you're done with it.
- */
-export class PngEncoder {
-    #inner;
-    constructor(options = {}) {
-        this.#inner = call(() => new wasm.Encoder(...encoderArgs(options)));
-    }
-    /** Like the `encode` function, with this encoder's options. */
-    encode(image) {
-        return call(() => encodeWith(image, (target) => this.#inner.encode(target)));
-    }
-    /** Like the `encodeRgba8` function, with this encoder's options. */
-    encodeRgba8(image) {
-        return this.encode(rgbaToPngImage(image));
-    }
-    free() {
-        this.#inner.free();
-    }
-}
+export { PngDecoder, PngEncoder, PngError, decode, decodeRgba8, encode, encodeRgba8, init, parseText, pixelsPerInch, readChunks, readHeader, toImageData, } from "./core.js";
+export { createWorkerPool, WorkerPoolError } from "./pool.js";
+export { decodeAsync, decodeRgba8Async, defaultWorkerPool, encodeAsync, encodeRgba8Async, parseTextAsync, readChunksAsync, readHeaderAsync, terminateDefaultWorkerPool, } from "./async.js";

package/dist/pool.d.ts

@@ -0,0 +1,82 @@
+import { type DecodeOptions, type EncodeOptions, type PngChunks, type PngHeader, type PngImage, type PngText, type RawImage, type ReadChunksOptions, type RgbaImage, type RgbaImageInput } from "./core.js";
+/** The parts of a Node `worker_threads` `Worker` a pool uses. */
+export interface NodeWorkerLike {
+    postMessage(value: unknown, transferList?: readonly ArrayBuffer[]): void;
+    on(event: "message" | "error" | "messageerror" | "exit", listener: (value: any) => void): unknown;
+    terminate(): unknown;
+    ref?(): void;
+    unref?(): void;
+}
+export interface WorkerPoolOptions {
+    /**
+     * The most workers to run at once. Default: the number of CPU cores
+     * (`navigator.hardwareConcurrency`, or `os.availableParallelism()` in Node),
+     * at most 8.
+     */
+    size?: number;
+    /**
+     * Starts a worker running format-png's worker script, instead of the pool
+     * starting one itself. Only needed with bundlers that don't bundle
+     * `new Worker(new URL("./worker.js", import.meta.url))`, such as esbuild, or
+     * to start workers your own way.
+     */
+    createWorker?: () => Worker | NodeWorkerLike;
+}
+/** Options for one job, taken by every `WorkerPool` method alongside its usual options. */
+export interface JobOptions {
+    /**
+     * Move the input's `ArrayBuffer` to the worker instead of copying it.
+     * Default false. The buffer is detached as soon as the method is called:
+     * the input, and every other view of the same buffer, becomes empty. It
+     * must be a plain `ArrayBuffer`, not a `SharedArrayBuffer`. For `encode`
+     * and `encodeRgba8` this applies to `image.data`; the rest is copied.
+     */
+    transfer?: boolean;
+    /**
+     * Cancels the job, rejecting it with `signal.reason`. A queued job is taken
+     * off the queue; a running one has its worker stopped and replaced.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Runs format-png in Web Workers (or worker_threads in Node), so decoding and
+ * encoding don't block the calling thread. Each method takes the same
+ * arguments as the function of the same name and resolves to the same result,
+ * or rejects with the same `PngError`.
+ *
+ * Workers start when jobs need them, at most `size`, and stay alive between
+ * jobs until `terminate()`. Jobs queue when every worker is busy and start in
+ * the order they were submitted.
+ */
+export interface WorkerPool {
+    /** The most workers this pool runs at once. */
+    readonly size: number;
+    decode(bytes: Uint8Array, options?: DecodeOptions & JobOptions): Promise<RawImage>;
+    decodeRgba8(bytes: Uint8Array, options?: DecodeOptions & JobOptions): Promise<RgbaImage>;
+    /**
+     * As with the `readChunks` function, each chunk's `data` is a view into
+     * `bytes`; with `transfer: true`, into a buffer moved back from the worker.
+     */
+    readChunks(bytes: Uint8Array, options?: ReadChunksOptions & JobOptions): Promise<PngChunks>;
+    readHeader(bytes: Uint8Array, options?: JobOptions): Promise<PngHeader>;
+    parseText(type: PngText["chunkType"], data: Uint8Array, options?: JobOptions): Promise<PngText>;
+    encode(image: PngImage, options?: EncodeOptions & JobOptions): Promise<Uint8Array>;
+    encodeRgba8(image: RgbaImageInput, options?: EncodeOptions & JobOptions): Promise<Uint8Array>;
+    /**
+     * Stops every worker. Queued and running jobs, and every later call, reject
+     * with a `WorkerPoolError` whose `code` is "terminated".
+     */
+    terminate(): Promise<void>;
+}
+/**
+ * A job that failed because of the pool rather than the PNG: "terminated" if
+ * the pool was terminated, "worker-crashed" if its worker stopped unexpectedly
+ * (the pool replaces it).
+ */
+export declare class WorkerPoolError extends Error {
+    readonly code: "terminated" | "worker-crashed";
+    name: string;
+    constructor(code: "terminated" | "worker-crashed", message: string);
+}
+/** Creates a pool of workers. Nothing starts until the first job. */
+export declare function createWorkerPool(options?: WorkerPoolOptions): WorkerPool;