@layerzerolabs/base-definitions 0.2.68 → 0.2.69

package/src/lzyringe.ts

@@ -1,71 +0,0 @@
-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<T>(key: string, value: T extends Promise<any> ? never : T) {
-        this.throwIfRegistered(key);
-        this.store[key] = { type: 'value', value };
-    }
-
-    /** Registers a promise value that will be resolved literally by resolve()
-     * @throws if already registered
-     */
-    public registerPromise(key: string, value: Promise<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

@@ -1,348 +0,0 @@
-import type { Dependencies } from '@layerzerolabs/dependency-graph';
-import { DependencyNode } from '@layerzerolabs/dependency-graph';
-import type { Registrar } from '@layerzerolabs/dfs';
-import { dfs } from '@layerzerolabs/dfs';
-export type { Registrar };
-
-type NodeClass = new (...args: any[]) => DependencyNode;
-type AbstractNodeClass = abstract new (...args: any[]) => DependencyNode;
-
-/**
- * <!-- anchor:RegistrarBuilder -->
- * 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, ancestry: DependencyNode[]) => Promise<any>;
-
-    protected nodeHandlers: Record<
-        string,
-        {
-            fn: (node: DependencyNode, ancestry: DependencyNode[]) => Promise<any>;
-            identifier: string;
-        }
-    > = {};
-
-    protected classHandlers: {
-        nodeClass: AbstractNodeClass;
-        identifier: string;
-        fn: (node: DependencyNode, ancestry: DependencyNode[]) => Promise<any>;
-    }[] = [];
-
-    protected classAliases: {
-        fromNodeClass: AbstractNodeClass;
-        getToNode: (from: DependencyNode) => DependencyNode;
-    }[] = [];
-
-    protected nodeAliases: Record<string, (node: DependencyNode) => DependencyNode> = {};
-
-    protected getEntrypoints: (
-        node: DependencyNode,
-    ) => DependencyNode[] | Promise<DependencyNode[]> = (node) => [node];
-
-    constructor() {
-        this.defaultHandler = async (node: DependencyNode) => {
-            throw new Error(
-                `This registrar does not provide a handler for the dependency type used by ${JSON.stringify(node)}`,
-            );
-        };
-    }
-
-    public addNodeHandler<
-        Node extends DependencyNode,
-        Function extends (node: Node, ancestry: DependencyNode[]) => Promise<any>,
-    >(node: DependencyNode, identifier: string, fn: Function) {
-        if (this.nodeHandlers[node.name]) {
-            throw new Error(
-                `Cannot define a node handler for an identifier that already has a handler: ${node.name}`,
-            );
-        }
-        this.nodeHandlers[node.name] = {
-            fn: fn as unknown as (node: DependencyNode, ancestry: DependencyNode[]) => Promise<any>,
-            identifier,
-        };
-        return this as RegistrarBuilder<
-            _ReturnTypes & {
-                ['nodeHandlers']: { [nodeName: string]: Awaited<ReturnType<Function>> };
-            }
-        >;
-    }
-
-    /**
-     * Returns the class handler identifier that would be used for a given node,
-     * or undefined if no class handler matches.
-     */
-    public getClassIdentifierForNode(node: DependencyNode): string | undefined {
-        for (const { nodeClass, identifier } of this.classHandlers) {
-            if (node instanceof nodeClass) {
-                return identifier;
-            }
-        }
-        return undefined;
-    }
-
-    /**
-     * Add a function fn to be called on all nodes of class
-     * @param nodeClass
-     * @param identifier
-     * @param fn
-     */
-    public addClassHandler<
-        Identifier extends string,
-        _NodeClass extends NodeClass,
-        Function extends (node: InstanceType<_NodeClass>, ancestry: DependencyNode[]) => 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
-            if (handler.nodeClass === nodeClass) {
-                this.classHandlers[i] = {
-                    nodeClass,
-                    identifier,
-                    fn: fn as unknown as (node: DependencyNode) => Promise<any>,
-                };
-
-                return this as RegistrarBuilder<
-                    _ReturnTypes & {
-                        [_K in Identifier]: { [nodeName: string]: Awaited<ReturnType<Function>> };
-                    }
-                >;
-            }
-            //check if the new handler has an ordering requirement against an existing handler
-            //(we always want to use more specific handlers if they exist)
-            // eslint-disable-next-line no-prototype-builtins
-            if (handler.nodeClass.prototype.isPrototypeOf(nodeClass.prototype)) {
-                this.classHandlers.splice(i, 0, {
-                    nodeClass,
-                    identifier,
-                    fn: fn as unknown as (node: DependencyNode) => Promise<any>,
-                });
-
-                return this as RegistrarBuilder<
-                    _ReturnTypes & {
-                        [_K in Identifier]: { [nodeName: string]: Awaited<ReturnType<Function>> };
-                    }
-                >;
-            }
-            i++;
-        }
-
-        this.classHandlers.push({
-            nodeClass,
-            identifier,
-            fn: fn as unknown as (node: DependencyNode) => Promise<any>,
-        });
-
-        return this as RegistrarBuilder<
-            _ReturnTypes & {
-                [_K in Identifier]: { [nodeName: string]: Awaited<ReturnType<Function>> };
-            }
-        >;
-    }
-
-    /**
-     * 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,
-    ) {
-        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) => DependencyNode,
-                };
-
-                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) => DependencyNode,
-                });
-
-                return this;
-            }
-            i++;
-        }
-
-        this.classAliases.push({
-            fromNodeClass,
-            getToNode: getToNode as unknown as (from: DependencyNode) => DependencyNode,
-        });
-
-        return this;
-    }
-
-    /**
-     * Alias a specific named node, such that when encountered in the tree,
-     * it will be transformed to a different node before processing.
-     * The transformed node's dependencies will be traversed instead.
-     * This is useful for short-circuiting dependency traversal for specific nodes.
-     *
-     * @param nodeName name of the node to alias
-     * @param getToNode method that returns the transformed node
-     */
-    public addNodeAlias(
-        node: DependencyNode,
-        getToNode: (fromNodeInstance: DependencyNode) => DependencyNode,
-    ) {
-        this.nodeAliases[node.name] = getToNode;
-        return this;
-    }
-
-    /**
-     * Set a custom entrypoint getter function. By default, the entrypoint getter
-     * returns the node passed in as the sole entrypoint.
-     */
-    public setEntrypointsGetter(
-        fn: (node: DependencyNode) => DependencyNode[] | Promise<DependencyNode[]>,
-    ) {
-        this.getEntrypoints = fn;
-        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, ancestry: DependencyNode[]) => any) {
-        this.defaultHandler = fn;
-        return this;
-    }
-
-    public build(): Registrar<_ReturnTypes> {
-        const mergedNodePrehandler = (node: DependencyNode) => {
-            // Check node aliases first (more specific)
-            const nodeAlias = this.nodeAliases[node.name];
-            if (nodeAlias) {
-                return nodeAlias(node);
-            }
-
-            // Then check class aliases
-            for (const { fromNodeClass, getToNode: toNode } of this.classAliases) {
-                if (node instanceof fromNodeClass) {
-                    return toNode(node);
-                }
-            }
-            return node;
-        };
-
-        const mergedNodeHandler = async (node: DependencyNode, ancestry: DependencyNode[]) => {
-            if (node.name === '_virtualEntrypoint') {
-                return {
-                    key: node.name,
-                    value: undefined,
-                };
-            }
-
-            const nodeHandler = this.nodeHandlers[node.name];
-            if (nodeHandler) {
-                return {
-                    key: nodeHandler.identifier ?? node.name,
-                    value: await nodeHandler.fn(node, ancestry),
-                };
-            }
-
-            for (const { nodeClass, identifier, fn } of this.classHandlers) {
-                if (node instanceof nodeClass) {
-                    return {
-                        key: identifier,
-                        value: await fn(node, ancestry),
-                    };
-                }
-            }
-
-            return {
-                key: 'default',
-                value: await this.defaultHandler(node, ancestry),
-            };
-        };
-        return {
-            traverseDependencies: async (node: DependencyNode) => {
-                const entrypoints = await this.getEntrypoints(node);
-                if (entrypoints.length === 1)
-                    return await dfs<_ReturnTypes>(node, mergedNodeHandler, mergedNodePrehandler)();
-
-                const dependencies = entrypoints.reduce((acc, cur) => {
-                    acc[cur.name] = cur;
-                    return acc;
-                }, {} as Dependencies);
-
-                class VirtualNode extends DependencyNode {}
-
-                const virtualEntrypoint = new VirtualNode({
-                    name: '_virtualEntrypoint',
-                    dependencies,
-                });
-
-                return await dfs<_ReturnTypes>(
-                    virtualEntrypoint,
-                    mergedNodeHandler,
-                    mergedNodePrehandler,
-                )();
-            },
-        };
-    }
-}
-
-export const multiplexOrderedRegistrars = <
-    const T extends [name: string, registrar: Registrar<{}>][],
->(
-    ...registrars: T
-) => {
-    const multiplexRegistrar: Registrar<{
-        [K in Extract<keyof T, number> as T[K] extends readonly [infer Name extends string, any]
-            ? Name
-            : never]: T[K] extends readonly [any, Registrar<infer Ret>] ? Ret : never;
-    }> = {
-        traverseDependencies: async (
-            ...params: Parameters<Registrar<any>['traverseDependencies']>
-        ) => {
-            const acc: Record<string, any> = {};
-            for (const [name, registrar] of registrars) {
-                const result = await registrar.traverseDependencies(...params);
-                acc[name] = result;
-            }
-
-            return acc;
-        },
-    } as any;
-
-    return multiplexRegistrar;
-};

package/src/utils.ts

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

package/test/registrarBuilder.test.ts

@@ -1,175 +0,0 @@
-import { describe, expect, test } from 'vitest';
-
-import { Dependencies, DependencyNode } from '@layerzerolabs/dependency-graph';
-
-import { RegistrarBuilder } from '../src/registrarBuilder';
-
-const SimpleClassA = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends DependencyNode<Name, _Dependencies> {};
-
-const mySimpleClassA1 = new SimpleClassA({ name: 'MySimpleClassA' });
-const mySimpleClassA2 = new SimpleClassA({ name: 'MySimpleClassA' });
-
-const ExtendsClassA = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends SimpleClassA<Name, _Dependencies> {};
-
-const myExtendsClassA1 = new ExtendsClassA({ name: 'MyExtendsClassA' });
-
-const ExtendsExtendsClassA = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends ExtendsClassA<Name, _Dependencies> {};
-
-const myExtendsExtendsClassA1 = new ExtendsExtendsClassA({ name: 'MyExtendsExtendsClassA' });
-
-const SimpleClassB = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends DependencyNode<Name, _Dependencies> {};
-
-const mySimpleClassB1 = new SimpleClassB({ name: 'MySimpleClassB' });
-const mySimpleClassB2 = new SimpleClassB({
-    name: 'MySimpleClassB',
-    dependencies: { mySimpleClassA1 },
-});
-
-const SimpleClassC = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends DependencyNode<Name, _Dependencies> {};
-
-const mySimpleClassC1 = new SimpleClassC({ name: 'MySimpleClassC' });
-const mySimpleClassC2 = new SimpleClassC({
-    name: 'MySimpleClassC',
-    dependencies: { mySimpleClassB2, mySimpleClassA1 },
-});
-
-describe('Registrar builder', () => {
-    test('The registered callbacks should be called in order, such that dependencies are called before dependants', async () => {
-        let order: string[] = [];
-        const builder = new RegistrarBuilder()
-            .addClassHandler(SimpleClassA, 'handler', () => order.push('A'))
-            .addClassHandler(SimpleClassB, 'handler', () => order.push('B'))
-            .addDefault(() => {})
-            .build();
-
-        await builder.traverseDependencies(mySimpleClassB1);
-        expect(order).toStrictEqual(['B']);
-        order = [];
-        await builder.traverseDependencies(mySimpleClassA1);
-        expect(order).toStrictEqual(['A']);
-        order = [];
-        await builder.traverseDependencies(mySimpleClassB2);
-        expect(order).toStrictEqual(['A', 'B']);
-    });
-    test('The registered callback should be called only once for each unique definition', async () => {
-        let calledCount = 0;
-        let defaultCount = 0;
-        const builder = new RegistrarBuilder()
-            .addClassHandler(SimpleClassA, 'handler', () => calledCount++)
-            .addDefault(() => defaultCount++)
-            .build();
-
-        await builder.traverseDependencies(mySimpleClassC1);
-        expect(calledCount).toBe(0);
-        await builder.traverseDependencies(mySimpleClassC2);
-        expect(calledCount).toBe(1);
-        await builder.traverseDependencies(mySimpleClassA1);
-        await builder.traverseDependencies(mySimpleClassA2);
-        expect(calledCount).toBe(3);
-        expect(defaultCount).toBe(3);
-        await builder.traverseDependencies(mySimpleClassC1);
-        expect(calledCount).toBe(3);
-        expect(defaultCount).toBe(4);
-    });
-    test('The most specific applicable handler should always be called, regardless of definition order', async () => {
-        let calledCount: number[] = [0, 0, 0];
-        const builder = new RegistrarBuilder()
-            .addClassHandler(ExtendsClassA, 'handler', () => calledCount[1]++)
-            .addClassHandler(SimpleClassA, 'handler', () => calledCount[0]++)
-            .addClassHandler(ExtendsExtendsClassA, 'handler', () => calledCount[2]++)
-            .addDefault(() => {})
-            .build();
-
-        await builder.traverseDependencies(myExtendsClassA1);
-        expect(calledCount).toStrictEqual([0, 1, 0]);
-        await builder.traverseDependencies(mySimpleClassA1);
-        expect(calledCount).toStrictEqual([1, 1, 0]);
-        await builder.traverseDependencies(myExtendsExtendsClassA1);
-        await builder.traverseDependencies(myExtendsExtendsClassA1);
-        expect(calledCount).toStrictEqual([1, 1, 2]);
-    });
-    test('The traverseDependencies method should return an object with the keys defined in the handlers, and the returns of those handlers', async () => {
-        let inc = 0;
-        const builder = new RegistrarBuilder()
-            .addClassHandler(SimpleClassA, 'simpleA', () => inc++)
-            .addClassHandler(SimpleClassB, 'simpleB', () => inc++)
-            .addDefault(() => {})
-            .build();
-
-        const ret = await builder.traverseDependencies(mySimpleClassA1);
-        expect(ret).toStrictEqual({ simpleA: { MySimpleClassA: 0 } });
-        const ret2 = await builder.traverseDependencies(mySimpleClassB2);
-        expect(ret2).toStrictEqual({
-            simpleA: { MySimpleClassA: 1 },
-            simpleB: { MySimpleClassB: 2 },
-        });
-    });
-});
-
-describe('Node handlers', () => {
-    test('Should take priority over class handlers', async () => {
-        let classHandlerCalled = false;
-        let namedHandlerCalled = false;
-
-        const builder = new RegistrarBuilder()
-            .addClassHandler(SimpleClassA, 'simpleA', async () => {
-                classHandlerCalled = true;
-                return 'from-class';
-            })
-            .addNodeHandler(mySimpleClassA1, 'MySimpleClassA', async () => {
-                namedHandlerCalled = true;
-                return 'from-named';
-            })
-            .build();
-
-        await builder.traverseDependencies(mySimpleClassA1);
-
-        expect(namedHandlerCalled).toBe(true);
-        expect(classHandlerCalled).toBe(false);
-    });
-
-    test('Should be invoked with correct arguments and return values', async () => {
-        let receivedNode: DependencyNode | undefined;
-        let receivedAncestry: DependencyNode[] | undefined;
-
-        const builder = new RegistrarBuilder()
-            .addNodeHandler(mySimpleClassA1, 'MySimpleClassA', async (node, ancestry) => {
-                receivedNode = node;
-                receivedAncestry = ancestry;
-                return 'named-result';
-            })
-            .build();
-
-        const result = await builder.traverseDependencies(mySimpleClassA1);
-
-        expect(receivedNode).toBe(mySimpleClassA1);
-        expect(receivedAncestry).toStrictEqual([]);
-        // Result is grouped by handler identifier (node name for named handlers)
-        expect(result).toStrictEqual({ MySimpleClassA: { MySimpleClassA: 'named-result' } });
-    });
-
-    test('Registering duplicate node handlers should throw', () => {
-        expect(() => {
-            new RegistrarBuilder()
-                .addNodeHandler(mySimpleClassA1, 'MySimpleClassA', async () => 'first')
-                .addNodeHandler(mySimpleClassA1, 'MySimpleClassA', async () => 'second');
-        }).toThrow(
-            'Cannot define a node handler for an identifier that already has a handler: MySimpleClassA',
-        );
-    });
-});

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-    "extends": "@layerzerolabs/typescript-configuration/tsconfig.base.json",
-    "compilerOptions": {
-        "rootDir": "./src",
-        "outDir": "./dist",
-        "strictPropertyInitialization": false,
-        "noUnusedLocals": false,
-        "noUnusedParameters": false,
-        "jsx": "react-jsx"
-    },
-    "exclude": [
-        "node_modules",
-        "**/__mocks__/*",
-        "**/__tests__/*",
-        "**/*.spec.ts",
-        "**/*.test.ts",
-        "dist"
-    ],
-    "include": ["src/**/*"]
-}

package/tsup.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from 'tsup';
-
-import { createPackageTsupConfig } from '@layerzerolabs/tsup-configuration';
-
-export default defineConfig(({ watch }) => ({
-    ...createPackageTsupConfig(),
-    clean: !watch,
-}));