@wirestate/core 0.6.3 → 0.7.0-experimental.2

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## Unreleased
+
+- 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`: Removed in favor of `createContainer`
+- `createContainer`: 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
+- Replace IoC-context provision APIs with `ContainerContext`, `containerProvide`, `ContainerProvider`, and `useContainerProvision`
+- Replace injectables-provider APIs with `subContainerProvide`, `SubContainerProvider`, and `useSubContainerProvider`
+- Provide plain `Container` values through Lit context instead of wrapper objects
+- Recreate managed child containers when the parent container context changes
+- Add `useContainer` and `useScope` consumers in `@wirestate/lit`
+
 ## 0.6.3
 
 - Update readme files for each module
@@ -59,6 +85,6 @@
 - useService -> useInjection
 - AbstractService::getService -> AbstractService::resolve
 
-## 0.1.1
+## 0.1.0
 
 - Initial release

package/README.md

@@ -1,4 +1,4 @@
-# @wirestate/core
+# @wirestate/core [[monorepo](https://github.com/Neloreck/wirestate)] [[docs](https://neloreck.github.io/wirestate/)]
 
 [![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)
@@ -16,7 +16,7 @@ npm install @wirestate/core reflect-metadata
 Import `reflect-metadata` once at your application entry point, before any wirestate imports:
 
 ```ts
-import 'reflect-metadata';
+import "reflect-metadata";
 ```
 
 ## Services
@@ -24,15 +24,13 @@ import 'reflect-metadata';
 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.
 
 ```ts
-import { Injectable, Inject, WireScope } from '@wirestate/core';
+import { Injectable, Inject, WireScope } from "@wirestate/core";
 
 @Injectable()
 export class CounterService {
   public count = 0;
 
-  public constructor(
-    @Inject(WireScope) private scope: WireScope
-  ) {}
+  public constructor(@Inject(WireScope) private scope: WireScope) {}
 
   public increment(): void {
     this.count++;
@@ -43,13 +41,17 @@ export class CounterService {
 ## Container
 
 ```ts
-import { createIocContainer, bindService } from '@wirestate/core';
+import { createContainer, bindService } from "@wirestate/core";
 
-const container = createIocContainer();
+const container = createContainer({
+  seed: { baseUrl: "https://example.com" },
+  entries: [CounterService],
+});
 
-bindService(container, CounterService);
+bindService(container, AnotherService);
 
-const service = container.get(CounterService);
+const counterService = container.get(CounterService);
+const anotherService = container.get(AnotherService);
 ```
 
 `bindService` binds a class in singleton scope by default.
@@ -60,20 +62,20 @@ Use `bindConstant` to bind a value, `bindEntry` to bind under a custom token.
 Events are fire-and-forget messages. Any service can emit or subscribe.
 
 ```ts
-import { OnEvent, WireScope, Inject } from '@wirestate/core';
+import { OnEvent, WireScope, Inject } from "@wirestate/core";
 
 @Injectable()
 export class SenderService {
   public constructor(@Inject(WireScope) private scope: WireScope) {}
 
   public notify(): void {
-    this.scope.emitEvent('USER_LOGGED_OUT');
+    this.scope.emitEvent("USER_LOGGED_OUT");
   }
 }
 
 @Injectable()
 export class ReceiverService {
-  @OnEvent('USER_LOGGED_OUT')
+  @OnEvent("USER_LOGGED_OUT")
   public onLogout(): void {
     // handle logout
   }
@@ -87,11 +89,11 @@ export class ReceiverService {
 Commands are write operations dispatched by token. A single handler is expected per command type.
 
 ```ts
-import { OnCommand, WireScope, Inject } from '@wirestate/core';
+import { OnCommand, WireScope, Inject } from "@wirestate/core";
 
 @Injectable()
 export class AuthService {
-  @OnCommand('LOGIN')
+  @OnCommand("LOGIN")
   public async onLogin(payload: { username: string }): Promise<void> {
     // perform login
   }
@@ -102,7 +104,7 @@ export class AnotherService {
   public constructor(@Inject(WireScope) private scope: WireScope) {}
 
   public async login(): Promise<void> {
-    await this.scope.executeCommand('LOGIN').task;
+    await this.scope.executeCommand("LOGIN").task;
   }
 }
 ```
@@ -114,13 +116,13 @@ Use `commandOptional` when a handler may not be registered — returns `null` in
 Queries are request-response operations. A single handler is expected per query type.
 
 ```ts
-import { OnQuery, WireScope, Inject } from '@wirestate/core';
+import { OnQuery, WireScope, Inject } from "@wirestate/core";
 
 @Injectable()
 export class StoreService {
   private items: Array<string> = [];
 
-  @OnQuery('STORE_ITEMS')
+  @OnQuery("STORE_ITEMS")
   public onGetItems(): Array<string> {
     return this.items;
   }
@@ -131,8 +133,8 @@ export class AnotherService {
   public constructor(@Inject(WireScope) private scope: WireScope) {}
 
   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');
+    const asyncItems: Array<string> = await this.scope.queryData("STORE_ITEMS");
+    const syncItems: Array<string> = await this.scope.queryData("STORE_ITEMS");
   }
 }
 ```
@@ -142,7 +144,7 @@ export class AnotherService {
 Seeds pass initial data to services when they are activated.
 
 ```ts
-import { SEED, Injectable, Inject } from '@wirestate/core';
+import { SEED, Injectable, Inject } from "@wirestate/core";
 
 // Shared seed — same object injected into all services in the tree:
 @Injectable()
@@ -165,7 +167,7 @@ In React, pass them as `seed` or `seeds` props to the provider — see `@wiresta
 ## Lifecycle
 
 ```ts
-import { OnActivated, OnDeactivation } from '@wirestate/core';
+import { OnActivated, OnDeactivation } from "@wirestate/core";
 
 @Injectable()
 export class PollingService {
@@ -173,7 +175,7 @@ export class PollingService {
 
   @OnActivated()
   public onActivated(): void {
-    this.timer = setInterval(() => console.info('interval execution'), 5000);
+    this.timer = setInterval(() => console.info("interval execution"), 5000);
   }
 
   @OnDeactivation()
@@ -190,14 +192,23 @@ export class PollingService {
 
 `WireScope` is injected per-service and exposes:
 
-| Method | Description |
-|---|---|
-| `getContainer()` | Access the raw IoC container |
-| `resolve(token)` | Resolve a service or value by token |
-| `getSeed(token)` | Get the per-service seed for a given token |
-| `emitEvent(type, payload?)` | Emit an event |
-| `command(type)` | Get a caller for a command |
-| `query(type)` | Get a caller for a query |
+| 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
 
@@ -210,18 +221,18 @@ import {
   mockBindService,
   mockBindEntry,
   mockUnbindService,
-} from '@wirestate/core/test-utils';
+} from "@wirestate/core/test-utils";
 ```
 
 ### `mockContainer(options?)`
 
 Creates a configured IoC container for testing. Accepts an optional object:
 
-| 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 |
+| 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 |
 
 ```ts
 const container = mockContainer({