format-png 0.2.0 → 0.3.0

package/dist/pool.js

@@ -0,0 +1,407 @@
+import { defaultSize, spawnWorker } from "#spawn";
+import { PngError, } from "./core.js";
+/**
+ * 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 class WorkerPoolError extends Error {
+    code;
+    name = "WorkerPoolError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const terminated = () => new WorkerPoolError("terminated", "format-png: the worker pool was terminated");
+/** Creates a pool of workers. Nothing starts until the first job. */
+export function createWorkerPool(options = {}) {
+    const size = options.size ?? Math.min(Math.max(defaultSize(), 1), 8);
+    if (!Number.isInteger(size) || size < 1)
+        throw new RangeError(`format-png: a worker pool's size must be a whole number of at least 1, not ${size}`);
+    return new Pool(size, options.createWorker ?? spawnWorker);
+}
+function isNodeWorker(worker) {
+    return typeof worker.on === "function";
+}
+function wrap(worker, onResponse, onCrash) {
+    if (isNodeWorker(worker)) {
+        worker.on("message", onResponse);
+        worker.on("error", (error) => onCrash(error instanceof Error ? error.message : String(error)));
+        worker.on("messageerror", () => onCrash("a message from the worker couldn't be read"));
+        worker.on("exit", (code) => onCrash(`the worker exited with code ${code}`));
+        return {
+            post: (request, transfer) => worker.postMessage(request, transfer),
+            terminate: async () => void (await worker.terminate()),
+            keepAlive: (on) => (on ? worker.ref?.() : worker.unref?.()),
+        };
+    }
+    worker.addEventListener("message", (event) => onResponse(event.data));
+    worker.addEventListener("error", (event) => {
+        event.preventDefault();
+        onCrash(event.message || "the worker failed to start or threw an uncaught error");
+    });
+    worker.addEventListener("messageerror", () => onCrash("a message from the worker couldn't be read"));
+    return {
+        post: (request, transfer) => worker.postMessage(request, transfer),
+        terminate: async () => worker.terminate(),
+        keepAlive: () => { },
+    };
+}
+const errorClasses = { TypeError, RangeError, SyntaxError, ReferenceError };
+function toError({ name, message }) {
+    if (name === "PngError")
+        return new PngError(message);
+    const error = new (errorClasses[name] ?? Error)(message);
+    error.name = name;
+    return error;
+}
+/**
+ * A copy of `bytes` the pool owns, with a buffer of its own: copied, or moved
+ * with `transfer`, which detaches the caller's buffer now rather than when the
+ * job starts.
+ */
+function own(bytes, transfer) {
+    // Uint8Array or Uint8ClampedArray, never a subclass: a Node Buffer's `slice` doesn't copy.
+    const Type = (bytes instanceof Uint8ClampedArray ? Uint8ClampedArray : Uint8Array);
+    if (!transfer)
+        return new Type(bytes);
+    const { buffer, byteOffset, length } = bytes;
+    if (!(buffer instanceof ArrayBuffer))
+        throw new TypeError("format-png: `transfer` needs an ArrayBuffer; a SharedArrayBuffer can't be transferred");
+    return new Type(structuredClone(buffer, { transfer: [buffer] }), byteOffset, length);
+}
+/** The options to send to the worker: without `transfer` and `signal`, which can't be cloned. */
+function workerOptions(options) {
+    const { transfer: _transfer, signal: _signal, ...rest } = options;
+    return rest;
+}
+const crashed = (message) => new WorkerPoolError("worker-crashed", `format-png: a worker crashed: ${message}`);
+/**
+ * Schedules tasks on workers. A worker runs one task at a time. When one is
+ * free, it first runs its pinned tasks, then the next task of the next job, in
+ * turn: a job split into many segments doesn't hold up the jobs after it.
+ * Nothing waits while holding a worker, so nothing can deadlock: a prepared
+ * image waiting for its segments only takes memory in the worker that holds
+ * it, which runs other tasks meanwhile, including those segments.
+ */
+class Pool {
+    size;
+    #createWorker;
+    #slots = [];
+    /** Jobs with queued tasks, in order; `#next` is the one whose turn it is. */
+    #jobs = [];
+    #next = 0;
+    /** Every job not settled yet. */
+    #active = new Set();
+    #nextId = 1;
+    #nextHandle = 1;
+    #terminated = false;
+    constructor(size, createWorker) {
+        this.size = size;
+        this.#createWorker = createWorker;
+    }
+    async decode(bytes, options = {}) {
+        this.#check(options);
+        const input = own(bytes, options.transfer);
+        return this.#single("decode", [input, workerOptions(options)], [input.buffer], options);
+    }
+    async decodeRgba8(bytes, options = {}) {
+        this.#check(options);
+        const input = own(bytes, options.transfer);
+        return this.#single("decodeRgba8", [input, workerOptions(options)], [input.buffer], options);
+    }
+    async readChunks(bytes, options = {}) {
+        this.#check(options);
+        const input = own(bytes, options.transfer);
+        const returnInput = options.transfer ?? false;
+        return this.#single("readChunks", [input, workerOptions(options)], [input.buffer], options, (value) => {
+            // The worker sent each chunk's data as its length. Rebuilt as views
+            // into the caller's bytes, as `readChunks` returns, or into the
+            // input moved back from the worker.
+            const { chunks, input: returned } = value;
+            const base = returned ?? bytes;
+            for (const chunk of chunks.chunks) {
+                const length = chunk.data;
+                chunk.data = base.subarray(chunk.offset + 8, chunk.offset + 8 + length);
+            }
+            return chunks;
+        }, returnInput);
+    }
+    async readHeader(bytes, options = {}) {
+        this.#check(options);
+        const input = own(bytes, options.transfer);
+        return this.#single("readHeader", [input], [input.buffer], options);
+    }
+    async parseText(type, data, options = {}) {
+        this.#check(options);
+        const input = own(data, options.transfer);
+        return this.#single("parseText", [type, input], [input.buffer], options);
+    }
+    async encode(image, options = {}) {
+        this.#check(options);
+        const data = own(image.data, options.transfer);
+        return this.#encode("encode", { ...image, data }, data.buffer, options);
+    }
+    async encodeRgba8(image, options = {}) {
+        this.#check(options);
+        // Only the fields `encodeRgba8` reads: an `ImageData` would otherwise be cloned whole.
+        const { width, height, metadata, chunks, interlaced } = image;
+        const data = own(image.data, options.transfer);
+        return this.#encode("encodeRgba8", { width, height, data, metadata, chunks, interlaced }, data.buffer, options);
+    }
+    async terminate() {
+        this.#terminated = true;
+        for (const job of this.#active)
+            this.#fail(job, terminated());
+        await Promise.all(this.#slots.splice(0).map((slot) => this.#retire(slot)));
+    }
+    /** Throws if the job can't start, before its input is copied or detached. */
+    #check(options) {
+        if (this.#terminated)
+            throw terminated();
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+    }
+    /** A job of one task, whose answer `finish` turns into the result. */
+    #single(op, args, transfer, options, finish = (value) => value, returnInput) {
+        return this.#submit(options, (job) => ({
+            job, op, args, transfer,
+            request: returnInput ? { returnInput } : undefined,
+            done: (value) => this.#succeed(job, finish(value)),
+        }));
+    }
+    /**
+     * Encodes on one worker with `threads: "single"`. Otherwise, by default,
+     * prepares the image on one worker and compresses its segments on all of
+     * them: the same bytes as `threads: "auto"`.
+     */
+    #encode(op, image, buffer, options) {
+        const threads = options.threads ?? "auto";
+        const args = [image, { ...workerOptions(options), threads }];
+        if (threads === "single")
+            return this.#single(op, args, [buffer], options);
+        const handle = this.#nextHandle++;
+        return this.#submit(options, (job) => ({
+            job, op, args, transfer: [buffer],
+            request: { split: true, handle },
+            done: (value, slot) => this.#prepared(job, slot, handle, value),
+        }));
+    }
+    /** A split encode's image is prepared: queues its segments, then its "finish" on the worker that prepared it. */
+    #prepared(job, slot, handle, value) {
+        if ("png" in value) {
+            this.#succeed(job, value.png); // small enough to have no segments
+            return;
+        }
+        job.prepared = { slot, handle };
+        slot.holds.add(job);
+        if (job.settled) {
+            this.#free(job); // cancelled while it was being prepared
+            return;
+        }
+        const { segments, level, strategy } = value;
+        const compressed = new Array(segments.length);
+        let remaining = segments.length;
+        job.queue = segments.map((segment, i) => ({
+            job,
+            op: "compressSegment",
+            args: [segment, level, strategy],
+            transfer: [segment.buffer],
+            done: (result) => {
+                if (job.settled)
+                    return;
+                compressed[i] = result;
+                if (--remaining > 0)
+                    return;
+                job.finishing = true;
+                slot.pinned.push({
+                    job,
+                    op: "finish",
+                    args: [handle, compressed],
+                    transfer: compressed.map((part) => part.buffer),
+                    after: () => {
+                        slot.holds.delete(job);
+                        job.prepared = undefined;
+                    },
+                    done: (png) => this.#succeed(job, png),
+                });
+            },
+        }));
+        this.#jobs.push(job);
+    }
+    /** Frees the job's prepared image, if it has one that "finish" won't free. */
+    #free(job) {
+        const { prepared } = job;
+        if (!prepared || job.finishing)
+            return;
+        job.prepared = undefined;
+        const { slot, handle } = prepared;
+        slot.pinned.push({ job, op: "free", args: [handle], transfer: [], after: () => slot.holds.delete(job), done: () => { } });
+    }
+    #submit(options, first) {
+        const { signal } = options;
+        return new Promise((resolve, reject) => {
+            const job = { queue: [], running: new Set(), finishing: false, settled: false, resolve, reject, signal };
+            job.queue.push(first(job));
+            if (signal) {
+                job.onAbort = () => this.#abort(job);
+                signal.addEventListener("abort", job.onAbort, { once: true });
+            }
+            this.#active.add(job);
+            this.#jobs.push(job);
+            this.#pump();
+        });
+    }
+    /** Starts tasks on idle workers, starting workers as needed. */
+    #pump() {
+        for (;;) {
+            for (const slot of this.#slots) {
+                if (!slot.task && slot.pinned.length > 0)
+                    this.#run(slot, slot.pinned.shift());
+            }
+            if (this.#jobs.length === 0)
+                return;
+            let slot = this.#slots.find((candidate) => !candidate.task);
+            if (!slot) {
+                if (this.#slots.length >= this.size)
+                    return;
+                try {
+                    slot = this.#spawn();
+                }
+                catch (error) {
+                    this.#fail(this.#jobs[0], error);
+                    continue;
+                }
+            }
+            // Round robin: the next job's next task.
+            if (this.#next >= this.#jobs.length)
+                this.#next = 0;
+            const job = this.#jobs[this.#next];
+            const task = job.queue.shift();
+            if (job.queue.length === 0)
+                this.#jobs.splice(this.#next, 1);
+            else
+                this.#next++;
+            this.#run(slot, task);
+        }
+    }
+    #run(slot, task) {
+        const id = this.#nextId++;
+        slot.task = task;
+        slot.taskId = id;
+        task.job.running.add(slot);
+        slot.worker.keepAlive(true);
+        try {
+            slot.worker.post({ id, op: task.op, args: task.args, ...task.request }, task.transfer);
+        }
+        catch (error) {
+            slot.task = undefined;
+            task.job.running.delete(slot);
+            slot.worker.keepAlive(false);
+            task.after?.();
+            this.#fail(task.job, error);
+        }
+    }
+    #spawn() {
+        const slot = { worker: undefined, pinned: [], holds: new Set(), retired: false };
+        slot.worker = wrap(this.#createWorker(), (response) => this.#onResponse(slot, response), (message) => this.#onCrash(slot, message));
+        slot.worker.keepAlive(false);
+        this.#slots.push(slot);
+        return slot;
+    }
+    #onResponse(slot, response) {
+        const { task } = slot;
+        if (slot.retired || !task || slot.taskId !== response.id)
+            return;
+        slot.task = undefined;
+        task.job.running.delete(slot);
+        slot.worker.keepAlive(false);
+        task.after?.();
+        if (!response.ok) {
+            this.#fail(task.job, toError(response.error));
+            // A trap: the worker goes, with any other job's prepared image.
+            if (response.retire)
+                void this.#retire(slot, crashed("its WebAssembly instance failed"));
+        }
+        else {
+            try {
+                task.done(response.value, slot);
+            }
+            catch (error) {
+                this.#fail(task.job, error);
+            }
+        }
+        this.#pump();
+    }
+    #onCrash(slot, message) {
+        if (slot.retired)
+            return;
+        void this.#retire(slot, crashed(message));
+        this.#pump();
+    }
+    #abort(job) {
+        if (job.settled)
+            return;
+        // Running tasks: wasm can't be interrupted, so their workers go, unless
+        // a worker holds prepared images, which would go with it. Then its task
+        // finishes, and the result is dropped.
+        const stop = [...job.running].filter((slot) => slot.holds.size === 0);
+        this.#fail(job, job.signal.reason);
+        for (const slot of stop)
+            void this.#retire(slot);
+        this.#pump();
+    }
+    /** Rejects the job, drops its queued tasks, and frees its prepared image. */
+    #fail(job, error) {
+        if (job.settled)
+            return;
+        this.#settle(job);
+        job.reject(error);
+        job.queue.length = 0;
+        const index = this.#jobs.indexOf(job);
+        if (index >= 0) {
+            this.#jobs.splice(index, 1);
+            if (index < this.#next)
+                this.#next--;
+        }
+        this.#free(job);
+    }
+    #succeed(job, value) {
+        if (job.settled)
+            return;
+        this.#settle(job);
+        job.resolve(value);
+    }
+    #settle(job) {
+        job.settled = true;
+        this.#active.delete(job);
+        if (job.onAbort)
+            job.signal.removeEventListener("abort", job.onAbort);
+    }
+    /**
+     * Stops a worker. With `error`, the job it was running and every job whose
+     * prepared image it held reject with it.
+     */
+    #retire(slot, error) {
+        slot.retired = true;
+        const index = this.#slots.indexOf(slot);
+        if (index >= 0)
+            this.#slots.splice(index, 1);
+        const { task } = slot;
+        slot.task = undefined;
+        if (task) {
+            task.job.running.delete(slot);
+            if (error)
+                this.#fail(task.job, error);
+        }
+        for (const job of slot.holds) {
+            job.prepared = undefined; // gone with the worker
+            if (error)
+                this.#fail(job, error);
+        }
+        slot.holds.clear();
+        slot.pinned.length = 0;
+        return slot.worker.terminate().catch(() => { });
+    }
+}

package/dist/port-node.d.ts

@@ -0,0 +1,3 @@
+import type { Request } from "./protocol.js";
+export declare function listen(handler: (request: Request) => void): void;
+export declare function post(message: unknown, transfer: ArrayBuffer[]): void;

package/dist/port-node.js

@@ -0,0 +1,9 @@
+// The worker side of a WorkerPool in Node: worker_threads' `parentPort`.
+import { parentPort } from "node:worker_threads";
+const port = parentPort;
+export function listen(handler) {
+    port.on("message", handler);
+}
+export function post(message, transfer) {
+    port.postMessage(message, transfer);
+}

package/dist/port-web.d.ts

@@ -0,0 +1,3 @@
+import type { Request } from "./protocol.js";
+export declare function listen(handler: (request: Request) => void): void;
+export declare function post(message: unknown, transfer: ArrayBuffer[]): void;

package/dist/port-web.js

@@ -0,0 +1,7 @@
+const scope = self;
+export function listen(handler) {
+    scope.addEventListener("message", (event) => handler(event.data));
+}
+export function post(message, transfer) {
+    scope.postMessage(message, transfer);
+}

package/dist/protocol.d.ts

@@ -0,0 +1,40 @@
+export type Op = "decode" | "decodeRgba8" | "readChunks" | "readHeader" | "parseText" | "encode" | "encodeRgba8" | "compressSegment" | "finish" | "free"
+/** How many prepared images the worker holds: for tests. */
+ | "handles";
+export interface Request {
+    id: number;
+    op: Op;
+    args: unknown[];
+    /** `readChunks` only: send the input back, as the chunks' data are views into it. */
+    returnInput?: boolean;
+    /** `encode` and `encodeRgba8`: prepare the image, keeping it as `handle`, rather than encode it. */
+    split?: boolean;
+    handle?: number;
+}
+/** What an `encode` with `split` returns. */
+export type Prepared = {
+    png: Uint8Array;
+} | {
+    segments: Uint8Array[];
+    level: number;
+    strategy: string;
+};
+export interface SerializedError {
+    name: string;
+    message: string;
+}
+export type Response = {
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: SerializedError;
+    retire: boolean;
+};
+/**
+ * The buffers of every typed array in `value`, to transfer rather than copy.
+ * Only call it on values whose buffers nothing else uses.
+ */
+export declare function buffersIn(value: unknown, found?: Set<ArrayBuffer>): ArrayBuffer[];

package/dist/protocol.js

@@ -0,0 +1,36 @@
+// The messages between a WorkerPool and its workers. The same in browsers and
+// Node; only how a message is posted differs (see spawn-*.ts and port-*.ts).
+//
+// Each worker runs one task at a time:
+//   pool → worker  { id, op, args, returnInput, split, handle }   input buffers transferred
+//   worker → pool  { id, ok: true, value }          output buffers transferred
+//                  { id, ok: false, error, retire } retire: the worker can't be trusted anymore
+//
+// Most jobs are one task. An encode with `split` is several, so one image is
+// compressed by every worker:
+//   1. "encode"/"encodeRgba8", split, handle h, on any worker A. A prepares the
+//      image. With no segments it returns { png }. Otherwise it keeps the
+//      prepared image as h and returns { segments, level, strategy }.
+//   2. "compressSegment" [segment, level, strategy] for each, on any worker.
+//   3. "finish" [h, compressed] on A: the PNG. A drops h, whatever happens.
+//   Or "free" [h] on A, if the job failed or was cancelled first.
+// A worker holding prepared images still runs other tasks between these.
+/**
+ * The buffers of every typed array in `value`, to transfer rather than copy.
+ * Only call it on values whose buffers nothing else uses.
+ */
+export function buffersIn(value, found = new Set()) {
+    if (ArrayBuffer.isView(value)) {
+        if (value.buffer instanceof ArrayBuffer)
+            found.add(value.buffer);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            buffersIn(item, found);
+    }
+    else if (value !== null && typeof value === "object") {
+        for (const item of Object.values(value))
+            buffersIn(item, found);
+    }
+    return [...found];
+}

package/dist/spawn-node.d.ts

@@ -0,0 +1,3 @@
+import { Worker } from "node:worker_threads";
+export declare function spawnWorker(): Worker;
+export declare function defaultSize(): number;

package/dist/spawn-node.js

@@ -0,0 +1,9 @@
+// Starts a WorkerPool worker in Node, with worker_threads.
+import { availableParallelism } from "node:os";
+import { Worker } from "node:worker_threads";
+export function spawnWorker() {
+    return new Worker(new URL("./worker.js", import.meta.url));
+}
+export function defaultSize() {
+    return availableParallelism();
+}

package/dist/spawn-web.d.ts

@@ -0,0 +1,2 @@
+export declare function spawnWorker(): Worker;
+export declare function defaultSize(): number;

package/dist/spawn-web.js

@@ -0,0 +1,9 @@
+// Starts a WorkerPool worker in browsers, bundlers and Web Workers. Written as
+// `new Worker(new URL("./worker.js", import.meta.url), { type: "module" })` so
+// bundlers such as Vite and webpack find and bundle the worker.
+export function spawnWorker() {
+    return new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
+}
+export function defaultSize() {
+    return globalThis.navigator?.hardwareConcurrency || 4;
+}