format-png 0.1.0

package/dist/index.js

@@ -0,0 +1,367 @@
+import initWasm, * as wasm from "./wasm/format_png_wasm.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.
+ *
+ * In browsers and bundlers, call it with no argument: the `.wasm` file is
+ * fetched from next to this module. In Node, pass its bytes:
+ *
+ * ```js
+ * import { readFile } from "node:fs/promises";
+ * await init(await readFile(new URL(import.meta.resolve("format-png/format_png_wasm_bg.wasm"))));
+ * ```
+ *
+ * You can also pass a URL to fetch it from, or a compiled `WebAssembly.Module`.
+ */
+export function init(source) {
+    ready ??= initWasm(source === undefined ? undefined : { module_or_path: source })
+        .then(() => {
+        initialized = true;
+    })
+        .catch((error) => {
+        ready = undefined; // allow a retry
+        throw error;
+    });
+    return ready;
+}
+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();
+    }
+}