@pixagram/pixahash 0.1.0

package/pool.js

@@ -0,0 +1,193 @@
+// @pixagram/pixahash/pool — data-parallel hashing across a pool of workers.
+//
+// For a single 5–30 kB hash the worker round-trip costs more than the hash
+// itself (microseconds). A pool wins when you (a) want to keep the UI thread
+// free during a burst of work, or (b) need to hash *many* items in parallel.
+//
+//   import { createPool } from '@pixagram/pixahash/pool';
+//   const pool = await createPool();              // size = CPU count
+//   const id   = await pool.hash128(bytes);       // -> BigInt
+//   const ids  = await Promise.all(items.map((x) => pool.hashHex(x, 0, 256)));
+//   pool.destroy();
+//
+// Data is copied to the worker by default (your buffers stay intact). Pass
+// `{ transfer: true }` at construction to move buffers instead (faster for
+// large inputs, but it neuters the caller's ArrayBuffer).
+
+import { toSeed64 } from "./index.js";
+
+const isNode =
+  typeof process !== "undefined" &&
+  process.versions != null &&
+  process.versions.node != null;
+
+const workerURL = new URL("./worker.js", import.meta.url);
+
+function defaultSize() {
+  if (!isNode && typeof navigator !== "undefined" && navigator.hardwareConcurrency) {
+    return Math.max(1, navigator.hardwareConcurrency);
+  }
+  if (isNode) {
+    // Lazy: avoid a static import of os just for this.
+    try {
+      // eslint-disable-next-line no-undef
+      return Math.max(1, require("node:os").cpus().length);
+    } catch {
+      /* ESM: fall through */
+    }
+  }
+  return 4;
+}
+
+async function spawn(onMessage, onError) {
+  if (isNode) {
+    const { Worker } = await import("node:worker_threads");
+    const wk = new Worker(workerURL);
+    wk.on("message", onMessage);
+    wk.on("error", onError);
+    return {
+      post: (msg, transfer) => wk.postMessage(msg, transfer),
+      terminate: () => wk.terminate(),
+    };
+  }
+  const wk = new Worker(workerURL, { type: "module" });
+  wk.onmessage = (e) => onMessage(e.data);
+  wk.onerror = onError;
+  return {
+    post: (msg, transfer) => wk.postMessage(msg, transfer),
+    terminate: () => wk.terminate(),
+  };
+}
+
+export class HashPool {
+  constructor(opts = {}) {
+    this.size = Math.max(1, opts.size || defaultSize());
+    this.transfer = !!opts.transfer;
+    this._workers = [];
+    this._idle = [];
+    this._queue = [];
+    this._pending = new Map(); // id -> { resolve, reject }
+    this._seq = 0;
+    this._started = null;
+    this._destroyed = false;
+  }
+
+  /** Spawn the workers. Idempotent; awaited automatically by the hash methods. */
+  start() {
+    if (this._started) return this._started;
+    this._started = (async () => {
+      const onError = (err) => this._failAll(err);
+      for (let i = 0; i < this.size; i++) {
+        const worker = await spawn((m) => this._onMessage(worker, m), onError);
+        worker.busy = false;
+        this._workers.push(worker);
+        this._idle.push(worker);
+      }
+      this._drain();
+    })();
+    return this._started;
+  }
+
+  _onMessage(worker, msg) {
+    const entry = this._pending.get(msg.id);
+    if (entry) {
+      this._pending.delete(msg.id);
+      if (msg.error) entry.reject(new Error(msg.error));
+      else entry.resolve(msg.result);
+    }
+    worker.busy = false;
+    this._idle.push(worker);
+    this._drain();
+  }
+
+  _failAll(err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    for (const { reject } of this._pending.values()) reject(e);
+    this._pending.clear();
+    for (const t of this._queue.splice(0)) t.reject(e);
+  }
+
+  _drain() {
+    while (this._idle.length && this._queue.length) {
+      const worker = this._idle.pop();
+      const task = this._queue.shift();
+      worker.busy = true;
+      this._pending.set(task.id, task);
+      worker.post(task.msg, task.transfer);
+    }
+  }
+
+  _submit(op, data, seed, bits, extra) {
+    if (this._destroyed) {
+      return Promise.reject(new Error("pixahash: pool has been destroyed."));
+    }
+    const id = ++this._seq;
+    const msg = { id, op, data, seed: toSeed64(seed), bits, ...extra };
+
+    let transfer;
+    if (this.transfer) {
+      if (data instanceof ArrayBuffer) transfer = [data];
+      else if (ArrayBuffer.isView(data)) transfer = [data.buffer];
+    }
+
+    const p = new Promise((resolve, reject) => {
+      this._queue.push({ id, msg, transfer, resolve, reject });
+    });
+    // Ensure workers exist, then dispatch.
+    this.start().then(() => this._drain());
+    return p;
+  }
+
+  hash32(data, seed) {
+    return this._submit("hash32", data, seed);
+  }
+  hash64(data, seed) {
+    return this._submit("hash64", data, seed);
+  }
+  hash128(data, seed) {
+    return this._submit("hash128", data, seed);
+  }
+  hashHex(data, seed, bits) {
+    return this._submit("hashHex", data, seed, bits);
+  }
+  hashBase58(data, seed, bits) {
+    return this._submit("hashBase58", data, seed, bits);
+  }
+  digest(data, seed) {
+    return this._submit("digest", data, seed);
+  }
+
+  /**
+   * Hash an array of items in a single round-trip on one worker. Cheaper than
+   * one message per item when you have many small inputs; less parallel than
+   * dispatching them individually. `op` defaults to "hash64".
+   */
+  hashMany(items, { op = "hash64", seed, bits } = {}) {
+    return this._submit("hashMany", items, seed, bits, { innerOp: op });
+  }
+
+  /** Terminate all workers and reject anything still in flight. */
+  async destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._failAll(new Error("pixahash: pool destroyed."));
+    await this.start().catch(() => {});
+    await Promise.all(this._workers.map((w) => w.terminate()));
+    this._workers = [];
+    this._idle = [];
+  }
+
+  /** Alias for destroy(). */
+  terminate() {
+    return this.destroy();
+  }
+}
+
+/** Construct and fully start a HashPool. */
+export async function createPool(opts = {}) {
+  const pool = new HashPool(opts);
+  await pool.start();
+  return pool;
+}
+
+export default { HashPool, createPool };

package/worker.js

@@ -0,0 +1,70 @@
+// @pixagram/pixahash/worker — isomorphic worker entry.
+//
+// Runs hashing off the calling thread. Used by HashPool, but you can also drive
+// it directly. Works as a browser Module Worker and as a Node worker_threads
+// worker. Protocol (one message per request):
+//
+//   in:  { id, op, data, seed, bits }
+//   out: { id, result }            on success
+//        { id, error: string }     on failure
+//
+// `op` is one of: hash32 | hash64 | hash128 | hashHex | hashBase58 | digest
+//                 | hashMany  (data = array of items; result = array)
+// `data` is a string | ArrayBuffer | Uint8Array (or array thereof for hashMany).
+
+import { ready, hash32, hash64, hash128, hashHex, hashBase58, digest } from "./index.js";
+
+const OPS = {
+  hash32: (d, s) => hash32(d, s),
+  hash64: (d, s) => hash64(d, s),
+  hash128: (d, s) => hash128(d, s),
+  hashHex: (d, s, b) => hashHex(d, s, b),
+  hashBase58: (d, s, b) => hashBase58(d, s, b),
+  digest: (d, s) => digest(d, s),
+};
+
+const isNode =
+  typeof process !== "undefined" &&
+  process.versions != null &&
+  process.versions.node != null;
+
+let post;
+
+if (isNode) {
+  const { parentPort } = await import("node:worker_threads");
+  post = (msg, transfer) => parentPort.postMessage(msg, transfer);
+  parentPort.on("message", handle);
+} else {
+  post = (msg, transfer) => self.postMessage(msg, transfer);
+  self.onmessage = (e) => handle(e.data);
+}
+
+// Pre-warm so the first real request doesn't pay the init cost.
+ready();
+
+function run(op, data, seed, bits) {
+  const fn = OPS[op];
+  if (!fn) throw new Error(`pixahash worker: unknown op "${op}"`);
+  return fn(data, seed, bits);
+}
+
+async function handle(msg) {
+  const { id, op, data, seed, bits } = msg;
+  try {
+    await ready();
+    let result;
+    if (op === "hashMany") {
+      const inner = OPS[msg.innerOp || "hash64"];
+      if (!inner) throw new Error(`pixahash worker: unknown op "${msg.innerOp}"`);
+      result = data.map((d) => inner(d, seed, bits));
+    } else {
+      result = run(op, data, seed, bits);
+    }
+
+    // Transfer digest buffers back to avoid a copy.
+    const transfer = result instanceof Uint8Array ? [result.buffer] : undefined;
+    post({ id, result }, transfer);
+  } catch (err) {
+    post({ id, error: err && err.message ? err.message : String(err) });
+  }
+}