@dxos/util 0.8.4-main.fd6878d → 0.8.4-main.fdfb99ef29

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

@@ -0,0 +1,153 @@
+//
+// 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 | undefined = 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 = '$';
+        if (value != null && typeof value === 'object') {
+          seen.set(value, 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 && !Array.isArray(value)) {
+        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}`;
+    }
+  }
+
+  try {
+    return JSON.stringify(obj, replacer, indent);
+  } catch (error: any) {
+    return `ERROR: ${error.message}`;
+  }
+}
+
+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;
+    }
+
+    // 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);
+
+      // 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;
+      }
+    }
+
+    // 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/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));
@@ -41,3 +45,10 @@ export function trim(strings: TemplateStringsArray, ...values: any[]) {
   // Remove that indent from all lines.
   return lines.map((l) => l.slice(minIndent)).join('\n');
 }
+
+// From https://stackoverflow.com/a/67243723/2804332
+/**
+ * Converts a string to kebab case.
+ */
+export const kebabize = (str: string) =>
+  str.replace(/[A-Z]+(?![a-z])|[A-Z]/g, ($, ofs) => (ofs ? '-' : '') + $.toLowerCase());

package/src/to-fallback.ts

@@ -4,166 +4,55 @@
 
 import { type PublicKey } from '@dxos/keys';
 
+/**
+ * When changing this set, please check the result in a console or e.g. RunKit (https://runkit.com/thure/642214441dd6ae000855a8de)
+ * Emoji sometimes use a combination of code points, and some code points aren't visible on their own, so by adding or deleting you may unintentionally create non-visible items.
+ * This set was chosen from the characters in Unicode Emoji v15.0 based on the following criteria:
+ * – not people or isolated anthropomorphic faces
+ * – not flags
+ * – more concrete than abstract
+ * – less culturally specific
+ * – less easily confused with another emoji in the set
+ * – requires less special knowledge to identify
+ * – less likely to evoke negative feelings (no meat, no drugs, no weapons, etc)
+ * – less common as a signifier in UX
+ * NOTE that this is intentionally an array of strings because of the way emoji graphemes work.
+ */
+// prettier-ignore
 export const idEmoji = [
-  // When changing this set, please check the result in a console or e.g. RunKit (https://runkit.com/thure/642214441dd6ae000855a8de)
-  // Emoji sometimes use a combination of code points, and some code points aren't visible on their own, so by adding or deleting you may unintentionally create non-visible items.
-  // This set was chosen from the characters in Unicode Emoji v15.0 based on the following criteria:
-  // – not people or isolated anthropomorphic faces
-  // – not flags
-  // – more concrete than abstract
-  // – less culturally specific
-  // – less easily confused with another emoji in the set
-  // – requires less special knowledge to identify
-  // – less likely to evoke negative feelings (no meat, no drugs, no weapons, etc)
-  // – less common as a signifier in UX
-  // NOTE that this is intentionally an array of strings because of the way emoji graphemes work.
-  '👻',
-  '👹',
-  '👽',
-  '🤖',
-  '🎃',
-  '🦾',
-  '🦿',
-  '🦷',
-  '👣',
-  '👁️',
-  '🧶',
-  '👑',
-  '🐒',
-  '🦆',
-  '🦉',
-  '🐴',
-  '🦄',
-  '🐝',
-  '🦋',
-  '🐞',
-  '🪲',
-  '🐢',
-  '🦎',
-  '🦕',
-  '🦑',
-  '🦀',
-  '🐠',
-  '🐬',
-  '🐋',
-  '🦭',
-  '🐅',
-  '🐆',
-  '🦓',
-  '🦍',
-  '🦧',
-  '🐘',
-  '🐫',
-  '🦒',
-  '🦘',
-  '🦬',
-  '🐖',
-  '🐏',
-  '🦌',
-  '🐕',
-  '🐈',
-  '🐓',
-  '🦚',
-  '🦜',
-  '🦢',
-  '🦩',
-  '🦦',
-  '🐁',
-  '🐿️',
-  '🌵',
-  '🌲',
-  '🌳',
-  '🪵',
-  '🌱',
-  '🍁',
-  '🪺',
-  '🍄',
-  '🐚',
-  '🪸',
-  '🪨',
-  '🌾',
-  '🌷',
-  '🌻',
-  '☀️',
-  '🌙',
-  '🪐',
-  '⭐️',
-  '⚡️',
-  '☄️',
-  '🔥',
-  '🌈',
-  '☁️',
-  '💧',
-  '⛱️',
-  '🌊',
-  '🍎',
-  '🍋',
-  '🍉',
-  '🍇',
-  '🫐',
-  '🍈',
-  '🍒',
-  '🍑',
-  '🥭',
-  '🍍',
-  '🥥',
-  '🥝',
-  '🥑',
-  '🌶️',
-  '🌽',
-  '🥕',
-  '🍬',
-  '🥜',
-  '🫖',
-  '☕️',
-  '🍵',
-  '🧊',
-  '🧂',
-  '🏔️',
-  '⚓️',
-  '🛟',
-  '🏝️',
-  '🛶',
-  '🚀',
-  '🛰️',
-  '⛲️',
-  '🏰',
-  '🚲',
-  '⛺️',
-  '🎙️',
-  '🧲',
-  '⚙️',
-  '🔩',
-  '🔮',
-  '🔭',
-  '🔬',
-  '🧬',
-  '🌡️',
-  '🧺',
-  '🛎️',
-  '🔑',
-  '🪑',
-  '🧸',
-  '🎈',
-  '🎀',
-  '🎊',
-  '♻️',
-  '🎵',
+  '👻', '👹', '👽', '🤖', '🎃', '🦾', '🦿', '🦷', 
+  '👣', '👁️', '🧶', '👑', '🐒', '🦆', '🦉', '🐴',
+  '🦄', '🐝', '🦋', '🐞', '🪲', '🐢', '🦎', '🦕', 
+  '🦑', '🦀', '🐠', '🐬', '🐋', '🦭', '🐅', '🐆', 
+  '🦓', '🦍', '🦧', '🐘', '🐫', '🦒', '🦘', '🦬', 
+  '🐖', '🐏', '🦌', '🐕', '🐈', '🐓', '🦚', '🦜', 
+  '🦢', '🦩', '🦦', '🐁', '🐿️', '🌵', '🌲', '🌳',
+  '🪵', '🌱', '🍁', '🪺', '🍄', '🐚', '🪸', '🪨',
+  '🌾', '🌷', '🌻', '☀️', '🌙', '🪐', '⭐️', '⚡️',
+  '☄️', '🔥', '🌈', '☁️', '💧', '⛱️', '🌊', '🍎',
+  '🍋', '🍉', '🍇', '🫐', '🍈', '🍒', '🍑', '🥭',
+  '🍍', '🥥', '🥝', '🥑', '🌶️', '🌽', '🥕', '🍬',
+  '🥜', '🫖', '☕️', '🍵', '🧊', '🧂', '🏔️', '⚓️',
+  '🛟', '🏝️', '🛶', '🚀', '🛰️', '⛲️', '🏰', '🚲',
+  '⛺️', '🎙️', '🧲', '⚙️', '🔩', '🔮', '🔭', '🔬',
+  '🧬', '🌡️', '🧺', '🛎️', '🔑', '🪑', '🧸', '🎈',
+  '🎀', '🎊', '♻️', '🎵',
 ];
 
 export const idHue = [
   'red' as const,
-  // 'orange' as const, /* More shades in these palettes are considered “ugly” */
-  'amber' as const, // Amber arcs between red-orange and yellow as it gets lighter, so improves aesthetics.
-  // 'yellow' as const, /* More shades in these palettes are considered “ugly” */
+  'orange' as const,
+  'amber' as const,
+  'yellow' as const,
   'lime' as const,
   'green' as const,
   'emerald' as const,
   'teal' as const,
   'cyan' as const,
-  // 'sky' as const, /* Omitted since it is quite similar to the primary accent palette */
-  // 'blue' as const, /* Omitted since it is quite similar to the primary accent palette */
-  // 'indigo' as const, /* Omitted since it is quite similar to the primary accent palette */
+  // Omit colors similar to primary accent.
+  // 'sky' as const,
+  // 'blue' as const,
+  // 'indigo' as const,
   'violet' as const,
   'purple' as const,
   'fuchsia' as const,
@@ -171,17 +60,11 @@ export const idHue = [
   'rose' as const,
 ];
 
-// TODO(wittjosiah): Do we need all of these variants?
 export const keyToEmoji = (key: PublicKey) => keyToFallback(key).emoji;
-
 export const hexToEmoji = (hex: string) => hexToFallback(hex).emoji;
-
 export const toEmoji = (hash: number) => toFallback(hash).emoji;
-
 export const keyToHue = (key: PublicKey) => keyToFallback(key).hue;
-
 export const hexToHue = (hex: string) => hexToFallback(hex).hue;
-
 export const toHue = (hash: number) => toFallback(hash).hue;
 
 export type FallbackValue = {
@@ -194,17 +77,18 @@ export const keyToFallback = (key: PublicKey) => hexToFallback(key.toHex());
 // TODO(wittjosiah): Support non-hex strings (e.g. DIDs, UUIDs, etc.)
 export const hexToFallback = (hex: string) => toFallback(parseInt(hex, 16));
 
+// TODO(burdon): Rename?
 export const toFallback = (hash: number): FallbackValue => {
-  // Calculate total possible combinations of emoji and hue pairs
+  // Calculate total possible combinations of emoji and hue pairs.
   const totalCombinations = idEmoji.length * idHue.length;
 
-  // Get a deterministic index within the range of all possible combinations
+  // Get a deterministic index within the range of all possible combinations.
   const combinationIndex = hash % totalCombinations;
 
-  // Calculate which emoji to use based on the combination index
+  // Calculate which emoji to use based on the combination index.
   const emojiIndex = Math.floor(combinationIndex / idHue.length);
 
-  // Calculate which hue to use based on the combination index
+  // Calculate which hue to use based on the combination index.
   const hueIndex = combinationIndex % idHue.length;
 
   return {

package/src/types.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { isNonNullable } from './types';
+import { arrayMove, arraySwap, isNonNullable } from './types';
 
 describe('types', () => {
   test('filter', async () => {
@@ -12,4 +12,14 @@ describe('types', () => {
     const filtered: number[] = values.filter(isNonNullable);
     expect(filtered).to.deep.equal([1, 2, 3, 4]);
   });
+
+  test('arrayMove', () => {
+    expect(arrayMove([1, 2, 3, 4], 0, 2)).to.deep.equal([2, 3, 1, 4]);
+    expect(arrayMove([1, 2, 3, 4], 2, 0)).to.deep.equal([3, 1, 2, 4]);
+  });
+
+  test('arraySwap', () => {
+    expect(arraySwap([1, 2, 3, 4], 0, 2)).to.deep.equal([3, 2, 1, 4]);
+    expect(arraySwap([1, 2, 3, 4], 2, 0)).to.deep.equal([3, 2, 1, 4]);
+  });
 });

package/src/types.ts

@@ -10,15 +10,33 @@ export type MaybeProvider<T, V = void> = T | ((arg: V) => T);
 
 export type MaybePromise<T> = T | Promise<T>;
 
-export type GuardedType<T> = T extends (value: any) => value is infer R ? R : never;
-
-export type DeepReadonly<T> = {
-  readonly [P in keyof T]: T[P] extends Record<string, any>
-    ? DeepReadonly<T[P]>
-    : T[P] extends Array<infer U>
-      ? ReadonlyArray<DeepReadonly<U>>
-      : T[P];
-};
+export type GuardedType<T> = T extends ((value: any) => value is infer R) ? R : never;
+
+/**
+ * Removes readonly modifiers from top-level properties of T.
+ * Also converts readonly arrays at the top level to mutable arrays.
+ * For nested properties, mutability depends on the schema definition.
+ */
+export type ToMutable<T> = T extends object
+  ? { -readonly [K in keyof T]: T[K] extends readonly (infer U)[] ? U[] : T[K] }
+  : T;
+
+export type Intersection<Types extends readonly unknown[]> = Types extends [infer First, ...infer Rest]
+  ? First & Intersection<Rest>
+  : unknown;
+
+/**
+ * Recursively makes all properties of T readonly.
+ * Primitives (including branded types like `string & { __brand: true }`) are returned as-is.
+ * Arrays become ReadonlyArrays with deeply readonly elements.
+ */
+export type DeepReadonly<T> = T extends string | number | boolean | bigint | symbol | null | undefined
+  ? T // Primitives (including branded primitives) stay as-is.
+  : T extends Array<infer U>
+    ? ReadonlyArray<DeepReadonly<U>>
+    : T extends object
+      ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
+      : T;
 
 export type DeepWriteable<T> = { -readonly [K in keyof T]: T[K] extends object ? DeepWriteable<T[K]> : T[K] };
 
@@ -48,7 +66,7 @@ export type Falsy = false | 0 | '' | null | undefined;
  * NOTE: To filter by type:
  * items.filter((item: any): item is RangeSet<Decoration> => item instanceof RangeSet)
  */
-export const isNotFalsy = <T>(value: T): value is Exclude<T, Falsy> => !!value;
+export const isTruthy = <T>(value: T): value is Exclude<T, Falsy> => !!value;
 export const isNonNullable = <T>(value: T | null | undefined): value is T => value != null;
 
 // TODO(burdon): Replace use of setTimeout everywhere?
@@ -104,9 +122,19 @@ export const sortKeys = <T extends object>(obj: T): T =>
     }, {} as T);
 
 /**
- * Swap position of element within array.
+ * Move element within array.
  */
-export const arrayMove = <T>(array: T[], from: number, to: number): Array<T> => {
+export const arrayMove = <T>(array: T[], from: number, to: number): T[] => {
   array.splice(to < 0 ? array.length + to : to, 0, array.splice(from, 1)[0]);
   return array;
 };
+
+/**
+ * Swap position of element within array.
+ */
+export function arraySwap<T>(array: T[], from: number, to: number): T[] {
+  const current = array[from];
+  array[from] = array[to];
+  array[to] = current;
+  return array;
+}

package/src/unit.test.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from 'vitest';
+
+import { Unit } from './unit';
+
+describe('url', () => {
+  it('duration', ({ expect }) => {
+    const tests: [number, string][] = [
+      [0, '0ms'],
+      [1, '1ms'],
+      [1_000, '1.0s'],
+      [2_887, '2.9s'],
+      [1_000 * 60, '1m'],
+      [1_000 * 60 + 1_000 * 5, '1m 5s'],
+      [1_000 * 60 * 60 + 1_000 * 60 * 5, '1h 5m'],
+    ];
+
+    tests.forEach(([input, output]) => {
+      expect(Unit.Duration(input).toString(), input.toString()).toBe(output);
+    });
+  });
+});