@dxos/util 0.4.9 → 0.4.10-main.068c3d8

package/dist/types/src/di-key.d.ts

@@ -0,0 +1,50 @@
+/// <reference types="node" />
+import { inspect } from 'node:util';
+export declare const symbolSingleton: unique symbol;
+export type SingletonFactory<T> = () => T;
+export declare class SymbolDiKey<T> {
+    symbol: symbol;
+    constructor(name: string);
+    [symbolSingleton]?: SingletonFactory<T>;
+    toString(): string;
+    [inspect.custom](): string;
+}
+export type ConstructorDiKey<T> = {
+    new (...args: any[]): T;
+    [symbolSingleton]?: SingletonFactory<T>;
+};
+/**
+ * Represents a key for an entry in a DI container.
+ * Class constructors can be used as is.
+ * Multiple keys can be combined into a single key to represent parameterized types.
+ * Composite keys maintain referential equality.
+ * Keys can optionally have a singleton factory attached to them.
+ */
+export type DiKey<T> = {
+    new (...args: any[]): T;
+} | SymbolDiKey<T>;
+export declare const DiKey: {
+    /**
+     * Needed to ensure referential equality of combined keys.
+     *
+     * This is a multilevel map of maps, where the maps are also used as keys.
+     *
+     * Good luck :)
+     */
+    "__#1@#combinedRegistry": WeakMap<WeakKey, any>;
+    define<T>(name: string): DiKey<T>;
+    singleton<T_1>(name: string, factory: SingletonFactory<T_1>): DiKey<T_1>;
+    stringify(id: DiKey<any>): string;
+    /**
+     * Create composite keys to represent parameterized types.
+     *
+     * @example DiKey.combine(A, B, C) => "A<B, C>"
+     *
+     * Maintains referential equality: `DiKey.combine(A, B) === DiKey.combine(A, B)`
+     */
+    combine(...ids: DiKey<any>[]): any;
+    getSingletonFactory<T_2>(id: DiKey<T_2>): SingletonFactory<T_2> | undefined;
+    "__#1@#lookupCombined"(map: WeakMap<any, any>, [first, ...rest]: DiKey<any>[]): WeakMap<any, any>;
+    "__#1@#combinedDescription"([first, ...rest]: DiKey<any>[]): string;
+};
+//# sourceMappingURL=di-key.d.ts.map

package/dist/types/src/di-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"di-key.d.ts","sourceRoot":"","sources":["../../../src/di-key.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,eAAO,MAAM,eAAe,eAAsB,CAAC;AAEnD,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAE1C,qBAAa,WAAW,CAAC,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;gBAEH,IAAI,EAAE,MAAM;IAIjB,CAAC,eAAe,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAa;IAE3D,QAAQ;IAIR,CAAC,OAAO,CAAC,MAAM,CAAC;CAGjB;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAExB,CAAC,eAAe,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACzC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IACf;IACE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CACzB,GACD,WAAW,CAAC,CAAC,CAAC,CAAC;AAEnB,eAAO,MAAM,KAAK;IAChB;;;;;;OAMG;;oBAKa,MAAM;yBAIH,MAAM;kBAMX,MAAM,GAAG,CAAC,GAAG,MAAM;IAWjC;;;;;;OAMG;oBACa,MAAM,GAAG,CAAC,EAAE;;gCASP,QAAQ,GAAG,EAAE,GAAG,CAAC,oBAAoB,MAAM,GAAG,CAAC,EAAE,GAAG,QAAQ,GAAG,EAAE,GAAG,CAAC;kDASnD,MAAM,GAAG,CAAC,EAAE;CAGjD,CAAC"}

package/dist/types/src/di-key.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=di-key.test.d.ts.map

package/dist/types/src/di-key.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"di-key.test.d.ts","sourceRoot":"","sources":["../../../src/di-key.test.ts"],"names":[],"mappings":""}

package/dist/types/src/json.d.ts

@@ -1,3 +1,6 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /**
  * JSON.stringify replacer.
  */
@@ -6,6 +9,10 @@ export declare function jsonReplacer(this: any, key: string, value: any): any;
  * Recursively converts an object into a JSON-compatible object.
  */
 export declare const jsonify: (value: any, depth?: number, visitedObjects?: WeakSet<any>) => any;
+/**
+ * Recursively converts an object into a JSON-compatible object appropriate for logging.
+ */
+export declare const jsonlogify: (value: any, depth?: number, visitedObjects?: WeakSet<any>) => any;
 export type JsonKeyOptions = {
     truncate?: boolean;
     humanize?: boolean;

package/dist/types/src/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/json.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,CAqBpE;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,UAAW,GAAG,oDAAmD,GA+BpF,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,eAAe,aAChB,cAAc,WAClB,MAAM,SAAS,GAAG,QAUvB,CAAC"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/json.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAKtG;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,CAqBpE;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,UAAW,GAAG,oDAAmD,GA+BpF,CAAC;AAEF;;GAEG;AAGH,eAAO,MAAM,UAAU,UAAW,GAAG,oDAAmD,GAiCvF,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,eAAe,aAChB,cAAc,WAClB,MAAM,SAAS,GAAG,QAUvB,CAAC"}

package/dist/types/src/map.d.ts

@@ -1,5 +1,10 @@
+interface IMap<K, V> {
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+}
 /**
  * Get or set map value.
  */
-export declare const defaultMap: <K, V>(map: Map<K, V>, key: K, def: V | (() => V)) => V;
+export declare const defaultMap: <K, V>(map: IMap<K, V>, key: K, def: V | (() => V)) => V;
+export {};
 //# sourceMappingURL=map.d.ts.map

package/dist/types/src/map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/map.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,UAAU,yDAQtB,CAAC"}
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/map.ts"],"names":[],"mappings":"AAIA,UAAU,IAAI,CAAC,CAAC,EAAE,CAAC;IACjB,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC3B,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,0DAQtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/util",
-  "version": "0.4.9",
+  "version": "0.4.10-main.068c3d8",
   "description": "Temporary bucket for misc functions, which should graduate into separate packages.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,13 +16,13 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/debug": "0.4.9",
-    "@dxos/invariant": "0.4.9",
-    "@dxos/keys": "0.4.9",
-    "@dxos/node-std": "0.4.9"
+    "@dxos/invariant": "0.4.10-main.068c3d8",
+    "@dxos/debug": "0.4.10-main.068c3d8",
+    "@dxos/keys": "0.4.10-main.068c3d8",
+    "@dxos/node-std": "0.4.10-main.068c3d8"
   },
   "devDependencies": {
-    "@dxos/crypto": "0.4.9"
+    "@dxos/crypto": "0.4.10-main.068c3d8"
   },
   "publishConfig": {
     "access": "public"

package/src/di-container.test.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { test } from 'vitest';
+
+import { DiContainer } from './di-container';
+import { DiKey } from './di-key';
+
+test('DiContainer', ({ expect }) => {
+  const A = DiKey.define<string>('A');
+  class B {}
+
+  const generic = DiKey.define('Generic');
+  type Generic<T> = { foo: T };
+  const Generic = <T>(param: DiKey<T>): DiKey<Generic<T>> => DiKey.combine(generic, param);
+
+  const Singleton = DiKey.singleton('Singleton', () => 'singleton');
+
+  const b = new B();
+  const container = new DiContainer()
+    .provide(B, b)
+    .provide(Generic(A), {
+      foo: 'Generic A',
+    })
+    .provide(Generic(B), { foo: b });
+
+  expect(container.get(B)).toBe(b);
+  expect(container.get(Generic(A)).foo).toBe('Generic A');
+  expect(container.get(Generic(B)).foo).toBe(b);
+  expect(container.get(Singleton)).toBe('singleton');
+});

package/src/di-container.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { DiKey } from './di-key';
+
+export class DiContainer {
+  #entries = new Map<DiKey<any>, any>();
+
+  get<T>(key: DiKey<T>): T {
+    const value = this.#entries.get(key);
+    if (value === undefined) {
+      const factory = DiKey.getSingletonFactory(key);
+      if (factory != null) {
+        const singletonValue = factory();
+        this.#entries.set(key, singletonValue);
+        return singletonValue;
+      }
+
+      throw new Error(`Key ${DiKey.stringify(key)} does not exist in the container`);
+    }
+
+    return value;
+  }
+
+  provide<T>(key: DiKey<T>, value: T): this {
+    if (DiKey.getSingletonFactory(key) != null) {
+      throw new Error(`Key ${DiKey.stringify(key)} is a singleton key and cannot be provided directly`);
+    }
+    if (this.#entries.has(key)) {
+      throw new Error(`Key ${DiKey.stringify(key)} already exists in the container`);
+    }
+
+    this.#entries.set(key, value);
+
+    return this;
+  }
+
+  delete<T>(key: DiKey<T>): this {
+    this.#entries.delete(key);
+
+    return this;
+  }
+}

package/src/di-key.test.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { test } from 'vitest';
+
+import { DiKey } from './di-key';
+
+test('DiKey', ({ expect }) => {
+  const A = DiKey.define('A');
+  class B {}
+
+  // eslint-disable-next-line no-self-compare
+  expect(DiKey.combine(A, B) === DiKey.combine(A, B)).toBeTruthy();
+  expect(DiKey.stringify(DiKey.combine(A, B))).toEqual('A<B>');
+});

package/src/di-key.ts

@@ -0,0 +1,111 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { inspect } from 'node:util';
+
+import { defaultMap } from './map';
+
+export const symbolSingleton = Symbol('singleton');
+
+export type SingletonFactory<T> = () => T;
+
+export class SymbolDiKey<T> {
+  symbol: symbol;
+
+  constructor(name: string) {
+    this.symbol = Symbol(name);
+  }
+
+  public [symbolSingleton]?: SingletonFactory<T> = undefined;
+
+  toString() {
+    return String(this.symbol).slice(7, -1);
+  }
+
+  [inspect.custom]() {
+    return this.toString();
+  }
+}
+
+export type ConstructorDiKey<T> = {
+  new (...args: any[]): T;
+
+  [symbolSingleton]?: SingletonFactory<T>;
+};
+
+/**
+ * Represents a key for an entry in a DI container.
+ * Class constructors can be used as is.
+ * Multiple keys can be combined into a single key to represent parameterized types.
+ * Composite keys maintain referential equality.
+ * Keys can optionally have a singleton factory attached to them.
+ */
+export type DiKey<T> =
+  | {
+      new (...args: any[]): T;
+    }
+  | SymbolDiKey<T>;
+
+export const DiKey = new (class DiKeyConstructor {
+  /**
+   * Needed to ensure referential equality of combined keys.
+   *
+   * This is a multilevel map of maps, where the maps are also used as keys.
+   *
+   * Good luck :)
+   */
+  // TODO(dmaretskyi): Disable private members lowering for dev env.
+  // TODO(dmaretskyi): Could be a weak map after a NodeJS upgrade.
+  #combinedRegistry = new WeakMap();
+
+  define<T>(name: string): DiKey<T> {
+    return new SymbolDiKey(name);
+  }
+
+  singleton<T>(name: string, factory: SingletonFactory<T>): DiKey<T> {
+    const id = new SymbolDiKey(name);
+    id[symbolSingleton] = factory;
+    return id as any;
+  }
+
+  stringify(id: DiKey<any>): string {
+    switch (typeof id) {
+      case 'symbol':
+        return String(id).slice(7, -1);
+      case 'function':
+        return id.name;
+      default:
+        return String(id);
+    }
+  }
+
+  /**
+   * Create composite keys to represent parameterized types.
+   *
+   * @example DiKey.combine(A, B, C) => "A<B, C>"
+   *
+   * Maintains referential equality: `DiKey.combine(A, B) === DiKey.combine(A, B)`
+   */
+  combine(...ids: DiKey<any>[]) {
+    const map = this.#lookupCombined(this.#combinedRegistry, ids);
+    return defaultMap(this.#combinedRegistry, map, () => this.#combinedDescription(ids));
+  }
+
+  getSingletonFactory<T>(id: DiKey<T>): SingletonFactory<T> | undefined {
+    return (id as any)[symbolSingleton];
+  }
+
+  #lookupCombined(map: WeakMap<any, any>, [first, ...rest]: DiKey<any>[]): WeakMap<any, any> {
+    const value = defaultMap(map, first, () => new Map());
+    if (rest.length > 0) {
+      return this.#lookupCombined(value, rest);
+    } else {
+      return value;
+    }
+  }
+
+  #combinedDescription([first, ...rest]: DiKey<any>[]) {
+    return `${this.stringify(first)}<${rest.map(this.stringify).join(', ')}>`;
+  }
+})();

package/src/json.ts

@@ -9,7 +9,10 @@ import { PublicKey } from '@dxos/keys';
 import { humanize } from './human-hash';
 import { arrayToBuffer } from './uint8array';
 
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
 const MAX_DEPTH = 5;
+const LOG_MAX_DEPTH = 7;
 
 /**
  * JSON.stringify replacer.
@@ -73,6 +76,46 @@ export const jsonify = (value: any, depth = 0, visitedObjects = new WeakSet<any>
   }
 };
 
+/**
+ * Recursively converts an object into a JSON-compatible object appropriate for logging.
+ */
+
+// TODO(nf): use util.inspect/[util.inspect.custom] instead?
+export const jsonlogify = (value: any, depth = 0, visitedObjects = new WeakSet<any>()): any => {
+  if (depth > LOG_MAX_DEPTH) {
+    return null;
+  } else if (typeof value === 'function') {
+    return null;
+  } else if (typeof value === 'object' && value !== null) {
+    if (visitedObjects.has(value)) {
+      return null;
+    }
+    visitedObjects.add(value);
+
+    try {
+      if (value instanceof Uint8Array) {
+        return arrayToBuffer(value).toString('hex');
+      } else if (Array.isArray(value)) {
+        return value.map((x) => jsonlogify(x, depth + 1, visitedObjects));
+      } else if (typeof value.toJSONL === 'function') {
+        return value.toJSONL();
+      } else if (typeof value.toJSON === 'function') {
+        return value.toJSON();
+      } else {
+        const res: any = {};
+        for (const key of Object.keys(value)) {
+          res[key] = jsonlogify(value[key], depth + 1, visitedObjects);
+        }
+        return res;
+      }
+    } finally {
+      visitedObjects.delete(value);
+    }
+  } else {
+    return value;
+  }
+};
+
 export type JsonKeyOptions = {
   truncate?: boolean;
   humanize?: boolean;

package/src/map.ts

@@ -2,10 +2,15 @@
 // Copyright 2020 DXOS.org
 //
 
+interface IMap<K, V> {
+  get(key: K): V | undefined;
+  set(key: K, value: V): this;
+}
+
 /**
  * Get or set map value.
  */
-export const defaultMap = <K, V>(map: Map<K, V>, key: K, def: V | (() => V)) => {
+export const defaultMap = <K, V>(map: IMap<K, V>, key: K, def: V | (() => V)) => {
   let value = map.get(key);
   if (value === undefined) {
     value = typeof def === 'function' ? (def as () => V)() : def;