@wirestate/react 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+## 0.6.0
+
+- Split wirestate as separate @wirestate packages
+
+## 0.5.0
+
+- Add default initial state param on creation of containers
+- Explicit typing for query callers, export new types
+- For wire-scope add missing optional query/command/resolve methods
+- Add sourcemaps in lib bundles
+- Add `signals` entry for variants of storage usage without mobx
+
+## 0.4.0
+
+- Add `OnActivated` decorator
+- Add `OnDeactivated` decorator
+- `initialState` -> `seed`
+- `type` -> `bindingType`
+- `scopeType` -> `bindingScopeType`
+- Emit events with two params instead of manually composed object, signal `from`
+- Add commands module
+- Add WireScope shared class for managing of wirestate events, queries and commands
+- Remove abstract service in favor of WireScope usage
+- Signals -> events
+- `useOptionalInjection` -> add fallback handler
+
+## 0.3.0
+
+- Rename `createServicesProvider` to `createInjectablesProvider`
+- Add `useSignals`, `useSignalHandler` hooks for better signal handling ergonomics
+- Add `useOptionalInjection` hook for safe resolution of optional dependencies
+- Support optional queries via `queryOptional`, `useOptionalQueryCaller`, and `useOptionalSyncQueryCaller`
+- Support merging of initial states when multiple providers co-exist
+- Add more re-exports from `mobx` and `inversify` for easier consumer usage
+- Improve test coverage, extend test utilities
+- Correctly notify about `IS_DISPOSED` after deactivation of services
+
+## 0.2.0
+
+- Activate and deactivate services in stack ordering
+- Portable libs will not fail with react compiler builds
+- Extend test-utils
+- Increasing test coverage
+- Error handling / custom error class
+- Allow addition of constant bindings in the IOC container
+- useService -> useInjection
+- AbstractService::getService -> AbstractService::resolve
+
+## 0.1.1
+
+- Initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syrotenko Igor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+# <a href='https://www.npmjs.com/package/wirestate'> ⚡ wirestate </a>
+
+[![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)
+[![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)
+
+## Installation
+
+```bash
+npm install --save @wirestate/core reflect-metadata
+```
+
+### For react-mobx
+
+```bash
+npm install --save @wirestate/react @wirestate/react-mobx mobx mobx-react-lite
+```
+
+### For signals
+
+```bash
+npm install --save @wirestate/react @wirestate/react-signals @preact/signals-react
+npm install --save-dev @preact/signals-react-transform
+```
+
+## Quick Start with mobx
+
+### 1. Define a Service
+
+Services are standard classes decorated with `@Injectable`. Use `WireScope` to interact with the framework.
+
+```typescript
+import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
+import { makeObservable, Observable, Action } from '@wirestate/react-mobx';
+
+@Injectable()
+export class CounterService {
+  @Observable()
+  public count: number = 0;
+
+  public constructor(
+    @Inject(WireScope)
+    private scope: WireScope
+  ) {
+    makeObservable(this);
+  }
+
+  @Action()
+  public increment(amount: number = 1): void {
+    this.count += amount;
+  }
+
+  @Action()
+  public reset(): void {
+    this.count = 0;
+  }
+
+  @OnCommand('INCREMENT')
+  public onIncrementCommand(amount: number = 1): void {
+    this.increment(amount);
+  }
+
+  @OnQuery('GET_TOTAL')
+  public onGetTotal(): number {
+    return this.count;
+  }
+
+  @OnEvent('RESET')
+  public onResetEvent(): void {
+    this.reset();
+  }
+}
+```
+
+### 2. Configure the Provider
+
+Bind services at any level of the component tree.
+Lifetimes are managed automatically.
+
+```tsx
+import { IocProvider, createInjectablesProvider } from '@wirestate/react';
+import { CounterService } from './CounterService';
+
+const MainProvider = createInjectablesProvider([CounterService]);
+
+export function Application() {
+  return (
+    <IocProvider>
+      <MainProvider>
+        <CounterView />
+      </MainProvider>
+    </IocProvider>
+  );
+}
+```
+
+### 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>
+  );
+});
+```
+
+## Quick Start with signals
+
+### 1. Define a Service
+
+Services use `signal` and `computed` for state management.
+
+```typescript
+import { Injectable, Inject, WireScope, OnEvent, OnCommand, OnQuery } from '@wirestate/core';
+import { signal, computed, Signal, ReadonlySignal } from '@wirestate/react-signals';
+
+@Injectable()
+export class CounterService {
+  public readonly count: Signal<number> = signal(0);
+  public readonly isEven: ReadonlySignal<boolean> = computed(() => this.count.value % 2 === 0);
+
+  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('GET_TOTAL')
+  public onGetTotal(): number {
+    return this.count.value;
+  }
+
+  @OnEvent('RESET')
+  public onResetEvent(): void {
+    this.reset();
+  }
+}
+```
+
+### 2. Configure the Provider
+
+The provider configuration remains the same regardless of the reactivity implementation.
+
+```tsx
+import { IocProvider, createInjectablesProvider } from '@wirestate/react';
+import { CounterService } from './CounterService';
+
+const MainProvider = createInjectablesProvider([CounterService]);
+
+export function Application() {
+  return (
+    <IocProvider>
+      <MainProvider>
+        <CounterView />
+      </MainProvider>
+    </IocProvider>
+  );
+}
+```
+
+### 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>
+  );
+}
+```
+
+## Advanced Usage
+
+### Seeding Shared Initial State
+
+`wirestate` supports providing initial data (seeds) to services during activation.
+
+```tsx
+const MainProvider = createInjectablesProvider([CounterService]);
+
+<IocProvider>
+  <MainProvider seed={{ initialCount: 100 }}>
+    <CounterView />
+  </MainProvider>
+</IocProvider>
+```
+
+In the service:
+
+```typescript
+import { Injectable, Inject, SEED } from 'wirestate';
+
+@Injectable()
+export class CounterService {
+  // ...
+  public constructor(
+    @Inject(SEED) 
+    initialState: { initialCount: number  }
+  ) {
+    this.count = seed.initialCount;
+  }
+}
+```
+
+### Seeding Bound Initial State
+
+`wirestate` supports providing initial data (seeds) to services during activation.
+
+```tsx
+const MainProvider = createInjectablesProvider([CounterService]);
+
+<IocProvider>
+  <MainProvider seeds={[[CounterService, { count: 10 }]]}>
+    <CounterView />
+  </MainProvider>
+</IocProvider>
+```
+
+In the service:
+
+```typescript
+import { Injectable, Inject, WireScope } from 'wirestate';
+
+@Injectable()
+export class CounterService {
+  // ...
+  public constructor(@Inject(WireScope) scope: WireScope) {
+    this.count = scope.getSeed(CounterService).count;
+  }
+}
+```
+
+### Service Lifecycle
+
+Use decorators to handle initialization and cleanup.
+
+```typescript
+import { OnActivated, OnDeactivation } from 'wirestate';
+
+@OnActivated()
+public onActivated(): void {
+  // Start polling, fetch initial data, etc.
+}
+
+@OnDeactivation()
+public onDeactivation(): void {
+  // Cleanup subscriptions
+}
+```
+
+## License
+
+MIT