@weave-js/core 0.15.3 → 0.16.0

package/lib/runtime/initLogger.js

@@ -1,19 +1,29 @@
-/**
- * @typedef {import('../types.js').Runtime} Runtime
- * @typedef {import('../types.js').Broker} Broker
- * @typedef {import('../types.js').Transport} Transport
-*/
 
 const { defaultsDeep } = require('@weave-js/utils');
 const { createLogger: createDefaultLogger } = require('../logger/index');
 
 /**
- * Init logger
- * @param {Runtime} runtime - Runtime reference
+ * Initializes the logging subsystem for the runtime
+ *
+ * Creates a logger factory that can generate module-specific loggers with consistent formatting
+ * and configuration. Supports both custom logger functions and built-in logger with configurable
+ * levels, formatting, and output destinations.
+ *
+ * @param {import("../../types").Runtime} runtime - Runtime instance to initialize logger for
  * @returns {void}
+ * @example
+ * initLogger(runtime);
+ * const moduleLogger = runtime.createLogger('SERVICE-MANAGER');
+ * moduleLogger.info('Service initialized');
  */
 exports.initLogger = (runtime) => {
-  const loggerFactory = (runtime, moduleName, additional = {}) => {
+  /**
+   * Factory function to create module-specific loggers
+   * @param {string} moduleName - Name of the module requesting a logger
+   * @param {object} [additional={}] - Additional metadata to include in log entries
+   * @returns {import("../../types").Logger} Configured logger instance
+   */
+  const loggerFactory = (moduleName, additional = {}) => {
     const bindings = {
       nodeId: runtime.options.nodeId,
       moduleName,
@@ -21,7 +31,7 @@ exports.initLogger = (runtime) => {
     };
 
     if (typeof runtime.options.logger === 'function') {
-      return runtime.options.logger(bindings, runtime.options.logger.level);
+      return runtime.options.logger(bindings, runtime.options.logger);
     }
 
     const loggerOptions = defaultsDeep({
@@ -33,8 +43,18 @@ exports.initLogger = (runtime) => {
     return createDefaultLogger(loggerOptions);
   };
 
-  const createLogger = (moduleName, service) => loggerFactory(runtime, moduleName, service);
+  /**
+   * Public API for creating loggers
+   * @param {string} moduleName - Name of the module requesting a logger
+   * @param {object} [service] - Service context for additional metadata
+   * @returns {import("../../types").Logger} Configured logger instance
+   */
+  const createLogger = (moduleName, service) => loggerFactory(moduleName, service);
 
+  /**
+   * Main runtime logger instance
+   * @type {import("../../types").Logger}
+   */
   const log = createLogger('WEAVE');
 
   Object.assign(runtime, {

package/lib/runtime/initMetrics.js

@@ -3,19 +3,15 @@ const { WeaveError } = require('../errors');
 const { registerCommonMetrics, updateCommonMetrics } = require('../metrics/common');
 const MetricTypes = require('../metrics/types');
 
-/**
- * @typedef {import('../types.js').Runtime} Runtime
-*/
-
 /**
  * Init metrics module
- * @param {Runtime} runtime - Runtime reference
+ * @param {import('../../types').Runtime} runtime - Runtime reference
  * @returns {void}
  */
 exports.initMetrics = (runtime) => {
   const metricOptions = runtime.options.metrics;
 
-  if (metricOptions.enabled) {
+  if (metricOptions?.enabled) {
     const storage = new Map();
 
     const log = runtime.createLogger('METRICS');
@@ -41,12 +37,26 @@ exports.initMetrics = (runtime) => {
             });
           }
         },
-        stop () {
+        async stop () {
           if (commonUpdateTimer) {
             clearInterval(commonUpdateTimer);
           }
 
-          return Promise.all(this.adapters.map(adapter => adapter.stop()));
+          if (!this.adapters || this.adapters.length === 0) {
+            return;
+          }
+
+          const results = await Promise.allSettled(this.adapters.map(adapter => adapter.stop()));
+          const failures = results.filter(result => result.status === 'rejected');
+
+          if (failures.length > 0) {
+            failures.forEach(failure => {
+              log.warn(failure.reason, 'Failed to stop metrics adapter');
+            });
+            log.warn(`Failed to stop ${failures.length} of ${this.adapters.length} metrics adapters`);
+          }
+
+          return results;
         },
         register (obj) {
           if (!isPlainObject(obj)) {

package/lib/runtime/initRegistry.js

@@ -5,7 +5,7 @@
  * Copyright 2021 Fachwerk
 */
 /**
- * @typedef {import('../types').Runtime} Runtime
+ * @typedef {import('../types.__js').Runtime} Runtime
 */
 const { createRegistry } = require('../registry/registry.js');
 

package/lib/runtime/initServiceManager.js

@@ -1,6 +1,10 @@
 const { createServiceFromSchema } = require('../registry/service/service.js');
 const { WeaveError } = require('../errors');
 
+/**
+ *
+ * @param {import('../../types/index.js').Runtime} runtime
+ */
 exports.initServiceManager = (runtime) => {
   const { options, log, eventBus, transport, state, registry, handleError } = runtime;
 

package/lib/runtime/initTracing.js

@@ -1,6 +1,10 @@
 const { resolveCollector } = require('../tracing/collectors');
 const { Span } = require('../tracing/span');
 
+/**
+ * Init tracer
+ * @param {import('../../types').Runtime} runtime Runtime
+ */
 exports.initTracer = (runtime) => {
   const options = runtime.options.tracing;
   const log = runtime.createLogger('TRACER');
@@ -37,7 +41,7 @@ exports.initTracer = (runtime) => {
       invokeCollectorMethod (method, args) {
         collectors.map(collector => collector[method].apply(collector, args));
       },
-      startSpan (name, spanOptions) {
+      startSpan (name, spanOptions = {}) {
         const parentOptions = {};
 
         if (spanOptions.parentSpan) {

package/lib/runtime/initTransport.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../types').TransportAdapter} TransportAdapter
+ * @typedef {import('../types.__js').TransportAdapter} TransportAdapter
 **/
 
 const { createTransport } = require('../transport/createTransport');

package/lib/runtime/initUuidFactory.js

@@ -1,12 +1,8 @@
-/**
- * @typedef {import('../types.js').Runtime} Runtime
-*/
-
 const { isFunction, uuid } = require('@weave-js/utils');
 
 /**
  * Init uuid Generator and attach it to our runtime object.
- * @param {Runtime} runtime Runtime object.
+ * @param {import('../../types').Runtime} runtime Runtime object.
  * @returns {void}
 */
 exports.initUUIDFactory = (runtime) => {

package/lib/runtime/initValidator.js

@@ -4,16 +4,11 @@
  * Copyright 2021 Fachwerk
 */
 
-/**
- * @typedef {import('../types.js').Runtime} Runtime
-*/
-
 const ObjectValidator = require('@weave-js/validator');
 
 /**
  * Init validator and attach it to our runtime object.
- * @param {Runtime} runtime Runtime object.
- * @returns {void}
+ * @param {import('../../types').Runtime} runtime Runtime object.
 */
 exports.initValidator = (runtime) => {
   const validator = ObjectValidator();

package/lib/tracing/collectors/base.js

@@ -1,5 +1,10 @@
 const { isObject, pick } = require('@weave-js/utils');
 
+/**
+ * Create a base tracing collector
+ * @param {import('../../../types').Runtime} runtime
+ * @returns {import('../../../types').TracingCollector}
+ */
 exports.createBaseTracingCollector = (runtime) => {
   const baseTracingCollector = Object.create(null);
 
@@ -22,6 +27,13 @@ exports.createBaseTracingCollector = (runtime) => {
     // throw new WeaveError('not implemented.')
   };
 
+  /**
+   * Flatten an object.
+   * @param {object} obj Object
+   * @param {boolean?} convertToString
+   * @param {string?} path
+   * @returns {object}
+   */
   baseTracingCollector.flattenTags = (obj, convertToString = false, path = '') => {
     if (!obj) {
       return null;
@@ -41,11 +53,17 @@ exports.createBaseTracingCollector = (runtime) => {
     }, {});
   };
 
-  baseTracingCollector.getErrorFields = (err, fields) => {
-    if (!err) {
+  /**
+   * Get fields of an error object.
+   * @param {Error} error Error
+   * @param {string[]} fields
+   * @returns
+   */
+  baseTracingCollector.getErrorFields = (error, fields) => {
+    if (!error) {
       return null;
     }
-    return pick(err, fields);
+    return pick(error, fields);
   };
 
   return baseTracingCollector;

package/lib/tracing/collectors/event.js

@@ -1,5 +1,10 @@
 const { createBaseTracingCollector } = require('./base');
 
+/**
+ * Merge options wirh default options.
+ * @param {import('../../../types').TracingOptions} options
+ * @returns {import('../../../types').TracingOptions}
+ */
 const mergeDefaultOptions = (options) => {
   return Object.assign({
     interval: 5000,
@@ -10,6 +15,11 @@ const mergeDefaultOptions = (options) => {
   }, options);
 };
 
+/**
+ * Create event collector for tracing
+ * @param {import('../../../types').TracingOptions} options
+ * @returns {(runtime: import('../../broker').Runtime, tracer: any) => import('../../../types').TracingCollector}
+ */
 module.exports = (options) => (runtime, tracer) => {
   options = mergeDefaultOptions(options);
 

package/lib/tracing/collectors/index.js

@@ -1,3 +1,17 @@
+/**
+ * Tracing collectors for distributed tracing and observability
+ *
+ * Provides pluggable collectors that capture and export trace data:
+ * - Event: Event-based collector that emits trace spans as events
+ * - BaseCollector: Abstract base class for custom collector implementations
+ *
+ * Collectors can be resolved by name (string) or provided as constructor functions/instances.
+ * They handle span lifecycle management, trace context propagation, and data export
+ * to various observability backends like Jaeger, Zipkin, or custom systems.
+ *
+ * @namespace TracingCollectors
+ */
+
 const { isFunction } = require('@weave-js/utils');
 
 const collectors = {
@@ -5,11 +19,30 @@ const collectors = {
   BaseCollector: require('./base')
 };
 
-const getByName = name => {
+/**
+ * Get a tracing collector by name (case-insensitive lookup)
+ * @param {string} name Tracing collector name (e.g., 'Event', 'BaseCollector')
+ * @returns {import('../../../types').TracingCollector} The collector constructor or undefined if not found
+ */
+const getByName = (name) => {
   const n = Object.keys(collectors).find(collectorName => collectorName.toLowerCase() === name.toLowerCase());
   return collectors[n];
 };
 
+/**
+ * Resolve a tracing collector by name, function, or object
+ *
+ * Supports multiple collector resolution patterns:
+ * - String: Looks up collector by name ('Event', 'BaseCollector')
+ * - Function: Calls function with runtime to get collector instance
+ * - Object: Returns object directly as collector instance
+ * - Constructor: Instantiates with new operator
+ *
+ * @param {import('../../../types').Runtime} runtime Runtime instance for collector initialization
+ * @param {string | Function | Object | import('../../../types').TracingCollector} collector Tracing collector specification
+ * @returns {import('../../../types').TracingCollector} Resolved collector instance
+ * @throws {Error} When collector cannot be resolved or is not found
+ */
 exports.resolveCollector = (runtime, collector) => {
   let CollectorClass;
   if (typeof collector === 'string') {

package/lib/transport/adapters/adapterBase.js

@@ -4,6 +4,8 @@
  * Copyright 2021 Fachwerk
  */
 
+const { WeavePacketSizeLimitExceeded } = require('../../errors');
+
 const EventEmitter = require('events').EventEmitter;
 
 /**
@@ -15,12 +17,12 @@ const EventEmitter = require('events').EventEmitter;
  * @property {number} interruptCounter Interruption counter.
  * @property {number} repeatAttemptCounter Repeat attempt counter
  * @property {function(Object, Object, Object):Promise<any>} init Repeat attempt counter
-*/
+ */
 
 /**
  * Create a adapter base object.
  * @returns {AdapterBase} Adapter base object
-*/
+ */
 const createTransportBase = () => {
   let prefix = 'weave';
 
@@ -57,7 +59,7 @@ const createTransportBase = () => {
      * @param {*} connectionEventParams Connection event
      * @param {boolean} [startHeartbeatTimers=true] Start timers for this adapter
      * @returns {void}
-    */
+     */
     connected (connectionEventParams = {}) {
       this.bus.emit('$adapter.connected', connectionEventParams);
     },
@@ -82,7 +84,15 @@ const createTransportBase = () => {
     serialize (packet) {
       try {
         packet.payload.sender = this.broker.nodeId;
-        return Buffer.from(JSON.stringify(packet));
+        const payloadBuffer = Buffer.from(JSON.stringify(packet));
+        const maxPayloadSize = this.broker.options.transport.maxPayloadSize
+        if (maxPayloadSize && payloadBuffer.byteLength > maxPayloadSize) {
+          this.log.warn({ type: packet.payload.type,  })
+          if (this.broker.options.transport.rejectLargePayloadSize) {
+            throw new WeavePacketSizeLimitExceeded(packet.payload.type, payloadBuffer.byteLength, maxPayloadSize);
+          }
+        }
+        return payloadBuffer;
       } catch (error) {
         this.broker.handleError(error);
       }

package/lib/transport/adapters/fromURI.js

@@ -6,30 +6,38 @@
 const { parse } = require('url');
 const getAdapterByName = require('./getAdapterByName');
 
-function fromURI (uri) {
-  if (typeof uri !== 'string') {
-    throw new Error('URI needs to be a string.');
+function fromURI (uri, handleError) {
+  try {
+    if (typeof uri !== 'string') {
+      throw new Error('URI needs to be a string.');
+    }
+
+    const urlObject = parse(uri);
+
+    if (!urlObject.protocol) {
+      throw new Error('Protocol is missing.');
+    }
+
+    const name = urlObject.protocol.slice(0, -1).toLowerCase();
+
+    const AdapterFactory = getAdapterByName(name);
+
+    if (!AdapterFactory) {
+      throw new Error('No adapter found.');
+    }
+
+    let config = null;
+    if (AdapterFactory.uriToConfig) {
+      config = AdapterFactory.uriToConfig(urlObject);
+    }
+    return AdapterFactory(config);
+  } catch (error) {
+    if (typeof handleError === 'function') {
+      handleError(error);
+      return null;
+    }
+    throw error;
   }
-
-  const urlObject = parse(uri);
-
-  if (!urlObject.protocol) {
-    throw new Error('Protocol is missing.');
-  }
-
-  const name = urlObject.protocol.slice(0, -1).toLowerCase();
-
-  const AdapterFactory = getAdapterByName(name);
-
-  if (!AdapterFactory) {
-    throw new Error('No adapter found.');
-  }
-
-  let config = null;
-  if (AdapterFactory.uriToConfig) {
-    config = AdapterFactory.uriToConfig(urlObject);
-  }
-  return AdapterFactory(config);
 }
 
 module.exports = fromURI;

package/lib/transport/createTransport.js

@@ -5,12 +5,13 @@
  */
 
 /**
- * @typedef {import('../types').Runtime} Runtime
- * @typedef {import('../types.js').TransportAdapter} TransportAdapter
- * @typedef {import('../types.js').Transport} Transport
- * @typedef {import('../types').TransportMessage} TransportMessage
- * @typedef {import('../types').Context} Context
-*/
+ * @typedef {import('../../types').Runtime} Runtime
+ * @typedef {import('../../types').Transport} Transport
+ * @typedef {import('../../types').TransportMessage} TransportMessage
+ * @typedef {import('../../types').Context} Context
+ * @typedef {import('../../types').Node} Node
+ * @typedef {import('../../types').PendingStore} PendingStore
+ */
 
 // Own packages
 const { WeaveError, WeaveQueueSizeExceededError } = require('../errors');
@@ -21,11 +22,25 @@ const createMessageHandler = require('./messageHandlers');
 const { errorPayloadFactory } = require('./errorPayloadFactory');
 
 /**
- * Create a Transport adapter
- * @param {Runtime} runtime Broker instance
- * @param {TransportAdapter} adapter Adapter wrapper
- * @returns {Transport} transport
-*/
+ * Creates a transport layer for network communication between Weave nodes
+ *
+ * The transport handles:
+ * - Network connections between nodes
+ * - Message serialization and deserialization
+ * - Request/response lifecycle management
+ * - Stream handling for large payloads
+ * - Heartbeat and node discovery
+ * - Connection reconnection and error recovery
+ * - Load balancing and routing
+ *
+ * @param {Runtime} runtime - Weave runtime instance
+ * @param {any} adapter - Transport adapter implementation (TCP, NATS, Redis, etc.)
+ * @returns {Transport} Configured transport instance with messaging capabilities
+ * @example
+ * const tcpAdapter = require('./adapters/tcp');
+ * const transport = createTransport(runtime, tcpAdapter);
+ * await transport.connect();
+ */
 exports.createTransport = (runtime, adapter) => {
   const transport = Object.create(null);
   const { nodeId, middlewareHandler, createLogger } = runtime;
@@ -54,10 +69,12 @@ exports.createTransport = (runtime, adapter) => {
   transport.adapterName = adapter.name;
   transport.statistics = {
     received: {
-      packages: 0
+      packages: 0,
+      bytes: 0
     },
     sent: {
-      packages: 0
+      packages: 0,
+      bytes: 0
     }
   };
 

package/lib/transport/messageHandlers.js

@@ -12,9 +12,9 @@ const MessageTypes = require('./messageTypes');
 const { restoreError } = require('../utils/restoreError');
 
 /**
- * @typedef {import('../types').Transport} Transport
- * @typedef {import('../types').Runtime} Runtime
- * @typedef {import('../types').TransportMessageHandler} TransportMessageHandler
+ * @typedef {import('../types.__js').Transport} Transport
+ * @typedef {import('../types.__js').Runtime} Runtime
+ * @typedef {import('../types.__js').TransportMessageHandler} TransportMessageHandler
 */
 
 /**

package/lib/utils/index.js

@@ -1,5 +1,21 @@
 
+/**
+ * Utility functions for Weave framework internal operations
+ *
+ * Provides common utilities for:
+ * - Options processing and default merging
+ * - Error restoration from serialized format
+ * - Handler wrapping for middleware integration
+ *
+ * These utilities are used internally by the framework and are not part
+ * of the public API. They handle low-level operations like configuration
+ * processing, error handling, and function composition.
+ *
+ * @namespace Utils
+ */
+
 exports = {
   ...require('./options'),
-  ...require('./restoreError')
+  ...require('./restoreError'),
+  ...require('./wrap-handler')
 };

package/lib/utils/options.js

@@ -1,25 +1,54 @@
+/**
+ * @typedef {import('../../types').ServiceSchema} ServiceSchema
+ */
+
 const {
   clone,
   compact,
   deepMerge,
   defaultsDeep,
   flatten,
-  wrapHandler,
   wrapInArray
 } = require('@weave-js/utils');
 
+const { wrapHandler } = require('../utils/wrap-handler');
+
+/**
+ * Merge service settings with deep default merging
+ * @param {Object} source Source settings object
+ * @param {Object} targetSchema Target schema settings
+ * @returns {Object} Merged settings object
+ */
 function mergeSettings (source, targetSchema) {
   return defaultsDeep(source, targetSchema);
 }
 
+/**
+ * Merge service metadata with deep default merging
+ * @param {Object} source Source metadata object
+ * @param {Object} targetSchema Target schema metadata
+ * @returns {Object} Merged metadata object
+ */
 function mergeMeta (source, targetSchema) {
   return defaultsDeep(source, targetSchema);
 }
 
+/**
+ * Merge arrays ensuring unique values
+ * @param {Array} source Source array
+ * @param {Array} targetSchema Target schema array
+ * @returns {Array} Flattened and compacted unique array
+ */
 function mergeUniqueArrays (source, targetSchema) {
   return compact(flatten([targetSchema, source]));
 }
 
+/**
+ * Merge service actions with handler wrapping and conflict resolution
+ * @param {Object} source Source actions object
+ * @param {Object} targetSchema Target schema actions
+ * @returns {Object} Merged actions object with wrapped handlers
+ */
 function mergeActions (source, targetSchema) {
   Object.keys(source).map(key => {
     // prevent action merge
@@ -37,7 +66,12 @@ function mergeActions (source, targetSchema) {
   return targetSchema;
 }
 
-// Merge events
+/**
+ * Merge service events with handler composition
+ * @param {Object} source Source events object
+ * @param {Object} targetSchema Target schema events
+ * @returns {Object} Merged events object with composed handlers
+ */
 function mergeEvents (source, targetSchema) {
   Object.keys(source).map(key => {
     const sourceEvent = wrapHandler(source[key]);
@@ -54,10 +88,22 @@ function mergeEvents (source, targetSchema) {
   return targetSchema;
 }
 
+/**
+ * Merge service methods by object assignment
+ * @param {Object} source Source methods object
+ * @param {Object} targetSchema Target schema methods
+ * @returns {Object} Merged methods object
+ */
 function mergeMethods (source, targetSchema) {
   return Object.assign(source, targetSchema);
 }
 
+/**
+ * Merge action hooks by combining hook arrays
+ * @param {Object} source Source action hooks object
+ * @param {Object} target Target action hooks object
+ * @returns {Object} Merged action hooks with combined arrays
+ */
 function mergeActionHooks (source, target) {
   Object.keys(source).map(hookName => {
     if (!target[hookName]) {
@@ -74,10 +120,32 @@ function mergeActionHooks (source, target) {
   return target;
 }
 
+/**
+ * Merge lifecycle hooks into a flattened array
+ * @param {Array|Function} source Source lifecycle hooks
+ * @param {Array|Function} targetSchema Target schema lifecycle hooks
+ * @returns {Array} Flattened and compacted lifecycle hooks array
+ */
 function mergeLifecicleHooks (source, targetSchema) {
   return compact(flatten([targetSchema, source]));
 }
 
+/**
+ * Merge service schemas with comprehensive property handling
+ *
+ * Handles different merge strategies for various schema properties:
+ * - name, version: Override values
+ * - dependencies, mixins: Merge unique arrays
+ * - settings, meta: Deep merge objects
+ * - actions, events: Merge with handler wrapping
+ * - hooks: Merge action hooks by combining arrays
+ * - lifecycle hooks: Flatten into arrays
+ * - methods: Object assignment
+ *
+ * @param {ServiceSchema} mixin Mixin service schema
+ * @param {ServiceSchema} targetSchema Target service schema to merge into
+ * @returns {ServiceSchema} Merged service schema with combined properties
+ */
 function mergeSchemas (mixin, targetSchema) {
   const mixinSchema = clone(mixin);
   const resultSchema = clone(targetSchema);