@wirestate/react 0.6.2 → 0.7.0-experimental.1

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 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
@@ -55,6 +79,6 @@
 - useService -> useInjection
 - AbstractService::getService -> AbstractService::resolve
 
-## 0.1.1
+## 0.1.0
 
 - Initial release

package/README.md

@@ -1,319 +1,283 @@
-# <a href='https://www.npmjs.com/package/wirestate'> ⚡ wirestate </a>
+# @wirestate/react [[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/react.svg?style=flat-square)](https://www.npmjs.com/package/@wirestate/react)
 [![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. 
-
-It optionally works with **MobX**, **Signals**, or other custom reactivity implementations.
-
-## Architecture & Core Concepts
-
-Designed for complex applications, `wirestate` enforces a clear separation of concerns:
-
-- **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. 
-
-## Requirements
-
-- `react >= 16.8.0`
-- `reflect-metadata` (must be imported at application entry)
+React integration for wirestate. Providers and hooks for injecting services and communicating through events, commands, and queries.
 
 ## Installation
 
 ```bash
-npm install --save @wirestate/core reflect-metadata
+npm install @wirestate/core @wirestate/react reflect-metadata
 ```
 
-### For react-mobx
+## Providers
 
-```bash
-npm install --save @wirestate/react @wirestate/react-mobx mobx mobx-react-lite
-```
+### `ContainerProvider`
 
-### For signals
+Root provider. Creates the top-level IoC container. Place once near the root of your application.
 
-```bash
-npm install --save @wirestate/react @wirestate/react-signals @preact/signals-react
-npm install --save-dev @preact/signals-react-transform
-```
+With globally declared container:
 
-## Quick Start with mobx
+```tsx
+import { createContainer, Container } from "@wirestate/core";
+import { ContainerProvider } from "@wirestate/react";
+import { CounterService, LoggerService } from "./services";
 
-### 1. Define a Service
+const container: Container = createContainer({
+  entries: [CounterService, LoggerService],
+  activate: [LoggerService],
+});
 
-Services are standard classes decorated with `@Injectable`. Use `WireScope` to interact with the framework.
+export function Application() {
+  return (
+    <ContainerProvider container={container}>
+      <SomeComponent />
+    </ContainerProvider>
+  );
+}
+```
 
-```typescript
-import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
-import { makeObservable, Observable, Action } from '@wirestate/react-mobx';
+With locally declared container:
 
-@Injectable()
-export class CounterService {
-  @Observable()
-  public count: number = 0;
+```tsx
+import { createContainer, Container } from "@wirestate/core";
+import { ContaierProvider, ContainerActivator, useRootContainer } from "@wirestate/react";
+import { CounterService, LoggerService } from "./services";
 
-  public constructor(
-    @Inject(WireScope)
-    private scope: WireScope
-  ) {
-    makeObservable(this);
-  }
+export function Application() {
+  const container: Container = useRootContainer(
+    () =>
+      createContainer({
+        entries: [CounterService, LoggerService],
+      }),
+    []
+  );
 
-  @Action()
-  public increment(amount: number = 1): void {
-    this.count += amount;
-  }
+  return (
+    <ContaierProvider container={container}>
+      <ContainerActivator activate={[LoggerService]}>
+        <SomeComponent />
+      </ContainerActivator>
+    </ContaierProvider>
+  );
+}
+```
 
-  @Action()
-  public reset(): void {
-    this.count = 0;
-  }
+### `useRootContainer(factory, deps)`
 
-  @OnCommand('INCREMENT')
-  public onIncrementCommand(amount: number = 1): void {
-    this.increment(amount);
-  }
+Creates and memoizes a root container for the component instance.
+The factory runs again only when `deps` change or on dev mode HMR refreshment.
 
-  @OnQuery('GET_TOTAL')
-  public onGetTotal(): number {
-    return this.count;
-  }
+```tsx
+import { Container, createContainer } from "@wirestate/core";
+import { useRootContainer, ContainerProvider } from "@wirestate/react";
+
+function Root() {
+  const container: Container = useRootContainer(
+    () =>
+      createContainer({
+        entries: [CounterService, LoggerService],
+      }),
+    []
+  );
 
-  @OnEvent('RESET')
-  public onResetEvent(): void {
-    this.reset();
-  }
+  return (
+    <ContainerProvider container={container}>
+      <SomeComponent />
+    </ContainerProvider>
+  );
 }
 ```
 
-### 2. Configure the Provider
+### `createInjectablesProvider`
 
-Bind services at any level of the component tree.
-Lifetimes are managed automatically.
+Creates a component that binds a set of services into a child container scoped to the component's lifetime.
+Services are activated on mount and deactivated on unmount. Expects to be under `ContainerProvider` tree.
 
 ```tsx
-import { IocProvider, createInjectablesProvider } from '@wirestate/react';
-import { CounterService } from './CounterService';
+import { createInjectablesProvider } from "@wirestate/react";
+import { CounterService, LoggerService } from "./services";
 
-const MainProvider = createInjectablesProvider([CounterService]);
+const InjectionProvider = createInjectablesProvider([CounterService, LoggerService]);
 
-export function Application() {
+export function CounterPage() {
   return (
-    <IocProvider>
-      <MainProvider>
-        <CounterView />
-      </MainProvider>
-    </IocProvider>
+    <InjectionProvider>
+      <CounterView />
+    </InjectionProvider>
   );
 }
 ```
 
-### 3. Consume in Components
+**Props:**
 
-Directly use services and rely on mobx reactivity.
-Or use specialized hooks for communication without direct references.
+| Prop    | Type          | Description                                                 |
+| ------- | ------------- | ----------------------------------------------------------- |
+| `seeds` | `SeedEntries` | Per-service seeds, e.g. `[[CounterService, { count: 10 }]]` |
 
-```tsx
-import { useInjection, useCommandCaller, useEventEmitter } from '@wirestate/react';
-import { observer } from '@wirestate/react-mobx';
-import { CounterService } from './CounterService';
+`seeds` are applied on first render only.
+
+### `ContainerActivator`
 
-export const CounterView = observer(() => {
-  const service = useInjection(CounterService);
-  const call = useCommandCaller();
-  const emit = useEventEmitter();
+Resolves a list of already bound services from the current container before rendering children.
+Useful when services should be eagerly activated for a subtree.
 
+```tsx
+import { ContainerActivator } from "@wirestate/react";
+import { CounterService, LoggerService } from "./services";
+
+export function CounterPage() {
   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>
+    <ContainerActivator activate={[CounterService, LoggerService]}>
+      <CounterView />
+    </ContainerActivator>
   );
-});
+}
 ```
 
-## Quick Start with signals
+`ContainerActivator` runs activation once per container instance. If the container changes, activation runs again.
+
+## Injection hooks
 
-### 1. Define a Service
+### `useInjection(token)`
 
-Services use `signal` and `computed` for state management.
+Resolves a value from the nearest container. Re-resolves when the container resets.
+
+```tsx
+import { useInjection } from "@wirestate/react";
+import { CounterService } from "./services";
 
-```typescript
-import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
-import { signal, computed, Signal, ReadonlySignal } from '@wirestate/react-signals';
+function CounterView() {
+  const counter = useInjection(CounterService);
+  return <span>{counter.count}</span>;
+}
+```
 
-@Injectable()
-export class CounterService {
-  public readonly count: Signal<number> = signal(0);
-  public readonly isEven: ReadonlySignal<boolean> = computed(() => this.count.value % 2 === 0);
+### `useOptionalInjection(token)`
 
-  public constructor(
-    @Inject(WireScope)
-    private scope: WireScope
-  ) {}
+Same as `useInjection` but returns `null` if the token is not bound.
 
-  public increment(amount: number = 1): void {
-    this.count.value += amount;
-  }
+## Event hooks
 
-  public reset(): void {
-    this.count.value = 0;
-  }
+### `useEventEmitter()`
 
-  @OnCommand('INCREMENT')
-  public onIncrementCommand(amount: number = 1): void {
-    this.increment(amount);
-  }
+Returns a function that emits an event into the current container's event bus.
 
-  @OnQuery('GET_TOTAL')
-  public onGetTotal(): number {
-    return this.count.value;
-  }
+```tsx
+const emit = useEventEmitter();
 
-  @OnEvent('RESET')
-  public onResetEvent(): void {
-    this.reset();
-  }
-}
+emit("RESET");
+emit("ADD", { amount: 5 });
 ```
 
-### 2. Configure the Provider
+### `useEvent(type, handler)`
 
-The provider configuration remains the same regardless of the reactivity implementation.
+Subscribes a handler to a single event type for the lifetime of the component.
 
 ```tsx
-import { IocProvider, createInjectablesProvider } from '@wirestate/react';
-import { CounterService } from './CounterService';
+useEvent("RESET", (event) => {
+  console.log(event.type, event.payload);
+});
+```
 
-const MainProvider = createInjectablesProvider([CounterService]);
+### `useEvents(types, handler)`
 
-export function Application() {
-  return (
-    <IocProvider>
-      <MainProvider>
-        <CounterView />
-      </MainProvider>
-    </IocProvider>
-  );
-}
+Subscribes to multiple event types with a single handler.
+
+```tsx
+useEvents(["RESET", "CLEAR"], (event) => {
+  console.log(event.type, event.payload);
+});
 ```
 
-### 3. Consume in Components
+### `useEventsHandler(handler)`
 
-Access signals directly in components. Reactivity is handled by the signals transform or manual subscription.
+Subscribes to all events. The handler receives the event type and payload.
 
 ```tsx
-import { useInjection, useCommandCaller, useEventEmitter } from '@wirestate/react';
-import { CounterService } from './CounterService';
+useEventsHandler((event) => {
+  logger.log(event.type, event.payload);
+});
+```
 
-export function CounterView() {
-  const service = useInjection(CounterService);
-  const call = useCommandCaller();
-  const emit = useEventEmitter();
+## Command hooks
 
-  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>
-  );
+### `useCommandCaller()`
+
+Returns a function that dispatches a command and waits for its result.
+
+```tsx
+const call = useCommandCaller();
+
+async function handleClick() {
+  await call("LOGIN", { username: "alice" }).task;
 }
 ```
 
-## Advanced Usage
+### `useOptionalCommandCaller()`
 
-### Seeding Shared Initial State
+Same as `useCommandCaller` but returns `null` if no handler is registered.
 
-`wirestate` supports providing initial data (seeds) to services during activation.
+### `useCommandHandler(type, handler)`
 
-```tsx
-const MainProvider = createInjectablesProvider([CounterService]);
+Registers a command handler from a component for the lifetime of the component.
 
-<IocProvider>
-  <MainProvider seed={{ initialCount: 100 }}>
-    <CounterView />
-  </MainProvider>
-</IocProvider>
+```tsx
+useCommandHandler("SCROLL_TOP", () => {
+  window.scrollTo(0, 0);
+});
 ```
 
-In the service:
+## Query hooks
 
-```typescript
-import { Injectable, Inject, SEED } from 'wirestate';
+### `useQueryCaller()`
 
-@Injectable()
-export class CounterService {
-  // ...
-  public constructor(
-    @Inject(SEED) 
-    initialState: { initialCount: number  }
-  ) {
-    this.count = seed.initialCount;
-  }
-}
+Returns an async function that calls a query handler and resolves its return value.
+
+```tsx
+const query = useQueryCaller();
+const items = await query("GET_ITEMS");
 ```
 
-### Seeding Bound Initial State
+### `useSyncQueryCaller()`
 
-`wirestate` supports providing initial data (seeds) to services during activation.
+Same as `useQueryCaller` but calls a synchronous handler.
 
-```tsx
-const MainProvider = createInjectablesProvider([CounterService]);
+### `useOptionalQueryCaller()` / `useOptionalSyncQueryCaller()`
 
-<IocProvider>
-  <MainProvider seeds={[[CounterService, { count: 10 }]]}>
-    <CounterView />
-  </MainProvider>
-</IocProvider>
-```
+Return `null` when no handler is registered instead of throwing.
 
-In the service:
+### `useQueryHandler(type, handler)`
 
-```typescript
-import { Injectable, Inject, WireScope } from 'wirestate';
+Registers a query handler from a component.
 
-@Injectable()
-export class CounterService {
-  // ...
-  public constructor(@Inject(WireScope) scope: WireScope) {
-    this.count = scope.getSeed(CounterService).count;
-  }
-}
+```tsx
+useQueryHandler("GET_SCROLL_POS", () => window.scrollY);
 ```
 
-### Service Lifecycle
+## Container hooks
 
-Use decorators to handle initialization and cleanup.
+### `useContainer()`
 
-```typescript
-import { OnActivated, OnDeactivation } from 'wirestate';
+Returns the nearest `Container` instance. Useful for advanced manual resolution.
 
-@OnActivated()
-public onActivated(): void {
-  // Start polling, fetch initial data, etc.
-}
+### `useContainerRevision()`
 
-@OnDeactivation()
-public onDeactivation(): void {
-  // Cleanup subscriptions
-}
+Returns a counter that increments each time the container is reset. Use to trigger effects when the container changes.
+
+### `useScope()`
+
+Returns the current `WireScope` linked to the nearest container.
+
+## Test utilities
+
+```ts
+import { withContainerProvider } from "@wirestate/react/test-utils";
 ```
 
+`withContainerProvider(children, container?, seed?)` — wraps a React tree with an `ContainerProvider` for use in tests.
+
 ## License
 
 MIT