@layerzerolabs/dfs 0.2.68 → 0.2.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/dfs",
-  "version": "0.2.68",
+  "version": "0.2.70",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -13,14 +13,17 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
   "dependencies": {
-    "@layerzerolabs/dependency-graph": "0.2.68"
+    "@layerzerolabs/dependency-graph": "0.2.70"
   },
   "devDependencies": {
     "tsup": "^8.4.0",
     "vitest": "^3.2.3",
-    "@layerzerolabs/tsup-configuration": "0.2.68",
-    "@layerzerolabs/typescript-configuration": "0.2.68"
+    "@layerzerolabs/typescript-configuration": "0.2.70",
+    "@layerzerolabs/tsup-configuration": "0.2.70"
   },
   "publishConfig": {
     "access": "public",

package/.turbo/turbo-build.log

@@ -1,19 +0,0 @@
- WARN  Issue while reading "/home/runner/work/monorepo-internal/monorepo-internal/.npmrc". Failed to replace env in config: ${NPM_TOKEN}
-
-> @layerzerolabs/dfs@0.0.2 build /home/runner/work/monorepo-internal/monorepo-internal/packages/framework/dfs
-> tsup
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/monorepo-internal/monorepo-internal/packages/framework/dfs/tsup.config.ts
-CLI Target: ES2023
-CLI Cleaning output folder
-CJS Build start
-ESM Build start
-CJS dist/index.cjs     3.43 KB
-CJS dist/index.cjs.map 11.79 KB
-CJS ⚡️ Build success in 103ms
-ESM dist/index.js     3.42 KB
-ESM dist/index.js.map 11.78 KB
-ESM ⚡️ Build success in 104ms

package/.turbo/turbo-lint.log

@@ -1,8 +0,0 @@
-
-> @layerzerolabs/dfs@0.0.2 lint /home/runner/work/monorepo-internal/monorepo-internal/packages/framework/dfs
-> eslint . --max-warnings 0 || (eslint . --fix --max-warnings 0 && false)
-
-(node:66152) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/runner/work/monorepo-internal/monorepo-internal/eslint.config.js?mtime=1775777605148 is not specified and it doesn't parse as CommonJS.
-Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
-To eliminate this warning, add "type": "module" to /home/runner/work/monorepo-internal/monorepo-internal/package.json.
-(Use `node --trace-warnings ...` to show where the warning was created)

package/.turbo/turbo-test.log

@@ -1,19 +0,0 @@
-
-> @layerzerolabs/dfs@0.0.2 test /home/runner/work/monorepo-internal/monorepo-internal/packages/framework/dfs
-> vitest --run --pass-with-no-tests --typecheck
-
-Testing types with tsc and vue-tsc is an experimental feature.
-Breaking changes might not follow SemVer, please pin Vitest's version when using it.
-
- RUN  v3.2.4 /home/runner/work/monorepo-internal/monorepo-internal/packages/framework/dfs
-
- ✓ test/dfs.test.ts (7 tests) 675ms
-   ✓ DI Depth-first-search > The handlers for each of a node's dependencies should be completed before that node  304ms
-   ✓ DI Ancestry - randomized DAG property > random DAGs: ancestry includes all ancestors and distances are non-decreasing  350ms
-
- Test Files  1 passed (1)
-      Tests  7 passed (7)
-Type Errors  no errors
-   Start at  23:35:39
-   Duration  1.12s (transform 98ms, setup 0ms, collect 88ms, tests 675ms, environment 0ms, prepare 107ms)
-

package/src/index.ts

@@ -1,162 +0,0 @@
-import type { DependencyNode } from '@layerzerolabs/dependency-graph';
-
-/**
- * <!-- anchor:Registrar -->
- * A registrar is a simple interface for an object that provides the ability to traverse the dependency graph.
- * It is implicit in this definition that the registrar should also *register* values adhering to the schemata
- * of the graph.
- */
-export interface Registrar<ReturnType> {
-    traverseDependencies: (rootNode: DependencyNode) => Promise<ReturnType>;
-}
-export type NodeHandlerFunction = (
-    node: DependencyNode,
-    ancestry: DependencyNode[],
-) => Promise<{ key: string; value: any }>;
-export type NodePreHandlerFunction = (node: DependencyNode) => DependencyNode;
-
-// Map of ancestor node -> minimal hop distance
-type AncestorDistanceByNode = Map<DependencyNode, number>;
-// Index from node name -> its ancestor distance map
-type AncestryDistanceIndex = Map<string, AncestorDistanceByNode>;
-
-/**
- * In-place merge of minimal ancestry distances.
- *
- * childDistances holds minimal distances from the child to each ancestor (keyed by DependencyNode).
- * For every entry in parentDistances, we update the child's map with (parentDist + 1),
- * keeping the minimal value if the ancestor already exists.
- */
-const mergeAncestorDistances = (
-    parentDistances: AncestorDistanceByNode,
-    childDistances: AncestorDistanceByNode,
-) => {
-    for (const [ancestor, parentDist] of parentDistances) {
-        const candidate = parentDist + 1;
-        const current = childDistances.get(ancestor) || Infinity;
-        childDistances.set(ancestor, Math.min(current, candidate));
-    }
-};
-
-/**
- * Builds a minimal ancestry distance index for all nodes reachable from the root.
- *
- * Returns a Map: node.name -> Map<DependencyNode, distance> where distance is the minimal hop count
- * from the node to that ancestor. We perform a Kahn-style BFS over the DAG, and for each edge
- * curNode -> dep we merge curNode's minimal distances into the dependency with +1 hop and take the minimum.
- */
-const buildAncestryDistanceIndex = (
-    node: DependencyNode,
-    prehandler: NodePreHandlerFunction,
-): AncestryDistanceIndex => {
-    const ancestryDistanceIndex: AncestryDistanceIndex = new Map();
-    const inDegreeByNodeName = new Map<string, number>();
-
-    // If A depends on B and C, B depends on C, we initialize with:
-    // ancestryDistanceIndex: { A: Map(), B: Map(), C: Map() }
-    // inDegreeByNodeName: { B: 1, C: 2 }
-    const initializeMaps = (cur: DependencyNode) => {
-        ancestryDistanceIndex.set(cur.name, new Map());
-        for (const dep of Object.values(cur.dependencies)) {
-            const handledDep = prehandler(dep);
-            const inDegree = inDegreeByNodeName.get(handledDep.name) || 0;
-            inDegreeByNodeName.set(handledDep.name, inDegree + 1);
-            if (!ancestryDistanceIndex.has(handledDep.name)) initializeMaps(handledDep);
-        }
-    };
-
-    const handled = prehandler(node);
-
-    initializeMaps(handled);
-
-    // Kahn-style topological BFS accumulating minimal distance ancestors
-    let queue = [handled];
-    while (queue.length > 0) {
-        const curNode = queue.shift()!;
-        // Include self with distance 0, then extend with the already known minimal distances
-        const currentMinimalDistances: AncestorDistanceByNode = new Map([
-            [curNode, 0],
-            ...ancestryDistanceIndex.get(curNode.name)!,
-        ]);
-        // Add the new processable dependencies to the queue, update their state.
-        for (const dep of Object.values(curNode.dependencies)) {
-            const handledDep = prehandler(dep);
-            const inDegree = inDegreeByNodeName.get(handledDep.name)!;
-            // We are the last edge missing in the graph for this dependency -> we can process it after us.
-            if (inDegree === 1) {
-                queue.push(handledDep);
-            }
-            // Reduce the in-degree of the dependency -> it basically means that this edge got removed from the graph.
-            inDegreeByNodeName.set(handledDep.name, inDegree - 1);
-
-            // Merge curNode's minimal distances (+1 hop) into the dependency's minimal distances
-            const childDistances = ancestryDistanceIndex.get(handledDep.name)!;
-            mergeAncestorDistances(currentMinimalDistances, childDistances);
-        }
-    }
-
-    for (const [nodeName, inDegree] of inDegreeByNodeName) {
-        if (inDegree !== 0) {
-            throw new Error(
-                `node ${nodeName} has in-degree ${inDegree}, this indicates a cycle in the graph containing the node`,
-            );
-        }
-    }
-
-    return ancestryDistanceIndex;
-};
-
-/**
- * Performs a depth-first-search on a tree of dependency nodes, and returns a function
- * that will call the handler for each node in the tree, ordered s.t. the handler of N
- * will be called only after the handlers of dependencies(N) have been called.
- * The node's ancestors are sorted by non-decreasing minimal distance.
- * The resolver function will only call the handler once for each unique definition node.
- * The resolver function returns an object whose keys are the keys defined
- * by each of the handlers, and whose values are objects whose keys are the names
- * of the nodes resolved and whose values are the values defined by the handlers.
- * @param node the root node of the tree
- * @param handler a function that accepts a node and registers it
- * @param prehandler a function that accepts a node and returns a node. Will be used to pre-process the graph
- * @returns a resolver function
- */
-export const dfs = <ReturnTypes>(
-    node: DependencyNode,
-    handler: NodeHandlerFunction,
-    prehandler: NodePreHandlerFunction = (node) => node,
-    _returns: ReturnTypes = {} as any,
-): (() => Promise<ReturnTypes>) => {
-    const ancestryDistanceIndex = buildAncestryDistanceIndex(node, prehandler);
-
-    // Maintains Map<node.name, Promise<void>> -> the promise to resolve the node, for all nodes.
-    const nodeResolverPromises = new Map<string, Promise<void>>();
-    const resolveNode = async (node: DependencyNode) => {
-        const prehandledNode = prehandler(node);
-        // first wait for all its children
-        const childrenPromises = [];
-        for (const dependencyValue of Object.values(prehandledNode.dependencies)) {
-            // Grab the cached promise or create it, we want to have only 1 handler promise for each node.
-            if (!nodeResolverPromises.has(dependencyValue.name)) {
-                nodeResolverPromises.set(dependencyValue.name, resolveNode(dependencyValue));
-            }
-            childrenPromises.push(nodeResolverPromises.get(dependencyValue.name)!);
-        }
-        await Promise.all(childrenPromises);
-
-        // Then, you can process yourself. Build ancestry sorted by non-decreasing minimal distance.
-        const minimalDistances = ancestryDistanceIndex.get(prehandledNode.name)!;
-        const sortedAncestors = Array.from(minimalDistances.entries()).sort((a, b) => a[1] - b[1]);
-        const regRes = await handler(
-            prehandledNode,
-            sortedAncestors.map(([node, _]) => node),
-        );
-        if (regRes) {
-            ((_returns as any)[regRes.key] ??= {})[prehandledNode.name] = regRes.value;
-        }
-    };
-
-    return async () => {
-        await resolveNode(node);
-        return _returns;
-    };
-};

package/test/dfs.test.ts

@@ -1,330 +0,0 @@
-import { describe, expect, test } from 'vitest';
-
-import { Dependencies, DependencyNode } from '@layerzerolabs/dependency-graph';
-
-import { dfs } from '../src';
-
-const SimpleClassA = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends DependencyNode<Name, _Dependencies> {};
-
-const mySimpleClassA = new SimpleClassA({ name: 'MySimpleClassA' });
-
-const SimpleClassB = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends DependencyNode<Name, _Dependencies> {};
-
-const mySimpleClassB = new SimpleClassB({
-    name: 'MySimpleClassB',
-    dependencies: { mySimpleClassA },
-});
-
-const SimpleClassC = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends DependencyNode<Name, _Dependencies> {};
-
-const mySimpleClassC = new SimpleClassC({
-    name: 'MySimpleClassC',
-    dependencies: { mySimpleClassB },
-});
-
-const SimpleClassD = class<
-    Name extends string,
-    _Dependencies extends Dependencies,
-> extends DependencyNode<Name, _Dependencies> {};
-
-const mySimpleClassD = new SimpleClassD({
-    name: 'MySimpleClassD',
-    dependencies: { mySimpleClassC, mySimpleClassB, mySimpleClassA },
-});
-
-describe('DI Depth-first-search', () => {
-    test('Initial DFS and resolution should happen separately and return the expected structure', async () => {
-        let wasCalled = false;
-        const resolve = dfs(mySimpleClassA, async () => {
-            wasCalled = true;
-            return { key: 'nodeKey', value: 'nodeValue' };
-        });
-
-        //when called, dfs should traverse the tree and collect all the nodes,
-        //returning a function that will call the handler on each node
-        expect(resolve).toBeTypeOf('function');
-
-        //it shouldn't call the handler until the resolve function is called
-        expect(wasCalled).toBe(false);
-        const res = await resolve();
-        //the resolve method should await all of the handlers
-        expect(wasCalled).toBe(true);
-        //the resolve method should return an object whose keys are the keys defined
-        //by each of the handlers, and whose values are objects whose keys are the names
-        //of the nodes resolved and whose values are the values defined by the handlers
-        expect(res).toStrictEqual({ nodeKey: { MySimpleClassA: 'nodeValue' } });
-    });
-
-    test(`The handlers for each of a node's dependencies should be completed before that node`, async () => {
-        let order: string[] = [];
-
-        const handler: Parameters<typeof dfs>[1] = async (node) => {
-            const handlerRet = { key: '_', value: '_' };
-            if (node.name === mySimpleClassA.name) {
-                order.push('A');
-                await new Promise((res) => setTimeout(res, 50));
-                return handlerRet;
-            } else if (node.name === mySimpleClassB.name) {
-                order.push('B');
-                await new Promise((res) => setTimeout(res, 100));
-                return handlerRet;
-            } else if (node.name === mySimpleClassC.name) {
-                order.push('C');
-                return handlerRet;
-            }
-            throw new Error(`Unexpected node ${JSON.stringify(node)}`);
-        };
-
-        await dfs(mySimpleClassB, handler)();
-        expect(order).toStrictEqual(['A', 'B']);
-
-        order = [];
-
-        await dfs(mySimpleClassC, handler)();
-        expect(order).toStrictEqual(['A', 'B', 'C']);
-    });
-
-    test('The handler should be called only once for each unique node', async () => {
-        let count = 0;
-
-        const handler: Parameters<typeof dfs>[1] = async (_node) => {
-            count++;
-            return { key: '_', value: '_' };
-        };
-
-        await dfs(mySimpleClassB, handler)();
-        expect(count).toBe(2);
-
-        count = 0;
-
-        await dfs(mySimpleClassD, handler)();
-        expect(count).toBe(4);
-    });
-});
-
-describe('DI Ancestry - inclusion and distance order', () => {
-    test('C -> B -> A', async () => {
-        const { ancestry } = await dfs<{ ancestry: Record<string, string[]> }>(
-            mySimpleClassC,
-            async (_node, ancestry) => {
-                return { key: 'ancestry', value: ancestry.map((n) => n.name) };
-            },
-        )();
-
-        expect(ancestry.MySimpleClassC).toStrictEqual([]);
-        expect(ancestry.MySimpleClassB).toStrictEqual(['MySimpleClassC']);
-        expect(ancestry.MySimpleClassA).toStrictEqual(['MySimpleClassB', 'MySimpleClassC']);
-    });
-
-    test('D -> (C, B, A) with C -> B -> A', async () => {
-        const { ancestry } = await dfs<{ ancestry: Record<string, string[]> }>(
-            mySimpleClassD,
-            async (_node, ancestry) => {
-                return { key: 'ancestry', value: ancestry.map((n) => n.name) };
-            },
-        )();
-
-        // D is the root
-        expect(ancestry.MySimpleClassD).toStrictEqual([]);
-
-        // C has only D above it
-        expect(ancestry.MySimpleClassC).toStrictEqual(['MySimpleClassD']);
-
-        // B has both C and D at distance 1 (order between them is not asserted)
-        expect(new Set(ancestry.MySimpleClassB)).toStrictEqual(
-            new Set(['MySimpleClassC', 'MySimpleClassD']),
-        );
-        expect(ancestry.MySimpleClassB.length).toBe(2);
-
-        // A must include B and D (distance 1, order between them not asserted), then C (distance 2)
-        expect(new Set(ancestry.MySimpleClassA.slice(0, 2))).toStrictEqual(
-            new Set(['MySimpleClassB', 'MySimpleClassD']),
-        );
-        expect(ancestry.MySimpleClassA[2]).toBe('MySimpleClassC');
-    });
-
-    test('ancestry matches expected distance layers', async () => {
-        const { ancestry } = await dfs<{ ancestry: Record<string, string[]> }>(
-            mySimpleClassD,
-            async (_node, ancestry) => {
-                return { key: 'ancestry', value: ancestry.map((n) => n.name) };
-            },
-        )();
-
-        const expectedLayers: Record<string, string[][]> = {
-            MySimpleClassD: [],
-            MySimpleClassC: [['MySimpleClassD']],
-            MySimpleClassB: [['MySimpleClassC', 'MySimpleClassD']],
-            MySimpleClassA: [['MySimpleClassB', 'MySimpleClassD'], ['MySimpleClassC']],
-        };
-
-        for (const [nodeName, layers] of Object.entries(expectedLayers)) {
-            const actual = ancestry[nodeName];
-            let idx = 0;
-            for (const layer of layers) {
-                const segment = actual.slice(idx, idx + layer.length);
-                expect(new Set(segment)).toStrictEqual(new Set(layer));
-                idx += layer.length;
-            }
-            expect(idx).toBe(actual.length);
-        }
-    });
-});
-
-describe('DI Ancestry - randomized DAG property', () => {
-    const GNode = class<
-        Name extends string,
-        _Dependencies extends Dependencies,
-    > extends DependencyNode<Name, _Dependencies> {};
-
-    const makeRng = (seed: number) => {
-        let state = seed >>> 0;
-        return () => {
-            state = (state * 1664525 + 1013904223) >>> 0; // LCG
-            return state / 2 ** 32;
-        };
-    };
-
-    const buildRandomDag = (
-        numNodes: number,
-        edgeProbability: number,
-        seed: number,
-    ): DependencyNode<any, any>[] => {
-        const rng = makeRng(seed);
-        const nodes: DependencyNode<any, any>[] = [];
-        for (let i = 0; i < numNodes; i++) {
-            const deps: Record<string, DependencyNode<any, any>> = {};
-            for (let j = 0; j < i; j++) {
-                if (rng() < edgeProbability) {
-                    deps[`d${j}`] = nodes[j];
-                }
-            }
-            if (i > 0 && Object.keys(deps).length === 0) {
-                const j = Math.floor(rng() * i);
-                deps[`d${j}`] = nodes[j];
-            }
-            nodes.push(new GNode({ name: `N${i}`, dependencies: deps }));
-        }
-        return nodes;
-    };
-
-    const collectReachable = (root: DependencyNode<any, any>) => {
-        const map = new Map<string, DependencyNode<any, any>>();
-        const queue: DependencyNode<any, any>[] = [root];
-        while (queue.length > 0) {
-            const cur = queue.shift()!;
-            if (map.has(cur.name)) continue;
-            map.set(cur.name, cur);
-            for (const dep of Object.values(cur.dependencies) as DependencyNode<any, any>[]) {
-                queue.push(dep);
-            }
-        }
-        return map;
-    };
-
-    const buildDependentsIndex = (nodes: Map<string, DependencyNode<any, any>>) => {
-        const dependentsIndex = new Map<string, Set<string>>();
-        for (const node of nodes.values()) dependentsIndex.set(node.name, new Set());
-        for (const node of nodes.values()) {
-            for (const dep of Object.values(node.dependencies) as DependencyNode<any, any>[]) {
-                dependentsIndex.get(dep.name)!.add(node.name);
-            }
-        }
-        return dependentsIndex;
-    };
-
-    const computeDependentDistances = (
-        start: string,
-        dependentsIndex: Map<string, Set<string>>,
-    ) => {
-        const distances = new Map<string, number>();
-        const queue: Array<{ name: string; dist: number }> = [{ name: start, dist: 0 }];
-        distances.set(start, 0);
-        while (queue.length > 0) {
-            const { name, dist } = queue.shift()!;
-            for (const next of dependentsIndex.get(name) || [])
-                if (!distances.has(next)) {
-                    distances.set(next, dist + 1);
-                    queue.push({ name: next, dist: dist + 1 });
-                }
-        }
-        distances.delete(start);
-        return distances;
-    };
-
-    test('random DAGs: ancestry includes all ancestors and distances are non-decreasing', async () => {
-        // increase/play with these values if you're making changes :D
-        const iterations = 2;
-        const numNodes = 200;
-
-        // Edge probability p: node i has E[in-degree(i)] ≈ p*i (edges only to earlier nodes).
-        // Average per node ≈ p*(n-1)/2. For n=500 and p=0.25, avg ≈ 62; the last node ≈ 125.
-        const edgeProbability = 0.25;
-
-        // Sampling probability: fraction of reachable nodes validated.
-        // E[sampled] ≈ reachableCount * sampleProbability (≈100 if ~500 reachable).
-        const sampleProbability = 0.2;
-
-        const seeds = Array.from({ length: iterations }, () =>
-            Math.floor(Math.random() * 0x7fffffff),
-        );
-
-        for (const seed of seeds) {
-            try {
-                const nodes = buildRandomDag(numNodes, edgeProbability, seed);
-                const root = nodes[nodes.length - 1];
-                const res = await dfs<{ ancestry: Record<string, string[]> }>(
-                    root,
-                    async (_node, ancestry) => {
-                        return { key: 'ancestry', value: ancestry.map((n) => n.name) };
-                    },
-                )();
-                const reachable = collectReachable(root);
-                const dependentsIndex = buildDependentsIndex(reachable);
-
-                // dfs should traverse exactly the reachable set
-                expect(new Set(Object.keys(res.ancestry))).toStrictEqual(new Set(reachable.keys()));
-
-                const sample: { nodeName: string; list: string[] }[] = [];
-                for (const [nodeName, list] of Object.entries(res.ancestry)) {
-                    if (Math.random() < sampleProbability) {
-                        sample.push({ nodeName, list });
-                    }
-                }
-
-                for (const { nodeName, list } of sample) {
-                    // No self in ancestry
-                    expect(list.includes(nodeName)).toBe(false);
-                    // Inclusion: exactly the set of reachable dependents
-                    const distMap = computeDependentDistances(nodeName, dependentsIndex);
-                    expect(new Set(list)).toStrictEqual(new Set(distMap.keys()));
-
-                    // No duplicates
-                    expect(new Set(list).size).toBe(list.length);
-
-                    // Distance non-decreasing
-                    for (let i = 1; i < list.length; i++) {
-                        const prev = distMap.get(list[i - 1])!;
-                        const cur = distMap.get(list[i])!;
-                        expect(prev <= cur).toBe(true);
-                    }
-                }
-            } catch (err: any) {
-                if (err && typeof err === 'object' && 'message' in err) {
-                    err.message = `failed random dag test with seed ${seed}: ${err.message}`;
-                    throw err;
-                }
-                throw new Error(`failed random dag test with seed ${seed}: ${String(err)}`);
-            }
-        }
-    });
-});

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,
-}));