@virentia/effector 0.2.1 → 0.3.0

package/README.md

@@ -10,53 +10,141 @@ Use this package when Virentia models need to call Effector units, or existing E
 pnpm add @virentia/effector effector @virentia/core
 ```
 
-## Basic usage
+## Associate scopes
 
 ```ts
-import { scope, scoped } from "@virentia/core";
-import { createEffectorCompatibility } from "@virentia/effector";
-import { allSettled, fork } from "effector";
+import { scope } from "@virentia/core";
+import { associate } from "@virentia/effector";
+import { fork } from "effector";
 
-const effector = createEffectorCompatibility();
 const virentiaScope = scope();
 const effectorScope = fork();
 
-const association = effector.associate({
+associate({
   virentia: virentiaScope,
   effector: effectorScope,
 });
 ```
 
-A Virentia scope and an Effector scope are required. The association is only a disposable link between them.
+A Virentia scope and an Effector scope are associated globally through weak maps.
+The examples below use these associated scopes.
 
-## Links
+## Universal Ports
+
+Use `fool(unit)` at feature boundaries. The result is a pass-through unit for one direction: one feature writes to the port, another feature reads from it. Effector features can read or write that port as `clock`, `source`, or `target`; Virentia features can read it as `on` or call it from `run`/`scoped`.
+
+The unit keeps the natural call style of the system it came from. A port created from `event()` is called like a Virentia event. A port created from `createEvent()` is launched like an Effector event.
+
+## Virentia Feature To Effector Feature
 
 ```ts
-effector.link(virentiaSubmitted, effectorSubmitted, ({ id }) => id);
-
-await scoped(virentiaScope, () =>
-  allSettled(effectorSubmitted, {
-    scope: effectorScope,
-    params: "user:1",
-  }),
-);
+import { event, scoped } from "@virentia/core";
+import { fool } from "@virentia/effector";
+import { createEvent, createStore, sample } from "effector";
+
+const checkoutRequested = fool(event<{ orderId: string }>());
+
+function createVirentiaCheckoutFeature() {
+  return {
+    requestCheckout: checkoutRequested,
+  };
+}
+
+function createEffectorBillingFeature() {
+  const $session = createStore({ token: "session-token" });
+  const billingStarted = createEvent<{ orderId: string; token: string }>();
+  const $startedOrders = createStore<string[]>([]).on(billingStarted, (orders, order) => [
+    ...orders,
+    order.orderId,
+  ]);
+
+  sample({
+    clock: checkoutRequested,
+    source: $session,
+    fn: (session, request) => ({
+      orderId: request.orderId,
+      token: session.token,
+    }),
+    target: billingStarted,
+  });
+
+  return {
+    $startedOrders,
+    billingStarted,
+  };
+}
+
+const billing = createEffectorBillingFeature();
+const checkout = createVirentiaCheckoutFeature();
+
+await scoped(virentiaScope, async () => {
+  await checkout.requestCheckout({ orderId: "order:1" });
+});
 ```
 
-The association is only a lifetime handle. Use `scoped`, Effector `allSettled`, `scopeBind`, or UI Providers to choose scopes.
+The Virentia feature owns the command and calls it naturally. The Effector feature consumes that one pass-through port as its `clock`, then keeps its own output and state in `billing`.
 
-## Effector sample
+## Effector Feature To Virentia Feature
 
 ```ts
-import { sample } from "effector";
-
-sample({
-  clock: effectorUserClicked,
-  source: $session,
-  fn: (session, userId) => ({ userId, token: session.token }),
-  target: effector.asEffector(virentiaUserOpened),
+import { event, reaction, store } from "@virentia/core";
+import { fool } from "@virentia/effector";
+import { allSettled, createEvent, sample } from "effector";
+
+const routeOpened = fool(createEvent<string>());
+
+function createEffectorRoutesFeature() {
+  const profileClicked = createEvent<string>();
+
+  sample({
+    clock: profileClicked,
+    target: routeOpened,
+  });
+
+  return {
+    profileClicked,
+  };
+}
+
+function createVirentiaProfileFeature() {
+  const profileLoaded = event<{ userId: string; name: string }>();
+  const loadedCount = store(0);
+
+  reaction({
+    on: routeOpened,
+    run(userId) {
+      profileLoaded({
+        userId,
+        name: "Ada",
+      });
+    },
+  });
+
+  reaction({
+    on: profileLoaded,
+    run() {
+      loadedCount.value += 1;
+    },
+  });
+
+  return {
+    loadedCount,
+  };
+}
+
+const routes = createEffectorRoutesFeature();
+createVirentiaProfileFeature();
+
+await allSettled(routes.profileClicked, {
+  scope: effectorScope,
+  params: "user:1",
 });
 ```
 
+The Effector feature owns navigation and launches its own event naturally. The Virentia feature listens to that universal port with `on`, then calls its own Virentia port from `run`.
+
+Use `scoped`, Effector `allSettled`, `scopeBind`, or UI Providers to choose scopes.
+
 ## Tests
 
 ```sh