@layerzerolabs/base-definitions 0.0.2 → 0.0.5

package/dist/utils.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var B2JM5RKU_cjs = require('./B2JM5RKU.cjs');
+require('./2W6KYHJN.cjs');
+require('./YJF4D23A.cjs');
+
+
+
+Object.defineProperty(exports, "extractSchemaFromFactory", {
+  enumerable: true,
+  get: function () { return B2JM5RKU_cjs.extractSchemaFromFactory; }
+});
+//# sourceMappingURL=utils.cjs.map
+//# sourceMappingURL=utils.cjs.map

package/dist/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"utils.cjs"}

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import type z from 'zod/v4';
+import { type FactoryDefinition } from './definitions';
+export declare const extractSchemaFromFactory: <Dim extends z.ZodObject>(factoryDefinition: FactoryDefinition<any, Dim, any, any>, dimension: z.infer<Dim>) => z.ZodObject;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B,OAAO,EAAE,KAAK,iBAAiB,EAAuB,MAAM,eAAe,CAAC;AAE5E,eAAO,MAAM,wBAAwB,GAAI,GAAG,SAAS,CAAC,CAAC,SAAS,EAC5D,mBAAmB,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACxD,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,KACxB,CAAC,CAAC,SAcJ,CAAC"}

package/dist/utils.js

@@ -0,0 +1,5 @@
+export { extractSchemaFromFactory } from './ISLTTWBQ.js';
+import './PLNCBQCW.js';
+import './VUOMXK5T.js';
+//# sourceMappingURL=utils.js.map
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"utils.js"}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@layerzerolabs/base-definitions",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "license": "MIT",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "reflect-metadata": "^0.2.2",
     "zod": "^3.23.8",
-    "@layerzerolabs/dependency-graph": "0.0.2",
-    "@layerzerolabs/dfs": "0.0.2"
+    "@layerzerolabs/dfs": "0.0.5",
+    "@layerzerolabs/dependency-graph": "0.0.5",
+    "@layerzerolabs/common-utils": "0.0.5"
   },
   "publishConfig": {
     "access": "restricted",
@@ -16,10 +16,10 @@
   },
   "devDependencies": {
     "tsup": "^8.4.0",
-    "@layerzerolabs/tsup-configuration": "0.0.1",
-    "@layerzerolabs/typescript-configuration": "0.0.0",
-    "@layerzerolabs/typescript-utils": "0.0.0",
-    "@layerzerolabs/eslint-configuration": "0.0.0"
+    "vitest": "^3.2.3",
+    "@layerzerolabs/typescript-configuration": "0.0.5",
+    "@layerzerolabs/tsup-configuration": "0.0.5",
+    "@layerzerolabs/typescript-utils": "0.0.5"
   },
   "module": "./dist/index.js",
   "exports": {
@@ -35,7 +35,7 @@
     "build": "tsup",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix --max-warnings 0",
-    "typecheck": "tsc --noEmit",
+    "test": "vitest --run --pass-with-no-tests",
     "dev": "tsup --watch"
   }
 }

package/src/definitions.ts

@@ -1,66 +1,109 @@
-import type { z } from 'zod';
+import type { z } from 'zod/v4';
 
+import type { FunctionPointer } from '@layerzerolabs/common-utils';
 import type { Dependencies } from '@layerzerolabs/dependency-graph';
 import { DependencyNode } from '@layerzerolabs/dependency-graph';
-import type { IntersectionValueOf, RemoveNever } from '@layerzerolabs/typescript-utils';
+import type {
+    AdvancedRecord,
+    AdvancedRecordLookup,
+    Merge,
+    MethodOf,
+    RemoveNever,
+    UnionToIntersection,
+} from '@layerzerolabs/typescript-utils';
+
+export type DimensionToSchemaMap<DimConstraint extends object = object> = {
+    byDimension?: AdvancedRecord<DimConstraint, z.ZodType>;
+    base: z.ZodType;
+};
+
+export type GetModelFromSchema<DMap extends DimensionToSchemaMap, Dim> =
+    AdvancedRecordLookup<DMap['byDimension'], Dim> extends never
+        ? z.infer<DMap['base']>
+        : Merge<z.infer<DMap['base']>, z.infer<AdvancedRecordLookup<DMap['byDimension'], Dim>>>;
+
+type GetImplFunctionWithConditionalOptionalDim<Dim, Return> = {} extends Dim
+    ? (dim?: Dim) => Return
+    : (dim: Dim) => Return;
+
+type GetImplOverloads<
+    Dim extends z.ZodObject<any>,
+    DMap extends DimensionToSchemaMap<z.infer<Dim>>,
+> = UnionToIntersection<
+    | {
+          [I in keyof DMap['byDimension']]: DMap['byDimension'][I] extends readonly [infer K, any]
+              ? {
+                    getImpl: GetImplFunctionWithConditionalOptionalDim<
+                        K,
+                        GetModelFromSchema<DMap, K>
+                    >;
+                }
+              : never;
+      }[keyof DMap['byDimension']]
+    | { getImpl: GetImplFunctionWithConditionalOptionalDim<z.infer<Dim>, z.infer<DMap['base']>> }
+>;
 
 export type Factory<
     _Dependencies extends Dependencies,
     Dim extends z.ZodObject<any>,
-    GetImplMetadata extends {
-        getModel: (dim: z.infer<Dim>) => any;
-    },
-> = { getImpl: (dim: z.infer<Dim>) => ReturnType<GetImplMetadata['getModel']> };
+    DMap extends DimensionToSchemaMap<z.infer<Dim>>,
+> = { implKeys: string[] } & GetImplOverloads<Dim, DMap>;
 
 export type GetFactory<
     _Dependencies extends Dependencies,
     Dim extends z.ZodObject<any>,
-    GetImplMetadata extends { getModel: (dim: z.infer<Dim>) => any },
-> = () =>
-    | Factory<_Dependencies, Dim, GetImplMetadata>
-    | Promise<Factory<_Dependencies, Dim, GetImplMetadata>>;
-
-export type GetFactoryForDefinition<Definition> = GetFactory<
-    Definition extends FactoryDefinition<any, any, any, infer D> ? D : never,
-    Definition extends FactoryDefinition<any, infer D, any, any> ? D : never,
-    Definition extends FactoryDefinition<any, any, infer G, any> ? G : never
->;
+    DMap extends DimensionToSchemaMap<z.infer<Dim>>,
+> = () => Factory<_Dependencies, Dim, DMap> | Promise<Factory<_Dependencies, Dim, DMap>>;
 
+/**
+ * Factory definitions are a type of dependency node that shall be resolved to a *factory*.
+ * A factory is an object that provides a getImpl method which accepts some parameters *dim*,
+ * and returns some object getImplMetadata.getModel(dim).
+ * That is, a factory definition is given by the set of parameters it uses to get its implementations,
+ * and a function defining the schema it will return for each set of parameters.
+ * @param name inherited from {@link DependencyNode}
+ * @param dependencies inherited from {@link DependencyNode}
+ * @param dimensions a Zod schema for the parameters this factory operates on.
+ * @param dimensionToSchemaMap A map from dimension objects to the Zod schema for the implementation.
+ * @param getFactory a method that should return an object with a getImpl method that returns
+ * entities adhering to the schema for the corresponding getModel call
+ */
 export class FactoryDefinition<
     Name extends string,
     Dim extends z.ZodObject<any>,
-    GetImplMetadata extends {
-        getKey: (dim: z.infer<Dim>) => any;
-        getModel: (dim: z.infer<Dim>) => any;
-        revLookup: {
-            [key: string]: {
-                dim: z.infer<Dim>;
-                model: any;
-            };
-        };
-    },
+    DMap extends DimensionToSchemaMap<z.infer<Dim>>,
     _Dependencies extends Dependencies,
 > extends DependencyNode<Name, _Dependencies> {
     public readonly dimensions: Dim;
-    public readonly getImplMetadata: GetImplMetadata;
-    public readonly getFactory: GetFactory<_Dependencies, Dim, GetImplMetadata>;
+    public readonly dimensionToSchemaMap: DMap;
+    public readonly getFactory: GetFactory<_Dependencies, Dim, DMap>;
     constructor({
         dimensions,
-        getImplMetadata,
+        dimensionToSchemaMap,
         getFactory,
         ...args
     }: {
         dimensions: Dim;
-        getImplMetadata: GetImplMetadata;
-        getFactory: GetFactory<_Dependencies, Dim, GetImplMetadata>;
+        dimensionToSchemaMap: DMap;
+        getFactory: GetFactory<_Dependencies, Dim, DMap>;
     } & ConstructorParameters<typeof DependencyNode<Name, _Dependencies>>[0]) {
         super(args);
         this.dimensions = dimensions;
-        this.getImplMetadata = getImplMetadata;
+        this.dimensionToSchemaMap = dimensionToSchemaMap;
         this.getFactory = getFactory;
     }
 }
 
+/**
+ * An object definition is a dependency node that refers to some entity
+ * matching a given schema. That is, it may be resolved to any entity
+ * that adheres to the {@link schema}.
+ * The object definition is abstract, as it cannot be meaningfully resolved without
+ * additional information. For an example of an object definition, see ReflexiveObjectDefinition or ContextDefinition
+ * @param name inherited from {@link DependencyNode}
+ * @param dependencies inherited from {@link DependencyNode}
+ * @param schema a Zod schema defining the expected resolution for this definition
+ */
 export abstract class ObjectDefinition<
     Name extends string,
     Schema extends z.ZodSchema,
@@ -83,36 +126,72 @@ export type Definition<Name extends string> =
     | FactoryDefinition<Name, any, any, any>
     | ObjectDefinition<Name, any, any>;
 
-export type DefinitionResolution<Definition extends DependencyNode<any, any>> =
+/**
+ * Infers the expected type of a definition once it has been resolved
+ */
+export type ResolvedDefinition<Definition extends DependencyNode<any, any>> =
     Definition extends ObjectDefinition<any, infer Schema, any>
         ? z.infer<Schema>
-        : Definition extends FactoryDefinition<any, any, infer GetImpl, any>
-          ? {
-                getImpl: GetImpl['getModel'];
-            }
-          : never;
-
-export type DefinitionsResolution<Deps extends Dependencies> = {
-    [Key in keyof Deps]: DefinitionResolution<Deps[Key]>;
+        : Definition extends FactoryDefinition<any, infer Dim, infer DMap, any>
+          ? Factory<Definition['dependencies'], Dim, DMap>
+          : Definition extends FactoryDefinition<any, any, any, any>
+            ? Factory<
+                  Definition['dependencies'],
+                  Definition['dimensions'],
+                  Definition['dimensionToSchemaMap']
+              >
+            : unknown;
+
+/**
+ * Given a record from string to definition, maps each definition T to ResolvedDefinition<T>
+ */
+export type ResolvedDefinitionMap<Deps extends Dependencies> = {
+    [Key in keyof Deps]: ResolvedDefinition<Deps[Key]>;
 };
 
-export type DefinitionImplsResolution<Definition extends DependencyNode<any, any>, Dim> =
-    Definition extends FactoryDefinition<any, infer _Dim, infer GetImpl, any>
-        ? Dim extends z.infer<_Dim>
-            ? IntersectionValueOf<{
-                  [key in keyof GetImpl['revLookup']]: Dim extends GetImpl['revLookup'][key]['dim']
-                      ? GetImpl['revLookup'][key]['model']
-                      : GetImpl['revLookup']['__base']['model'];
-              }>
-            : never
+/**
+ * For some factory definition F and some dimension D s.t. D ⊇ F.dimensions, infers the expected return type of
+ * ResolvedDefinition<F>.getImpl(D)
+ */
+export type ResolvedFactoryImplementation<Definition extends DependencyNode<any, any>, Dim> =
+    Definition extends FactoryDefinition<any, any, any, any>
+        ? GetModelFromSchema<Definition['dimensionToSchemaMap'], Dim>
         : never;
 
-export type DefinitionsImplsResolution<Deps extends Dependencies, Dim> = RemoveNever<{
-    [Key in keyof Deps]: DefinitionImplsResolution<Deps[Key], Dim>;
+/**
+ * Given a record from string to definition and some dimension D, maps each definition T to ResolvedFactoryImplementation<T, D>
+ */
+export type ResolvedFactoryImplementationMap<Deps extends Dependencies, Dim> = RemoveNever<{
+    [Key in keyof Deps]: ResolvedFactoryImplementation<Deps[Key], Dim>;
 }>;
 
-export type Context<Deps extends Dependencies, Dim> = {
-    dependencies: DefinitionsResolution<Deps>;
-    impls: DefinitionsImplsResolution<Deps, Dim>;
+type ActivityContext<_FactoryDefinition extends FactoryDefinition<any, any, any, any>, Dim> = {
+    getFunctionPointer: _FactoryDefinition extends FactoryDefinition<any, any, any, any>
+        ? <Method extends MethodOf<ResolvedFactoryImplementation<_FactoryDefinition, Dim>>>(
+              method: Method,
+          ) => FunctionPointer<Method>
+        : never;
+};
+
+/**
+ * The parameters that shall be received by a factory's implementation getter
+ */
+export type Context<_FactoryDefinition extends FactoryDefinition<any, any, any, any>, Dim> = {
+    name: _FactoryDefinition extends FactoryDefinition<infer Name, any, any, any> ? Name : never;
+    dependencies: _FactoryDefinition extends FactoryDefinition<any, any, any, infer Deps>
+        ? ResolvedDefinitionMap<Deps>
+        : never;
     dim: Dim;
+    impls: _FactoryDefinition extends FactoryDefinition<any, any, any, infer Deps>
+        ? ResolvedFactoryImplementationMap<Deps, Dim>
+        : never;
+} & ActivityContext<_FactoryDefinition, Dim>;
+
+export const serializeDimensions = (dim: object = {}) => {
+    return Object.keys(dim).length
+        ? Object.entries(dim)
+              .sort()
+              .map(([dimName, dimVal]) => `${dimName}_${dimVal}`, '')
+              .join('&')
+        : '_base';
 };

package/src/index.ts

@@ -1,2 +1,4 @@
 export * from './definitions';
+export * from './lzyringe';
 export * from './registrarBuilder';
+export * from './utils';

package/src/lzyringe.ts

@@ -0,0 +1,63 @@
+type StoreValue = {
+    type: 'value';
+    value: any;
+};
+type StoreFactory = {
+    type: 'factory';
+    value: () => any;
+};
+type StoreAny = StoreValue | StoreFactory;
+
+export class DependencyStore {
+    private store: Record<string, StoreAny | undefined> = {};
+
+    private throwIfRegistered(key: string) {
+        if (this.store[key] != null) {
+            throw new Error(`${key} is already registered`);
+        }
+    }
+
+    private throwIfUnregistered(key: string) {
+        if (this.store[key] == null) {
+            throw new Error(`${key} is not registered`);
+        }
+    }
+
+    /** Registers a value that will be resolved literally by resolve()
+     * @throws if already registered
+     */
+    public register(key: string, value: any) {
+        this.throwIfRegistered(key);
+        this.store[key] = { type: 'value', value };
+    }
+
+    /** Registers a factory function that will be called by resolve()
+     * @throws if already registered
+     */
+    public registerFactory(key: string, factory: () => any) {
+        this.throwIfRegistered(key);
+        this.store[key] = { type: 'factory', value: factory };
+    }
+
+    /** Unregisters a key
+     * @throws if not registered
+     */
+    public unregister(key: string) {
+        this.throwIfUnregistered(key);
+        this.store[key] = undefined;
+    }
+
+    /**
+     * Drops all registered values
+     */
+    public invalidate() {
+        this.store = {};
+    }
+
+    /** Resolves a key to a value */
+    public resolve(key: string) {
+        this.throwIfUnregistered(key);
+        const stored = this.store[key]!;
+        return stored.type === 'factory' ? stored.value() : stored.value;
+    }
+}

package/src/registrarBuilder.ts

@@ -3,6 +3,21 @@ import type { Registrar } from '@layerzerolabs/dfs';
 export type { Registrar };
 import { dfs } from '@layerzerolabs/dfs';
 
+type NodeClass = new (...args: any[]) => DependencyNode<any, any>;
+type AbstractNodeClass = abstract new (...args: any[]) => DependencyNode<any, any>;
+
+/**
+ * A builder class for a {@link Registrar}.
+ * Builds a registrar that switches on node class--i.e., enables defining
+ * specific registration behaviour for specific node classes.
+ * Intelligently handles inheritance, always using the most specific
+ * handler defined for any given class.
+ * The registrar built shall return an object that maps from a handler ID,
+ * to a map from node name to the return of each handler,
+ * e.g., { objectNodes: { myObjectNode: 'my handler return' }}.
+ * This can be used to extract a specific resolved value after resolving the tree,
+ * given that the handlers return the resolved nodes.
+ */
 export class RegistrarBuilder<_ReturnTypes> {
     protected defaultHandler: (node: DependencyNode<any, any>) => Promise<any>;
     constructor() {
@@ -14,11 +29,16 @@ export class RegistrarBuilder<_ReturnTypes> {
     }
 
     protected classHandlers: {
-        nodeClass: abstract new (...args: any[]) => DependencyNode<any, any>;
+        nodeClass: AbstractNodeClass;
         identifier: string;
         fn: (node: DependencyNode<any, any>) => Promise<any>;
     }[] = [];
 
+    protected classAliases: {
+        fromNodeClass: AbstractNodeClass;
+        getToNode: (from: DependencyNode<any, any>) => DependencyNode<any, any>;
+    }[] = [];
+
     /**
      * Add a function fn to be called on all nodes of class
      * @param nodeClass
@@ -27,9 +47,15 @@ export class RegistrarBuilder<_ReturnTypes> {
      */
     public addClassHandler<
         Identifier extends string,
-        NodeClass extends new (...args: any[]) => DependencyNode<any, any>,
-        Function extends (node: InstanceType<NodeClass>) => any,
-    >(nodeClass: NodeClass, identifier: Identifier, fn: Function) {
+        _NodeClass extends NodeClass,
+        Function extends (node: InstanceType<_NodeClass>) => any,
+    >(nodeClass: _NodeClass, identifier: Identifier, fn: Function) {
+        if (this.classAliases.find(({ fromNodeClass }) => fromNodeClass === nodeClass)) {
+            throw new Error(
+                `Cannot define a handler for a class that is aliased to something else. This would be pointless`,
+            );
+        }
+
         let i = 0;
         for (const handler of this.classHandlers) {
             //check if we are overriding an existing handler
@@ -78,17 +104,86 @@ export class RegistrarBuilder<_ReturnTypes> {
         >;
     }
 
+    /**
+     * Alias some class *from*, such that any node of that class in the tree will be
+     * treated as though it were some other node *to*. The *to* node is given as a
+     * function returning a class instance, so that its dependencies, name, etc can be fixed.
+     * The registrar will ignore the dependencies of the original node, and follow the alias's
+     * dependencies instead.
+     *
+     * Additionally, this method does not affect the typing of the registrar. The output type
+     * of the build() method will not reflect the alias.
+     *
+     * @param fromNodeClass alias instances of this class
+     * @param getToNode method that returns the *to* part of the alias
+     */
+    public addClassAlias<FromNodeClass extends AbstractNodeClass>(
+        fromNodeClass: FromNodeClass,
+        getToNode: (fromNodeInstance: InstanceType<FromNodeClass>) => DependencyNode<any, any>,
+    ) {
+        if (this.classHandlers.find(({ nodeClass }) => nodeClass === fromNodeClass)) {
+            throw new Error(`Cannot define an alias for a class that already has a handler`);
+        }
+
+        let i = 0;
+        for (const alias of this.classAliases) {
+            //check if we are overriding an existing alias
+            if (alias.fromNodeClass === fromNodeClass) {
+                this.classAliases[i] = {
+                    fromNodeClass,
+                    getToNode: getToNode as unknown as (
+                        from: DependencyNode<any, any>,
+                    ) => DependencyNode<any, any>,
+                };
+
+                return this;
+            }
+            //check if the new alias has an ordering requirement against an existing alias
+            //(we always want to use more specific handlers if they exist)
+            // eslint-disable-next-line no-prototype-builtins
+            if (alias.fromNodeClass.prototype.isPrototypeOf(fromNodeClass.prototype)) {
+                this.classAliases.splice(i, 0, {
+                    fromNodeClass,
+                    getToNode: getToNode as unknown as (
+                        from: DependencyNode<any, any>,
+                    ) => DependencyNode<any, any>,
+                });
+
+                return this;
+            }
+            i++;
+        }
+
+        this.classAliases.push({
+            fromNodeClass,
+            getToNode: getToNode as unknown as (
+                from: DependencyNode<any, any>,
+            ) => DependencyNode<any, any>,
+        });
+
+        return this;
+    }
+
     /**
      * Add a default function fn to be used on nodes whose types do not have handlers.
      * If this is not set, the default behaviour will be to throw
      * @param fn
      */
-    public addDefault(fn: (node: DependencyNode<any, any>) => Promise<any>) {
+    public addDefault(fn: (node: DependencyNode<any, any>) => any) {
         this.defaultHandler = fn;
         return this;
     }
 
     public build(): Registrar<_ReturnTypes> {
+        const mergedNodePrehandler = (node: DependencyNode<any, any>) => {
+            for (const { fromNodeClass, getToNode: toNode } of this.classAliases) {
+                if (node instanceof fromNodeClass) {
+                    return toNode(node);
+                }
+            }
+            return node;
+        };
+
         const mergedNodeHandler = async (node: DependencyNode<any, any>) => {
             for (const { nodeClass, identifier, fn } of this.classHandlers) {
                 if (node instanceof nodeClass) {
@@ -106,7 +201,7 @@ export class RegistrarBuilder<_ReturnTypes> {
         };
         return {
             traverseDependencies: async (node: DependencyNode<any, any>) =>
-                await dfs<any, _ReturnTypes>(node, mergedNodeHandler)(),
+                await dfs<any, _ReturnTypes>(node, mergedNodeHandler, mergedNodePrehandler)(),
         };
     }
 }

package/src/utils.ts

@@ -0,0 +1,24 @@
+import type z from 'zod/v4';
+
+import type { AdvancedRecord } from '@layerzerolabs/typescript-utils';
+
+import { type FactoryDefinition, serializeDimensions } from './definitions';
+
+export const extractSchemaFromFactory = <Dim extends z.ZodObject>(
+    factoryDefinition: FactoryDefinition<any, Dim, any, any>,
+    dimension: z.infer<Dim>,
+): z.ZodObject => {
+    const schema =
+        (factoryDefinition.dimensionToSchemaMap.byDimension &&
+            Object.values(
+                factoryDefinition.dimensionToSchemaMap.byDimension as AdvancedRecord,
+            ).find(([dim]) => serializeDimensions(dim) === serializeDimensions(dimension))?.[1]) ??
+        factoryDefinition.dimensionToSchemaMap.base;
+    if (!schema?.shape) {
+        throw new Error(
+            `Couldn't resolve the schema of factory ${factoryDefinition.name} for dim ${JSON.stringify(dimension)}`,
+        );
+    }
+
+    return schema;
+};