@wirestate/core 0.6.0

package/index.d.ts

@@ -0,0 +1,566 @@
+import { ServiceIdentifier, LazyServiceIdentifier, Container, Newable } from 'inversify';
+export { bindingTypeValues as BindingType, Container, ContainerModule, inject as Inject, injectable as Injectable, LazyServiceIdentifier, multiInject as MultiInject, named as Named, Newable, optional as Optional, postConstruct as PostConstruct, preDestroy as PreDestroy, bindingScopeValues as ScopeBindingType, ServiceIdentifier, tagged as Tagged } from 'inversify';
+import { I as IInjectableDescriptor } from './lib.js';
+
+declare function forwardRef<TInstance = unknown>(forward: () => ServiceIdentifier<TInstance>): LazyServiceIdentifier<TInstance>;
+
+interface IBindServiceOptions {
+    isWithIgnoreLifecycle?: boolean;
+}
+/**
+ * Registers a service class in the container with activation/deactivation logic.
+ * Ensures container references, event subscriptions, command and query handlers are managed correctly.
+ *
+ * @param container - target Inversify container
+ * @param entry - service constructor
+ * @param options - options object to control binding flow
+ */
+declare function bindService<T extends object>(container: Container, entry: Newable<T>, options?: IBindServiceOptions): void;
+
+/**
+ * Options for {@link bindEntry}.
+ */
+interface IBindEntryOptions extends IBindServiceOptions {
+    isWithIgnoreLifecycle?: boolean;
+}
+/**
+ * Binds a single service entry to the container, dispatching to the
+ * correct binding strategy based on the descriptor's `type` field.
+ *
+ * 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
+ *
+ * @param container - target IOC container to bind into
+ * @param entry - entry descriptor to bind
+ * @param options - optional binding configuration
+ * @returns void
+ */
+declare function bindEntry<T extends object = object>(container: Container, entry: Newable<T> | IInjectableDescriptor, options?: IBindEntryOptions): void;
+
+/**
+ * Binds a constant value to a token in the container.
+ *
+ * @param container - target Inversify container
+ * @param entry - entry descriptor to bind
+ */
+declare function bindConstant<T>(container: Container, entry: IInjectableDescriptor): void;
+
+/**
+ * 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.
+ *
+ * @param entry - entry descriptor to get service identifier for
+ * @returns injectable identifier token
+ */
+declare function getEntryToken<T extends object = object>(entry: Newable<T> | IInjectableDescriptor): ServiceIdentifier;
+
+type TAnyObject = Record<string, any>;
+type Optional<T> = T | null;
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Command identifier. Use symbols for private commands.
+ */
+type TCommandType = string | symbol;
+/**
+ * Command handler signature.
+ */
+type TCommandHandler<D = unknown, R = unknown> = (data: D) => MaybePromise<R>;
+/**
+ * Command calling function signature.
+ */
+type TCommandCaller<R = unknown, D = unknown, T extends TCommandType = TCommandType> = (type: T, data?: D) => ICommandDescriptor<R>;
+/**
+ * Command calling function signature.
+ */
+type TOptionalCommandCaller<R = unknown, D = unknown, T extends TCommandType = TCommandType> = (type: T, data?: D) => Optional<ICommandDescriptor<R>>;
+/**
+ * Removes a command handler.
+ */
+type TCommandUnregister = () => void;
+/**
+ * Command execution status.
+ */
+declare enum ECommandStatus {
+    PENDING = "pending",
+    SETTLED = "settled",
+    ERROR = "error"
+}
+/**
+ * Descriptor returned by command execution.
+ * Contains the task promise, current status, and responder with result/error.
+ */
+interface ICommandDescriptor<R = unknown> {
+    readonly task: Promise<R>;
+    readonly status: ECommandStatus;
+}
+
+/**
+ * Dispatches a command on the provided container.
+ *
+ * @param container - inversify container
+ * @param type - command type
+ * @param data - command data
+ * @returns command descriptor
+ */
+declare function command<R = unknown, D = unknown, T extends TCommandType = TCommandType>(container: Container, type: T, data?: D): ICommandDescriptor<R>;
+
+/**
+ * Dispatches a command on the provided container, returning null if no handler is registered.
+ *
+ * @param container - inversify container
+ * @param type - command type
+ * @param data - command data
+ * @returns command descriptor or null
+ */
+declare function commandOptional<R = unknown, D = unknown, T extends TCommandType = TCommandType>(container: Container, type: T, data?: D): Optional<ICommandDescriptor<R>>;
+
+/**
+ * Decorator for service methods that handle a command.
+ *
+ * @param type - command type identifier
+ * @returns decorator function
+ */
+declare function OnCommand(type: TCommandType): MethodDecorator;
+
+/**
+ * Dispatches commands to handlers.
+ *
+ * Unlike queries, command execution always wraps the handler in a promise
+ * and returns a descriptor with task, status, and responder.
+ */
+declare class CommandBus {
+    /**
+     * Internal handler storage.
+     * Uses a stack for each command type to support shadowing.
+     */
+    private readonly handlers;
+    /**
+     * Registers a command handler.
+     * Returns an unregister function.
+     *
+     * @param type - command type
+     * @param handler - handler function
+     * @returns unregister function
+     */
+    register<D = unknown, R = unknown>(type: TCommandType, handler: TCommandHandler<D, R>): TCommandUnregister;
+    /**
+     * 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
+     *
+     * @throws if no handler is registered
+     */
+    command<R = unknown, D = unknown>(type: TCommandType, data?: D): ICommandDescriptor<R>;
+    /**
+     * Dispatches a command to the last registered handler, returning null if no handler exists.
+     *
+     * @param type - command type
+     * @param data - command payload
+     * @returns command descriptor or null if no handler is registered
+     */
+    commandOptional<R = unknown, D = unknown>(type: TCommandType, data?: D): Optional<ICommandDescriptor<R>>;
+    /**
+     * Checks if a handler is registered for the given type.
+     *
+     * @param type - command type
+     * @returns true if handler exists
+     */
+    has(type: TCommandType): boolean;
+    /**
+     * Removes all registered handlers.
+     */
+    clear(): void;
+}
+
+interface ICreateIocContainerOptions {
+    /**
+     * Parent container for inheritance.
+     */
+    readonly parent?: Container;
+    /**
+     * Optional default seed value.
+     */
+    readonly seed?: TAnyObject;
+}
+/**
+ * Creates an IoC container with framework essentials.
+ *
+ * @param options - container configuration
+ * @returns new IoC container
+ */
+declare function createIocContainer(options?: ICreateIocContainerOptions): Container;
+
+/**
+ * Event identifier.
+ */
+type TEventType = string | symbol;
+/**
+ * Event object.
+ */
+interface IEvent<P = unknown, T extends TEventType = TEventType, F = unknown> {
+    readonly type: T;
+    readonly payload?: P;
+    readonly from?: F;
+}
+/**
+ * Event handler signature.
+ */
+type TEventHandler<E extends IEvent = IEvent> = (event: E) => void;
+/**
+ * Unsubscribes from events, part of events subscription lifecycle.
+ */
+type TEventUnsubscriber = () => void;
+/**
+ * Event emitter signature.
+ */
+type TEventEmitter<P = unknown, T extends TEventType = TEventType, F = unknown> = (type: T, payload?: P, from?: F) => void;
+
+/**
+ * Lookup key for service seeds.
+ */
+type TSeedKey = Newable | string | symbol;
+/**
+ * Service-to-seed mapping entry.
+ */
+type TSeedEntry<T = unknown> = readonly [TSeedKey, T];
+/**
+ * Collection of seed entries.
+ */
+type TSeedEntries = ReadonlyArray<TSeedEntry>;
+
+/**
+ * Query identifier. Use symbols for private queries.
+ */
+type TQueryType = string | symbol;
+/**
+ * Query handler signature.
+ */
+type TQueryHandler<D = unknown, R = unknown> = (data: D) => MaybePromise<R>;
+/**
+ * Removes a query handler.
+ */
+type TQueryUnregister = () => void;
+/**
+ * Public query responder signature.
+ */
+type TQueryResponder<R = unknown, D = unknown> = (data?: D) => MaybePromise<R>;
+/**
+ * Dispatches queries and returns their result as a value or promise.
+ */
+type TQueryCaller = <R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D) => MaybePromise<R>;
+/**
+ * Dispatches synchronous queries and returns their result directly.
+ */
+type TSyncQueryCaller = <R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D) => R;
+/**
+ * Dispatches optional queries. Returns null when no handler is registered.
+ */
+type TOptionalQueryCaller = <R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D) => Optional<MaybePromise<R>>;
+/**
+ * Dispatches optional synchronous queries. Returns null when no handler is registered.
+ */
+type TOptionalSyncQueryCaller = <R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D) => Optional<R>;
+
+/**
+ * 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.
+ */
+declare class WireScope {
+    private readonly container;
+    /**
+     * Whether the scope was deactivated and disposed from the container.
+     */
+    readonly isDisposed: boolean;
+    constructor(container: Optional<Container>);
+    /**
+     * Access the IoC container.
+     * Available only for activated instances of scope.
+     *
+     * @returns active container
+     *
+     * @throws WirestateError if scope is not activated or already disposed
+     */
+    getContainer(): Container;
+    /**
+     * Resolves a sibling service or injected value.
+     * Use for lazy resolution or circular dependency breaking.
+     * Available only for activated containers.
+     *
+     * @param injectionId - injection identifier
+     * @returns resolved injection, service instance, or generic value
+     *
+     * @throws WirestateError if scope is not activated
+     */
+    resolve<T>(injectionId: ServiceIdentifier<T>): T;
+    /**
+     * Resolves a sibling service or injected value.
+     * Use for lazy resolution or circular dependency breaking.
+     * Available only for activated containers.
+     *
+     * @param injectionId - injection identifier
+     * @returns resolved injection, service instance, generic value, or null if it is not bound
+     *
+     * @throws WirestateError if scope is not activated
+     */
+    resolveOptional<T>(injectionId: ServiceIdentifier<T>): Optional<T>;
+    /**
+     * Broadcasts an event.
+     * Available only for activated containers.
+     *
+     * @param type - type of event to emit
+     * @param payload - optional payload to send with the event
+     * @param from - optional sender of the event
+     *
+     * @throws WirestateError if scope is not activated
+     */
+    emitEvent<P, T extends TEventType = TEventType>(type: T, payload?: P, from?: unknown): void;
+    /**
+     * Dispatches a query and returns the result.
+     * Available only for activated containers.
+     *
+     * @param type - query type
+     * @param data - query data
+     * @returns query result
+     *
+     * @throws WirestateError if scope is not activated
+     */
+    queryData<R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D): MaybePromise<R>;
+    /**
+     * Dispatches a query and returns the result.
+     * Available only for activated containers.
+     *
+     * @param type - query type
+     * @param data - query data
+     * @returns query result or null if handler is not registered
+     */
+    queryOptionalData<R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D): Optional<MaybePromise<R>>;
+    /**
+     * Dispatches a command and returns the descriptor.
+     * Available only for activated containers.
+     *
+     * @param type - command type
+     * @param data - command data
+     * @returns command descriptor
+     *
+     * @throws WirestateError if scope is not activated
+     */
+    executeCommand<R = unknown, D = unknown, T extends TCommandType = TCommandType>(type: T, data?: D): ICommandDescriptor<R>;
+    /**
+     * Dispatches a command and returns the descriptor.
+     * Available only for activated containers.
+     *
+     * @param type - command type
+     * @param data - command data
+     * @returns command descriptor or null if handler is not registered
+     */
+    executeOptionalCommand<R = unknown, D = unknown, T extends TCommandType = TCommandType>(type: T, data?: D): Optional<ICommandDescriptor<R>>;
+    getSeed<T>(): T;
+    getSeed<T>(seed?: TSeedKey): Optional<T>;
+}
+
+/**
+ * A custom error class that contains generic error information for Wirestate-related issues.
+ *
+ * This class extends the native `Error` class and is used to represent errors specific
+ * to the Wirestate library, providing more structured error handling.
+ */
+declare class WirestateError extends Error {
+    /**
+     * Name or error class to help differentiate error class in minified environments.
+     */
+    readonly name: string;
+    /**
+     * Error code describing the issue.
+     */
+    readonly code: number;
+    /**
+     * Error message describing the issue.
+     */
+    readonly message: string;
+    constructor(code?: number, detail?: string);
+}
+
+/**
+ * Emits events for container from outside scope.
+ *
+ * @param container - inversify container
+ * @param type - event type ot emit
+ * @param payload - event payload
+ * @param from - optional indicator of the event source
+ */
+declare function emitEvent<P, T extends TEventType>(container: Container, type: T, payload?: P, from?: unknown): void;
+
+/**
+ * Decorator for service methods that respond to events.
+ *
+ * @param types - event type(s) to handle. If omitted, handles all events
+ * @returns decorator function
+ */
+declare function OnEvent(types?: TEventType | ReadonlyArray<TEventType>): MethodDecorator;
+
+/**
+ * Dispatches events to subscribers.
+ */
+declare class EventBus {
+    private readonly handlers;
+    /**
+     * Broadcasts an event to all subscribers.
+     *
+     * @param event - event to emit
+     */
+    emit<P = unknown, T extends TEventType = TEventType, F = unknown>(event: IEvent<P, T, F>): void;
+    /**
+     * Subscribes a handler to all events.
+     * Returns an unsubscribe function.
+     *
+     * @param handler - event handler function
+     * @returns unsubscribe function
+     */
+    subscribe(handler: TEventHandler): TEventUnsubscriber;
+    /**
+     * Removes all registered handlers.
+     *
+     * @internal
+     */
+    clear(): void;
+}
+
+/**
+ * Dispatches a query on the provided container.
+ *
+ * @param container - inversify container
+ * @param type - query type
+ * @param data - query data
+ * @returns query result
+ */
+declare function query<R = unknown, D = unknown>(container: Container, type: TQueryType, data?: D): MaybePromise<R>;
+
+/**
+ * Dispatches a query on the provided container, returning null if no handler is registered.
+ *
+ * @param container - inversify container
+ * @param type - query type
+ * @param data - query data
+ * @returns query result or null
+ */
+declare function queryOptional<R = unknown, D = unknown>(container: Container, type: TQueryType, data?: D): Optional<MaybePromise<R>>;
+
+/**
+ * Dispatches queries to handlers.
+ */
+declare class QueryBus {
+    /**
+     * Internal handler storage.
+     * Uses a stack for each query type to support shadowing (e.g., component-level vs service-level).
+     */
+    private readonly handlers;
+    /**
+     * Registers a query handler.
+     * Returns an unregister function.
+     *
+     * @param type - query type
+     * @param handler - handler function
+     * @returns unregister function
+     */
+    register<D = unknown, R = unknown>(type: TQueryType, handler: TQueryHandler<D, R>): TQueryUnregister;
+    /**
+     * Dispatches a query to the last registered handler.
+     *
+     * @param type - query type
+     * @param data - query payload
+     * @returns query result
+     *
+     * @throws if no handler is registered
+     */
+    query<R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D): MaybePromise<R>;
+    /**
+     * Dispatches a query to the last registered handler, returning null if no handler exists.
+     *
+     * @param type - query type
+     * @param data - query payload
+     * @returns query result or null if no handler is registered
+     */
+    queryOptional<R = unknown, D = unknown, T extends TQueryType = TQueryType>(type: T, data?: D): Optional<MaybePromise<R>>;
+    /**
+     * Checks if a handler is registered for the given type.
+     *
+     * @param type - query type
+     * @returns true if handler exists
+     */
+    has(type: TQueryType): boolean;
+    /**
+     * Removes all registered handlers.
+     *
+     * @internal
+     */
+    clear(): void;
+}
+
+/**
+ * Decorator for service methods that respond to a query.
+ *
+ * @param type - query type identifier
+ * @returns decorator function
+ */
+declare function OnQuery(type: TQueryType): MethodDecorator;
+
+/**
+ * Token for the container-scoped seeds map.
+ */
+declare const SEEDS_TOKEN: unique symbol;
+/**
+ * Token for the container-scoped shared seed object.
+ */
+declare const SEED_TOKEN: unique symbol;
+
+/**
+ * Applies seeds to the container into the existing instance instead of replacing it.
+ * This allows multiple providers to co-exist without wiping each other's seeds.
+ *
+ * @param container - target container
+ * @param seeds - targeted seed entries apply
+ */
+declare function applySeeds(container: Container, seeds: TSeedEntries): void;
+
+/**
+ * Applies shared seed to the container.
+ *
+ * @param container - target container
+ * @param seed - shared seed object
+ */
+declare function applySharedSeed(container: Container, seed: TAnyObject): void;
+
+/**
+ * Removes specific seeds from the container.
+ * Used during provider unmounting to clean up only the entries owned by that provider.
+ *
+ * @param container - target container
+ * @param seeds - targeted seeds to remove
+ */
+declare function unapplySeeds(container: Container, seeds: TSeedEntries): void;
+
+/**
+ * Decorator for service methods that run after activation.
+ *
+ * @returns decorator function
+ */
+declare function OnActivated(): MethodDecorator;
+
+/**
+ * Decorator for service methods that run before deactivation.
+ *
+ * @returns decorator function
+ */
+declare function OnDeactivation(): MethodDecorator;
+
+export { CommandBus, ECommandStatus as CommandStatus, EventBus, IInjectableDescriptor as InjectableDescriptor, OnActivated, OnCommand, OnDeactivation, OnEvent, OnQuery, QueryBus, SEED_TOKEN as SEED, SEEDS_TOKEN as SEEDS, WireScope, WirestateError, applySeeds, applySharedSeed, bindConstant, bindEntry, bindService, command, commandOptional, createIocContainer, emitEvent, forwardRef, getEntryToken, query, queryOptional, unapplySeeds };
+export type { TCommandCaller as CommandCaller, ICommandDescriptor as CommandDescriptor, TCommandHandler as CommandHandler, TCommandType as CommandType, TCommandUnregister as CommandUnregister, IEvent as Event, TEventEmitter as EventEmitter, TEventHandler as EventHandler, TEventType as EventType, TEventUnsubscriber as EventUnsubscriber, TOptionalCommandCaller as OptionalCommandCaller, TOptionalQueryCaller as OptionalQueryCaller, TOptionalSyncQueryCaller as OptionalSyncQueryCaller, TQueryCaller as QueryCaller, TQueryHandler as QueryHandler, TQueryResponder as QueryResponder, TQueryType as QueryType, TQueryUnregister as QueryUnregister, TSeedEntries as SeedEntries, TSeedEntry as SeedEntry, TSeedKey as SeedKey, TSyncQueryCaller as SyncQueryCaller };

package/lib.d.ts

@@ -0,0 +1,17 @@
+import { ServiceIdentifier, bindingTypeValues, bindingScopeValues } from 'inversify';
+
+type TBindingType = (typeof bindingTypeValues)[keyof typeof bindingTypeValues];
+type TScopeBindingType = (typeof bindingScopeValues)[keyof typeof bindingScopeValues];
+interface IInjectableDescriptor<T = unknown, V = unknown> {
+    id: ServiceIdentifier<T>;
+    value?: V;
+    bindingType?: TBindingType;
+    scopeBindingType?: TScopeBindingType;
+    /**
+     * Factory function for dynamic value bindings.
+     * Used when type is set to DynamicValue.
+     */
+    factory?: () => T;
+}
+
+export type { IInjectableDescriptor as I };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@wirestate/core",
+  "version": "0.6.0",
+  "description": "Store management library core based on inversify",
+  "sideEffects": false,
+  "author": "Syrotenko Igor",
+  "homepage": "https://github.com/neloreck/wirestate#readme",
+  "license": "MIT",
+  "main": "./cjs/development/index.js",
+  "module": "./esm/development/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": {
+        "production": "./esm/production/index.js",
+        "default": "./esm/development/index.js"
+      },
+      "require": {
+        "production": "./cjs/production/index.js",
+        "default": "./cjs/development/index.js"
+      }
+    },
+    "./test-utils": {
+      "types": "./test-utils.d.ts",
+      "require": {
+        "production": "./cjs/production/test-utils.js",
+        "default": "./cjs/development/test-utils.js"
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neloreck/wirestate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/neloreck/wirestate/issues"
+  },
+  "keywords": [
+    "class-based",
+    "context",
+    "declarative",
+    "management",
+    "manager",
+    "inversify",
+    "ioc",
+    "di",
+    "dependency-injection",
+    "state",
+    "store",
+    "typescript"
+  ],
+  "dependencies": {
+    "inversify": "^8.1.0"
+  },
+  "peerDependencies": {
+    "reflect-metadata": ">=0.2.0",
+    "tslib": ">=2.5.0"
+  },
+  "optionalDependencies": {}
+}