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

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.4-main.ead640a",
+  "version": "0.8.4-main.f466a3d56e",
   "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -19,25 +23,19 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "lodash.get": "^4.4.2",
-    "lodash.set": "^4.3.2",
-    "@dxos/debug": "0.8.4-main.ead640a",
-    "@dxos/keys": "0.8.4-main.ead640a",
-    "@dxos/invariant": "0.8.4-main.ead640a",
-    "@dxos/node-std": "0.8.4-main.ead640a"
+    "@hazae41/symbol-dispose-polyfill": "^1.0.2",
+    "@dxos/debug": "0.8.4-main.f466a3d56e",
+    "@dxos/node-std": "0.8.4-main.f466a3d56e",
+    "@dxos/keys": "0.8.4-main.f466a3d56e",
+    "@dxos/invariant": "0.8.4-main.f466a3d56e"
   },
   "devDependencies": {
-    "@types/lodash.get": "^4.4.9",
-    "@types/lodash.set": "^4.3.9",
-    "@dxos/crypto": "0.8.4-main.ead640a"
+    "@dxos/crypto": "0.8.4-main.f466a3d56e"
   },
   "publishConfig": {
     "access": "public"

package/src/array.ts

@@ -42,14 +42,14 @@ export const diff = <A, B = A>(
   return result;
 };
 
-export const intersection = <A, B = A>(a: A[], b: B[], comparator: Comparator<A, B>): A[] =>
+export const intersection = <A, B = A>(a: readonly A[], b: readonly B[], comparator: Comparator<A, B>): A[] =>
   a.filter((a) => b.find((b) => comparator(a, b)) !== undefined);
 
 /**
  * Returns a new array with only the first instance of each unique item
  * based on a specified property.
  *
- * @typeParam T - The type of items in the input array.
+ * @typeProp T - The type of items in the input array.
  * @param array - The array to filter for distinct items.
  * @param key - The property key to determine uniqueness for each item.
  * @returns A new array with only distinct items based on the specified property.
@@ -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/browser-storage.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/** Delete all IndexedDB databases for this origin. */
+export const clearIndexedDB = async (): Promise<void> => {
+  const dbs = await indexedDB.databases();
+  const results = await Promise.allSettled(
+    dbs
+      .filter((db) => db.name != null)
+      .map(
+        (db) =>
+          new Promise<void>((resolve, reject) => {
+            const request = indexedDB.deleteDatabase(db.name!);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+            request.onblocked = () => reject(new Error(`IndexedDB deletion blocked: ${db.name}`));
+          }),
+      ),
+  );
+  const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');
+  if (failures.length > 0) {
+    throw new AggregateError(
+      failures.map((r) => r.reason),
+      'Failed to delete some IndexedDB databases',
+    );
+  }
+};
+
+/** Remove all entries from the Origin Private File System. */
+export const clearOPFS = async (): Promise<void> => {
+  const root = await navigator.storage.getDirectory();
+  const errors: unknown[] = [];
+  for await (const [name] of root.entries()) {
+    try {
+      await root.removeEntry(name, { recursive: true });
+    } catch (err) {
+      errors.push(err);
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, 'Failed to remove some OPFS entries');
+  }
+};
+
+/** Unregister all service workers for this origin. */
+export const clearServiceWorkers = async (): Promise<void> => {
+  const regs = await navigator.serviceWorker.getRegistrations();
+  for (const reg of regs) {
+    await reg.unregister();
+  }
+};
+
+/** Delete all HTTP caches for this origin. */
+export const clearCaches = async (): Promise<void> => {
+  const keys = await caches.keys();
+  for (const key of keys) {
+    await caches.delete(key);
+  }
+};

package/src/circular-buffer.test.ts

@@ -16,6 +16,32 @@ describe('CircularBuffer', () => {
     }
   });
 
+  test('clear resets buffer', () => {
+    const buffer = new CircularBuffer<number>(5);
+    buffer.push(1);
+    buffer.push(2);
+    buffer.push(3);
+    expect(buffer.elementCount).toBe(3);
+
+    buffer.clear();
+    expect(buffer.elementCount).toBe(0);
+    expect([...buffer]).toStrictEqual([]);
+    expect(buffer.getLast()).toBeUndefined();
+  });
+
+  test('clear allows reuse', () => {
+    const buffer = new CircularBuffer<number>(3);
+    buffer.push(10);
+    buffer.push(20);
+    buffer.clear();
+
+    buffer.push(30);
+    buffer.push(40);
+    expect(buffer.elementCount).toBe(2);
+    expect([...buffer]).toStrictEqual([30, 40]);
+    expect(buffer.getLast()).toBe(40);
+  });
+
   test('full cycle', () => {
     const maxSize = 10;
     const regularArray: number[] = [];

package/src/circular-buffer.ts

@@ -26,6 +26,11 @@ export class CircularBuffer<T> {
     return this._elementCount;
   }
 
+  public clear(): void {
+    this._nextIndex = 0;
+    this._elementCount = 0;
+  }
+
   public getLast(): T | undefined {
     if (this._elementCount === 0) {
       return undefined;

package/src/complex.ts

@@ -214,6 +214,38 @@ export class ComplexMap<K, V> implements Map<K, V> {
     return this;
   }
 
+  /**
+   * Returns the value for the given key if present, otherwise inserts and returns the default value.
+   * @param key - The key to look up or insert.
+   * @param defaultValue - The value to insert if the key is not present.
+   * @returns The existing or newly inserted value.
+   */
+  getOrInsert(key: K, defaultValue: V): V {
+    const primitive = this._keyProjection(key);
+    if (this._values.has(primitive)) {
+      return this._values.get(primitive)!;
+    }
+    this.set(key, defaultValue);
+    return defaultValue;
+  }
+
+  /**
+   * Returns the value for the given key if present, otherwise computes, inserts, and returns a new value.
+   * The callback is only invoked when the key is missing.
+   * @param key - The key to look up or insert.
+   * @param callbackfn - Function to compute the value if the key is not present.
+   * @returns The existing or newly computed value.
+   */
+  getOrInsertComputed(key: K, callbackfn: (key: K) => V): V {
+    const primitive = this._keyProjection(key);
+    if (this._values.has(primitive)) {
+      return this._values.get(primitive)!;
+    }
+    const value = callbackfn(key);
+    this.set(key, value);
+    return value;
+  }
+
   get size(): number {
     return this._keys.size;
   }

package/src/composite-key.test.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { compositeKey, splitCompositeKey } from './composite-key';
+
+describe('compositeKey', () => {
+  test('joins parts with colon', ({ expect }) => {
+    expect(compositeKey('a', 'b', 'c')).to.eq('a:b:c');
+  });
+
+  test('single part returns as-is', ({ expect }) => {
+    expect(compositeKey('only')).to.eq('only');
+  });
+
+  test('handles empty strings in parts', ({ expect }) => {
+    expect(compositeKey('', 'b')).to.eq(':b');
+  });
+});
+
+describe('splitCompositeKey', () => {
+  test('splits on colon', ({ expect }) => {
+    expect(splitCompositeKey('a:b:c')).to.deep.eq(['a', 'b', 'c']);
+  });
+
+  test('single part returns array of one', ({ expect }) => {
+    expect(splitCompositeKey('only')).to.deep.eq(['only']);
+  });
+});

package/src/composite-key.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+const SEPARATOR = ':';
+
+/**
+ * Build a composite key from string parts joined by a colon separator.
+ * Parts must not contain the separator character.
+ */
+export const compositeKey = (...parts: string[]): string => parts.join(SEPARATOR);
+
+/**
+ * Split a composite key back into its parts.
+ */
+export const splitCompositeKey = (key: string): string[] => key.split(SEPARATOR);

package/src/deep.ts

@@ -2,14 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-import get from 'lodash.get';
-import set from 'lodash.set';
-
 import { invariant } from '@dxos/invariant';
 
-// TODO(burdon): Re-export most common utils? (isEqual, defaultsDeep, merge, omit, pick, etc.)
-export { get, set };
-
 /**
  * Initialize a deeply nested object.
  * @returns The value of the prop after assignment.
@@ -19,6 +13,8 @@ export const setDeep = <T>(obj: any, path: readonly (string | number)[], value:
   let parent = obj;
   for (const key of path.slice(0, -1)) {
     if (parent[key] === undefined) {
+      // TODO(wittjosiah): This logic is flawed. This shouldn't be used for initializing arrays.
+      //   Prefer `Obj.setValue` for ECHO objects.
       const isArrayIndex = !isNaN(Number(key));
       parent[key] = isArrayIndex ? [] : {};
     }

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/di-key.ts

@@ -47,7 +47,7 @@ export type DiKey<T> =
     }
   | SymbolDiKey<T>;
 
-export const DiKey = new (class DiKeyConstructor {
+class DiKeyConstructor {
   /**
    * Needed to ensure referential equality of combined keys.
    *
@@ -57,7 +57,7 @@ export const DiKey = new (class DiKeyConstructor {
    */
   // TODO(dmaretskyi): Disable private members lowering for dev env.
   // TODO(dmaretskyi): Could be a weak map after a NodeJS upgrade.
-  #combinedRegistry = new WeakMap();
+  private _combinedRegistry = new WeakMap();
 
   define<T>(name: string): DiKey<T> {
     return new SymbolDiKey(name);
@@ -88,24 +88,26 @@ export const DiKey = new (class DiKeyConstructor {
    * Maintains referential equality: `DiKey.combine(A, B) === DiKey.combine(A, B)`
    */
   combine(...ids: DiKey<any>[]) {
-    const map = this.#lookupCombined(this.#combinedRegistry, ids);
-    return defaultMap(this.#combinedRegistry, map, () => this.#combinedDescription(ids));
+    const map = this._lookupCombined(this._combinedRegistry, ids);
+    return defaultMap(this._combinedRegistry, map, () => this._combinedDescription(ids));
   }
 
   getSingletonFactory<T>(id: DiKey<T>): SingletonFactory<T> | undefined {
     return (id as any)[symbolSingleton];
   }
 
-  #lookupCombined(map: WeakMap<any, any>, [first, ...rest]: DiKey<any>[]): WeakMap<any, any> {
+  private _lookupCombined(map: WeakMap<any, any>, [first, ...rest]: DiKey<any>[]): WeakMap<any, any> {
     const value = defaultMap(map, first, () => new Map());
     if (rest.length > 0) {
-      return this.#lookupCombined(value, rest);
+      return this._lookupCombined(value, rest);
     } else {
       return value;
     }
   }
 
-  #combinedDescription([first, ...rest]: DiKey<any>[]) {
+  private _combinedDescription([first, ...rest]: DiKey<any>[]) {
     return `${this.stringify(first)}<${rest.map(this.stringify).join(', ')}>`;
   }
-})();
+}
+
+export const DiKey = new DiKeyConstructor();

package/src/error-format.ts

@@ -0,0 +1,24 @@
+/**
+ * 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/id.test.ts

@@ -0,0 +1,109 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { id, isWellFormedId, isWellFormedIdPart } from './id';
+
+describe('id', () => {
+  test('accepts a three-part id', ({ expect }) => {
+    expect(id`com.example.foo`).toBe('com.example.foo');
+  });
+
+  test('accepts a four-part id', ({ expect }) => {
+    expect(id`org.dxos.plugin.deck`).toBe('org.dxos.plugin.deck');
+  });
+
+  test('accepts hyphens in authority segments', ({ expect }) => {
+    expect(id`my-org.example.foo`).toBe('my-org.example.foo');
+  });
+
+  test('accepts mixed-case name segment', ({ expect }) => {
+    expect(id`org.dxos.plugin.deckPlugin`).toBe('org.dxos.plugin.deckPlugin');
+  });
+
+  test('accepts alphanumeric characters in authority segments', ({ expect }) => {
+    expect(id`foo123.bar456.qux`).toBe('foo123.bar456.qux');
+  });
+
+  test('interpolates values', ({ expect }) => {
+    const namespace = 'org.dxos';
+    const name = 'plugin';
+    expect(id`${namespace}.${name}.deck`).toBe('org.dxos.plugin.deck');
+  });
+
+  test('throws on empty string', ({ expect }) => {
+    expect(() => id``).toThrow(/Invalid id/);
+  });
+
+  test('throws for fewer than three parts', ({ expect }) => {
+    expect(() => id`foo`).toThrow(/Invalid id/);
+    expect(() => id`foo.bar`).toThrow(/Invalid id/);
+  });
+
+  test('throws when first character is a digit', ({ expect }) => {
+    expect(() => id`1foo.bar.baz`).toThrow(/Invalid id/);
+  });
+
+  test('throws on leading or trailing dot', ({ expect }) => {
+    expect(() => id`.foo.bar.baz`).toThrow(/Invalid id/);
+    expect(() => id`foo.bar.baz.`).toThrow(/Invalid id/);
+  });
+
+  test('throws on consecutive dots', ({ expect }) => {
+    expect(() => id`foo..bar`).toThrow(/Invalid id/);
+  });
+
+  test('throws on hyphens in the name segment', ({ expect }) => {
+    expect(() => id`org.example.foo-bar`).toThrow(/Invalid id/);
+  });
+
+  test('throws on disallowed characters', ({ expect }) => {
+    expect(() => id`foo_bar.baz.qux`).toThrow(/Invalid id/);
+    expect(() => id`foo bar.baz.qux`).toThrow(/Invalid id/);
+  });
+
+  test('throws when an interpolated value produces an invalid name segment', ({ expect }) => {
+    const bad = '1bad';
+    expect(() => id`org.dxos.${bad}`).toThrow(/Invalid id/);
+  });
+});
+
+describe('isWellFormedId', () => {
+  test('matches valid ids', ({ expect }) => {
+    expect(isWellFormedId('com.example.foo')).toBe(true);
+    expect(isWellFormedId('org.dxos.plugin.deck')).toBe(true);
+    expect(isWellFormedId('a1.b2.c3')).toBe(true);
+    expect(isWellFormedId('my-org.example.foo')).toBe(true);
+  });
+
+  test('rejects ids with fewer than three parts', ({ expect }) => {
+    expect(isWellFormedId('foo')).toBe(false);
+    expect(isWellFormedId('foo.bar')).toBe(false);
+  });
+
+  test('rejects invalid ids', ({ expect }) => {
+    expect(isWellFormedId('')).toBe(false);
+    expect(isWellFormedId('1foo.bar.baz')).toBe(false);
+    expect(isWellFormedId('foo.bar.')).toBe(false);
+    expect(isWellFormedId('.foo.bar')).toBe(false);
+    expect(isWellFormedId('foo..bar.baz')).toBe(false);
+    expect(isWellFormedId('org.example.foo-bar')).toBe(false);
+  });
+});
+
+describe('isWellFormedIdPart', () => {
+  test('matches valid name segments', ({ expect }) => {
+    expect(isWellFormedIdPart('foo')).toBe(true);
+    expect(isWellFormedIdPart('Foo')).toBe(true);
+    expect(isWellFormedIdPart('fooBar123')).toBe(true);
+  });
+
+  test('rejects invalid name segments', ({ expect }) => {
+    expect(isWellFormedIdPart('foo.bar')).toBe(false);
+    expect(isWellFormedIdPart('foo-bar')).toBe(false);
+    expect(isWellFormedIdPart('1foo')).toBe(false);
+    expect(isWellFormedIdPart('')).toBe(false);
+  });
+});

package/src/id.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Name segment: starts with alpha, alphanumeric only (no hyphens), max 63 chars.
+const PART = /^[a-zA-Z][a-zA-Z0-9]{0,62}$/;
+
+// Reference: https://atproto.com/specs/nsid
+const ID =
+  /^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)$/;
+
+/**
+ * Branded string type for well-formed ids.
+ */
+export type Id = string & { readonly __id: unique symbol };
+
+/**
+ * Tagged template literal that constructs a well-formed, dot-delimited id string.
+ * Throws if the resulting string is not well-formed.
+ *
+ * Follows the AT Protocol NSID convention (https://atproto.com/specs/nsid)
+ * Full NSID: authority segments (hyphens allowed) + dot + name segment (no hyphens).
+ * - Authority segments: at most 253 characters (including periods), and must contain at least two segments.
+ * - Name segment: starts with alpha, alphanumeric only (no hyphens), max 63 chars.
+ *
+ * @example
+ *   id`org.dxos.plugin.deck` // 'org.dxos.plugin.deck'
+ *   id`${ns}.${plugin}.deck` // joins interpolated values
+ */
+export function id(strings: TemplateStringsArray, ...values: unknown[]): Id {
+  const raw = strings.reduce((out, str, i) => out + str + (i < values.length ? String(values[i]) : ''), '');
+  if (!ID.test(raw)) {
+    throw new Error(`Invalid id (expected AT Protocol NSID): ${JSON.stringify(raw)}`);
+  }
+
+  return raw as Id;
+}
+
+/**
+ * Returns true if the given string is a well-formed NSID.
+ */
+export const isWellFormedId = (value: string): boolean => ID.test(value);
+
+/**
+ * Returns true if the given string is a well-formed NSID name segment:
+ * `/^[a-zA-Z][a-zA-Z0-9]{0,62}$/` (starts with alpha, alphanumeric only, no dots or hyphens).
+ */
+export const isWellFormedIdPart = (value: string): boolean => PART.test(value);

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,12 +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 './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';
@@ -37,9 +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 './safe-stringify';
 export * from './sliding-window-summary';
 export * from './sort';
 export * from './string';