flurryx 0.6.1 → 0.7.0

package/README.md

@@ -21,11 +21,12 @@
 flurryx bridges the gap between RxJS async operations and Angular signals. Define a store, pipe your HTTP calls through an operator, read signals in your templates. No actions, no reducers, no effects boilerplate.
 
 ```typescript
-// Store — declare your slots in 3 lines
-export const ProductStore = Store
-  .resource('LIST').as<Product[]>()
-  .resource('DETAIL').as<Product>()
-  .build();
+// Store — declare your slots with a single interface
+interface ProductStoreConfig {
+  LIST: Product[];
+  DETAIL: Product;
+}
+export const ProductStore = Store.for<ProductStoreConfig>().build();
 
 // Facade
 @SkipIfCached('LIST', (i) => i.store)
@@ -56,6 +57,7 @@ No `async` pipe. No `subscribe` in templates. No manual unsubscription.
 - [How to Use](#how-to-use)
   - [ResourceState](#resourcestate)
   - [Store API](#store-api)
+  - [Store Creation Styles](#store-creation-styles)
   - [syncToStore](#synctostore)
   - [syncToKeyedStore](#synctokeyedstore)
   - [@SkipIfCached](#skipifcached)
@@ -143,18 +145,20 @@ 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>`.
+Define a TypeScript interface mapping slot names to their data types, then pass it to the `Store` builder:
 
 ```typescript
 import { Store } from "flurryx";
 
-export const ProductStore = Store
-  .resource('LIST').as<Product[]>()
-  .resource('DETAIL').as<Product>()
-  .build();
+interface ProductStoreConfig {
+  LIST: Product[];
+  DETAIL: Product;
+}
+
+export const ProductStore = Store.for<ProductStoreConfig>().build();
 ```
 
-That's it. No enum, no interface, no class, no constructor. The builder returns 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
 
@@ -252,13 +256,27 @@ 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.
+The `Store` builder creates a store backed by `WritableSignal<ResourceState>` per slot. Three creation styles are available:
 
 ```typescript
+// 1. Interface-based (recommended) — type-safe with zero boilerplate
+interface MyStoreConfig {
+  USERS: User[];
+  SELECTED: User;
+}
+export const MyStore = Store.for<MyStoreConfig>().build();
+
+// 2. Fluent chaining — inline slot definitions
 export const MyStore = Store
   .resource('USERS').as<User[]>()
   .resource('SELECTED').as<User>()
   .build();
+
+// 3. Enum-constrained — validates keys against a runtime enum
+export const MyStore = Store.for(MyStoreEnum)
+  .resource('USERS').as<User[]>()
+  .resource('SELECTED').as<User>()
+  .build();
 ```
 
 Once injected, the store exposes these methods:
@@ -283,6 +301,69 @@ 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.
 
+### Store Creation Styles
+
+#### Interface-based: `Store.for<Config>().build()`
+
+The recommended approach. Define a TypeScript interface where keys are slot names and values are the data types:
+
+```typescript
+import { Store } from "flurryx";
+
+interface ChatStoreConfig {
+  SESSIONS: ChatSession[];
+  CURRENT_SESSION: ChatSession;
+  MESSAGES: ChatMessage[];
+}
+
+export const ChatStore = Store.for<ChatStoreConfig>().build();
+```
+
+The generic argument is type-only — there is no runtime enum or config object. Under the hood, the store lazily creates signals on first access, so un-accessed keys have zero overhead.
+
+Type safety is fully enforced:
+
+```typescript
+const store = inject(ChatStore);
+
+store.get('SESSIONS');                          // WritableSignal<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
+```
+
+#### Fluent chaining: `Store.resource().as<T>().build()`
+
+Define slots inline without a separate interface:
+
+```typescript
+export const ChatStore = Store
+  .resource('SESSIONS').as<ChatSession[]>()
+  .resource('CURRENT_SESSION').as<ChatSession>()
+  .resource('MESSAGES').as<ChatMessage[]>()
+  .build();
+```
+
+#### Enum-constrained: `Store.for(enum).resource().as<T>().build()`
+
+When you have a runtime enum (e.g. shared with backend code), pass it to `.for()` to ensure every key is accounted for:
+
+```typescript
+const ChatStoreEnum = {
+  SESSIONS: 'SESSIONS',
+  CURRENT_SESSION: 'CURRENT_SESSION',
+  MESSAGES: 'MESSAGES',
+} as const;
+
+export const ChatStore = Store.for(ChatStoreEnum)
+  .resource('SESSIONS').as<ChatSession[]>()
+  .resource('CURRENT_SESSION').as<ChatSession>()
+  .resource('MESSAGES').as<ChatMessage[]>()
+  .build();
+```
+
+The builder only allows keys from the enum, and `.build()` is only available once all keys have been defined.
+
 ### syncToStore
 
 RxJS pipeable operator that bridges an `Observable` to a store slot.

package/package.json

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