@dxos/util 0.8.4-main.bbf232bc24 → 0.8.4-main.bc2380dfbc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/util",
-  "version": "0.8.4-main.bbf232bc24",
+  "version": "0.8.4-main.bc2380dfbc",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": false,
   "type": "module",
@@ -29,13 +29,13 @@
   ],
   "dependencies": {
     "@hazae41/symbol-dispose-polyfill": "^1.0.2",
-    "@dxos/debug": "0.8.4-main.bbf232bc24",
-    "@dxos/keys": "0.8.4-main.bbf232bc24",
-    "@dxos/invariant": "0.8.4-main.bbf232bc24",
-    "@dxos/node-std": "0.8.4-main.bbf232bc24"
+    "@dxos/debug": "0.8.4-main.bc2380dfbc",
+    "@dxos/keys": "0.8.4-main.bc2380dfbc",
+    "@dxos/invariant": "0.8.4-main.bc2380dfbc",
+    "@dxos/node-std": "0.8.4-main.bc2380dfbc"
   },
   "devDependencies": {
-    "@dxos/crypto": "0.8.4-main.bbf232bc24"
+    "@dxos/crypto": "0.8.4-main.bc2380dfbc"
   },
   "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';