ng-simple-state 21.1.3 → 21.1.5

package/README.md

@@ -1,4 +1,4 @@
-# NgSimpleState [![Build Status](https://app.travis-ci.com/nigrosimone/ng-simple-state.svg?branch=main)](https://app.travis-ci.com/nigrosimone/ng-simple-state) [![Coverage Status](https://coveralls.io/repos/github/nigrosimone/ng-simple-state/badge.svg?branch=main)](https://coveralls.io/github/nigrosimone/ng-simple-state?branch=main) [![NPM version](https://img.shields.io/npm/v/ng-simple-state.svg)](https://www.npmjs.com/package/ng-simple-state) [![Maintainability](https://api.codeclimate.com/v1/badges/1bfc363a95053ecc3429/maintainability)](https://codeclimate.com/github/nigrosimone/ng-simple-state/maintainability)
+# NgSimpleState [![NPM version](https://img.shields.io/npm/v/ng-simple-state.svg)](https://www.npmjs.com/package/ng-simple-state) [![Maintainability](https://qlty.sh/gh/nigrosimone/projects/ng-simple-state/maintainability.svg)](https://qlty.sh/gh/nigrosimone/projects/ng-simple-state)
 
 Simple state management in Angular with only Services and RxJS or Signal.
 
@@ -31,7 +31,6 @@ npm i ng-simple-state
 | *serializeState*       | A function used to serialize the state to a string.                                             | `JSON.stringify` |
 | *deserializeState*     | A function used to deserialize the state from a string.                                         | `JSON.parse`     |
 | *plugins*              | Array of plugins to extend store functionality.                                                 | `[]`             |
-| *enableImmer*          | Enable Immer-style immutable updates.                                                           | `false`          |
 | *immerProduce*         | Custom Immer produce function for immutable updates.                                            | undefined        |
 
 _Side note: each store can be override the global configuration implementing `storeConfig()` method (see "Override global config")._
@@ -1154,7 +1153,6 @@ Usage in component:
   selector: 'app-profile',
   template: `
     <p>Full Name: {{ store.fullName() }}</p>
-    <p>Is Adult: {{ store.isAdult() ? 'Yes' : 'No' }}</p>
     <input [value]="firstName()" (input)="updateFirstName($event)" placeholder="First name" />
     <input [value]="lastName()" (input)="updateLastName($event)" placeholder="Last name" />
   `
@@ -1283,89 +1281,83 @@ const myCustomPlugin: NgSimpleStatePlugin = {
 };
 ```
 
-### Batch Updates
+### Transactions
 
-Group multiple state updates into a single emission to improve performance:
+Execute operations with automatic rollback on error using `withTransaction`:
 
 ```ts
-import { Injectable, Signal } from '@angular/core';
-import { NgSimpleStateBaseSignalStore, NgSimpleStateStoreConfig, batchState } from 'ng-simple-state';
-
-export interface FormState {
-  name: string;
-  email: string;
-  phone: string;
-  isValid: boolean;
-}
-
-@Injectable({ providedIn: 'root' })
-export class FormStore extends NgSimpleStateBaseSignalStore<FormState> {
+import { withTransaction } from 'ng-simple-state';
+
+// Transaction with automatic rollback on error
+await withTransaction(store, async (tx) => {
+  store.setState({ step: 1 });
+  await apiCall(); // If this fails, state rolls back automatically
+  store.setState({ step: 2 });
+  tx.commit(); // Explicit commit (optional - auto-commits if not called)
+});
 
-  storeConfig(): NgSimpleStateStoreConfig<FormState> {
-    return { storeName: 'FormStore' };
+// Manual rollback example
+await withTransaction(store, async (tx) => {
+  store.setState({ processing: true });
+  const result = await riskyOperation();
+  
+  if (!result.success) {
+    tx.rollback(); // Manually rollback to initial state
+    return;
   }
+  
+  store.setState({ data: result.data });
+  tx.commit();
+});
+```
 
-  initialState(): FormState {
-    return { name: '', email: '', phone: '', isValid: false };
-  }
+### Debounced Updates
 
-  selectForm(): Signal<FormState> {
-    return this.selectState();
-  }
+Rate-limit state updates with `createDebouncedUpdater`. Only the last update within the time window is applied:
 
-  // Batch multiple updates - only one emission at the end
-  updateAllFields(name: string, email: string, phone: string): void {
-    batchState(() => {
-      this.setState({ name });
-      this.setState({ email });
-      this.setState({ phone });
-      this.setState({ isValid: this.validateForm(name, email, phone) });
-    }); // Single emission with all changes
-  }
+```ts
+import { createDebouncedUpdater } from 'ng-simple-state';
 
-  // Regular updates (each triggers an emission)
-  setName(name: string): void {
-    this.setState({ name });
-  }
+// Create a debounced updater with 300ms delay
+const { update, flush, cancel } = createDebouncedUpdater<MyState>(
+  (state) => store.setState(state),
+  300
+);
 
-  setEmail(email: string): void {
-    this.setState({ email });
-  }
+// Rapid calls - only the last one is applied after 300ms
+update({ searchQuery: 'a' });
+update({ searchQuery: 'ab' });
+update({ searchQuery: 'abc' }); // Only this is applied after 300ms
 
-  private validateForm(name: string, email: string, phone: string): boolean {
-    return name.length > 0 && email.includes('@') && phone.length >= 10;
-  }
-}
+// Force immediate update
+flush();
+
+// Cancel any pending update
+cancel();
 ```
 
-Usage in component:
+### Throttled Updates
+
+Limit update frequency with `createThrottledUpdater`. At most one update per time window:
 
 ```ts
-@Component({
-  selector: 'app-form',
-  template: `
-    <form (ngSubmit)="submitForm()">
-      <input [(ngModel)]="name" name="name" placeholder="Name" />
-      <input [(ngModel)]="email" name="email" placeholder="Email" />
-      <input [(ngModel)]="phone" name="phone" placeholder="Phone" />
-      <button type="submit">Save All (Batched)</button>
-    </form>
-    <p>Form Valid: {{ form().isValid ? 'Yes' : 'No' }}</p>
-  `
-})
-export class FormComponent {
-  store = inject(FormStore);
-  form = this.store.selectForm();
-  
-  name = '';
-  email = '';
-  phone = '';
+import { createThrottledUpdater } from 'ng-simple-state';
 
-  submitForm(): void {
-    // All updates batched into single emission
-    this.store.updateAllFields(this.name, this.email, this.phone);
-  }
-}
+// Create a throttled updater with 100ms delay
+const { update, cancel } = createThrottledUpdater<MyState>(
+  (state) => store.setState(state),
+  100
+);
+
+// First call executes immediately, subsequent calls are throttled
+update({ scrollPosition: 100 }); // Executes immediately
+update({ scrollPosition: 150 }); // Queued
+update({ scrollPosition: 200 }); // Replaces queued update
+
+// After 100ms, { scrollPosition: 200 } is applied
+
+// Cancel pending throttled update
+cancel();
 ```
 
 ### Immer-style Updates
@@ -1508,6 +1500,43 @@ Features available in Redux DevTools:
 
 ![Redux DevTools](https://github.com/nigrosimone/ng-simple-state/blob/main/projects/ng-simple-state-demo/src/assets/dev-tool.gif?raw=true)
 
+### Integration with ng-http-caching
+
+`ng-simple-state` can be used as a reactive storage backend for [ng-http-caching](https://www.npmjs.com/package/ng-http-caching). This integration allows you to manage the HTTP cache through `ng-simple-state` stores, providing full visibility and control over the cache state within your DevTools or application state.
+
+1. Install `ng-http-caching`:
+
+```bash
+npm i ng-http-caching
+```
+
+2. Configure `ng-http-caching` to use the `ng-simple-state` adapter in your `bootstrapApplication`:
+
+```ts
+import { provideNgHttpCaching } from 'ng-http-caching';
+import { withNgHttpCachingNgSimpleState } from 'ng-http-caching/ng-simple-state';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideNgHttpCaching({
+      store: withNgHttpCachingNgSimpleState(),
+    }),
+    // ... other providers
+  ]
+});
+```
+
+You can customize the store configuration (e.g., enable persistence or change the store name) by passing a configuration object to the adapter:
+
+```ts
+provideNgHttpCaching({
+  store: withNgHttpCachingNgSimpleState({
+    storeName: 'MyCacheStore',
+    // ... other NgSimpleStateStoreConfig options
+  }),
+})
+```
+
 ## Alternatives
 
 Aren't you satisfied? there are some valid alternatives: