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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.4-main.fdfb99ef29",
+  "version": "0.8.4-staging.60fe92afc8",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,12 +8,13 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": {
@@ -29,13 +30,13 @@
   ],
   "dependencies": {
     "@hazae41/symbol-dispose-polyfill": "^1.0.2",
-    "@dxos/invariant": "0.8.4-main.fdfb99ef29",
-    "@dxos/debug": "0.8.4-main.fdfb99ef29",
-    "@dxos/keys": "0.8.4-main.fdfb99ef29",
-    "@dxos/node-std": "0.8.4-main.fdfb99ef29"
+    "@dxos/debug": "0.8.4-staging.60fe92afc8",
+    "@dxos/invariant": "0.8.4-staging.60fe92afc8",
+    "@dxos/node-std": "0.8.4-staging.60fe92afc8",
+    "@dxos/keys": "0.8.4-staging.60fe92afc8"
   },
   "devDependencies": {
-    "@dxos/crypto": "0.8.4-main.fdfb99ef29"
+    "@dxos/crypto": "0.8.4-staging.60fe92afc8"
   },
   "publishConfig": {
     "access": "public"

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

@@ -24,6 +24,7 @@ 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';

package/src/map-values.ts

@@ -52,6 +52,9 @@ class DeepMapper {
         res[i] = this._map(value[i], i);
       }
       return res;
+    } else if (ArrayBuffer.isView(value)) {
+      // Typed arrays (Uint8Array, etc.) are opaque leaf values, not POJOs to recurse into.
+      return value;
     } else if (value !== null && typeof value === 'object') {
       const res: any = {};
       this._cyclic.set(value, res);
@@ -112,6 +115,9 @@ class DeepMapperAsync {
         res[i] = await this._map(value[i], i);
       }
       return res;
+    } else if (ArrayBuffer.isView(value)) {
+      // Typed arrays (Uint8Array, etc.) are opaque leaf values, not POJOs to recurse into.
+      return value;
     } else if (value !== null && typeof value === 'object') {
       const res: any = {};
       this._cyclic.set(value, res);

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/string.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, test } from 'vitest';
 
-import { trim } from './string';
+import { inline, trim } from './string';
 
 describe('string', () => {
   test('dedent', async ({ expect }) => {
@@ -16,4 +16,27 @@ describe('string', () => {
 
     expect(text).to.eq('- 1\n- 2\n  - 3');
   });
+
+  test('inline collapses whitespace to single spaces', async ({ expect }) => {
+    const classes = inline`
+      rounded-xs outline-none text-end
+      data-[type=year]:min-w-[4ch]
+      data-[focused]:bg-accent-bg  data-[focused]:text-accent-fg
+    `;
+
+    expect(classes).to.eq(
+      'rounded-xs outline-none text-end data-[type=year]:min-w-[4ch] data-[focused]:bg-accent-bg data-[focused]:text-accent-fg',
+    );
+  });
+
+  test('inline interpolates values', async ({ expect }) => {
+    const variant = 'data-[focused]:bg-accent-bg';
+    const classes = inline`
+      rounded-xs
+      ${variant}
+      outline-none
+    `;
+
+    expect(classes).to.eq('rounded-xs data-[focused]:bg-accent-bg outline-none');
+  });
 });

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

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

@@ -53,6 +53,8 @@ export const Unit: Record<string, UnitFormat> = {
   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);
@@ -68,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,