@dxos/util 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

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');
+  });
+});

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

package/src/string.ts

@@ -12,3 +12,39 @@ export const capitalize = (str: string): string => {
 
   return str.charAt(0).toUpperCase() + str.slice(1);
 };
+
+/**
+ * Remove leading space from multi-line strings.
+ */
+export function trim(strings: TemplateStringsArray, ...values: any[]) {
+  // First, build the raw result with relative indentation.
+  const raw = strings.reduce((out, str, i) => {
+    out += str;
+    if (i < values.length) {
+      const match = str.match(/(^|\n)([ \t]*)$/);
+      const baseIndent = match ? match[2] : '';
+      const val = String(values[i]).replace(/\r?\n/g, '\n' + baseIndent);
+      out += val;
+    }
+    return out;
+  }, '');
+
+  // 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();
+
+  // 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));
+
+  // 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/tree.test.ts

@@ -6,7 +6,7 @@ import { describe, test } from 'vitest';
 
 import { PublicKey } from '@dxos/keys';
 
-import { stringifyTree, type TreeNode } from './tree';
+import { type TreeNode, stringifyTree } from './tree';
 
 describe('Tree logging', () => {
   test('simple', () => {

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]);
+  });
 });