@dxos/util 0.8.4-main.2e9d522 → 0.8.4-main.3c1ae3b

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.4-main.2e9d522",
+  "version": "0.8.4-main.3c1ae3b",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": {
         "require": "./dist/lib/node/index.cjs",
         "default": "./dist/lib/node-esm/index.mjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
+      }
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -27,17 +27,18 @@
     "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.2e9d522",
-    "@dxos/invariant": "0.8.4-main.2e9d522",
-    "@dxos/keys": "0.8.4-main.2e9d522",
-    "@dxos/node-std": "0.8.4-main.2e9d522"
+    "@dxos/debug": "0.8.4-main.3c1ae3b",
+    "@dxos/invariant": "0.8.4-main.3c1ae3b",
+    "@dxos/keys": "0.8.4-main.3c1ae3b",
+    "@dxos/node-std": "0.8.4-main.3c1ae3b"
   },
   "devDependencies": {
     "@types/lodash.get": "^4.4.9",
     "@types/lodash.set": "^4.3.9",
-    "@dxos/crypto": "0.8.4-main.2e9d522"
+    "@dxos/crypto": "0.8.4-main.3c1ae3b"
   },
   "publishConfig": {
     "access": "public"

package/src/array.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { diff, intersection, distinctBy, partition } from './array';
+import { diff, distinctBy, intersection, partition } from './array';
 
 describe('diff', () => {
   test('returns the difference between two sets', () => {

package/src/array.ts

@@ -130,3 +130,10 @@ export const intersectBy = <T, K>(arrays: T[][], selector: (item: T) => K): T[]
     return lookups.every((lookup) => lookup.has(key));
   });
 };
+
+export const coerceArray = <T>(arr: T | T[] | undefined): T[] => {
+  if (arr === undefined) {
+    return [];
+  }
+  return Array.isArray(arr) ? arr : [arr];
+};

package/src/binder.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import util from 'node:util';
+import { promisify } from 'node:util';
 
 /**
  * Function binder replaces pify.
@@ -10,5 +10,5 @@ import util from 'node:util';
 // TODO(burdon): Replace pify everywhere.
 export const createBinder = (obj: any) => ({
   fn: (fn: Function) => fn.bind(obj),
-  async: (fn: Function) => util.promisify(fn.bind(obj)),
+  async: (fn: Function) => promisify(fn.bind(obj)),
 });

package/src/circular-buffer.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { describe, test, expect } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
 import { CircularBuffer } from './circular-buffer';
 

package/src/complex.test.ts

@@ -6,7 +6,7 @@ import { expect, test } from 'vitest';
 
 import { PublicKey } from '@dxos/keys';
 
-import { makeSet, makeMap } from './complex';
+import { makeMap, makeSet } from './complex';
 
 const PulicKeySet = makeSet<PublicKey>(PublicKey.hash);
 

package/src/defer.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import './explicit-resource-management-polyfill';
+import '@hazae41/symbol-dispose-polyfill';
 
 /**
  * Run function on scope exit. Go style.

package/src/error-format.ts

@@ -0,0 +1,22 @@
+/**
+ * Formats an error with its cause chain.
+ */
+//
+// Copyright 2025 DXOS.org
+//
+
+export const formatErrorWithCauses = (error: Error): string => {
+  const lines: string[] = [];
+  let current: Error | undefined = error;
+  let level = 0;
+
+  while (current) {
+    const prefix = level === 0 ? '' : `Caused by: `;
+    lines.push(prefix + (current.stack ?? String(current)));
+    if (!(current.cause instanceof Error)) break;
+    current = current.cause;
+    level += 1;
+  }
+
+  return lines.join('\n\n');
+};

package/src/filename.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Creates a unique filename.
+ */
+export const createFilename = ({
+  parts = [],
+  ext,
+  date = new Date(),
+}: {
+  parts?: string[];
+  ext?: string;
+  date?: Date;
+}) => [date.toISOString().replace(/[:.]/g, '-'), ...parts].join('_') + (ext ? `.${ext}` : '');

package/src/human-hash.test.ts

@@ -4,7 +4,7 @@
 
 import { expect, test } from 'vitest';
 
-import { createKeyPair, createId } from '@dxos/crypto';
+import { createId, createKeyPair } from '@dxos/crypto';
 import { PublicKey } from '@dxos/keys';
 
 import { humanize } from './human-hash';

package/src/index.ts

@@ -18,7 +18,7 @@ export * from './deep';
 export * from './defer-function';
 export * from './defer';
 export * from './entry';
-export * from './first-two-chars';
+export * from './filename';
 export * from './for-each-async';
 export * from './human-hash';
 export * from './instance-id';
@@ -41,6 +41,7 @@ export * from './remove-undefined-keys';
 export * from './safe-await';
 export * from './safe-instanceof';
 export * from './safe-parse';
+export * from './safe-stringify';
 export * from './sliding-window-summary';
 export * from './sort';
 export * from './string';
@@ -51,5 +52,7 @@ export * from './tracer';
 export * from './tree';
 export * from './types';
 export * from './uint8array';
+export * from './unit';
 export * from './url';
 export * from './weak';
+export * from './error-format';

package/src/position.test.ts

@@ -2,9 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, it, expect } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
-import { byPosition, type Position } from './position';
+import { type Position, byPosition } from './position';
 
 type TestItem = {
   id: number;

package/src/safe-parse.ts

@@ -2,33 +2,37 @@
 // 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) {
-      // no-op.
-    }
+      return JSON.parse(str);
+    } catch {}
   }
+
   return defaultValue;
 };

package/src/safe-stringify.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export const SKIP = Object.freeze({});
+
+export type StringifyReplacer = (key: string, value: any) => typeof SKIP | any;
+
+export function safeStringify(obj: any, filter: StringifyReplacer = defaultFilter, indent = 2) {
+  const seen = new WeakSet();
+
+  function replacer(key: string, value: any) {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) {
+        return '[Circular]';
+      }
+
+      seen.add(value);
+    }
+
+    if (filter) {
+      const v2 = filter?.(key, value);
+      if (v2 !== undefined) {
+        return v2 === SKIP ? undefined : v2;
+      }
+    }
+
+    return value;
+  }
+
+  let result = '';
+  try {
+    result = JSON.stringify(obj, replacer, indent);
+  } catch (error: any) {
+    result = `Error: ${error.message}`;
+  }
+
+  return result;
+}
+
+export type CreateReplacerProps = {
+  omit?: string[];
+  parse?: string[];
+  maxDepth?: number;
+  maxArrayLen?: number;
+  maxStringLen?: number;
+};
+
+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 === '') {
+      currentDepth = 0;
+    } else if (this && typeof this === 'object') {
+      const parentDepth = depthMap.get(this) ?? 0;
+      currentDepth = parentDepth + 1;
+    }
+
+    if (typeof value === 'function') {
+      return undefined;
+    }
+
+    // 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 undefined;
+    }
+    if (parse?.includes(key) && typeof value === 'string') {
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    }
+    if (maxArrayLen != null && Array.isArray(value) && value.length > maxArrayLen) {
+      return `[length: ${value.length}]`;
+    }
+    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

@@ -14,6 +14,6 @@ describe('string', () => {
         - 3
     `;
 
-    expect(text).to.eq('- 1\n- 2\n  - 3\n');
+    expect(text).to.eq('- 1\n- 2\n  - 3');
   });
 });

package/src/string.ts

@@ -16,9 +16,35 @@ export const capitalize = (str: string): string => {
 /**
  * Remove leading space from multi-line strings.
  */
-export const trim = (strings: TemplateStringsArray, ...values: any[]) => {
-  const full = String.raw(strings, ...values);
-  const lines = full.replace(/^\n/, '').split('\n');
-  const indent = Math.min(...lines.filter((l) => l.trim()).map((l) => l.match(/^ */)![0].length));
-  return lines.map((l) => l.slice(indent)).join('\n');
-};
+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

@@ -194,17 +194,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.ts

@@ -12,6 +12,14 @@ export type MaybePromise<T> = T | Promise<T>;
 
 export type GuardedType<T> = T extends (value: any) => value is infer R ? R : never;
 
+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;
+
 export type DeepReadonly<T> = {
   readonly [P in keyof T]: T[P] extends Record<string, any>
     ? DeepReadonly<T[P]>
@@ -48,7 +56,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?

package/src/uint8array.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { test, expect, describe } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
 import { arrayToBuffer, arrayToString, bufferToArray, stringToArray } from './uint8array';
 

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

package/src/unit.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export type Unit = {
+  symbol: string;
+  quotient: number;
+  precision?: number;
+};
+
+export type UnitValue<T> = {
+  unit: Unit;
+  value: number;
+  formattedValue: T;
+  toString: () => string;
+};
+
+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;
+    return {
+      unit,
+      value,
+      formattedValue: value.toFixed(precision),
+      toString: () => `${value.toFixed(precision)}${unit.symbol}`,
+    };
+  };
+};
+
+const MS_SECONDS = 1_000;
+const MS_MINUTES = 60 * MS_SECONDS;
+const MS_HOURS = 60 * MS_MINUTES;
+
+export const Unit: Record<string, UnitFormat> = {
+  // General.
+  Percent: createFormat({ symbol: '%', quotient: 1 / 100, precision: 2 }),
+  Thousand: createFormat({ symbol: 'k', quotient: 1_000, precision: 2 }),
+
+  // Bytes (note KB vs KiB).
+  Gigabyte: createFormat({ symbol: 'GB', quotient: 1_000 * 1_000 * 1_000, precision: 2 }),
+  Megabyte: createFormat({ symbol: 'MB', quotient: 1_000 * 1_000, precision: 2 }),
+  Kilobyte: createFormat({ symbol: 'KB', quotient: 1_000, precision: 2 }),
+  Byte: createFormat({ symbol: 'B', quotient: 1 }),
+
+  // Time.
+  Hour: createFormat({ symbol: 'h', quotient: MS_HOURS }),
+  Minute: createFormat({ symbol: 'm', quotient: MS_MINUTES }),
+  Second: createFormat({ symbol: 's', quotient: MS_SECONDS, precision: 1 }),
+  Millisecond: createFormat({ symbol: 'ms', quotient: 1 }),
+  Duration: (n: number) => {
+    const hours = Math.floor(n / MS_HOURS);
+    const minutes = Math.floor((n % MS_HOURS) / MS_MINUTES);
+    if (hours) {
+      const formattedValue = minutes ? `${hours}h ${minutes}m` : `${hours}h`;
+      return {
+        unit: { symbol: 'h', quotient: MS_HOURS },
+        value: hours,
+        formattedValue,
+        toString: () => formattedValue,
+      };
+    }
+
+    if (minutes) {
+      const seconds = (n - MS_MINUTES * minutes) / MS_SECONDS;
+      const formattedValue = seconds ? `${minutes}m ${seconds}s` : `${minutes}m`;
+      return {
+        unit: { symbol: 'm', quotient: MS_MINUTES },
+        value: minutes,
+        formattedValue,
+        toString: () => formattedValue,
+      };
+    }
+
+    const seconds = n >= MS_SECONDS;
+    if (seconds) {
+      return Unit.Second(n);
+    }
+
+    return Unit.Millisecond(n);
+  },
+} as const;

package/src/weak.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { test, expect, describe } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
 import { WeakDictionary } from './weak';
 

package/dist/types/src/explicit-resource-management-polyfill.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=explicit-resource-management-polyfill.d.ts.map

package/dist/types/src/explicit-resource-management-polyfill.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"explicit-resource-management-polyfill.d.ts","sourceRoot":"","sources":["../../../src/explicit-resource-management-polyfill.ts"],"names":[],"mappings":""}

package/dist/types/src/first-two-chars.d.ts

@@ -1,9 +0,0 @@
-/**
- * Returns the first two renderable characters from a string that are separated by non-word characters.
- * Handles Unicode characters correctly.
- *
- * @param {string} label - The input string to process
- * @returns {[string, string]} Array containing the two characters, or empty strings if not found
- */
-export declare const getFirstTwoRenderableChars: (label: string) => string[];
-//# sourceMappingURL=first-two-chars.d.ts.map

package/dist/types/src/first-two-chars.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"first-two-chars.d.ts","sourceRoot":"","sources":["../../../src/first-two-chars.ts"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,MAAM,aA2BvD,CAAC"}

package/src/explicit-resource-management-polyfill.ts

@@ -1,13 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-// https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
-
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-// @ts-ignore
-Symbol.dispose ??= Symbol('Symbol.dispose');
-
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-// @ts-ignore
-Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');