@wirestate/core 0.6.1 → 0.7.0-experimental.1

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 0.7.0
+
+- Add `useScope` in `@wirestate/react`
+- New lit elements modules - `@wirestate/lit` and `@wirestate/lit-signals`
+- `EventBus`: add `unsubscribe` method for explicit handler removal by reference
+- `QueryBus`: add `unregister` method for explicit handler removal by type and reference
+- `CommandBus`: add `unregister` method for explicit handler removal by type and reference
+- `WireScope`: add new event/command/query subscribe-unsubscribe methods
+- Export more alias / methods from `@wirestate/core`
+- Export more alias / methods from `@wirestate/react-mobx`
+- Export missing methods typing for `@wirestate/core`
+- Extensive JSDoc coverage for wirestate packages
+- `createIocContainer`: Added ability to instantly provide and activate entries, targeted seeds
+- `createInjectablesProvider`: Removed.
+- `IocProvider`: Removed
+- `useRootContainer`: Added separate hook for store management in React tree
+- `ContainerProvider`: Simpler provider for containers.
+- `SubContainerProvider`: Added component solving problems of removed `createInjectablesProvider`
+- `ContainerActivator`: Added separate activation component
+
+## 0.6.3
+
+- Update readme files for each module
+
+## 0.6.2
+
+- Corrected build system, react package structure
+
 ## 0.6.1
 
 - React related types moved to react lib
@@ -51,6 +79,6 @@
 - useService -> useInjection
 - AbstractService::getService -> AbstractService::resolve
 
-## 0.1.1
+## 0.1.0
 
 - Initial release

package/README.md

@@ -1,317 +1,271 @@
-# <a href='https://www.npmjs.com/package/wirestate'> ⚡ wirestate </a>
+# @wirestate/core [[monorepo](https://github.com/Neloreck/wirestate)] [[docs](https://neloreck.github.io/wirestate/)]
 
-[![npm version](https://img.shields.io/npm/v/wirestate.svg?style=flat-square)](https://www.npmjs.com/package/wirestate)
-[![language-ts](https://img.shields.io/badge/language-typescript-blue.svg?style=flat)](https://github.com/Neloreck/wirestate/search?l=typescript)
+[![npm](https://img.shields.io/npm/v/@wirestate/core.svg?style=flat-square)](https://www.npmjs.com/package/@wirestate/core)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/Neloreck/wirestate/blob/master/LICENSE)
 
-`wirestate` is a reactivity-independent state management framework for React. It integrates **InversifyJS** for robust Dependency Injection,
-providing IOC/DI/indirection based architecture based on concepts of Services, Events, Commands, and Queries. 
+Core package for wirestate.
+Provides the DI container, service primitives, and event/command/query buses.
+React integration is in [`@wirestate/react`](https://www.npmjs.com/package/@wirestate/react).
 
-It optionally works with **MobX**, **Signals**, or other custom reactivity implementations.
+## Installation
 
-## Architecture & Core Concepts
+```bash
+npm install @wirestate/core reflect-metadata
+```
 
-Designed for complex applications, `wirestate` enforces a clear separation of concerns:
+Import `reflect-metadata` once at your application entry point, before any wirestate imports:
 
-- **Services**: Singleton-scoped logic units that hold state and business logic.
-- **Dependency Injection**: First-class InversifyJS integration for decoupled, testable code.
-- **Reactivity**: Independent state tracking (optional integration with MobX, Signals, etc.).
-- **Events**: Fire-and-forget communication for cross-service side effects.
-- **Commands**: Encapsulated write operations with standardized execution status (pending, settled, error).
-- **Queries**: Synchronous or asynchronous request-response patterns for data retrieval.
-- **Lifecycle Management**: Automated services provision within react tree, activation/deactivation lifecycle. 
+```ts
+import "reflect-metadata";
+```
 
-## Requirements
+## Services
 
-- `react >= 16.8.0`
-- `reflect-metadata` (must be imported at application entry)
+Services are plain classes decorated with `@Injectable`. Each service may inject a `WireScope` which provides access to the event, command, and query buses and to other services in the container.
 
-## Installation
+```ts
+import { Injectable, Inject, WireScope } from "@wirestate/core";
 
-```bash
-npm install --save @wirestate/core reflect-metadata
-```
+@Injectable()
+export class CounterService {
+  public count = 0;
 
-### For react-mobx
+  public constructor(@Inject(WireScope) private scope: WireScope) {}
 
-```bash
-npm install --save @wirestate/react @wirestate/react-mobx mobx mobx-react-lite
+  public increment(): void {
+    this.count++;
+  }
+}
 ```
 
-### For signals
+## Container
 
-```bash
-npm install --save @wirestate/react @wirestate/react-signals @preact/signals-react
-npm install --save-dev @preact/signals-react-transform
-```
+```ts
+import { createIocContainer, bindService } from "@wirestate/core";
 
-## Quick Start with mobx
+const container = createIocContainer({
+  seed: { baseUrl: "https://example.com" },
+  entries: [CounterService],
+});
 
-### 1. Define a Service
+bindService(container, AnotherService);
 
-Services are standard classes decorated with `@Injectable`. Use `WireScope` to interact with the framework.
+const counterService = container.get(CounterService);
+const anotherService = container.get(AnotherService);
+```
 
-```typescript
-import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
-import { makeObservable, Observable, Action } from '@wirestate/react-mobx';
+`bindService` binds a class in singleton scope by default.
+Use `bindConstant` to bind a value, `bindEntry` to bind under a custom token.
 
-@Injectable()
-export class CounterService {
-  @Observable()
-  public count: number = 0;
-
-  public constructor(
-    @Inject(WireScope)
-    private scope: WireScope
-  ) {
-    makeObservable(this);
-  }
+## Events
 
-  @Action()
-  public increment(amount: number = 1): void {
-    this.count += amount;
-  }
+Events are fire-and-forget messages. Any service can emit or subscribe.
 
-  @Action()
-  public reset(): void {
-    this.count = 0;
-  }
+```ts
+import { OnEvent, WireScope, Inject } from "@wirestate/core";
 
-  @OnCommand('INCREMENT')
-  public onIncrementCommand(amount: number = 1): void {
-    this.increment(amount);
-  }
+@Injectable()
+export class SenderService {
+  public constructor(@Inject(WireScope) private scope: WireScope) {}
 
-  @OnQuery('GET_TOTAL')
-  public onGetTotal(): number {
-    return this.count;
+  public notify(): void {
+    this.scope.emitEvent("USER_LOGGED_OUT");
   }
+}
 
-  @OnEvent('RESET')
-  public onResetEvent(): void {
-    this.reset();
+@Injectable()
+export class ReceiverService {
+  @OnEvent("USER_LOGGED_OUT")
+  public onLogout(): void {
+    // handle logout
   }
 }
 ```
 
-### 2. Configure the Provider
+`@OnEvent()` with no argument subscribes to all events.
 
-Bind services at any level of the component tree.
-Lifetimes are managed automatically.
+## Commands
 
-```tsx
-import { IocProvider, createInjectablesProvider } from '@wirestate/react';
-import { CounterService } from './CounterService';
+Commands are write operations dispatched by token. A single handler is expected per command type.
 
-const MainProvider = createInjectablesProvider([CounterService]);
+```ts
+import { OnCommand, WireScope, Inject } from "@wirestate/core";
 
-export function Application() {
-  return (
-    <IocProvider>
-      <MainProvider>
-        <CounterView />
-      </MainProvider>
-    </IocProvider>
-  );
+@Injectable()
+export class AuthService {
+  @OnCommand("LOGIN")
+  public async onLogin(payload: { username: string }): Promise<void> {
+    // perform login
+  }
 }
-```
 
-### 3. Consume in Components
-
-Directly use services and rely on mobx reactivity.
-Or use specialized hooks for communication without direct references.
-
-```tsx
-import { useInjection, useCommandCaller, useEventEmitter } from '@wirestate/react';
-import { observer } from '@wirestate/react-mobx';
-import { CounterService } from './CounterService';
-
-export const CounterView = observer(() => {
-  const service = useInjection(CounterService);
-  const call = useCommandCaller();
-  const emit = useEventEmitter();
-
-  return (
-    <div>
-      <p>Count: {service.count}</p>
-      <button onClick={() => service.increment(5)}>Add 1 (Method)</button>
-      <button onClick={() => call('INCREMENT', 5)}>Add 5 (Command)</button>
-      <button onClick={() => service.reset()}>Reset (Method)</button>
-      <button onClick={() => emit('RESET')}>Reset (Event)</button>
-    </div>
-  );
-});
+@Injectable()
+export class AnotherService {
+  public constructor(@Inject(WireScope) private scope: WireScope) {}
+
+  public async login(): Promise<void> {
+    await this.scope.executeCommand("LOGIN").task;
+  }
+}
 ```
 
-## Quick Start with signals
+Use `commandOptional` when a handler may not be registered — returns `null` instead of throwing.
 
-### 1. Define a Service
+## Queries
 
-Services use `signal` and `computed` for state management.
+Queries are request-response operations. A single handler is expected per query type.
 
-```typescript
-import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
-import { signal, computed, Signal, ReadonlySignal } from '@wirestate/react-signals';
+```ts
+import { OnQuery, WireScope, Inject } from "@wirestate/core";
 
 @Injectable()
-export class CounterService {
-  public readonly count: Signal<number> = signal(0);
-  public readonly isEven: ReadonlySignal<boolean> = computed(() => this.count.value % 2 === 0);
+export class StoreService {
+  private items: Array<string> = [];
 
-  public constructor(
-    @Inject(WireScope)
-    private scope: WireScope
-  ) {}
-
-  public increment(amount: number = 1): void {
-    this.count.value += amount;
-  }
-
-  public reset(): void {
-    this.count.value = 0;
-  }
-
-  @OnCommand('INCREMENT')
-  public onIncrementCommand(amount: number = 1): void {
-    this.increment(amount);
+  @OnQuery("STORE_ITEMS")
+  public onGetItems(): Array<string> {
+    return this.items;
   }
+}
 
-  @OnQuery('GET_TOTAL')
-  public onGetTotal(): number {
-    return this.count.value;
-  }
+@Injectable()
+export class AnotherService {
+  public constructor(@Inject(WireScope) private scope: WireScope) {}
 
-  @OnEvent('RESET')
-  public onResetEvent(): void {
-    this.reset();
+  public async someActionRequiringItems(): Promise<void> {
+    const asyncItems: Array<string> = await this.scope.queryData("STORE_ITEMS");
+    const syncItems: Array<string> = await this.scope.queryData("STORE_ITEMS");
   }
 }
 ```
 
-### 2. Configure the Provider
-
-The provider configuration remains the same regardless of the reactivity implementation.
+## Seeds
 
-```tsx
-import { IocProvider, createInjectablesProvider } from '@wirestate/react';
-import { CounterService } from './CounterService';
+Seeds pass initial data to services when they are activated.
 
-const MainProvider = createInjectablesProvider([CounterService]);
+```ts
+import { SEED, Injectable, Inject } from "@wirestate/core";
 
-export function Application() {
-  return (
-    <IocProvider>
-      <MainProvider>
-        <CounterView />
-      </MainProvider>
-    </IocProvider>
-  );
+// Shared seed — same object injected into all services in the tree:
+@Injectable()
+export class MyService {
+  public constructor(@Inject(SEED) private seed: { theme: string }) {}
 }
-```
 
-### 3. Consume in Components
-
-Access signals directly in components. Reactivity is handled by the signals transform or manual subscription.
-
-```tsx
-import { useInjection, useCommandCaller, useEventEmitter } from '@wirestate/react';
-import { CounterService } from './CounterService';
-
-export function CounterView() {
-  const service = useInjection(CounterService);
-  const call = useCommandCaller();
-  const emit = useEventEmitter();
-
-  return (
-    <div>
-      <p>Count: {service.count}</p>
-      <p>Even: {service.isEven.value ? 'Yes' : 'No'}</p>
-      <button onClick={() => service.increment(5)}>Add 1 (Method)</button>
-      <button onClick={() => call('INCREMENT', 5)}>Add 5 (Command)</button>
-      <button onClick={() => service.reset()}>Reset (Method)</button>
-      <button onClick={() => emit('RESET')}>Reset (Event)</button>
-    </div>
-  );
+// Per-service seed — each service gets its own seed value:
+@Injectable()
+export class OtherService {
+  public constructor(@Inject(WireScope) scope: WireScope) {
+    const { count } = scope.getSeed(OtherService) as { count: number };
+  }
 }
 ```
 
-## Advanced Usage
-
-### Seeding Shared Initial State
+Seeds are applied via `applySeeds` / `applySharedSeed` and removed via `unapplySeeds`.
+In React, pass them as `seed` or `seeds` props to the provider — see `@wirestate/react`.
 
-`wirestate` supports providing initial data (seeds) to services during activation.
+## Lifecycle
 
-```tsx
-const MainProvider = createInjectablesProvider([CounterService]);
-
-<IocProvider>
-  <MainProvider seed={{ initialCount: 100 }}>
-    <CounterView />
-  </MainProvider>
-</IocProvider>
-```
+```ts
+import { OnActivated, OnDeactivation } from "@wirestate/core";
 
-In the service:
+@Injectable()
+export class PollingService {
+  private timer?: ReturnType<typeof setInterval>;
 
-```typescript
-import { Injectable, Inject, SEED } from 'wirestate';
+  @OnActivated()
+  public onActivated(): void {
+    this.timer = setInterval(() => console.info("interval execution"), 5000);
+  }
 
-@Injectable()
-export class CounterService {
-  // ...
-  public constructor(
-    @Inject(SEED) 
-    initialState: { initialCount: number  }
-  ) {
-    this.count = seed.initialCount;
+  @OnDeactivation()
+  public onDeactivation(): void {
+    clearInterval(this.timer);
   }
 }
 ```
 
-### Seeding Bound Initial State
+`@OnActivated` runs after the service is bound and all dependencies are resolved.
+`@OnDeactivation` runs when the container scope is disposed.
+
+## WireScope API
+
+`WireScope` is injected per-service and exposes:
+
+| Method                                    | Description                                                     |
+| ----------------------------------------- | --------------------------------------------------------------- |
+| `getContainer()`                          | Access the raw IoC container                                    |
+| `resolve(token)`                          | Resolve a service or value by token                             |
+| `resolveOptional(token)`                  | Resolve a service or value, returns `null` if not bound         |
+| `getSeed(token?)`                         | Get the per-service or shared seed                              |
+| `emitEvent(type, payload?, from?)`        | Emit an event                                                   |
+| `subscribeToEvent(handler)`               | Subscribe a handler to all events; returns unsubscribe function |
+| `unsubscribeFromEvent(handler)`           | Remove a specific event subscription by handler reference       |
+| `queryData(type, data?)`                  | Dispatch a query and return the result                          |
+| `queryOptionalData(type, data?)`          | Dispatch a query; returns `null` if no handler is registered    |
+| `registerQueryHandler(type, handler)`     | Register a query handler; returns unregister function           |
+| `unregisterQueryHandler(type, handler)`   | Remove a specific query handler by type and reference           |
+| `executeCommand(type, data?)`             | Dispatch a command and return a descriptor                      |
+| `executeOptionalCommand(type, data?)`     | Dispatch a command; returns `null` if no handler is registered  |
+| `registerCommandHandler(type, handler)`   | Register a command handler; returns unregister function         |
+| `unregisterCommandHandler(type, handler)` | Remove a specific command handler by type and reference         |
+
+## Test utilities
+
+Available via `@wirestate/core/test-utils`:
+
+```ts
+import {
+  mockContainer,
+  mockService,
+  mockBindService,
+  mockBindEntry,
+  mockUnbindService,
+} from "@wirestate/core/test-utils";
+```
+
+### `mockContainer(options?)`
 
-`wirestate` supports providing initial data (seeds) to services during activation.
+Creates a configured IoC container for testing. Accepts an optional object:
 
-```tsx
-const MainProvider = createInjectablesProvider([CounterService]);
+| Option          | Type                                     | Description                                   |
+| --------------- | ---------------------------------------- | --------------------------------------------- |
+| `entries`       | `Array<Newable \| InjectableDescriptor>` | Services or descriptors to bind               |
+| `activate`      | `Array<ServiceIdentifier>`               | Tokens to resolve immediately after binding   |
+| `skipLifecycle` | `boolean`                                | Skip `@OnActivated` / `@OnDeactivation` hooks |
 
-<IocProvider>
-  <MainProvider seeds={[[CounterService, { count: 10 }]]}>
-    <CounterView />
-  </MainProvider>
-</IocProvider>
+```ts
+const container = mockContainer({
+  entries: [CounterService, LoggerService],
+  activate: [CounterService],
+});
 ```
 
-In the service:
+### `mockService(ServiceClass, container?, options?)`
 
-```typescript
-import { Injectable, Inject, WireScope } from 'wirestate';
+Binds a service class to a container and returns its instance. Creates a new `mockContainer` if none is provided.
 
-@Injectable()
-export class CounterService {
-  // ...
-  public constructor(@Inject(WireScope) scope: WireScope) {
-    this.count = scope.getSeed(CounterService).count;
-  }
-}
+```ts
+const counter = mockService(CounterService);
+counter.increment();
+expect(counter.count).toBe(1);
 ```
 
-### Service Lifecycle
+### `mockBindService(container, ServiceClass, options?)`
 
-Use decorators to handle initialization and cleanup.
+Binds a service class to an existing container. Accepts `{ skipLifecycle?: boolean }`.
 
-```typescript
-import { OnActivated, OnDeactivation } from 'wirestate';
+### `mockBindEntry(container, entry, options?)`
 
-@OnActivated()
-public onActivated(): void {
-  // Start polling, fetch initial data, etc.
-}
+Binds a service class or `InjectableDescriptor` to an existing container. Accepts `{ skipLifecycle?: boolean }`.
 
-@OnDeactivation()
-public onDeactivation(): void {
-  // Cleanup subscriptions
-}
+### `mockUnbindService(container, ServiceClass)`
+
+Removes a service binding from the container. Useful for overriding registrations between tests.
+
+```ts
+mockUnbindService(container, CounterService);
+mockBindEntry(container, { token: CounterService, useValue: fakeCounter });
 ```
 
 ## License