@dxos/keys 0.9.0 → 0.9.1-staging.ee54ba693a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/keys",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -27,17 +27,17 @@
   ],
   "dependencies": {
     "ulidx": "^2.3.0",
-    "@dxos/debug": "0.9.0",
-    "@dxos/node-std": "0.9.0",
-    "@dxos/invariant": "0.9.0"
+    "@dxos/debug": "0.9.1-staging.ee54ba693a",
+    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
+    "@dxos/node-std": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
     "base32-decode": "^1.0.0",
     "base32-encode": "^2.0.0",
-    "effect": "3.21.3"
+    "effect": "3.21.4"
   },
   "peerDependencies": {
-    "effect": "3.21.3"
+    "effect": "3.21.4"
   },
   "publishConfig": {
     "access": "public"

package/src/DXN.test.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
 import * as DXN from './DXN';
@@ -23,6 +24,40 @@ describe('DXN.isDXN', () => {
   });
 });
 
+describe('DXN.Name', () => {
+  test('accepts valid NSIDs — no type errors', () => {
+    // Three-segment minimum (first + middle + final), all camelCase.
+    DXN.make('a.b.c');
+    // Multi-segment, all camelCase.
+    DXN.make('org.dxos.type.calendar');
+    // Hyphen is allowed in a MIDDLE segment.
+    DXN.make('org.dxos.app-framework.event.startup');
+    // Versioned form.
+    DXN.make('org.dxos.type.calendar', '1.0.0');
+  });
+
+  test('rejects invalid NSIDs — compile-time type errors', () => {
+    // Wrapped in a never-called arrow so the invalid calls are type-checked but
+    // never executed at runtime. If Name unexpectedly starts accepting any
+    // of these, the @ts-expect-error directive itself becomes a build error
+    // ("Unused '@ts-expect-error' directive"), causing the CI check to fail.
+    void (() => {
+      // No dots — single segment.
+      // @ts-expect-error
+      DXN.make('unknown');
+      // Hyphen in the FINAL segment.
+      // @ts-expect-error
+      DXN.make('com.example.type.registry-entry');
+      // Hyphen in the final segment, versioned.
+      // @ts-expect-error
+      DXN.make('com.example.type.registry-entry', '0.1.0');
+      // Common mistake: kebab-case activation event name.
+      // @ts-expect-error
+      DXN.make('org.dxos.app-framework.event.setup-react-surface');
+    });
+  });
+});
+
 describe('DXN.make', () => {
   test('produces unversioned DXN', ({ expect }) => {
     expect(DXN.make('org.dxos.type.calendar')).toBe('dxn:org.dxos.type.calendar');
@@ -32,9 +67,12 @@ describe('DXN.make', () => {
     expect(DXN.make('org.dxos.type.calendar', '1.0.0')).toBe('dxn:org.dxos.type.calendar:1.0.0');
   });
 
-  test('throws on invalid NSID', ({ expect }) => {
+  test('throws on invalid NSID at runtime', ({ expect }) => {
+    // @ts-expect-error intentionally invalid NSIDs — verifying runtime throws
     expect(() => DXN.make('not-a-valid-nsid')).toThrow();
+    // @ts-expect-error
     expect(() => DXN.make('com.example.type.registry-entry')).toThrow();
+    // @ts-expect-error
     expect(() => DXN.make('com.example.type.registry-entry', '0.1.0')).toThrow();
   });
 });
@@ -83,3 +121,19 @@ describe('DXN.getVersion', () => {
     expect(DXN.getVersion(DXN.make('org.dxos.type.calendar'))).toBeUndefined();
   });
 });
+
+describe('DXN.NameSchema', () => {
+  const isName = Schema.is(DXN.NameSchema);
+
+  test('accepts a well-formed NSID name (no dxn: prefix)', ({ expect }) => {
+    expect(isName('com.anthropic.model.claude-sonnet-4-6.default')).toBe(true);
+    expect(isName('org.dxos.provider.edge')).toBe(true);
+    expect(isName('com.meta.model.llama-3-2-1b.instruct')).toBe(true);
+  });
+
+  test('rejects malformed names', ({ expect }) => {
+    expect(isName('single')).toBe(false); // not multi-segment
+    expect(isName('com.example.model.has-hyphen')).toBe(false); // final segment has a hyphen
+    expect(isName('dxn:com.example.type.thing')).toBe(false); // already a full DXN, not a bare name
+  });
+});

package/src/DXN.ts

@@ -30,6 +30,44 @@ const DXN_SPEC_REGEXP =
  */
 export type DXN = URI.URI & { readonly __DXN: unique symbol };
 
+/**
+ * Compile-time validation for NSID strings (the `dxn:` prefix is absent here).
+ *
+ * Checks two rules expressible with template literal types:
+ * - Must contain at least one dot (multi-segment).
+ * - Final segment (after the last dot) must not contain a hyphen.
+ *
+ * TypeScript template literal inference is non-greedy: `${string}.${infer Rest}`
+ * always splits at the first dot. The type recurses until `Rest` has no more dots,
+ * at which point it is the true final segment and is checked for hyphens.
+ *
+ * Broad `string` passes through unchanged so that template-literal call sites
+ * whose prefix segment is `string` are not rejected — those are validated at
+ * runtime by the regex inside `parse`.
+ */
+export type Name<T extends string> = [string] extends [T]
+  ? string
+  : T extends `${string}.${infer Rest}`
+    ? Rest extends `${string}.${string}`
+      ? [Name<Rest>] extends [never]
+        ? never
+        : T
+      : Rest extends `${string}-${string}`
+        ? never
+        : T
+    : never;
+
+/**
+ * Effect Schema validating an NSID name — the `dxn:`-less portion — at runtime, mirroring the rules
+ * the {@link Name} type checks at compile time (multi-segment; camelCase final segment). Pairs with
+ * the {@link Name} type for schema fields that hold a bare NSID (e.g. a model id passed to a creator
+ * helper). Named `NameSchema` because a value cannot share the generic `Name` type's name.
+ */
+export const NameSchema: Schema.Schema<string, string> = Schema.String.pipe(
+  Schema.filter((value) => DXN_SPEC_REGEXP.test(`dxn:${value}`), { message: () => 'Invalid NSID name' }),
+  Schema.annotations({ title: 'DXN.Name', description: 'NSID name (the dxn: prefix omitted)' }),
+);
+
 /**
  * Cheap prefix check — does not validate the full DXN grammar.
  * Sufficient for narrowing a URI to a DXN.
@@ -40,11 +78,19 @@ export const isDXN = (value: unknown): value is DXN => typeof value === 'string'
  * Constructs a DXN from an NSID (and optional version). Throws if the result
  * is not a valid DXN. Use `tryMake` for non-throwing string parsing.
  *
+ * Static NSID strings are validated at compile time via {@link Name}:
+ * the final segment must be camelCase (no hyphens). Template-literal strings
+ * with a runtime prefix are accepted here but still validated at runtime.
+ *
  * @example make('org.dxos.type.calendar') → 'dxn:org.dxos.type.calendar'
  * @example make('org.dxos.type.calendar', '1.0.0') → 'dxn:org.dxos.type.calendar:1.0.0'
  */
-export const make = (nsid: string, version?: string): DXN =>
-  parse(version != null ? `dxn:${nsid}:${version}` : `dxn:${nsid}`);
+export const make: {
+  <T extends string>(
+    nsid: [Name<T>] extends [never] ? `Invalid NSID "${T}": final segment must be camelCase (no hyphens)` : T,
+    version?: string,
+  ): DXN;
+} = (nsid: string, version?: string): DXN => parse(version != null ? `dxn:${nsid}:${version}` : `dxn:${nsid}`);
 
 /**
  * Parses a full DXN string. Returns undefined on failure.