@dxos/keys 0.8.2-staging.7ac8446 → 0.8.2-staging.f780727

package/dist/types/src/space-id.d.ts

@@ -1,3 +1,4 @@
+import { Schema } from 'effect';
 /**
  * A unique identifier for a space.
  * Space keys are generated by creating a keypair, and then taking the first 20 bytes of the SHA-256 hash of the public key and encoding them to multibase RFC4648 base-32 format (prefixed with B, see Multibase Table).
@@ -6,11 +7,12 @@
 export type SpaceId = string & {
     __SpaceId: true;
 };
-export declare const SpaceId: Readonly<{
-    byteLength: 20;
+export declare const SpaceId: Schema.Schema<SpaceId, string> & {
+    byteLength: number;
     encode: (value: Uint8Array) => SpaceId;
     decode: (value: SpaceId) => Uint8Array;
     isValid: (value: string) => value is SpaceId;
+    make: (value: string) => SpaceId;
     random: () => SpaceId;
-}>;
+};
 //# sourceMappingURL=space-id.d.ts.map

package/dist/types/src/space-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"space-id.d.ts","sourceRoot":"","sources":["../../../src/space-id.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC;AAEnD,eAAO,MAAM,OAAO;;oBAEF,UAAU,KAAG,OAAO;oBAMpB,OAAO,KAAG,UAAU;qBAKnB,MAAM,KAAG,KAAK,IAAI,OAAO;kBAG9B,OAAO;EAGnB,CAAC"}
+{"version":3,"file":"space-id.d.ts","sourceRoot":"","sources":["../../../src/space-id.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAiBhC;;;;GAIG;AAEH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC;AAEnD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;IACvC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,UAAU,CAAC;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC;IAC7C,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,MAAM,EAAE,MAAM,OAAO,CAAC;CAoBvB,CAAC"}

package/dist/types/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"version":"5.7.3"}
+{"version":"5.8.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/keys",
-  "version": "0.8.2-staging.7ac8446",
+  "version": "0.8.2-staging.f780727",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -27,9 +27,11 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/debug": "0.8.2-staging.7ac8446",
-    "@dxos/invariant": "0.8.2-staging.7ac8446",
-    "@dxos/node-std": "0.8.2-staging.7ac8446"
+    "effect": "3.14.21",
+    "ulidx": "^2.3.0",
+    "@dxos/debug": "0.8.2-staging.f780727",
+    "@dxos/invariant": "0.8.2-staging.f780727",
+    "@dxos/node-std": "0.8.2-staging.f780727"
   },
   "devDependencies": {
     "base32-decode": "^1.0.0",

package/src/dxn.ts

@@ -2,16 +2,20 @@
 // Copyright 2024 DXOS.org
 //
 
+import { Schema } from 'effect';
 import type { inspect, InspectOptionsStylized } from 'node:util';
 
 import { inspectCustom } from '@dxos/debug';
 import { invariant } from '@dxos/invariant';
 
-import type { SpaceId } from './space-id';
+import { ObjectId } from './object-id';
+import { SpaceId } from './space-id';
 
 /**
  * Tags for ECHO DXNs that should resolve the object ID in the local space.
  */
+// TODO(dmaretskyi): Rebrand this as "unknown location" to specify objects in the same space or queue. Essentially making the DXN it a URI not URL
+// TODO(dmaretskyi): "@" is a separator character in the URI spec.
 export const LOCAL_SPACE_TAG = '@';
 
 // TODO(burdon): Namespace for.
@@ -20,6 +24,8 @@ export const QueueSubspaceTags = Object.freeze({
   TRACE: 'trace',
 });
 
+export type QueueSubspaceTag = (typeof QueueSubspaceTags)[keyof typeof QueueSubspaceTags];
+
 /**
  * DXN unambiguously names a resource like an ECHO object, schema definition, plugin, etc.
  * Each DXN starts with a dxn prefix, followed by a resource kind.
@@ -37,6 +43,18 @@ export const QueueSubspaceTags = Object.freeze({
  * ```
  */
 export class DXN {
+  // TODO(dmaretskyi): Should this be a transformation into the DXN type?
+  static Schema = Schema.NonEmptyString.pipe(
+    Schema.pattern(/^dxn:([^:]+):(?:[^:]+:?)+[^:]$/),
+    // TODO(dmaretskyi): To set the format we need to move the annotation IDs out of the echo-schema package.
+    // FormatAnnotation.set(FormatEnum.DXN),
+    Schema.annotations({
+      title: 'DXN',
+      description: 'DXN URI',
+      examples: ['dxn:type:example.com/type/MyType', 'dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6'],
+    }),
+  );
+
   /**
    * Kind constants.
    */
@@ -50,7 +68,7 @@ export class DXN {
      * dxn:echo:<space id>:<echo id>
      * dxn:echo:@:<echo id>
      */
-    // TODO(burdon): Rename to OBJECT?
+    // TODO(burdon): Rename to OBJECT? (BREAKING CHANGE).
     // TODO(burdon): Add separate Kind for space.
     ECHO: 'echo',
 
@@ -63,12 +81,16 @@ export class DXN {
     QUEUE: 'queue',
   });
 
-  static equals(a: DXN, b: DXN) {
+  get kind() {
+    return this.#kind;
+  }
+
+  static equals(a: DXN, b: DXN): boolean {
     return a.kind === b.kind && a.parts.length === b.parts.length && a.parts.every((part, i) => part === b.parts[i]);
   }
 
   // TODO(burdon): Rename isValid.
-  static isDXNString(dxn: string) {
+  static isDXNString(dxn: string): boolean {
     return dxn.startsWith('dxn:');
   }
 
@@ -101,7 +123,7 @@ export class DXN {
   /**
    * @example `dxn:type:example.com/type/Contact`
    */
-  static fromTypename(typename: string) {
+  static fromTypename(typename: string): DXN {
     return new DXN(DXN.kind.TYPE, [typename]);
   }
 
@@ -109,17 +131,25 @@ export class DXN {
    * @example `dxn:type:example.com/type/Contact:0.1.0`
    */
   // TODO(dmaretskyi): Consider using @ as the version separator.
-  static fromTypenameAndVersion(typename: string, version: string) {
+  static fromTypenameAndVersion(typename: string, version: string): DXN {
     return new DXN(DXN.kind.TYPE, [typename, version]);
   }
 
   /**
    * @example `dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6`
    */
-  static fromLocalObjectId(id: string) {
+  static fromLocalObjectId(id: string): DXN {
     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));
+
+    return new DXN(DXN.kind.QUEUE, [subspaceTag, spaceId, queueId, ...(objectId ? [objectId] : [])]);
+  }
+
   #kind: string;
   #parts: string[];
 
@@ -145,24 +175,21 @@ export class DXN {
     this.#parts = parts;
   }
 
-  get kind() {
-    return this.#kind;
-  }
-
   get parts() {
     return this.#parts;
   }
 
+  // TODO(burdon): Should getters fail?
   get typename() {
     invariant(this.#kind === DXN.kind.TYPE);
     return this.#parts[0];
   }
 
-  hasTypenameOf(typename: string) {
+  hasTypenameOf(typename: string): boolean {
     return this.#kind === DXN.kind.TYPE && this.#parts.length === 1 && this.#parts[0] === typename;
   }
 
-  isLocalObjectId() {
+  isLocalObjectId(): boolean {
     return this.#kind === DXN.kind.ECHO && this.#parts[0] === LOCAL_SPACE_TAG && this.#parts.length === 2;
   }
 
@@ -215,7 +242,7 @@ export class DXN {
   /**
    * 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) {
+  [inspectCustom](depth: number, options: InspectOptionsStylized, inspectFn: typeof inspect): string {
     const printControlCode = (code: number) => {
       return `\x1b[${code}m`;
     };
@@ -226,6 +253,29 @@ export class DXN {
   }
 }
 
+// TODO(dmaretskyi): Fluent API:
+/*
+class DXN {
+  ...
+isEchoDXN(): this is EchoDXN {
+  return this.#kind === DXN.kind.ECHO;
+}
+...
+}
+
+interface EchoDXN extends DXN {
+  objectId: ObjectId;
+}
+
+declare const dxn: DXN;
+
+dxn.objectId
+
+if(dxn.isEchoDXN()) {
+  dxn.objectId
+}
+  ```
+
 /**
  * API namespace.
  */

package/src/index.ts

@@ -7,3 +7,4 @@ export * from './public-key';
 export * from './types';
 export * from './space-id';
 export * from './dxn';
+export * from './object-id';

package/src/object-id.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+import { ulid } from 'ulidx';
+
+// TODO(dmaretskyi): Make brand.
+// 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',
+  pattern: '^[0-7][0-9A-HJKMNP-TV-Z]{25}$',
+});
+
+export type ObjectId = typeof ObjectIdSchema.Type;
+
+export interface ObjectIdClass extends Schema.SchemaClass<ObjectId, string> {
+  isValid(id: string): id is ObjectId;
+  make(id: string): ObjectId;
+  random(): ObjectId;
+}
+
+/**
+ * Randomly generated unique identifier for an object.
+ *
+ * Follows ULID spec.
+ */
+export const ObjectId: ObjectIdClass = class extends ObjectIdSchema {
+  static isValid(id: string): id is ObjectId {
+    try {
+      Schema.decodeSync(ObjectId)(id);
+      return true;
+    } catch (err) {
+      return false;
+    }
+  }
+
+  static random(): ObjectId {
+    return ulid() as ObjectId;
+  }
+};

package/src/public-key.ts

@@ -90,7 +90,7 @@ export class PublicKey implements Equatable {
   /**
    * Creates new instance of PublicKey from hex string.
    */
-  static fromHex(hex: string) {
+  static fromHex(hex: string): PublicKey {
     if (hex.startsWith('0x')) {
       hex = hex.slice(2);
     }
@@ -139,7 +139,7 @@ export class PublicKey implements Equatable {
   /**
    * Tests two keys for equality.
    */
-  static equals(left: PublicKeyLike, right: PublicKeyLike) {
+  static equals(left: PublicKeyLike, right: PublicKeyLike): boolean {
     return PublicKey.from(left).equals(right);
   }
 
@@ -196,7 +196,7 @@ export class PublicKey implements Equatable {
     return this.toHex();
   }
 
-  toJSON() {
+  toJSON(): string {
     return this.toHex();
   }
 
@@ -216,7 +216,7 @@ export class PublicKey implements Equatable {
     return 'B' + base32Encode(this._value, 'RFC4648');
   }
 
-  truncate(length = undefined) {
+  truncate(length = undefined): string {
     return truncateKey(this, length);
   }
 
@@ -228,14 +228,14 @@ export class PublicKey implements Equatable {
     return this._value;
   }
 
-  getInsecureHash(modulo: number) {
+  getInsecureHash(modulo: number): number {
     return Math.abs(this._value.reduce((acc, val) => (acc ^ val) | 0, 0)) % modulo;
   }
 
   /**
    * 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) {
+  [inspectCustom](depth: number, options: InspectOptionsStylized, inspectFn: typeof inspect): string {
     if (!options.colors || typeof process.stdout.hasColors !== 'function' || !process.stdout.hasColors()) {
       return `<PublicKey ${this.truncate()}>`;
     }
@@ -302,7 +302,7 @@ export class PublicKey implements Equatable {
   /**
    * Test this key for equality with some other key.
    */
-  equals(other: PublicKeyLike) {
+  equals(other: PublicKeyLike): boolean {
     const otherConverted = PublicKey.from(other);
     if (this._value.length !== otherConverted._value.length) {
       return false;
@@ -316,7 +316,7 @@ export class PublicKey implements Equatable {
     return equal;
   }
 
-  [equalsSymbol](other: any) {
+  [equalsSymbol](other: any): boolean {
     if (!PublicKey.isPublicKey(other)) {
       return false;
     }

package/src/space-id.ts

@@ -4,43 +4,55 @@
 
 import base32Decode from 'base32-decode';
 import base32Encode from 'base32-encode';
+import { Schema } from 'effect';
 
 import { invariant } from '@dxos/invariant';
 
 import { randomBytes } from './random-bytes';
 
+/**
+ * Denotes RFC4648 base-32 format.
+ */
+const MULTIBASE_PREFIX = 'B';
+
+const ENCODED_LENGTH = 33;
+
+const isValid = (value: string): value is SpaceId => {
+  return typeof value === 'string' && value.startsWith(MULTIBASE_PREFIX) && value.length === ENCODED_LENGTH;
+};
+
 /**
  * A unique identifier for a space.
  * Space keys are generated by creating a keypair, and then taking the first 20 bytes of the SHA-256 hash of the public key and encoding them to multibase RFC4648 base-32 format (prefixed with B, see Multibase Table).
  * @example BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE
  */
-// TODO(burdon): Use effect brand.
+// TODO(burdon): Use effect branded type?
 export type SpaceId = string & { __SpaceId: true };
 
-export const SpaceId = Object.freeze({
-  byteLength: 20,
-  encode: (value: Uint8Array): SpaceId => {
+export const SpaceId: Schema.Schema<SpaceId, string> & {
+  byteLength: number;
+  encode: (value: Uint8Array) => SpaceId;
+  decode: (value: SpaceId) => Uint8Array;
+  isValid: (value: string) => value is SpaceId;
+  make: (value: string) => SpaceId;
+  random: () => SpaceId;
+} = class extends Schema.String.pipe(Schema.filter(isValid)) {
+  static byteLength = 20;
+
+  static encode = (value: Uint8Array): SpaceId => {
     invariant(value instanceof Uint8Array, 'Invalid type');
     invariant(value.length === SpaceId.byteLength, 'Invalid length');
-
     return (MULTIBASE_PREFIX + base32Encode(value, 'RFC4648')) as SpaceId;
-  },
-  decode: (value: SpaceId): Uint8Array => {
-    invariant(value.startsWith(MULTIBASE_PREFIX), 'Invalid multibase32 encoding');
+  };
 
+  static decode = (value: SpaceId): Uint8Array => {
+    invariant(value.startsWith(MULTIBASE_PREFIX), 'Invalid multibase32 encoding');
     return new Uint8Array(base32Decode(value.slice(1), 'RFC4648'));
-  },
-  isValid: (value: string): value is SpaceId => {
-    return typeof value === 'string' && value.startsWith(MULTIBASE_PREFIX) && value.length === ENCODED_LENGTH;
-  },
-  random: (): SpaceId => {
-    return SpaceId.encode(randomBytes(SpaceId.byteLength));
-  },
-});
+  };
 
-/**
- * Denotes RFC4648 base-32 format.
- */
-const MULTIBASE_PREFIX = 'B';
+  static isValid = isValid;
 
-const ENCODED_LENGTH = 33;
+  static random = (): SpaceId => {
+    return SpaceId.encode(randomBytes(SpaceId.byteLength));
+  };
+};