@wirestate/core 0.6.3 → 0.7.0-experimental.1

package/esm/development/commands/command-bus.js

@@ -3,10 +3,14 @@ import { WirestateError } from '../error/wirestate-error.js';
 import { CommandStatus } from '../types/commands.js';
 
 /**
- * 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() {
@@ -17,45 +21,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.
+   *
+   * @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.
    *
-   * @throws 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);
@@ -79,31 +70,87 @@ 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.
    *
-   * @param type - command type
-   * @param data - command payload
-   * @returns command descriptor or null 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 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;
 }();

package/esm/development/commands/command-bus.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-bus.js","sources":["../../../../../../../../src/wirestate-core/commands/command-bus.ts"],"sourcesContent":[null],"names":["CommandBus","handlers","Map","prototype","register","type","handler","_this","stack","get","set","push","current","index","indexOf","splice","length","delete","command","data","WirestateError","ERROR_CODE_FAILED_TO_RESOLVE_COMMAND_HANDLER","concat","String","descriptor","task","status","CommandStatus","PENDING","Promise","resolve","then","result","SETTLED","catch","error","ERROR","commandOptional","has","Boolean","_a","clear"],"mappings":"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"}
+{"version":3,"file":"command-bus.js","sources":["../../../../../../../../src/wirestate-core/commands/command-bus.ts"],"sourcesContent":[null],"names":["CommandBus","handlers","Map","prototype","clear","command","type","data","stack","get","length","WirestateError","ERROR_CODE_FAILED_TO_RESOLVE_COMMAND_HANDLER","concat","String","handler","descriptor","task","status","CommandStatus","PENDING","Promise","resolve","then","result","SETTLED","catch","error","ERROR","commandOptional","has","Boolean","_a","register","_this","set","push","unregister","current","index","indexOf","splice","delete"],"mappings":"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"}

package/esm/development/commands/command-optional.js

@@ -1,12 +1,35 @@
 import { CommandBus } from './command-bus.js';
 
 /**
- * Dispatches a command on the provided container, returning null if no handler is registered.
+ * Dispatches a command through the {@link CommandBus} resolved from the container, returning null if no handler exists.
  *
- * @param container - inversify container
- * @param type - command type
- * @param data - command data
- * @returns command descriptor or null
+ * @remarks
+ * This is a convenience wrapper around the `CommandBus.commandOptional` method.
+ * Unlike {@link command}, it does not throw if no handler is registered.
+ *
+ * @group Commands
+ *
+ * @template R - Type of the expected result from the command execution.
+ * @template D - Type of the data (payload) passed to the command.
+ * @template T - Type of the command identifier.
+ *
+ * @param container - Inversify {@link Container} to resolve the {@link CommandBus} from.
+ * @param type - Unique identifier of the command to dispatch.
+ * @param data - Optional payload for the command handler.
+ * @returns A {@link CommandDescriptor} if a handler was found, or `null` otherwise.
+ *
+ * @example
+ * ```typescript
+ * const descriptor = commandOptional<User, FindUserOptions>(
+ *   container,
+ *   "FIND_USER",
+ *   { id: "123" }
+ * );
+ *
+ * if (descriptor) {
+ *   const user: User = await descriptor.task;
+ * }
+ * ```
  */
 function commandOptional(container, type, data) {
   return container.get(CommandBus).commandOptional(type, data);

package/esm/development/commands/command-optional.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-optional.js","sources":["../../../../../../../../src/wirestate-core/commands/command-optional.ts"],"sourcesContent":[null],"names":["commandOptional","container","type","data","get","CommandBus"],"mappings":";;AAUA;;;;;;;AAOG;SACaA,eAAeA,CAC7BC,SAAoB,EACpBC,IAAO,EACPC,IAAQ,EAAA;AAIR,EAAA,OAAOF,SAAS,CAACG,GAAG,CAACC,UAAU,CAAC,CAACL,eAAe,CAAOE,IAAI,EAAEC,IAAI,CAAC;AACpE;;;;"}
+{"version":3,"file":"command-optional.js","sources":["../../../../../../../../src/wirestate-core/commands/command-optional.ts"],"sourcesContent":[null],"names":["commandOptional","container","type","data","get","CommandBus"],"mappings":";;AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BG;SACaA,eAAeA,CAC7BC,SAAoB,EACpBC,IAAO,EACPC,IAAQ,EAAA;AAIR,EAAA,OAAOF,SAAS,CAACG,GAAG,CAACC,UAAU,CAAC,CAACL,eAAe,CAAOE,IAAI,EAAEC,IAAI,CAAC;AACpE;;;;"}

package/esm/development/commands/command.js

@@ -1,12 +1,33 @@
 import { CommandBus } from './command-bus.js';
 
 /**
- * Dispatches a command on the provided container.
+ * Dispatches a command through the {@link CommandBus} resolved from the container.
  *
- * @param container - inversify container
- * @param type - command type
- * @param data - command data
- * @returns command descriptor
+ * @remarks
+ * This is a convenience wrapper around the `CommandBus.command` method.
+ * Commands allow for decoupled communication between services.
+ *
+ * @group Commands
+ *
+ * @template R - Type of the expected result from the command execution.
+ * @template D - Type of the data (payload) passed to the command.
+ * @template T - Type of the command identifier.
+ *
+ * @param container - Inversify {@link Container} to resolve the {@link CommandBus} from.
+ * @param type - Unique identifier of the command to dispatch.
+ * @param data - Optional payload for the command handler.
+ * @returns A descriptor to track the command execution and result.
+ *
+ * @example
+ * ```typescript
+ * const descriptor = command<User, UserFindParameters>(
+ *   container,
+ *   "FIND_USER",
+ *   { id: "123" }
+ * );
+ *
+ * const user: User = await descriptor.task;
+ * ```
  */
 function command(container, type, data) {
   return container.get(CommandBus).command(type, data);

package/esm/development/commands/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sources":["../../../../../../../../src/wirestate-core/commands/command.ts"],"sourcesContent":[null],"names":["command","container","type","data","get","CommandBus"],"mappings":";;AASA;;;;;;;AAOG;SACaA,OAAOA,CACrBC,SAAoB,EACpBC,IAAO,EACPC,IAAQ,EAAA;AAIR,EAAA,OAAOF,SAAS,CAACG,GAAG,CAACC,UAAU,CAAC,CAACL,OAAO,CAAOE,IAAI,EAAEC,IAAI,CAAC;AAC5D;;;;"}
+{"version":3,"file":"command.js","sources":["../../../../../../../../src/wirestate-core/commands/command.ts"],"sourcesContent":[null],"names":["command","container","type","data","get","CommandBus"],"mappings":";;AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;SACaA,OAAOA,CACrBC,SAAoB,EACpBC,IAAO,EACPC,IAAQ,EAAA;AAIR,EAAA,OAAOF,SAAS,CAACG,GAAG,CAACC,UAAU,CAAC,CAACL,OAAO,CAAOE,IAAI,EAAEC,IAAI,CAAC;AAC5D;;;;"}

package/esm/development/commands/get-command-handler-metadata.js

@@ -2,11 +2,16 @@ import { COMMAND_HANDLER_METADATA } from '../registry.js';
 
 /**
  * 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;

package/esm/development/commands/get-command-handler-metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-command-handler-metadata.js","sources":["../../../../../../../../src/wirestate-core/commands/get-command-handler-metadata.ts"],"sourcesContent":[null],"names":["getCommandHandlerMetadata","instance","constructor","chain","Object","Function","prototype","own","COMMAND_HANDLER_METADATA","get","length","push","getPrototypeOf","reverse","flat"],"mappings":";;AAOA;;;;;;;AAOG;AACG,SAAUA,yBAAyBA,CAACC,QAAgB,EAAA;AAMxD,EAAA,IAAIC,WAAW,GAAYD,QAAQ,CAACC,WAAW;EAE/C,IAAMC,KAAK,GAAyC,EAAE;AAEtD;AACA,EAAA,OAAO,OAAOD,WAAW,KAAK,UAAU,IAAIA,WAAW,KAAKE,MAAM,IAAIF,WAAW,KAAKG,QAAQ,CAACC,SAAS,EAAE;AACxG,IAAA,IAAMC,GAAG,GAAyCC,wBAAwB,CAACC,GAAG,CAACP,WAAqB,CAAC;AAErG,IAAA,IAAIK,GAAG,IAAIA,GAAG,CAACG,MAAM,GAAG,CAAC,EAAE;AACzBP,MAAAA,KAAK,CAACQ,IAAI,CAACJ,GAAG,CAAC;AACjB,IAAA;AAEAL,IAAAA,WAAW,GAAGE,MAAM,CAACQ,cAAc,CAACV,WAAW,CAAC;AAClD,EAAA;AAQA;EACA,OAAOC,KAAK,CAACU,OAAO,EAAE,CAACC,IAAI,EAAE;AAC/B;;;;"}
+{"version":3,"file":"get-command-handler-metadata.js","sources":["../../../../../../../../src/wirestate-core/commands/get-command-handler-metadata.ts"],"sourcesContent":[null],"names":["getCommandHandlerMetadata","instance","constructor","chain","Object","Function","prototype","own","COMMAND_HANDLER_METADATA","get","length","push","getPrototypeOf","reverse","flat"],"mappings":";;AAOA;;;;;;;;;;;;AAYG;AACG,SAAUA,yBAAyBA,CAACC,QAAgB,EAAA;AAMxD,EAAA,IAAIC,WAAW,GAAYD,QAAQ,CAACC,WAAW;EAE/C,IAAMC,KAAK,GAAyC,EAAE;AAEtD;AACA,EAAA,OAAO,OAAOD,WAAW,KAAK,UAAU,IAAIA,WAAW,KAAKE,MAAM,IAAIF,WAAW,KAAKG,QAAQ,CAACC,SAAS,EAAE;AACxG,IAAA,IAAMC,GAAG,GAAyCC,wBAAwB,CAACC,GAAG,CAACP,WAAqB,CAAC;AAErG,IAAA,IAAIK,GAAG,IAAIA,GAAG,CAACG,MAAM,GAAG,CAAC,EAAE;AACzBP,MAAAA,KAAK,CAACQ,IAAI,CAACJ,GAAG,CAAC;AACjB,IAAA;AAEAL,IAAAA,WAAW,GAAGE,MAAM,CAACQ,cAAc,CAACV,WAAW,CAAC;AAClD,EAAA;AAQA;EACA,OAAOC,KAAK,CAACU,OAAO,EAAE,CAACC,IAAI,EAAE;AAC/B;;;;"}

package/esm/development/commands/on-command.js

@@ -1,10 +1,26 @@
 import { COMMAND_HANDLER_METADATA } from '../registry.js';
 
 /**
- * Decorator for service methods that handle a command.
+ * Decorator for service methods that handle a specific command.
  *
- * @param type - command type identifier
- * @returns decorator function
+ * @remarks
+ * Methods decorated with `@OnCommand` are automatically registered as command handlers
+ * when the service is bound via {@link bindService}.
+ *
+ * @group Commands
+ *
+ * @param type - Unique identifier of the command to handle.
+ * @returns A method decorator function.
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @OnCommand("USER_LOGIN")
+ *   private onUserLogin(credentials: Credentials): Promise<Session> {
+ *     return auth.login(credentials);
+ *   }
+ * }
+ * ```
  */
 function OnCommand(type) {
   return function (target, propertyKey) {

package/esm/development/commands/on-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"on-command.js","sources":["../../../../../../../../src/wirestate-core/commands/on-command.ts"],"sourcesContent":[null],"names":["OnCommand","type","target","propertyKey","constructor","list","COMMAND_HANDLER_METADATA","get","set","push","methodName"],"mappings":";;AAOA;;;;;AAKG;AACG,SAAUA,SAASA,CAACC,IAAiB,EAAA;AACzC,EAAA,OAAO,UAACC,MAAM,EAAEC,WAAW,EAAA;AASzB,IAAA,IAAMC,WAAW,GAAGF,MAAM,CAACE,WAAW;AAEtC,IAAA,IAAIC,IAAI,GAAyCC,wBAAwB,CAACC,GAAG,CAACH,WAAW,CAAC;IAE1F,IAAI,CAACC,IAAI,EAAE;AACTA,MAAAA,IAAI,GAAG,EAAE;AACTC,MAAAA,wBAAwB,CAACE,GAAG,CAACJ,WAAW,EAAEC,IAAI,CAAC;AACjD,IAAA;AAEA;IACAA,IAAI,CAACI,IAAI,CAAC;AAAEC,MAAAA,UAAU,EAAEP,WAAW;AAAEF,MAAAA,IAAI,EAAAA;AAAA,KAAE,CAAC;EAC9C,CAAC;AACH;;;;"}
+{"version":3,"file":"on-command.js","sources":["../../../../../../../../src/wirestate-core/commands/on-command.ts"],"sourcesContent":[null],"names":["OnCommand","type","target","propertyKey","constructor","list","COMMAND_HANDLER_METADATA","get","set","push","methodName"],"mappings":";;AAOA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,SAAUA,SAASA,CAACC,IAAiB,EAAA;AACzC,EAAA,OAAO,UAACC,MAAM,EAAEC,WAAW,EAAA;AASzB,IAAA,IAAMC,WAAW,GAAGF,MAAM,CAACE,WAAW;AAEtC,IAAA,IAAIC,IAAI,GAAyCC,wBAAwB,CAACC,GAAG,CAACH,WAAW,CAAC;IAE1F,IAAI,CAACC,IAAI,EAAE;AACTA,MAAAA,IAAI,GAAG,EAAE;AACTC,MAAAA,wBAAwB,CAACE,GAAG,CAACJ,WAAW,EAAEC,IAAI,CAAC;AACjD,IAAA;AAEA;IACAA,IAAI,CAACI,IAAI,CAAC;AAAEC,MAAAA,UAAU,EAAEP,WAAW;AAAEF,MAAAA,IAAI,EAAAA;AAAA,KAAE,CAAC;EAC9C,CAAC;AACH;;;;"}

package/esm/development/container/create-base-container.js

@@ -0,0 +1,57 @@
+import { Container } from 'inversify';
+import { CommandBus } from '../commands/command-bus.js';
+import { EventBus } from '../events/event-bus.js';
+import { QueryBus } from '../queries/query-bus.js';
+import { applySeeds } from '../seeds/apply-seeds.js';
+import { SEEDS_TOKEN, SEED_TOKEN } from '../seeds/tokens.js';
+
+/**
+ * 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 Container({
+    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;
+}
+
+export { createBaseContainer };
+//# sourceMappingURL=create-base-container.js.map

package/esm/development/container/create-base-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-base-container.js","sources":["../../../../../../../../src/wirestate-core/container/create-base-container.ts"],"sourcesContent":[null],"names":["createBaseContainer","options","container","Container","parent","defaultScope","bind","EventBus","toConstantValue","QueryBus","CommandBus","SEEDS_TOKEN","Map","SEED_TOKEN","_a","seed","seeds","applySeeds"],"mappings":";;;;;;;AAmCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BG;AACG,SAAUA,mBAAmBA,CAACC,OAAmC,EAAA;;AACrE,EAAA,IAAMC,SAAS,GAAc,IAAIC,SAAS,CAAC;IACzCC,MAAM,EAAEH,OAAO,CAACG,MAAM;AACtBC,IAAAA,YAAY,EAAE;AACf,GAAA,CAAC;AAEFH,EAAAA,SAAS,CAACI,IAAI,CAACC,QAAQ,CAAC,CAACC,eAAe,CAAC,IAAID,QAAQ,EAAE,CAAC;AACxDL,EAAAA,SAAS,CAACI,IAAI,CAACG,QAAQ,CAAC,CAACD,eAAe,CAAC,IAAIC,QAAQ,EAAE,CAAC;AACxDP,EAAAA,SAAS,CAACI,IAAI,CAACI,UAAU,CAAC,CAACF,eAAe,CAAC,IAAIE,UAAU,EAAE,CAAC;AAE5DR,EAAAA,SAAS,CAACI,IAAI,CAACK,WAAW,CAAC,CAACH,eAAe,CAAC,IAAII,GAAG,EAAc,CAAC;EAClEV,SAAS,CAACI,IAAI,CAACO,UAAU,CAAC,CAACL,eAAe,CAAC,CAAAM,EAAA,GAAAb,OAAO,CAACc,IAAI,MAAA,IAAA,IAAAD,EAAA,KAAA,MAAA,GAAAA,EAAA,GAAI,EAAE,CAAC;EAE9D,IAAIb,OAAO,CAACe,KAAK,EAAE;AACjBC,IAAAA,UAAU,CAACf,SAAS,EAAED,OAAO,CAACe,KAAK,CAAC;AACtC,EAAA;AAEA,EAAA,OAAOd,SAAS;AAClB;;;;"}

package/esm/development/container/create-container.js

@@ -0,0 +1,78 @@
+import { createBaseContainer } from './create-base-container.js';
+import { WireScope } from './wire-scope.js';
+import { Container } from 'inversify';
+import { bindEntry } from '../bind/bind-entry.js';
+import { getEntryToken } from '../bind/get-entry-token.js';
+import { ERROR_CODE_VALIDATION_ERROR } from '../error/error-code.js';
+import { WirestateError } from '../error/wirestate-error.js';
+
+/**
+ * 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 = createIocContainer({
+ *   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 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;
+}
+
+export { createContainer };
+//# sourceMappingURL=create-container.js.map

package/esm/development/container/create-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-container.js","sources":["../../../../../../../../src/wirestate-core/container/create-container.ts"],"sourcesContent":[null],"names":["createContainer","options","activate","length","_a","entries","WirestateError","ERROR_CODE_VALIDATION_ERROR","entryTokens","map","getEntryToken","_i","_b","eager","includes","concat","String","container","Container","defaultScope","parent","createBaseContainer","bind","WireScope","toResolvedValue","inTransientScope","_c","_d","entry","bindEntry","_e","_f","get"],"mappings":";;;;;;;;AAuDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;AACG,SAAUA,eAAeA,CAACC,OAAoC,EAAA;;AAApC,EAAA,IAAAA,OAAA,KAAA,MAAA,EAAA;IAAAA,OAAA,GAAA,EAAoC;AAAA,EAAA;EAGlE,IAAIA,OAAO,CAACC,QAAQ,IAAID,OAAO,CAACC,QAAQ,CAACC,MAAM,EAAE;IAC/C,IAAI,EAAC,CAAAC,EAAA,GAAAH,OAAO,CAACI,OAAO,MAAA,IAAA,IAAAD,EAAA,KAAA,MAAA,GAAA,MAAA,GAAAA,EAAA,CAAED,MAAM,CAAA,EAAE;AAC5B,MAAA,MAAM,IAAIG,cAAc,CACtBC,2BAA2B,EAC3B,sEAAsE,CACvE;AACH,IAAA;IAEA,IAAMC,WAAW,GAAqCP,OAAO,CAACI,OAAO,CAACI,GAAG,CAACC,aAAa,CAAC;AAExF,IAAA,KAAoB,IAAAC,EAAA,GAAA,CAAgB,EAAhBC,EAAA,GAAAX,OAAO,CAACC,QAAQ,EAAhBS,EAAA,GAAAC,EAAA,CAAAT,MAAgB,EAAhBQ,EAAA,EAAgB,EAAE;AAAjC,MAAA,IAAME,KAAK,GAAAD,EAAA,CAAAD,EAAA,CAAA;AACd,MAAA,IAAI,CAACH,WAAW,CAACM,QAAQ,CAACD,KAAK,CAAC,EAAE;AAChC,QAAA,MAAM,IAAIP,cAAc,CACtBC,2BAA2B,EAC3B,8BAAA,CAAAQ,MAAA,CAA+BC,MAAM,CAACH,KAAK,CAAC,EAAA,8DAAA,CAA8D,CAC3G;AACH,MAAA;AACF,IAAA;AACF,EAAA;AAEA,EAAA,IAAMI,SAAS,GAAc,IAAIC,SAAS,CAAC;AACzCC,IAAAA,YAAY,EAAE,WAAW;IACzBC,MAAM,EAAEC,mBAAmB,CAACpB,OAAO;AACpC,GAAA,CAAC;EAEFgB,SAAS,CACNK,IAAI,CAACC,SAAS,CAAC,CACfC,eAAe,CAAC,YAAA;AAAiB,IAAA,OAAA,IAAID,SAAS,CAACN,SAAS,CAAC;AAAxB,EAAA,CAAwB,CAAC,CAC1DQ,gBAAgB,EAAE;EAIrB,IAAIxB,OAAO,CAACI,OAAO,EAAE;AACnB,IAAA,KAAoB,IAAAqB,EAAA,GAAA,CAAe,EAAfC,EAAA,GAAA1B,OAAO,CAACI,OAAO,EAAfqB,EAAA,GAAAC,EAAA,CAAAxB,MAAe,EAAfuB,EAAA,EAAe,EAAE;AAAhC,MAAA,IAAME,KAAK,GAAAD,EAAA,CAAAD,EAAA,CAAA;AACdG,MAAAA,SAAS,CAACZ,SAAS,EAAEW,KAAK,CAAC;AAC7B,IAAA;AACF,EAAA;EAEA,IAAI3B,OAAO,CAACC,QAAQ,EAAE;AACpB,IAAA,KAAoB,IAAA4B,EAAA,GAAA,CAAgB,EAAhBC,EAAA,GAAA9B,OAAO,CAACC,QAAQ,EAAhB4B,EAAA,GAAAC,EAAA,CAAA5B,MAAgB,EAAhB2B,EAAA,EAAgB,EAAE;AAAjC,MAAA,IAAMF,KAAK,GAAAG,EAAA,CAAAD,EAAA,CAAA;AACdb,MAAAA,SAAS,CAACe,GAAG,CAACJ,KAAK,CAAC;AACtB,IAAA;AACF,EAAA;AAEA,EAAA,OAAOX,SAAS;AAClB;;;;"}