flurryx 0.7.5 → 0.8.0

package/README.md

@@ -29,18 +29,37 @@ interface ProductStoreConfig {
 export const ProductStore = Store.for<ProductStoreConfig>().build();
 
 // Facade
-@SkipIfCached('LIST', (i) => i.store)
-@Loading('LIST', (i) => i.store)
-loadProducts() {
-  this.http.get<Product[]>('/api/products')
-    .pipe(syncToStore(this.store, 'LIST'))
-    .subscribe();
+@Injectable()
+export class ProductFacade {
+  @SkipIfCached("LIST", (i) => i.store)
+  @Loading("LIST", (i) => i.store)
+  loadProducts() {
+    this.http
+      .get<Product[]>("/api/products")
+      .pipe(syncToStore(this.store, "LIST"))
+      .subscribe();
+  }
+
+  // Read signals from the facade
+  getProducts() {
+    return this.store.get("LIST");
+  }
 }
 
-// Component template — just read the signal
-@if (facade.list().isLoading) { <spinner /> }
-@for (product of facade.list().data; track product.id) {
-  <product-card [product]="product" />
+// Component — read the facade signal once, use it in the template
+@Component({
+  selector: "app-product-list",
+  template: `
+    @if (productsState().isLoading) {
+    <spinner />
+    } @for (product of productsState().data; track product.id) {
+    <product-card [product]="product" />
+    }
+  `,
+})
+export class ProductListComponent {
+  private readonly facade = inject(ProductFacade);
+  readonly productsState = this.facade.getProducts();
 }
 ```
 
@@ -67,6 +86,7 @@ No `async` pipe. No `subscribe` in templates. No manual unsubscription.
 - [Keyed Resources](#keyed-resources)
 - [Store Mirroring](#store-mirroring)
   - [Builder .mirror()](#builder-mirror)
+  - [Builder .mirrorSelf()](#builder-mirrorself)
   - [Builder .mirrorKeyed()](#builder-mirrorkeyed)
   - [mirrorKey](#mirrorkey)
   - [collectKeyed](#collectkeyed)
@@ -163,7 +183,7 @@ interface ProductStoreConfig {
 export const ProductStore = Store.for<ProductStoreConfig>().build();
 ```
 
-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.
+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 `Signal<ResourceState<Product[]>>`, and invalid keys or mismatched types are caught at compile time.
 
 ### Step 2 — Create a facade
 
@@ -174,29 +194,33 @@ import { Injectable, inject } from "@angular/core";
 import { HttpClient } from "@angular/common/http";
 import { syncToStore, SkipIfCached, Loading } from "flurryx";
 
-@Injectable({ providedIn: "root" })
+@Injectable()
 export class ProductFacade {
   private readonly http = inject(HttpClient);
   readonly store = inject(ProductStore);
 
-  // Expose signals for templates
-  readonly list = this.store.get('LIST');
-  readonly detail = this.store.get('DETAIL');
+  getProducts() {
+    return this.store.get("LIST");
+  }
+
+  getProductDetail() {
+    return this.store.get("DETAIL");
+  }
 
-  @SkipIfCached('LIST', (i: ProductFacade) => i.store)
-  @Loading('LIST', (i: ProductFacade) => i.store)
+  @SkipIfCached("LIST", (i: ProductFacade) => i.store)
+  @Loading("LIST", (i: ProductFacade) => i.store)
   loadProducts() {
     this.http
       .get<Product[]>("/api/products")
-      .pipe(syncToStore(this.store, 'LIST'))
+      .pipe(syncToStore(this.store, "LIST"))
       .subscribe();
   }
 
-  @Loading('DETAIL', (i: ProductFacade) => i.store)
+  @Loading("DETAIL", (i: ProductFacade) => i.store)
   loadProduct(id: string) {
     this.http
       .get<Product>(`/api/products/${id}`)
-      .pipe(syncToStore(this.store, 'DETAIL'))
+      .pipe(syncToStore(this.store, "DETAIL"))
       .subscribe();
   }
 }
@@ -207,18 +231,19 @@ export class ProductFacade {
 ```typescript
 @Component({
   template: `
-    @if (facade.list().isLoading) {
+    @if (productsState().isLoading) {
     <spinner />
-    } @if (facade.list().status === 'Success') { @for (product of
-    facade.list().data; track product.id) {
+    } @if (productsState().status === 'Success') { @for (product of
+    productsState().data; track product.id) {
     <product-card [product]="product" />
-    } } @if (facade.list().status === 'Error') {
-    <error-banner [errors]="facade.list().errors" />
+    } } @if (productsState().status === 'Error') {
+    <error-banner [errors]="productsState().errors" />
     }
   `,
 })
 export class ProductListComponent {
-  readonly facade = inject(ProductFacade);
+  private readonly facade = inject(ProductFacade);
+  readonly productsState = this.facade.getProducts();
 
   constructor() {
     this.facade.loadProducts();
@@ -261,7 +286,7 @@ A slot starts as `{ data: undefined, isLoading: false, status: undefined, errors
 
 ### Store API
 
-The `Store` builder creates a store backed by `WritableSignal<ResourceState>` per slot. Three creation styles are available:
+The `Store` builder creates a store backed by `Signal<ResourceState>` per slot. Three creation styles are available:
 
 ```typescript
 // 1. Interface-based (recommended) — type-safe with zero boilerplate
@@ -288,7 +313,7 @@ Once injected, the store exposes these methods:
 
 | Method                    | Description                                                                           |
 | ------------------------- | ------------------------------------------------------------------------------------- |
-| `get(key)`                | Returns the `WritableSignal` for a slot                                               |
+| `get(key)`                | Returns the `Signal` for a slot                                               |
 | `update(key, partial)`    | Merges partial state (immutable spread)                                               |
 | `clear(key)`              | Resets a slot to its initial empty state                                              |
 | `clearAll()`              | Resets every slot                                                                     |
@@ -306,6 +331,10 @@ Once injected, the store exposes these methods:
 
 > Update hooks are stored in a `WeakMap` keyed by store instance, so garbage collection works naturally across multiple store lifetimes.
 
+#### Read-only signals
+
+`get(key)` returns a **read-only `Signal`**, not a `WritableSignal`. Consumers can read state but cannot mutate it directly — all writes must go through the store's own methods (`update`, `clear`, `startLoading`, …). This enforces strict encapsulation: the store is the single owner of its state, and external code can only observe it.
+
 ### Store Creation Styles
 
 #### Interface-based: `Store.for<Config>().build()`
@@ -331,7 +360,7 @@ Type safety is fully enforced:
 ```typescript
 const store = inject(ChatStore);
 
-store.get('SESSIONS');                          // WritableSignal<ResourceState<ChatSession[]>>
+store.get('SESSIONS');                          // Signal<ResourceState<ChatSession[]>>
 store.update('SESSIONS', { data: [session] });  // ✅ type-checked
 store.update('SESSIONS', { data: 42 });         // ❌ TS error — number is not ChatSession[]
 store.get('INVALID');                           // ❌ TS error — key does not exist
@@ -692,6 +721,45 @@ export const SessionStore = Store.for<{ ARTICLES: Item[] }>()
 
 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 .mirrorSelf()
+
+Use `.mirrorSelf()` when one slot in a store should mirror another slot in the same store. It is useful for aliases, local snapshots, or secondary slots that should stay in sync with a primary slot without wiring `onUpdate` manually.
+
+```typescript
+interface SessionStoreConfig {
+  CUSTOMER_DETAILS: Customer;
+  CUSTOMER_SNAPSHOT: Customer;
+}
+
+export const SessionStore = Store.for<SessionStoreConfig>()
+  .mirrorSelf('CUSTOMER_DETAILS', 'CUSTOMER_SNAPSHOT')
+  .build();
+```
+
+It mirrors the full resource state one way — `data`, `isLoading`, `status`, and `errors` all flow from the source key to the target key. The target key must be different from the source key.
+
+Because it listens to updates on the built store itself, `.mirrorSelf()` also reacts when the source key is updated by another mirror:
+
+```typescript
+interface CustomerStoreConfig {
+  CUSTOMERS: Customer[];
+}
+
+interface SessionStoreConfig {
+  CUSTOMERS: Customer[];
+  CUSTOMER_COPY: Customer[];
+}
+
+export const CustomerStore = Store.for<CustomerStoreConfig>().build();
+
+export const SessionStore = Store.for<SessionStoreConfig>()
+  .mirror(CustomerStore, 'CUSTOMERS')
+  .mirrorSelf('CUSTOMERS', 'CUSTOMER_COPY')
+  .build();
+```
+
+`.mirrorSelf()` is available on all builder styles. For fluent builders, declare both slots first, then chain `.mirrorSelf(sourceKey, targetKey)` before `.build()`.
+
 ### 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).

package/package.json

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