@dxos/util 0.8.4-main.c85a9c8dae → 0.8.4-main.cb12b3f963

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.4-main.c85a9c8dae",
+  "version": "0.8.4-main.cb12b3f963",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -23,22 +23,19 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
     "@hazae41/symbol-dispose-polyfill": "^1.0.2",
-    "@dxos/debug": "0.8.4-main.c85a9c8dae",
-    "@dxos/invariant": "0.8.4-main.c85a9c8dae",
-    "@dxos/node-std": "0.8.4-main.c85a9c8dae",
-    "@dxos/keys": "0.8.4-main.c85a9c8dae"
+    "@dxos/debug": "0.8.4-main.cb12b3f963",
+    "@dxos/invariant": "0.8.4-main.cb12b3f963",
+    "@dxos/keys": "0.8.4-main.cb12b3f963",
+    "@dxos/node-std": "0.8.4-main.cb12b3f963"
   },
   "devDependencies": {
-    "@dxos/crypto": "0.8.4-main.c85a9c8dae"
+    "@dxos/crypto": "0.8.4-main.cb12b3f963"
   },
   "publishConfig": {
     "access": "public"

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/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/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

@@ -13,7 +13,9 @@ export const formatErrorWithCauses = (error: Error): string => {
   while (current) {
     const prefix = level === 0 ? '' : `Caused by: `;
     lines.push(prefix + (current.stack ?? String(current)));
-    if (!(current.cause instanceof Error)) break;
+    if (!(current.cause instanceof Error)) {
+      break;
+    }
     current = current.cause;
     level += 1;
   }

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,10 +15,12 @@ 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';
@@ -38,6 +41,7 @@ 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';
@@ -55,5 +59,3 @@ export * from './uint8array';
 export * from './unit';
 export * from './url';
 export * from './weak';
-export * from './error-format';
-export * from './retry';

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/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}`,
     };
   };
 };

package/src/weak.ts

@@ -7,13 +7,20 @@
  */
 export class WeakDictionary<K, V extends object> implements Map<K, V> {
   private readonly _internal = new Map<K, WeakRef<V>>();
-  private readonly _finalization = new FinalizationRegistry((cleanUpCallback: () => void) => {
-    cleanUpCallback();
+  private readonly _finalization = new FinalizationRegistry<{ key: K; ref: WeakRef<V> }>(({ key, ref }) => {
+    if (this._internal.get(key) === ref) {
+      this._internal.delete(key);
+    }
   });
 
   constructor(entries?: [K, V][]) {
-    this._internal = new Map(entries?.map(([key, value]) => [key, new WeakRef(value)]));
-    entries?.forEach(([key, value]) => this._register(key, value));
+    if (entries) {
+      for (const [key, value] of entries) {
+        const ref = new WeakRef(value);
+        this._internal.set(key, ref);
+        this._register(key, value, ref);
+      }
+    }
   }
 
   *entries(): SetIterator<[K, V]> {
@@ -55,11 +62,48 @@ export class WeakDictionary<K, V extends object> implements Map<K, V> {
   }
 
   set(key: K, value: V): this {
-    this._internal.set(key, new WeakRef(value));
-    this._register(key, value);
+    const previous = this._internal.get(key)?.deref();
+    if (previous) {
+      this._unregister(previous);
+    }
+    const ref = new WeakRef(value);
+    this._internal.set(key, ref);
+    this._register(key, value, ref);
     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 existing = this.get(key);
+    if (existing !== undefined) {
+      return existing;
+    }
+    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 existing = this.get(key);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const value = callbackfn(key);
+    this.set(key, value);
+    return value;
+  }
+
   has(key: K): boolean {
     return this._internal.has(key) && this._internal.get(key)!.deref() !== undefined;
   }
@@ -96,14 +140,8 @@ export class WeakDictionary<K, V extends object> implements Map<K, V> {
     });
   }
 
-  private _register(key: K, value: V): void {
-    this._finalization.register(
-      value,
-      () => {
-        this._internal.delete(key);
-      },
-      value,
-    );
+  private _register(key: K, value: V, ref: WeakRef<V>): void {
+    this._finalization.register(value, { key, ref }, value);
   }
 
   private _unregister(value: V): void {