@dxos/util 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/string.ts

@@ -13,6 +13,22 @@ export const capitalize = (str: string): string => {
   return str.charAt(0).toUpperCase() + str.slice(1);
 };
 
+/**
+ * Collapse a multi-line tagged template literal to a single space-separated string.
+ * Useful for statically concatenating long lists of class names across multiple lines:
+ *
+ * ```ts
+ * const cls = inline`
+ *   rounded-xs outline-none
+ *   data-[focused]:bg-accent-bg
+ * `;
+ * ```
+ */
+export function inline(strings: TemplateStringsArray, ...values: any[]): string {
+  const raw = strings.reduce((out, str, i) => out + str + (i < values.length ? String(values[i]) : ''), '');
+  return raw.replace(/\s+/g, ' ').trim();
+}
+
 /**
  * Remove leading space from multi-line strings.
  */
@@ -32,8 +48,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.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]);
+  });
 });

package/src/types.ts

@@ -10,15 +10,33 @@ 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 DeepReadonly<T> = {
-  readonly [P in keyof T]: T[P] extends Record<string, any>
-    ? DeepReadonly<T[P]>
-    : T[P] extends Array<infer U>
-      ? ReadonlyArray<DeepReadonly<U>>
-      : T[P];
-};
+export type GuardedType<T> = T extends ((value: any) => value is infer R) ? R : never;
+
+/**
+ * Removes readonly modifiers from top-level properties of T.
+ * Also converts readonly arrays at the top level to mutable arrays.
+ * For nested properties, mutability depends on the schema definition.
+ */
+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;
+
+/**
+ * Recursively makes all properties of T readonly.
+ * Primitives (including branded types like `string & { __brand: true }`) are returned as-is.
+ * Arrays become ReadonlyArrays with deeply readonly elements.
+ */
+export type DeepReadonly<T> = T extends string | number | boolean | bigint | symbol | null | undefined
+  ? T // Primitives (including branded primitives) stay as-is.
+  : T extends Array<infer U>
+    ? ReadonlyArray<DeepReadonly<U>>
+    : T extends object
+      ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
+      : T;
 
 export type DeepWriteable<T> = { -readonly [K in keyof T]: T[K] extends object ? DeepWriteable<T[K]> : T[K] };
 
@@ -104,9 +122,19 @@ export const sortKeys = <T extends object>(obj: T): T =>
     }, {} as T);
 
 /**
- * Swap position of element within array.
+ * Move element within array.
  */
-export const arrayMove = <T>(array: T[], from: number, to: number): Array<T> => {
+export const arrayMove = <T>(array: T[], from: number, to: number): T[] => {
   array.splice(to < 0 ? array.length + to : to, 0, array.splice(from, 1)[0]);
   return array;
 };
+
+/**
+ * Swap position of element within array.
+ */
+export function arraySwap<T>(array: T[], from: number, to: number): T[] {
+  const current = array[from];
+  array[from] = array[to];
+  array[to] = current;
+  return array;
+}

package/src/uint8array.ts

@@ -35,3 +35,47 @@ export const bufferToArray = (buffer: Buffer): Uint8Array => {
 export const stringToArray = (string: string): Uint8Array => bufferToArray(Buffer.from(string, 'hex'));
 
 export const arrayToString = (array: Uint8Array): string => arrayToBuffer(array).toString('hex');
+
+/**
+ * JSON-safe representation of a `Uint8Array`, per the IPLD DAG-JSON spec.
+ * https://ipld.io/specs/codecs/dag-json/spec/#bytes
+ *
+ * Bytes are encoded as `{ "/": { "bytes": "<base64-no-padding>" } }`.
+ * Distinguishable from encoded references `{ "/": "<string>" }` by the type of the `/` value.
+ */
+export type EncodedUint8Array = { '/': { bytes: string } };
+
+const toUnpaddedBase64 = (bytes: Uint8Array): string => arrayToBuffer(bytes).toString('base64').replace(/=+$/, '');
+
+/**
+ * Encode a `Uint8Array` as the DAG-JSON bytes form `{ '/': { bytes: '<base64-no-padding>' } }`.
+ */
+export const encodeUint8ArrayToJson = (bytes: Uint8Array): EncodedUint8Array => ({
+  '/': { bytes: toUnpaddedBase64(bytes) },
+});
+
+/**
+ * Type-guard that returns true iff `value` is the DAG-JSON bytes form produced by
+ * {@link encodeUint8ArrayToJson} — an object with exactly one key `'/'` whose value is an
+ * object with exactly one string key `bytes`.
+ */
+export const isEncodedUint8Array = (value: unknown): value is EncodedUint8Array => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  if (Object.keys(value).length !== 1) {
+    return false;
+  }
+  const inner = (value as any)['/'];
+  if (typeof inner !== 'object' || inner === null || Array.isArray(inner)) {
+    return false;
+  }
+  return Object.keys(inner).length === 1 && typeof inner.bytes === 'string';
+};
+
+/**
+ * Decode a DAG-JSON bytes form (as produced by {@link encodeUint8ArrayToJson}) back to a
+ * `Uint8Array`. The base64 string is tolerated with or without padding.
+ */
+export const decodeUint8ArrayFromJson = (encoded: EncodedUint8Array): Uint8Array =>
+  bufferToArray(Buffer.from(encoded['/'].bytes, 'base64'));

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}`,
     };
   };
 };
@@ -42,12 +46,15 @@ export const Unit: Record<string, UnitFormat> = {
   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 }),
+
+  // TODO(burdon): Inconsistent formattedValue.
   Duration: (n: number) => {
     const hours = Math.floor(n / MS_HOURS);
     const minutes = Math.floor((n % MS_HOURS) / MS_MINUTES);
@@ -63,7 +70,7 @@ export const Unit: Record<string, UnitFormat> = {
 
     if (minutes) {
       const seconds = (n - MS_MINUTES * minutes) / MS_SECONDS;
-      const formattedValue = seconds ? `${minutes}m ${seconds}s` : `${minutes}m`;
+      const formattedValue = seconds ? `${minutes}m ${Math.round(seconds)}s` : `${minutes}m`;
       return {
         unit: { symbol: 'm', quotient: MS_MINUTES },
         value: minutes,

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 {

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