@dbx-tools/shared-core 0.3.29 → 0.3.31

package/package.json

@@ -15,14 +15,14 @@
     "consola": "^3.4.2"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "4.3.6"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.29",
+  "version": "0.3.31",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/async.ts

@@ -183,6 +183,34 @@ export function tieAbortSignal(child: AbortController, parent?: AbortSignal): vo
   });
 }
 
+/**
+ * Combine several optional cancellation sources into one signal that aborts
+ * as soon as any of them does.
+ *
+ * The usual caller is an operation that has to honor more than one source at
+ * once - a caller's own signal (a closed connection, an agent run being
+ * cancelled) plus one derived from a timeout - where the awaited I/O accepts
+ * only a single signal. Absent sources are ignored, and a lone signal is
+ * returned as-is so the common path allocates nothing. Returns `undefined`
+ * only when every input is absent, which callers can pass straight through
+ * to an optional `signal` parameter.
+ *
+ * Aborting an input aborts the result (carrying that input's `reason`);
+ * nothing propagates back the other way.
+ *
+ * @example
+ * await fetch(url, { signal: combineAbortSignals(req.signal, timeout.signal) });
+ */
+export function combineAbortSignals(
+  ...signals: (AbortSignal | undefined)[]
+): AbortSignal | undefined {
+  const present = signals.filter((signal): signal is AbortSignal => signal !== undefined);
+  if (present.length <= 1) return present[0];
+  const combined = new AbortController();
+  for (const signal of present) tieAbortSignal(combined, signal);
+  return combined.signal;
+}
+
 /**
  * Promisified `setTimeout` that wakes up early (and rejects with
  * `signal.reason`) when `signal` aborts mid-wait. Short-circuits to a

package/src/hash.ts

@@ -22,8 +22,13 @@
  *   id has to be short / typeable and the scope is bounded - cache keys
  *   local to a request, slug suffixes. `length <= 0` throws.
  *
- * Built on `globalThis.crypto.randomUUID()` so the same function works in
- * Node (>= 19) and modern browsers without a polyfill.
+ * Prefers `crypto.randomUUID()`, which covers Node (>= 19) and a browser on
+ * a secure origin. Browsers gate `randomUUID` behind a secure context, so a
+ * page served over plain http (a LAN dev host) has `crypto` but not that
+ * method; this package is browser-safe and its callers mint ids on the
+ * render path, so it degrades instead of throwing: `getRandomValues` when
+ * present, else `Math.random`. Every branch returns a well-formed v4 UUID -
+ * only the entropy source differs.
  *
  * @example
  * id();   // "123e4567-e89b-12d3-a456-426614174000"
@@ -33,13 +38,32 @@ export function id(length?: number): string {
   if (length !== undefined && length <= 0) {
     throw new Error("Length must be greater than 0");
   }
-  const id = globalThis.crypto.randomUUID();
+  const id = uuidV4();
   if (length !== undefined) {
     return id.replace(/-/g, "").slice(0, length);
   }
   return id;
 }
 
+/** A v4 UUID from the strongest randomness source this runtime offers. */
+function uuidV4(): string {
+  const webCrypto = globalThis.crypto as Crypto | undefined;
+  if (typeof webCrypto?.randomUUID === "function") return webCrypto.randomUUID();
+
+  const bytes = new Uint8Array(16);
+  if (typeof webCrypto?.getRandomValues === "function") {
+    webCrypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  // Stamp the version (4) and variant (10xx) fields RFC 4122 requires.
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
 /**
  * Short, deterministic FNV-1a hash over one or more values. Wraps
  * {@link fnvHashWithOptions} with all defaults: 6-char Crockford-style

package/test/async.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { async } from "../index";
+
+describe("async.combineAbortSignals", () => {
+  it("returns undefined when every source is absent", () => {
+    assert.equal(async.combineAbortSignals(), undefined);
+    assert.equal(async.combineAbortSignals(undefined, undefined), undefined);
+  });
+
+  it("passes a lone signal through without wrapping it", () => {
+    const { signal } = new AbortController();
+    assert.equal(async.combineAbortSignals(signal), signal);
+    assert.equal(async.combineAbortSignals(undefined, signal, undefined), signal);
+  });
+
+  it("aborts when any source aborts, carrying that source's reason", () => {
+    for (const index of [0, 1, 2]) {
+      const controllers = [new AbortController(), new AbortController(), new AbortController()];
+      const combined = async.combineAbortSignals(...controllers.map((c) => c.signal));
+      assert.equal(combined?.aborted, false);
+      controllers[index]!.abort(new Error(`source ${index}`));
+      assert.equal(combined?.aborted, true);
+      assert.equal((combined?.reason as Error).message, `source ${index}`);
+    }
+  });
+
+  it("is already aborted when a source aborted before combining", () => {
+    const early = new AbortController();
+    early.abort(new Error("gone"));
+    const combined = async.combineAbortSignals(early.signal, new AbortController().signal);
+    assert.equal(combined?.aborted, true);
+    assert.equal((combined?.reason as Error).message, "gone");
+  });
+
+  it("does not propagate back to the sources", () => {
+    const first = new AbortController();
+    const second = new AbortController();
+    const combined = async.combineAbortSignals(first.signal, second.signal);
+    first.abort();
+    assert.equal(combined?.aborted, true);
+    assert.equal(second.signal.aborted, false);
+  });
+});

package/test/hash.test.ts

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { hash } from "../index";
+
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+const original = globalThis.crypto;
+
+const withCrypto = (value: unknown, body: () => void) => {
+  Object.defineProperty(globalThis, "crypto", { value, configurable: true, writable: true });
+  try {
+    body();
+  } finally {
+    Object.defineProperty(globalThis, "crypto", {
+      value: original,
+      configurable: true,
+      writable: true,
+    });
+  }
+};
+
+describe("hash.id", () => {
+  afterEach(() => {
+    assert.equal(globalThis.crypto, original);
+  });
+
+  it("mints a v4 UUID from crypto.randomUUID when available", () => {
+    assert.match(hash.id(), UUID_V4);
+    assert.notEqual(hash.id(), hash.id());
+  });
+
+  it("returns a short hex slice when a length is given", () => {
+    assert.match(hash.id(8), /^[0-9a-f]{8}$/);
+    assert.equal(hash.id(1).length, 1);
+  });
+
+  it("rejects a non-positive length", () => {
+    assert.throws(() => hash.id(0), /greater than 0/);
+    assert.throws(() => hash.id(-1), /greater than 0/);
+  });
+
+  it("falls back to getRandomValues where randomUUID is absent (plain-http browser)", () => {
+    withCrypto({ getRandomValues: original.getRandomValues.bind(original) }, () => {
+      assert.match(hash.id(), UUID_V4);
+      assert.notEqual(hash.id(), hash.id());
+    });
+  });
+
+  it("falls back to Math.random where crypto is absent entirely", () => {
+    withCrypto(undefined, () => {
+      assert.match(hash.id(), UUID_V4);
+      assert.match(hash.id(12), /^[0-9a-f]{12}$/);
+    });
+  });
+});