@dxos/keys 0.8.3-staging.0fa589b → 0.8.4-main.28f8d3d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/keys",
-  "version": "0.8.3-staging.0fa589b",
+  "version": "0.8.4-main.28f8d3d",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,12 +10,10 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
-      "node": {
-        "require": "./dist/lib/node/index.cjs",
-        "default": "./dist/lib/node-esm/index.mjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
+      "node": "./dist/lib/node-esm/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -27,11 +25,11 @@
     "src"
   ],
   "dependencies": {
-    "effect": "3.14.21",
+    "effect": "3.17.7",
     "ulidx": "^2.3.0",
-    "@dxos/invariant": "0.8.3-staging.0fa589b",
-    "@dxos/node-std": "0.8.3-staging.0fa589b",
-    "@dxos/debug": "0.8.3-staging.0fa589b"
+    "@dxos/debug": "0.8.4-main.28f8d3d",
+    "@dxos/invariant": "0.8.4-main.28f8d3d",
+    "@dxos/node-std": "0.8.4-main.28f8d3d"
   },
   "devDependencies": {
     "base32-decode": "^1.0.0",

package/src/dxn.ts

@@ -2,11 +2,12 @@
 // Copyright 2024 DXOS.org
 //
 
+import type { InspectOptionsStylized, inspect } from 'node:util';
+
 import { Schema } from 'effect';
-import type { inspect, InspectOptionsStylized } from 'node:util';
 
-import { devtoolsFormatter, type DevtoolsFormatter, inspectCustom } from '@dxos/debug';
-import { invariant } from '@dxos/invariant';
+import { type DevtoolsFormatter, devtoolsFormatter, inspectCustom } from '@dxos/debug';
+import { assertArgument, invariant } from '@dxos/invariant';
 
 import { ObjectId } from './object-id';
 import { SpaceId } from './space-id';
@@ -18,6 +19,8 @@ import { SpaceId } from './space-id';
 // TODO(dmaretskyi): "@" is a separator character in the URI spec.
 export const LOCAL_SPACE_TAG = '@';
 
+export const DXN_ECHO_REGEXP = /@(dxn:[a-zA-Z0-p:@]+)/;
+
 // TODO(burdon): Namespace for.
 export const QueueSubspaceTags = Object.freeze({
   DATA: 'data',
@@ -43,6 +46,7 @@ export type QueueSubspaceTag = (typeof QueueSubspaceTags)[keyof typeof QueueSubs
  * ```
  */
 export class DXN {
+  // TODO(burdon): Rename to DXN (i.e., DXN.DXN).
   // TODO(dmaretskyi): Should this be a transformation into the DXN type?
   static Schema = Schema.NonEmptyString.pipe(
     Schema.pattern(/^dxn:([^:]+):(?:[^:]+:?)+[^:]$/),
@@ -119,7 +123,7 @@ export class DXN {
   static tryParse(dxn: string): DXN | undefined {
     try {
       return DXN.parse(dxn);
-    } catch (error) {
+    } catch {
       return undefined;
     }
   }
@@ -139,17 +143,27 @@ export class DXN {
     return new DXN(DXN.kind.TYPE, [typename, version]);
   }
 
+  /**
+   * @example `dxn:echo:BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE:01J00J9B45YHYSGZQTQMSKMGJ6`
+   */
+  static fromSpaceAndObjectId(spaceId: SpaceId, objectId: ObjectId): DXN {
+    assertArgument(SpaceId.isValid(spaceId), `Invalid space ID: ${spaceId}`);
+    assertArgument(ObjectId.isValid(objectId), `Invalid object ID: ${objectId}`);
+    return new DXN(DXN.kind.ECHO, [spaceId, objectId]);
+  }
+
   /**
    * @example `dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6`
    */
   static fromLocalObjectId(id: string): DXN {
+    assertArgument(ObjectId.isValid(id), `Invalid object ID: ${id}`);
     return new DXN(DXN.kind.ECHO, [LOCAL_SPACE_TAG, id]);
   }
 
   static fromQueue(subspaceTag: QueueSubspaceTag, spaceId: SpaceId, queueId: ObjectId, objectId?: ObjectId) {
-    invariant(SpaceId.isValid(spaceId));
-    invariant(ObjectId.isValid(queueId));
-    invariant(!objectId || ObjectId.isValid(objectId));
+    assertArgument(SpaceId.isValid(spaceId), `Invalid space ID: ${spaceId}`);
+    assertArgument(ObjectId.isValid(queueId), `Invalid queue ID: ${queueId}`);
+    assertArgument(!objectId || ObjectId.isValid(objectId), `Invalid object ID: ${objectId}`);
 
     return new DXN(DXN.kind.QUEUE, [subspaceTag, spaceId, queueId, ...(objectId ? [objectId] : [])]);
   }
@@ -158,8 +172,11 @@ export class DXN {
   #parts: string[];
 
   constructor(kind: string, parts: string[]) {
-    invariant(parts.length > 0);
-    invariant(parts.every((part) => typeof part === 'string' && part.length > 0 && part.indexOf(':') === -1));
+    assertArgument(parts.length > 0, `Invalid DXN: ${parts}`);
+    assertArgument(
+      parts.every((part) => typeof part === 'string' && part.length > 0 && part.indexOf(':') === -1),
+      `Invalid DXN: ${parts}`,
+    );
 
     // Per-type validation.
     switch (kind) {
@@ -179,6 +196,35 @@ export class DXN {
     this.#parts = parts;
   }
 
+  toString(): DXN.String {
+    return `dxn:${this.#kind}:${this.#parts.join(':')}` as DXN.String;
+  }
+
+  toJSON(): string {
+    return this.toString();
+  }
+
+  /**
+   * Used by Node.js to get textual representation of this object when it's printed with a `console.log` statement.
+   */
+  [inspectCustom](depth: number, options: InspectOptionsStylized, inspectFn: typeof inspect): string {
+    const printControlCode = (code: number) => {
+      return `\x1b[${code}m`;
+    };
+
+    return (
+      printControlCode(inspectFn.colors.blueBright![0]) + this.toString() + printControlCode(inspectFn.colors.reset![0])
+    );
+  }
+
+  get [devtoolsFormatter](): DevtoolsFormatter {
+    return {
+      header: () => {
+        return ['span', { style: 'font-weight: bold;' }, this.toString()];
+      },
+    };
+  }
+
   get parts() {
     return this.#parts;
   }
@@ -204,6 +250,7 @@ export class DXN {
 
     const [type, version] = this.#parts;
     return {
+      // TODO(wittjosiah): Should be `typename` for consistency.
       type,
       version: version as string | undefined,
     };
@@ -239,29 +286,11 @@ export class DXN {
     };
   }
 
-  toString(): DXN.String {
-    return `dxn:${this.#kind}:${this.#parts.join(':')}` as DXN.String;
-  }
-
   /**
-   * Used by Node.js to get textual representation of this object when it's printed with a `console.log` statement.
+   * Produces a new DXN with the given parts appended.
    */
-  [inspectCustom](depth: number, options: InspectOptionsStylized, inspectFn: typeof inspect): string {
-    const printControlCode = (code: number) => {
-      return `\x1b[${code}m`;
-    };
-
-    return (
-      printControlCode(inspectFn.colors.blueBright![0]) + this.toString() + printControlCode(inspectFn.colors.reset![0])
-    );
-  }
-
-  get [devtoolsFormatter](): DevtoolsFormatter {
-    return {
-      header: () => {
-        return ['span', { style: 'font-weight: bold;' }, this.toString()];
-      },
-    };
+  extend(parts: string[]): DXN {
+    return new DXN(this.#kind, [...this.#parts, ...parts]);
   }
 }
 
@@ -299,8 +328,7 @@ export declare namespace DXN {
 
   export type EchoDXN = {
     spaceId?: SpaceId;
-    // TODO(burdon): Rename objectId.
-    echoId: string; // TODO(dmaretskyi): ObjectId.
+    echoId: string; // TODO(dmaretskyi): Rename to `objectId` and use `ObjectId` for the type.
   };
 
   export type QueueDXN = {

package/src/index.ts

@@ -7,4 +7,4 @@ export * from './identity-did';
 export * from './object-id';
 export * from './public-key';
 export * from './space-id';
-export * from './types';
+export type * from './types';

package/src/object-id.ts

@@ -9,7 +9,7 @@ import { ulid } from 'ulidx';
 // export const ObjectIdBrand: unique symbol = Symbol('@dxos/echo/ObjectId');
 // export const ObjectIdSchema = Schema.ULID.pipe(S.brand(ObjectIdBrand));
 const ObjectIdSchema = Schema.String.pipe(Schema.pattern(/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/i)).annotations({
-  description: 'a Universally Unique Lexicographically Sortable Identifier',
+  description: 'A Universally Unique Lexicographically Sortable Identifier',
   pattern: '^[0-7][0-9A-HJKMNP-TV-Z]{25}$',
 });
 
@@ -31,7 +31,7 @@ export const ObjectId: ObjectIdClass = class extends ObjectIdSchema {
     try {
       Schema.decodeSync(ObjectId)(id);
       return true;
-    } catch (err) {
+    } catch {
       return false;
     }
   }

package/src/public-key.ts

@@ -2,15 +2,16 @@
 // Copyright 2020 DXOS.org
 //
 
+import { type InspectOptionsStylized, type inspect } from 'node:util';
+
 import base32Decode from 'base32-decode';
 import base32Encode from 'base32-encode';
-import { type inspect, type InspectOptionsStylized } from 'node:util';
 
 import {
-  devtoolsFormatter,
   type DevtoolsFormatter,
-  equalsSymbol,
   type Equatable,
+  devtoolsFormatter,
+  equalsSymbol,
   inspectCustom,
   truncateKey,
 } from '@dxos/debug';

package/src/random-bytes.ts

@@ -4,7 +4,7 @@
 
 export const randomBytes = (length: number) => {
   // globalThis.crypto is not available in Node.js when running in vitest even though the documentation says it should be.
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
   const webCrypto = globalThis.crypto ?? require('node:crypto').webcrypto;
 
   const bytes = new Uint8Array(length);