@olane/o-node 0.7.13-alpha.0 → 0.7.13-alpha.1

package/dist/test/helpers/simple-node-builder.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SimpleNodeBuilder - Fluent API for creating single-node tests
+ *
+ * @example
+ * ```typescript
+ * const node = await new SimpleNodeBuilder(MyTool)
+ *   .withConfig({ apiKey: 'test' })
+ *   .withAddress('o://test-tool')
+ *   .build(env);
+ * ```
+ */
+import type { oNodeTool } from '../../src/o-node.tool.js';
+import type { oNodeAddress } from '../../src/router/o-node.address.js';
+import type { TestEnvironment } from './test-environment.js';
+import type { TestNodeConfig } from './test-environment.js';
+export declare class SimpleNodeBuilder<T extends oNodeTool = any> {
+    private nodeClass;
+    private config;
+    private autoStart;
+    constructor(NodeClass: new (config: any) => T);
+    /**
+     * Set node configuration
+     */
+    withConfig(config: TestNodeConfig): this;
+    /**
+     * Set node address
+     */
+    withAddress(address: oNodeAddress): this;
+    /**
+     * Set node description
+     */
+    withDescription(description: string): this;
+    /**
+     * Set leader reference
+     */
+    withLeader(leader: oNodeAddress | null): this;
+    /**
+     * Set parent reference
+     */
+    withParent(parent: oNodeAddress | null): this;
+    /**
+     * Control automatic start
+     */
+    withAutoStart(autoStart: boolean): this;
+    /**
+     * Build and create the node
+     */
+    build(env: TestEnvironment): Promise<T>;
+}
+//# sourceMappingURL=simple-node-builder.d.ts.map

package/dist/test/helpers/simple-node-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-node-builder.d.ts","sourceRoot":"","sources":["../../../test/helpers/simple-node-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,qBAAa,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,GAAG;IACtD,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAiB;gBAEtB,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,KAAK,CAAC;IAI7C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKxC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKxC;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK1C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAK7C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAK7C;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAKvC;;OAEG;IACG,KAAK,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC;CAG9C"}

package/dist/test/helpers/simple-node-builder.js

@@ -0,0 +1,66 @@
+/**
+ * SimpleNodeBuilder - Fluent API for creating single-node tests
+ *
+ * @example
+ * ```typescript
+ * const node = await new SimpleNodeBuilder(MyTool)
+ *   .withConfig({ apiKey: 'test' })
+ *   .withAddress('o://test-tool')
+ *   .build(env);
+ * ```
+ */
+export class SimpleNodeBuilder {
+    constructor(NodeClass) {
+        this.config = {};
+        this.autoStart = true;
+        this.nodeClass = NodeClass;
+    }
+    /**
+     * Set node configuration
+     */
+    withConfig(config) {
+        this.config = { ...this.config, ...config };
+        return this;
+    }
+    /**
+     * Set node address
+     */
+    withAddress(address) {
+        this.config.address = address;
+        return this;
+    }
+    /**
+     * Set node description
+     */
+    withDescription(description) {
+        this.config.description = description;
+        return this;
+    }
+    /**
+     * Set leader reference
+     */
+    withLeader(leader) {
+        this.config.leader = leader;
+        return this;
+    }
+    /**
+     * Set parent reference
+     */
+    withParent(parent) {
+        this.config.parent = parent;
+        return this;
+    }
+    /**
+     * Control automatic start
+     */
+    withAutoStart(autoStart) {
+        this.autoStart = autoStart;
+        return this;
+    }
+    /**
+     * Build and create the node
+     */
+    async build(env) {
+        return await env.createNode(this.nodeClass, this.config, this.autoStart);
+    }
+}

package/dist/test/helpers/test-environment.d.ts

@@ -0,0 +1,140 @@
+/**
+ * TestEnvironment - Core test setup and lifecycle management for O-Network nodes
+ *
+ * Provides automatic cleanup, node factories, and common test utilities
+ * to eliminate boilerplate in O-Network package tests.
+ *
+ * @example
+ * ```typescript
+ * describe('MyTool', () => {
+ *   const env = new TestEnvironment();
+ *
+ *   afterEach(async () => {
+ *     await env.cleanup();
+ *   });
+ *
+ *   it('should work', async () => {
+ *     const node = await env.createNode(MyTool);
+ *     expect(node.state).to.equal(NodeState.RUNNING);
+ *   });
+ * });
+ * ```
+ */
+import type { oNode } from '../../src/o-node.js';
+import type { oNodeAddress } from '../../src/router/o-node.address.js';
+/**
+ * Node configuration for test environment
+ */
+export interface TestNodeConfig {
+    address?: oNodeAddress;
+    leader?: oNodeAddress | null;
+    parent?: oNodeAddress | null;
+    description?: string;
+    [key: string]: any;
+}
+/**
+ * Core test environment class for O-Network testing
+ *
+ * Manages node lifecycle, automatic cleanup, and provides
+ * factory methods for common test scenarios.
+ *
+ * Note: This class does not include leader-related utilities to avoid
+ * circular dependencies with @olane/o-leader. Packages that need leader
+ * functionality should implement their own test utilities.
+ */
+export declare class TestEnvironment {
+    private nodes;
+    private cleanupCallbacks;
+    /**
+     * Create a node
+     *
+     * @param NodeClass - Node class to instantiate
+     * @param config - Node configuration
+     * @param autoStart - Whether to start node automatically (default: true)
+     * @returns Node instance
+     *
+     * @example
+     * ```typescript
+     * const node = await env.createNode(MyTool, {
+     *   address: new oNodeAddress('o://test')
+     * });
+     * ```
+     */
+    createNode<T extends oNode>(NodeClass: new (config: any) => T, config?: TestNodeConfig, autoStart?: boolean): Promise<T>;
+    /**
+     * Track a node for automatic cleanup
+     *
+     * @param node - Node instance to track
+     *
+     * @example
+     * ```typescript
+     * const node = new MyNode({});
+     * env.track(node);
+     * await node.start();
+     * ```
+     */
+    track(node: oNode): void;
+    /**
+     * Register a cleanup callback
+     *
+     * Useful for cleaning up external resources (databases, files, etc.)
+     *
+     * @param callback - Async cleanup function
+     *
+     * @example
+     * ```typescript
+     * const db = await createTestDB();
+     * env.onCleanup(async () => {
+     *   await db.close();
+     * });
+     * ```
+     */
+    onCleanup(callback: () => Promise<void>): void;
+    /**
+     * Stop all tracked nodes and execute cleanup callbacks
+     *
+     * Stops nodes in reverse order (children before parents)
+     * Call this in afterEach hooks.
+     *
+     * @example
+     * ```typescript
+     * afterEach(async () => {
+     *   await env.cleanup();
+     * });
+     * ```
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get all tracked nodes
+     *
+     * @returns Array of tracked node instances
+     */
+    getNodes(): oNode[];
+    /**
+     * Get count of tracked nodes
+     *
+     * @returns Number of tracked nodes
+     */
+    getNodeCount(): number;
+    /**
+     * Check if all tracked nodes are stopped
+     *
+     * @returns True if all nodes are stopped
+     */
+    allNodesStopped(): boolean;
+    /**
+     * Wait for a condition to be true
+     *
+     * @param condition - Function that returns true when condition is met
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @param intervalMs - Check interval in milliseconds (default: 100)
+     * @returns Promise that resolves when condition is met or rejects on timeout
+     *
+     * @example
+     * ```typescript
+     * await env.waitFor(() => tool.isReady, 10000);
+     * ```
+     */
+    waitFor(condition: () => boolean, timeoutMs?: number, intervalMs?: number): Promise<void>;
+}
+//# sourceMappingURL=test-environment.d.ts.map

package/dist/test/helpers/test-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-environment.d.ts","sourceRoot":"","sources":["../../../test/helpers/test-environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,gBAAgB,CAAkC;IAE1D;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,CAAC,SAAS,KAAK,EAC9B,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,KAAK,CAAC,EACjC,MAAM,GAAE,cAAmB,EAC3B,SAAS,GAAE,OAAc,GACxB,OAAO,CAAC,CAAC,CAAC;IAgBb;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IAIxB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI9C;;;;;;;;;;;;OAYG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B9B;;;;OAIG;IACH,QAAQ,IAAI,KAAK,EAAE;IAInB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;OAIG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;;;;;;;;;OAYG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,OAAO,EACxB,SAAS,GAAE,MAAa,EACxB,UAAU,GAAE,MAAY,GACvB,OAAO,CAAC,IAAI,CAAC;CAUjB"}

package/dist/test/helpers/test-environment.js

@@ -0,0 +1,184 @@
+/**
+ * TestEnvironment - Core test setup and lifecycle management for O-Network nodes
+ *
+ * Provides automatic cleanup, node factories, and common test utilities
+ * to eliminate boilerplate in O-Network package tests.
+ *
+ * @example
+ * ```typescript
+ * describe('MyTool', () => {
+ *   const env = new TestEnvironment();
+ *
+ *   afterEach(async () => {
+ *     await env.cleanup();
+ *   });
+ *
+ *   it('should work', async () => {
+ *     const node = await env.createNode(MyTool);
+ *     expect(node.state).to.equal(NodeState.RUNNING);
+ *   });
+ * });
+ * ```
+ */
+import { NodeState } from '@olane/o-core';
+/**
+ * Core test environment class for O-Network testing
+ *
+ * Manages node lifecycle, automatic cleanup, and provides
+ * factory methods for common test scenarios.
+ *
+ * Note: This class does not include leader-related utilities to avoid
+ * circular dependencies with @olane/o-leader. Packages that need leader
+ * functionality should implement their own test utilities.
+ */
+export class TestEnvironment {
+    constructor() {
+        this.nodes = [];
+        this.cleanupCallbacks = [];
+    }
+    /**
+     * Create a node
+     *
+     * @param NodeClass - Node class to instantiate
+     * @param config - Node configuration
+     * @param autoStart - Whether to start node automatically (default: true)
+     * @returns Node instance
+     *
+     * @example
+     * ```typescript
+     * const node = await env.createNode(MyTool, {
+     *   address: new oNodeAddress('o://test')
+     * });
+     * ```
+     */
+    async createNode(NodeClass, config = {}, autoStart = true) {
+        const node = new NodeClass({
+            parent: null,
+            leader: null,
+            ...config,
+        });
+        this.track(node);
+        if (autoStart) {
+            await node.start();
+        }
+        return node;
+    }
+    /**
+     * Track a node for automatic cleanup
+     *
+     * @param node - Node instance to track
+     *
+     * @example
+     * ```typescript
+     * const node = new MyNode({});
+     * env.track(node);
+     * await node.start();
+     * ```
+     */
+    track(node) {
+        this.nodes.push(node);
+    }
+    /**
+     * Register a cleanup callback
+     *
+     * Useful for cleaning up external resources (databases, files, etc.)
+     *
+     * @param callback - Async cleanup function
+     *
+     * @example
+     * ```typescript
+     * const db = await createTestDB();
+     * env.onCleanup(async () => {
+     *   await db.close();
+     * });
+     * ```
+     */
+    onCleanup(callback) {
+        this.cleanupCallbacks.push(callback);
+    }
+    /**
+     * Stop all tracked nodes and execute cleanup callbacks
+     *
+     * Stops nodes in reverse order (children before parents)
+     * Call this in afterEach hooks.
+     *
+     * @example
+     * ```typescript
+     * afterEach(async () => {
+     *   await env.cleanup();
+     * });
+     * ```
+     */
+    async cleanup() {
+        // Stop nodes in reverse order (children first)
+        const nodesToStop = [...this.nodes].reverse();
+        for (const node of nodesToStop) {
+            try {
+                if (node.state === NodeState.RUNNING) {
+                    await node.stop();
+                }
+            }
+            catch (error) {
+                console.error('Error stopping node:', error);
+            }
+        }
+        // Execute cleanup callbacks
+        for (const callback of this.cleanupCallbacks) {
+            try {
+                await callback();
+            }
+            catch (error) {
+                console.error('Error in cleanup callback:', error);
+            }
+        }
+        // Clear tracking
+        this.nodes = [];
+        this.cleanupCallbacks = [];
+    }
+    /**
+     * Get all tracked nodes
+     *
+     * @returns Array of tracked node instances
+     */
+    getNodes() {
+        return [...this.nodes];
+    }
+    /**
+     * Get count of tracked nodes
+     *
+     * @returns Number of tracked nodes
+     */
+    getNodeCount() {
+        return this.nodes.length;
+    }
+    /**
+     * Check if all tracked nodes are stopped
+     *
+     * @returns True if all nodes are stopped
+     */
+    allNodesStopped() {
+        return this.nodes.every(node => node.state === NodeState.STOPPED);
+    }
+    /**
+     * Wait for a condition to be true
+     *
+     * @param condition - Function that returns true when condition is met
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @param intervalMs - Check interval in milliseconds (default: 100)
+     * @returns Promise that resolves when condition is met or rejects on timeout
+     *
+     * @example
+     * ```typescript
+     * await env.waitFor(() => tool.isReady, 10000);
+     * ```
+     */
+    async waitFor(condition, timeoutMs = 5000, intervalMs = 100) {
+        const startTime = Date.now();
+        while (!condition()) {
+            if (Date.now() - startTime > timeoutMs) {
+                throw new Error(`Timeout waiting for condition after ${timeoutMs}ms`);
+            }
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+        }
+    }
+}

package/dist/test/helpers/test-node.tool.d.ts

@@ -1,14 +1,45 @@
 import { oNodeTool } from '../../src/o-node.tool.js';
+import { oNodeToolConfig } from '../../src/interfaces/o-node.tool-config.js';
+import { Libp2pConfig } from '@olane/o-config';
 /**
  * Test-only extension of oNodeTool that adds streaming test methods.
  * This class should only be used in test files and is not part of the production code.
+ *
+ * Compatible with TestEnvironment for automatic cleanup and lifecycle management.
+ *
+ * @example
+ * ```typescript
+ * import { TestEnvironment } from './helpers/index.js';
+ * import { TestNodeTool } from './helpers/test-node.tool.js';
+ *
+ * const env = new TestEnvironment();
+ * const tool = new TestNodeTool({ address: new oNodeAddress('o://test') });
+ * await tool.start();
+ * // TestEnvironment will handle cleanup automatically
+ * ```
  */
 export declare class TestNodeTool extends oNodeTool {
+    constructor(config: oNodeToolConfig);
+    configure(): Promise<Libp2pConfig>;
     /**
      * Test method that emits chunks for 10 seconds at 100ms intervals.
      * Used for testing streaming functionality across hierarchical networks.
      *
+     * This method demonstrates streaming responses with AsyncGenerator,
+     * which is a common pattern for real-time data processing and long-running operations.
+     *
      * @returns AsyncGenerator that yields 100 chunks over 10 seconds
+     * @example
+     * ```typescript
+     * const response = await tool.use(tool.address, {
+     *   method: 'test_stream',
+     *   params: {}
+     * });
+     *
+     * for await (const chunk of response) {
+     *   console.log(`Received chunk ${chunk.chunk}`);
+     * }
+     * ```
      */
     _tool_test_stream(): AsyncGenerator<any>;
 }

package/dist/test/helpers/test-node.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-node.tool.d.ts","sourceRoot":"","sources":["../../../test/helpers/test-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,SAAS;IACzC;;;;;OAKG;IACI,iBAAiB,IAAI,cAAc,CAAC,GAAG,CAAC;CAehD"}
+{"version":3,"file":"test-node.tool.d.ts","sourceRoot":"","sources":["../../../test/helpers/test-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,MAAM,EAAE,eAAe;IAO7B,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;IAcxC;;;;;;;;;;;;;;;;;;;OAmBG;IACI,iBAAiB,IAAI,cAAc,CAAC,GAAG,CAAC;CAiBhD"}

package/dist/test/helpers/test-node.tool.js

@@ -1,14 +1,61 @@
 import { oNodeTool } from '../../src/o-node.tool.js';
+import { oNodeAddress } from '../../src/index.js';
 /**
  * Test-only extension of oNodeTool that adds streaming test methods.
  * This class should only be used in test files and is not part of the production code.
+ *
+ * Compatible with TestEnvironment for automatic cleanup and lifecycle management.
+ *
+ * @example
+ * ```typescript
+ * import { TestEnvironment } from './helpers/index.js';
+ * import { TestNodeTool } from './helpers/test-node.tool.js';
+ *
+ * const env = new TestEnvironment();
+ * const tool = new TestNodeTool({ address: new oNodeAddress('o://test') });
+ * await tool.start();
+ * // TestEnvironment will handle cleanup automatically
+ * ```
  */
 export class TestNodeTool extends oNodeTool {
+    constructor(config) {
+        super({
+            ...config,
+            address: new oNodeAddress('o://test')
+        });
+    }
+    async configure() {
+        const config = await super.configure();
+        config.connectionGater = {
+            denyDialPeer: (peerId) => {
+                return false;
+            },
+            // who can call us?
+            denyInboundEncryptedConnection: (peerId, maConn) => {
+                return false;
+            },
+        };
+        return config;
+    }
     /**
      * Test method that emits chunks for 10 seconds at 100ms intervals.
      * Used for testing streaming functionality across hierarchical networks.
      *
+     * This method demonstrates streaming responses with AsyncGenerator,
+     * which is a common pattern for real-time data processing and long-running operations.
+     *
      * @returns AsyncGenerator that yields 100 chunks over 10 seconds
+     * @example
+     * ```typescript
+     * const response = await tool.use(tool.address, {
+     *   method: 'test_stream',
+     *   params: {}
+     * });
+     *
+     * for await (const chunk of response) {
+     *   console.log(`Received chunk ${chunk.chunk}`);
+     * }
+     * ```
      */
     async *_tool_test_stream() {
         const totalDuration = 10000; // 10 seconds
@@ -17,9 +64,11 @@ export class TestNodeTool extends oNodeTool {
         for (let i = 0; i < totalChunks; i++) {
             yield {
                 chunk: i + 1,
+                total: totalChunks,
                 timestamp: new Date().toISOString(),
                 nodeAddress: this.address.toString(),
                 message: `Chunk ${i + 1} of ${totalChunks}`,
+                progress: ((i + 1) / totalChunks) * 100,
             };
             await new Promise((resolve) => setTimeout(resolve, intervalMs));
         }

package/dist/test/network-communication.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=network-communication.spec.d.ts.map

package/dist/test/network-communication.spec.d.ts.map

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