@dxos/util 0.8.3 → 0.8.4-main.1068cf700f

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.3",
+  "version": "0.8.4-main.1068cf700f",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": {
         "require": "./dist/lib/node/index.cjs",
         "default": "./dist/lib/node-esm/index.mjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
+      }
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -27,17 +31,18 @@
     "src"
   ],
   "dependencies": {
+    "@hazae41/symbol-dispose-polyfill": "^1.0.2",
     "lodash.get": "^4.4.2",
     "lodash.set": "^4.3.2",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/node-std": "0.8.3",
-    "@dxos/debug": "0.8.3",
-    "@dxos/keys": "0.8.3"
+    "@dxos/invariant": "0.8.4-main.1068cf700f",
+    "@dxos/keys": "0.8.4-main.1068cf700f",
+    "@dxos/debug": "0.8.4-main.1068cf700f",
+    "@dxos/node-std": "0.8.4-main.1068cf700f"
   },
   "devDependencies": {
     "@types/lodash.get": "^4.4.9",
     "@types/lodash.set": "^4.3.9",
-    "@dxos/crypto": "0.8.3"
+    "@dxos/crypto": "0.8.4-main.1068cf700f"
   },
   "publishConfig": {
     "access": "public"

package/src/array.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { diff, intersection, distinctBy, partition } from './array';
+import { diff, distinctBy, intersection, partition } from './array';
 
 describe('diff', () => {
   test('returns the difference between two sets', () => {

package/src/array.ts

@@ -16,7 +16,6 @@ export type DiffResult<A, B = A> = {
  * @param next
  * @param comparator
  */
-// TODO(burdon): Factor out.
 export const diff = <A, B = A>(
   previous: readonly A[],
   next: readonly B[],
@@ -43,15 +42,14 @@ export const diff = <A, B = A>(
   return result;
 };
 
-// TODO(burdon): Factor out.
-export const intersection = <A, B = A>(a: A[], b: B[], comparator: Comparator<A, B>): A[] =>
+export const intersection = <A, B = A>(a: readonly A[], b: readonly B[], comparator: Comparator<A, B>): A[] =>
   a.filter((a) => b.find((b) => comparator(a, b)) !== undefined);
 
 /**
  * Returns a new array with only the first instance of each unique item
  * based on a specified property.
  *
- * @typeParam T - The type of items in the input array.
+ * @typeProp T - The type of items in the input array.
  * @param array - The array to filter for distinct items.
  * @param key - The property key to determine uniqueness for each item.
  * @returns A new array with only distinct items based on the specified property.
@@ -132,3 +130,10 @@ export const intersectBy = <T, K>(arrays: T[][], selector: (item: T) => K): T[]
     return lookups.every((lookup) => lookup.has(key));
   });
 };
+
+export const coerceArray = <T>(arr: T | T[] | undefined): T[] => {
+  if (arr === undefined) {
+    return [];
+  }
+  return Array.isArray(arr) ? arr : [arr];
+};

package/src/assume.ts

@@ -16,7 +16,6 @@
  * ```
  */
 // NOTE: Keep as `function` to avoid type inference issues.
-// eslint-disable-next-line @stayradiated/prefer-arrow-functions/prefer-arrow-functions
 export function assumeType<T>(value: unknown): asserts value is T {
   // No-op.
 }

package/src/binder.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import util from 'node:util';
+import { promisify } from 'node:util';
 
 /**
  * Function binder replaces pify.
@@ -10,5 +10,5 @@ import util from 'node:util';
 // TODO(burdon): Replace pify everywhere.
 export const createBinder = (obj: any) => ({
   fn: (fn: Function) => fn.bind(obj),
-  async: (fn: Function) => util.promisify(fn.bind(obj)),
+  async: (fn: Function) => promisify(fn.bind(obj)),
 });

package/src/circular-buffer.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { describe, test, expect } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
 import { CircularBuffer } from './circular-buffer';
 

package/src/complex.test.ts

@@ -6,7 +6,7 @@ import { expect, test } from 'vitest';
 
 import { PublicKey } from '@dxos/keys';
 
-import { makeSet, makeMap } from './complex';
+import { makeMap, makeSet } from './complex';
 
 const PulicKeySet = makeSet<PublicKey>(PublicKey.hash);
 

package/src/deep.ts

@@ -19,6 +19,8 @@ export const setDeep = <T>(obj: any, path: readonly (string | number)[], value:
   let parent = obj;
   for (const key of path.slice(0, -1)) {
     if (parent[key] === undefined) {
+      // TODO(wittjosiah): This logic is flawed. This shouldn't be used for initializing arrays.
+      //   Prefer `Obj.setValue` for ECHO objects.
       const isArrayIndex = !isNaN(Number(key));
       parent[key] = isArrayIndex ? [] : {};
     }

package/src/defer.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import './explicit-resource-management-polyfill';
+import '@hazae41/symbol-dispose-polyfill';
 
 /**
  * Run function on scope exit. Go style.

package/src/error-format.ts

@@ -0,0 +1,22 @@
+/**
+ * Formats an error with its cause chain.
+ */
+//
+// Copyright 2025 DXOS.org
+//
+
+export const formatErrorWithCauses = (error: Error): string => {
+  const lines: string[] = [];
+  let current: Error | undefined = error;
+  let level = 0;
+
+  while (current) {
+    const prefix = level === 0 ? '' : `Caused by: `;
+    lines.push(prefix + (current.stack ?? String(current)));
+    if (!(current.cause instanceof Error)) break;
+    current = current.cause;
+    level += 1;
+  }
+
+  return lines.join('\n\n');
+};

package/src/filename.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Creates a unique filename.
+ */
+export const createFilename = ({
+  parts = [],
+  ext,
+  date = new Date(),
+}: {
+  parts?: string[];
+  ext?: string;
+  date?: Date;
+}) => [date.toISOString().replace(/[:.]/g, '-'), ...parts].join('_') + (ext ? `.${ext}` : '');

package/src/human-hash.test.ts

@@ -4,7 +4,7 @@
 
 import { expect, test } from 'vitest';
 
-import { createKeyPair, createId } from '@dxos/crypto';
+import { createId, createKeyPair } from '@dxos/crypto';
 import { PublicKey } from '@dxos/keys';
 
 import { humanize } from './human-hash';

package/src/index.ts

@@ -4,6 +4,7 @@
 
 export * from './array-to-hex';
 export * from './array';
+export * from './assume';
 export * from './binder';
 export * from './bitfield';
 export * from './callback-collection';
@@ -17,7 +18,7 @@ export * from './deep';
 export * from './defer-function';
 export * from './defer';
 export * from './entry';
-export * from './first-two-chars';
+export * from './filename';
 export * from './for-each-async';
 export * from './human-hash';
 export * from './instance-id';
@@ -40,7 +41,7 @@ export * from './remove-undefined-keys';
 export * from './safe-await';
 export * from './safe-instanceof';
 export * from './safe-parse';
-export * from './sliding-window-summary';
+export * from './safe-stringify';
 export * from './sliding-window-summary';
 export * from './sort';
 export * from './string';
@@ -51,5 +52,8 @@ export * from './tracer';
 export * from './tree';
 export * from './types';
 export * from './uint8array';
+export * from './unit';
+export * from './url';
 export * from './weak';
-export * from './assume';
+export * from './error-format';
+export * from './retry';

package/src/json.ts

@@ -17,7 +17,7 @@ const LOG_MAX_DEPTH = 7;
 /**
  * JSON.stringify replacer.
  */
-export function jsonReplacer(this: any, key: string, value: any): any {
+export const jsonReplacer = (key: string, value: any): any => {
   // TODO(burdon): Why is this represented as `{ type: 'Buffer', data }`.
   if (value !== null && typeof value === 'object' && typeof value[inspect.custom] === 'function') {
     return value[inspect.custom]();
@@ -32,13 +32,8 @@ export function jsonReplacer(this: any, key: string, value: any): any {
     }
   }
 
-  // TODO(burdon): Option.
-  // code if (Array.isArray(value)) {
-  // code   return value.length;
-  // code } else {
   return value;
-  // code }
-}
+};
 
 /**
  * Recursively converts an object into a JSON-compatible object.

package/src/object.ts

@@ -2,6 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
+/**
+ * @deprecated Use `Struct.keys` from effect.
+ */
 export const keys = <R>(obj: R): (keyof R)[] => Object.keys(obj as any) as (keyof R)[];
 
 export const entries = <R>(obj: R): [keyof R, R[keyof R]][] => Object.entries(obj as any) as [keyof R, any][];

package/src/platform.ts

@@ -5,10 +5,20 @@
 // NOTE: `!=` is required.
 export const isNode = () => typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
 
+export const isBun = () => (globalThis as any).Bun !== undefined;
+
+export const isTauri = () => !!(globalThis as any).__TAURI__;
+
 /* eslint-disable */
 
 // From https://stackoverflow.com/a/11381730/2804332.
-export const mobileAndTabletCheck = () => {
+export const isMobile = () => {
+    let check = false;
+    (function(a){if(/(android|bb\d+|meego).+mobile|avantgo|bada\/|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge |maemo|midp|mmp|mobile.+firefox|netfront|opera m(ob|in)i|palm( os)?|phone|p(ixi|re)\/|plucker|pocket|psp|series(4|6)0|symbian|treo|up\.(browser|link)|vodafone|wap|windows ce|xda|xiino/i.test(a)||/1207|6310|6590|3gso|4thp|50[1-6]i|770s|802s|a wa|abac|ac(er|oo|s\-)|ai(ko|rn)|al(av|ca|co)|amoi|an(ex|ny|yw)|aptu|ar(ch|go)|as(te|us)|attw|au(di|\-m|r |s )|avan|be(ck|ll|nq)|bi(lb|rd)|bl(ac|az)|br(e|v)w|bumb|bw\-(n|u)|c55\/|capi|ccwa|cdm\-|cell|chtm|cldc|cmd\-|co(mp|nd)|craw|da(it|ll|ng)|dbte|dc\-s|devi|dica|dmob|do(c|p)o|ds(12|\-d)|el(49|ai)|em(l2|ul)|er(ic|k0)|esl8|ez([4-7]0|os|wa|ze)|fetc|fly(\-|_)|g1 u|g560|gene|gf\-5|g\-mo|go(\.w|od)|gr(ad|un)|haie|hcit|hd\-(m|p|t)|hei\-|hi(pt|ta)|hp( i|ip)|hs\-c|ht(c(\-| |_|a|g|p|s|t)|tp)|hu(aw|tc)|i\-(20|go|ma)|i230|iac( |\-|\/)|ibro|idea|ig01|ikom|im1k|inno|ipaq|iris|ja(t|v)a|jbro|jemu|jigs|kddi|keji|kgt( |\/)|klon|kpt |kwc\-|kyo(c|k)|le(no|xi)|lg( g|\/(k|l|u)|50|54|\-[a-w])|libw|lynx|m1\-w|m3ga|m50\/|ma(te|ui|xo)|mc(01|21|ca)|m\-cr|me(rc|ri)|mi(o8|oa|ts)|mmef|mo(01|02|bi|de|do|t(\-| |o|v)|zz)|mt(50|p1|v )|mwbp|mywa|n10[0-2]|n20[2-3]|n30(0|2)|n50(0|2|5)|n7(0(0|1)|10)|ne((c|m)\-|on|tf|wf|wg|wt)|nok(6|i)|nzph|o2im|op(ti|wv)|oran|owg1|p800|pan(a|d|t)|pdxg|pg(13|\-([1-8]|c))|phil|pire|pl(ay|uc)|pn\-2|po(ck|rt|se)|prox|psio|pt\-g|qa\-a|qc(07|12|21|32|60|\-[2-7]|i\-)|qtek|r380|r600|raks|rim9|ro(ve|zo)|s55\/|sa(ge|ma|mm|ms|ny|va)|sc(01|h\-|oo|p\-)|sdk\/|se(c(\-|0|1)|47|mc|nd|ri)|sgh\-|shar|sie(\-|m)|sk\-0|sl(45|id)|sm(al|ar|b3|it|t5)|so(ft|ny)|sp(01|h\-|v\-|v )|sy(01|mb)|t2(18|50)|t6(00|10|18)|ta(gt|lk)|tcl\-|tdg\-|tel(i|m)|tim\-|t\-mo|to(pl|sh)|ts(70|m\-|m3|m5)|tx\-9|up(\.b|g1|si)|utst|v400|v750|veri|vi(rg|te)|vk(40|5[0-3]|\-v)|vm40|voda|vulc|vx(52|53|60|61|70|80|81|83|85|98)|w3c(\-| )|webc|whit|wi(g |nc|nw)|wmlb|wonu|x700|yas\-|your|zeto|zte\-/i.test(a.substr(0,4))) { check = true; } })(navigator.userAgent || navigator.vendor || (window as any).opera);
+    return check;
+  };
+
+export const isMobileOrTablet = () => {
   let check = false;
   ((a) => { if (/(android|bb\d+|meego).+mobile|avantgo|bada\/|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge |maemo|midp|mmp|mobile.+firefox|netfront|opera m(ob|in)i|palm( os)?|phone|p(ixi|re)\/|plucker|pocket|psp|series(4|6)0|symbian|treo|up\.(browser|link)|vodafone|wap|windows ce|xda|xiino|android|ipad|playbook|silk/i.test(a) || /1207|6310|6590|3gso|4thp|50[1-6]i|770s|802s|a wa|abac|ac(er|oo|s\-)|ai(ko|rn)|al(av|ca|co)|amoi|an(ex|ny|yw)|aptu|ar(ch|go)|as(te|us)|attw|au(di|\-m|r |s )|avan|be(ck|ll|nq)|bi(lb|rd)|bl(ac|az)|br(e|v)w|bumb|bw\-(n|u)|c55\/|capi|ccwa|cdm\-|cell|chtm|cldc|cmd\-|co(mp|nd)|craw|da(it|ll|ng)|dbte|dc\-s|devi|dica|dmob|do(c|p)o|ds(12|\-d)|el(49|ai)|em(l2|ul)|er(ic|k0)|esl8|ez([4-7]0|os|wa|ze)|fetc|fly(\-|_)|g1 u|g560|gene|gf\-5|g\-mo|go(\.w|od)|gr(ad|un)|haie|hcit|hd\-(m|p|t)|hei\-|hi(pt|ta)|hp( i|ip)|hs\-c|ht(c(\-| |_|a|g|p|s|t)|tp)|hu(aw|tc)|i\-(20|go|ma)|i230|iac( |\-|\/)|ibro|idea|ig01|ikom|im1k|inno|ipaq|iris|ja(t|v)a|jbro|jemu|jigs|kddi|keji|kgt( |\/)|klon|kpt |kwc\-|kyo(c|k)|le(no|xi)|lg( g|\/(k|l|u)|50|54|\-[a-w])|libw|lynx|m1\-w|m3ga|m50\/|ma(te|ui|xo)|mc(01|21|ca)|m\-cr|me(rc|ri)|mi(o8|oa|ts)|mmef|mo(01|02|bi|de|do|t(\-| |o|v)|zz)|mt(50|p1|v )|mwbp|mywa|n10[0-2]|n20[2-3]|n30(0|2)|n50(0|2|5)|n7(0(0|1)|10)|ne((c|m)\-|on|tf|wf|wg|wt)|nok(6|i)|nzph|o2im|op(ti|wv)|oran|owg1|p800|pan(a|d|t)|pdxg|pg(13|\-([1-8]|c))|phil|pire|pl(ay|uc)|pn\-2|po(ck|rt|se)|prox|psio|pt\-g|qa\-a|qc(07|12|21|32|60|\-[2-7]|i\-)|qtek|r380|r600|raks|rim9|ro(ve|zo)|s55\/|sa(ge|ma|mm|ms|ny|va)|sc(01|h\-|oo|p\-)|sdk\/|se(c(\-|0|1)|47|mc|nd|ri)|sgh\-|shar|sie(\-|m)|sk\-0|sl(45|id)|sm(al|ar|b3|it|t5)|so(ft|ny)|sp(01|h\-|v\-|v )|sy(01|mb)|t2(18|50)|t6(00|10|18)|ta(gt|lk)|tcl\-|tdg\-|tel(i|m)|tim\-|t\-mo|to(pl|sh)|ts(70|m\-|m3|m5)|tx\-9|up(\.b|g1|si)|utst|v400|v750|veri|vi(rg|te)|vk(40|5[0-3]|\-v)|vm40|voda|vulc|vx(52|53|60|61|70|80|81|83|85|98)|w3c(\-| )|webc|whit|wi(g |nc|nw)|wmlb|wonu|x700|yas\-|your|zeto|zte\-/i.test(a.substr(0,4))) { check = true; } })(navigator.userAgent || navigator.vendor || (window as any).opera);
   return check;
@@ -34,7 +44,7 @@ export const safariCheck = () =>
  */
 // From https://flaming.codes/posts/how-to-determine-os-in-browser.
 export const getHostPlatform = () => {
-  if (!('navigator' in window)) {
+  if (!('navigator' in globalThis)) {
     return 'unknown';
   }
 

package/src/position.test.ts

@@ -2,9 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, it, expect } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
-import { byPosition, type Position } from './position';
+import { type Position, byPosition } from './position';
 
 type TestItem = {
   id: number;

package/src/retry.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export interface RetryOptions<T> {
+  /**
+   * @default 3
+   */
+  count?: number;
+
+  /**
+   * @default 100
+   */
+  delayMs?: number;
+
+  /**
+   * Factor to increase delay by.
+   * @default 2
+   */
+  exponent?: number;
+
+  /**
+   * Retry if error matches the predicate.
+   * @default () => true
+   */
+  retryOnError?: (error: unknown) => Promise<boolean>;
+
+  /**
+   * Retry if value matches the predicate.
+   * @default () => false
+   */
+  retryOnValue?: (value: T) => Promise<boolean>;
+}
+
+const DEFAULT_RETRY_OPTIONS: Required<RetryOptions<unknown>> = {
+  count: 3,
+  delayMs: 100,
+  exponent: 2,
+  retryOnError: async () => true,
+  retryOnValue: async () => false,
+};
+
+/**
+ * Retries the operation a number of times.
+ * @returns The result of the succesfull invocation
+ * @throws Last error if all retries failed
+ */
+export const retry = async <T>(options: RetryOptions<T>, cb: () => Promise<T>): Promise<T> => {
+  const fullOptions: Required<RetryOptions<T>> = { ...DEFAULT_RETRY_OPTIONS, ...options };
+
+  let numRetries = 0,
+    currentDelay = fullOptions.delayMs;
+  while (true) {
+    let result: T;
+    try {
+      result = await cb();
+    } catch (err) {
+      if (numRetries > fullOptions.count || !(await fullOptions.retryOnError(err))) {
+        throw err;
+      }
+      await new Promise((resolve) => setTimeout(resolve, currentDelay));
+      currentDelay *= fullOptions.exponent;
+      numRetries++;
+      continue;
+    }
+    if (!(await fullOptions.retryOnValue(result))) {
+      return result;
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentDelay));
+    currentDelay *= fullOptions.exponent;
+    numRetries++;
+    continue;
+  }
+};

package/src/safe-parse.ts

@@ -2,31 +2,37 @@
 // Copyright 2024 DXOS.org
 //
 
-export const safeParseInt = (value: string | undefined, defaultValue?: number) => {
+export function safeParseInt(str: string | undefined, defaultValue: number): number;
+export function safeParseInt(str: string | undefined): number | undefined;
+export function safeParseInt(str: string | undefined, defaultValue?: number): number | undefined {
   try {
-    const n = parseInt(value ?? '');
-    return isNaN(n) ? defaultValue : n;
-  } catch (err) {
+    const value = parseInt(str ?? '');
+    return isNaN(value) ? defaultValue : value;
+  } catch {
     return defaultValue;
   }
-};
+}
 
-export const safeParseFloat = (str: string, defaultValue?: number): number | undefined => {
+export function safeParseFloat(str: string | undefined, defaultValue: number): number;
+export function safeParseFloat(str: string | undefined): number | undefined;
+export function safeParseFloat(str: string | undefined, defaultValue?: number): number | undefined {
   try {
-    return parseFloat(str);
+    const value = parseFloat(str ?? '');
+    return isNaN(value) ? defaultValue : value;
   } catch {
-    return defaultValue ?? 0;
+    return defaultValue;
   }
-};
+}
 
 export const safeParseJson: {
-  <T extends object>(data: string | undefined | null, defaultValue: T): T;
-  <T extends object>(data: string | undefined | null): T | undefined;
-} = <T extends object>(data: string | undefined | null, defaultValue?: T) => {
-  if (data && data.length > 0) {
+  <T extends object>(str: string | undefined | null, defaultValue: T): T;
+  <T extends object>(str: string | undefined | null): T | undefined;
+} = <T extends object = any>(str: string | undefined | null, defaultValue?: T): T | undefined => {
+  if (str && str.length > 0) {
     try {
-      return JSON.parse(data);
-    } catch (err) {}
+      return JSON.parse(str);
+    } catch {}
   }
+
   return defaultValue;
 };

package/src/safe-stringify.ts

@@ -0,0 +1,146 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export const SKIP = Object.freeze({});
+
+/**
+ * JSON.stringify replacer function.
+ */
+export type StringifyReplacer = (key: string, value: any) => typeof SKIP | any;
+
+/**
+ * Safely stringifies an object.
+ */
+export function safeStringify(obj: any, filter: StringifyReplacer = defaultFilter, indent = 2) {
+  const seen = new WeakMap<object, string>();
+
+  // NOTE: Called for the root object with undefined key.
+  function replacer(this: any, key: string, value: any) {
+    try {
+      let path = key;
+      if (!key) {
+        path = '$';
+        return value;
+      } else if (this) {
+        const parentPath = seen.get(this);
+        path = parentPath ? `${parentPath}.${key}` : key;
+      }
+
+      // Null or undefined.
+      if (value == null) {
+        return value;
+      }
+
+      // Ignore functions.
+      if (typeof value === 'function') {
+        return undefined;
+      }
+
+      // Ignore exotic objects (non-plain objects like DOM elements, class instances, etc.)
+      if (typeof value === 'object' && Object.getPrototypeOf(value) !== Object.prototype) {
+        return undefined;
+      }
+
+      // Check cycles.
+      if (typeof value === 'object' && value !== null) {
+        const exists = seen.get(value);
+        if (exists) {
+          return `[${path} => ${exists}]`;
+        }
+
+        seen.set(value, path);
+      }
+
+      if (filter) {
+        const filteredValue = filter?.(key, value);
+        if (filteredValue !== undefined) {
+          return filteredValue === SKIP ? undefined : filteredValue;
+        }
+      }
+
+      return value;
+    } catch (error: any) {
+      return `ERROR: ${error.message}`;
+    }
+  }
+
+  return JSON.stringify(obj, replacer, indent);
+}
+
+export type CreateReplacerProps = {
+  omit?: string[];
+  parse?: string[]; // TODO(burdon): Parse JSON value.
+  maxDepth?: number;
+  maxArrayLen?: number;
+  maxStringLen?: number;
+};
+
+/**
+ * Construct JSON.stringify replacer.
+ */
+// TODO(burdon): Change to composite effect.
+export const createReplacer = ({
+  omit,
+  parse,
+  maxDepth,
+  maxArrayLen,
+  maxStringLen,
+}: CreateReplacerProps = {}): StringifyReplacer => {
+  let currentDepth = 0;
+  const depthMap = new WeakMap<object, number>();
+
+  return function (this: any, key: string, value: any) {
+    // Track depth.
+    if (key === '') {
+      // Root.
+      currentDepth = 0;
+    } else if (this && typeof this === 'object') {
+      const parentDepth = depthMap.get(this) ?? 0;
+      currentDepth = parentDepth + 1;
+    }
+
+    // Skip functions.
+    if (typeof value === 'function') {
+      return SKIP;
+    }
+
+    // Store depth for this object.
+    if (value && typeof value === 'object') {
+      depthMap.set(value, currentDepth);
+
+      // Check max depth.
+      if (maxDepth != null && currentDepth >= maxDepth) {
+        return Array.isArray(value) ? `[{ length: ${value.length} }]` : `{ keys: ${Object.keys(value).length} }`;
+      }
+    }
+
+    // Apply other filters.
+    if (omit?.includes(key)) {
+      return SKIP;
+    }
+
+    // Parse JSON values.
+    if (parse?.includes(key) && typeof value === 'string') {
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    }
+
+    // Show array length.
+    if (maxArrayLen != null && Array.isArray(value) && value.length > maxArrayLen) {
+      return `[length: ${value.length}]`;
+    }
+
+    // Truncate strings.
+    if (maxStringLen != null && typeof value === 'string' && value.length > maxStringLen) {
+      return value.slice(0, maxStringLen) + '...';
+    }
+
+    return value;
+  };
+};
+
+export const defaultFilter: StringifyReplacer = createReplacer();

package/src/sort.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { compareMulti, compareScalar, compareObject, compareString } from './sort';
+import { compareMulti, compareObject, compareScalar, compareString } from './sort';
 
 const data = [
   { i: 0, idx: 1, label: 'apple' },

package/src/string.test.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { trim } from './string';
+
+describe('string', () => {
+  test('dedent', async ({ expect }) => {
+    const text = trim`
+      - 1
+      - 2
+        - 3
+    `;
+
+    expect(text).to.eq('- 1\n- 2\n  - 3');
+  });
+});