@dbx-tools/shared-core 0.3.28 → 0.3.30

package/README.md

@@ -7,7 +7,18 @@ browsers, workers, CLIs, and shared schema packages. Modules are exported as
 namespaces so call sites stay explicit:
 
 ```ts
-import { async, error, hash, http, log, net, object, brand, string } from "@dbx-tools/shared-core";
+import {
+  async,
+  brand,
+  error,
+  hash,
+  http,
+  json,
+  log,
+  net,
+  object,
+  string,
+} from "@dbx-tools/shared-core";
 ```
 
 Node-only helpers live in [`@dbx-tools/core`](../../node/core). AppKit and
@@ -21,8 +32,10 @@ Key features:
   status/message extraction.
 - Deterministic non-cryptographic hashes and short ids for cache keys, slugs,
   and generated names.
-- String normalization helpers for slugs, identifiers, unique labels, and prompt
-  descriptions.
+- Non-throwing JSON parsing for untrusted input, with record narrowing so parsed
+  data is not cast blindly.
+- String normalization helpers for slugs, identifiers, unique labels, human
+  labels, config lists, and prompt descriptions.
 - Object/iterable, predicate, HTTP, cookie, network, token, memoization, and
   logging helpers that avoid Node-only dependencies.
 - Namespace exports that make utility call sites explicit without creating a
@@ -91,6 +104,26 @@ const suffix = hash.fnvHashWithOptions({ length: 6 }, longName);
 These hashes are deterministic and non-cryptographic. Use them for cache keys,
 slug suffixes, and trace-stable identifiers, not secrets or signatures.
 
+## Parsing Untrusted JSON
+
+```ts
+const body = json.parseRecord(await readRequestText(req)) ?? {};
+const chunk = json.parse<StreamChunk>(sseData);
+if (!chunk) continue;
+
+const settings = json.parse<Settings>(process.env.SETTINGS, DEFAULT_SETTINGS);
+```
+
+`json.parse()` returns the fallback (or `undefined`) instead of throwing, so a
+malformed request body, env var, config file, subprocess stdout, or third-party
+response does not need its own `try`/`catch`. `json.parseRecord()` additionally
+narrows to `Record<string, unknown>`, which a bare `JSON.parse(...) as Record<...>`
+does not: it rejects a parsed `null`, array, or scalar rather than letting it
+through as an object.
+
+Reach for `JSON.parse` directly only when a throw is the correct outcome, such as
+reading a file this repo generated itself.
+
 ## Strings And Descriptions
 
 ```ts
@@ -107,6 +140,21 @@ const description = string.toDescription([
 ids, schema ids, and generated labels consistent. `toDescription()` turns nested
 description data into prompt/tool text without hand-concatenating paragraphs.
 
+Three helpers exist so call sites stop re-implementing them:
+
+```ts
+const label = string.toLabel("web_search"); // "Web Search"
+const name = string.capitalize(segment); // no charAt(0).toUpperCase() idiom
+const host = string.trimToEmpty(parsed.host); // unknown JSON field -> string
+const allowed = string.parseList(process.env.ALLOWED_URLS);
+```
+
+`toLabel()` and `capitalize()` are the humanizers for identifiers and path
+segments. `trimToNull()` / `trimToEmpty()` / `firstNonEmpty()` coerce an unknown
+field off parsed JSON. `parseList()` normalizes a config value that may arrive as
+an array or as one comma/whitespace-separated env string, de-duplicating as it
+goes.
+
 ## Objects And Predicates
 
 ```ts
@@ -216,8 +264,9 @@ without paying formatting cost when disabled.
 - `async` - polling, sleep, and abort-signal wiring.
 - `error` - unknown-error normalization and HTTP-ish error context.
 - `hash` - ids, FNV hashes, and base32 encoding.
-- `string` - tokenization, slugs, identifiers, descriptions, pluralization, and
-  HTML escaping.
+- `json` - non-throwing `parse()` and record-narrowing `parseRecord()`.
+- `string` - tokenization, slugs, identifiers, human labels, string coercion,
+  config lists, descriptions, pluralization, and HTML escaping.
 - `object` - record checks, boolean coercion, deep equality, shape types, and
   lazy sequence transforms + collection helpers.
 - `predicate` - composable boolean/type predicates.

package/index.ts

@@ -8,6 +8,7 @@ export * as error from "./src/error";
 export * as functionModule from "./src/function";
 export * as hash from "./src/hash";
 export * as http from "./src/http";
+export * as json from "./src/json";
 export * as log from "./src/log";
 export * as net from "./src/net";
 export * as object from "./src/object";

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.28",
+  "version": "0.3.30",
   "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/src/json.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser-safe JSON helpers for the parse-untrusted-text case.
+ *
+ * `JSON.parse` throws on malformed input and returns `any`, so almost every
+ * caller in this repo wrapped it in the same try/catch and then re-narrowed the
+ * result by hand. {@link parse} collapses the try/catch (a bad document yields
+ * the fallback instead of throwing) and {@link parseRecord} adds the narrowing
+ * that untrusted JSON almost always needs before it can be indexed.
+ *
+ * Use these when the document comes from OUTSIDE the process - a request body,
+ * an env var, a config file, a subprocess's stdout, a third-party API. Keep
+ * bare `JSON.parse` where a throw is the correct outcome (an internally
+ * produced document that must be well-formed).
+ *
+ * These deliberately do NOT validate shape beyond "is it a record". Reach for
+ * a zod schema when the payload has a contract; these only get you from `string`
+ * to a safely typed starting point.
+ *
+ * @module
+ */
+
+import { isRecord } from "./object";
+
+/**
+ * Parse JSON text, returning `fallback` (default `undefined`) instead of
+ * throwing when `text` is absent or malformed.
+ *
+ * The return type is caller-asserted, exactly like `JSON.parse` - this only
+ * removes the try/catch, it does not validate. Prefer {@link parseRecord} or a
+ * schema when the result is indexed.
+ *
+ * @example
+ * const config = json.parse<Config>(await readFile(path, "utf8"));
+ * const tags = json.parse(process.env.TAGS, []);
+ */
+export function parse<T = unknown>(text: unknown, fallback: T): T;
+export function parse<T = unknown>(text: unknown): T | undefined;
+export function parse<T = unknown>(text: unknown, fallback?: T): T | undefined {
+  if (typeof text !== "string" || text.trim().length === 0) return fallback;
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Parse JSON text that is expected to be an object, returning `undefined` when
+ * it is absent, malformed, or parses to a non-record (an array, a bare string,
+ * `null`, ...).
+ *
+ * This is the common case for manifests, env-var config blobs, and untyped API
+ * payloads: {@link parse} followed by {@link isRecord}, so the result can be
+ * indexed without an `as Record<string, unknown>` cast.
+ *
+ * @example
+ * const manifest = json.parseRecord(await readFile("package.json", "utf8")) ?? {};
+ * const name = manifest.name;
+ */
+export function parseRecord(text: unknown): Record<string, unknown> | undefined {
+  const parsed = parse(text);
+  return isRecord(parsed) ? parsed : undefined;
+}

package/src/string.ts

@@ -115,7 +115,7 @@ export function* tokenizeWithOptions(
     for (const tokenMatch of stringValue.matchAll(regexp)) {
       let token = tokenMatch[0]!;
       if (opts.lowerCase) token = token.toLowerCase();
-      if (opts.capitalize) token = token.charAt(0).toUpperCase() + token.slice(1);
+      if (opts.capitalize) token = capitalize(token);
       if (!token) continue;
       for (const override of TOKENIZE_OVERRIDES) {
         token = override(token, opts);
@@ -205,6 +205,57 @@ export function trimToNull(value: unknown): string | null {
   return trimmed ? trimmed : null;
 }
 
+// Config lists arrive either already split (an array) or as one env-var string
+// with entries separated by commas and/or whitespace.
+const LIST_SEPARATOR_REGEXP = /[\s,]+/;
+
+/**
+ * Normalize a config list that may arrive as an array or as a single
+ * comma/whitespace-separated string: split, apply `transform`, drop empties,
+ * and de-duplicate (first occurrence wins).
+ *
+ * This is the shape every allow-list / fallback-order setting in this repo
+ * takes, because the same value can come from typed config (`string[]`) or from
+ * an environment variable (`"a, b c"`). Pass `transform` to normalize entries
+ * as they are read; it defaults to trimming.
+ *
+ * @example
+ * parseList("docs.example.com, *.databricks.com");
+ * parseList(process.env.MODEL_FALLBACKS);
+ * parseList(raw, normalizeUrlPattern);
+ */
+export function parseList(
+  raw: string | readonly string[] | undefined | null,
+  transform: (entry: string) => string = (entry) => entry.trim(),
+): string[] {
+  const entries =
+    typeof raw === "string" ? raw.split(LIST_SEPARATOR_REGEXP) : Array.isArray(raw) ? raw : [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    const normalized = transform(entry);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+/**
+ * {@link trimToNull} with an empty-string miss instead of `null`, for callers
+ * that build a string unconditionally and treat "absent" as "".
+ *
+ * Reading loosely-typed JSON is the motivating case: a field that should be a
+ * string may be missing or the wrong type, and the caller wants `""` rather
+ * than a null check at every access.
+ *
+ * @example
+ * const title = trimToEmpty(record.title); // always a string
+ */
+export function trimToEmpty(value: unknown): string {
+  return trimToNull(value) ?? "";
+}
+
 /**
  * Trim the first usable string out of `value`. Returns `null` when
  * `value` is `undefined`, `null`, an empty string, or an array whose

package/src/token.ts

@@ -8,19 +8,27 @@
  */
 
 import { forEachHeaderValue, type HeaderLike } from "./http";
+import * as json from "./json";
 import { isLevelEnabled, logger } from "./log";
 
 const BEARER_PREFIX_REGEX = /^bearer\s+/i;
 const SPLIT_REGEX = /\s+|\s*,\s*/;
 const log = logger("shared/token");
 
-/** Decode a JWT segment (base64url with standard base64 padding). */
-function decodeJwtSegment(segment: string): string {
+/**
+ * Decode a JWT segment (base64url with standard base64 padding), or
+ * `undefined` when the segment is not valid base64.
+ */
+function decodeJwtSegment(segment: string): string | undefined {
   const normalized = segment.replace(/-/g, "+").replace(/_/g, "/");
   const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
-  const binary = atob(padded);
-  const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
-  return new TextDecoder().decode(bytes);
+  try {
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return undefined;
+  }
 }
 
 /**
@@ -55,14 +63,8 @@ export function getAccessTokenPayload(
       }
       const parts = input.split(".", 4);
       if (parts.length === 2 || parts.length === 3) {
-        try {
-          const payload = JSON.parse(decodeJwtSegment(parts[1]!));
-          if (typeof payload === "object" && payload !== null) {
-            accessTokenPayload = payload as Record<string, unknown>;
-          }
-        } catch {
-          // Malformed JWT payload; fall through to empty object.
-        }
+        // A malformed segment yields undefined; fall through to empty object.
+        accessTokenPayload = json.parseRecord(decodeJwtSegment(parts[1]!));
       }
     }
   }

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}$/);
+    });
+  });
+});

package/test/json.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { json } from "../index";
+
+describe("json.parse", () => {
+  it("parses a well-formed document", () => {
+    assert.deepEqual(json.parse('{"a":1}'), { a: 1 });
+    assert.deepEqual(json.parse("[1,2]"), [1, 2]);
+    assert.equal(json.parse('"text"'), "text");
+  });
+
+  it("returns the fallback for malformed JSON instead of throwing", () => {
+    assert.equal(json.parse("{not json"), undefined);
+    assert.deepEqual(json.parse("{not json", { ok: false }), { ok: false });
+  });
+
+  it("treats absent / blank / non-string input as a miss", () => {
+    assert.equal(json.parse(undefined), undefined);
+    assert.equal(json.parse(null), undefined);
+    assert.equal(json.parse("   "), undefined);
+    assert.equal(json.parse(42), undefined);
+    assert.deepEqual(json.parse(undefined, []), []);
+  });
+});
+
+describe("json.parseRecord", () => {
+  it("returns the object for a record document", () => {
+    assert.deepEqual(json.parseRecord('{"name":"pkg"}'), { name: "pkg" });
+  });
+
+  it("rejects documents that parse to a non-record", () => {
+    assert.equal(json.parseRecord("[1,2]"), undefined);
+    assert.equal(json.parseRecord('"text"'), undefined);
+    assert.equal(json.parseRecord("null"), undefined);
+    assert.equal(json.parseRecord("7"), undefined);
+  });
+
+  it("returns undefined for malformed or absent input", () => {
+    assert.equal(json.parseRecord("{oops"), undefined);
+    assert.equal(json.parseRecord(undefined), undefined);
+  });
+});

package/test/string.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { string } from "../index";
+
+describe("string.trimToEmpty", () => {
+  it("trims a string", () => {
+    assert.equal(string.trimToEmpty("  hi  "), "hi");
+  });
+
+  it("yields an empty string for a non-string or blank value", () => {
+    assert.equal(string.trimToEmpty(undefined), "");
+    assert.equal(string.trimToEmpty(null), "");
+    assert.equal(string.trimToEmpty(42), "");
+    assert.equal(string.trimToEmpty("   "), "");
+  });
+});
+
+describe("string.parseList", () => {
+  it("splits a comma / whitespace separated string", () => {
+    assert.deepEqual(string.parseList("a, b  c,d"), ["a", "b", "c", "d"]);
+  });
+
+  it("accepts an array and trims its entries", () => {
+    assert.deepEqual(string.parseList([" a ", "b"]), ["a", "b"]);
+  });
+
+  it("drops empties and de-duplicates, first occurrence winning", () => {
+    assert.deepEqual(string.parseList("a,,b, a ,b"), ["a", "b"]);
+  });
+
+  it("returns an empty list for absent input", () => {
+    assert.deepEqual(string.parseList(undefined), []);
+    assert.deepEqual(string.parseList(null), []);
+    assert.deepEqual(string.parseList(""), []);
+  });
+
+  it("applies a transform and de-duplicates on the transformed value", () => {
+    assert.deepEqual(
+      string.parseList("A, a, B", (entry) => entry.trim().toLowerCase()),
+      ["a", "b"],
+    );
+  });
+});