flurryx 0.7.1 → 0.7.4

package/README.md

@@ -66,6 +66,8 @@ No `async` pipe. No `subscribe` in templates. No manual unsubscription.
   - [Constants](#constants)
 - [Keyed Resources](#keyed-resources)
 - [Store Mirroring](#store-mirroring)
+  - [Builder .mirror()](#builder-mirror)
+  - [Builder .mirrorKeyed()](#builder-mirrorkeyed)
   - [mirrorKey](#mirrorkey)
   - [collectKeyed](#collectkeyed)
 - [Design Decisions](#design-decisions)
@@ -599,14 +601,190 @@ import {
 
 When building session or aggregation stores that combine state from multiple feature stores, you typically need `onUpdate` listeners, cleanup arrays, and `DestroyRef` wiring. The `mirrorKey` and `collectKeyed` utilities reduce that to a single call.
 
+```
++--------------------+                    +--------------------+
+| Feature Store A    |                    |                    |
+| (CUSTOMERS)        |-- mirrorKey ------>|                    |
++--------------------+                    |                    |
+                                          |  Session Store     |
++--------------------+                    |  (aggregated)      |
+| Feature Store B    |                    |                    |
+| (ORDERS)           |-- mirrorKey ------>|  CUSTOMERS      +  |
++--------------------+                    |  ORDERS         +  |
+                                          |  CUSTOMER_CACHE +  |
++--------------------+                    |  ORDER_CACHE    +  |
+| Feature Store C    |                    |                    |
+| (CUSTOMER_DETAIL)  |-- collectKeyed --->|                    |
++--------------------+                    |                    |
+                                          |                    |
++--------------------+                    |                    |
+| Feature Store D    |                    |                    |
+| (ORDER_DETAIL)     |-- mirrorKeyed --->|                    |
++--------------------+                    +--------------------+
+```
+
+```typescript
+import { Store, mirrorKey, collectKeyed } from "flurryx";
+```
+
+### Builder .mirror()
+
+The simplest way to set up mirroring is directly in the store builder. Chain `.mirror()` to declare which source stores to mirror from — the wiring happens automatically when Angular creates the store.
+
+```typescript
+// Feature stores
+interface CustomerStoreConfig {
+  CUSTOMERS: Customer[];
+}
+export const CustomerStore = Store.for<CustomerStoreConfig>().build();
+
+interface OrderStoreConfig {
+  ORDERS: Order[];
+}
+export const OrderStore = Store.for<OrderStoreConfig>().build();
+```
+
+**Interface-based builder** (recommended):
+
+```typescript
+interface SessionStoreConfig {
+  CUSTOMERS: Customer[];
+  ORDERS: Order[];
+}
+
+export const SessionStore = Store.for<SessionStoreConfig>()
+  .mirror(CustomerStore, 'CUSTOMERS')
+  .mirror(OrderStore, 'ORDERS')
+  .build();
+```
+
+**Fluent chaining:**
+
+```typescript
+export const SessionStore = Store
+  .resource('CUSTOMERS').as<Customer[]>()
+  .resource('ORDERS').as<Order[]>()
+  .mirror(CustomerStore, 'CUSTOMERS')
+  .mirror(OrderStore, 'ORDERS')
+  .build();
+```
+
+**Enum-constrained:**
+
 ```typescript
-import { mirrorKey, collectKeyed } from "flurryx";
+const SessionEnum = { CUSTOMERS: 'CUSTOMERS', ORDERS: 'ORDERS' } as const;
+
+export const SessionStore = Store.for(SessionEnum)
+  .resource('CUSTOMERS').as<Customer[]>()
+  .resource('ORDERS').as<Order[]>()
+  .mirror(CustomerStore, 'CUSTOMERS')
+  .mirror(OrderStore, 'ORDERS')
+  .build();
 ```
 
+**Different source and target keys:**
+
+```typescript
+export const SessionStore = Store.for<{ ARTICLES: Item[] }>()
+  .mirror(ItemStore, 'ITEMS', 'ARTICLES')
+  .build();
+```
+
+The builder calls `inject()` under the hood, so source stores are resolved through Angular's DI. Everything — data, loading, status, errors — is mirrored automatically. No manual cleanup needed; the mirrors live as long as the store.
+
+### Builder .mirrorKeyed()
+
+When the source store holds a single-entity slot (e.g. `CUSTOMER_DETAILS: Customer`) and you want to accumulate those fetches into a `KeyedResourceData` cache on the target, use `.mirrorKeyed()`. It is the builder equivalent of [`collectKeyed`](#collectkeyed).
+
+```typescript
+// Feature store — fetches one customer at a time
+interface CustomerStoreConfig {
+  CUSTOMERS: Customer[];
+  CUSTOMER_DETAILS: Customer;
+}
+export const CustomerStore = Store.for<CustomerStoreConfig>().build();
+```
+
+**Interface-based builder** (recommended):
+
+```typescript
+interface SessionStoreConfig {
+  CUSTOMERS: Customer[];
+  CUSTOMER_CACHE: KeyedResourceData<string, Customer>;
+}
+
+export const SessionStore = Store.for<SessionStoreConfig>()
+  .mirror(CustomerStore, 'CUSTOMERS')
+  .mirrorKeyed(CustomerStore, 'CUSTOMER_DETAILS', {
+    extractId: (data) => data?.id,
+  }, 'CUSTOMER_CACHE')
+  .build();
+```
+
+**Fluent chaining:**
+
+```typescript
+export const SessionStore = Store
+  .resource('CUSTOMERS').as<Customer[]>()
+  .resource('CUSTOMER_CACHE').as<KeyedResourceData<string, Customer>>()
+  .mirror(CustomerStore, 'CUSTOMERS')
+  .mirrorKeyed(CustomerStore, 'CUSTOMER_DETAILS', {
+    extractId: (data) => data?.id,
+  }, 'CUSTOMER_CACHE')
+  .build();
+```
+
+**Enum-constrained:**
+
+```typescript
+const SessionEnum = { CUSTOMERS: 'CUSTOMERS', CUSTOMER_CACHE: 'CUSTOMER_CACHE' } as const;
+
+export const SessionStore = Store.for(SessionEnum)
+  .resource('CUSTOMERS').as<Customer[]>()
+  .resource('CUSTOMER_CACHE').as<KeyedResourceData<string, Customer>>()
+  .mirror(CustomerStore, 'CUSTOMERS')
+  .mirrorKeyed(CustomerStore, 'CUSTOMER_DETAILS', {
+    extractId: (data) => data?.id,
+  }, 'CUSTOMER_CACHE')
+  .build();
+```
+
+**Same source and target key** — when the key names match, the last argument can be omitted:
+
+```typescript
+export const SessionStore = Store.for<{
+  CUSTOMER_DETAILS: KeyedResourceData<string, Customer>;
+}>()
+  .mirrorKeyed(CustomerStore, 'CUSTOMER_DETAILS', {
+    extractId: (data) => data?.id,
+  })
+  .build();
+```
+
+Each entity fetched through the source slot is accumulated by ID into the target's `KeyedResourceData`. Loading, status, and errors are tracked per entity. When the source is cleared, the corresponding entity is removed from the cache.
+
 ### mirrorKey
 
 Mirrors a resource key from one store to another. When the source updates, the target is updated with the same state.
 
+```
++------------------+--------------------------------+------------------+
+| CustomerStore    |          mirrorKey             | SessionStore     |
+|                  |                                |                  |
+| CUSTOMERS -------|--- onUpdate --> update ------->| CUSTOMERS        |
+|                  |   (same key or different)      |                  |
+| { data,          |                                | { data,          |
+|   status,        |                                |   status,        |
+|   isLoading }    |                                |   isLoading }    |
++------------------+--------------------------------+------------------+
+
+source.update('CUSTOMERS', { data: [...], status: 'Success' })
+     |
+     '--> target is automatically updated with the same state
+```
+
+You wire it once. Every future update — data, loading, errors — flows automatically. Call the cleanup function or use `destroyRef` to stop.
+
 ```typescript
 // Same key on both stores (default)
 mirrorKey(customersStore, 'CUSTOMERS', sessionStore);
@@ -623,40 +801,24 @@ mirrorKey(customersStore, 'CUSTOMERS', sessionStore, { destroyRef });
 mirrorKey(customersStore, 'ITEMS', sessionStore, 'ARTICLES', { destroyRef });
 ```
 
-**Full example — session facade that aggregates feature stores:**
-
-```typescript
-// Feature stores
-interface CustomerStoreConfig {
-  CUSTOMERS: Customer[];
-}
-export const CustomerStore = Store.for<CustomerStoreConfig>().build();
-
-interface OrderStoreConfig {
-  ORDERS: Order[];
-}
-export const OrderStore = Store.for<OrderStoreConfig>().build();
+**Full example — session store that aggregates feature stores:**
 
-// Session store — mirrors state from feature stores
-interface SessionStoreConfig {
-  CUSTOMERS: Customer[];
-  ORDERS: Order[];
-}
-export const SessionStore = Store.for<SessionStoreConfig>().build();
+For simple aggregation, prefer the [builder `.mirror()` approach](#builder-mirror). Use `mirrorKey` when you need imperative control — e.g. conditional mirroring, late setup, or `DestroyRef`-based cleanup:
 
+```typescript
 @Injectable({ providedIn: 'root' })
-export class SessionFacade {
+export class SessionStore {
   private readonly customerStore = inject(CustomerStore);
   private readonly orderStore = inject(OrderStore);
-  private readonly sessionStore = inject(SessionStore);
+  private readonly store = inject(Store.for<SessionStoreConfig>().build());
   private readonly destroyRef = inject(DestroyRef);
 
-  readonly customers = this.sessionStore.get('CUSTOMERS');
-  readonly orders = this.sessionStore.get('ORDERS');
+  readonly customers = this.store.get('CUSTOMERS');
+  readonly orders = this.store.get('ORDERS');
 
   constructor() {
-    mirrorKey(this.customerStore, 'CUSTOMERS', this.sessionStore, { destroyRef: this.destroyRef });
-    mirrorKey(this.orderStore, 'ORDERS', this.sessionStore, { destroyRef: this.destroyRef });
+    mirrorKey(this.customerStore, 'CUSTOMERS', this.store, { destroyRef: this.destroyRef });
+    mirrorKey(this.orderStore, 'ORDERS', this.store, { destroyRef: this.destroyRef });
   }
 }
 ```
@@ -667,6 +829,33 @@ Everything — loading flags, data, status, errors — is mirrored automatically
 
 Accumulates single-entity fetches into a `KeyedResourceData` cache on a target store. Each time the source emits a successful entity, it is merged into the target's keyed map by a user-provided `extractId` function.
 
+```
++--------------------+-----------------+--------------------------+
+| CustomerStore      |  collectKeyed   | SessionStore             |
+|                    |                 |                          |
+| CUSTOMER_DETAILS   | extractId(data) | CUSTOMER_CACHE           |
+| (one at a time)    | finds the key   | (KeyedResourceData)      |
++--------+-----------+-----------------+                          |
+         |                             | entities:                |
+         |  fetch("c1") -> Success     |   c1: { id, name }       |
+         |  fetch("c2") -> Success     |   c2: { id, name }       |
+         |  fetch("c3") -> Error       |                          |
+         |                             | isLoading:               |
+         |  clear() -> removes last    |   c1: false              |
+         |              entity         |   c2: false              |
+         |                             |                          |
+         '---- accumulates ----------->| status:                  |
+                                       |   c1: 'Success'          |
+                                       |   c2: 'Success'          |
+                                       |   c3: 'Error'            |
+                                       |                          |
+                                       | errors:                  |
+                                       |   c3: [{ code, msg }]    |
+                                       +--------------------------+
+```
+
+Each entity is tracked independently — its own loading flag, status, and errors. The source store fetches one entity at a time; `collectKeyed` builds up the full cache on the target.
+
 ```typescript
 // Same key on both stores
 collectKeyed(customerStore, 'CUSTOMER_DETAILS', sessionStore, {
@@ -703,18 +892,17 @@ export const CustomerStore = Store.for<CustomerStoreConfig>().build();
 interface SessionStoreConfig {
   CUSTOMER_CACHE: KeyedResourceData<string, Customer>;
 }
-export const SessionStore = Store.for<SessionStoreConfig>().build();
 
 @Injectable({ providedIn: 'root' })
-export class SessionFacade {
+export class SessionStore {
   private readonly customerStore = inject(CustomerStore);
-  private readonly sessionStore = inject(SessionStore);
+  private readonly store = inject(Store.for<SessionStoreConfig>().build());
   private readonly destroyRef = inject(DestroyRef);
 
-  readonly customerCache = this.sessionStore.get('CUSTOMER_CACHE');
+  readonly customerCache = this.store.get('CUSTOMER_CACHE');
 
   constructor() {
-    collectKeyed(this.customerStore, 'CUSTOMER_DETAILS', this.sessionStore, 'CUSTOMER_CACHE', {
+    collectKeyed(this.customerStore, 'CUSTOMER_DETAILS', this.store, 'CUSTOMER_CACHE', {
       extractId: (data) => data?.id,
       destroyRef: this.destroyRef,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flurryx",
-  "version": "0.7.1",
+  "version": "0.7.4",
   "description": "Signal-first reactive state management for Angular",
   "license": "MIT",
   "type": "module",
@@ -38,9 +38,9 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@flurryx/core": "0.7.1",
-    "@flurryx/store": "0.7.1",
-    "@flurryx/rx": "0.7.1"
+    "@flurryx/core": "0.7.4",
+    "@flurryx/store": "0.7.4",
+    "@flurryx/rx": "0.7.4"
   },
   "peerDependencies": {
     "@angular/core": ">=17.0.0",