@wirestate/core 0.6.1 → 0.7.0-experimental.1

package/lib.d.ts

@@ -1,17 +1,136 @@
-import { ServiceIdentifier, bindingTypeValues, bindingScopeValues } from 'inversify';
+import { bindingTypeValues, ServiceIdentifier, bindingScopeValues, Newable } from 'inversify';
 
+/**
+ * Inversify binding strategy types.
+ *
+ * @group Bind
+ */
 type BindingType = (typeof bindingTypeValues)[keyof typeof bindingTypeValues];
+/**
+ * Inversify scope strategy types.
+ *
+ * @group Bind
+ */
 type ScopeBindingType = (typeof bindingScopeValues)[keyof typeof bindingScopeValues];
+/**
+ * Represents descriptor used by wirestate bind/provision APIs to describe how one injectable is resolved.
+ *
+ * @remarks
+ * This interface bridges standard Inversify binding options with Wirestate's simplified registration API.
+ * It is used by {@link bindConstant}, {@link bindDynamicValue}, and {@link bindEntry}.
+ *
+ * @group Bind
+ *
+ * @template T - Service type resolved from container by {@link id} or returned by {@link factory}.
+ * @template V - Value type used by constant/value-style bindings via {@link value}.
+ *
+ * @example
+ * ```typescript
+ * const descriptor: InjectableDescriptor<UserRepo> = {
+ *   id: UserRepo,
+ *   scopeBindingType: "Singleton"
+ * };
+ * ```
+ */
 interface InjectableDescriptor<T = unknown, V = unknown> {
-    id: ServiceIdentifier<T>;
-    value?: V;
-    bindingType?: BindingType;
-    scopeBindingType?: ScopeBindingType;
     /**
-     * Factory function for dynamic value bindings.
-     * Used when type is set to DynamicValue.
+     * Inversify binding strategy.
+     *
+     * @remarks
+     * Example values: `ConstantValue`, `DynamicValue`, `Factory`, `Provider`.
      */
-    factory?: () => T;
+    readonly bindingType?: BindingType;
+    /**
+     * Factory function used by dynamic value bindings.
+     *
+     * @remarks
+     * Called by the {@link Container} to create a service instance of type T.
+     */
+    readonly factory?: () => T;
+    /**
+     * Unique service token used by Inversify to locate the injectable binding.
+     *
+     * @remarks
+     * Accepts class constructor, symbol, or string service identifier.
+     */
+    readonly id: ServiceIdentifier<T>;
+    /**
+     * Inversify scope strategy for created instances.
+     *
+     * @remarks
+     * Example values: `Singleton`, `Transient`, `Request`.
+     */
+    readonly scopeBindingType?: ScopeBindingType;
+    /**
+     * Prebuilt value for value-based bindings.
+     *
+     * @remarks
+     * Used when binding mode expects a direct value instance (e.g., constant values).
+     */
+    readonly value?: V;
 }
 
-export type { InjectableDescriptor as I };
+/**
+ * Generic object with string or symbol keys and any value.
+ *
+ * @group general-types
+ */
+type AnyObject = Record<string | symbol, any>;
+/**
+ * Represents a value that can be null.
+ *
+ * @template T - The base type.
+ * @group general-types
+ */
+type Optional<T> = T | null;
+/**
+ * Represents a value that can be a T or a Promise resolving to T.
+ *
+ * @template T - The base type.
+ * @group general-types
+ */
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Represents a lookup key for service seeds.
+ *
+ * @remarks
+ * Supports class constructors (for targeted seeds), strings, or symbols.
+ *
+ * @group Seeds
+ */
+type SeedKey = Newable | string | symbol;
+/**
+ * Represents a key-value map for targeted seeds.
+ *
+ * @remarks
+ * Used to store initial state values that are injected into services
+ * based on their class constructor or a custom token.
+ *
+ * @group Seeds
+ *
+ * @template T - The type of values stored in the map.
+ */
+type SeedsMap<T = unknown> = Map<SeedKey, T>;
+/**
+ * Represents a single service-to-seed mapping entry.
+ *
+ * @remarks
+ * Represented as a readonly tuple of `[SeedKey, T]`.
+ *
+ * @group Seeds
+ *
+ * @template T - The type of the seed value.
+ */
+type SeedEntry<T = unknown> = readonly [SeedKey, T];
+/**
+ * Represents a collection of seed entries.
+ *
+ * @remarks
+ * Used during container initialization to populate the {@link SeedsMap}.
+ *
+ * @group Seeds
+ */
+type SeedEntries = ReadonlyArray<SeedEntry>;
+
+export type { AnyObject as A, InjectableDescriptor as I, MaybePromise as M, Optional as O, SeedEntries as S, SeedKey as a, SeedEntry as b, SeedsMap as c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirestate/core",
-  "version": "0.6.1",
+  "version": "0.7.0-experimental.1",
   "description": "Store management library core based on inversify",
   "sideEffects": false,
   "author": "Syrotenko Igor",
@@ -54,7 +54,6 @@
     "inversify": "^8.1.0"
   },
   "peerDependencies": {
-    "reflect-metadata": ">=0.2.0",
     "tslib": ">=2.5.0"
   },
   "optionalDependencies": {}

package/test-utils.d.ts

@@ -1,107 +1,207 @@
 import { Container as Container$1, Newable, ServiceIdentifier } from 'inversify';
-import { I as InjectableDescriptor } from './lib.js';
+import { I as InjectableDescriptor, A as AnyObject, S as SeedEntries } from './lib.js';
 
 /**
- * Options for {@link mockBindService}.
+ * Represents options for {@link mockBindService}.
+ *
+ * @group Test-utils
  */
 interface MockBindServiceOptions {
     /**
      * Whether to skip the activation lifecycle for the service.
-     * If true, `OnActivated` and `OnDeactivation` hooks will not be triggered.
+     *
+     * @remarks
+     * If true, `@OnActivated` and `@OnDeactivation` hooks will not be triggered.
+     *
+     * @default false
      */
     skipLifecycle?: boolean;
 }
 /**
  * Binds a service class to the IoC container for testing purposes.
- * This utility uses {@link bindService} internally to ensure the service is correctly registered
- * with the appropriate scope and metadata.
  *
- * @param container - the IoC container to bind the service to
- * @param ServiceClass - the service class to bind
- * @param options - optional binding configuration
- * @returns void
+ * @remarks
+ * This utility is a testing wrapper for {@link bindService}.
+ * It ensures the service is correctly registered with singleton scope and lifecycle metadata.
+ *
+ * @group Test-utils
+ *
+ * @template T - The type of the service being bound.
+ *
+ * @param container - The Inversify {@link Container} to bind the service to.
+ * @param ServiceClass - The service class constructor to bind.
+ * @param options - Configuration options for the mock binding.
+ *
+ * @example
+ * ```typescript
+ * mockBindService(container, AnalyticsService);
+ * ```
  */
 declare function mockBindService<T extends object>(container: Container$1, ServiceClass: Newable<T>, options?: MockBindServiceOptions): void;
 
 /**
- * Options for {@link mockBindEntry}.
+ * Represents options for {@link mockBindEntry}.
+ *
+ * @group Test-utils
  */
 interface MockBindEntryOptions {
     /**
      * Whether to skip the activation lifecycle for the entry.
-     * If true, `OnActivated` and `OnDeactivation` hooks will not be triggered.
-     * Note: This only applies when the entry is a service class or an instance binding.
+     *
+     * @remarks
+     * If true, `@OnActivated` and `@OnDeactivation` hooks will not be triggered.
+     * This only applies when the entry is a service class or an instance binding.
+     *
+     * @default false
      */
     skipLifecycle?: boolean;
 }
 /**
  * Binds a service entry to the IoC container for testing purposes.
- * This utility uses {@link bindEntry} internally.
- * It supports both service classes and injectable descriptors (constants, dynamic values, etc.).
  *
- * @param container - the IoC container to bind the entry to
- * @param entry - the service class or injectable descriptor to bind
- * @param options - optional binding configuration
- * @returns void
+ * @remarks
+ * This utility is a testing wrapper for {@link bindEntry}.
+ * It supports both service classes and {@link InjectableDescriptor} objects.
+ *
+ * @group Test-utils
+ *
+ * @template T - The type of the service being bound.
+ *
+ * @param container - The Inversify {@link Container} to bind the entry to.
+ * @param entry - The service class constructor or {@link InjectableDescriptor} to bind.
+ * @param options - Configuration options for the mock binding.
+ *
+ * @example
+ * ```typescript
+ * mockBindEntry(container, UserService, { skipLifecycle: true });
+ * ```
  */
 declare function mockBindEntry<T extends object>(container: Container$1, entry: Newable<T> | InjectableDescriptor, options?: MockBindEntryOptions): void;
 
 /**
  * Unbinds a service from the IoC container.
- * This is useful in tests to reset or override specific service registrations.
  *
- * @param container - the IoC container to unbind the service from
- * @param ServiceClass - the service class to unbind
+ * @remarks
+ * This is a convenience wrapper for `container.unbind`.
+ * It is useful in tests to reset or override specific service registrations
+ * between test cases.
+ *
+ * @group Test-utils
+ *
+ * @template T - The type of the service to unbind.
+ *
+ * @param container - The Inversify {@link Container} to unbind from.
+ * @param ServiceClass - The service class constructor to unbind.
+ *
+ * @example
+ * ```typescript
+ * mockUnbindService(container, LegacyService);
+ * ```
  */
 declare function mockUnbindService<T extends object>(container: Container$1, ServiceClass: Newable<T>): void;
 
 /**
- * Options for {@link mockContainer}.
+ * Represents options for {@link mockContainer}.
+ *
+ * @group Test-utils
  */
 interface MockContainerOptions {
+    /**
+     * Optional parent container.
+     * Enables hierarchical resolution and sharing of bindings.
+     */
+    readonly parent?: Container$1;
+    /**
+     * Initial data for the root seed.
+     */
+    readonly seed?: AnyObject;
+    /**
+     * Targeted seeds bound to specific injectables or tokens.
+     */
+    readonly seeds?: SeedEntries;
     /**
      * List of services or injectable descriptors to bind to the container.
+     *
+     * @remarks
+     * Accepts class constructors or {@link InjectableDescriptor} objects.
      */
-    entries?: Array<Newable<object> | InjectableDescriptor>;
+    readonly entries?: Array<Newable<object> | InjectableDescriptor>;
     /**
      * List of injection identifiers to immediately activate after binding.
-     * All identifiers must correspond to entries provided in the `services` list.
+     *
+     * @remarks
+     * Activating a service triggers its resolution and `@OnActivated` hooks.
+     * All identifiers must correspond to entries provided in the `entries` list.
      */
-    activate?: Array<ServiceIdentifier>;
+    readonly activate?: Array<ServiceIdentifier>;
     /**
      * Whether to skip the activation lifecycle for all bound services.
-     * If true, `OnActivated` and `OnDeactivation` hooks will not be triggered.
+     *
+     * @remarks
+     * If true, `@OnActivated` and `@OnDeactivation` hooks will not be triggered.
+     *
+     * @default false
      */
-    skipLifecycle?: boolean;
+    readonly skipLifecycle?: boolean;
 }
 /**
- * Creates and configures a mock IoC container for testing.
- * This utility initializes a new container and binds the provided services or descriptors using {@link mockBindEntry}.
- * It also supports optional immediate activation of services.
+ * Mocks and configures an Inversify {@link Container} for testing.
+ *
+ * @remarks
+ * This utility initializes a new container via {@link createContainer} and
+ * binds the provided `entries` using {@link mockBindEntry}. It can also
+ * automatically resolve (activate) a subset of services.
  *
- * @param options - configuration options for the mock container
- * @returns a configured InversifyJS {@link Container}
+ * @group Test-utils
  *
- * @throws {WirestateError} if an identifier in `activate` is not found in `services`
+ * @param options - Configuration options for the mock container.
+ * @returns A configured Inversify {@link Container}.
+ *
+ * @throws {WirestateError} If an identifier in `activate` is not found in `entries`.
+ *
+ * @example
+ * ```typescript
+ * const container: Container = mockContainer({
+ *   entries: [UserService, AuthService],
+ *   activate: [AuthService]
+ * });
+ * ```
  */
 declare function mockContainer(options?: MockContainerOptions): Container$1;
 
 /**
- * Options for {@link mockService}.
+ * Represents options for {@link mockService}.
+ *
+ * @group Test-utils
  */
 interface MockServiceOptions {
     /**
-     * If true, skips the lifecycle hooks (e.g., OnActivated) during service binding and instantiation.
+     * If true, skips lifecycle hooks (e.g., `@OnActivated`) during binding and instantiation.
+     *
+     * @default false
      */
     skipLifecycle?: boolean;
 }
 /**
- * Mocks a service by binding it to an IoC container and returning its instance.
+ * Mocks a service by binding it to an IoC container and returning its resolved instance.
+ *
+ * @remarks
+ * This is a high-level utility that combines {@link mockContainer} and {@link mockBindService}.
+ * If no container is provided, a fresh one is created.
+ *
+ * @group Test-utils
+ *
+ * @template T - The type of the service being mocked.
+ *
+ * @param service - The service class constructor to mock.
+ * @param container - The Inversify container to use (defaults to a new mock container).
+ * @param options - Additional options for mocking.
+ * @returns The resolved service instance.
  *
- * @param service - the service class to mock
- * @param container - the IoC container to use, defaults to a new {@link mockContainer}
- * @param options - additional options for mocking
- * @returns the instantiated service instance
+ * @example
+ * ```typescript
+ * const service: MyService = mockService(MyService);
+ * ```
  */
 declare function mockService<T extends object>(service: Newable<T>, container?: Container, options?: MockServiceOptions): T;
 

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

@@ -1,35 +0,0 @@
-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 { SEEDS_TOKEN, SEED_TOKEN } from '../registry.js';
-import { WireScope } from './wire-scope.js';
-
-/**
- * Creates an IoC container with framework essentials.
- *
- * @param options - container configuration
- * @returns new IoC container
- */
-function createIocContainer(options) {
-  var _a;
-  if (options === void 0) {
-    options = {};
-  }
-  var container = new Container({
-    defaultScope: "Singleton",
-    parent: options.parent
-  });
-  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 : {});
-  container.bind(WireScope).toResolvedValue(function () {
-    return new WireScope(container);
-  }).inTransientScope();
-  return container;
-}
-
-export { createIocContainer };
-//# sourceMappingURL=create-ioc-container.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"create-ioc-container.js","sources":["../../../../../../../../src/wirestate-core/container/create-ioc-container.ts"],"sourcesContent":[null],"names":["createIocContainer","options","container","Container","defaultScope","parent","bind","EventBus","toConstantValue","QueryBus","CommandBus","SEEDS_TOKEN","Map","SEED_TOKEN","_a","seed","WireScope","toResolvedValue","inTransientScope"],"mappings":";;;;;;;AAyBA;;;;;AAKG;AACG,SAAUA,kBAAkBA,CAACC,OAAuC,EAAA;;AAAvC,EAAA,IAAAA,OAAA,KAAA,MAAA,EAAA;IAAAA,OAAA,GAAA,EAAuC;AAAA,EAAA;AAGxE,EAAA,IAAMC,SAAS,GAAc,IAAIC,SAAS,CAAC;AACzCC,IAAAA,YAAY,EAAE,WAAW;IACzBC,MAAM,EAAEJ,OAAO,CAACI;AACjB,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;AAC5DR,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;EAE9DZ,SAAS,CACNI,IAAI,CAACU,SAAS,CAAC,CACfC,eAAe,CAAC,YAAA;AAAiB,IAAA,OAAA,IAAID,SAAS,CAACd,SAAS,CAAC;AAAxB,EAAA,CAAwB,CAAC,CAC1DgB,gBAAgB,EAAE;AAIrB,EAAA,OAAOhB,SAAS;AAClB;;;;"}

package/esm/production/container/create-ioc-container.js

@@ -1 +0,0 @@
-import{Container as n}from"inversify";import{CommandBus as e}from"../commands/command-bus.js";import{EventBus as o}from"../events/event-bus.js";import{QueryBus as t}from"../queries/query-bus.js";import{SEEDS_TOKEN as r,SEED_TOKEN as i}from"../registry.js";import{WireScope as s}from"./wire-scope.js";function a(a){var u;void 0===a&&(a={});var m=new n({defaultScope:"Singleton",parent:a.parent});return m.bind(o).toConstantValue(new o),m.bind(t).toConstantValue(new t),m.bind(e).toConstantValue(new e),m.bind(r).toConstantValue(new Map),m.bind(i).toConstantValue(null!==(u=a.seed)&&void 0!==u?u:{}),m.bind(s).toResolvedValue((function(){return new s(m)})).inTransientScope(),m}export{a as createIocContainer};//# sourceMappingURL=create-ioc-container.js.map

package/esm/production/container/create-ioc-container.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"create-ioc-container.js","sources":["../../../../../../../../src/wirestate-core/container/create-ioc-container.ts"],"sourcesContent":[null],"names":["Container","CommandBus","EventBus","QueryBus","SEEDS_TOKEN","SEED_TOKEN","WireScope","createIocContainer","options","container","defaultScope","parent","bind","toConstantValue","Map","_a","seed","toResolvedValue","inTransientScope"],"mappings":"oBAyBAA,MAAA,iCAAAC,MAAA,gDAAAC,MAAA,4CAAAC,MAAA,gDAAAC,gBAAAC,MAAA,qCAAAC,MAAA,kBAMM,SAAUC,EAAmBC,cAAA,IAAAA,IAAAA,EAAA,CAAA,GAGjC,IAAMC,EAAuB,IAAIT,EAAU,CACzCU,aAAc,YACdC,OAAQH,EAAQG,SAgBlB,OAbAF,EAAUG,KAAKV,GAAUW,gBAAgB,IAAIX,GAC7CO,EAAUG,KAAKT,GAAUU,gBAAgB,IAAIV,GAC7CM,EAAUG,KAAKX,GAAYY,gBAAgB,IAAIZ,GAC/CQ,EAAUG,KAAKR,GAAaS,gBAAgB,IAAIC,KAChDL,EAAUG,KAAKP,GAAYQ,gBAA4B,QAAZE,EAAAP,EAAQQ,YAAI,IAAAD,EAAAA,EAAI,CAAA,GAE3DN,EACGG,KAAKN,GACLW,iBAAgB,WAAiB,OAAA,IAAIX,EAAUG,EAAd,IACjCS,mBAIIT,CACT,QAAAF"}