@wirestate/core 0.6.3 → 0.7.0-experimental.2

package/cjs/development/lib.js

@@ -4,6 +4,7 @@ var inversify = require('inversify');
 var tslib = require('tslib');
 
 var ERROR_CODE_GENERIC = 1;
+var ERROR_CODE_VALIDATION_ERROR = 50;
 var ERROR_CODE_INVALID_ARGUMENTS = 51;
 var ERROR_CODE_BINDING_SCOPE = 52;
 var ERROR_CODE_FAILED_TO_RESOLVE_QUERY_HANDLER = 101;
@@ -12,20 +13,41 @@ var ERROR_CODE_ACCESS_BEFORE_ACTIVATION = 200;
 var ERROR_CODE_ACCESS_AFTER_DISPOSAL = 201;
 
 /**
- * A custom error class that contains generic error information for Wirestate-related issues.
+ * Base error class for all Wirestate-related exceptions.
  *
- * This class extends the native `Error` class and is used to represent errors specific
- * to the Wirestate library, providing more structured error handling.
+ * @remarks
+ * `WirestateError` provides structured error information, including a numeric error code
+ * and a descriptive message. It is used throughout the library to signal lifecycle
+ * violations, messaging failures, and configuration issues.
+ *
+ * @group Error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   scope.getContainer();
+ * } catch (error) {
+ *   if (error instanceof WirestateError) {
+ *     console.error(`Error code: ${error.code}`);
+ *   }
+ * }
+ * ```
  */
 var WirestateError = /** @class */function (_super) {
   tslib.__extends(WirestateError, _super);
+  /**
+   * Creates a new instance of WirestateError.
+   *
+   * @param code - Numeric identifier for the error (defaults to ERROR_CODE_GENERIC).
+   * @param detail - Optional descriptive message.
+   */
   function WirestateError(code, detail) {
     if (code === void 0) {
       code = ERROR_CODE_GENERIC;
     }
     var _this = _super.call(this) || this;
     /**
-     * Name or error class to help differentiate error class in minified environments.
+     * The name of the error class, useful for identification in minified environments.
      */
     _this.name = "WirestateError";
     _this.code = code;
@@ -36,23 +58,64 @@ var WirestateError = /** @class */function (_super) {
 }(Error);
 
 /**
- * Binds a constant value to a token in the container.
+ * Binds a constant value to a service identifier in the container.
+ *
+ * @remarks
+ * Use this to register configuration values, primitive constants, or pre-instantiated objects.
+ * Constant values are bound with a singleton scope by default.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the service being bound.
+ *
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Descriptor containing `id` (token) and `value` (constant).
+ * @returns Inversify fluent syntax for additional constraints.
+ *
+ * @throws {@link WirestateError} If `entry.scopeBindingType` is not `Singleton`.
  *
- * @param container - target Inversify container
- * @param entry - entry descriptor to bind
+ * @example
+ * ```typescript
+ * const API_URL: unique symbol = Symbol("API_URL");
+ *
+ * bindConstant(container, {
+ *   id: API_URL,
+ *   value: "https://api.example.com"
+ * });
+ * ```
  */
 function bindConstant(container, entry) {
   if (entry.scopeBindingType && entry.scopeBindingType !== inversify.bindingScopeValues.Singleton) {
     throw new WirestateError(ERROR_CODE_BINDING_SCOPE, "Provided unexpected binding scope for constant value.");
   }
-  container.bind(entry.id).toConstantValue(entry.value);
+  return container.bind(entry.id).toConstantValue(entry.value);
 }
 
 /**
- * Binds a constant value to a token in the container.
+ * Binds a dynamic value (factory-based) to an identifier in the container.
+ *
+ * @remarks
+ * Use this when the value depends on runtime state or requires logic during resolution.
+ * The binding uses `entry.factory` if provided; otherwise, it falls back to `entry.value`.
+ * Supports custom scoping via `entry.scopeBindingType`.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the value being bound.
+ *
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Descriptor containing `id`, `factory` or `value`, and optional `scopeBindingType`.
+ * @returns Inversify fluent syntax for additional constraints.
  *
- * @param container - target Inversify container
- * @param entry - descriptor of entry to bind
+ * @example
+ * ```typescript
+ * const DATE_NOW: unique symbol = Symbol("DATE_NOW");
+ *
+ * bindDynamicValue(container, {
+ *   id: DATE_NOW,
+ *   factory: () => new Date()
+ * });
+ * ```
  */
 function bindDynamicValue(container, entry) {
   var binding = container.bind(entry.id).toDynamicValue(function () {
@@ -62,31 +125,40 @@ function bindDynamicValue(container, entry) {
     return entry.value;
   });
   if (!entry.scopeBindingType) {
-    return;
+    return binding;
   } else if (entry.scopeBindingType === inversify.bindingScopeValues.Transient) {
-    binding.inTransientScope();
+    return binding.inTransientScope();
   } else if (entry.scopeBindingType === inversify.bindingScopeValues.Request) {
-    binding.inRequestScope();
+    return binding.inRequestScope();
   } else {
-    binding.inSingletonScope();
+    return binding.inSingletonScope();
   }
 }
 
 /**
- * Command execution status.
+ * Represents the current state of a command execution.
+ *
+ * @group Commands
  */
 exports.CommandStatus = void 0;
 (function (CommandStatus) {
+  /** The command task has started but not yet completed. */
   CommandStatus["PENDING"] = "pending";
+  /** The command task has successfully completed. */
   CommandStatus["SETTLED"] = "settled";
+  /** The command task failed with an error. */
   CommandStatus["ERROR"] = "error";
 })(exports.CommandStatus || (exports.CommandStatus = {}));
 
 /**
- * Dispatches commands to handlers.
+ * Orchestrates command dispatching and handler registration.
  *
- * Unlike queries, command execution always wraps the handler in a promise
- * and returns a descriptor with task, status, and responder.
+ * @remarks
+ * The `CommandBus` provides a way to decouple command dispatchers from their handlers.
+ * It supports handler shadowing: when multiple handlers are registered for the same type,
+ * the last registered one takes priority.
+ *
+ * @group Commands
  */
 var CommandBus = /** @class */function () {
   function CommandBus() {
@@ -97,45 +169,32 @@ var CommandBus = /** @class */function () {
     this.handlers = new Map();
   }
   /**
-   * Registers a command handler.
-   * Returns an unregister function.
-   *
-   * @param type - command type
-   * @param handler - handler function
-   * @returns unregister function
+   * Removes all registered command handlers from the bus.
    */
-  CommandBus.prototype.register = function (type, handler) {
-    var _this = this;
-    var stack = this.handlers.get(type);
-    if (!stack) {
-      stack = [];
-      this.handlers.set(type, stack);
-    }
-    stack.push(handler);
-    return function () {
-      var current = _this.handlers.get(type);
-      if (!current) {
-        return;
-      }
-      var index = current.indexOf(handler);
-      if (index >= 0) {
-        current.splice(index, 1);
-      }
-      // Clean empty stacks.
-      if (current.length === 0) {
-        _this.handlers.delete(type);
-      }
-    };
+  CommandBus.prototype.clear = function () {
+    this.handlers.clear();
   };
   /**
    * Dispatches a command to the last registered handler.
-   * Wraps the handler execution in a promise and returns a descriptor.
    *
-   * @param type - command type
-   * @param data - command payload
-   * @returns command descriptor with task, status, and responder
+   * @remarks
+   * Execution is always asynchronous. The handler's return value is wrapped in a Promise.
+   * Returns a {@link CommandDescriptor} that tracks the execution status and task.
    *
-   * @throws if no handler is registered
+   * @template R - Type of the command result.
+   * @template D - Type of the command payload data.
+   *
+   * @param type - Command identifier.
+   * @param data - Optional payload for the handler.
+   * @returns A descriptor for the executing command.
+   *
+   * @throws {@link WirestateError} If no handler is registered.
+   *
+   * @example
+   * ```typescript
+   * const descriptor: CommandDescriptor<User> = commandBus.command<User, string>("GET_USER", "id-123");
+   * const user: User = await descriptor.task;
+   * ```
    */
   CommandBus.prototype.command = function (type, data) {
     var stack = this.handlers.get(type);
@@ -159,96 +218,214 @@ var CommandBus = /** @class */function () {
     return descriptor;
   };
   /**
-   * Dispatches a command to the last registered handler, returning null if no handler exists.
+   * Dispatches a command if a handler exists, otherwise returns null.
+   *
+   * @template R - Type of the command result.
+   * @template D - Type of the command payload data.
    *
-   * @param type - command type
-   * @param data - command payload
-   * @returns command descriptor or null if no handler is registered
+   * @param type - Command identifier.
+   * @param data - Optional payload for the handler.
+   * @returns A command descriptor, or `null` if no handler is found.
    */
   CommandBus.prototype.commandOptional = function (type, data) {
     var stack = this.handlers.get(type);
     return (stack === null || stack === void 0 ? void 0 : stack.length) ? this.command(type, data) : null;
   };
   /**
-   * Checks if a handler is registered for the given type.
+   * Checks if at least one handler is registered for the given command type.
    *
-   * @param type - command type
-   * @returns true if handler exists
+   * @param type - Command identifier.
+   * @returns `true` if a handler is available, `false` otherwise.
    */
   CommandBus.prototype.has = function (type) {
     var _a;
     return Boolean((_a = this.handlers.get(type)) === null || _a === void 0 ? void 0 : _a.length);
   };
   /**
-   * Removes all registered handlers.
+   * Registers a handler for a specific command type.
+   *
+   * @remarks
+   * If multiple handlers are registered for the same type, they are stored in a stack.
+   * The most recently registered handler will be used for dispatching.
+   *
+   * @template D - Type of the command payload data.
+   * @template R - Type of the command execution result.
+   *
+   * @param type - Command identifier.
+   * @param handler - Function to execute when the command is dispatched.
+   * @returns A function to unregister the handler.
+   *
+   * @example
+   * ```typescript
+   * const unregister: CommandUnregister = commandBus.register("LOG_MESSAGE", (message: string) => {
+   *   console.log(message);
+   * });
+   * ```
    */
-  CommandBus.prototype.clear = function () {
-    this.handlers.clear();
+  CommandBus.prototype.register = function (type, handler) {
+    var _this = this;
+    var stack = this.handlers.get(type);
+    if (!stack) {
+      stack = [];
+      this.handlers.set(type, stack);
+    }
+    stack.push(handler);
+    return function () {
+      return _this.unregister(type, handler);
+    };
+  };
+  /**
+   * Removes a previously registered command handler.
+   *
+   * @remarks
+   * If the handler was not registered for the given type, this operation does nothing.
+   *
+   * @template D - Type of the command payload data.
+   * @template R - Type of the command execution result.
+   *
+   * @param type - Command identifier.
+   * @param handler - The handler function instance to remove.
+   */
+  CommandBus.prototype.unregister = function (type, handler) {
+    var current = this.handlers.get(type);
+    if (!current) {
+      return;
+    }
+    var index = current.indexOf(handler);
+    if (index >= 0) {
+      current.splice(index, 1);
+    }
+    // Clean empty stacks.
+    if (current.length === 0) {
+      this.handlers.delete(type);
+    }
   };
   return CommandBus;
 }();
 
 /**
- * Token for the container-scoped seeds map.
- */
-var SEEDS_TOKEN = Symbol("@wirestate/seeds");
-/**
- * Token for the container-scoped shared seed object.
- */
-var SEED_TOKEN = Symbol("@wirestate/seed");
-/**
- * Map of class constructors to their declared query handlers.
- * Inherited via a prototype chain at resolve time.
+ * Registry of class constructors to their declared query handlers.
+ *
+ * @remarks
+ * This map is populated by the {@link OnQuery} decorator. Handlers are
+ * inherited via the prototype chain at service resolution time.
+ *
+ * @group Queries
+ * @internal
  */
 var QUERY_HANDLER_METADATA = new WeakMap();
 /**
- * Map of class constructors to their declared command handlers.
- * Inherited via a prototype chain at resolve time.
+ * Registry of class constructors to their declared command handlers.
+ *
+ * @remarks
+ * This map is populated by the {@link OnCommand} decorator. Handlers are
+ * inherited via the prototype chain at service resolution time.
+ *
+ * @group Commands
+ * @internal
  */
 var COMMAND_HANDLER_METADATA = new WeakMap();
 /**
- * Map of class constructors to their `@OnActivated`-decorated method names.
- * Inherited via a prototype chain at resolve time.
+ * Registry of class constructors to their `@OnActivated`-decorated method names.
+ *
+ * @remarks
+ * This map is populated by the {@link OnActivated} decorator. Activation hooks are
+ * executed in parent-to-child order during service initialization.
+ *
+ * @group Service
+ * @internal
  */
 var ACTIVATED_HANDLER_METADATA = new WeakMap();
 /**
- * Map of class constructors to their `@OnDeactivation`-decorated method names.
- * Inherited via a prototype chain at resolve time.
+ * Registry of class constructors to their `@OnDeactivation`-decorated method names.
+ *
+ * @remarks
+ * This map is populated by the {@link OnDeactivation} decorator. Deactivation hooks are
+ * executed in parent-to-child order during service disposal.
+ *
+ * @group Service
+ * @internal
  */
 var DEACTIVATION_HANDLER_METADATA = new WeakMap();
 /**
- * Map of class constructors for their declared event handlers.
- * Inherited via a prototype chain at resolve time.
+ * Registry of class constructors to their declared event handlers.
+ *
+ * @remarks
+ * This map is populated by the {@link OnEvent} decorator. Event handlers are
+ * inherited via the prototype chain at service resolution time.
+ *
+ * @group Events
+ * @internal
  */
 var EVENT_HANDLER_METADATA = new WeakMap();
 /**
- * Private storage for service-to-container references.
+ * Internal storage for mapping service instances to their originating Inversify containers.
+ *
+ * @remarks
+ * Used during the service lifecycle to ensure that resolution and messaging
+ * occur within the correct container context.
+ *
+ * @group Bind
+ * @internal
  */
 var CONTAINER_REFS_BY_SERVICE = new WeakMap();
 /**
- * Private storage for injected WireScope instances per service.
+ * Internal storage for managing injected {@link WireScope} instances per service.
+ *
+ * @remarks
+ * Tracks the scopes associated with a service instance for lifecycle management
+ * and cleanup.
+ *
+ * @group Container
+ * @internal
  */
 var WIRE_SCOPES_BY_SERVICE = new WeakMap();
 /**
- * Private storage for service event unsubscribers.
+ * Internal storage for service event unsubscribers.
+ *
+ * @remarks
+ * Stores the unsubscription functions returned when a service automatically
+ * subscribes to events via the {@link OnEvent} decorator.
+ *
+ * @group Events
+ * @internal
  */
 var EVENT_UNSUBSCRIBERS_BY_SERVICE = new WeakMap();
 /**
- * Private storage for service query unregisters.
+ * Internal storage for service query unregisters.
+ *
+ * @remarks
+ * Stores the unregistration functions returned when a service automatically
+ * registers query handlers via the {@link OnQuery} decorator.
+ *
+ * @group Queries
+ * @internal
  */
 var QUERY_UNREGISTERS_BY_SERVICE = new WeakMap();
 /**
- * Private storage for service command unregisters.
+ * Internal storage for service command unregisters.
+ *
+ * @remarks
+ * Stores the unregistration functions returned when a service automatically
+ * registers command handlers via the {@link OnCommand} decorator.
+ *
+ * @group Commands
+ * @internal
  */
 var COMMAND_UNREGISTERS_BY_SERVICE = new WeakMap();
 
 /**
  * Retrieves `@OnCommand` metadata from the class hierarchy.
- * Returns handlers ordered from base to derived class.
  *
- * @param instance - service instance
- * @returns metadata list
+ * @remarks
+ * Traverses the prototype chain to collect all command handlers.
+ * Returns metadata ordered from base class to derived class to ensure parent-first execution.
+ *
+ * @group Commands
  * @internal
+ *
+ * @param instance - The service instance to inspect.
+ * @returns A read-only array of metadata for all discovered command handlers.
  */
 function getCommandHandlerMetadata(instance) {
   var constructor = instance.constructor;
@@ -266,16 +443,40 @@ function getCommandHandlerMetadata(instance) {
 }
 
 /**
- * Dispatches events to subscribers.
+ * Orchestrates event broadcasting to multiple subscribers.
+ *
+ * @remarks
+ * The `EventBus` facilitates decoupled, many-to-many communication.
+ * Unlike commands or queries, which are dispatched to a single handler,
+ * events are broadcast to all registered subscribers.
+ *
+ * @group Events
  */
 var EventBus = /** @class */function () {
   function EventBus() {
     this.handlers = new Set();
   }
   /**
-   * Broadcasts an event to all subscribers.
+   * Broadcasts an event to all registered subscribers.
+   *
+   * @remarks
+   * Handlers are executed in a try-catch block to ensure that a single
+   * failing subscriber does not prevent others from receiving the event.
    *
-   * @param event - event to emit
+   * @template P - Type of the event payload.
+   * @template T - Type of the event identifier.
+   * @template F - Type of the event source.
+   *
+   * @param event - The event object to broadcast.
+   *
+   * @example
+   * ```typescript
+   * eventBus.emit({
+   *   type: "USER_LOGGED_IN",
+   *   payload: { userId: "123" },
+   *   from: AuthService
+   * });
+   * ```
    */
   EventBus.prototype.emit = function (event) {
     // Snapshot prevents concurrent modification errors if handlers sub/unsub during emit.
@@ -291,21 +492,46 @@ var EventBus = /** @class */function () {
     }
   };
   /**
-   * Subscribes a handler to all events.
-   * Returns an unsubscribe function.
+   * Registers a handler to receive all broadcasted events.
+   *
+   * @param handler - Function invoked for every emitted event.
+   * @returns An {@link EventUnsubscriber} function to remove the subscription.
    *
-   * @param handler - event handler function
-   * @returns unsubscribe function
+   * @example
+   * ```typescript
+   * const unsubscribe: EventUnsubscriber = eventBus.subscribe((event) => {
+   *   console.log('Received event:', event);
+   * });
+   * ```
    */
   EventBus.prototype.subscribe = function (handler) {
     var _this = this;
     this.handlers.add(handler);
     return function () {
-      _this.handlers.delete(handler);
+      return _this.unsubscribe(handler);
     };
   };
   /**
-   * Removes all registered handlers.
+   * Removes a previously registered event handler.
+   *
+   * @remarks
+   * If the handler was not subscribed, this operation does nothing.
+   *
+   * @param handler - The handler function instance to remove.
+   */
+  EventBus.prototype.unsubscribe = function (handler) {
+    this.handlers.delete(handler);
+  };
+  /**
+   * Checks if the bus has any active subscribers.
+   *
+   * @returns `true` if at least one handler is registered, `false` otherwise.
+   */
+  EventBus.prototype.has = function () {
+    return this.handlers.size > 0;
+  };
+  /**
+   * Removes all registered handlers from the bus.
    *
    * @internal
    */
@@ -316,7 +542,15 @@ var EventBus = /** @class */function () {
 }();
 
 /**
- * Dispatches queries to handlers.
+ * Orchestrates query dispatching and handler registration.
+ *
+ * @remarks
+ * The `QueryBus` provides a request-response mechanism for decoupled communication.
+ * It supports handler shadowing: when multiple handlers are registered for the same type,
+ * the last registered one (e.g., at the component level) takes priority over earlier ones
+ * (e.g., at the global service level).
+ *
+ * @group Queries
  */
 var QueryBus = /** @class */function () {
   function QueryBus() {
@@ -327,12 +561,23 @@ var QueryBus = /** @class */function () {
     this.handlers = new Map();
   }
   /**
-   * Registers a query handler.
-   * Returns an unregister function.
+   * Registers a handler for a specific query type.
    *
-   * @param type - query type
-   * @param handler - handler function
-   * @returns unregister function
+   * @remarks
+   * If multiple handlers are registered for the same type, they are stored in a stack.
+   * The most recently registered handler will be used for resolution.
+   *
+   * @template D - Type of the query input data.
+   * @template R - Type of the query result.
+   *
+   * @param type - Unique query identifier.
+   * @param handler - Function to execute when the query is dispatched.
+   * @returns A function to unregister the handler.
+   *
+   * @example
+   * ```typescript
+   * const unregister: QueryUnregister = queryBus.register("GET_NOW", () => Date.now());
+   * ```
    */
   QueryBus.prototype.register = function (type, handler) {
     var _this = this;
@@ -343,28 +588,56 @@ var QueryBus = /** @class */function () {
     }
     stack.push(handler);
     return function () {
-      var current = _this.handlers.get(type);
-      if (!current) {
-        return;
-      }
-      var index = current.indexOf(handler);
-      if (index >= 0) {
-        current.splice(index, 1);
-      }
-      // Clean empty stacks.
-      if (current.length === 0) {
-        _this.handlers.delete(type);
-      }
+      return _this.unregister(type, handler);
     };
   };
   /**
-   * Dispatches a query to the last registered handler.
+   * Removes a previously registered query handler.
+   *
+   * @remarks
+   * If the handler was not registered for the given type, this operation does nothing.
    *
-   * @param type - query type
-   * @param data - query payload
-   * @returns query result
+   * @template D - Type of the query input data.
+   * @template R - Type of the query result.
    *
-   * @throws if no handler is registered
+   * @param type - Unique query identifier.
+   * @param handler - The handler function instance to remove.
+   */
+  QueryBus.prototype.unregister = function (type, handler) {
+    var current = this.handlers.get(type);
+    if (!current) {
+      return;
+    }
+    var index = current.indexOf(handler);
+    if (index >= 0) {
+      current.splice(index, 1);
+    }
+    // Clean empty stacks.
+    if (current.length === 0) {
+      this.handlers.delete(type);
+    }
+  };
+  /**
+   * Dispatches a query to the last registered handler and returns the result.
+   *
+   * @remarks
+   * Query handlers can be synchronous or asynchronous. The result is returned as-is
+   * (or as a Promise if the handler is async).
+   *
+   * @template R - Type of the expected query result.
+   * @template D - Type of the data (payload) passed to the query.
+   * @template T - Type of the query identifier.
+   *
+   * @param type - Unique query identifier.
+   * @param data - Optional input data for the handler.
+   * @returns The result of the query execution.
+   *
+   * @throws {@link WirestateError} If no handler is registered for the given type.
+   *
+   * @example
+   * ```typescript
+   * const user: User = await queryBus.query<User, string>("FIND_USER", "user-id-123");
+   * ```
    */
   QueryBus.prototype.query = function (type, data) {
     var stack = this.handlers.get(type);
@@ -375,11 +648,15 @@ var QueryBus = /** @class */function () {
     throw new WirestateError(ERROR_CODE_FAILED_TO_RESOLVE_QUERY_HANDLER, "No query handler registered in container for type: '".concat(String(type), "'."));
   };
   /**
-   * Dispatches a query to the last registered handler, returning null if no handler exists.
+   * Dispatches a query if a handler exists, otherwise returns null.
+   *
+   * @template R - Type of the expected query result.
+   * @template D - Type of the data (payload) passed to the query.
+   * @template T - Type of the query identifier.
    *
-   * @param type - query type
-   * @param data - query payload
-   * @returns query result or null if no handler is registered
+   * @param type - Unique query identifier.
+   * @param data - Optional input data for the handler.
+   * @returns The query result, or `null` if no handler is found.
    */
   QueryBus.prototype.queryOptional = function (type, data) {
     var stack = this.handlers.get(type);
@@ -389,17 +666,17 @@ var QueryBus = /** @class */function () {
     return null;
   };
   /**
-   * Checks if a handler is registered for the given type.
+   * Checks if at least one handler is registered for the given query type.
    *
-   * @param type - query type
-   * @returns true if handler exists
+   * @param type - Unique query identifier.
+   * @returns `true` if a handler is available, `false` otherwise.
    */
   QueryBus.prototype.has = function (type) {
     var stack = this.handlers.get(type);
     return Boolean(stack && stack.length);
   };
   /**
-   * Removes all registered handlers.
+   * Removes all registered query handlers from the bus.
    *
    * @internal
    */
@@ -410,9 +687,44 @@ var QueryBus = /** @class */function () {
 }();
 
 /**
- * Injectable scope providing access to wirestate buses and seeds.
- * Each injecting service receives its own instance (transient scope).
- * The scope is activated and deactivated automatically alongside its owner service.
+ * Unique symbol used as a token for the container-scoped seeds map.
+ *
+ * @remarks
+ * This token is used to bind and resolve the {@link SeedsMap} in the Inversify {@link Container}.
+ *
+ * @group Seeds
+ *
+ * @example
+ * ```typescript
+ * const seedsMap: SeedsMap = container.get(SEEDS_TOKEN);
+ * ```
+ */
+var SEEDS_TOKEN = Symbol("@wirestate/core/seeds");
+/**
+ * Unique symbol used as a token for the container-scoped shared seed object.
+ *
+ * @remarks
+ * This token is used to bind and resolve the global shared seed object in the Inversify {@link Container}.
+ *
+ * @group Seeds
+ *
+ * @example
+ * ```typescript
+ * const sharedSeed: AnyObject = container.get(SEED_TOKEN);
+ * ```
+ */
+var SEED_TOKEN = Symbol("@wirestate/core/seed");
+
+/**
+ * A transient bridge providing services with access to Wirestate buses, lazy resolution, and seeds.
+ *
+ * @remarks
+ * Every service bound via {@link bindService} receives its own unique `WireScope` instance.
+ * It acts as a facade to the IoC container while enforcing lifecycle safety.
+ *
+ * Methods are available only while the scope is "active" (after service activation and before deactivation).
+ *
+ * @group Container
  */
 var WireScope = /** @class */function () {
   function WireScope(container) {
@@ -423,12 +735,18 @@ var WireScope = /** @class */function () {
     this.isDisposed = false;
   }
   /**
-   * Access the IoC container.
-   * Available only for activated instances of scope.
+   * Provides direct access to the underlying Inversify {@link Container}.
+   *
+   * @returns The active {@link Container}.
    *
-   * @returns active container
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
    *
-   * @throws WirestateError if scope is not activated or already disposed
+   * @example
+   * ```typescript
+   * const container: Container = scope.getContainer();
+   *
+   * container.bind("TOKEN").toConstantValue(42);
+   * ```
    */
   WireScope.prototype.getContainer = function () {
     if (this.container) {
@@ -441,41 +759,64 @@ var WireScope = /** @class */function () {
     }
   };
   /**
-   * Resolves a sibling service or injected value.
-   * Use for lazy resolution or circular dependency breaking.
-   * Available only for activated containers.
+   * Lazily resolves a service or value from the container.
+   *
+   * @remarks
+   * Use this to break circular dependencies or for services that are not needed immediately.
+   *
+   * @template T - Type of the service or value to resolve.
+   *
+   * @param injectionId - Service token (class constructor, symbol, or string).
+   * @returns The resolved instance or value.
    *
-   * @param injectionId - injection identifier
-   * @returns resolved injection, service instance, or generic value
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   * @throws {Error} If the service cannot be resolved from the container.
    *
-   * @throws WirestateError if scope is not activated
+   * @example
+   * ```typescript
+   * const service: MyService = scope.resolve(MyService);
+   * ```
    */
   WireScope.prototype.resolve = function (injectionId) {
     return this.getContainer().get(injectionId);
   };
   /**
-   * Resolves a sibling service or injected value.
-   * Use for lazy resolution or circular dependency breaking.
-   * Available only for activated containers.
+   * Lazily resolves a service if it is bound, otherwise returns null.
    *
-   * @param injectionId - injection identifier
-   * @returns resolved injection, service instance, generic value, or null if it is not bound
+   * @template T - Type of the service or value to resolve.
    *
-   * @throws WirestateError if scope is not activated
+   * @param injectionId - Service token (class constructor, symbol, or string).
+   * @returns The resolved instance, value, or `null` if not bound.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * const logger: Logger | null = scope.resolveOptional(Logger);
+   *
+   * logger?.info("Resolved optionally");
+   * ```
    */
   WireScope.prototype.resolveOptional = function (injectionId) {
     var container = this.getContainer();
     return container.isBound(injectionId) ? container.get(injectionId) : null;
   };
   /**
-   * Broadcasts an event.
-   * Available only for activated containers.
+   * Dispatches an event to the {@link EventBus}.
+   *
+   * @template P - Type of the event payload.
+   * @template T - Type of the event identifier.
+   *
+   * @param type - Event identifier.
+   * @param payload - Optional data associated with the event.
+   * @param from - Optional source identifier (defaults to current scope).
    *
-   * @param type - type of event to emit
-   * @param payload - optional payload to send with the event
-   * @param from - optional sender of the event
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
    *
-   * @throws WirestateError if scope is not activated
+   * @example
+   * ```typescript
+   * scope.emitEvent("VALUE_CHANGED", { value: "abcd" });
+   * ```
    */
   WireScope.prototype.emitEvent = function (type, payload, from) {
     this.getContainer().get(EventBus).emit({
@@ -485,63 +826,210 @@ var WireScope = /** @class */function () {
     });
   };
   /**
-   * Dispatches a query and returns the result.
-   * Available only for activated containers.
+   * Subscribes to all events on the {@link EventBus}.
+   *
+   * @param handler - Function called for every emitted event.
+   * @returns A function to unsubscribe.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe: EventUnsubscriber = scope.subscribeToEvent((event) => {
+   *   console.log("Event received:", event);
+   * });
+   * ```
+   */
+  WireScope.prototype.subscribeToEvent = function (handler) {
+    return this.getContainer().get(EventBus).subscribe(handler);
+  };
+  /**
+   * Unsubscribes a specific handler from the {@link EventBus}.
+   *
+   * @param handler - The handler instance to remove.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * scope.unsubscribeFromEvent(this.onEvent);
+   * ```
+   */
+  WireScope.prototype.unsubscribeFromEvent = function (handler) {
+    this.getContainer().get(EventBus).unsubscribe(handler);
+  };
+  /**
+   * Dispatches a query and waits for the result.
+   *
+   * @template R - Type of the query result.
+   * @template D - Type of the query data (payload).
+   * @template T - Type of the query identifier.
    *
-   * @param type - query type
-   * @param data - query data
-   * @returns query result
+   * @param type - Query identifier.
+   * @param data - Input data for the query handler.
+   * @returns The query result (can be a Promise).
    *
-   * @throws WirestateError if scope is not activated
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   * @throws {@link WirestateError} If no query handler is registered.
+   *
+   * @example
+   * ```typescript
+   * const user: User = await scope.queryData("GET_USER", { id: 1 });
+   * ```
    */
   WireScope.prototype.queryData = function (type, data) {
     return this.getContainer().get(QueryBus).query(type, data);
   };
   /**
-   * Dispatches a query and returns the result.
-   * Available only for activated containers.
+   * Dispatches a query and returns the result, or null if no handler is registered.
+   *
+   * @template R - Type of the query result.
+   * @template D - Type of the query data (payload).
+   * @template T - Type of the query identifier.
    *
-   * @param type - query type
-   * @param data - query data
-   * @returns query result or null if handler is not registered
+   * @param type - Query identifier.
+   * @param data - Input data for the query handler.
+   * @returns The query result or `null`.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * const config: Config | null = await scope.queryOptionalData("GET_CONFIG");
+   * ```
    */
   WireScope.prototype.queryOptionalData = function (type, data) {
     return this.getContainer().get(QueryBus).queryOptional(type, data);
   };
   /**
-   * Dispatches a command and returns the descriptor.
-   * Available only for activated containers.
+   * Registers a handler for a specific query type.
+   *
+   * @template D - Type of the query data (payload).
+   * @template R - Type of the query result.
+   *
+   * @param type - Query identifier.
+   * @param handler - The handler function.
+   * @returns A function to unregister the handler.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * scope.registerQueryHandler("GET_DATE_NOW", () => new Date());
+   * ```
+   */
+  WireScope.prototype.registerQueryHandler = function (type, handler) {
+    return this.getContainer().get(QueryBus).register(type, handler);
+  };
+  /**
+   * Removes a specific query handler registration.
+   *
+   * @template D - Type of the query data (payload).
+   * @template R - Type of the query result.
+   *
+   * @param type - Query identifier.
+   * @param handler - The handler instance to remove.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * scope.unregisterQueryHandler("GET_DATE_NOW", this.onGetDateNow);
+   * ```
+   */
+  WireScope.prototype.unregisterQueryHandler = function (type, handler) {
+    this.getContainer().get(QueryBus).unregister(type, handler);
+  };
+  /**
+   * Dispatches a command and returns a descriptor to track its progress.
+   *
+   * @template R - Type of the command result.
+   * @template D - Type of the command payload.
+   * @template T - Type of the command identifier.
+   *
+   * @param type - Command identifier.
+   * @param data - Payload for the command.
+   * @returns A {@link CommandDescriptor}.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   * @throws {@link WirestateError} If no command handler is registered.
    *
-   * @param type - command type
-   * @param data - command data
-   * @returns command descriptor
+   * @example
+   * ```typescript
+   * const descriptor: CommandDescriptor = scope.executeCommand("LOGOUT");
    *
-   * @throws WirestateError if scope is not activated
+   * await descriptor.task;
+   * ```
    */
   WireScope.prototype.executeCommand = function (type, data) {
     return this.getContainer().get(CommandBus).command(type, data);
   };
   /**
-   * Dispatches a command and returns the descriptor.
-   * Available only for activated containers.
+   * Dispatches a command if a handler is registered, otherwise returns null.
    *
-   * @param type - command type
-   * @param data - command data
-   * @returns command descriptor or null if handler is not registered
+   * @template R - Type of the command result.
+   * @template D - Type of the command payload.
+   * @template T - Type of the command identifier.
+   *
+   * @param type - Command identifier.
+   * @param data - Payload for the command.
+   * @returns A {@link CommandDescriptor} or `null`.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * const descriptor: CommandDescriptor | null = scope.executeOptionalCommand("CLEANUP_CACHE");
+   *
+   * if (descriptor) {
+   *   await descriptor.task;
+   * }
+   * ```
    */
   WireScope.prototype.executeOptionalCommand = function (type, data) {
     return this.getContainer().get(CommandBus).commandOptional(type, data);
   };
   /**
-   * Reads seed for the provided injection.
-   * Returns shared seed if parameters are not provided.
-   * Available only for activated containers.
+   * Registers a handler for a specific command type.
+   *
+   * @template D - Type of the command payload.
+   * @template R - Type of the command result.
    *
-   * @param seed - lookup key
-   * @returns seed data or null if missing
+   * @param type - Command identifier.
+   * @param handler - The handler function.
+   * @returns A function to unregister the handler.
    *
-   * @throws WirestateError if context is not activated
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * scope.registerCommandHandler("LOG_ERROR", (error) => {
+   *   console.error(error);
+   * });
+   * ```
    */
+  WireScope.prototype.registerCommandHandler = function (type, handler) {
+    return this.getContainer().get(CommandBus).register(type, handler);
+  };
+  /**
+   * Removes a specific command handler registration.
+   *
+   * @template D - Type of the command payload.
+   * @template R - Type of the command result.
+   *
+   * @param type - Command identifier.
+   * @param handler - The handler instance to remove.
+   *
+   * @throws {@link WirestateError} If accessed before activation or after disposal.
+   *
+   * @example
+   * ```typescript
+   * scope.unregisterCommandHandler("LOG_ERROR", this.handleLogError);
+   * ```
+   */
+  WireScope.prototype.unregisterCommandHandler = function (type, handler) {
+    this.getContainer().get(CommandBus).unregister(type, handler);
+  };
   WireScope.prototype.getSeed = function (seed) {
     return seed ? this.getContainer().get(SEEDS_TOKEN).get(seed) || null : this.getContainer().get(SEED_TOKEN);
   };
@@ -550,12 +1038,27 @@ var WireScope = /** @class */function () {
 }();
 
 /**
- * Retrieves `@OnEvent` metadata from the class hierarchy.
- * Returns handlers ordered from base to derived class.
+ * Retrieves event handler metadata for a service instance by traversing its prototype chain.
+ *
+ * @remarks
+ * This utility collects metadata registered via the {@link OnEvent} decorator.
+ * It ensures that handlers are returned in parent-to-child order (base class handlers first),
+ * which is critical for maintaining predictable event execution patterns in inherited services.
  *
- * @param instance - service instance
- * @returns metadata list
+ * @group Events
  * @internal
+ *
+ * @param instance - The service instance to scan for event handlers.
+ * @returns A read-only array of event handler metadata, ordered from base to derived class.
+ *
+ * @example
+ * ```typescript
+ * const metadata = getEventHandlerMetadata(myService);
+ *
+ * metadata.forEach(meta => {
+ *   console.log(`Method ${String(meta.propertyKey)} handles event ${String(meta.type)}`);
+ * });
+ * ```
  */
 function getEventHandlerMetadata(instance) {
   var constructor = instance.constructor;
@@ -575,9 +1078,27 @@ function getEventHandlerMetadata(instance) {
 /**
  * Composes service event handlers into a single dispatcher.
  *
- * @param instance - service instance
- * @returns event handler or null if no handlers are declared
+ * @remarks
+ * Scans the provided instance for methods decorated with {@link OnEvent}.
+ * If handlers are found, it returns a fan-out function that dispatches events
+ * to all matching methods based on their registered event types.
+ *
+ * @group Events
  * @internal
+ *
+ * @template T - Type of the service instance.
+ *
+ * @param instance - Service instance to scan for handlers.
+ * @returns A unified event handler, or `null` if no handlers are declared.
+ *
+ * @example
+ * ```typescript
+ * const dispatcher = buildEventDispatcher(myServiceInstance);
+ *
+ * if (dispatcher) {
+ *   dispatcher({ type: "SOME_EVENT", payload: { data: 123 } });
+ * }
+ * ```
  */
 function buildEventDispatcher(instance) {
   var entries = [];
@@ -608,12 +1129,28 @@ function buildEventDispatcher(instance) {
 }
 
 /**
- * Retrieves `@OnQuery` metadata from the class hierarchy.
- * Returns handlers ordered from base to derived class.
+ * Retrieves query handler metadata for a service instance by traversing its prototype chain.
+ *
+ * @remarks
+ * This utility collects metadata registered via the {@link OnQuery} decorator.
+ * It ensures that handlers are returned in parent-to-child order (base class handlers first).
+ * Since queries support shadowing, child class handlers registered later will effectively
+ * override parent handlers for the same query type.
  *
- * @param instance - service instance
- * @returns metadata list
+ * @group Queries
  * @internal
+ *
+ * @param instance - The service instance to scan for query handlers.
+ * @returns A read-only array of query handler metadata, ordered from base to derived class.
+ *
+ * @example
+ * ```typescript
+ * const metadata = getQueryHandlerMetadata(myService);
+ *
+ * metadata.forEach(meta => {
+ *   console.log(`Method ${String(meta.methodName)} handles query ${String(meta.type)}`);
+ * });
+ * ```
  */
 function getQueryHandlerMetadata(instance) {
   var constructor = instance.constructor;
@@ -631,12 +1168,24 @@ function getQueryHandlerMetadata(instance) {
 }
 
 /**
- * Retrieves `@OnActivated` method names from the class hierarchy.
- * Returns method names ordered from base to derived class.
+ * Retrieves the names of methods decorated with {@link OnActivated} by traversing the prototype chain.
  *
- * @param instance - service instance
- * @returns list of method names
+ * @remarks
+ * This utility ensures that handlers are returned in parent-to-child order (base class handlers first),
+ * maintaining a predictable initialization sequence for inherited services.
+ *
+ * @group Service
  * @internal
+ *
+ * @param instance - The service instance to scan for activation handlers.
+ * @returns A read-only array of method names (strings or symbols).
+ *
+ * @example
+ * ```typescript
+ * const methods = getActivatedHandlerMetadata(myService);
+ *
+ * methods.forEach(methodName => (myService as any)[methodName]());
+ * ```
  */
 function getActivatedHandlerMetadata(instance) {
   var constructor = instance.constructor;
@@ -654,12 +1203,24 @@ function getActivatedHandlerMetadata(instance) {
 }
 
 /**
- * Retrieves `@OnDeactivation` method names from the class hierarchy.
- * Returns method names ordered from base to derived class.
+ * Retrieves the names of methods decorated with {@link OnDeactivation} by traversing the prototype chain.
+ *
+ * @remarks
+ * This utility ensures that handlers are returned in parent-to-child order (base class handlers first),
+ * maintaining a predictable cleanup sequence for inherited services.
  *
- * @param instance - service instance
- * @returns list of method names
+ * @group Service
  * @internal
+ *
+ * @param instance - The service instance to scan for deactivation handlers.
+ * @returns A read-only array of method names (strings or symbols).
+ *
+ * @example
+ * ```typescript
+ * const methods = getDeactivationHandlerMetadata(myService);
+ *
+ * methods.forEach(methodName => (myService as any)[methodName]());
+ * ```
  */
 function getDeactivationHandlerMetadata(instance) {
   var constructor = instance.constructor;
@@ -677,12 +1238,56 @@ function getDeactivationHandlerMetadata(instance) {
 }
 
 /**
- * Registers a service class in the container with activation/deactivation logic.
- * Ensures container references, event subscriptions, command and query handlers are managed correctly.
+ * Binds a service class in the {@link Container} with full lifecycle and messaging integration.
+ *
+ * @remarks
+ * Binds the class in singleton scope and configures Inversify activation/deactivation hooks to:
+ * - Manage the `IS_DISPOSED` lifecycle state flag.
+ * - Trigger `@OnActivated` and `@OnDeactivation` decorated methods.
+ * - Register/unregister `@OnCommand`, `@OnEvent` and `@OnQuery` handlers.
+ * - Set up event dispatching and bus subscriptions.
+ * - Track and dispose injected {@link WireScope} instances.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the service instance.
  *
- * @param container - target Inversify container
- * @param entry - service constructor
- * @param options - options object to control binding flow
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Service class constructor.
+ * @param options - Configuration options for the binding.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class UserService {
+ *   @OnActivated()
+ *   public onActivated(): void {
+ *     console.log("UserService activated");
+ *   }
+ *
+ *   @OnDeactivation()
+ *   public onDeactivation(): void {
+ *     console.log("UserService deactivating");
+ *   }
+ *
+ *   @OnEvent("USER_LOGGED_IN")
+ *   private onUserLoggedIn(event: UserLoggedInEvent) {
+ *     console.log('User logged in:', event.payload);
+ *   }
+ *
+ *   @OnCommand("LOG_DATE_NOW")
+ *   private onLogDateNow(): void {
+ *     console.log("Date now:", new Date());
+ *   }
+ *
+ *   @OnQuery("DATE_NOW")
+ *   private onQueryDateNow(): void {
+ *     return new Date();
+ *   }
+ * }
+ *
+ * bindService(container, UserService);
+ * ```
  */
 function bindService(container, entry, options) {
   // Inversify's fluent binding API only allows a single `.onActivation` /
@@ -776,9 +1381,10 @@ function bindService(container, entry, options) {
 /**
  * Attaches a event subscription to a service.
  *
- * @param service - service instance
- * @param handler - event handler
  * @internal
+ *
+ * @param service - Service instance.
+ * @param handler - Event handler.
  */
 function attachEventsSubscription(service, handler) {
   var _a;
@@ -790,8 +1396,9 @@ function attachEventsSubscription(service, handler) {
 /**
  * Detaches the event subscription from a service.
  *
- * @param service - service instance
  * @internal
+ *
+ * @param service - Service instance.
  */
 function detachEventSubscription(service) {
   var unsubscribe = EVENT_UNSUBSCRIBERS_BY_SERVICE.get(service);
@@ -803,9 +1410,10 @@ function detachEventSubscription(service) {
 /**
  * Registers a query unregister function for a service.
  *
- * @param service - service instance
- * @param unregister - query unregister function
  * @internal
+ *
+ * @param service - Service instance.
+ * @param unregister - Query unregister function.
  */
 function attachQueryUnregister(service, unregister) {
   var list = QUERY_UNREGISTERS_BY_SERVICE.get(service);
@@ -818,8 +1426,9 @@ function attachQueryUnregister(service, unregister) {
 /**
  * Executes and removes all query unregister functions for a service.
  *
- * @param service - service instance
  * @internal
+ *
+ * @param service - Service instance.
  */
 function detachQueryUnregister(service) {
   var list = QUERY_UNREGISTERS_BY_SERVICE.get(service);
@@ -835,9 +1444,10 @@ function detachQueryUnregister(service) {
 /**
  * Registers a command unregister function for a service.
  *
- * @param service - service instance
- * @param unregister - command unregister function
  * @internal
+ *
+ * @param service - Service instance.
+ * @param unregister - Command unregister function.
  */
 function attachCommandUnregister(service, unregister) {
   var list = COMMAND_UNREGISTERS_BY_SERVICE.get(service);
@@ -850,8 +1460,9 @@ function attachCommandUnregister(service, unregister) {
 /**
  * Executes and removes all command unregister functions for a service.
  *
- * @param service - service instance
  * @internal
+ *
+ * @param service - Service instance.
  */
 function detachCommandUnregister(service) {
   var list = COMMAND_UNREGISTERS_BY_SERVICE.get(service);
@@ -869,11 +1480,12 @@ function detachCommandUnregister(service) {
  * Property iteration happens only when the constructor metadata declares a WireScope
  * parameter, avoiding false positives from manually created or subclassed scopes.
  *
- * todo: Simplify this part.
+ * Todo: Simplify this part..
  *
- * @param service - service instance
- * @param Service - service constructor
  * @internal
+ *
+ * @param service - Service instance.
+ * @param Service - Service constructor.
  */
 function attachWireScopes(service, Service) {
   var paramTypes = Reflect.getMetadata("design:paramtypes", Service);
@@ -898,10 +1510,11 @@ function attachWireScopes(service, Service) {
  * Marks all injected WireScope instances for this service as disposed and removes
  * the stored references.
  *
- * todo: Simplify this part.
+ * Todo: Simplify this part..
  *
- * @param service - service instance
  * @internal
+ *
+ * @param service - Service instance.
  */
 function detachWireScopes(service) {
   var scopes = WIRE_SCOPES_BY_SERVICE.get(service);
@@ -917,72 +1530,242 @@ function detachWireScopes(service) {
 }
 
 /**
- * Binds a single service entry to the container, dispatching to the
- * correct binding strategy based on the descriptor's `type` field.
+ * Binds an entry to the Inversify {@link Container} using the appropriate strategy.
+ *
+ * @remarks
+ * This is a high-level dispatching function that selects the binding method based on the `entry` type:
+ * - **Class Constructor**: Binds as a singleton service via {@link bindService}.
+ * - **ConstantValue**: Binds a fixed value via {@link bindConstant}.
+ * - **DynamicValue**: Binds a factory-generated value via {@link bindDynamicValue}.
+ * - **Instance**: Binds a value as a class instance via {@link bindService}.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the object being bound.
+ *
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Class constructor or {@link InjectableDescriptor} describing the service.
+ * @param options - Optional binding configuration (primarily used for class-based services).
+ *
+ * @throws {@link WirestateError} If `entry.scopeBindingType` is not `Singleton` for constant values.
+ *
+ * @example
+ * ```typescript
+ * // Binding a class constructor (defaults to singleton)
+ * class MyService {}
  *
- * Supports:
- * - Service classes (function entries) - bound as singleton
- * - Constant values - bound via `bindConstant`
- * - Dynamic values - bound via `toDynamicValue` with optional scope
- * - Instance bindings - bound as generic singleton service
+ * bindEntry(container, MyService);
  *
- * @param container - target IOC container to bind into
- * @param entry - entry descriptor to bind
- * @param options - optional binding configuration
- * @returns void
+ * // Binding a constant value
+ * const API_URL: unique symbol = Symbol("API_URL");
+ *
+ * bindEntry(container, {
+ *   id: API_URL,
+ *   value: "https://api.example.com"
+ * });
+ *
+ * // Binding a dynamic value (factory)
+ * const CURRENT_TIME: unique symbol = Symbol("CURRENT_TIME");
+ *
+ * bindEntry(container, {
+ *   id: CURRENT_TIME,
+ *   bindingType: "DynamicValue",
+ *   factory: () => new Date()
+ * });
+ * ```
  */
 function bindEntry(container, entry, options) {
   if (options === void 0) {
     options = {};
   }
   if (typeof entry === "function") {
-    return bindService(container, entry, options);
+    bindService(container, entry, options);
+    return;
   }
   if (!entry.bindingType || entry.bindingType === inversify.bindingTypeValues.ConstantValue) {
-    return bindConstant(container, entry);
+    bindConstant(container, entry);
+    return;
   }
   if (entry.bindingType === inversify.bindingTypeValues.DynamicValue) {
-    return bindDynamicValue(container, entry);
+    bindDynamicValue(container, entry);
+    return;
   }
   // Default: treat as class descriptor (Instance binding).
-  return bindService(container, entry.value, options);
+  bindService(container, entry.value, options);
 }
 
 /**
- * Returns the container token for a service entry.
- * For plain service classes the class itself is the token;
- * for descriptors the `id` field is used.
+ * Resolves the identifier for a given entry.
+ *
+ * @remarks
+ * Handles both plain service classes and injectable descriptors:
+ * - If `entry` is a class constructor, it is returned as the identifier.
+ * - If `entry` is an {@link InjectableDescriptor}, its `id` field is returned.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the injectable object.
+ *
+ * @param entry - Class constructor or descriptor to get the identifier for.
+ * @returns Identifier token for Inversify.
  *
- * @param entry - entry descriptor to get service identifier for
- * @returns injectable identifier token
+ * @example
+ * ```typescript
+ * class MyService {}
+ *
+ * getEntryToken(MyService); // returns MyService
+ *
+ * getEntryToken({ id: "my-service" }); // returns "my-service"
+ * ```
  */
 function getEntryToken(entry) {
   return typeof entry === "function" ? entry : entry.id;
 }
 
 /**
- * Creates an IoC container with framework essentials.
+ * Applies targeted seeds to the container's internal seed map.
+ *
+ * @remarks
+ * This function updates the existing {@link SeedsMap} instance instead of replacing it.
+ * This ensures that multiple providers can co-exist and contribute their own seeds
+ * without overwriting each other's data.
+ *
+ * @group Seeds
+ *
+ * @param container - The Inversify {@link Container} where seeds should be applied.
+ * @param seeds - An array of {@link SeedEntries} to add to the container.
  *
- * @param options - container configuration
- * @returns new IoC container
+ * @example
+ * ```typescript
+ * applySeeds(container, [
+ *   [UserService, { initialUser: "admin" }],
+ *   ["API_KEY", "12345"]
+ * ]);
+ * ```
  */
-function createIocContainer(options) {
-  var _a;
-  if (options === void 0) {
-    options = {};
+function applySeeds(container, seeds) {
+  var existing = container.get(SEEDS_TOKEN);
+  for (var _i = 0, seeds_1 = seeds; _i < seeds_1.length; _i++) {
+    var _a = seeds_1[_i],
+      key = _a[0],
+      state = _a[1];
+    existing.set(key, state);
   }
+}
+
+/**
+ * Creates the foundational {@link Container} used by Wirestate.
+ *
+ * @remarks
+ * This helper configures the core container primitives shared by higher-level
+ * container factories:
+ * - sets the default scope to `Singleton`
+ * - binds the core buses: {@link EventBus}, {@link QueryBus}, and {@link CommandBus}
+ * - registers the seed map tokens: `SEEDS_TOKEN` and `SEED_TOKEN`
+ * - applies any targeted seed entries passed in `options.seeds`
+ *
+ * @group Container
+ * @internal
+ *
+ * @param options - Base container configuration.
+ * @returns A configured {@link Container} instance.
+ *
+ * @example
+ * ```typescript
+ * const SOME_TOKEN: unique symbol = Symbol("SOME_TOKEN");
+ *
+ * const container: Container = createBaseContainer({
+ *   seed: { environment: "test" },
+ *   seeds: [
+ *     [SOME_TOKEN, { value: 123 }],
+ *   ],
+ * });
+ *
+ * const rootSeed = container.get(SEED_TOKEN);
+ * ```
+ */
+function createBaseContainer(options) {
+  var _a;
   var container = new inversify.Container({
-    defaultScope: "Singleton",
-    parent: options.parent
+    parent: options.parent,
+    defaultScope: "Singleton"
   });
   container.bind(EventBus).toConstantValue(new EventBus());
   container.bind(QueryBus).toConstantValue(new QueryBus());
   container.bind(CommandBus).toConstantValue(new CommandBus());
   container.bind(SEEDS_TOKEN).toConstantValue(new Map());
   container.bind(SEED_TOKEN).toConstantValue((_a = options.seed) !== null && _a !== void 0 ? _a : {});
+  if (options.seeds) {
+    applySeeds(container, options.seeds);
+  }
+  return container;
+}
+
+/**
+ * Creates an Inversify IoC container pre-configured with Wirestate essentials.
+ *
+ * @remarks
+ * The container is initialized with:
+ * - State management tokens: `SEEDS_TOKEN` and `SEED_TOKEN`.
+ * - Messaging buses: {@link EventBus}, {@link QueryBus}, {@link CommandBus}.
+ * - Service bridge: {@link WireScope} (bound in transient scope).
+ * - Default scope set to `Singleton`.
+ *
+ * @group Container
+ *
+ * @param options - {@link CreateContainerOptions} configuration.
+ * @returns A new Inversify {@link Container} instance.
+ *
+ * @example
+ * ```typescript
+ * const container: Container = createContainer({
+ *   seeds: [
+ *     [CounterService, { count: 1000 }],
+ *     ["SOME_KEY", "VALUE"],
+ *   ],
+ *   entries: [CounterService, LoggerService],
+ *   activate: [LoggerService]
+ * });
+ *
+ * bindService(container, MyService);
+ * ```
+ */
+function createContainer(options) {
+  var _a;
+  if (options === void 0) {
+    options = {};
+  }
+  if (options.activate && options.activate.length) {
+    if (!((_a = options.entries) === null || _a === void 0 ? void 0 : _a.length)) {
+      throw new WirestateError(ERROR_CODE_VALIDATION_ERROR, "Supplied activation list while entries for binding are not provided.");
+    }
+    var entryTokens = options.entries.map(getEntryToken);
+    for (var _i = 0, _b = options.activate; _i < _b.length; _i++) {
+      var eager = _b[_i];
+      if (!entryTokens.includes(eager)) {
+        throw new WirestateError(ERROR_CODE_VALIDATION_ERROR, "createInjectablesProvider: '".concat(String(eager), "' is listed in 'activate' but was not provided in 'entries'."));
+      }
+    }
+  }
+  var container = new inversify.Container({
+    defaultScope: "Singleton",
+    parent: createBaseContainer(options)
+  });
   container.bind(WireScope).toResolvedValue(function () {
     return new WireScope(container);
   }).inTransientScope();
+  if (options.entries) {
+    for (var _c = 0, _d = options.entries; _c < _d.length; _c++) {
+      var entry = _d[_c];
+      bindEntry(container, entry);
+    }
+  }
+  if (options.activate) {
+    for (var _e = 0, _f = options.activate; _e < _f.length; _e++) {
+      var entry = _f[_e];
+      container.get(entry);
+    }
+  }
   return container;
 }
 
@@ -999,9 +1782,11 @@ exports.SEEDS_TOKEN = SEEDS_TOKEN;
 exports.SEED_TOKEN = SEED_TOKEN;
 exports.WireScope = WireScope;
 exports.WirestateError = WirestateError;
+exports.applySeeds = applySeeds;
 exports.bindConstant = bindConstant;
+exports.bindDynamicValue = bindDynamicValue;
 exports.bindEntry = bindEntry;
 exports.bindService = bindService;
-exports.createIocContainer = createIocContainer;
+exports.createContainer = createContainer;
 exports.getEntryToken = getEntryToken;
 //# sourceMappingURL=lib.js.map