@dbx-tools/shared-core 0.1.2

package/src/net.ts

@@ -0,0 +1,535 @@
+/**
+ * Browser-safe networking helpers built around {@link urlBuilder}: a
+ * tolerant `URL` coercion + chainable builder that gracefully handles
+ * partial inputs (bare hosts, path-only strings, `{ url }` wrappers),
+ * a small IPv4 / IPv6 address + CIDR toolkit (parsing and membership
+ * lookups), and email-address parsing ({@link parseEmails} /
+ * {@link isEmail}) that normalizes the CSV / single-string / array
+ * inputs email recipient and allow-list fields accept into a clean
+ * `string[]`. No node-only imports, so this module is the canonical
+ * home for anything URL-, IP-, or email-shaped that also has to run in
+ * a Vite / Webpack / esbuild client bundle. Node-only network helpers
+ * (e.g. DNS resolution) belong in a node-tagged package, not here.
+ */
+
+import type { NonFunctionKeys } from "./object";
+
+const LOCAL_HOST_URL = new URL("http://localhost");
+const URL_SCHEME_DEFAULT = "https";
+const URL_SCHEME_PREFIX = /^([A-Za-z][A-Za-z0-9+.-]*:\/\/)/;
+const URL_PATH_SEGMENT_TRIM = /^\/+|\/+$/g;
+const URL_SCHEME_SEPARATOR = "://";
+
+/** Total bit width of an address of each {@link IpVersion}. */
+const IP_BITS: Readonly<Record<IpVersion, number>> = { 4: 32, 6: 128 };
+const IPV4_OCTET = /^\d{1,3}$/;
+const IPV6_HEXTET = /^[0-9a-fA-F]{1,4}$/;
+
+/** Delimiters between addresses in a free-text / CSV email list. */
+const EMAIL_LIST_SEPARATOR = /[\s,;]+/;
+/** Pragmatic `local@domain.tld` shape check (not full RFC 5322). */
+const EMAIL_ADDRESS = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// ────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Anything {@link urlBuilder} (and {@link pathMatch}) know how to coerce
+ * into a URL:
+ *
+ * - A string: a host, a full URL, or a path / query / hash fragment.
+ * - A WHATWG `URL` instance.
+ * - Any object with a `url` field (e.g. a fetch `Request`, a Databricks
+ *   `WorkspaceClient` config).
+ */
+export type UrlLike = string | URL | { url: string };
+
+/** IP protocol family: `4` for IPv4, `6` for IPv6. */
+export type IpVersion = 4 | 6;
+
+/**
+ * A parsed IP address. `value` is the address as an unsigned integer
+ * (a 32-bit range for v4, 128-bit for v6) held in a `bigint` so both
+ * families share one comparison / masking path. Produce one with
+ * {@link parseIp}.
+ */
+export interface ParsedIp {
+  version: IpVersion;
+  /** The address as an unsigned integer (`bigint` for uniform v4/v6 math). */
+  value: bigint;
+}
+
+/**
+ * A parsed CIDR block (`10.0.0.0/8`, `2001:db8::/32`). `base` is the
+ * network address with all host bits cleared, so membership is a
+ * single masked compare (see {@link ipInCidr}). Produce one with
+ * {@link parseCidr}. Carries the normalized `cidr` string for logging
+ * and to key back to caller-side metadata.
+ */
+export interface Cidr {
+  version: IpVersion;
+  /** Network address (host bits zeroed) as an unsigned `bigint`. */
+  base: bigint;
+  /** Prefix length in bits (the number after the `/`). */
+  prefix: number;
+  /** Normalized `<address>/<prefix>` string. */
+  cidr: string;
+}
+
+/** Settable, non-method `URL` properties - the keys {@link UrlBuilder.with} accepts. */
+type UrlPropertyKey = NonFunctionKeys<UrlBuilderImpl>;
+
+/**
+ * A `URL` subclass with chainable, copy-on-write helpers. Every mutating
+ * method returns a fresh builder rather than editing in place, so a base
+ * builder can be safely reused. Construct one via {@link urlBuilder}.
+ */
+class UrlBuilderImpl extends URL {
+  constructor(url: URL) {
+    super(url);
+  }
+
+  /** The scheme without the trailing colon (`https`, not `https:`). */
+  get scheme(): string {
+    return this.protocol.slice(0, -1);
+  }
+
+  set scheme(value: string) {
+    this.protocol = value + ":";
+  }
+
+  /**
+   * Return a copy with a single `URL` property (`pathname`, `search`,
+   * `hostname`, `scheme`, ...) set to `value`, leaving this builder
+   * untouched.
+   */
+  with<K extends UrlPropertyKey>(key: K, value: UrlBuilderImpl[K]): UrlBuilder {
+    const next = new UrlBuilderImpl(this);
+    (next as any)[key] = value;
+    return new UrlBuilderImpl(next);
+  }
+
+  /**
+   * Return a copy with `pathSegments` appended to the current pathname.
+   * Segments may be strings or string arrays; each is trimmed of
+   * boundary slashes and blanks are dropped before joining with `/`.
+   */
+  withPathAppend(...pathSegments: (string | string[])[]): UrlBuilder {
+    return this.withPathReplace(this.pathname, ...pathSegments);
+  }
+
+  /**
+   * Return a copy whose pathname is `pathSegments` joined with `/`,
+   * replacing any existing path. Segments may be strings or string
+   * arrays; each is trimmed of boundary slashes and blanks are dropped.
+   */
+  withPathReplace(...pathSegments: (string | string[])[]): UrlBuilder {
+    const pathnameParts: string[] = [...pathSegments].flatMap((p) =>
+      Array.isArray(p) ? p : [p],
+    );
+    const pathname = pathnameParts
+      .map((p) => p.replace(URL_PATH_SEGMENT_TRIM, ""))
+      .filter(Boolean)
+      .join("/");
+    return this.with("pathname", "/" + pathname);
+  }
+
+  /**
+   * Test whether this URL's pathname is `path` or lives beneath it,
+   * matching on segment boundaries so `/api` matches `/api` and
+   * `/api/cool` but not `/apicool`. A missing leading slash on `path`
+   * is tolerated; query and hash are ignored (they aren't part of
+   * `pathname`). Matching is exact otherwise - trailing slashes are
+   * not normalized and `/` matches only the root.
+   */
+  pathMatches(path: string): boolean {
+    const pathname = this.pathname;
+    if (pathname == path) return true;
+    if (!path.startsWith("/")) path = "/" + path;
+    if (pathname == path) return true;
+    return pathname.startsWith(path + "/");
+  }
+}
+
+/** Public type for the {@link urlBuilder} return value. */
+export type UrlBuilder = UrlBuilderImpl;
+
+/** With no argument, resolves to the base origin (never `null`). */
+export function urlBuilder(): UrlBuilder;
+
+/**
+ * Coerce a {@link UrlLike} into a chainable {@link UrlBuilder}, or `null`
+ * when the input cannot be parsed into a URL. Never throws.
+ *
+ * - A `URL` instance or `{ url }` wrapper is adopted as-is.
+ * - A bare hostname (`"example.com"`) is upgraded to `https://`; an
+ *   explicit scheme is preserved.
+ * - A path / query / hash fragment (`"/api"`, `"?q=1"`, `"#x"`) is
+ *   resolved against {@link defaultUrl} (the browser origin, else
+ *   `http://localhost`).
+ * - An empty / blank string or omitted input resolves to the base
+ *   origin.
+ *
+ * @example
+ * urlBuilder("example.com");          // https://example.com/
+ * urlBuilder("http://x/path");        // http://x/path
+ * urlBuilder("/api/v2");              // http://localhost/api/v2
+ * urlBuilder({ url: "http://y" });    // http://y/
+ * urlBuilder();                       // http://localhost/
+ */
+export function urlBuilder(input?: UrlLike): UrlBuilder | null;
+
+export function urlBuilder(input?: UrlLike): UrlBuilder | null {
+  if (input instanceof URL) {
+    return new UrlBuilderImpl(input);
+  }
+  if (input !== null && typeof input === "object" && "url" in input) {
+    input = input.url;
+  }
+  if (typeof input === "string") {
+    input = input.trim();
+  }
+  if (input) {
+    if (input.startsWith("/") || input.startsWith("?") || input.startsWith("#")) {
+      const joinedUrl = defaultUrl().toString().slice(0, -1) + input;
+      return urlBuilder(joinedUrl);
+    } else if (input.startsWith(URL_SCHEME_SEPARATOR)) {
+      input = `${URL_SCHEME_DEFAULT}${input}`;
+    } else {
+      const match = input.match(URL_SCHEME_PREFIX);
+      const schemePrefix = match?.[1];
+      if (schemePrefix) {
+        const rest = input.slice(schemePrefix.length);
+        input = `${schemePrefix}${rest || defaultUrl().hostname}`;
+      } else {
+        input = `${URL_SCHEME_DEFAULT}://${input}`;
+      }
+    }
+  } else {
+    return urlBuilder(defaultUrl());
+  }
+  const url = parseUrl(input);
+  return url ? urlBuilder(url) : null;
+}
+
+/**
+ * Convenience wrapper over {@link UrlBuilder.pathMatches}: coerce
+ * `input` via {@link urlBuilder} and test its pathname against `path`.
+ * Returns `false` for input that can't be parsed into a URL.
+ *
+ * @example
+ * pathMatch("/api/cool?q=1", "/api");      // true
+ * pathMatch("/apicool", "/api");           // false
+ * pathMatch("https://host/api", "/api");   // true
+ * pathMatch(request, "/api/v2");           // fetch Request
+ */
+export function pathMatch(input: UrlLike, path: string): boolean {
+  const urlb = urlBuilder(input);
+  if (!urlb) return false;
+  return urlb.pathMatches(path);
+}
+
+/**
+ * Base origin for resolving path-only inputs. In a browser this is the
+ * current page's origin (`window.location.origin`), so `urlBuilder("/api")`
+ * reflects where the app is actually served from; on the server / in
+ * tests (no `window`, or an opaque `"null"` origin) it falls back to
+ * `http://localhost`.
+ */
+function defaultUrl(): URL {
+  // Reach `window` via `globalThis` so this compiles without the DOM
+  // lib (it's `undefined` on the server / in workers without one).
+  const origin = (globalThis as { window?: { location?: { origin?: string } } }).window
+    ?.location?.origin;
+  if (origin && origin !== "null") {
+    const originUrl = parseUrl(origin);
+    if (originUrl) {
+      return originUrl;
+    }
+  }
+  return new URL(LOCAL_HOST_URL);
+}
+
+function parseUrl(input: string): URL | null {
+  if (input && input.includes(URL_SCHEME_SEPARATOR)) {
+    try {
+      return new URL(input);
+    } catch {}
+  }
+  return null;
+}
+
+// ────────────────────────────────────────────────────────────────
+// Email addresses
+// ────────────────────────────────────────────────────────────────
+
+/** Options for {@link parseEmails}. */
+export interface ParseEmailsOptions {
+  /** Lower-case every address (useful for allow-lists / matching). Off by default. */
+  lowercase?: boolean;
+  /**
+   * Drop later case-insensitive duplicates, keeping first-seen casing.
+   * On by default - a recipient or pattern list rarely wants repeats.
+   */
+  dedupe?: boolean;
+}
+
+/**
+ * Normalize the shapes an email address field accepts - a single string,
+ * a comma / semicolon / whitespace separated list, an array of either,
+ * or nothing - into a clean `string[]`. Each entry is split on the list
+ * separators, trimmed, and de-emptied; blanks and non-string array
+ * members are dropped. By default duplicates are removed
+ * case-insensitively (first-seen casing wins) and casing is otherwise
+ * preserved; pass `lowercase` to fold everything to lower case (e.g. for
+ * an allow-list). This is the one place recipient lists, CC/BCC inputs,
+ * and sender allow-lists across the repo agree on how free-text email
+ * input is read. Never throws; does not validate - pair with
+ * {@link isEmail} when you need to reject malformed addresses.
+ *
+ * @example
+ * parseEmails("a@x.com, b@y.com; a@x.com"); // ["a@x.com", "b@y.com"]
+ * parseEmails(["A@x.com", " b@y.com "]);      // ["A@x.com", "b@y.com"]
+ * parseEmails("*@corp.com", { lowercase: true }); // ["*@corp.com"]
+ * parseEmails(undefined);                     // []
+ */
+export function parseEmails(
+  input: string | readonly string[] | null | undefined,
+  options: ParseEmailsOptions = {},
+): string[] {
+  if (input === null || input === undefined) return [];
+  const { lowercase = false, dedupe = true } = options;
+  const entries = Array.isArray(input) ? input : [input as string];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of entries) {
+    if (typeof entry !== "string") continue;
+    for (const token of entry.split(EMAIL_LIST_SEPARATOR)) {
+      const trimmed = token.trim();
+      if (!trimmed) continue;
+      const address = lowercase ? trimmed.toLowerCase() : trimmed;
+      if (dedupe) {
+        const key = address.toLowerCase();
+        if (seen.has(key)) continue;
+        seen.add(key);
+      }
+      out.push(address);
+    }
+  }
+  return out;
+}
+
+/**
+ * Pragmatic `local@domain.tld` shape check: non-empty local and domain
+ * parts around a single `@`, with a dotted domain and no whitespace.
+ * Deliberately loose (not full RFC 5322) - enough to catch obvious typos
+ * and give CLI / form feedback, not to gate delivery. Trims first. This
+ * is a purely syntactic test, so a wildcard allow-list pattern like
+ * `*@example.com` passes; distinguishing a pattern from a real address
+ * is the sender policy's job, not this validator's.
+ *
+ * @example
+ * isEmail("alice@example.com"); // true
+ * isEmail("nope");              // false (no @)
+ * isEmail("no@domain");         // false (no dotted domain)
+ */
+export function isEmail(value: string): boolean {
+  return EMAIL_ADDRESS.test(value.trim());
+}
+
+// ────────────────────────────────────────────────────────────────
+// IP addresses and CIDR blocks
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * Parse an IPv4 (`"1.2.3.4"`) or IPv6 (`"2001:db8::1"`,
+ * `"::ffff:1.2.3.4"`, `"::1"`) address into a {@link ParsedIp}, or
+ * `null` when the input isn't a valid literal. Never throws. Surrounding
+ * whitespace, `[...]` brackets around an IPv6 literal, and an IPv6 zone
+ * id (`fe80::1%eth0`) are all tolerated. The `value` is returned as a
+ * `bigint` so v4 and v6 share one comparison path.
+ *
+ * @example
+ * parseIp("10.0.0.1");        // { version: 4, value: 167772161n }
+ * parseIp("2001:db8::1");     // { version: 6, value: ... }
+ * parseIp("not-an-ip");       // null
+ */
+export function parseIp(input: string): ParsedIp | null {
+  let text = input.trim();
+  if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+  if (text.includes(":")) {
+    // Drop an IPv6 zone id (`fe80::1%eth0`) - it isn't part of the address.
+    const zone = text.indexOf("%");
+    if (zone >= 0) text = text.slice(0, zone);
+    const value = parseIpv6(text);
+    return value === null ? null : { version: 6, value };
+  }
+  const value = parseIpv4(text);
+  return value === null ? null : { version: 4, value };
+}
+
+/**
+ * Parse a CIDR block (`"10.0.0.0/8"`, `"2001:db8::/32"`) into a
+ * {@link Cidr} with host bits cleared from `base`, or `null` when the
+ * input isn't a valid block (bad address, missing / out-of-range
+ * prefix). Never throws.
+ *
+ * @example
+ * parseCidr("10.0.0.0/8")?.base;   // 167772160n (10.0.0.0)
+ * parseCidr("10.1.2.3/8")?.base;   // 167772160n (host bits dropped)
+ * parseCidr("10.0.0.0/40");        // null (prefix > 32 for v4)
+ */
+export function parseCidr(input: string): Cidr | null {
+  const text = input.trim();
+  const slash = text.lastIndexOf("/");
+  if (slash < 0) return null;
+  const prefixText = text.slice(slash + 1);
+  if (!IPV4_OCTET.test(prefixText)) return null;
+  const ip = parseIp(text.slice(0, slash));
+  if (!ip) return null;
+  const prefix = Number(prefixText);
+  const bits = IP_BITS[ip.version];
+  if (prefix > bits) return null;
+  const base = ip.value & networkMask(bits, prefix);
+  return {
+    version: ip.version,
+    base,
+    prefix,
+    cidr: `${text.slice(0, slash)}/${prefix}`,
+  };
+}
+
+/**
+ * Test whether `ip` falls inside `cidr`. Both arguments accept either
+ * a string (parsed on the fly via {@link parseIp} / {@link parseCidr})
+ * or an already-parsed value - pass parsed values in hot loops to skip
+ * re-parsing. Returns `false` for unparseable input or a version
+ * mismatch (an IPv4 address is never inside an IPv6 block).
+ *
+ * @example
+ * ipInCidr("10.1.2.3", "10.0.0.0/8");   // true
+ * ipInCidr("11.0.0.1", "10.0.0.0/8");   // false
+ */
+export function ipInCidr(ip: string | ParsedIp, cidr: string | Cidr): boolean {
+  const parsedIp = typeof ip === "string" ? parseIp(ip) : ip;
+  const parsedCidr = typeof cidr === "string" ? parseCidr(cidr) : cidr;
+  if (!parsedIp || !parsedCidr || parsedIp.version !== parsedCidr.version) {
+    return false;
+  }
+  const mask = networkMask(IP_BITS[parsedCidr.version], parsedCidr.prefix);
+  return (parsedIp.value & mask) === parsedCidr.base;
+}
+
+/**
+ * Return the first CIDR in `cidrs` that contains `ip`, or `null` when
+ * none match. `cidrs` holds pre-parsed {@link Cidr} values (or any
+ * object extending it), so callers can carry side metadata on each
+ * entry (e.g. a region tag) and read it straight off the returned
+ * match. Linear scan; parse the address once by passing a
+ * {@link ParsedIp}.
+ *
+ * @example
+ * const ranges = ["10.0.0.0/8", "192.168.0.0/16"]
+ *   .map(parseCidr)
+ *   .filter((c): c is Cidr => c !== null);
+ * findContainingCidr("10.1.2.3", ranges)?.cidr; // "10.0.0.0/8"
+ */
+export function findContainingCidr<T extends Cidr>(
+  ip: string | ParsedIp,
+  cidrs: Iterable<T>,
+): T | null {
+  const parsedIp = typeof ip === "string" ? parseIp(ip) : ip;
+  if (!parsedIp) return null;
+  for (const cidr of cidrs) {
+    if (cidr.version !== parsedIp.version) continue;
+    const mask = networkMask(IP_BITS[cidr.version], cidr.prefix);
+    if ((parsedIp.value & mask) === cidr.base) return cidr;
+  }
+  return null;
+}
+
+/**
+ * Network mask for `prefix` leading bits of a `bits`-wide address as a
+ * `bigint`: the top `prefix` bits set, the low host bits cleared.
+ * `prefix === 0` yields `0n` (matches everything); `prefix === bits`
+ * yields the all-ones mask (matches a single address).
+ */
+function networkMask(bits: number, prefix: number): bigint {
+  const hostBits = BigInt(bits - prefix);
+  const full = (1n << BigInt(bits)) - 1n;
+  return full ^ ((1n << hostBits) - 1n);
+}
+
+/** Parse a dotted-quad IPv4 literal into a 32-bit value, else `null`. */
+function parseIpv4(input: string): bigint | null {
+  const parts = input.split(".");
+  if (parts.length !== 4) return null;
+  let value = 0n;
+  for (const part of parts) {
+    if (!IPV4_OCTET.test(part)) return null;
+    const octet = Number(part);
+    if (octet > 255) return null;
+    value = (value << 8n) | BigInt(octet);
+  }
+  return value;
+}
+
+/**
+ * Parse an IPv6 literal into a 128-bit value, else `null`. Handles `::`
+ * zero-compression (at most once) and a trailing embedded IPv4 group
+ * (`::ffff:1.2.3.4`). The zone id, if any, is expected to be stripped
+ * by {@link parseIp} before this is called.
+ */
+function parseIpv6(input: string): bigint | null {
+  const halves = input.split("::");
+  if (halves.length > 2) return null;
+
+  const head = parseHextets(halves[0]!);
+  if (head === null) return null;
+
+  if (halves.length === 2) {
+    const tail = parseHextets(halves[1]!);
+    if (tail === null) return null;
+    // "::" must stand in for at least one all-zero hextet.
+    const missing = 8 - head.length - tail.length;
+    if (missing < 1) return null;
+    return hextetsToValue([...head, ...Array(missing).fill(0), ...tail]);
+  }
+
+  if (head.length !== 8) return null;
+  return hextetsToValue(head);
+}
+
+/**
+ * Parse one colon-separated run of IPv6 hextets, expanding a trailing
+ * embedded IPv4 group into its two hextets. An empty string yields an
+ * empty list (the side of a leading / trailing `::`).
+ */
+function parseHextets(part: string): number[] | null {
+  if (part === "") return [];
+  const tokens = part.split(":");
+  const hextets: number[] = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    if (token.includes(".")) {
+      // A dotted-quad is only legal as the final group.
+      if (i !== tokens.length - 1) return null;
+      const v4 = parseIpv4(token);
+      if (v4 === null) return null;
+      hextets.push(Number((v4 >> 16n) & 0xffffn), Number(v4 & 0xffffn));
+    } else {
+      if (!IPV6_HEXTET.test(token)) return null;
+      hextets.push(parseInt(token, 16));
+    }
+  }
+  return hextets;
+}
+
+/** Fold exactly 8 hextets into a single 128-bit `bigint`, else `null`. */
+function hextetsToValue(hextets: number[]): bigint | null {
+  if (hextets.length !== 8) return null;
+  let value = 0n;
+  for (const hextet of hextets) value = (value << 16n) | BigInt(hextet);
+  return value;
+}

package/src/object.ts

@@ -0,0 +1,165 @@
+/**
+ * Small value guards, coercions, object-shape types, and structural
+ * deep-equality: narrow parsed JSON to a record, coerce loose truthy/falsy
+ * strings to a boolean, describe object shapes (`NameLike`, `NonFunctionKeys`),
+ * and compare values with {@link deepEqual}. Dependency-free and browser-safe.
+ */
+
+/** Minimal shape for objects that expose an optional `name` (e.g. AppKit plugins). */
+export interface NameLike {
+  name?: string;
+}
+
+export type NonFunctionKeys<T> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? never : K;
+}[keyof T];
+
+/**
+ * Narrow `value` to a plain (non-array) object. Use as a type guard
+ * before indexing into / mutating parsed JSON so the access is
+ * type-safe.
+ *
+ * @example
+ * if (isRecord(parsed)) parsed.foo = 1;
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Coerce a loose boolean-ish value to a real `boolean`, or `undefined`
+ * when it can't be interpreted. Recognizes `true`/`t`/`on`/`1`/`yes`/`y`
+ * and their negatives (case- and whitespace-insensitive for strings), as
+ * well as the numbers `1` and `0`.
+ */
+export function toBoolean(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  else if (typeof value === "string") {
+    value = value.trim().toLowerCase();
+    if (
+      value === "true" ||
+      value == "t" ||
+      value === "on" ||
+      value === "1" ||
+      value === "yes" ||
+      value === "y"
+    )
+      return true;
+    else if (
+      value === "false" ||
+      value == "f" ||
+      value === "off" ||
+      value === "0" ||
+      value === "no" ||
+      value === "n"
+    )
+      return false;
+  } else if (typeof value === "number") {
+    if (value === 1) return true;
+    else if (value === 0) return false;
+  }
+  return undefined;
+}
+
+/**
+ * Structural deep-equality with an optional custom comparator.
+ *
+ * {@link deepEqual} mirrors the semantics of the `fast-deep-equal`
+ * package (handled: nested plain objects/arrays, `Map`, `Set`, `Date`,
+ * `RegExp`, typed arrays, `NaN`, and `+0`/`-0` treated as equal) but is
+ * dependency-free so `@dbx-tools/shared-core` keeps no runtime deps.
+ *
+ * The optional `comparator` short-circuits the structural walk at any
+ * node: return `true`/`false` to force the result for that pair, or
+ * `undefined` to defer to the built-in comparison. It is invoked for the
+ * root pair and recursively for each nested pair, so a caller can, e.g.,
+ * compare two domain objects by id while letting everything else fall
+ * back to structural equality.
+ *
+ * @example
+ * deepEqual({ a: 1 }, { a: 1 });                 // true
+ * deepEqual([1, 2], [1, 2]);                      // true
+ * deepEqual(a, b, (x, y) =>
+ *   isEntity(x) && isEntity(y) ? x.id === y.id : undefined);
+ */
+export type DeepEqualComparator = (a: unknown, b: unknown) => boolean | undefined;
+
+export function deepEqual(a: unknown, b: unknown, comparator?: DeepEqualComparator): boolean {
+  if (comparator) {
+    const decided = comparator(a, b);
+    if (decided !== undefined) return decided;
+  }
+
+  if (a === b) return true;
+
+  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) {
+    // NaN is the only value not equal to itself under `===`.
+    return a !== a && b !== b;
+  }
+
+  if (a.constructor !== b.constructor) return false;
+
+  if (Array.isArray(a)) {
+    const bArr = b as unknown[];
+    if (a.length !== bArr.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], bArr[i], comparator)) return false;
+    }
+    return true;
+  }
+
+  if (a instanceof Map) {
+    const bMap = b as Map<unknown, unknown>;
+    if (a.size !== bMap.size) return false;
+    for (const [key, value] of a) {
+      if (!bMap.has(key)) return false;
+      if (!deepEqual(value, bMap.get(key), comparator)) return false;
+    }
+    return true;
+  }
+
+  if (a instanceof Set) {
+    const bSet = b as Set<unknown>;
+    if (a.size !== bSet.size) return false;
+    for (const value of a) {
+      if (!bSet.has(value)) return false;
+    }
+    return true;
+  }
+
+  if (a instanceof Date) {
+    return a.getTime() === (b as Date).getTime();
+  }
+
+  if (a instanceof RegExp) {
+    const bRe = b as RegExp;
+    return a.source === bRe.source && a.flags === bRe.flags;
+  }
+
+  if (ArrayBuffer.isView(a) && !(a instanceof DataView)) {
+    const aArr = a as unknown as ArrayLike<number>;
+    const bArr = b as unknown as ArrayLike<number>;
+    if (aArr.length !== bArr.length) return false;
+    for (let i = 0; i < aArr.length; i++) {
+      if (aArr[i] !== bArr[i]) return false;
+    }
+    return true;
+  }
+
+  const aKeys = Object.keys(a as Record<string, unknown>);
+  const bKeys = Object.keys(b as Record<string, unknown>);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (
+      !deepEqual(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+        comparator,
+      )
+    ) {
+      return false;
+    }
+  }
+  return true;
+}