@dxos/keys 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/keys",
-  "version": "0.8.4-main.dedc0f3",
+  "version": "0.8.4-main.dfabb4ec29",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": false,
@@ -17,23 +21,23 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "effect": "3.17.7",
     "ulidx": "^2.3.0",
-    "@dxos/debug": "0.8.4-main.dedc0f3",
-    "@dxos/invariant": "0.8.4-main.dedc0f3",
-    "@dxos/node-std": "0.8.4-main.dedc0f3"
+    "@dxos/debug": "0.8.4-main.dfabb4ec29",
+    "@dxos/invariant": "0.8.4-main.dfabb4ec29",
+    "@dxos/node-std": "0.8.4-main.dfabb4ec29"
   },
   "devDependencies": {
     "base32-decode": "^1.0.0",
-    "base32-encode": "^2.0.0"
+    "base32-encode": "^2.0.0",
+    "effect": "3.20.0"
+  },
+  "peerDependencies": {
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/dxn.ts

@@ -2,10 +2,9 @@
 // Copyright 2024 DXOS.org
 //
 
+import * as Schema from 'effect/Schema';
 import type { InspectOptionsStylized, inspect } from 'node:util';
 
-import { Schema } from 'effect';
-
 import { type DevtoolsFormatter, devtoolsFormatter, inspectCustom } from '@dxos/debug';
 import { assertArgument, invariant } from '@dxos/invariant';
 
@@ -33,7 +32,7 @@ export type QueueSubspaceTag = (typeof QueueSubspaceTags)[keyof typeof QueueSubs
 // Consider: https://github.com/multiformats/multiaddr
 // dxn:echo:[<space-id>:[<queue-id>:]]<object-id>
 // dxn:echo:[S/<space-id>:[Q/<queue-id>:]]<object-id>
-// dxn:type:dxos.org/markdown/Contact
+// dxn:type:org.dxos.markdown.contact
 
 /**
  * DXN unambiguously names a resource like an ECHO object, schema definition, plugin, etc.
@@ -47,8 +46,8 @@ export type QueueSubspaceTag = (typeof QueueSubspaceTags)[keyof typeof QueueSubs
  * dxn:echo:<space key>:<echo id>
  * dxn:echo:BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE:01J00J9B45YHYSGZQTQMSKMGJ6
  * dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6
- * dxn:type:dxos.org/type/Calendar
- * dxn:plugin:dxos.org/agent/plugin/functions
+ * dxn:type:org.dxos.type.calendar
+ * dxn:plugin:org.dxos.agent.plugin.functions
  * ```
  */
 export class DXN {
@@ -57,11 +56,11 @@ export class DXN {
   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),
+    // FormatAnnotation.set(TypeFormat.DXN),
     Schema.annotations({
       title: 'DXN',
       description: 'DXN URI',
-      examples: ['dxn:type:example.com/type/MyType', 'dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6'],
+      examples: ['dxn:type:com.example.type.my-type', 'dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6'],
     }),
   );
 
@@ -140,14 +139,14 @@ export class DXN {
   }
 
   /**
-   * @example `dxn:type:example.com/type/Contact`
+   * @example `dxn:type:com.example.type.person`
    */
   static fromTypename(typename: string): DXN {
     return new DXN(DXN.kind.TYPE, [typename]);
   }
 
   /**
-   * @example `dxn:type:example.com/type/Contact:0.1.0`
+   * @example `dxn:type:com.example.type.person:0.1.0`
    */
   // TODO(dmaretskyi): Consider using @ as the version separator.
   static fromTypenameAndVersion(typename: string, version: string): DXN {
@@ -300,7 +299,7 @@ export class DXN {
     }
 
     return {
-      subspaceTag,
+      subspaceTag: subspaceTag as QueueSubspaceTag,
       spaceId: spaceId as SpaceId,
       queueId,
       objectId: objectId as string | undefined,
@@ -338,7 +337,7 @@ export declare namespace DXN {
   };
 
   export type QueueDXN = {
-    subspaceTag: string;
+    subspaceTag: QueueSubspaceTag;
     spaceId: SpaceId;
     queueId: string; // TODO(dmaretskyi): ObjectId.
     objectId?: string; // TODO(dmaretskyi): ObjectId.

package/src/object-id.ts

@@ -2,8 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
-import { ulid } from 'ulidx';
+import * as Schema from 'effect/Schema';
+import { type PRNG, type ULIDFactory, monotonicFactory } from 'ulidx';
 
 // TODO(dmaretskyi): Make brand.
 // export const ObjectIdBrand: unique symbol = Symbol('@dxos/echo/ObjectId');
@@ -16,9 +16,39 @@ const ObjectIdSchema = Schema.String.pipe(Schema.pattern(/^[0-7][0-9A-HJKMNP-TV-
 export type ObjectId = typeof ObjectIdSchema.Type;
 
 export interface ObjectIdClass extends Schema.SchemaClass<ObjectId, string> {
+  /**
+   * @returns true if the string is a valid ObjectId.
+   */
   isValid(id: string): id is ObjectId;
+
+  /**
+   * Creates an ObjectId from a string validating the format.
+   */
   make(id: string): ObjectId;
+
+  /**
+   * Generates a random ObjectId.
+   */
   random(): ObjectId;
+
+  /**
+   * WARNING: To be used only within tests.
+   *
+   * Disables randomness in ObjectId generation, causing the same sequence of IDs to be generated.
+   * Do not use in production code as this will cause data collisions.
+   * Place this at the top of the test file to ensure that the same sequence of IDs is generated.
+   *
+   * ```ts
+   * ObjectId.dangerouslyDisableRandomness();
+   *
+   * describe('suite', () => {
+   *   // ...
+   * });
+   * ```
+   *
+   * NOTE: The generated IDs depend on the order of ObjectId.random() calls, which might be affected by test order, scheduling, etc.
+   */
+  dangerouslyDisableRandomness(): void;
 }
 
 /**
@@ -27,6 +57,9 @@ export interface ObjectIdClass extends Schema.SchemaClass<ObjectId, string> {
  * Follows ULID spec.
  */
 export const ObjectId: ObjectIdClass = class extends ObjectIdSchema {
+  static #factory: ULIDFactory = monotonicFactory();
+  static #seedTime: number | undefined = undefined;
+
   static isValid(id: string): id is ObjectId {
     try {
       Schema.decodeSync(ObjectId)(id);
@@ -37,6 +70,62 @@ export const ObjectId: ObjectIdClass = class extends ObjectIdSchema {
   }
 
   static random(): ObjectId {
-    return ulid() as ObjectId;
+    return this.#factory(this.#seedTime) as ObjectId;
+  }
+
+  static dangerouslyDisableRandomness() {
+    this.#factory = monotonicFactory(makeTestPRNG());
+    this.#seedTime = new Date('2025-01-01').getTime();
   }
 };
+
+/**
+ * Test PRNG that always starts with the same seed and produces the same sequence.
+ */
+const makeTestPRNG = (): PRNG => {
+  const rng = new SimplePRNG();
+  return () => {
+    return rng.next();
+  };
+};
+
+/**
+ * Simple Linear Congruential Generator (LCG) for pseudo-random number generation.
+ * Returns numbers in the range [0, 1) (0 inclusive, 1 exclusive).
+ */
+export class SimplePRNG {
+  #seed: number;
+
+  // LCG parameters (from Numerical Recipes)
+  static readonly #a = 1664525;
+  static readonly #c = 1013904223;
+  static readonly #m = Math.pow(2, 32);
+
+  /**
+   * Creates a new PRNG instance.
+   * @param seed - Initial seed value. If not provided, uses 0.
+   */
+  constructor(seed: number = 0) {
+    this.#seed = seed;
+  }
+
+  /**
+   * Generates the next pseudo-random number in the range [0, 1).
+   * @returns A pseudo-random number between 0 (inclusive) and 1 (exclusive).
+   */
+  next(): number {
+    // Update seed using LCG formula: (a * seed + c) mod m
+    this.#seed = (SimplePRNG.#a * this.#seed + SimplePRNG.#c) % SimplePRNG.#m;
+
+    // Normalize to [0, 1) range
+    return this.#seed / SimplePRNG.#m;
+  }
+
+  /**
+   * Resets the generator with a new seed.
+   * @param seed - New seed value.
+   */
+  reset(seed: number): void {
+    this.#seed = seed;
+  }
+}

package/src/prng.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Simple Linear Congruential Generator (LCG) for pseudo-random number generation.
+ * Returns numbers in the range [0, 1) (0 inclusive, 1 exclusive).
+ */
+export class SimplePRNG {
+  private _seed: number;
+
+  // LCG parameters (from Numerical Recipes)
+  private static readonly _a = 1664525;
+  private static readonly _c = 1013904223;
+  private static readonly _m = Math.pow(2, 32);
+
+  /**
+   * Creates a new PRNG instance.
+   * @param seed - Initial seed value. If not provided, uses current timestamp.
+   */
+  constructor(seed?: number) {
+    this._seed = seed ?? Date.now();
+  }
+
+  /**
+   * Generates the next pseudo-random number in the range [0, 1).
+   * @returns A pseudo-random number between 0 (inclusive) and 1 (exclusive).
+   */
+  next(): number {
+    // Update seed using LCG formula: (a * seed + c) mod m
+    this._seed = (SimplePRNG._a * this._seed + SimplePRNG._c) % SimplePRNG._m;
+
+    // Normalize to [0, 1) range
+    return this._seed / SimplePRNG._m;
+  }
+
+  /**
+   * Resets the generator with a new seed.
+   * @param seed - New seed value.
+   */
+  reset(seed: number): void {
+    this._seed = seed;
+  }
+}
+
+/**
+ * Creates a simple PRNG function with optional seed.
+ * @param seed - Optional seed value.
+ * @returns A function that returns pseudo-random numbers in [0, 1).
+ */
+export const createPRNG = (seed?: number): (() => number) => {
+  const prng = new SimplePRNG(seed);
+  return () => prng.next();
+};

package/src/public-key.ts

@@ -2,10 +2,9 @@
 // Copyright 2020 DXOS.org
 //
 
-import { type InspectOptionsStylized, type inspect } from 'node:util';
-
 import base32Decode from 'base32-decode';
 import base32Encode from 'base32-encode';
+import { type InspectOptionsStylized, type inspect } from 'node:util';
 
 import {
   type DevtoolsFormatter,
@@ -217,7 +216,7 @@ export class PublicKey implements Equatable {
     return 'B' + base32Encode(this._value, 'RFC4648');
   }
 
-  truncate(length = undefined): string {
+  truncate(length?: number): string {
     return truncateKey(this, length);
   }
 

package/src/space-id.ts

@@ -4,7 +4,7 @@
 
 import base32Decode from 'base32-decode';
 import base32Encode from 'base32-encode';
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { invariant } from '@dxos/invariant';
 
@@ -17,7 +17,7 @@ const MULTIBASE_PREFIX = 'B';
 
 const ENCODED_LENGTH = 33;
 
-const isValid = (value: string): value is SpaceId => {
+const isValid = (value: unknown): value is SpaceId => {
   return typeof value === 'string' && value.startsWith(MULTIBASE_PREFIX) && value.length === ENCODED_LENGTH;
 };
 
@@ -33,7 +33,7 @@ export const SpaceId: Schema.Schema<SpaceId, string> & {
   byteLength: number;
   encode: (value: Uint8Array) => SpaceId;
   decode: (value: SpaceId) => Uint8Array;
-  isValid: (value: string) => value is SpaceId;
+  isValid: (value: unknown) => value is SpaceId;
   make: (value: string) => SpaceId;
   random: () => SpaceId;
 } = class extends Schema.String.pipe(Schema.filter(isValid)) {