@dxos/util 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

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,13 +15,16 @@ 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 './first-two-chars';
+export * from './error-format';
+export * from './filename';
 export * from './for-each-async';
 export * from './human-hash';
+export * from './id';
 export * from './instance-id';
 export * from './interval';
 export * from './join-tables';
@@ -38,10 +42,11 @@ 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';
-export * from './sliding-window-summary';
+export * from './safe-stringify';
 export * from './sliding-window-summary';
 export * from './sort';
 export * from './string';
@@ -52,5 +57,6 @@ export * from './tracer';
 export * from './tree';
 export * from './types';
 export * from './uint8array';
+export * from './unit';
 export * from './url';
 export * from './weak';

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/map-values.ts

@@ -52,6 +52,9 @@ class DeepMapper {
         res[i] = this._map(value[i], i);
       }
       return res;
+    } else if (ArrayBuffer.isView(value)) {
+      // Typed arrays (Uint8Array, etc.) are opaque leaf values, not POJOs to recurse into.
+      return value;
     } else if (value !== null && typeof value === 'object') {
       const res: any = {};
       this._cyclic.set(value, res);
@@ -112,6 +115,9 @@ class DeepMapperAsync {
         res[i] = await this._map(value[i], i);
       }
       return res;
+    } else if (ArrayBuffer.isView(value)) {
+      // Typed arrays (Uint8Array, etc.) are opaque leaf values, not POJOs to recurse into.
+      return value;
     } else if (value !== null && typeof value === 'object') {
       const res: any = {};
       this._cyclic.set(value, res);

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,12 +5,44 @@
 // 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);
+  ((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 +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/position.test.ts

@@ -2,9 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, it, expect } from 'vitest';
+import { describe, test } from 'vitest';
 
-import { byPosition, type Position } from './position';
+import { type Position, byPosition } from './position';
 
 type TestItem = {
   id: number;
@@ -12,14 +12,14 @@ type TestItem = {
 };
 
 describe('byPosition', () => {
-  it('should keep items with same position in their original order', () => {
+  test('should keep items with same position in their original order', ({ expect }) => {
     const items: TestItem[] = [
-      { id: 1, position: 'static' },
-      { id: 2, position: 'static' },
-      { id: 3, position: 'hoist' },
-      { id: 4, position: 'hoist' },
-      { id: 5, position: 'fallback' },
-      { id: 6, position: 'fallback' },
+      { id: 1 },
+      { id: 2 },
+      { id: 3, position: 'first' },
+      { id: 4, position: 'first' },
+      { id: 5, position: 'last' },
+      { id: 6, position: 'last' },
     ];
 
     const sorted = [...items].sort(byPosition);
@@ -30,69 +30,63 @@ describe('byPosition', () => {
     expect(sorted.findIndex((item) => item.id === 5)).toBeLessThan(sorted.findIndex((item) => item.id === 6));
   });
 
-  it('should place "hoist" items before "static" items', () => {
-    const items: TestItem[] = [
-      { id: 1, position: 'static' },
-      { id: 2, position: 'hoist' },
-    ];
+  test('should place "first" items before items in natural order', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1 }, { id: 2, position: 'first' }];
 
     const sorted = [...items].sort(byPosition);
-    expect(sorted[0].position).toBe('hoist');
-    expect(sorted[1].position).toBe('static');
+    expect(sorted[0].position).toBe('first');
+    expect(sorted[1].position).toBeUndefined();
   });
 
-  it('should place "fallback" items after "static" items', () => {
-    const items: TestItem[] = [
-      { id: 1, position: 'fallback' },
-      { id: 2, position: 'static' },
-    ];
+  test('should place "last" items after items in natural order', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1, position: 'last' }, { id: 2 }];
 
     const sorted = [...items].sort(byPosition);
-    expect(sorted[0].position).toBe('static');
-    expect(sorted[1].position).toBe('fallback');
+    expect(sorted[0].position).toBeUndefined();
+    expect(sorted[1].position).toBe('last');
   });
 
-  it('should treat items without position as "static"', () => {
-    const items: TestItem[] = [{ id: 1 }, { id: 2, position: 'hoist' }, { id: 3, position: 'fallback' }];
+  test('should treat items without position as natural order', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1 }, { id: 2, position: 'first' }, { id: 3, position: 'last' }];
 
     const sorted = [...items].sort(byPosition);
-    expect(sorted[0].position).toBe('hoist');
+    expect(sorted[0].position).toBe('first');
     expect(sorted[1].position).toBeUndefined();
-    expect(sorted[2].position).toBe('fallback');
+    expect(sorted[2].position).toBe('last');
   });
 
-  it('should correctly sort mixed positions', () => {
+  test('should correctly sort mixed positions', ({ expect }) => {
     const items: TestItem[] = [
-      { id: 1, position: 'fallback' },
-      { id: 2, position: 'static' },
-      { id: 3, position: 'hoist' },
-      { id: 4 }, // implicit static
-      { id: 5, position: 'hoist' },
-      { id: 6, position: 'fallback' },
+      { id: 1, position: 'last' },
+      { id: 2 },
+      { id: 3, position: 'first' },
+      { id: 4 },
+      { id: 5, position: 'first' },
+      { id: 6, position: 'last' },
     ];
 
     const sorted = [...items].sort(byPosition);
 
-    // All hoisted items should come first
-    expect(sorted[0].position).toBe('hoist');
-    expect(sorted[1].position).toBe('hoist');
+    // All "first" items should come first
+    expect(sorted[0].position).toBe('first');
+    expect(sorted[1].position).toBe('first');
 
-    // Static items (including undefined) should be in the middle
-    expect(sorted[2].position).toBe('static');
+    // Natural-order items (undefined) should be in the middle
+    expect(sorted[2].position).toBeUndefined();
     expect(sorted[3].position).toBeUndefined();
 
-    // Fallback items should be last
-    expect(sorted[4].position).toBe('fallback');
-    expect(sorted[5].position).toBe('fallback');
+    // "last" items should be at the end
+    expect(sorted[4].position).toBe('last');
+    expect(sorted[5].position).toBe('last');
   });
 
-  it('should handle empty arrays', () => {
+  test('should handle empty arrays', ({ expect }) => {
     const items: TestItem[] = [];
     expect(() => [...items].sort(byPosition)).not.toThrow();
   });
 
-  it('should handle single item arrays', () => {
-    const items: TestItem[] = [{ id: 1, position: 'static' }];
+  test('should handle single item arrays', ({ expect }) => {
+    const items: TestItem[] = [{ id: 1 }];
     expect(() => [...items].sort(byPosition)).not.toThrow();
   });
 });

package/src/position.ts

@@ -6,25 +6,21 @@
 
 /**
  * Determines priority order:
- * - `static` - Remain in natural order.
- * - `hoist` - Placed before `static`.
- * - `fallback` - Placed after `static`.
+ * - `undefined` - Remain in natural order.
+ * - `first` - Placed before items in natural order.
+ * - `last` - Placed after items in natural order.
  */
-// TODO(wittjosiah): Change to 'static' | 'start' | 'end'.
-export type Position = 'static' | 'hoist' | 'fallback';
+export type Position = 'first' | 'last';
 
 /**
  * Sorting function for sorting by position.
  */
-export const byPosition = <T extends { position?: Position }>(
-  { position: a = 'static' }: T,
-  { position: b = 'static' }: T,
-) => {
+export const byPosition = <T extends { position?: Position }>({ position: a }: T, { position: b }: T) => {
   if (a === b) {
     return 0;
-  } else if (a === 'hoist' || b === 'fallback') {
+  } else if (a === 'first' || b === 'last') {
     return -1;
-  } else if (b === 'hoist' || a === 'fallback') {
+  } else if (b === 'first' || a === 'last') {
     return 1;
   } else {
     return 0;

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,45 @@
 // 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;
 };
+
+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');
+  });
+});