@weave-js/core 0.15.3 → 0.16.0

package/lib/metrics/common.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../types.js').Runtime} Runtime
+ * @typedef {import('../types.__js').Runtime} Runtime
 */
 const os = require('os');
 const Constants = require('./constants');

package/lib/metrics/exporter/base.js

@@ -4,11 +4,11 @@ module.exports = (options) => {
   const cache = {};
 
   cache.init = (registry) => {
-    Promise.resolve(new WeaveError('Init method not implemented'));
+    return Promise.resolve(new WeaveError('Init method not implemented'));
   };
 
   cache.stop = (registry) => {
-    Promise.resolve(new WeaveError('Stop method not implemented'));
+    return Promise.resolve(new WeaveError('Stop method not implemented'));
   };
 
   return cache;

package/lib/metrics/exporter/event.js

@@ -1,35 +1,37 @@
-const { createBaseMetricAdapter } = require('./base');
+const BaseAdapter = require('./base');
 
 module.exports = (options) => {
   const lastChanges = new Set();
 
-  const adapter = createBaseMetricAdapter(options);
+  const adapter = BaseAdapter(options);
 
-  const sendEvent = (registry, options) => {
-    const broker = registry.broker;
-    const list = this.registry.list();
+  const sendEvent = () => {
+    const broker = adapter.registry.broker;
+    const list = adapter.registry.list();
 
-    broker.emit(this.options.eventName, list);
+    broker.emit(adapter.options.eventName, list);
 
     lastChanges.clear();
   };
 
   adapter.init = (registry) => {
-    this.options = Object.assign(options, {
+    adapter.options = Object.assign({
       eventName: '$metrics.changed',
       interval: 5000
-    });
+    }, options);
 
-    this.registry = registry;
+    adapter.registry = registry;
 
-    if (this.options.interval > 0) {
-      this.timer = setInterval(() => sendEvent(), this.options.interval);
-      this.timer.unref();
+    if (adapter.options.interval > 0) {
+      adapter.timer = setInterval(() => sendEvent(), adapter.options.interval);
+      adapter.timer.unref();
+    } else {
+      adapter.timer = undefined;
     }
   };
 
   adapter.stop = () => {
-    clearInterval(this.timer);
+    clearInterval(adapter.timer);
     return Promise.resolve();
   };
 

package/lib/metrics/exporter/index.js

@@ -24,7 +24,7 @@ module.exports = {
     let cacheFactory;
 
     if (options === true) {
-      cacheFactory = this.adapters.Event;
+      cacheFactory = adapters.Event;
     } else if (isString(options)) {
       const cache = getByName(options);
 

package/lib/metrics/index.js

@@ -1,2 +1,30 @@
+/**
+ * Metrics collection and monitoring system
+ *
+ * Provides standardized metrics collection for:
+ * - Request/response times and counts
+ * - Error rates and types
+ * - Node performance metrics
+ * - Custom application metrics
+ * - System resource utilization
+ *
+ * Supports multiple metric types:
+ * - Counters: Incrementing values (request counts, errors)
+ * - Gauges: Current values (memory usage, active connections)
+ * - Histograms: Value distributions (response times, payload sizes)
+ * - Info: Static metadata (version, build info)
+ *
+ * @namespace Metrics
+ */
+
+/**
+ * Metric constants and identifiers
+ * @type {object}
+ */
 exports.Constants = require('./constants');
+
+/**
+ * Metric exporter implementations for different backends
+ * @type {object}
+ */
 exports.Exporter = require('./exporter');

package/lib/middlewares/bulkhead/index.js

@@ -7,8 +7,8 @@ const { Constants } = require('../../metrics');
 const { WeaveQueueSizeExceededError } = require('../../errors');
 
 /**
- * @typedef {import('../../types').Runtime} Runtime
- * @typedef {import('../../types').Middleware} Middleware
+ * @typedef {import('../../types.__js').Runtime} Runtime
+ * @typedef {import('../../types.__js').Middleware} Middleware
 */
 
 /**
@@ -44,7 +44,7 @@ module.exports = (runtime) => {
           });
       };
 
-      return function bulkheadMiddlware (context, serviceInjections) {
+      return function bulkheadMiddleware (context, serviceInjections) {
         // Execute action immediately
         if (currentlyInFlight < bulkheadOptions.concurrentCalls) {
           currentlyInFlight++;

package/lib/middlewares/cache/index.js

@@ -21,7 +21,7 @@ module.exports = (runtime) => {
         return function cacheMiddleware (context, serviceInjections) {
           // handle enabled function
           if (isEnabledFunction) {
-            if (!action.cache.enabled.call(null, context)) {
+            if (!action.cache.condition.call(null, context)) {
               // Enabled function returns "false". Cache is disabled.
               return handler(context, serviceInjections);
             }
@@ -75,11 +75,12 @@ module.exports = (runtime) => {
 
                   return handler(context).then((result) => {
                     // Cache the value
-                    cache.set(cacheHashKey, result, action.cache.ttl).then(() => {
-                      // release the lock
-                      release();
+                    return cache.set(cacheHashKey, result, action.cache.ttl).then(() => {
+                      return result;
                     });
-                    return result;
+                  }).finally(() => {
+                    // Always release the lock
+                    release();
                   });
                 });
               });

package/lib/middlewares/context-tracker/index.js

@@ -52,32 +52,39 @@ module.exports = (runtime) => {
     return new Promise((resolve) => {
       if (contextList.length === 0) {
         resolve();
+        return;
       }
 
       let isTimedOut = false;
       const timeout = setTimeout(() => {
         isTimedOut = true;
         log.error(new WeaveGracefulStopTimeoutError(service));
-        contextList = [];
         resolve();
       }, shutdownTimeout);
 
       let isFirstCheck = true;
+      let checkInterval;
+
       const checkContexts = () => {
         if (contextList.length === 0) {
           clearTimeout(timeout);
+          if (checkInterval) {
+            clearInterval(checkInterval);
+          }
           resolve();
         } else {
           if (isFirstCheck) {
             log.info(`Waiting for ${contextList.length} open Contexts...`);
             isFirstCheck = false;
           }
-
-          if (!isTimedOut) {
-            setTimeout(checkContexts, 100);
-          }
         }
       };
+
+      // Use setInterval instead of recursive setTimeout to prevent stack overflow
+      if (!isTimedOut) {
+        checkInterval = setInterval(checkContexts, 100);
+        checkInterval.unref();
+      }
       setImmediate(checkContexts);
     });
   };

package/lib/middlewares/index.js

@@ -4,6 +4,24 @@
  * Copyright 2021 Fachwerk
  */
 
+/**
+ * Built-in middleware implementations for cross-cutting concerns
+ *
+ * Middlewares provide reusable functionality that can be applied to actions and events:
+ * - ActionHooks: Before/after/error hooks for actions
+ * - Bulkhead: Concurrency limiting and isolation
+ * - Cache: Response caching and invalidation
+ * - CircuitBreaker: Circuit breaker pattern for fault tolerance
+ * - ErrorHandler: Centralized error processing
+ * - Metrics: Performance monitoring and collection
+ * - Tracing: Distributed tracing support
+ * - Retry: Automatic retry with backoff strategies
+ * - Timeout: Request timeout handling
+ * - ContextTracker: Context lifecycle tracking
+ * - Validator: Parameter validation middleware
+ *
+ * @namespace Middlewares
+ */
 module.exports = {
   ActionHooks: require('./action-hooks'),
   Bulkhead: require('./bulkhead'),

package/lib/middlewares/tracing/tags.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import("../../types.js").Context} Context
- * @typedef {import("../../types.js").TracingOptions} TracingOptions
+ * @typedef {import("../../types.__js").Context} Context
+ * @typedef {import("../../types.__js").TracingOptions} TracingOptions
 */
 
 const { isFunction, dotGet, isObject } = require('@weave-js/utils');

package/lib/middlewares/validator/index.js

@@ -8,8 +8,8 @@ const { WeaveParameterValidationError } = require('../../errors');
 const { capitalize } = require('@weave-js/utils');
 
 /**
- * @typedef {import('../../types').Runtime} Runtime
- * @typedef {import('../../types').Middleware} Middleware
+ * @typedef {import('../../types.__js').Runtime} Runtime
+ * @typedef {import('../../types.__js').Middleware} Middleware
 **/
 
 /**

package/lib/registry/actionEndpoint.js

@@ -1,9 +1,9 @@
 /**
- * @typedef {import("../types.js").Runtime} Runtime
- * @typedef {import("../types.js").Endpoint} Endpoint
- * @typedef {import("../types.js").Node} Node
- * @typedef {import("../types.js").Service} Service
- * @typedef {import("../types.js").ServiceAction} ServiceAction
+ * @typedef {import("../types.__js").Runtime} Runtime
+ * @typedef {import("../types.__js").Endpoint} Endpoint
+ * @typedef {import("../types.__js").Node} Node
+ * @typedef {import("../types.__js").Service} Service
+ * @typedef {import("../types.__js").ServiceAction} ServiceAction
 */
 
 /*

package/lib/registry/collections/actionCollection.js

@@ -7,8 +7,8 @@
 */
 
 /**
- * @typedef {import('../../types.js').Registry} Registry
- * @typedef {import('../../types.js').ServiceActionCollection} ServiceActionCollection
+ * @typedef {import('../../types.__js').Registry} Registry
+ * @typedef {import('../../types.__js').ServiceActionCollection} ServiceActionCollection
 */
 const { omit } = require('@weave-js/utils');
 const { createEndpointList } = require('./endpointCollection');

package/lib/registry/collections/endpointCollection.js

@@ -7,11 +7,11 @@
  */
 
 /**
- * @typedef {import('../../types.js').Runtime} Runtime
- * @typedef {import('../../types.js').EventCollection} EventCollection
- * @typedef {import('../../types.js').Service} Service
- * @typedef {import('../../types.js').Node} Node
- * @typedef {import('../../types.js').EndpointCollection} EndpointCollection
+ * @typedef {import('../../types.__js').Runtime} Runtime
+ * @typedef {import('../../types.__js').EventCollection} EventCollection
+ * @typedef {import('../../types.__js').Service} Service
+ * @typedef {import('../../types.__js').Node} Node
+ * @typedef {import('../../types.__js').EndpointCollection} EndpointCollection
 */
 
 const { createActionEndpoint } = require('../actionEndpoint');

package/lib/registry/collections/eventCollection.js

@@ -7,11 +7,11 @@
 */
 
 /**
- * @typedef {import('../../types.js').Registry} Registry
- * @typedef {import('../../types.js').EventCollection} EventCollection
- * @typedef {import('../../types.js').Service} Service
- * @typedef {import('../../types.js').Node} Node
- * @typedef {import('../../types.js').EndpointCollection} EndpointCollection
+ * @typedef {import('../../types.__js').Registry} Registry
+ * @typedef {import('../../types.__js').EventCollection} EventCollection
+ * @typedef {import('../../types.__js').Service} Service
+ * @typedef {import('../../types.__js').Node} Node
+ * @typedef {import('../../types.__js').EndpointCollection} EndpointCollection
 */
 
 const { omit, match } = require('@weave-js/utils');

package/lib/registry/collections/nodeCollection.js

@@ -7,8 +7,8 @@
  */
 
 /**
- * @typedef {import('../../types.js').Registry} Registry
- * @typedef {import('../../types.js').NodeCollection} NodeCollection
+ * @typedef {import('../../types.__js').Registry} Registry
+ * @typedef {import('../../types.__js').NodeCollection} NodeCollection
 */
 
 const { getIpList, omit } = require('@weave-js/utils');

package/lib/registry/collections/serviceCollection.js

@@ -7,8 +7,8 @@
 */
 
 /**
- * @typedef {import('../../types').Registry} Registry
- * @typedef {import('../../types').ServiceCollection} ServiceCollection
+ * @typedef {import('../../types.__js').Registry} Registry
+ * @typedef {import('../../types.__js').ServiceCollection} ServiceCollection
 */
 
 // const { createEndpointCollection } = require('./endpoint-collection')

package/lib/registry/node.js

@@ -5,7 +5,7 @@
  */
 
 /**
- * @typedef {import('../types.js').Node} Node
+ * @typedef {import('../types.__js').Node} Node
 */
 
 const { cpuUsage } = require('@weave-js/utils');

package/lib/registry/registry.js

@@ -6,17 +6,14 @@
 */
 
 /**
- * @typedef {import('../types.js').Registry} Registry
- * @typedef {import('../types.js').NodeCollection} NodeCollection
- * @typedef {import('../types.js').ServiceCollection} ServiceCollection
- * @typedef {import('../types.js').ServiceActionCollection} ServiceActionCollection
- * @typedef {import('../types.js').EventCollection} EventCollection
- * @typedef {import('../types.js').Runtime} Runtime
- * @typedef {import('../types.js').Broker} Broker
- * @typedef {import('../types.js').Node} Node
- * @typedef {import('../types.js').MiddlewareHandler} MiddlewareHandler
- * @typedef {import('../types.js').ServiceChangedDelegate} ServiceChangedDelegate
-*/
+ * @typedef {import('../../types').Registry} Registry
+ * @typedef {import('../../types').Runtime} Runtime
+ * @typedef {import('../../types').Broker} Broker
+ * @typedef {import('../../types').Node} Node
+ * @typedef {import('../../types').ServiceItem} ServiceItem
+ * @typedef {import('../../types').Endpoint} Endpoint
+ * @typedef {import('../../types').MiddlewareHandler} MiddlewareHandler
+ */
 
 const { safeCopy } = require('@weave-js/utils');
 
@@ -32,10 +29,22 @@ const { WeaveServiceNotFoundError, WeaveServiceNotAvailableError } = require('..
 const noop = () => {};
 
 /**
- * Registry factory
- * @param {Runtime} runtime Runtime
- * @returns {Registry} Registry
-*/
+ * Creates a service registry for managing distributed services and nodes
+ *
+ * The registry is responsible for:
+ * - Tracking available nodes and their services
+ * - Load balancing requests across service instances
+ * - Service discovery and routing
+ * - Handling node lifecycle events (connect/disconnect)
+ * - Managing action and event endpoints
+ *
+ * @param {Runtime} runtime - Weave runtime instance
+ * @returns {Registry} Initialized registry instance with collections and routing logic
+ * @example
+ * const registry = createRegistry(runtime);
+ * registry.registerLocalService(serviceItem);
+ * const endpoint = registry.getNextAvailableActionEndpoint('math.add');
+ */
 exports.createRegistry = (runtime) => {
   const { middlewareHandler } = runtime;
 

package/lib/registry/service/parseAction.js

@@ -1,6 +1,15 @@
-const { isFunction, clone, wrapHandler, isObject, promisify } = require('@weave-js/utils');
+const { isFunction, clone, isObject, promisify } = require('@weave-js/utils');
 const { WeaveError } = require('../../errors');
-
+const { wrapHandler } = require('../../utils/wrap-handler');
+
+/**
+ *
+ * @param {import('../../../types').Runtime} runtime Runtime
+ * @param {import('../../../types').Service} service Service
+ * @param {import('../../../types').ServiceActionSchema} actionDefinition Action definition
+ * @param {string} name
+ * @returns {import('../../../types').ServiceActionDefinition}
+ */
 module.exports.parseAction = (runtime, service, actionDefinition, name) => {
   let action = actionDefinition;
 

package/lib/registry/service/parseEvent.js

@@ -1,4 +1,5 @@
-const { isFunction, clone, wrapHandler, isObject, promisify } = require('@weave-js/utils');
+const { isFunction, clone, isObject, promisify } = require('@weave-js/utils');
+const { wrapHandler } = require('../../utils/wrap-handler');
 const { WeaveError } = require('../../errors');
 
 module.exports.parseEvent = (runtime, service, eventDefinition, name) => {

package/lib/registry/service/service.js

@@ -1,8 +1,9 @@
 /**
- * @typedef {import("../../types").Runtime} Runtime
- * @typedef {import("../../types").ServiceSchema} ServiceSchema
- * @typedef {import("../../types").Service} Service
-*/
+ * @typedef {import("../../../types").Runtime} Runtime
+ * @typedef {import("../../../types").ServiceSchema} ServiceSchema
+ * @typedef {import("../../../types").Service} Service
+ * @typedef {import("../../../types").Context} Context
+ */
 
 const { isFunction, clone, isObject, promisify } = require('@weave-js/utils');
 const { WeaveError } = require('../../errors');
@@ -11,10 +12,30 @@ const { parseEvent } = require('./parseEvent');
 const { reduceMixins } = require('./reduceMixins');
 const { createEventEndpoint } = require('../eventEndpoint');
 /**
- * Service factory
- * @param {Runtime} runtime Broker instance
- * @param {ServiceSchema} schema Service schema
- * @returns {Service} Service instance
+ * Creates a service instance from a service schema definition
+ *
+ * This factory function handles the complete service lifecycle:
+ * - Applies mixins and merges schemas
+ * - Parses and validates actions and events
+ * - Sets up service methods and lifecycle hooks
+ * - Initializes service metadata and settings
+ * - Creates action and event endpoints for the registry
+ *
+ * @param {Runtime} runtime - Weave runtime instance with broker reference
+ * @param {ServiceSchema} schema - Service definition containing actions, events, and configuration
+ * @returns {Service} Fully initialized service instance ready for registration
+ * @throws {WeaveError} When schema is missing or invalid
+ * @example
+ * const service = createServiceFromSchema(runtime, {
+ *   name: 'math',
+ *   version: '1.0.0',
+ *   actions: {
+ *     add: {
+ *       params: { a: 'number', b: 'number' },
+ *       handler: (ctx) => ctx.data.a + ctx.data.b
+ *     }
+ *   }
+ * });
  */
 exports.createServiceFromSchema = (runtime, schema) => {
   // Check if a schema is given

package/lib/registry/serviceItem.js

@@ -6,8 +6,8 @@
 'use strict';
 
 /**
- * @typedef {import("../types").ServiceItem} ServiceItem
- * @typedef {import("../types").Node} Node
+ * @typedef {import("../types.__js").ServiceItem} ServiceItem
+ * @typedef {import("../types.__js").Node} Node
 */
 
 /**

package/lib/runtime/initActionInvoker.js

@@ -1,5 +1,9 @@
 const errors = require('../errors');
 
+/**
+ * Attach action invoker
+ * @param {Partial<import('../../types').Runtime>} runtime Runtime
+ */
 exports.initActionInvoker = (runtime) => {
   const { registry, contextFactory, log, handleError } = runtime;
 
@@ -11,7 +15,7 @@ exports.initActionInvoker = (runtime) => {
    * @returns {Promise} Promise
   */
   const call = (actionName, data, opts = {}) => {
-    const endpoint = registry.getNextAvailableActionEndpoint(actionName, opts);
+    const endpoint = registry?.getNextAvailableActionEndpoint(actionName, opts);
 
     if (endpoint instanceof Error) {
       return Promise.reject(endpoint)

package/lib/runtime/initCache.js

@@ -1,6 +1,10 @@
 const { isFunction } = require('@weave-js/utils');
 const { WeaveError } = require('../errors');
 
+/**
+ * Init Cache
+ * @param {import('../../types').Runtime} runtime Runtime
+ */
 exports.initCache = (runtime) => {
   if (runtime.options.cache && runtime.options.cache.enabled) {
     if (!isFunction(runtime.options.cache.adapter)) {

package/lib/runtime/initContextFactory.js

@@ -7,36 +7,27 @@
 
 const { createContext } = require('../broker/context');
 
-/**
- * @typedef {import('../types').Runtime} Runtime
- * @typedef {import('../types').Context} Context
- * @typedef {import('../types').Endpoint} Endpoint
- * @typedef {import('../types').ActionOptions} ActionOptions
-*/
-
 /**
  * Init context factory.
- * @param {Runtime} runtime - Runtime reference
- * @returns {void}
+ * @param {import('../../types').Runtime} runtime - Runtime reference
 */
 exports.initContextFactory = (runtime) => {
   Object.defineProperty(runtime, 'contextFactory', {
     value: {
       /**
        * Creates a new context
-       * @param {Endpoint} endpoint - Endpoint
-       * @param {any} data - Data
-       * @param {ActionOptions} opts Options
-       * @returns {Context} Context
+       * @param {import('../../types').Endpoint} endpoint - Endpoint
+       * @param {Record<string, any>} data - Data
+       * @param {import('../../types').ActionOptions} opts Options
+       * @returns {import('../../types').Context} Context
       */
-      create (endpoint, data, opts) {
+      create (endpoint, data, opts = {}) {
         const context = createContext(runtime);
 
         if (endpoint) {
           context.setEndpoint(endpoint);
         }
 
-        opts = opts || {};
         context.setData(data);
         // context.timeout = opts.timeout || 0
         context.retryCount = opts.retryCount;

package/lib/runtime/initEventbus.js

@@ -8,7 +8,7 @@ exports.initEventbus = (runtime) => {
    * @param {*} [options=null] - Groups
    * @returns {Promise<any>} - Result
   */
-  const emit = (eventName, payload, options) => {
+  const emit = async (eventName, payload, options) => {
     if (Array.isArray(options)) {
       options = { groups: options };
     } else if (options == null) {
@@ -59,7 +59,17 @@ exports.initEventbus = (runtime) => {
         });
     }
 
-    return Promise.all(promises);
+    // Use allSettled to ensure all events are attempted even if some fail
+    const results = await Promise.allSettled(promises);
+
+    const failures = results.filter(result => result.status === 'rejected');
+    if (failures.length > 0) {
+      failures.forEach(failure => {
+        runtime.log.warn(failure.reason, `Failed to emit event "${eventName}" to remote service`);
+      });
+    }
+
+    return results;
   };
 
   /**
@@ -94,7 +104,7 @@ exports.initEventbus = (runtime) => {
   * @param {*} [options=null] Groups
   * @returns {Promise<any>} Promise
   */
-  const broadcast = (eventName, payload, options) => {
+  const broadcast = async (eventName, payload, options) => {
     if (Array.isArray(options)) {
       options = { groups: options };
     } else if (options == null) {
@@ -124,7 +134,18 @@ exports.initEventbus = (runtime) => {
     }
 
     promises.push(broadcastLocal(eventName, payload, options));
-    return Promise.all(promises);
+
+    // Use allSettled to ensure all broadcasts are attempted even if some fail
+    const results = await Promise.allSettled(promises);
+
+    const failures = results.filter(result => result.status === 'rejected');
+    if (failures.length > 0) {
+      failures.forEach(failure => {
+        runtime.log.warn(failure.reason, `Failed to broadcast event "${eventName}" to remote service`);
+      });
+    }
+
+    return results;
   };
 
   Object.defineProperty(runtime, 'eventBus', {