@wirestate/react 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/react
+# @wirestate/react [[monorepo](https://github.com/Neloreck/wirestate)] [[docs](https://neloreck.github.io/wirestate/)]
 
 [![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)
@@ -13,18 +13,79 @@ npm install @wirestate/core @wirestate/react reflect-metadata
 
 ## Providers
 
-### `IocProvider`
+### `ContainerProvider`
 
 Root provider. Creates the top-level IoC container. Place once near the root of your application.
 
+With globally declared container:
+
 ```tsx
-import { IocProvider } from '@wirestate/react';
+import { createContainer, Container } from "@wirestate/core";
+import { ContainerProvider } from "@wirestate/react";
+import { CounterService, LoggerService } from "./services";
+
+const container: Container = createContainer({
+  entries: [CounterService, LoggerService],
+  activate: [LoggerService],
+});
 
-export function App() {
+export function Application() {
   return (
-    <IocProvider>
+    <ContainerProvider container={container}>
       <SomeComponent />
-    </IocProvider>
+    </ContainerProvider>
+  );
+}
+```
+
+With locally declared container:
+
+```tsx
+import { createContainer, Container } from "@wirestate/core";
+import { ContaierProvider, ContainerActivator, useRootContainer } from "@wirestate/react";
+import { CounterService, LoggerService } from "./services";
+
+export function Application() {
+  const container: Container = useRootContainer(
+    () =>
+      createContainer({
+        entries: [CounterService, LoggerService],
+      }),
+    []
+  );
+
+  return (
+    <ContaierProvider container={container}>
+      <ContainerActivator activate={[LoggerService]}>
+        <SomeComponent />
+      </ContainerActivator>
+    </ContaierProvider>
+  );
+}
+```
+
+### `useRootContainer(factory, deps)`
+
+Creates and memoizes a root container for the component instance.
+The factory runs again only when `deps` change or on dev mode HMR refreshment.
+
+```tsx
+import { Container, createContainer } from "@wirestate/core";
+import { useRootContainer, ContainerProvider } from "@wirestate/react";
+
+function Root() {
+  const container: Container = useRootContainer(
+    () =>
+      createContainer({
+        entries: [CounterService, LoggerService],
+      }),
+    []
+  );
+
+  return (
+    <ContainerProvider container={container}>
+      <SomeComponent />
+    </ContainerProvider>
   );
 }
 ```
@@ -32,11 +93,11 @@ export function App() {
 ### `createInjectablesProvider`
 
 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.
+Services are activated on mount and deactivated on unmount. Expects to be under `ContainerProvider` tree.
 
 ```tsx
-import { createInjectablesProvider } from '@wirestate/react';
-import { CounterService, LoggerService } from './services';
+import { createInjectablesProvider } from "@wirestate/react";
+import { CounterService, LoggerService } from "./services";
 
 const InjectionProvider = createInjectablesProvider([CounterService, LoggerService]);
 
@@ -51,12 +112,31 @@ export function CounterPage() {
 
 **Props:**
 
-| Prop | Type | Description |
-|---|---|---|
-| `seed` | `object` | Shared seed injected into all services via `@Inject(SEED)` |
+| Prop    | Type          | Description                                                 |
+| ------- | ------------- | ----------------------------------------------------------- |
 | `seeds` | `SeedEntries` | Per-service seeds, e.g. `[[CounterService, { count: 10 }]]` |
 
-Both `seed` and `seeds` are applied on first render only.
+`seeds` are applied on first render only.
+
+### `ContainerActivator`
+
+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 (
+    <ContainerActivator activate={[CounterService, LoggerService]}>
+      <CounterView />
+    </ContainerActivator>
+  );
+}
+```
+
+`ContainerActivator` runs activation once per container instance. If the container changes, activation runs again.
 
 ## Injection hooks
 
@@ -65,8 +145,8 @@ Both `seed` and `seeds` are applied on first render only.
 Resolves a value from the nearest container. Re-resolves when the container resets.
 
 ```tsx
-import { useInjection } from '@wirestate/react';
-import { CounterService } from './services';
+import { useInjection } from "@wirestate/react";
+import { CounterService } from "./services";
 
 function CounterView() {
   const counter = useInjection(CounterService);
@@ -87,8 +167,8 @@ Returns a function that emits an event into the current container's event bus.
 ```tsx
 const emit = useEventEmitter();
 
-emit('RESET');
-emit('ADD', { amount: 5 });
+emit("RESET");
+emit("ADD", { amount: 5 });
 ```
 
 ### `useEvent(type, handler)`
@@ -96,7 +176,7 @@ emit('ADD', { amount: 5 });
 Subscribes a handler to a single event type for the lifetime of the component.
 
 ```tsx
-useEvent('RESET', (event) => {
+useEvent("RESET", (event) => {
   console.log(event.type, event.payload);
 });
 ```
@@ -106,7 +186,7 @@ useEvent('RESET', (event) => {
 Subscribes to multiple event types with a single handler.
 
 ```tsx
-useEvents(['RESET', 'CLEAR'], (event) => {
+useEvents(["RESET", "CLEAR"], (event) => {
   console.log(event.type, event.payload);
 });
 ```
@@ -131,7 +211,7 @@ Returns a function that dispatches a command and waits for its result.
 const call = useCommandCaller();
 
 async function handleClick() {
-  await call('LOGIN', { username: 'alice' }).task;
+  await call("LOGIN", { username: "alice" }).task;
 }
 ```
 
@@ -144,7 +224,7 @@ Same as `useCommandCaller` but returns `null` if no handler is registered.
 Registers a command handler from a component for the lifetime of the component.
 
 ```tsx
-useCommandHandler('SCROLL_TOP', () => {
+useCommandHandler("SCROLL_TOP", () => {
   window.scrollTo(0, 0);
 });
 ```
@@ -157,7 +237,7 @@ Returns an async function that calls a query handler and resolves its return val
 
 ```tsx
 const query = useQueryCaller();
-const items = await query('GET_ITEMS');
+const items = await query("GET_ITEMS");
 ```
 
 ### `useSyncQueryCaller()`
@@ -173,7 +253,7 @@ Return `null` when no handler is registered instead of throwing.
 Registers a query handler from a component.
 
 ```tsx
-useQueryHandler('GET_SCROLL_POS', () => window.scrollY);
+useQueryHandler("GET_SCROLL_POS", () => window.scrollY);
 ```
 
 ## Container hooks
@@ -186,13 +266,17 @@ Returns the nearest `Container` instance. Useful for advanced manual resolution.
 
 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 { withIocProvider } from '@wirestate/react/test-utils';
+import { withContainerProvider } from "@wirestate/react/test-utils";
 ```
 
-`withIocProvider(children, container?, seed?)` — wraps a React tree with an `IocProvider` for use in tests.
+`withContainerProvider(children, container?, seed?)` — wraps a React tree with an `ContainerProvider` for use in tests.
 
 ## License