@dbx-tools/shared-core 0.1.2

package/src/error.ts

@@ -0,0 +1,178 @@
+/**
+ * Error normalization helpers: collapse the ubiquitous
+ * `err instanceof Error ? err.message : String(err)` dance into a single
+ * call, walk `cause` / `AggregateError` chains, and coerce any thrown
+ * value into a real `Error`. Dependency-free and browser-safe.
+ */
+
+import { tokenizeWithOptions } from "./string";
+
+/**
+ * Normalize any thrown value into an `Error`. Returns `value` unchanged
+ * when it already is an `Error`, otherwise wraps its {@link errorMessage}
+ * in a fresh `Error`. Use when a consumer needs a real `Error` object
+ * (React error state, `reject`, rethrow) rather than just a printable
+ * string.
+ */
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(errorMessage(value));
+}
+
+/**
+ * Extract a human-readable message from any thrown value. Returns
+ * `value.message` when `value` is an `Error`, otherwise coerces via
+ * `String(value)`. Collapses the ubiquitous
+ *
+ * ```ts
+ * err instanceof Error ? err.message : String(err)
+ * ```
+ *
+ * dance into a single helper, useful for log attributes and any other
+ * "give me something printable" context.
+ */
+export function errorMessage(value: unknown): string {
+  const message = errorMessages(value).next().value;
+  return message ?? String(value);
+}
+
+/**
+ * Yield `message` / `errorCode` strings from every node in the error
+ * tree (see {@link errorNodes}). Used by {@link errorMessage} and
+ * message predicates elsewhere.
+ */
+export function* errorMessages(value: unknown): Generator<string, void, undefined> {
+  for (const node of errorNodes(value)) {
+    if (typeof node === "object") {
+      for (const key of ["message", "errorCode"]) {
+        if (key in node) {
+          const value = (node as Record<string, unknown>)[key];
+          if (typeof value === "string" && value) {
+            yield value;
+          }
+        }
+      }
+    } else if (typeof node === "string" && node) {
+      yield node;
+    }
+  }
+}
+
+/**
+ * Depth-first walk of an error value: the root, then `errors` (e.g.
+ * `AggregateError`) and `cause` chains. Cycle-safe via a `seen` set.
+ */
+export function* errorNodes(err: unknown): Generator<NonNullable<unknown>, void, undefined> {
+  const seen = new Set<unknown>();
+
+  function* visit(node: unknown): Generator<NonNullable<unknown>, void, undefined> {
+    if (node === undefined || node === null) return;
+    if (Array.isArray(node)) {
+      for (const child of node) {
+        yield* visit(child);
+      }
+      return;
+    }
+    if (seen.has(node)) return;
+    seen.add(node);
+    yield node;
+    if (typeof node === "object") {
+      for (const key of ["errors", "cause"]) {
+        if (key in node) {
+          const value = (node as Record<string, unknown>)[key];
+          yield* visit(value);
+        }
+      }
+    }
+  }
+  yield* visit(err);
+}
+
+/**
+ * Lazy view over a thrown value for HTTP-status + message classification.
+ * Status comes from the last positive `statusCode` / `code` on the error tree;
+ * messages/tokens come from every `message` / `errorCode` field (including
+ * `cause` and `AggregateError.errors`). Build with {@link errorContext}.
+ */
+export type ErrorContext = ErrorContextImpl;
+
+class ErrorContextImpl {
+  private _statusCode: number | undefined;
+  private _messages: string[] | undefined;
+  private _messageTokens: string[] | undefined;
+
+  constructor(private readonly err: NonNullable<unknown>) {}
+
+  /** Last positive `statusCode` / `code` found on the error tree, else `undefined` (0 ignored). */
+  get statusCode(): number | undefined {
+    if (this._statusCode === undefined) {
+      outer: for (const node of errorNodes(this.err)) {
+        if (typeof node !== "object" || node === null) continue;
+        for (const key of ["statusCode", "code"] as const) {
+          if (!(key in node)) continue;
+          const value = (node as Record<string, unknown>)[key];
+          if (typeof value === "number" && value > 99 && value < 600) {
+            this._statusCode = value;
+            break outer;
+          }
+        }
+      }
+      if (this._statusCode === undefined) {
+        this._statusCode = -1;
+      }
+    }
+    return this._statusCode == -1 ? undefined : this._statusCode;
+  }
+
+  /** Every `message` / `errorCode` string in the error tree. */
+  get messages(): string[] {
+    if (this._messages === undefined) {
+      this._messages = [...errorMessages(this.err)];
+    }
+    return this._messages;
+  }
+
+  /** Lowercased tokens from {@link messages}. */
+  get messageTokens(): string[] {
+    if (this._messageTokens === undefined) {
+      this._messageTokens = [...tokenizeWithOptions({ lowerCase: true }, ...this.messages)];
+    }
+    return this._messageTokens;
+  }
+
+  /** True for any 4xx status or message tokens `not exist` / `not found`. */
+  get notAccessible(): boolean {
+    if (this.hasStatusCode(4)) return true;
+    return this.hasMessage("not", "exist") || this.hasMessage("not", "found");
+  }
+
+  /**
+   * Match HTTP status. Pass a full code (`404`) or a class (`4` for any 4xx).
+   * Extra filters are OR'd. `false` when no status is on the error tree.
+   */
+  hasStatusCode(statusCodeFilter: number, ...statusCodeFilters: number[]): boolean {
+    const code = this.statusCode;
+    if (code) {
+      for (const filter of [statusCodeFilter, ...statusCodeFilters]) {
+        const match = (filter < 100 ? Math.trunc(code / 100) : code) === filter;
+        if (match) return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * True when every token from the filter phrase(s) appears in
+   * {@link messageTokens}. Each argument is tokenized on non-alphanumeric
+   * boundaries (e.g. `hasMessage("not", "found")` or `hasMessage("not found")`).
+   */
+  hasMessage(messageFilter: string, ...messageFilters: string[]): boolean {
+    return [messageFilter, ...messageFilters]
+      .flatMap((filter) => Array.from(tokenizeWithOptions({ lowerCase: true }, filter)))
+      .every((filterToken) => this.messageTokens.includes(filterToken));
+  }
+}
+
+/** Build an {@link ErrorContext} for status + message checks. `null` / `undefined` become `{}`. */
+export function errorContext(err: unknown): ErrorContext {
+  return new ErrorContextImpl(err ?? {});
+}

package/src/function.ts

@@ -0,0 +1,91 @@
+export interface MemoizeOptions {
+  /**
+   * Time-to-live in milliseconds. The cached value expires `ttlMs` after
+   * it was stored, so the next call past that recomputes; a rejection is
+   * also evicted so a later call retries rather than replaying the error.
+   * Omitted or `<= 0` means a successful value is cached forever (the default).
+   * Errors are never cached - see {@link memoize}.
+   *
+   * Use for periodically-refreshed data (published IP ranges, feature
+   * flags, anything fetched once and reused across requests).
+   */
+  ttlMs?: number;
+}
+
+/**
+ * Run a zero-argument factory once; later calls return the same result.
+ * The memoized function mirrors the factory's sync / async nature: a
+ * sync factory yields a sync getter (`() => T`), an async / thenable
+ * factory yields a promise-returning getter (`() => Promise<T>`) whose
+ * concurrent callers share the one in-flight promise until it settles.
+ *
+ * Errors are never cached: a sync factory that throws propagates the
+ * throw, and an async factory that rejects evicts the cached promise, so
+ * in both cases the next call retries. Pass `{ ttlMs }` to also expire
+ * and recompute a successful value after a window; without a TTL a
+ * success is cached forever.
+ *
+ * For an async factory the TTL window starts when the promise
+ * *resolves*, not when it was created - a slow in-flight request never
+ * counts as already-expired, and concurrent callers keep sharing the one
+ * pending promise until it settles.
+ *
+ * @example
+ * const ranges = functionModule.memoize(fetchIpRanges, { ttlMs: 24 * 60 * 60 * 1000 });
+ * await ranges(); // fetches
+ * await ranges(); // cached until 24h later
+ */
+export function memoize<T>(
+  factory: () => PromiseLike<T>,
+  options?: MemoizeOptions,
+): () => Promise<T>;
+export function memoize<T>(factory: () => T, options?: MemoizeOptions): () => T;
+
+export function memoize<T>(
+  factory: () => T | PromiseLike<T>,
+  options?: MemoizeOptions,
+): () => T | Promise<T> {
+  const ttlMs = options?.ttlMs ?? 0;
+  let cache: { value: T | Promise<T>; expiresAt: number } | undefined;
+  return () => {
+    if (cache === undefined || (ttlMs > 0 && Date.now() >= cache.expiresAt)) {
+      const result = factory();
+      if (isThenable(result)) {
+        const pending = Promise.resolve(result);
+        // `Infinity` keeps the entry unexpired while in flight (so a slow
+        // request isn't refetched and concurrent callers share it); the
+        // TTL window is stamped from resolution below.
+        const entry = { value: pending, expiresAt: Infinity };
+        cache = entry;
+        void pending.then(
+          () => {
+            entry.expiresAt = Date.now() + ttlMs;
+          },
+          // Never cache a rejection: evict so a later call retries.
+          () => {
+            if (cache === entry) cache = undefined;
+          },
+        );
+      } else {
+        cache = { value: result, expiresAt: Date.now() + ttlMs };
+      }
+    }
+    return cache.value;
+  };
+}
+
+/** Duck-type any value with a callable `.then` as a thenable. */
+function isThenable<T>(value: T | PromiseLike<T>): value is PromiseLike<T> {
+  if (value !== null) {
+    if (value instanceof Promise) {
+      return true;
+    } else if (
+      typeof value === "object" &&
+      "then" in value &&
+      typeof (value as PromiseLike<T>).then === "function"
+    ) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/hash.ts

@@ -0,0 +1,261 @@
+/**
+ * Short, deterministic non-cryptographic hashing and id minting.
+ *
+ * {@link fnvHash} / {@link fnvHashWithOptions} produce a stable FNV-1a
+ * digest over arbitrary structured input; {@link toBase32} encodes a
+ * 32-bit integer compactly; {@link id} mints v4 UUIDs (or short hex
+ * slices). All browser-safe - built on `globalThis.crypto`, no
+ * `node:crypto` import. **Never** use these for tokens, signatures, or
+ * anything an attacker shouldn't be able to forge.
+ */
+
+/**
+ * Mint a v4 UUID, or a short hex slice of one when `length` is set.
+ *
+ * - `id()` returns a full RFC 4122 v4 UUID. Pick this when global
+ *   uniqueness matters: long-running batches, ids that cross a storage /
+ *   process boundary, anything that may collide across machines.
+ * - `id(length)` returns the first `length` hex chars of a fresh UUID
+ *   with dashes stripped (e.g. `id(8) -> "a3f1c92b"`). Pick this when the
+ *   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.
+ *
+ * @example
+ * id();   // "123e4567-e89b-12d3-a456-426614174000"
+ * id(8);  // "a3f1c92b"
+ */
+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();
+  if (length !== undefined) {
+    return id.replace(/-/g, "").slice(0, length);
+  }
+  return id;
+}
+
+/**
+ * Short, deterministic FNV-1a hash over one or more values. Wraps
+ * {@link fnvHashWithOptions} with all defaults: 6-char Crockford-style
+ * base-32 output (digits + lowercase, minus `i`/`l`/`o`/`u`).
+ * Browser-safe (no `node:crypto`).
+ *
+ * Accepts any mix of primitives, arrays, plain objects, `Map`s, and
+ * `Set`s; nested structures are walked deterministically so the hash is
+ * order-stable for objects / maps / sets and order-sensitive for arrays.
+ * Cycles are detected and folded into a `circular:` marker.
+ *
+ * Use for cache keys, slug suffixes, log correlation ids, and other
+ * "give me something short and stable" needs - **never** for tokens or
+ * signatures. FNV-1a is a non-cryptographic hash.
+ *
+ * @example
+ * fnvHash("databricks-claude-sonnet-4-6"); // "k3p9q7"
+ * fnvHash([1, 2, 3]) !== fnvHash([3, 2, 1]);
+ */
+export function fnvHash(...values: unknown[]): string {
+  return fnvHashWithOptions({}, ...values);
+}
+
+/**
+ * Configurable counterpart to {@link fnvHash}.
+ *
+ * Options:
+ *   - `length` (default `6`): number of base-32 chars to return. Capped
+ *     at 7 - the underlying digest is 32 bits, which base-32-encodes to
+ *     at most 7 chars. Output is left-padded with the alphabet's zero
+ *     character so short digests still hit the requested width.
+ *   - `alphabet` (default Crockford-style
+ *     `"0123456789abcdefghjkmnpqrstvwxyz"`): 32 distinct characters used
+ *     to encode the digest. Throws when not exactly 32 unique chars.
+ *   - `digest` (default `0x811c9dc5`, the FNV-1a offset basis): the seed
+ *     the running digest starts from. Useful for namespacing so
+ *     otherwise-identical inputs hashed under different namespaces never
+ *     collide, and for chaining hashes across pipeline stages.
+ *
+ * The hash is **not** stable across changes to the alphabet or `length` -
+ * those tune the output, not the digest input.
+ *
+ * @example
+ * fnvHashWithOptions({ length: 4 }, "user@example.com");        // 4 chars
+ * fnvHashWithOptions({ digest: nsHash }, key) !== fnvHash(key); // namespaced
+ */
+export function fnvHashWithOptions(
+  options: { length?: number; alphabet?: string; digest?: number } = {},
+  ...values: unknown[]
+): string {
+  const { length = 6 } = options;
+
+  let digest = options.digest ?? 0x811c9dc5;
+
+  for (const value of hashAttributes(values)) {
+    for (let i = 0; i < value.length; i++) {
+      digest ^= value.charCodeAt(i);
+      digest = Math.imul(digest, 0x01000193);
+    }
+  }
+  const alphabet = base32Alphabet(options.alphabet);
+  return toBase32(digest, alphabet, true).padStart(7, alphabet[0]).slice(0, Math.min(length, 7));
+}
+
+/**
+ * Walk an arbitrary value as a stream of canonicalized string tokens
+ * suitable for feeding into a streaming hash like FNV-1a. Used by
+ * {@link fnvHashWithOptions} so structured inputs hash deterministically
+ * without a stringification round-trip through `JSON.stringify` (which
+ * silently drops `undefined`, has no canonical key order, and can't
+ * represent cycles).
+ *
+ * Canonicalization rules:
+ *
+ *   - `null` / `undefined` collapse to `null:`.
+ *   - Primitives (`string` / `number` / `boolean`) are tagged with their
+ *     `typeof` so `"1"` and `1` produce different digests.
+ *   - Arrays preserve order: `[1,2]` and `[2,1]` hash differently.
+ *   - Plain objects emit keys in lexical order of each key's own
+ *     hash-token stream, so `{a:1,b:2}` and `{b:2,a:1}` collapse.
+ *   - `Map` keys go through the same key-sort path as objects.
+ *   - `Set`s are sorted by each element's hash-token stream and emit only
+ *     the elements, so insertion order doesn't leak into the digest.
+ *   - Cycles emit `circular:` and stop descending.
+ *   - Anything else falls through to a `${typeof}:${JSON.stringify}`
+ *     token.
+ */
+function* hashAttributes(input: any, seen?: WeakSet<object>): Generator<string> {
+  if (input === null || input === undefined) {
+    yield "null:";
+    return;
+  }
+
+  const inputType = typeof input;
+  if (inputType === "string" || inputType === "number" || inputType === "boolean") {
+    yield `${inputType}:`;
+    yield input.toString();
+    return;
+  }
+  seen ??= new WeakSet<object>();
+
+  if (inputType === "object") {
+    if (seen.has(input)) {
+      yield "circular:";
+      return;
+    }
+    seen.add(input);
+    try {
+      if (Array.isArray(input)) {
+        yield "[";
+        for (const item of input) {
+          yield* hashAttributes(item, seen);
+          yield ",";
+        }
+        yield "]";
+        return;
+      } else {
+        const hashAttributeKeys = (keys: Array<unknown>) => {
+          return keys
+            .map((key) => {
+              const keyHashAttributes = [...hashAttributes(key, seen)];
+              return {
+                key,
+                keyHashAttributes,
+                sortKey: keyHashAttributes.join("\0"),
+              };
+            })
+            .sort((a, b) => a.sortKey.localeCompare(b.sortKey));
+        };
+        if (input instanceof Set) {
+          yield "[";
+          for (const hashAttributeKey of hashAttributeKeys(Array.from(input))) {
+            yield* hashAttributeKey.keyHashAttributes;
+            yield ",";
+          }
+          yield "]";
+          return;
+        } else {
+          yield "{";
+          const keys = input instanceof Map ? Array.from(input.keys()) : Object.keys(input);
+          for (const hashAttributeKey of hashAttributeKeys(keys)) {
+            const value =
+              input instanceof Map
+                ? input.get(hashAttributeKey.key)
+                : input[hashAttributeKey.key as keyof typeof input];
+            yield* hashAttributeKey.keyHashAttributes;
+            yield ":";
+            yield* hashAttributes(value, seen);
+            yield ",";
+          }
+          yield "}";
+          return;
+        }
+      }
+    } finally {
+      seen.delete(input);
+    }
+  }
+  yield `${inputType}:${JSON.stringify(input)}`;
+}
+
+/**
+ * Default Crockford-style base-32 alphabet: digits `0-9` then lowercase
+ * letters with `i`, `l`, `o`, `u` removed. Output is safe to drop into
+ * URLs, filenames, and `[A-Za-z0-9_-]`-bound marker captures.
+ */
+const BASE32_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+
+/**
+ * Resolve a caller-supplied alphabet against the default. Returns the
+ * default when the caller passed nothing; otherwise validates the
+ * override is exactly 32 unique chars. Throws on bad alphabets so callers
+ * fail fast instead of producing silently-degraded encodings.
+ */
+function base32Alphabet(alphabet?: string): string {
+  if (alphabet === undefined) return BASE32_ALPHABET;
+  else if (new Set(alphabet).size !== 32) {
+    throw new Error("Base32 alphabet must contain 32 unique characters");
+  }
+  return alphabet;
+}
+
+/**
+ * Encode a 32-bit unsigned integer as base-32 using the default
+ * Crockford-style alphabet (or `alphabet` when provided). The encoding
+ * has **no** zero-padding by default - `toBase32(0)` returns the
+ * alphabet's zero character, otherwise the result is the minimal number
+ * of digits that fits the value. Pad / truncate at the call site when you
+ * need a fixed width.
+ *
+ * `disableAlphabetValidation` skips the unique-32-char check for hot
+ * paths that have already validated the alphabet. The function still
+ * requires `alphabet.length === 32` either way.
+ *
+ * @example
+ * toBase32(0);        // "0"
+ * toBase32(31);       // "z"
+ * toBase32(0xdeadbe); // "6vmtw"
+ */
+export function toBase32(
+  value: number,
+  alphabet?: string,
+  disableAlphabetValidation?: boolean,
+): string {
+  if (!disableAlphabetValidation) {
+    alphabet = base32Alphabet(alphabet);
+  }
+  if (alphabet!.length !== 32) {
+    throw new Error(`Base32 alphabet must contain exactly 32 characters, got ${alphabet!.length}`);
+  }
+  value >>>= 0;
+  if (value === 0) {
+    return alphabet![0]!;
+  }
+  let result = "";
+  while (value > 0) {
+    result = alphabet![value & 31] + result;
+    value >>>= 5;
+  }
+  return result;
+}