@olane/o-node 0.7.44 → 0.7.46

package/dist/src/connection/o-node-connection.d.ts

@@ -13,6 +13,10 @@ export declare class oNodeConnection extends oConnection {
     constructor(config: oNodeConnectionConfig);
     get remotePeerId(): import("@olane/o-config").PeerId;
     get remoteAddr(): import("@olane/o-config").Multiaddr;
+    /**
+     * Get the connection configuration for compatibility checking.
+     */
+    get connectionConfig(): oNodeConnectionConfig;
     supportsAddress(address: oNodeAddress): boolean;
     getOrCreateStream(): Promise<oNodeConnectionStream>;
     createStream(): Promise<oNodeConnectionStream>;

package/dist/src/connection/o-node-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAU,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAEL,WAAW,EAGX,QAAQ,EACR,SAAS,EACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,qBAAa,eAAgB,SAAQ,WAAW;IAKlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAJrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IACvC,SAAS,CAAC,WAAW,EAAE,iBAAiB,CAAC;gBAEV,MAAM,EAAE,qBAAqB;IAO5D,IAAI,YAAY,qCAEf;IAED,IAAI,UAAU,wCAEb;IAED,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAMzC,iBAAiB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAanD,YAAY,IAAI,OAAO,CAAC,qBAAqB,CAAC;IA6BpD,IAAI,OAAO,IAAI,qBAAqB,EAAE,CAcrC;IAEK,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA6C/C,YAAY,CAAC,MAAM,EAAE,qBAAqB;IAI1C,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}
+{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAU,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAEL,WAAW,EAGX,QAAQ,EACR,SAAS,EACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,qBAAa,eAAgB,SAAQ,WAAW;IAKlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAJrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IACvC,SAAS,CAAC,WAAW,EAAE,iBAAiB,CAAC;gBAEV,MAAM,EAAE,qBAAqB;IAQ5D,IAAI,YAAY,qCAEf;IAED,IAAI,UAAU,wCAEb;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,qBAAqB,CAE5C;IAED,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAMzC,iBAAiB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAkBnD,YAAY,IAAI,OAAO,CAAC,qBAAqB,CAAC;IA6BpD,IAAI,OAAO,IAAI,qBAAqB,EAAE,CAcrC;IAEK,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA6C/C,YAAY,CAAC,MAAM,EAAE,qBAAqB;IAI1C,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}

package/dist/src/connection/o-node-connection.js

@@ -8,6 +8,7 @@ export class oNodeConnection extends oConnection {
         this.p2pConnection = config.p2pConnection;
         this.streamHandler = new StreamHandler(this.logger);
         this.reusePolicy = config.reusePolicy ?? 'none';
+        console.log('oNodeConnection constructor', this.reusePolicy);
     }
     get remotePeerId() {
         return this.p2pConnection.remotePeer;
@@ -15,16 +16,27 @@ export class oNodeConnection extends oConnection {
     get remoteAddr() {
         return this.p2pConnection.remoteAddr;
     }
+    /**
+     * Get the connection configuration for compatibility checking.
+     */
+    get connectionConfig() {
+        return this.config;
+    }
     supportsAddress(address) {
         return address.libp2pTransports.some((transport) => {
             return transport.toString() === this.remoteAddr.toString();
         });
     }
     async getOrCreateStream() {
-        if (this.reusePolicy === 'reuse' && this.streams.length > 0) {
-            this.logger.debug('Returning reuse stream: ', this.streams[0].p2pStream.protocol);
+        console.log('getOrCreateStream', this.reusePolicy);
+        if (this.reusePolicy === 'reuse') {
+            this.logger.debug('Reusing stream...');
             // search for streams that allow re-use
-            return this.streams[0];
+            if (this.streams.length > 0) {
+                this.logger.debug('Returning reuse stream: ', this.streams[0].p2pStream.protocol);
+                // search for streams that allow re-use
+                return this.streams[0];
+            }
         }
         return this.createStream();
     }

package/dist/src/connection/o-node-connection.manager.d.ts

@@ -9,6 +9,8 @@ export declare class oNodeConnectionManager extends oConnectionManager {
     private defaultDrainTimeoutMs?;
     private connectionsByAddress;
     private pendingDialsByAddress;
+    /** Cache of oNodeConnection instances keyed by p2p connection ID */
+    private nodeConnectionByConnectionId;
     constructor(config: oNodeConnectionManagerConfig);
     /**
      * Set up listeners to maintain connection cache state
@@ -27,6 +29,26 @@ export declare class oNodeConnectionManager extends oConnectionManager {
      * @returns The peer ID string or null if not found
      */
     private getPeerIdFromAddress;
+    /**
+     * Select the best connection from an array of connections.
+     * Prioritizes connections with active streams, then by direction based on context.
+     *
+     * @param connections - Array of connections to choose from
+     * @param reuseContext - If true, prefer inbound connections; otherwise prefer outbound
+     * @returns The best connection or null if none are suitable
+     */
+    private selectBestConnection;
+    /**
+     * Get a cached oNodeConnection for the given p2p connection if it exists and is valid.
+     * @param p2pConnection - The p2p connection to look up
+     * @returns A valid oNodeConnection or null if none found
+     */
+    private getCachedNodeConnection;
+    /**
+     * Cache an oNodeConnection by its p2p connection ID for potential reuse.
+     * @param conn - The oNodeConnection to cache
+     */
+    private cacheNodeConnection;
     getOrCreateConnection(nextHopAddress: oAddress, address: oAddress): Promise<Connection>;
     private performDial;
     answer(config: oConnectionConfig & {
@@ -34,7 +56,7 @@ export declare class oNodeConnectionManager extends oConnectionManager {
         reuse?: boolean;
     }): Promise<oNodeConnection>;
     /**
-     * Connect to a given address, reusing libp2p connections when possible
+     * Connect to a given address, reusing oNodeConnection and libp2p connections when possible
      * @param config - Connection configuration
      * @returns The connection object
      */
@@ -56,11 +78,14 @@ export declare class oNodeConnectionManager extends oConnectionManager {
      * @returns Object containing cache statistics
      */
     getCacheStats(): {
-        cachedConnections: number;
+        cachedAddresses: number;
+        totalCachedConnections: number;
         pendingDials: number;
+        cachedNodeConnections: number;
         connectionsByPeer: Array<{
             peerId: string;
             status: string;
+            addressKey: string;
         }>;
     };
     /**
@@ -68,5 +93,10 @@ export declare class oNodeConnectionManager extends oConnectionManager {
      * @returns Number of connections removed
      */
     cleanupStaleConnections(): number;
+    /**
+     * Clean up all stale oNodeConnections from cache
+     * @returns Number of oNodeConnections removed
+     */
+    cleanupStaleNodeConnections(): number;
 }
 //# sourceMappingURL=o-node-connection.manager.d.ts.map

package/dist/src/connection/o-node-connection.manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAQhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IAPzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,oBAAoB,CAAsC;IAClE,OAAO,CAAC,qBAAqB,CACjB;gBAES,MAAM,EAAE,4BAA4B;IAWzD;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAsBhC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IASrB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAatB,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;YA+DR,WAAW;IAwBnB,MAAM,CACV,MAAM,EAAE,iBAAiB,GAAG;QAAE,aAAa,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACzE,OAAO,CAAC,eAAe,CAAC;IAmC3B;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BlE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAwCpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;IA+C/D;;;OAGG;IACH,aAAa,IAAI;QACf,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9D;IAaD;;;OAGG;IACH,uBAAuB,IAAI,MAAM;CAgBlC"}
+{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAUhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IATzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,qBAAqB,CAA+C;IAC5E,oEAAoE;IACpE,OAAO,CAAC,4BAA4B,CACxB;gBAES,MAAM,EAAE,4BAA4B;IAWzD;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAyChC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IASrB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IA8D5B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAIrB,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;YAgFR,WAAW;IAwBnB,MAAM,CACV,MAAM,EAAE,iBAAiB,GAAG;QAAE,aAAa,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACzE,OAAO,CAAC,eAAe,CAAC;IA2C3B;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6ClE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAiDpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;IA6D/D;;;OAGG;IACH,aAAa,IAAI;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,YAAY,EAAE,MAAM,CAAC;QACrB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,iBAAiB,EAAE,KAAK,CAAC;YACvB,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC,CAAC;KACJ;IA6BD;;;OAGG;IACH,uBAAuB,IAAI,MAAM;IA6BjC;;;OAGG;IACH,2BAA2B,IAAI,MAAM;CAgBtC"}

package/dist/src/connection/o-node-connection.manager.js

@@ -6,6 +6,8 @@ export class oNodeConnectionManager extends oConnectionManager {
         this.config = config;
         this.connectionsByAddress = new Map();
         this.pendingDialsByAddress = new Map();
+        /** Cache of oNodeConnection instances keyed by p2p connection ID */
+        this.nodeConnectionByConnectionId = new Map();
         this.p2pNode = config.p2pNode;
         this.defaultReadTimeoutMs = config.defaultReadTimeoutMs;
         this.defaultDrainTimeoutMs = config.defaultDrainTimeoutMs;
@@ -22,11 +24,31 @@ export class oNodeConnectionManager extends oConnectionManager {
             if (!connection) {
                 return;
             }
-            for (const [addressKey, cachedConnection,] of this.connectionsByAddress.entries()) {
-                if (cachedConnection === connection) {
-                    this.logger.debug('Connection closed, removing from cache for address:', addressKey);
-                    this.connectionsByAddress.delete(addressKey);
-                }
+            // Clean up libp2p connection cache
+            // for (const [
+            //   addressKey,
+            //   cachedConnections,
+            // ] of this.connectionsByAddress.entries()) {
+            //   const index = cachedConnections.indexOf(connection);
+            //   if (index !== -1) {
+            //     this.logger.debug(
+            //       'Connection closed, removing from cache for address:',
+            //       addressKey,
+            //     );
+            //     cachedConnections.splice(index, 1);
+            //     // Remove the address key entirely if no connections remain
+            //     if (cachedConnections.length === 0) {
+            //       this.connectionsByAddress.delete(addressKey);
+            //     } else {
+            //       this.connectionsByAddress.set(addressKey, cachedConnections);
+            //     }
+            //   }
+            // }
+            // Clean up oNodeConnection cache by connection ID
+            const connectionId = connection.id;
+            if (this.nodeConnectionByConnectionId.has(connectionId)) {
+                this.logger.debug('Connection closed, removing oNodeConnection for connection ID:', connectionId);
+                this.nodeConnectionByConnectionId.delete(connectionId);
             }
         });
     }
@@ -63,6 +85,81 @@ export class oNodeConnectionManager extends oConnectionManager {
             return null;
         }
     }
+    /**
+     * Select the best connection from an array of connections.
+     * Prioritizes connections with active streams, then by direction based on context.
+     *
+     * @param connections - Array of connections to choose from
+     * @param reuseContext - If true, prefer inbound connections; otherwise prefer outbound
+     * @returns The best connection or null if none are suitable
+     */
+    selectBestConnection(connections, reuseContext = false) {
+        // Filter to only open connections
+        const openConnections = connections.filter((c) => c.status === 'open');
+        if (openConnections.length === 0) {
+            return null;
+        }
+        // Priority 1: Connections with active o-protocol streams
+        const connectionsWithStreams = openConnections
+            .map((conn) => ({
+            conn,
+            activeStreamCount: conn.streams.filter((s) => s.protocol.includes('/o/') &&
+                s.status === 'open' &&
+                s.writeStatus === 'writable' &&
+                s.remoteReadStatus === 'readable').length,
+        }))
+            .filter((item) => item.activeStreamCount > 0)
+            .sort((a, b) => b.activeStreamCount - a.activeStreamCount);
+        if (connectionsWithStreams.length > 0) {
+            this.logger.debug('Selected connection with active streams', {
+                streamCount: connectionsWithStreams[0].activeStreamCount,
+            });
+            return connectionsWithStreams[0].conn;
+        }
+        // Priority 2: Based on reuse context
+        if (reuseContext) {
+            // Prefer inbound connections
+            const inbound = openConnections.find((c) => c.direction === 'inbound' || !c.direction);
+            if (inbound) {
+                this.logger.debug('Selected inbound connection (reuse context)');
+                return inbound;
+            }
+        }
+        else {
+            // Prefer outbound connections
+            const outbound = openConnections.find((c) => c.direction === 'outbound');
+            if (outbound) {
+                this.logger.debug('Selected outbound connection (non-reuse context)');
+                return outbound;
+            }
+        }
+        // Priority 3: Return first open connection
+        this.logger.debug('Selected first available open connection', connectionsWithStreams);
+        return openConnections[0];
+    }
+    /**
+     * Get a cached oNodeConnection for the given p2p connection if it exists and is valid.
+     * @param p2pConnection - The p2p connection to look up
+     * @returns A valid oNodeConnection or null if none found
+     */
+    getCachedNodeConnection(p2pConnection) {
+        const cached = this.nodeConnectionByConnectionId.get(p2pConnection.id);
+        if (cached && cached.p2pConnection?.status === 'open') {
+            return cached;
+        }
+        // Clean up stale entry if connection is no longer open
+        if (cached) {
+            this.nodeConnectionByConnectionId.delete(p2pConnection.id);
+        }
+        return null;
+    }
+    /**
+     * Cache an oNodeConnection by its p2p connection ID for potential reuse.
+     * @param conn - The oNodeConnection to cache
+     */
+    cacheNodeConnection(conn) {
+        this.nodeConnectionByConnectionId.set(conn.p2pConnection.id, conn);
+    }
     async getOrCreateConnection(nextHopAddress, address) {
         if (!nextHopAddress) {
             throw new Error('Invalid address passed');
@@ -72,22 +169,32 @@ export class oNodeConnectionManager extends oConnectionManager {
         if (!addressKey) {
             throw new Error(`Unable to extract address key from address: ${nextHopAddress.toString()}`);
         }
-        // Check if we have a cached connection by address key
-        const cachedConnection = this.connectionsByAddress.get(addressKey);
-        if (cachedConnection && cachedConnection.status === 'open') {
-            this.logger.debug('Reusing cached connection for address:', nextHopAddress?.value);
-            return cachedConnection;
+        // Check if we have cached connections by address key
+        const cachedConnections = this.connectionsByAddress.get(addressKey) || [];
+        const bestConnection = this.selectBestConnection(cachedConnections, false);
+        if (bestConnection) {
+            this.logger.debug('Reusing cached connection for address:', nextHopAddress?.value, bestConnection.id);
+            return bestConnection;
         }
-        // Clean up stale connection if it exists but is not open
-        if (cachedConnection && cachedConnection.status !== 'open') {
-            this.logger.debug('Removing stale connection for address:', addressKey);
-            this.connectionsByAddress.delete(addressKey);
+        // Clean up stale connections if they exist but are not open
+        if (cachedConnections.length > 0) {
+            const openConnections = cachedConnections.filter((c) => c.status === 'open');
+            if (openConnections.length === 0) {
+                this.logger.debug('Removing all stale connections for address:', addressKey);
+                this.connectionsByAddress.delete(addressKey);
+            }
+            else if (openConnections.length < cachedConnections.length) {
+                this.logger.debug('Cleaning up some stale connections for address:', addressKey);
+                this.connectionsByAddress.set(addressKey, openConnections);
+            }
         }
         // Check if libp2p has an active connection for this address
         const libp2pConnection = this.getCachedLibp2pConnection(nextHopAddress);
         if (libp2pConnection && libp2pConnection.status === 'open') {
             this.logger.debug('Caching existing libp2p connection for address:', addressKey);
-            this.connectionsByAddress.set(addressKey, libp2pConnection);
+            const connections = this.connectionsByAddress.get(addressKey) || [];
+            connections.push(libp2pConnection);
+            this.connectionsByAddress.set(addressKey, connections);
             return libp2pConnection;
         }
         // Check if dial is already in progress for this address key
@@ -101,8 +208,10 @@ export class oNodeConnectionManager extends oConnectionManager {
         this.pendingDialsByAddress.set(addressKey, dialPromise);
         try {
             const connection = await dialPromise;
-            // Cache the established connection by address key
-            this.connectionsByAddress.set(addressKey, connection);
+            // Add the established connection to the cache array
+            const connections = this.connectionsByAddress.get(addressKey) || [];
+            connections.push(connection);
+            this.connectionsByAddress.set(addressKey, connections);
             return connection;
         }
         finally {
@@ -137,9 +246,16 @@ export class oNodeConnectionManager extends oConnectionManager {
             requestHandler: config.requestHandler ?? undefined,
             reusePolicy: reuse ? 'reuse' : 'none',
         });
+        // Cache the new connection by its p2p connection ID
+        this.cacheNodeConnection(connection);
         const addressKey = this.getAddressKey(nextHopAddress);
         if (addressKey) {
-            this.connectionsByAddress.set(addressKey, p2pConnection);
+            const connections = this.connectionsByAddress.get(addressKey) || [];
+            // Only add if not already in the cache
+            if (!connections.includes(p2pConnection)) {
+                connections.push(p2pConnection);
+                this.connectionsByAddress.set(addressKey, connections);
+            }
         }
         else {
             this.logger.error('Should not happen! Failed to generate an address key for address:', nextHopAddress);
@@ -147,13 +263,21 @@ export class oNodeConnectionManager extends oConnectionManager {
         return connection;
     }
     /**
-     * Connect to a given address, reusing libp2p connections when possible
+     * Connect to a given address, reusing oNodeConnection and libp2p connections when possible
      * @param config - Connection configuration
      * @returns The connection object
      */
     async connect(config) {
         const { address, nextHopAddress, callerAddress, readTimeoutMs, drainTimeoutMs, } = config;
+        // First get or create the underlying p2p connection
         const p2pConnection = await this.getOrCreateConnection(nextHopAddress, address);
+        // Check for existing valid oNodeConnection for this p2p connection
+        const existingConnection = this.getCachedNodeConnection(p2pConnection);
+        if (existingConnection) {
+            this.logger.debug('Reusing cached oNodeConnection for connection ID:', p2pConnection.id);
+            return existingConnection;
+        }
+        // No valid cached connection, create new one
         const connection = new oNodeConnection({
             nextHopAddress: nextHopAddress,
             address: address,
@@ -166,6 +290,8 @@ export class oNodeConnectionManager extends oConnectionManager {
             runOnLimitedConnection: this.config.runOnLimitedConnection ?? false,
             requestHandler: config.requestHandler ?? undefined,
         });
+        // Cache the new connection by its p2p connection ID
+        this.cacheNodeConnection(connection);
         return connection;
     }
     /**
@@ -180,8 +306,9 @@ export class oNodeConnectionManager extends oConnectionManager {
                 return false;
             }
             // Check our address-based cache first
-            const cachedConnection = this.connectionsByAddress.get(addressKey);
-            if (cachedConnection?.status === 'open') {
+            const cachedConnections = this.connectionsByAddress.get(addressKey) || [];
+            const bestConnection = this.selectBestConnection(cachedConnections, false);
+            if (bestConnection) {
                 return true;
             }
             // Fall back to checking libp2p's connections
@@ -194,7 +321,11 @@ export class oNodeConnectionManager extends oConnectionManager {
             if (hasOpenConnection) {
                 const openConnection = connections.find((conn) => conn.status === 'open');
                 if (openConnection) {
-                    this.connectionsByAddress.set(addressKey, openConnection);
+                    const existingConnections = this.connectionsByAddress.get(addressKey) || [];
+                    if (!existingConnections.includes(openConnection)) {
+                        existingConnections.push(openConnection);
+                        this.connectionsByAddress.set(addressKey, existingConnections);
+                    }
                 }
             }
             return hasOpenConnection;
@@ -216,9 +347,10 @@ export class oNodeConnectionManager extends oConnectionManager {
                 return null;
             }
             // Check address-based cache first
-            const cachedConnection = this.connectionsByAddress.get(addressKey);
-            if (cachedConnection?.status === 'open') {
-                return cachedConnection;
+            const cachedConnections = this.connectionsByAddress.get(addressKey) || [];
+            const bestConnection = this.selectBestConnection(cachedConnections, false);
+            if (bestConnection) {
+                return bestConnection;
             }
             const peerId = this.getPeerIdFromAddress(address);
             if (!peerId) {
@@ -227,15 +359,22 @@ export class oNodeConnectionManager extends oConnectionManager {
             // Query libp2p for connections to this peer
             const connections = this.p2pNode.getConnections();
             const filteredConnections = connections.filter((conn) => conn.remotePeer?.toString() === peerId);
-            // Find the first open connection
-            const openConnection = filteredConnections.find((conn) => conn.status === 'open');
-            // If we found an open connection in libp2p, cache it by address key
-            if (openConnection) {
-                this.connectionsByAddress.set(addressKey, openConnection);
-                return openConnection;
+            // Find open connections
+            const openConnections = filteredConnections.filter((conn) => conn.status === 'open');
+            // If we found open connections in libp2p, add them to cache and select best
+            if (openConnections.length > 0) {
+                const existingConnections = this.connectionsByAddress.get(addressKey) || [];
+                // Add any new connections that aren't already cached
+                for (const conn of openConnections) {
+                    if (!existingConnections.includes(conn)) {
+                        existingConnections.push(conn);
+                    }
+                }
+                this.connectionsByAddress.set(addressKey, existingConnections);
+                return this.selectBestConnection(existingConnections, false);
             }
-            // Clean up stale cache entry if connection is no longer open
-            if (cachedConnection) {
+            // Clean up stale cache entries if connections are no longer open
+            if (cachedConnections.length > 0) {
                 this.connectionsByAddress.delete(addressKey);
             }
             return null;
@@ -250,13 +389,22 @@ export class oNodeConnectionManager extends oConnectionManager {
      * @returns Object containing cache statistics
      */
     getCacheStats() {
+        const allConnections = [];
+        for (const [addressKey, connections,] of this.connectionsByAddress.entries()) {
+            for (const conn of connections) {
+                allConnections.push({
+                    peerId: conn.remotePeer?.toString() ?? 'unknown',
+                    status: conn.status,
+                    addressKey,
+                });
+            }
+        }
         return {
-            cachedConnections: this.connectionsByAddress.size,
+            cachedAddresses: this.connectionsByAddress.size,
+            totalCachedConnections: allConnections.length,
             pendingDials: this.pendingDialsByAddress.size,
-            connectionsByPeer: Array.from(this.connectionsByAddress.values()).map((conn) => ({
-                peerId: conn.remotePeer?.toString() ?? 'unknown',
-                status: conn.status,
-            })),
+            cachedNodeConnections: this.nodeConnectionByConnectionId.size,
+            connectionsByPeer: allConnections,
         };
     }
     /**
@@ -265,10 +413,19 @@ export class oNodeConnectionManager extends oConnectionManager {
      */
     cleanupStaleConnections() {
         let removed = 0;
-        for (const [addressKey, connection,] of this.connectionsByAddress.entries()) {
-            if (connection.status !== 'open') {
-                this.connectionsByAddress.delete(addressKey);
-                removed++;
+        for (const [addressKey, connections,] of this.connectionsByAddress.entries()) {
+            const openConnections = connections.filter((conn) => conn.status === 'open');
+            const staleCount = connections.length - openConnections.length;
+            if (staleCount > 0) {
+                removed += staleCount;
+                if (openConnections.length === 0) {
+                    // Remove the entire entry if no connections remain
+                    this.connectionsByAddress.delete(addressKey);
+                }
+                else {
+                    // Keep only the open connections
+                    this.connectionsByAddress.set(addressKey, openConnections);
+                }
             }
         }
         if (removed > 0) {
@@ -276,4 +433,21 @@ export class oNodeConnectionManager extends oConnectionManager {
         }
         return removed;
     }
+    /**
+     * Clean up all stale oNodeConnections from cache
+     * @returns Number of oNodeConnections removed
+     */
+    cleanupStaleNodeConnections() {
+        let removed = 0;
+        for (const [connectionId, conn,] of this.nodeConnectionByConnectionId.entries()) {
+            if (conn.p2pConnection?.status !== 'open') {
+                this.nodeConnectionByConnectionId.delete(connectionId);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            this.logger.debug(`Cleaned up ${removed} stale oNodeConnections`);
+        }
+        return removed;
+    }
 }

package/dist/src/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './synchronized.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/src/decorators/index.js

@@ -0,0 +1 @@
+export * from './synchronized.js';

package/dist/src/decorators/synchronized.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Method decorator that automatically acquires and releases a lock
+ * when the decorated method is called. Ensures only one invocation
+ * of the method executes at a time.
+ *
+ * @param lockName - Optional custom lock name. If not provided,
+ *                   defaults to "ClassName:methodName"
+ * @param timeoutMs - Optional timeout for lock acquisition in milliseconds
+ *
+ * @example
+ * class MyNode extends oNode {
+ *   protected lockManager = new LockManager();
+ *
+ *   @Synchronized('register:leader')
+ *   async registerLeader(): Promise<void> {
+ *     // This method is automatically synchronized
+ *   }
+ * }
+ */
+export declare function Synchronized(lockName?: string, timeoutMs?: number): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+//# sourceMappingURL=synchronized.d.ts.map

package/dist/src/decorators/synchronized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synchronized.d.ts","sourceRoot":"","sources":["../../../src/decorators/synchronized.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,YAEtD,GAAG,eACE,MAAM,cACP,kBAAkB,wBA8BjC"}

package/dist/src/decorators/synchronized.js

@@ -0,0 +1,39 @@
+/**
+ * Method decorator that automatically acquires and releases a lock
+ * when the decorated method is called. Ensures only one invocation
+ * of the method executes at a time.
+ *
+ * @param lockName - Optional custom lock name. If not provided,
+ *                   defaults to "ClassName:methodName"
+ * @param timeoutMs - Optional timeout for lock acquisition in milliseconds
+ *
+ * @example
+ * class MyNode extends oNode {
+ *   protected lockManager = new LockManager();
+ *
+ *   @Synchronized('register:leader')
+ *   async registerLeader(): Promise<void> {
+ *     // This method is automatically synchronized
+ *   }
+ * }
+ */
+export function Synchronized(lockName, timeoutMs) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        // Generate lock name if not provided
+        const finalLockName = lockName || `${target.constructor.name}:${propertyKey}`;
+        descriptor.value = async function (...args) {
+            // Ensure lockManager exists on the instance
+            const lockManager = this.lockManager;
+            if (!lockManager) {
+                throw new Error(`LockManager not initialized on instance. ` +
+                    `Ensure 'protected lockManager = new LockManager()' is declared in ${target.constructor.name}`);
+            }
+            // Execute the method with automatic lock management
+            return lockManager.withLock(finalLockName, async () => {
+                return originalMethod.apply(this, args);
+            }, timeoutMs);
+        };
+        return descriptor;
+    };
+}

package/dist/src/index.d.ts

@@ -1,5 +1,6 @@
 export * from './o-node.js';
 export * from './utils/index.js';
+export * from './decorators/index.js';
 export * from './o-node.hierarchy-manager.js';
 export * from './interfaces/o-node.config.js';
 export * from './connection/index.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,kCAAkC,CAAC"}

package/dist/src/index.js

@@ -1,5 +1,6 @@
 export * from './o-node.js';
 export * from './utils/index.js';
+export * from './decorators/index.js';
 export * from './o-node.hierarchy-manager.js';
 export * from './interfaces/o-node.config.js';
 export * from './connection/index.js';

package/dist/src/o-node.d.ts

@@ -11,6 +11,7 @@ import { oToolBase } from '@olane/o-tool';
 import { oConnectionHeartbeatManager } from './managers/o-connection-heartbeat.manager.js';
 import { oNodeConnectionConfig } from './connection/index.js';
 import { oReconnectionManager } from './managers/o-reconnection.manager.js';
+import { LockManager } from './utils/lock-manager.js';
 export declare class oNode extends oToolBase {
     peerId: PeerId;
     p2pNode: Libp2p;
@@ -23,6 +24,7 @@ export declare class oNode extends oToolBase {
     protected didRegister: boolean;
     protected hooksStartFinished: any[];
     protected hooksInitFinished: any[];
+    protected lockManager: LockManager;
     constructor(config: oNodeConfig);
     get leader(): oNodeAddress | null;
     get networkConfig(): Libp2pConfig;

package/dist/src/o-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"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"}

package/dist/src/o-node.js

@@ -1,3 +1,12 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 import { createNode, defaultLibp2pConfig, KEEP_ALIVE, } from '@olane/o-config';
 import { v4 as uuidv4 } from 'uuid';
 import { oNodeRouter } from './router/o-node.router.js';
@@ -11,12 +20,15 @@ import { oMethodResolver, oToolBase } from '@olane/o-tool';
 import { oLeaderResolverFallback } from './router/index.js';
 import { oNodeNotificationManager } from './o-node.notification-manager.js';
 import { oReconnectionManager } from './managers/o-reconnection.manager.js';
+import { LockManager } from './utils/lock-manager.js';
+import { Synchronized } from './decorators/synchronized.js';
 export class oNode extends oToolBase {
     constructor(config) {
         super(config);
         this.didRegister = false;
         this.hooksStartFinished = [];
         this.hooksInitFinished = [];
+        this.lockManager = new LockManager();
         this.config = config;
     }
     get leader() {
@@ -522,6 +534,8 @@ export class oNode extends oToolBase {
     resetState() {
         // Reset registration flag
         this.didRegister = false;
+        // Clear all locks
+        this.lockManager.clearAll();
         // Clear peer references
         this.peerId = undefined;
         this.p2pNode = undefined;
@@ -638,3 +652,15 @@ export class oNode extends oToolBase {
         }
     }
 }
+__decorate([
+    Synchronized('register:parent'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], oNode.prototype, "registerParent", null);
+__decorate([
+    Synchronized('register:leader'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], oNode.prototype, "registerLeader", null);

package/dist/src/o-node.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAoB,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAMrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IAC/C,OAAO,CAAC,aAAa,CAAiB;IAEhC,mBAAmB,CAAC,OAAO,EAAE,QAAQ;IAgBrC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAoBhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC;IAIV,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IAwCV,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CAgC5D"}
+{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAoB,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAMrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IAC/C,OAAO,CAAC,aAAa,CAAiB;IAEhC,mBAAmB,CAAC,OAAO,EAAE,QAAQ;IAsBrC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAoBhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC;IAIV,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IAyCV,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CAiC5D"}

package/dist/src/o-node.tool.js

@@ -13,6 +13,7 @@ import { ConnectionUtils } from './utils/connection.utils.js';
 export class oNodeTool extends oTool(oServerNode) {
     async handleProtocolReuse(address) {
         const reuseProtocol = address.protocol + '/reuse';
+        this.logger.debug('Handling protocol reuse: ' + reuseProtocol);
         const protocols = this.p2pNode.getProtocols();
         if (protocols.find((p) => p === reuseProtocol)) {
             // already handling
@@ -21,10 +22,11 @@ export class oNodeTool extends oTool(oServerNode) {
         const maxOutboundsStreams = process.env.MAX_OUTBOUND_STREAMS
             ? parseInt(process.env.MAX_OUTBOUND_STREAMS)
             : 1000;
-        await this.p2pNode.handle(reuseProtocol, this.handleStream.bind(this), {
+        await this.p2pNode.handle(reuseProtocol, this.handleStreamReuse.bind(this), {
             maxInboundStreams: 10000,
             maxOutboundStreams: maxOutboundsStreams,
         });
+        this.logger.debug('Handled protocol reuse: ' + reuseProtocol);
     }
     async handleProtocol(address) {
         const protocols = this.p2pNode.getProtocols();
@@ -72,6 +74,7 @@ export class oNodeTool extends oTool(oServerNode) {
             callerAddress: this.address,
             p2pConnection: connection,
             reuse,
+            // requestHandler: this.execute.bind(this), TODO: do we need this?
         });
         // Use StreamHandler for consistent stream handling
         // This follows libp2p v3 best practices for length-prefixed streaming
@@ -108,6 +111,7 @@ export class oNodeTool extends oTool(oServerNode) {
             }));
         }
         // create downward direction connection
+        this.logger.debug('Pinging child to confirm access');
         await this.useChild(childAddress, {
             method: 'ping',
             params: {},

package/dist/src/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './stream.utils.js';
 export * from './network.utils.js';
 export * from './connection.utils.js';
+export * from './lock-manager.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/src/utils/index.js

@@ -1,3 +1,4 @@
 export * from './stream.utils.js';
 export * from './network.utils.js';
 export * from './connection.utils.js';
+export * from './lock-manager.js';

package/dist/src/utils/lock-manager.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Promise-based lock manager for handling concurrent access to critical sections
+ * Supports named locks for fine-grained concurrency control
+ */
+export declare class LockManager {
+    private locks;
+    private lockStates;
+    private resolvers;
+    /**
+     * Acquire a named lock, waiting if necessary
+     * @param lockName - Unique identifier for the lock
+     * @param timeoutMs - Optional timeout in milliseconds
+     * @throws Error if timeout is reached
+     */
+    acquire(lockName: string, timeoutMs?: number): Promise<void>;
+    /**
+     * Release a named lock
+     * @param lockName - Unique identifier for the lock to release
+     */
+    release(lockName: string): void;
+    /**
+     * Execute a function with automatic lock acquisition/release
+     * @param lockName - Unique identifier for the lock
+     * @param fn - Async function to execute while holding the lock
+     * @param timeoutMs - Optional timeout for lock acquisition
+     * @returns The result of the function execution
+     */
+    withLock<T>(lockName: string, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;
+    /**
+     * Check if a lock is currently held
+     * @param lockName - Unique identifier for the lock
+     * @returns true if the lock is currently held
+     */
+    isLocked(lockName: string): boolean;
+    /**
+     * Clear all locks (for teardown/reset)
+     * Resolves any pending waiters
+     */
+    clearAll(): void;
+    /**
+     * Get statistics about current lock states (useful for debugging)
+     * @returns Object containing lock statistics
+     */
+    getStats(): {
+        totalLocks: number;
+        activeLocks: number;
+        lockNames: string[];
+    };
+}
+//# sourceMappingURL=lock-manager.d.ts.map

package/dist/src/utils/lock-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-manager.d.ts","sourceRoot":"","sources":["../../../src/utils/lock-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,SAAS,CAAsC;IAEvD;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlE;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAS/B;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,EACd,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IASb;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAInC;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAUhB;;;OAGG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB;CAWF"}

package/dist/src/utils/lock-manager.js

@@ -0,0 +1,101 @@
+/**
+ * Promise-based lock manager for handling concurrent access to critical sections
+ * Supports named locks for fine-grained concurrency control
+ */
+export class LockManager {
+    constructor() {
+        this.locks = new Map();
+        this.lockStates = new Map();
+        this.resolvers = new Map();
+    }
+    /**
+     * Acquire a named lock, waiting if necessary
+     * @param lockName - Unique identifier for the lock
+     * @param timeoutMs - Optional timeout in milliseconds
+     * @throws Error if timeout is reached
+     */
+    async acquire(lockName, timeoutMs) {
+        // Wait for any existing lock to be released
+        while (this.lockStates.get(lockName)) {
+            const currentLock = this.locks.get(lockName);
+            if (currentLock) {
+                if (timeoutMs) {
+                    await Promise.race([
+                        currentLock,
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`Lock timeout: ${lockName}`)), timeoutMs)),
+                    ]);
+                }
+                else {
+                    await currentLock;
+                }
+            }
+        }
+        // Acquire the lock
+        this.lockStates.set(lockName, true);
+        const lockPromise = new Promise((resolve) => {
+            this.resolvers.set(lockName, resolve);
+        });
+        this.locks.set(lockName, lockPromise);
+    }
+    /**
+     * Release a named lock
+     * @param lockName - Unique identifier for the lock to release
+     */
+    release(lockName) {
+        const resolver = this.resolvers.get(lockName);
+        if (resolver) {
+            resolver();
+            this.resolvers.delete(lockName);
+        }
+        this.lockStates.set(lockName, false);
+    }
+    /**
+     * Execute a function with automatic lock acquisition/release
+     * @param lockName - Unique identifier for the lock
+     * @param fn - Async function to execute while holding the lock
+     * @param timeoutMs - Optional timeout for lock acquisition
+     * @returns The result of the function execution
+     */
+    async withLock(lockName, fn, timeoutMs) {
+        await this.acquire(lockName, timeoutMs);
+        try {
+            return await fn();
+        }
+        finally {
+            this.release(lockName);
+        }
+    }
+    /**
+     * Check if a lock is currently held
+     * @param lockName - Unique identifier for the lock
+     * @returns true if the lock is currently held
+     */
+    isLocked(lockName) {
+        return this.lockStates.get(lockName) ?? false;
+    }
+    /**
+     * Clear all locks (for teardown/reset)
+     * Resolves any pending waiters
+     */
+    clearAll() {
+        // Resolve any pending waiters
+        for (const lockName of this.lockStates.keys()) {
+            this.release(lockName);
+        }
+        this.locks.clear();
+        this.lockStates.clear();
+        this.resolvers.clear();
+    }
+    /**
+     * Get statistics about current lock states (useful for debugging)
+     * @returns Object containing lock statistics
+     */
+    getStats() {
+        const activeLocks = Array.from(this.lockStates.entries()).filter(([_, isLocked]) => isLocked);
+        return {
+            totalLocks: this.lockStates.size,
+            activeLocks: activeLocks.length,
+            lockNames: activeLocks.map(([name]) => name),
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-node",
-  "version": "0.7.44",
+  "version": "0.7.46",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -40,7 +40,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.29.0",
-    "@olane/o-test": "0.7.44",
+    "@olane/o-test": "0.7.46",
     "@tsconfig/node20": "^20.1.6",
     "@types/jest": "^30.0.0",
     "@types/json5": "^2.2.0",
@@ -60,13 +60,13 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-config": "0.7.44",
-    "@olane/o-core": "0.7.44",
-    "@olane/o-protocol": "0.7.44",
-    "@olane/o-tool": "0.7.44",
+    "@olane/o-config": "0.7.46",
+    "@olane/o-core": "0.7.46",
+    "@olane/o-protocol": "0.7.46",
+    "@olane/o-tool": "0.7.46",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0",
     "json5": "^2.2.3"
   },
-  "gitHead": "de7bc5247c97fb219d522cc5874f7459634e03ec"
+  "gitHead": "48c45f37c6e2e1ee626ce1fb0f0de175ca2db3b6"
 }