flurryx 0.7.0 → 0.7.3

package/README.md

@@ -65,6 +65,10 @@ No `async` pipe. No `subscribe` in templates. No manual unsubscription.
   - [Error Normalization](#error-normalization)
   - [Constants](#constants)
 - [Keyed Resources](#keyed-resources)
+- [Store Mirroring](#store-mirroring)
+  - [Builder .mirror()](#builder-mirror)
+  - [mirrorKey](#mirrorkey)
+  - [collectKeyed](#collectkeyed)
 - [Design Decisions](#design-decisions)
 - [Contributing](#contributing)
 - [License](#license)
@@ -592,6 +596,253 @@ import {
 
 ---
 
+## Store Mirroring
+
+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 +  |
++--------------------+                    |                    |
+| Feature Store C    |                    |                    |
+| (CUSTOMER_DETAIL)  |-- collectKeyed --->|                    |
++--------------------+                    +--------------------+
+```
+
+```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
+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.
+
+### 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);
+
+// Different keys
+mirrorKey(customersStore, 'ITEMS', sessionStore, 'ARTICLES');
+
+// Manual cleanup
+const cleanup = mirrorKey(customersStore, 'CUSTOMERS', sessionStore);
+cleanup(); // stop mirroring
+
+// Auto-cleanup with Angular DestroyRef
+mirrorKey(customersStore, 'CUSTOMERS', sessionStore, { destroyRef });
+mirrorKey(customersStore, 'ITEMS', sessionStore, 'ARTICLES', { destroyRef });
+```
+
+**Full example — session store that aggregates feature stores:**
+
+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 SessionStore {
+  private readonly customerStore = inject(CustomerStore);
+  private readonly orderStore = inject(OrderStore);
+  private readonly store = inject(Store.for<SessionStoreConfig>().build());
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly customers = this.store.get('CUSTOMERS');
+  readonly orders = this.store.get('ORDERS');
+
+  constructor() {
+    mirrorKey(this.customerStore, 'CUSTOMERS', this.store, { destroyRef: this.destroyRef });
+    mirrorKey(this.orderStore, 'ORDERS', this.store, { destroyRef: this.destroyRef });
+  }
+}
+```
+
+Everything — loading flags, data, status, errors — is mirrored automatically. No manual `onUpdate` + cleanup boilerplate.
+
+### collectKeyed
+
+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, {
+  extractId: (data) => data?.id,
+  destroyRef,
+});
+
+// Different keys
+collectKeyed(customerStore, 'CUSTOMER_DETAILS', sessionStore, 'CUSTOMER_CACHE', {
+  extractId: (data) => data?.id,
+  destroyRef,
+});
+```
+
+**What it does on each source update:**
+
+| Source state | Action |
+|---|---|
+| `status: 'Success'` + valid ID | Merges entity into target's keyed data |
+| `status: 'Error'` + valid ID | Records per-key error and status |
+| `isLoading: true` + valid ID | Sets per-key loading flag |
+| Data cleared (e.g. `source.clear()`) | Removes previous entity from target |
+
+**Full example — collect individual customer lookups into a cache:**
+
+```typescript
+// Feature store — fetches one customer at a time
+interface CustomerStoreConfig {
+  CUSTOMER_DETAILS: Customer;
+}
+export const CustomerStore = Store.for<CustomerStoreConfig>().build();
+
+// Session store — accumulates all fetched customers
+interface SessionStoreConfig {
+  CUSTOMER_CACHE: KeyedResourceData<string, Customer>;
+}
+
+@Injectable({ providedIn: 'root' })
+export class SessionStore {
+  private readonly customerStore = inject(CustomerStore);
+  private readonly store = inject(Store.for<SessionStoreConfig>().build());
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly customerCache = this.store.get('CUSTOMER_CACHE');
+
+  constructor() {
+    collectKeyed(this.customerStore, 'CUSTOMER_DETAILS', this.store, 'CUSTOMER_CACHE', {
+      extractId: (data) => data?.id,
+      destroyRef: this.destroyRef,
+    });
+  }
+
+  // After loading customers "c1" and "c2", the cache contains:
+  // {
+  //   entities: { c1: Customer, c2: Customer },
+  //   isLoading: { c1: false, c2: false },
+  //   status: { c1: 'Success', c2: 'Success' },
+  //   errors: {}
+  // }
+}
+```
+
+---
+
 ## Design Decisions
 
 **Why signals instead of BehaviorSubject?**

package/dist/index.cjs

@@ -26,10 +26,12 @@ __export(index_exports, {
   Loading: () => import_rx.Loading,
   SkipIfCached: () => import_rx.SkipIfCached,
   Store: () => import_store.Store,
+  collectKeyed: () => import_store.collectKeyed,
   createKeyedResourceData: () => import_core.createKeyedResourceData,
   defaultErrorNormalizer: () => import_rx.defaultErrorNormalizer,
   isAnyKeyLoading: () => import_core.isAnyKeyLoading,
   isKeyedResourceData: () => import_core.isKeyedResourceData,
+  mirrorKey: () => import_store.mirrorKey,
   syncToKeyedStore: () => import_rx.syncToKeyedStore,
   syncToStore: () => import_rx.syncToStore
 });
@@ -45,10 +47,12 @@ var import_rx = require("@flurryx/rx");
   Loading,
   SkipIfCached,
   Store,
+  collectKeyed,
   createKeyedResourceData,
   defaultErrorNormalizer,
   isAnyKeyLoading,
   isKeyedResourceData,
+  mirrorKey,
   syncToKeyedStore,
   syncToStore
 });

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @flurryx/core\nexport type {\n  ResourceState,\n  StoreEnum,\n  KeyedResourceData,\n  KeyedResourceKey,\n  ResourceStatus,\n  ResourceErrors,\n} from \"@flurryx/core\";\nexport {\n  isKeyedResourceData,\n  createKeyedResourceData,\n  isAnyKeyLoading,\n  CACHE_NO_TIMEOUT,\n  DEFAULT_CACHE_TTL_MS,\n} from \"@flurryx/core\";\n\n// @flurryx/store\nexport { BaseStore, Store } from \"@flurryx/store\";\n\n// @flurryx/rx\nexport {\n  syncToStore,\n  syncToKeyedStore,\n  SkipIfCached,\n  Loading,\n  defaultErrorNormalizer,\n} from \"@flurryx/rx\";\nexport type {\n  SyncToStoreOptions,\n  SyncToKeyedStoreOptions,\n  ErrorNormalizer,\n} from \"@flurryx/rx\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,kBAMO;AAGP,mBAAiC;AAGjC,gBAMO;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @flurryx/core\nexport type {\n  ResourceState,\n  StoreEnum,\n  KeyedResourceData,\n  KeyedResourceKey,\n  ResourceStatus,\n  ResourceErrors,\n} from \"@flurryx/core\";\nexport {\n  isKeyedResourceData,\n  createKeyedResourceData,\n  isAnyKeyLoading,\n  CACHE_NO_TIMEOUT,\n  DEFAULT_CACHE_TTL_MS,\n} from \"@flurryx/core\";\n\n// @flurryx/store\nexport { BaseStore, Store, mirrorKey, collectKeyed } from \"@flurryx/store\";\nexport type { MirrorOptions, CollectKeyedOptions } from \"@flurryx/store\";\n\n// @flurryx/rx\nexport {\n  syncToStore,\n  syncToKeyedStore,\n  SkipIfCached,\n  Loading,\n  defaultErrorNormalizer,\n} from \"@flurryx/rx\";\nexport type {\n  SyncToStoreOptions,\n  SyncToKeyedStoreOptions,\n  ErrorNormalizer,\n} from \"@flurryx/rx\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,kBAMO;AAGP,mBAA0D;AAI1D,gBAMO;","names":[]}

package/dist/index.d.cts

@@ -1,3 +1,3 @@
 export { CACHE_NO_TIMEOUT, DEFAULT_CACHE_TTL_MS, KeyedResourceData, KeyedResourceKey, ResourceErrors, ResourceState, ResourceStatus, StoreEnum, createKeyedResourceData, isAnyKeyLoading, isKeyedResourceData } from '@flurryx/core';
-export { BaseStore, Store } from '@flurryx/store';
+export { BaseStore, CollectKeyedOptions, MirrorOptions, Store, collectKeyed, mirrorKey } from '@flurryx/store';
 export { ErrorNormalizer, Loading, SkipIfCached, SyncToKeyedStoreOptions, SyncToStoreOptions, defaultErrorNormalizer, syncToKeyedStore, syncToStore } from '@flurryx/rx';

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { CACHE_NO_TIMEOUT, DEFAULT_CACHE_TTL_MS, KeyedResourceData, KeyedResourceKey, ResourceErrors, ResourceState, ResourceStatus, StoreEnum, createKeyedResourceData, isAnyKeyLoading, isKeyedResourceData } from '@flurryx/core';
-export { BaseStore, Store } from '@flurryx/store';
+export { BaseStore, CollectKeyedOptions, MirrorOptions, Store, collectKeyed, mirrorKey } from '@flurryx/store';
 export { ErrorNormalizer, Loading, SkipIfCached, SyncToKeyedStoreOptions, SyncToStoreOptions, defaultErrorNormalizer, syncToKeyedStore, syncToStore } from '@flurryx/rx';

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   CACHE_NO_TIMEOUT,
   DEFAULT_CACHE_TTL_MS
 } from "@flurryx/core";
-import { BaseStore, Store } from "@flurryx/store";
+import { BaseStore, Store, mirrorKey, collectKeyed } from "@flurryx/store";
 import {
   syncToStore,
   syncToKeyedStore,
@@ -21,10 +21,12 @@ export {
   Loading,
   SkipIfCached,
   Store,
+  collectKeyed,
   createKeyedResourceData,
   defaultErrorNormalizer,
   isAnyKeyLoading,
   isKeyedResourceData,
+  mirrorKey,
   syncToKeyedStore,
   syncToStore
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @flurryx/core\nexport type {\n  ResourceState,\n  StoreEnum,\n  KeyedResourceData,\n  KeyedResourceKey,\n  ResourceStatus,\n  ResourceErrors,\n} from \"@flurryx/core\";\nexport {\n  isKeyedResourceData,\n  createKeyedResourceData,\n  isAnyKeyLoading,\n  CACHE_NO_TIMEOUT,\n  DEFAULT_CACHE_TTL_MS,\n} from \"@flurryx/core\";\n\n// @flurryx/store\nexport { BaseStore, Store } from \"@flurryx/store\";\n\n// @flurryx/rx\nexport {\n  syncToStore,\n  syncToKeyedStore,\n  SkipIfCached,\n  Loading,\n  defaultErrorNormalizer,\n} from \"@flurryx/rx\";\nexport type {\n  SyncToStoreOptions,\n  SyncToKeyedStoreOptions,\n  ErrorNormalizer,\n} from \"@flurryx/rx\";\n"],"mappings":";AASA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP,SAAS,WAAW,aAAa;AAGjC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @flurryx/core\nexport type {\n  ResourceState,\n  StoreEnum,\n  KeyedResourceData,\n  KeyedResourceKey,\n  ResourceStatus,\n  ResourceErrors,\n} from \"@flurryx/core\";\nexport {\n  isKeyedResourceData,\n  createKeyedResourceData,\n  isAnyKeyLoading,\n  CACHE_NO_TIMEOUT,\n  DEFAULT_CACHE_TTL_MS,\n} from \"@flurryx/core\";\n\n// @flurryx/store\nexport { BaseStore, Store, mirrorKey, collectKeyed } from \"@flurryx/store\";\nexport type { MirrorOptions, CollectKeyedOptions } from \"@flurryx/store\";\n\n// @flurryx/rx\nexport {\n  syncToStore,\n  syncToKeyedStore,\n  SkipIfCached,\n  Loading,\n  defaultErrorNormalizer,\n} from \"@flurryx/rx\";\nexport type {\n  SyncToStoreOptions,\n  SyncToKeyedStoreOptions,\n  ErrorNormalizer,\n} from \"@flurryx/rx\";\n"],"mappings":";AASA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP,SAAS,WAAW,OAAO,WAAW,oBAAoB;AAI1D;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}

package/package.json

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