@wirestate/react 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.6.3
+
+- Update readme files for each module
+
 ## 0.6.2
 
 - Corrected build system, react package structure

package/README.md

@@ -1,319 +1,199 @@
-# <a href='https://www.npmjs.com/package/wirestate'> ⚡ wirestate </a>
+# @wirestate/react
 
-[![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
-
-```bash
-npm install --save @wirestate/react @wirestate/react-mobx mobx mobx-react-lite
-```
+## Providers
 
-### For signals
+### `IocProvider`
 
-```bash
-npm install --save @wirestate/react @wirestate/react-signals @preact/signals-react
-npm install --save-dev @preact/signals-react-transform
-```
+Root provider. Creates the top-level IoC container. Place once near the root of your application.
 
-## Quick Start with mobx
+```tsx
+import { IocProvider } from '@wirestate/react';
 
-### 1. Define a Service
+export function App() {
+  return (
+    <IocProvider>
+      <SomeComponent />
+    </IocProvider>
+  );
+}
+```
 
-Services are standard classes decorated with `@Injectable`. Use `WireScope` to interact with the framework.
+### `createInjectablesProvider`
 
-```typescript
-import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
-import { makeObservable, Observable, Action } from '@wirestate/react-mobx';
+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 `IocProvider` tree.
 
-@Injectable()
-export class CounterService {
-  @Observable()
-  public count: number = 0;
+```tsx
+import { createInjectablesProvider } from '@wirestate/react';
+import { CounterService, LoggerService } from './services';
 
-  public constructor(
-    @Inject(WireScope)
-    private scope: WireScope
-  ) {
-    makeObservable(this);
-  }
+const InjectionProvider = createInjectablesProvider([CounterService, LoggerService]);
 
-  @Action()
-  public increment(amount: number = 1): void {
-    this.count += amount;
-  }
+export function CounterPage() {
+  return (
+    <InjectionProvider>
+      <CounterView />
+    </InjectionProvider>
+  );
+}
+```
 
-  @Action()
-  public reset(): void {
-    this.count = 0;
-  }
+**Props:**
 
-  @OnCommand('INCREMENT')
-  public onIncrementCommand(amount: number = 1): void {
-    this.increment(amount);
-  }
+| Prop | Type | Description |
+|---|---|---|
+| `seed` | `object` | Shared seed injected into all services via `@Inject(SEED)` |
+| `seeds` | `SeedEntries` | Per-service seeds, e.g. `[[CounterService, { count: 10 }]]` |
 
-  @OnQuery('GET_TOTAL')
-  public onGetTotal(): number {
-    return this.count;
-  }
+Both `seed` and `seeds` are applied on first render only.
 
-  @OnEvent('RESET')
-  public onResetEvent(): void {
-    this.reset();
-  }
-}
-```
+## Injection hooks
 
-### 2. Configure the Provider
+### `useInjection(token)`
 
-Bind services at any level of the component tree.
-Lifetimes are managed automatically.
+Resolves a value from the nearest container. Re-resolves when the container resets.
 
 ```tsx
-import { IocProvider, createInjectablesProvider } from '@wirestate/react';
-import { CounterService } from './CounterService';
+import { useInjection } from '@wirestate/react';
+import { CounterService } from './services';
 
-const MainProvider = createInjectablesProvider([CounterService]);
-
-export function Application() {
-  return (
-    <IocProvider>
-      <MainProvider>
-        <CounterView />
-      </MainProvider>
-    </IocProvider>
-  );
+function CounterView() {
+  const counter = useInjection(CounterService);
+  return <span>{counter.count}</span>;
 }
 ```
 
-### 3. Consume in Components
+### `useOptionalInjection(token)`
 
-Directly use services and rely on mobx reactivity.
-Or use specialized hooks for communication without direct references.
+Same as `useInjection` but returns `null` if the token is not bound.
 
-```tsx
-import { useInjection, useCommandCaller, useEventEmitter } from '@wirestate/react';
-import { observer } from '@wirestate/react-mobx';
-import { CounterService } from './CounterService';
+## Event hooks
 
-export const CounterView = observer(() => {
-  const service = useInjection(CounterService);
-  const call = useCommandCaller();
-  const emit = useEventEmitter();
+### `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>
-  );
-});
-```
+Returns a function that emits an event into the current container's event bus.
 
-## Quick Start with signals
+```tsx
+const emit = useEventEmitter();
 
-### 1. Define a Service
+emit('RESET');
+emit('ADD', { amount: 5 });
+```
 
-Services use `signal` and `computed` for state management.
+### `useEvent(type, handler)`
 
-```typescript
-import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
-import { signal, computed, Signal, ReadonlySignal } from '@wirestate/react-signals';
+Subscribes a handler to a single event type for the lifetime of the component.
 
-@Injectable()
-export class CounterService {
-  public readonly count: Signal<number> = signal(0);
-  public readonly isEven: ReadonlySignal<boolean> = computed(() => this.count.value % 2 === 0);
+```tsx
+useEvent('RESET', (event) => {
+  console.log(event.type, event.payload);
+});
+```
 
-  public constructor(
-    @Inject(WireScope)
-    private scope: WireScope
-  ) {}
+### `useEvents(types, handler)`
 
-  public increment(amount: number = 1): void {
-    this.count.value += amount;
-  }
+Subscribes to multiple event types with a single handler.
 
-  public reset(): void {
-    this.count.value = 0;
-  }
+```tsx
+useEvents(['RESET', 'CLEAR'], (event) => {
+  console.log(event.type, event.payload);
+});
+```
 
-  @OnCommand('INCREMENT')
-  public onIncrementCommand(amount: number = 1): void {
-    this.increment(amount);
-  }
+### `useEventsHandler(handler)`
 
-  @OnQuery('GET_TOTAL')
-  public onGetTotal(): number {
-    return this.count.value;
-  }
+Subscribes to all events. The handler receives the event type and payload.
 
-  @OnEvent('RESET')
-  public onResetEvent(): void {
-    this.reset();
-  }
-}
+```tsx
+useEventsHandler((event) => {
+  logger.log(event.type, event.payload);
+});
 ```
 
-### 2. Configure the Provider
+## Command hooks
 
-The provider configuration remains the same regardless of the reactivity implementation.
+### `useCommandCaller()`
 
-```tsx
-import { IocProvider, createInjectablesProvider } from '@wirestate/react';
-import { CounterService } from './CounterService';
+Returns a function that dispatches a command and waits for its result.
 
-const MainProvider = createInjectablesProvider([CounterService]);
+```tsx
+const call = useCommandCaller();
 
-export function Application() {
-  return (
-    <IocProvider>
-      <MainProvider>
-        <CounterView />
-      </MainProvider>
-    </IocProvider>
-  );
+async function handleClick() {
+  await call('LOGIN', { username: 'alice' }).task;
 }
 ```
 
-### 3. Consume in Components
+### `useOptionalCommandCaller()`
 
-Access signals directly in components. Reactivity is handled by the signals transform or manual subscription.
+Same as `useCommandCaller` but returns `null` if no handler is registered.
 
-```tsx
-import { useInjection, useCommandCaller, useEventEmitter } from '@wirestate/react';
-import { CounterService } from './CounterService';
+### `useCommandHandler(type, handler)`
 
-export function CounterView() {
-  const service = useInjection(CounterService);
-  const call = useCommandCaller();
-  const emit = useEventEmitter();
+Registers a command handler from a component for the lifetime of the component.
 
-  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>
-  );
-}
+```tsx
+useCommandHandler('SCROLL_TOP', () => {
+  window.scrollTo(0, 0);
+});
 ```
 
-## Advanced Usage
+## Query hooks
 
-### Seeding Shared Initial State
+### `useQueryCaller()`
 
-`wirestate` supports providing initial data (seeds) to services during activation.
+Returns an async function that calls a query handler and resolves its return value.
 
 ```tsx
-const MainProvider = createInjectablesProvider([CounterService]);
-
-<IocProvider>
-  <MainProvider seed={{ initialCount: 100 }}>
-    <CounterView />
-  </MainProvider>
-</IocProvider>
+const query = useQueryCaller();
+const items = await query('GET_ITEMS');
 ```
 
-In the service:
+### `useSyncQueryCaller()`
 
-```typescript
-import { Injectable, Inject, SEED } from 'wirestate';
+Same as `useQueryCaller` but calls a synchronous handler.
 
-@Injectable()
-export class CounterService {
-  // ...
-  public constructor(
-    @Inject(SEED) 
-    initialState: { initialCount: number  }
-  ) {
-    this.count = seed.initialCount;
-  }
-}
-```
+### `useOptionalQueryCaller()` / `useOptionalSyncQueryCaller()`
 
-### Seeding Bound Initial State
+Return `null` when no handler is registered instead of throwing.
 
-`wirestate` supports providing initial data (seeds) to services during activation.
+### `useQueryHandler(type, handler)`
 
-```tsx
-const MainProvider = createInjectablesProvider([CounterService]);
+Registers a query handler from a component.
 
-<IocProvider>
-  <MainProvider seeds={[[CounterService, { count: 10 }]]}>
-    <CounterView />
-  </MainProvider>
-</IocProvider>
+```tsx
+useQueryHandler('GET_SCROLL_POS', () => window.scrollY);
 ```
 
-In the service:
+## Container hooks
 
-```typescript
-import { Injectable, Inject, WireScope } from 'wirestate';
-
-@Injectable()
-export class CounterService {
-  // ...
-  public constructor(@Inject(WireScope) scope: WireScope) {
-    this.count = scope.getSeed(CounterService).count;
-  }
-}
-```
+### `useContainer()`
 
-### Service Lifecycle
+Returns the nearest `Container` instance. Useful for advanced manual resolution.
 
-Use decorators to handle initialization and cleanup.
+### `useContainerRevision()`
 
-```typescript
-import { OnActivated, OnDeactivation } from 'wirestate';
+Returns a counter that increments each time the container is reset. Use to trigger effects when the container changes.
 
-@OnActivated()
-public onActivated(): void {
-  // Start polling, fetch initial data, etc.
-}
+## Test utilities
 
-@OnDeactivation()
-public onDeactivation(): void {
-  // Cleanup subscriptions
-}
+```ts
+import { withIocProvider } from '@wirestate/react/test-utils';
 ```
 
+`withIocProvider(children, container?, seed?)` — wraps a React tree with an `IocProvider` for use in tests.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirestate/react",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "React alias and adapters for wirestate",
   "sideEffects": false,
   "author": "Syrotenko Igor",