@dxos/util 0.8.4-main.ef1bc66f44 → 0.8.4-main.f466a3d56e

package/src/position.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, expect, it } from 'vitest';
+import { describe, test } from 'vitest';
 
 import { type Position, byPosition } from './position';
 
@@ -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/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));

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 = {

package/src/types.ts

@@ -10,7 +10,7 @@ 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 GuardedType<T> = T extends ((value: any) => value is infer R) ? R : never;
 
 /**
  * Removes readonly modifiers from top-level properties of T.

package/src/unit.ts

@@ -20,11 +20,15 @@ export type UnitFormat<T = any> = (n: number, precision?: number) => UnitValue<T
 const createFormat = (unit: Unit): UnitFormat<string> => {
   return (n: number, precision = unit.precision ?? 0) => {
     const value = n / unit.quotient;
+    const formattedValue = value.toLocaleString('en-US', {
+      minimumFractionDigits: precision,
+      maximumFractionDigits: precision,
+    });
     return {
       unit,
       value,
-      formattedValue: value.toFixed(precision),
-      toString: () => `${value.toFixed(precision)}${unit.symbol}`,
+      formattedValue,
+      toString: () => `${formattedValue}${unit.symbol}`,
     };
   };
 };