@dxos/util 0.8.4-main.fbb7a13 → 0.8.4-main.fcc0d83b33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.4-main.fbb7a13",
+  "version": "0.8.4-main.fcc0d83b33",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -23,26 +23,19 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
     "@hazae41/symbol-dispose-polyfill": "^1.0.2",
-    "lodash.get": "^4.4.2",
-    "lodash.set": "^4.3.2",
-    "@dxos/debug": "0.8.4-main.fbb7a13",
-    "@dxos/invariant": "0.8.4-main.fbb7a13",
-    "@dxos/keys": "0.8.4-main.fbb7a13",
-    "@dxos/node-std": "0.8.4-main.fbb7a13"
+    "@dxos/invariant": "0.8.4-main.fcc0d83b33",
+    "@dxos/keys": "0.8.4-main.fcc0d83b33",
+    "@dxos/debug": "0.8.4-main.fcc0d83b33",
+    "@dxos/node-std": "0.8.4-main.fcc0d83b33"
   },
   "devDependencies": {
-    "@types/lodash.get": "^4.4.9",
-    "@types/lodash.set": "^4.3.9",
-    "@dxos/crypto": "0.8.4-main.fbb7a13"
+    "@dxos/crypto": "0.8.4-main.fcc0d83b33"
   },
   "publishConfig": {
     "access": "public"

package/src/browser-storage.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/** Delete all IndexedDB databases for this origin. */
+export const clearIndexedDB = async (): Promise<void> => {
+  const dbs = await indexedDB.databases();
+  const results = await Promise.allSettled(
+    dbs
+      .filter((db) => db.name != null)
+      .map(
+        (db) =>
+          new Promise<void>((resolve, reject) => {
+            const request = indexedDB.deleteDatabase(db.name!);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+            request.onblocked = () => reject(new Error(`IndexedDB deletion blocked: ${db.name}`));
+          }),
+      ),
+  );
+  const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');
+  if (failures.length > 0) {
+    throw new AggregateError(
+      failures.map((r) => r.reason),
+      'Failed to delete some IndexedDB databases',
+    );
+  }
+};
+
+/** Remove all entries from the Origin Private File System. */
+export const clearOPFS = async (): Promise<void> => {
+  const root = await navigator.storage.getDirectory();
+  const errors: unknown[] = [];
+  for await (const [name] of root.entries()) {
+    try {
+      await root.removeEntry(name, { recursive: true });
+    } catch (err) {
+      errors.push(err);
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, 'Failed to remove some OPFS entries');
+  }
+};
+
+/** Unregister all service workers for this origin. */
+export const clearServiceWorkers = async (): Promise<void> => {
+  const regs = await navigator.serviceWorker.getRegistrations();
+  for (const reg of regs) {
+    await reg.unregister();
+  }
+};
+
+/** Delete all HTTP caches for this origin. */
+export const clearCaches = async (): Promise<void> => {
+  const keys = await caches.keys();
+  for (const key of keys) {
+    await caches.delete(key);
+  }
+};

package/src/circular-buffer.test.ts

@@ -16,6 +16,32 @@ describe('CircularBuffer', () => {
     }
   });
 
+  test('clear resets buffer', () => {
+    const buffer = new CircularBuffer<number>(5);
+    buffer.push(1);
+    buffer.push(2);
+    buffer.push(3);
+    expect(buffer.elementCount).toBe(3);
+
+    buffer.clear();
+    expect(buffer.elementCount).toBe(0);
+    expect([...buffer]).toStrictEqual([]);
+    expect(buffer.getLast()).toBeUndefined();
+  });
+
+  test('clear allows reuse', () => {
+    const buffer = new CircularBuffer<number>(3);
+    buffer.push(10);
+    buffer.push(20);
+    buffer.clear();
+
+    buffer.push(30);
+    buffer.push(40);
+    expect(buffer.elementCount).toBe(2);
+    expect([...buffer]).toStrictEqual([30, 40]);
+    expect(buffer.getLast()).toBe(40);
+  });
+
   test('full cycle', () => {
     const maxSize = 10;
     const regularArray: number[] = [];

package/src/circular-buffer.ts

@@ -26,6 +26,11 @@ export class CircularBuffer<T> {
     return this._elementCount;
   }
 
+  public clear(): void {
+    this._nextIndex = 0;
+    this._elementCount = 0;
+  }
+
   public getLast(): T | undefined {
     if (this._elementCount === 0) {
       return undefined;

package/src/complex.ts

@@ -214,6 +214,38 @@ export class ComplexMap<K, V> implements Map<K, V> {
     return this;
   }
 
+  /**
+   * Returns the value for the given key if present, otherwise inserts and returns the default value.
+   * @param key - The key to look up or insert.
+   * @param defaultValue - The value to insert if the key is not present.
+   * @returns The existing or newly inserted value.
+   */
+  getOrInsert(key: K, defaultValue: V): V {
+    const primitive = this._keyProjection(key);
+    if (this._values.has(primitive)) {
+      return this._values.get(primitive)!;
+    }
+    this.set(key, defaultValue);
+    return defaultValue;
+  }
+
+  /**
+   * Returns the value for the given key if present, otherwise computes, inserts, and returns a new value.
+   * The callback is only invoked when the key is missing.
+   * @param key - The key to look up or insert.
+   * @param callbackfn - Function to compute the value if the key is not present.
+   * @returns The existing or newly computed value.
+   */
+  getOrInsertComputed(key: K, callbackfn: (key: K) => V): V {
+    const primitive = this._keyProjection(key);
+    if (this._values.has(primitive)) {
+      return this._values.get(primitive)!;
+    }
+    const value = callbackfn(key);
+    this.set(key, value);
+    return value;
+  }
+
   get size(): number {
     return this._keys.size;
   }

package/src/composite-key.test.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { compositeKey, splitCompositeKey } from './composite-key';
+
+describe('compositeKey', () => {
+  test('joins parts with colon', ({ expect }) => {
+    expect(compositeKey('a', 'b', 'c')).to.eq('a:b:c');
+  });
+
+  test('single part returns as-is', ({ expect }) => {
+    expect(compositeKey('only')).to.eq('only');
+  });
+
+  test('handles empty strings in parts', ({ expect }) => {
+    expect(compositeKey('', 'b')).to.eq(':b');
+  });
+});
+
+describe('splitCompositeKey', () => {
+  test('splits on colon', ({ expect }) => {
+    expect(splitCompositeKey('a:b:c')).to.deep.eq(['a', 'b', 'c']);
+  });
+
+  test('single part returns array of one', ({ expect }) => {
+    expect(splitCompositeKey('only')).to.deep.eq(['only']);
+  });
+});

package/src/composite-key.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+const SEPARATOR = ':';
+
+/**
+ * Build a composite key from string parts joined by a colon separator.
+ * Parts must not contain the separator character.
+ */
+export const compositeKey = (...parts: string[]): string => parts.join(SEPARATOR);
+
+/**
+ * Split a composite key back into its parts.
+ */
+export const splitCompositeKey = (key: string): string[] => key.split(SEPARATOR);

package/src/deep.ts

@@ -2,14 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-import get from 'lodash.get';
-import set from 'lodash.set';
-
 import { invariant } from '@dxos/invariant';
 
-// TODO(burdon): Re-export most common utils? (isEqual, defaultsDeep, merge, omit, pick, etc.)
-export { get, set };
-
 /**
  * Initialize a deeply nested object.
  * @returns The value of the prop after assignment.

package/src/di-key.ts

@@ -47,7 +47,7 @@ export type DiKey<T> =
     }
   | SymbolDiKey<T>;
 
-export const DiKey = new (class DiKeyConstructor {
+class DiKeyConstructor {
   /**
    * Needed to ensure referential equality of combined keys.
    *
@@ -57,7 +57,7 @@ export const DiKey = new (class DiKeyConstructor {
    */
   // TODO(dmaretskyi): Disable private members lowering for dev env.
   // TODO(dmaretskyi): Could be a weak map after a NodeJS upgrade.
-  #combinedRegistry = new WeakMap();
+  private _combinedRegistry = new WeakMap();
 
   define<T>(name: string): DiKey<T> {
     return new SymbolDiKey(name);
@@ -88,24 +88,26 @@ export const DiKey = new (class DiKeyConstructor {
    * Maintains referential equality: `DiKey.combine(A, B) === DiKey.combine(A, B)`
    */
   combine(...ids: DiKey<any>[]) {
-    const map = this.#lookupCombined(this.#combinedRegistry, ids);
-    return defaultMap(this.#combinedRegistry, map, () => this.#combinedDescription(ids));
+    const map = this._lookupCombined(this._combinedRegistry, ids);
+    return defaultMap(this._combinedRegistry, map, () => this._combinedDescription(ids));
   }
 
   getSingletonFactory<T>(id: DiKey<T>): SingletonFactory<T> | undefined {
     return (id as any)[symbolSingleton];
   }
 
-  #lookupCombined(map: WeakMap<any, any>, [first, ...rest]: DiKey<any>[]): WeakMap<any, any> {
+  private _lookupCombined(map: WeakMap<any, any>, [first, ...rest]: DiKey<any>[]): WeakMap<any, any> {
     const value = defaultMap(map, first, () => new Map());
     if (rest.length > 0) {
-      return this.#lookupCombined(value, rest);
+      return this._lookupCombined(value, rest);
     } else {
       return value;
     }
   }
 
-  #combinedDescription([first, ...rest]: DiKey<any>[]) {
+  private _combinedDescription([first, ...rest]: DiKey<any>[]) {
     return `${this.stringify(first)}<${rest.map(this.stringify).join(', ')}>`;
   }
-})();
+}
+
+export const DiKey = new DiKeyConstructor();

package/src/error-format.ts

@@ -13,7 +13,9 @@ export const formatErrorWithCauses = (error: Error): string => {
   while (current) {
     const prefix = level === 0 ? '' : `Caused by: `;
     lines.push(prefix + (current.stack ?? String(current)));
-    if (!(current.cause instanceof Error)) break;
+    if (!(current.cause instanceof Error)) {
+      break;
+    }
     current = current.cause;
     level += 1;
   }

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './array';
 export * from './assume';
 export * from './binder';
 export * from './bitfield';
+export * from './browser-storage';
 export * from './callback-collection';
 export * from './callback';
 export * from './case';
@@ -14,10 +15,12 @@ export * from './chunk-array';
 export * from './circular-buffer';
 export * from './clear-undefined';
 export * from './complex';
+export * from './composite-key';
 export * from './deep';
 export * from './defer-function';
 export * from './defer';
 export * from './entry';
+export * from './error-format';
 export * from './filename';
 export * from './for-each-async';
 export * from './human-hash';
@@ -38,6 +41,7 @@ export * from './random';
 export * from './range';
 export * from './reducers';
 export * from './remove-undefined-keys';
+export * from './retry';
 export * from './safe-await';
 export * from './safe-instanceof';
 export * from './safe-parse';
@@ -55,5 +59,3 @@ export * from './uint8array';
 export * from './unit';
 export * from './url';
 export * from './weak';
-export * from './error-format';
-export * from './retry';

package/src/platform.ts

@@ -13,14 +13,36 @@ export const isTauri = () => !!(globalThis as any).__TAURI__;
 
 // From https://stackoverflow.com/a/11381730/2804332.
 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;
-  };
+  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);
+  ((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;
 };
 
@@ -44,7 +66,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/safe-parse.ts

@@ -36,3 +36,11 @@ export const safeParseJson: {
 
   return defaultValue;
 };
+
+export const safeUrl = (str: string | undefined | null): URL | undefined => {
+  try {
+    return new URL(str ?? '');
+  } catch {
+    return undefined;
+  }
+};

package/src/safe-stringify.test.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { SKIP, createReplacer, safeStringify } from './safe-stringify';
+
+describe('safeStringify', () => {
+  test('stringifies plain nested objects', ({ expect }) => {
+    const data = { a: 1, b: { c: 'hello' } };
+    const result = safeStringify(data);
+    expect(result).to.include('"a": 1');
+    expect(result).to.include('"b"');
+    expect(result).to.include('"c": "hello"');
+  });
+
+  test('handles circular references (Cycle story)', ({ expect }) => {
+    const cycle: Record<string, unknown> = { a: 1, b: [] };
+    (cycle.b as unknown[]).push(cycle);
+
+    const result = safeStringify(cycle);
+    expect(result).to.include('"a": 1');
+    expect(result).to.include('=> $]');
+    expect(result).to.match(/\[\$\.b\.\d+ => \$\]/);
+  });
+
+  test('handles multiple circular references', ({ expect }) => {
+    const obj: Record<string, unknown> = { x: 1 };
+    obj.self = obj;
+
+    const result = safeStringify(obj);
+    expect(result).to.include('"x": 1');
+    expect(result).to.include('[$.self => $]');
+  });
+
+  test('filters functions', ({ expect }) => {
+    const data = { a: 1, fn: () => {} };
+    const result = safeStringify(data);
+    expect(result).to.include('"a": 1');
+    expect(result).not.to.include('fn');
+  });
+
+  test('filters exotic objects', ({ expect }) => {
+    class Custom {}
+    const data = { a: 1, exotic: new Custom() };
+    const result = safeStringify(data);
+    expect(result).to.include('"a": 1');
+    expect(result).not.to.include('exotic');
+  });
+
+  test('preserves arrays', ({ expect }) => {
+    const data = { arr: [1, 2, 3] };
+    const result = safeStringify(data);
+    expect(result).to.include('"arr"');
+    expect(result).to.include('1');
+    expect(result).to.include('2');
+    expect(result).to.include('3');
+  });
+});
+
+describe('createReplacer', () => {
+  test('maxArrayLen truncates long arrays (Large story)', ({ expect }) => {
+    const data = { arr: Array.from({ length: 15 }, (_, index) => index) };
+    const result = safeStringify(data, createReplacer({ maxArrayLen: 10 }));
+    expect(result).to.include('"[length: 15]"');
+  });
+
+  test('maxStringLen truncates long strings (Large story)', ({ expect }) => {
+    const data = { str: 'a'.repeat(20) };
+    const result = safeStringify(data, createReplacer({ maxStringLen: 10 }));
+    expect(result).to.include('"aaaaaaaaaa..."');
+  });
+
+  test('omit skips specified keys', ({ expect }) => {
+    const data = { a: 1, secret: 'hide', b: 2 };
+    const result = safeStringify(data, createReplacer({ omit: ['secret'] }));
+    expect(result).to.include('"a": 1');
+    expect(result).to.include('"b": 2');
+    expect(result).not.to.include('secret');
+  });
+
+  test('parse parses JSON string values', ({ expect }) => {
+    const data = { nested: '{"x":1}' };
+    const result = safeStringify(data, createReplacer({ parse: ['nested'] }));
+    expect(result).to.include('"x": 1');
+  });
+
+  test('SKIP return value removes key from output', ({ expect }) => {
+    const customReplacer = (_key: string, value: unknown) => (_key === 'skip' ? SKIP : value);
+    const data = { a: 1, skip: 'hidden' };
+    const result = safeStringify(data, customReplacer);
+    expect(result).to.include('"a": 1');
+    expect(result).not.to.include('skip');
+  });
+});

package/src/safe-stringify.ts

@@ -12,7 +12,7 @@ export type StringifyReplacer = (key: string, value: any) => typeof SKIP | any;
 /**
  * Safely stringifies an object.
  */
-export function safeStringify(obj: any, filter: StringifyReplacer = defaultFilter, indent = 2) {
+export function safeStringify(obj: any, filter: StringifyReplacer | undefined = defaultFilter, indent = 2) {
   const seen = new WeakMap<object, string>();
 
   // NOTE: Called for the root object with undefined key.
@@ -21,6 +21,9 @@ export function safeStringify(obj: any, filter: StringifyReplacer = defaultFilte
       let path = key;
       if (!key) {
         path = '$';
+        if (value != null && typeof value === 'object') {
+          seen.set(value, path);
+        }
         return value;
       } else if (this) {
         const parentPath = seen.get(this);
@@ -38,7 +41,7 @@ export function safeStringify(obj: any, filter: StringifyReplacer = defaultFilte
       }
 
       // Ignore exotic objects (non-plain objects like DOM elements, class instances, etc.)
-      if (typeof value === 'object' && Object.getPrototypeOf(value) !== Object.prototype) {
+      if (typeof value === 'object' && Object.getPrototypeOf(value) !== Object.prototype && !Array.isArray(value)) {
         return undefined;
       }
 
@@ -65,7 +68,11 @@ export function safeStringify(obj: any, filter: StringifyReplacer = defaultFilte
     }
   }
 
-  return JSON.stringify(obj, replacer, indent);
+  try {
+    return JSON.stringify(obj, replacer, indent);
+  } catch (error: any) {
+    return `ERROR: ${error.message}`;
+  }
 }
 
 export type CreateReplacerProps = {
@@ -105,6 +112,11 @@ export const createReplacer = ({
       return SKIP;
     }
 
+    // Show array length.
+    if (maxArrayLen != null && Array.isArray(value) && value.length > maxArrayLen) {
+      return `[length: ${value.length}]`;
+    }
+
     // Store depth for this object.
     if (value && typeof value === 'object') {
       depthMap.set(value, currentDepth);
@@ -129,11 +141,6 @@ export const createReplacer = ({
       }
     }
 
-    // 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) + '...';

package/src/string.ts

@@ -32,8 +32,12 @@ export function trim(strings: TemplateStringsArray, ...values: any[]) {
   // Split into lines and trim leading/trailing blank lines.
   const lines = raw.split('\n');
 
-  while (lines.length && !lines[0].trim()) lines.shift();
-  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  while (lines.length && !lines[0].trim()) {
+    lines.shift();
+  }
+  while (lines.length && !lines[lines.length - 1].trim()) {
+    lines.pop();
+  }
 
   // Find smallest indent across all non-blank lines.
   const minIndent = Math.min(...lines.filter((l) => l.trim()).map((l) => l.match(/^[ \t]*/)?.[0].length ?? 0));