@flurryx/store 0.7.3 → 0.7.5

package/README.md

@@ -0,0 +1,141 @@
+# @flurryx/store
+
+Signal-based reactive store for Angular. Part of the [flurryx](../../README.md) monorepo.
+
+## Installation
+
+```bash
+npm install @flurryx/store
+```
+
+Or use the umbrella package which re-exports everything:
+
+```bash
+npm install flurryx
+```
+
+## Store Creation
+
+Three builder styles are available:
+
+```typescript
+import { Store } from "@flurryx/store";
+
+// 1. Interface-based (recommended)
+interface MyStoreConfig {
+  USERS: User[];
+  SELECTED: User;
+}
+export const MyStore = Store.for<MyStoreConfig>().build();
+
+// 2. Fluent chaining
+export const MyStore = Store
+  .resource('USERS').as<User[]>()
+  .resource('SELECTED').as<User>()
+  .build();
+
+// 3. Enum-constrained
+const Enum = { USERS: 'USERS', SELECTED: 'SELECTED' } as const;
+export const MyStore = Store.for(Enum)
+  .resource('USERS').as<User[]>()
+  .resource('SELECTED').as<User>()
+  .build();
+```
+
+## Store API
+
+### Basic operations
+
+| Method | Description |
+|---|---|
+| `get(key)` | Returns the `WritableSignal` 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 |
+| `startLoading(key)` | Sets `isLoading: true`, clears `status` and `errors` |
+| `stopLoading(key)` | Sets `isLoading: false`, clears `status` and `errors` |
+| `onUpdate(key, callback)` | Registers a listener fired after `update` or `clear`. Returns an unsubscribe function |
+
+### Keyed operations
+
+For slots holding `KeyedResourceData<TKey, TValue>`:
+
+| Method | Description |
+|---|---|
+| `updateKeyedOne(key, resourceKey, entity)` | Merges one entity into a keyed slot |
+| `clearKeyedOne(key, resourceKey)` | Removes one entity from a keyed slot |
+| `startKeyedLoading(key, resourceKey)` | Sets loading for a single resource key |
+
+## Clearing Store Data
+
+### Whole-slot clearing
+
+Reset an entire store slot back to its initial empty state:
+
+```typescript
+const store = inject(ProductStore);
+
+// Clear a single slot
+store.clear('LIST');
+
+// Clear every slot in the store
+store.clearAll();
+```
+
+### Per-key clearing for keyed resources
+
+When a slot holds a `KeyedResourceData`, `clear('ITEMS')` wipes **every** cached entity. To invalidate a single entry, use `clearKeyedOne`:
+
+```typescript
+import { Store } from "@flurryx/store";
+import type { KeyedResourceData } from "@flurryx/core";
+
+// Define a store with a keyed slot
+interface InvoiceStoreConfig {
+  ITEMS: KeyedResourceData<string, Invoice>;
+}
+export const InvoiceStore = Store.for<InvoiceStoreConfig>().build();
+```
+
+```typescript
+const store = inject(InvoiceStore);
+
+// Remove only invoice "inv-42" from the cache.
+// All other cached invoices remain untouched.
+store.clearKeyedOne('ITEMS', 'inv-42');
+```
+
+`clearKeyedOne` removes the entity, its loading flag, status, and errors for that key, then recalculates the top-level `isLoading` based on remaining keys.
+
+**Facade example:**
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class InvoiceFacade {
+  private readonly http = inject(HttpClient);
+  readonly store = inject(InvoiceStore);
+
+  deleteInvoice(id: string) {
+    this.http.delete(`/api/invoices/${id}`).subscribe(() => {
+      // Evict only this invoice from the keyed cache
+      this.store.clearKeyedOne('ITEMS', id);
+    });
+  }
+}
+```
+
+**Comparison:**
+
+| Method | Scope | Use when |
+|---|---|---|
+| `clear(key)` | Entire slot | Logging out, resetting a form, full refresh |
+| `clearAll()` | Every slot | Session teardown |
+| `clearKeyedOne(key, resourceKey)` | Single entity in a keyed slot | Deleting or invalidating one cached item |
+
+## Store Mirroring
+
+The store builder supports `.mirror()` and `.mirrorKeyed()` for declarative cross-store synchronization. See the [root README](../../README.md#store-mirroring) for full documentation.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.cjs

@@ -273,6 +273,7 @@ var BaseStore = class {
 
 // src/lazy-store.ts
 var import_core3 = require("@angular/core");
+var import_core4 = require("@flurryx/core");
 function createDefaultState() {
   return {
     data: void 0,
@@ -336,6 +337,96 @@ var LazyStore = class {
       })
     );
   }
+  updateKeyedOne(key, resourceKey, entity) {
+    const sig = this.getOrCreate(key);
+    const state = sig();
+    const data = (0, import_core4.isKeyedResourceData)(state.data) ? state.data : (0, import_core4.createKeyedResourceData)();
+    const nextErrors = { ...data.errors };
+    delete nextErrors[resourceKey];
+    const nextData = {
+      ...data,
+      entities: { ...data.entities, [resourceKey]: entity },
+      isLoading: { ...data.isLoading, [resourceKey]: false },
+      status: { ...data.status, [resourceKey]: "Success" },
+      errors: nextErrors
+    };
+    this.update(key, {
+      data: nextData,
+      isLoading: (0, import_core4.isAnyKeyLoading)(nextData.isLoading),
+      status: void 0,
+      errors: void 0
+    });
+  }
+  clearKeyedOne(key, resourceKey) {
+    const sig = this.getOrCreate(key);
+    const state = sig();
+    if (!(0, import_core4.isKeyedResourceData)(state.data)) {
+      return;
+    }
+    const data = state.data;
+    const previousState = state;
+    const nextEntities = { ...data.entities };
+    delete nextEntities[resourceKey];
+    const nextIsLoading = { ...data.isLoading };
+    delete nextIsLoading[resourceKey];
+    const nextStatus = { ...data.status };
+    delete nextStatus[resourceKey];
+    const nextErrors = { ...data.errors };
+    delete nextErrors[resourceKey];
+    const nextData = {
+      ...data,
+      entities: nextEntities,
+      isLoading: nextIsLoading,
+      status: nextStatus,
+      errors: nextErrors
+    };
+    sig.update(
+      (prev) => ({
+        ...prev,
+        data: nextData,
+        status: void 0,
+        isLoading: (0, import_core4.isAnyKeyLoading)(nextIsLoading),
+        errors: void 0
+      })
+    );
+    const updatedState = sig();
+    this.notifyHooks(key, updatedState, previousState);
+  }
+  startKeyedLoading(key, resourceKey) {
+    const sig = this.getOrCreate(key);
+    const state = sig();
+    if (!(0, import_core4.isKeyedResourceData)(state.data)) {
+      this.startLoading(key);
+      return;
+    }
+    const previousState = state;
+    const data = state.data;
+    const nextIsLoading = {
+      ...data.isLoading,
+      [resourceKey]: true
+    };
+    const nextStatus = { ...data.status };
+    delete nextStatus[resourceKey];
+    const nextErrors = { ...data.errors };
+    delete nextErrors[resourceKey];
+    const nextData = {
+      ...data,
+      isLoading: nextIsLoading,
+      status: nextStatus,
+      errors: nextErrors
+    };
+    sig.update(
+      (previous) => ({
+        ...previous,
+        data: nextData,
+        status: void 0,
+        isLoading: (0, import_core4.isAnyKeyLoading)(nextIsLoading),
+        errors: void 0
+      })
+    );
+    const updatedState = sig();
+    this.notifyHooks(key, updatedState, previousState);
+  }
   onUpdate(key, callback) {
     if (!this.hooks.has(key)) {
       this.hooks.set(key, []);
@@ -368,7 +459,7 @@ var LazyStore = class {
 };
 
 // src/store-builder.ts
-var import_core4 = require("@angular/core");
+var import_core6 = require("@angular/core");
 
 // src/dynamic-store.ts
 var DynamicStore = class extends BaseStore {
@@ -397,108 +488,6 @@ function mirrorKey(source, sourceKey, target, targetKeyOrOptions, options) {
   return cleanup;
 }
 
-// src/resource.ts
-function resource() {
-  return {};
-}
-
-// src/store-builder.ts
-function wireMirrors(store, mirrors) {
-  for (const def of mirrors) {
-    const sourceStore = (0, import_core4.inject)(def.sourceToken);
-    mirrorKey(sourceStore, def.sourceKey, store, def.targetKey);
-  }
-  return store;
-}
-function createBuilder(accum, mirrors = []) {
-  return {
-    resource(key) {
-      return {
-        as() {
-          const nextAccum = {
-            ...accum,
-            [key]: resource()
-          };
-          return createBuilder(nextAccum, mirrors);
-        }
-      };
-    },
-    mirror(source, sourceKey, targetKey) {
-      const def = {
-        sourceToken: source,
-        sourceKey,
-        targetKey: targetKey ?? sourceKey
-      };
-      return createBuilder(accum, [...mirrors, def]);
-    },
-    build() {
-      return new import_core4.InjectionToken("FlurryxStore", {
-        providedIn: "root",
-        factory: () => wireMirrors(new DynamicStore(accum), mirrors)
-      });
-    }
-  };
-}
-function createConstrainedBuilder(_enumObj, accum, mirrors = []) {
-  return {
-    resource(key) {
-      return {
-        as() {
-          const nextAccum = {
-            ...accum,
-            [key]: resource()
-          };
-          return createConstrainedBuilder(_enumObj, nextAccum, mirrors);
-        }
-      };
-    },
-    mirror(source, sourceKey, targetKey) {
-      const def = {
-        sourceToken: source,
-        sourceKey,
-        targetKey: targetKey ?? sourceKey
-      };
-      return createConstrainedBuilder(_enumObj, accum, [...mirrors, def]);
-    },
-    build() {
-      return new import_core4.InjectionToken("FlurryxStore", {
-        providedIn: "root",
-        factory: () => wireMirrors(new DynamicStore(accum), mirrors)
-      });
-    }
-  };
-}
-function createInterfaceBuilder(mirrors = []) {
-  return {
-    mirror(source, sourceKey, targetKey) {
-      const def = {
-        sourceToken: source,
-        sourceKey,
-        targetKey: targetKey ?? sourceKey
-      };
-      return createInterfaceBuilder([...mirrors, def]);
-    },
-    build() {
-      return new import_core4.InjectionToken("FlurryxStore", {
-        providedIn: "root",
-        factory: () => wireMirrors(
-          new LazyStore(),
-          mirrors
-        )
-      });
-    }
-  };
-}
-var Store = {
-  ...createBuilder({}),
-  for(enumObj) {
-    if (arguments.length === 0) {
-      return createInterfaceBuilder();
-    }
-    return createConstrainedBuilder(enumObj, {});
-  }
-};
-
 // src/collect-keyed.ts
 var import_core5 = require("@flurryx/core");
 function collectKeyed(source, sourceKey, target, targetKeyOrOptions, options) {
@@ -585,6 +574,175 @@ function collectKeyed(source, sourceKey, target, targetKeyOrOptions, options) {
   }
   return cleanup;
 }
+
+// src/resource.ts
+function resource() {
+  return {};
+}
+
+// src/store-builder.ts
+function wireMirrors(store, mirrors) {
+  for (const def of mirrors) {
+    const sourceStore = (0, import_core6.inject)(def.sourceToken);
+    mirrorKey(sourceStore, def.sourceKey, store, def.targetKey);
+  }
+  return store;
+}
+function wireMirrorKeyed(store, defs) {
+  for (const def of defs) {
+    const sourceStore = (0, import_core6.inject)(def.sourceToken);
+    collectKeyed(sourceStore, def.sourceKey, store, def.targetKey, {
+      extractId: def.extractId
+    });
+  }
+  return store;
+}
+function createBuilder(accum, mirrors = [], mirrorKeyedDefs = []) {
+  return {
+    resource(key) {
+      return {
+        as() {
+          const nextAccum = {
+            ...accum,
+            [key]: resource()
+          };
+          return createBuilder(nextAccum, mirrors, mirrorKeyedDefs);
+        }
+      };
+    },
+    mirror(source, sourceKey, targetKey) {
+      const def = {
+        sourceToken: source,
+        sourceKey,
+        targetKey: targetKey ?? sourceKey
+      };
+      return createBuilder(accum, [...mirrors, def], mirrorKeyedDefs);
+    },
+    mirrorKeyed(source, sourceKey, options, targetKey) {
+      const def = {
+        sourceToken: source,
+        sourceKey,
+        targetKey: targetKey ?? sourceKey,
+        extractId: options.extractId
+      };
+      return createBuilder(accum, mirrors, [...mirrorKeyedDefs, def]);
+    },
+    build() {
+      return new import_core6.InjectionToken("FlurryxStore", {
+        providedIn: "root",
+        factory: () => {
+          const store = new DynamicStore(accum);
+          wireMirrors(store, mirrors);
+          wireMirrorKeyed(store, mirrorKeyedDefs);
+          return store;
+        }
+      });
+    }
+  };
+}
+function createConstrainedBuilder(_enumObj, accum, mirrors = [], mirrorKeyedDefs = []) {
+  return {
+    resource(key) {
+      return {
+        as() {
+          const nextAccum = {
+            ...accum,
+            [key]: resource()
+          };
+          return createConstrainedBuilder(
+            _enumObj,
+            nextAccum,
+            mirrors,
+            mirrorKeyedDefs
+          );
+        }
+      };
+    },
+    mirror(source, sourceKey, targetKey) {
+      const def = {
+        sourceToken: source,
+        sourceKey,
+        targetKey: targetKey ?? sourceKey
+      };
+      return createConstrainedBuilder(
+        _enumObj,
+        accum,
+        [...mirrors, def],
+        mirrorKeyedDefs
+      );
+    },
+    mirrorKeyed(source, sourceKey, options, targetKey) {
+      const def = {
+        sourceToken: source,
+        sourceKey,
+        targetKey: targetKey ?? sourceKey,
+        extractId: options.extractId
+      };
+      return createConstrainedBuilder(_enumObj, accum, mirrors, [
+        ...mirrorKeyedDefs,
+        def
+      ]);
+    },
+    build() {
+      return new import_core6.InjectionToken("FlurryxStore", {
+        providedIn: "root",
+        factory: () => {
+          const store = new DynamicStore(accum);
+          wireMirrors(store, mirrors);
+          wireMirrorKeyed(store, mirrorKeyedDefs);
+          return store;
+        }
+      });
+    }
+  };
+}
+function createInterfaceBuilder(mirrors = [], mirrorKeyedDefs = []) {
+  return {
+    mirror(source, sourceKey, targetKey) {
+      const def = {
+        sourceToken: source,
+        sourceKey,
+        targetKey: targetKey ?? sourceKey
+      };
+      return createInterfaceBuilder(
+        [...mirrors, def],
+        mirrorKeyedDefs
+      );
+    },
+    mirrorKeyed(source, sourceKey, options, targetKey) {
+      const def = {
+        sourceToken: source,
+        sourceKey,
+        targetKey: targetKey ?? sourceKey,
+        extractId: options.extractId
+      };
+      return createInterfaceBuilder(mirrors, [
+        ...mirrorKeyedDefs,
+        def
+      ]);
+    },
+    build() {
+      return new import_core6.InjectionToken("FlurryxStore", {
+        providedIn: "root",
+        factory: () => {
+          const store = new LazyStore();
+          wireMirrors(store, mirrors);
+          wireMirrorKeyed(store, mirrorKeyedDefs);
+          return store;
+        }
+      });
+    }
+  };
+}
+var Store = {
+  ...createBuilder({}),
+  for(enumObj) {
+    if (arguments.length === 0) {
+      return createInterfaceBuilder();
+    }
+    return createConstrainedBuilder(enumObj, {});
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseStore,