flurryx 0.6.2 → 0.7.1

package/README.md

@@ -65,6 +65,9 @@ No `async` pipe. No `subscribe` in templates. No manual unsubscription.
   - [Error Normalization](#error-normalization)
   - [Constants](#constants)
 - [Keyed Resources](#keyed-resources)
+- [Store Mirroring](#store-mirroring)
+  - [mirrorKey](#mirrorkey)
+  - [collectKeyed](#collectkeyed)
 - [Design Decisions](#design-decisions)
 - [Contributing](#contributing)
 - [License](#license)
@@ -145,11 +148,7 @@ npm install @flurryx/core @flurryx/store @flurryx/rx
 
 ### Step 1 — Define your store
 
-Use the `Store` fluent builder to declare named slots. Each slot holds a `ResourceState<T>`.
-
-**Option A — Interface-based (recommended)**
-
-Define a TypeScript interface mapping keys to data types, pass it as a generic:
+Define a TypeScript interface mapping slot names to their data types, then pass it to the `Store` builder:
 
 ```typescript
 import { Store } from "flurryx";
@@ -162,36 +161,7 @@ interface ProductStoreConfig {
 export const ProductStore = Store.for<ProductStoreConfig>().build();
 ```
 
-No enum, no chaining, no class. The interface is type-only — zero runtime cost. Every call to `store.get('LIST')` returns `WritableSignal<ResourceState<Product[]>>`, and invalid keys or mismatched types are caught at compile time.
-
-**Option B — Fluent chaining**
-
-Declare each slot inline:
-
-```typescript
-export const ProductStore = Store
-  .resource('LIST').as<Product[]>()
-  .resource('DETAIL').as<Product>()
-  .build();
-```
-
-**Option C — Enum-constrained**
-
-Bind the builder to an enum for compile-time key validation:
-
-```typescript
-const ProductStoreEnum = {
-  LIST: 'LIST',
-  DETAIL: 'DETAIL',
-} as const;
-
-export const ProductStore = Store.for(ProductStoreEnum)
-  .resource('LIST').as<Product[]>()
-  .resource('DETAIL').as<Product>()
-  .build();
-```
-
-All three options return an `InjectionToken` with `providedIn: 'root'`.
+That's it. The interface is type-only — zero runtime cost. The builder returns an `InjectionToken` with `providedIn: 'root'`. Every call to `store.get('LIST')` returns `WritableSignal<ResourceState<Product[]>>`, and invalid keys or mismatched types are caught at compile time.
 
 ### Step 2 — Create a facade
 
@@ -625,6 +595,143 @@ 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.
+
+```typescript
+import { mirrorKey, collectKeyed } from "flurryx";
+```
+
+### mirrorKey
+
+Mirrors a resource key from one store to another. When the source updates, the target is updated with the same state.
+
+```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 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();
+
+// Session store — mirrors state from feature stores
+interface SessionStoreConfig {
+  CUSTOMERS: Customer[];
+  ORDERS: Order[];
+}
+export const SessionStore = Store.for<SessionStoreConfig>().build();
+
+@Injectable({ providedIn: 'root' })
+export class SessionFacade {
+  private readonly customerStore = inject(CustomerStore);
+  private readonly orderStore = inject(OrderStore);
+  private readonly sessionStore = inject(SessionStore);
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly customers = this.sessionStore.get('CUSTOMERS');
+  readonly orders = this.sessionStore.get('ORDERS');
+
+  constructor() {
+    mirrorKey(this.customerStore, 'CUSTOMERS', this.sessionStore, { destroyRef: this.destroyRef });
+    mirrorKey(this.orderStore, 'ORDERS', this.sessionStore, { 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.
+
+```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>;
+}
+export const SessionStore = Store.for<SessionStoreConfig>().build();
+
+@Injectable({ providedIn: 'root' })
+export class SessionFacade {
+  private readonly customerStore = inject(CustomerStore);
+  private readonly sessionStore = inject(SessionStore);
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly customerCache = this.sessionStore.get('CUSTOMER_CACHE');
+
+  constructor() {
+    collectKeyed(this.customerStore, 'CUSTOMER_DETAILS', this.sessionStore, '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.6.2",
+  "version": "0.7.1",
   "description": "Signal-first reactive state management for Angular",
   "license": "MIT",
   "type": "module",
@@ -38,9 +38,9 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@flurryx/core": "0.6.2",
-    "@flurryx/store": "0.6.2",
-    "@flurryx/rx": "0.6.2"
+    "@flurryx/core": "0.7.1",
+    "@flurryx/store": "0.7.1",
+    "@flurryx/rx": "0.7.1"
   },
   "peerDependencies": {
     "@angular/core": ">=17.0.0",