@weave-js/core 0.15.3 → 0.16.0

package/lib/broker/context.js

@@ -5,25 +5,18 @@
 */
 'use strict';
 
-/**
- * @typedef {import('../types').Context} Context
- * @typedef {import('../types').Runtime} Runtime
- * @typedef {import('../types').ContextPromise} ContextPromise
- * @typedef {import('../types').Endpoint} Endpoint
-*/
-
 const { uuid, isFunction, isStream, isStreamObjectMode } = require('@weave-js/utils');
 const { WeaveMaxCallLevelError, WeaveError } = require('../errors');
 
 /**
  * Create a new context object
- * @param {Runtime} runtime Runtime reference
- * @returns {Context} Context
+ * @param {import('../../types').Runtime} runtime Runtime reference
+ * @returns {import('../../types').Context} Context
 */
 exports.createContext = (runtime) => {
   const spanStack = [];
 
-  /** @type {Context} */
+  /** @type {import('../../types').Context} */
   const context = {
     id: null,
     nodeId: runtime.nodeId || null,
@@ -119,7 +112,7 @@ exports.createContext = (runtime) => {
     },
     /**
      * Copy the current context.
-     * @returns {Context} New copied context
+     * @returns {import('../../types').Context} New copied context
     */
     copy () {
       const contextCopy = exports.createContext(runtime);

package/lib/broker/defaultOptions.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../types.js').BrokerOptions} BrokerOptions
+ * @typedef {import('../types.__js').BrokerOptions} BrokerOptions
 */
 
 /*
@@ -56,7 +56,8 @@ exports.getDefaultOptions = () => {
       maxChunkSize: 256 * 1024,
       streams: {
         handleBackpressure: true
-      }
+      },
+      rejectLargePayloadSize: false,
     },
     errorHandler: undefined,
     loadInternalMiddlewares: true,

package/lib/broker/index.js

@@ -1,9 +1,11 @@
 /**
- * @typedef {import('../types.js').Runtime} Runtime
- * @typedef {import('../types.js').BrokerOptions} BrokerOptions
- * @typedef {import('../types.js').Broker} Broker
- * @typedef {import('../types.js').Transport} Transport
-*/
+ * @typedef {import('../../types').Runtime} Runtime
+ * @typedef {import('../../types').BrokerOptions} BrokerOptions
+ * @typedef {import('../../types').Broker} Broker
+ * @typedef {import('../../types').Transport} Transport
+ * @typedef {import('../../types').Service} Service
+ * @typedef {import('../../types').ServiceSchema} ServiceSchema
+ */
 
 const { isFunction } = require('@weave-js/utils');
 const path = require('path');
@@ -11,10 +13,10 @@ const glob = require('glob');
 const Middlewares = require('../middlewares');
 
 /**
- * Creates a new Weave Broker instance
- * @param {Runtime} runtime - Weave runtime.
- * @returns {Broker} Broker instance
-*/
+ * Creates a new Weave Broker instance from the provided runtime
+ * @param {Runtime} runtime - Initialized Weave runtime containing all core components
+ * @returns {Broker} A fully configured Broker instance ready for use
+ */
 exports.createBrokerInstance = (runtime) => {
   const {
     version,
@@ -82,19 +84,30 @@ exports.createBrokerInstance = (runtime) => {
   broker.createService = services.createService.bind(broker);
 
   /**
-   * Global error handler of the broker.
-   * @param {*} error Error
+   * Global error handler for the broker. Processes non-fatal errors and passes them to the configured error handler.
+   * @param {Error} error - The error to handle
    * @returns {void}
-  */
+   */
   broker.handleError = runtime.handleError;
 
+  /**
+   * Fatal error handler that triggers graceful shutdown. Should only be used for unrecoverable errors.
+   * @param {string} [message] - Error message describing the fatal condition
+   * @param {Error} [error] - The underlying error that caused the fatal condition
+   * @param {boolean} [killProcess=true] - Whether to terminate the process after cleanup
+   * @returns {void}
+   */
   broker.fatalError = runtime.fatalError;
 
   /**
-  * Load and register a service from file.
-  * @param {string} filename Path to the service file.
-  * @returns {Service} Service
-  */
+   * Loads and registers a service from a file path. The file should export a service schema.
+   * @param {string} filename - Absolute or relative path to the service file
+   * @returns {Service} The created and registered service instance
+   * @throws {Error} When the service file cannot be loaded or contains invalid schema
+   * @example
+   * // Load a service from a file
+   * const service = broker.loadService('./services/math.service.js');
+   */
   broker.loadService = function (filename) {
     const filePath = path.resolve(filename);
     const schema = require(filePath);
@@ -129,12 +142,37 @@ exports.createBrokerInstance = (runtime) => {
       await transport.connect();
     }
 
-    try {
-      await Promise.all(services.serviceList.map(service => service.start()));
-    } catch (error) {
-      log.error(error, 'Unable to start all services');
+    // Start services using Promise.allSettled to continue even if some fail
+    const serviceStartResults = await Promise.allSettled(
+      services.serviceList.map(service => service.start())
+    );
+
+    const failedServices = serviceStartResults
+      .map((result, index) => ({ result, service: services.serviceList[index] }))
+      .filter(({ result }) => result.status === 'rejected');
+
+    if (failedServices.length > 0) {
+      const errorMessage = `Failed to start ${failedServices.length} of ${services.serviceList.length} services`;
+
+      failedServices.forEach(({ result, service }) => {
+        log.error(result.reason, `Unable to start service "${service.name}"`);
+      });
+
       clearInterval(options.waitForServiceInterval);
-      throw error;
+
+      // If critical services failed, throw error to prevent startup
+      if (failedServices.some(({ service }) => service.schema.critical !== false)) {
+        const criticalFailures = failedServices.filter(({ service }) => service.schema.critical !== false);
+
+        // If only one service failed, preserve the original error message for compatibility
+        if (criticalFailures.length === 1 && services.serviceList.length === 1) {
+          throw criticalFailures[0].result.reason;
+        } else {
+          throw new Error(`${errorMessage}. Critical services failed: ${criticalFailures.map(({ service }) => service.name).join(', ')}`);
+        }
+      } else {
+        log.warn(`${errorMessage}, but continuing startup as no critical services failed`);
+      }
     }
 
     runtime.state.isStarted = true;
@@ -165,11 +203,27 @@ exports.createBrokerInstance = (runtime) => {
 
     await middlewareHandler.callHandlersAsync('stopping', [runtime], true);
 
-    try {
-      await Promise.all(services.serviceList.map(service => service.stop()));
-    } catch (error) {
-      log.error(error, 'Unable to stop all services.');
-      throw error;
+    // Stop services using Promise.allSettled to attempt stopping all services
+    const serviceStopResults = await Promise.allSettled(
+      services.serviceList.map(service => service.stop())
+    );
+
+    const failedStops = serviceStopResults
+      .map((result, index) => ({ result, service: services.serviceList[index] }))
+      .filter(({ result }) => result.status === 'rejected');
+
+    if (failedStops.length > 0) {
+      failedStops.forEach(({ result, service }) => {
+        log.error(result.reason, `Unable to stop service "${service.name}"`);
+      });
+
+      // If only one service and it failed, preserve original error for compatibility
+      if (failedStops.length === 1 && services.serviceList.length === 1) {
+        throw failedStops[0].result.reason;
+      } else {
+        log.error(`Failed to stop ${failedStops.length} of ${services.serviceList.length} services, but continuing shutdown`);
+        // Continue with shutdown process rather than throwing
+      }
     }
 
     if (transport) {

package/lib/broker/public.d.ts

@@ -75,6 +75,8 @@ export type TransportOptions = {
   maxOfflineTime: number;
   maxChunkSize: number;
   streams: TransportStreamOptions;
+  maxPayloadSize: number;
+  rejectLargePayloadSize: boolean;
 }
 
 export type TransportStreamOptions = {
@@ -117,4 +119,3 @@ export type Broker = {
   handleError(err: Error): void;
   fatalError(err: Error): void;
 }
-

package/lib/buildRuntime.js

@@ -1,9 +1,3 @@
-/**
- * @typedef {import('./types.js').BrokerOptions} BrokerOptions
- * @typedef {import('./types.js').Runtime} Runtime
- * @typedef {import('./types.js').Broker} Broker
-*/
-
 const { initLogger } = require('./runtime/initLogger');
 const { initMiddlewareHandler } = require('./runtime/initMiddlewareManager');
 const { initRegistry } = require('./runtime/initRegistry');
@@ -23,20 +17,43 @@ const { version } = require('../package.json');
 const EventEmitter = require('eventemitter2');
 
 /**
- * Build runtime object
- * @param {BrokerOptions} options Broker options
- * @return {Runtime} Runtime
-*/
+ * Initializes and builds the complete Weave runtime with all core components
+ *
+ * The runtime contains all the core subsystems needed for a Weave broker:
+ * - Logger: Configurable logging system
+ * - Middleware: Request/response processing pipeline
+ * - Registry: Service discovery and load balancing
+ * - Context Factory: Request context creation
+ * - Event Bus: Pub/sub messaging system
+ * - Transport: Network communication layer
+ * - Cache: Distributed caching
+ * - Metrics: Performance monitoring
+ * - Tracing: Distributed tracing
+ *
+ * @param {import('../types').BrokerOptions} options - Broker configuration options
+ * @returns {import('../types').Runtime} Fully initialized runtime instance
+ * @example
+ * const runtime = initRuntime({
+ *   nodeId: 'my-service',
+ *   logger: { level: 'info' },
+ *   transport: { adapter: 'TCP' }
+ * });
+ */
 exports.initRuntime = (options) => {
   /**
-   * Event bus
-   * @returns {EventEmitter} Service object.
-  */
+   * Internal event bus for broker communication
+   * Supports wildcard patterns and high listener count for complex service topologies
+   * @type {EventEmitter}
+   */
   const bus = new EventEmitter({
     wildcard: true,
     maxListeners: 1000
   });
 
+  /**
+   * Core runtime object containing all initialized subsystems
+   * @type {import('../types').Runtime}
+   */
   const runtime = {
     nodeId: options.nodeId,
     version,

package/lib/cache/adapters/index.js

@@ -4,6 +4,20 @@
  * Copyright 2021 Fachwerk
  */
 
+/**
+ * Built-in cache adapter implementations
+ *
+ * Provides various caching backends:
+ * - Base: Abstract base cache implementation
+ * - InMemory: High-performance in-memory cache with LRU eviction
+ *
+ * Additional adapters available as separate packages:
+ * - Redis: Distributed Redis cache
+ * - Memcached: Memcached integration
+ * - File: File-based persistent cache
+ *
+ * @namespace CacheAdapters
+ */
 module.exports = {
   ...require('./base'),
   ...require('./inMemory')

package/lib/cache/lock.js

@@ -1,10 +1,20 @@
 const createLock = () => {
   const locked = new Map();
+  const timeouts = new Map();
 
   function acquire (key, ttl) {
     const lockedItems = locked.get(key);
     if (!lockedItems) {
       locked.set(key, []);
+      
+      // Set up TTL timeout if provided
+      if (ttl && ttl > 0) {
+        const timeoutId = setTimeout(() => {
+          release(key);
+        }, ttl);
+        timeouts.set(key, timeoutId);
+      }
+      
       return Promise.resolve();
     } else {
       return new Promise((resolve) => lockedItems.push(resolve));
@@ -18,6 +28,13 @@ const createLock = () => {
   function release (key) {
     const lockedItems = locked.get(key);
     if (lockedItems) {
+      // Clear TTL timeout if exists
+      const timeoutId = timeouts.get(key);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeouts.delete(key);
+      }
+      
       if (lockedItems.length > 0) {
         lockedItems.shift()();
       } else {

package/lib/errorHandler.js

@@ -6,7 +6,7 @@ exports.errorHandler = ({ options }, error) => {
 };
 
 exports.fatalErrorHandler = (runtime, message, error, killProcess = true) => {
-  const { options, log } = runtime;
+  const { options, log, broker } = runtime;
   if (options.logger.enabled) {
     log.fatal({ error }, message);
   } else {
@@ -14,6 +14,31 @@ exports.fatalErrorHandler = (runtime, message, error, killProcess = true) => {
   }
 
   if (killProcess) {
-    process.exit(1);
+    // Graceful shutdown instead of immediate process.exit
+    if (broker && runtime.state && runtime.state.isStarted) {
+      log.warn('Attempting graceful shutdown due to fatal error...');
+
+      // Set a timeout to prevent hanging indefinitely
+      const shutdownTimeout = setTimeout(() => {
+        log.error('Graceful shutdown timed out, forcing exit');
+        process.exit(1);
+      }, 10000); // 10 second timeout
+
+      broker.stop()
+        .then(() => {
+          clearTimeout(shutdownTimeout);
+          log.info('Graceful shutdown completed');
+          process.exit(1);
+        })
+        .catch((shutdownError) => {
+          clearTimeout(shutdownTimeout);
+          log.error('Graceful shutdown failed:', shutdownError);
+          process.exit(1);
+        });
+    } else {
+      // Fallback to immediate exit if broker not available or not started
+      log.warn('Broker not started or unavailable, performing immediate exit');
+      process.exit(1);
+    }
   }
 };

package/lib/errors.js

@@ -141,6 +141,15 @@ class WeaveGracefulStopTimeoutError extends WeaveError {
   }
 }
 
+class WeavePacketSizeLimitExceeded extends WeaveError {
+  constructor(messageType, packageSize, limit) {
+    super(
+      `Packet size limit exceeded: ${packageSize} bytes (max ${limit}). Type: ${messageType}`,
+      { code: 'WEAVE_PACKAGE_SIZE_LIMIT_EXCEEDED' }
+    )
+  }
+}
+
 module.exports = {
   WeaveBrokerOptionsError,
   WeaveMaxCallLevelError,
@@ -151,5 +160,6 @@ module.exports = {
   WeaveRetryableError,
   WeaveServiceNotAvailableError,
   WeaveServiceNotFoundError,
-  WeaveGracefulStopTimeoutError
+  WeaveGracefulStopTimeoutError,
+  WeavePacketSizeLimitExceeded
 };

package/lib/helper/defineAction.js

@@ -1,14 +1,29 @@
-/* istanbul ignore next */
-
 /**
- * @typedef {import('../types.js').ServiceActionDefinition} ServiceActionDefinition
+ * @import { ServiceActionSchema,TypeMap } from '@weave-js/core'
 */
 
 /**
- * Create and register a new service action.
- * @param {ServiceActionDefinition} actionDefinition - Schema of the the action
- * @returns {ServiceActionDefinition} Action definition
+ * Helper function to define a service action with proper TypeScript inference
+ *
+ * This is a type helper that provides compile-time type checking and IntelliSense
+ * for action definitions. It performs no runtime processing - just returns the
+ * action definition as-is while providing type safety.
+ *
+ * @template {{ [key: string]: { type: keyof TypeMap } } } TParamsSchema
+ * @param {ServiceActionSchema<TParamsSchema>} actionDefinition - Action schema with typed parameters
+ * @returns {ServiceActionSchema<TParamsSchema>} - Same action schema with preserved types
+ * @example
+ * const myAction = defineAction({
+ *   params: {
+ *     name: { type: 'string', required: true },
+ *     age: { type: 'number', min: 0 }
+ *   },
+ *   handler: (ctx) => {
+ *     // ctx.params is properly typed as { name: string, age?: number }
+ *     return `Hello ${ctx.params.name}`;
+ *   }
+ * });
 */
-module.exports = function (actionDefinition) {
+module.exports = function defineAction (actionDefinition) {
   return actionDefinition;
 };

package/lib/helper/defineBrokerOptions.js

@@ -1,13 +1,31 @@
-/* istanbul ignore next */
+/** @import { BrokerOptions } from '@weave-js/core' */
 
 /**
- * @typedef {import('../types.js').BrokerOptions} BrokerOptions
- */
-
-/**
- * Create and register a new service
- * @param {BrokerOptions} options - Broker options
- * @returns {BrokerOptions} Broker options
+ * Helper function to define broker options with proper TypeScript inference
+ *
+ * This is a type helper that provides compile-time type checking and IntelliSense
+ * for broker configuration. It performs no runtime processing - just returns the
+ * options as-is while providing type safety and configuration validation.
+ *
+ * @param {BrokerOptions} options - Complete broker configuration options
+ * @returns {BrokerOptions} Same broker options with preserved types
+ * @example
+ * const brokerConfig = defineBrokerOptions({
+ *   nodeId: 'my-node',
+ *   logger: {
+ *     level: 'info',
+ *     format: 'human'
+ *   },
+ *   transport: {
+ *     adapter: 'TCP',
+ *     options: {
+ *       port: 3000
+ *     }
+ *   },
+ *   cache: {
+ *     adapter: 'Memory'
+ *   }
+ * });
 */
 module.exports = function (options) {
   return options;

package/lib/helper/defineService.js

@@ -2,13 +2,37 @@
 /* istanbul ignore next */
 
 /**
- * @typedef {import('../types.js').ServiceSchema} ServiceSchema
-*/
+ * @import * as Weave from '@weave-js/core'
+ */
 
 /**
- * Create and register a new service
- * @param {ServiceSchema} serviceSchema - Schema of the Service
- * @returns {ServiceSchema} Service schema
+ * Helper function to define a service schema with proper TypeScript inference
+ *
+ * This is a type helper that provides compile-time type checking and IntelliSense
+ * for service definitions. It performs no runtime processing - just returns the
+ * service schema as-is while providing type safety and better developer experience.
+ *
+ * @param {Weave.ServiceSchema} serviceSchema - Complete service schema definition
+ * @returns {Weave.ServiceSchema} Same service schema with preserved types
+ * @example
+ * const userService = defineService({
+ *   name: 'users',
+ *   actions: {
+ *     create: {
+ *       params: {
+ *         name: { type: 'string', required: true },
+ *         email: { type: 'email', required: true }
+ *       },
+ *       handler: (ctx) => {
+ *         // ctx.params is properly typed
+ *         return this.createUser(ctx.params.name, ctx.params.email);
+ *       }
+ *     }
+ *   },
+ *   methods: {
+ *     createUser: (name, email) => ({ id: 1, name, email })
+ *   }
+ * });
 */
 module.exports = function (serviceSchema) {
   return serviceSchema;

package/lib/index.js

@@ -1,55 +1,105 @@
-/**
- * @typedef {import('./types.js').BrokerOptions} BrokerOptions
- * @typedef {import('./types.js').Runtime} Runtime
- * @typedef {import('./types.js').Broker} Broker
-*/
-
 const { getDefaultOptions } = require('./broker/defaultOptions');
 const { defaultsDeep } = require('@weave-js/utils');
 const { initRuntime } = require('./buildRuntime');
 const { createBrokerInstance } = require('./broker');
 
 /**
- * @type {BrokerOptions} options Broker options
-*/
+ * Default broker configuration options
+ * @type {import('../types').BrokerOptions}
+ */
 exports.defaultOptions = getDefaultOptions();
 
 /**
- * Build runtime object
- * @param {BrokerOptions} options Broker options
- * @return {Broker} Broker instance
-*/
+ * Creates a new Weave broker instance with the provided configuration
+ * @param {import('../types').BrokerOptions} [options] - Broker configuration options
+ * @returns {import('../types').Broker} A new Broker instance
+ * @example
+ * const { createBroker } = require('@weave-js/core');
+ *
+ * const broker = createBroker({
+ *   nodeId: 'my-service',
+ *   logger: { level: 'info' },
+ *   transport: { adapter: 'TCP' }
+ * });
+ *
+ * broker.start();
+ */
 exports.createBroker = (options) => {
   const defaultOptions = getDefaultOptions();
 
   options = defaultsDeep(options, defaultOptions);
 
   const runtime = initRuntime(options);
+  const broker = createBrokerInstance(runtime);
+
+  // Establish circular reference for graceful shutdown in fatal errors
+  runtime.broker = broker;
 
-  return createBrokerInstance(runtime);
+  return broker;
 };
 
 /**
- * @deprecated since version 0.9.0
- * @param {import('./types.js').BrokerOptions} options Broker options.
- * @returns {import('./types.js').Broker} Broker instance
-*/
+ * @deprecated since version 0.9.0 - Use createBroker instead
+ * @param {import('../types').BrokerOptions} [options] - Broker configuration options
+ * @returns {import('../types').Broker} A new Broker instance
+ */
 exports.Weave = exports.createBroker;
 
+/**
+ * Weave error classes and utilities
+ * @namespace
+ */
 exports.Errors = require('./errors');
 
+/**
+ * Weave constants and internal identifiers
+ * @namespace
+ */
 exports.Constants = require('./constants');
 
+/**
+ * Cache adapter implementations
+ * @namespace
+ */
 exports.Cache = require('./cache/adapters');
 
 /**
- * @deprecated since version 0.10.0
-*/
+ * @deprecated since version 0.10.0 - Use TracingAdapters instead
+ */
 exports.createBaseTracingCollector = require('./tracing/collectors/base').createBaseTracingCollector;
+
+/**
+ * Transport adapter implementations
+ * @namespace
+ */
 exports.TransportAdapters = require('./transport/adapters');
+
+/**
+ * Tracing collector implementations
+ * @namespace
+ */
 exports.TracingAdapters = require('./tracing/collectors');
+
+/**
+ * Cache adapter implementations (alias for Cache)
+ * @namespace
+ */
 exports.CacheAdapters = require('./cache/adapters');
 
+/**
+ * Helper function for type-safe broker option definitions
+ * @function
+ */
 exports.defineBrokerOptions = require('./helper/defineBrokerOptions');
+
+/**
+ * Helper function for type-safe service definitions
+ * @function
+ */
 exports.defineService = require('./helper/defineService');
+
+/**
+ * Helper function for type-safe action definitions
+ * @function
+ */
 exports.defineAction = require('./helper/defineAction');

package/lib/logger/format/asHumanReadable.js

@@ -1,7 +1,7 @@
 const { green, magenta, red, yellow, gray, cyan } = require('../utils/colorize');
 const os = require('os');
 
-exports.asHumanReadable = ({ levels, options }, originObj, message, number, time) => {
+exports.asHumanReadable = (runtime, originObj, message, number, time) => {
   let logResult = '';
 
   const logLevelColors = {
@@ -13,7 +13,7 @@ exports.asHumanReadable = ({ levels, options }, originObj, message, number, time
     verbose: gray
   };
 
-  const currentLabel = levels.labels[number];
+  const currentLabel = runtime.levels.labels[number];
 
   const color = logLevelColors[currentLabel] || yellow;
   // Log level label
@@ -22,8 +22,8 @@ exports.asHumanReadable = ({ levels, options }, originObj, message, number, time
   // date time
   logResult += ' [' + new Date(time).toISOString() + '] ';
 
-  if (options.base.pid && options.base.hostname) {
-    logResult += ` (${options.base.pid} on ${options.base.hostname})`;
+  if (runtime.options.base.pid && runtime.options.base.hostname) {
+    logResult += ` (${runtime.options.base.pid} on ${runtime.options.base.hostname})`;
   }
 
   if (message) {