@dbx-tools/shared-core 0.3.27 → 0.3.29

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

@@ -22,7 +22,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.27",
+  "version": "0.3.29",
   "types": "index.ts",
   "type": "module",
   "exports": {

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/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"],
+    );
+  });
+});