Merge pull request #1 from angular-redux2/feature/settings

Feature/settings

Author: Garefild

README.md

@@ -8,18 +8,21 @@ management using Redux.
 [![downloads per month](https://img.shields.io/npm/dm/@angular-redux2/undo.svg)](https://www.npmjs.com/package/@angular-redux2/undo)
 
 ## Installation
+
 You can install angular-redux2/sync using npm:
 
 ```bash
 npm install @angular-redux2/undo
 ```
 
 ## Usage
-- Take me to the [API docs](https://angular-redux2.github.io/undo).
+
+> Take me to the [API docs](https://angular-redux2.github.io/undo).
 
 To use `@angular-redux2/undo` in your Angular application, follow these steps:
 Define a StateWatchMap object that maps the properties you want to track for undo/redo operations to their corresponding
-state paths and configure the undo middleware in your Angular-Redux2/store setup by including it in the list of middleware:
+state paths and configure the undo middleware in your Angular-Redux2/store setup by including it in the list of
+middleware:
 
 ```typescript
 const middleware: Array<Middleware> = [
@@ -28,15 +31,26 @@ const middleware: Array<Middleware> = [
             path: 'path.to.property1'
         },
         propertyName2: {
-            path: 'path.to.property2'
+            path: 'path.to.property2',
+            limit: 5
         },
     }),
 ];
 
 ngRedux.configureStore(rootReducer, {}, middleware, enhancer);
 ```
+
+settings:
+
+- `path` (required): The path to the property in the state object using dot notation.
+- `filter` (optional): A filter function that determines if the property should be watched for undo/redo. Return true to
+  include the property, and false to exclude it. If not specified, all properties are included.
+- `limit` (optional): The maximum number of past snapshots to keep in the undo history. If the limit is reached, the
+  oldest snapshots are discarded. If not specified, no limit is applied.
+
 Implement the undo/redo functionality in your Angular component or service.
-You can use the `undo`, `redo`, `jump`, and `clear_history` methods provided by `NgUndoStateActions` to perform the corresponding actions:
+You can use the `undo`, `redo`, `jump`, and `clear_history` methods provided by `NgUndoStateActions` to perform the
+corresponding actions:
 
 ```typescript
 // Example component
@@ -54,7 +68,8 @@ import { undo, redo, jump, clear_history } from '@angular-redux2/undo';
   `
 })
 export class ExampleComponent {
-    constructor(private undoStateActions: NgUndoStateActions) {}
+    constructor(private undoStateActions: NgUndoStateActions) {
+    }
 
     @Dispatch
     onUndo() {
@@ -77,3 +92,47 @@ export class ExampleComponent {
     }
 }
 ```
+
+## State Watch Map
+
+The state watch map is an object that defines the paths to the state properties you want to track for undo. It has the
+following structure:
+
+```typescript
+export interface StateWatchMap {
+    [key: string]: {
+        path: string;
+        filter?: (action: any, currentState: any, snapshot: any) => boolean;
+        limit?: number;
+    }
+}
+```
+
+- `key` (string): The unique identifier for the state property.
+- `path` (string): The dot-separated path to the state property.
+- `filter` (optional function): A filter function that determines if an action should be captured in the undo history
+  for the specific state property.
+
+## Custom Filters
+
+You can define custom filter functions to control which actions are captured in the undo history for each state
+property.
+The filter function takes three parameters:
+
+- `action`: The dispatched action object.
+- `currentState`: The current store state object.
+- `snapshot`: The snapshot to insert into the history.
+
+The filter function should return true if the action should be captured, or false otherwise.
+Here's an example of a custom filter function that only captures actions with specific types:
+
+```typescript
+const stateWatchMap: StateWatchMap = {
+    'todos': {
+        path: 'todos',
+        filter: (action: any, currentState: any, snapshot: any): boolean => {
+            return action.type === 'ADD_TODO' || action.type === 'REMOVE_TODO';
+        }
+    }
+};
+```

docs/assets/search.js

@@ -20,7 +20,7 @@ <h4>Hierarchy</h4>
 <ul class="tsd-hierarchy">
 <li><span class="target">UndoService</span></li></ul></section><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/0956b3f/projects/angular-redux2/undo/src/services/undo.service.ts#L26">services/undo.service.ts:26</a></li></ul></aside>
+<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/c6324e8/projects/angular-redux2/undo/src/services/undo.service.ts#L26">services/undo.service.ts:26</a></li></ul></aside>
 <section class="tsd-panel-group tsd-index-group">
 <section class="tsd-panel tsd-index-panel">
 <details class="tsd-index-content tsd-index-accordion" open><summary class="tsd-accordion-summary tsd-index-summary">
@@ -58,7 +58,7 @@ <h5><span class="tsd-kind-parameter">stateWatchMap</span>: <a href="../interface
 </div></li></ul></div>
 <h4 class="tsd-returns-title">Returns <a href="UndoService.html" class="tsd-signature-type tsd-kind-class">UndoService</a></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/0956b3f/projects/angular-redux2/undo/src/services/undo.service.ts#L46">services/undo.service.ts:46</a></li></ul></aside></li></ul></section></section>
+<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/c6324e8/projects/angular-redux2/undo/src/services/undo.service.ts#L46">services/undo.service.ts:46</a></li></ul></aside></li></ul></section></section>
 <section class="tsd-panel-group tsd-member-group">
 <h2>Properties</h2>
 <section class="tsd-panel tsd-member tsd-is-protected"><a id="watchStateMap" class="tsd-anchor"></a>
@@ -72,20 +72,24 @@ <h4>Type declaration</h4>
 <li class="tsd-parameter-index-signature">
 <h5><span class="tsd-signature-symbol">[</span><span class="tsd-kind-parameter">key</span>: <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]: </span><span class="tsd-signature-type ">NgUndoStateActions</span></h5></li></ul></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/0956b3f/projects/angular-redux2/undo/src/services/undo.service.ts#L35">services/undo.service.ts:35</a></li></ul></aside></section></section>
+<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/c6324e8/projects/angular-redux2/undo/src/services/undo.service.ts#L35">services/undo.service.ts:35</a></li></ul></aside></section></section>
 <section class="tsd-panel-group tsd-member-group">
 <h2>Methods</h2>
 <section class="tsd-panel tsd-member tsd-is-protected"><a id="detectChange" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagProtected">Protected</code> <span>detect<wbr/>Change</span><a href="#detectChange" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <ul class="tsd-signatures tsd-is-protected">
-<li class="tsd-signature tsd-anchor-link" id="detectChange.detectChange-1"><span class="tsd-kind-call-signature">detect<wbr/>Change</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">state</span>, <span class="tsd-kind-parameter">newState</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">any</span><a href="#detectChange.detectChange-1" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></li>
+<li class="tsd-signature tsd-anchor-link" id="detectChange.detectChange-1"><span class="tsd-kind-call-signature">detect<wbr/>Change</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">action</span>, <span class="tsd-kind-parameter">state</span>, <span class="tsd-kind-parameter">newState</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">any</span><a href="#detectChange.detectChange-1" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></li>
 <li class="tsd-description"><code class="tsd-tag ts-flagProtected">Protected</code> 
 <div class="tsd-comment tsd-typography"><p>Detects changes in the state and inserts snapshots into the undo history when necessary.</p>
 </div>
 <div class="tsd-parameters">
 <h4 class="tsd-parameters-title">Parameters</h4>
 <ul class="tsd-parameter-list">
 <li>
+<h5><span class="tsd-kind-parameter">action</span>: <span class="tsd-signature-type">any</span></h5>
+<div class="tsd-comment tsd-typography"><p>The dispatched action object.</p>
+</div></li>
+<li>
 <h5><span class="tsd-kind-parameter">state</span>: <span class="tsd-signature-type">any</span></h5>
 <div class="tsd-comment tsd-typography"><p>The current state object.</p>
 </div></li>
@@ -98,7 +102,7 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">any</span
 </ul>
 <aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/0956b3f/projects/angular-redux2/undo/src/services/undo.service.ts#L113">services/undo.service.ts:113</a></li></ul></aside></li></ul></section>
+<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/c6324e8/projects/angular-redux2/undo/src/services/undo.service.ts#L117">services/undo.service.ts:117</a></li></ul></aside></li></ul></section>
 <section class="tsd-panel tsd-member tsd-is-protected"><a id="watcherAction" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><code class="tsd-tag ts-flagProtected">Protected</code> <span>watcher<wbr/>Action</span><a href="#watcherAction" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <ul class="tsd-signatures tsd-is-protected">
@@ -122,7 +126,7 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">any</span
 </ul>
 <aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/0956b3f/projects/angular-redux2/undo/src/services/undo.service.ts#L78">services/undo.service.ts:78</a></li></ul></aside></li></ul></section>
+<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/c6324e8/projects/angular-redux2/undo/src/services/undo.service.ts#L81">services/undo.service.ts:81</a></li></ul></aside></li></ul></section>
 <section class="tsd-panel tsd-member"><a id="watcherState" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>watcher<wbr/>State</span><a href="#watcherState" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <ul class="tsd-signatures">
@@ -150,7 +154,7 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">any</span
 </ul>
 <aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/0956b3f/projects/angular-redux2/undo/src/services/undo.service.ts#L61">services/undo.service.ts:61</a></li></ul></aside></li></ul></section></section></div>
+<li>Defined in <a href="https://github.com/angular-redux2/undo/blob/c6324e8/projects/angular-redux2/undo/src/services/undo.service.ts#L64">services/undo.service.ts:64</a></li></ul></aside></li></ul></section></section></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">
@@ -182,6 +186,7 @@ <h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><path d="M4.9389
 <li><a href="UndoService.html" class="current"><svg class="tsd-kind-icon" width="24" height="24" viewBox="0 0 24 24"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-class)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6" id="icon-128-path"></rect><path d="M11.898 16.1201C11.098 16.1201 10.466 15.8961 10.002 15.4481C9.53803 15.0001 9.30603 14.3841 9.30603 13.6001V9.64012C9.30603 8.85612 9.53803 8.24012 10.002 7.79212C10.466 7.34412 11.098 7.12012 11.898 7.12012C12.682 7.12012 13.306 7.34812 13.77 7.80412C14.234 8.25212 14.466 8.86412 14.466 9.64012H13.386C13.386 9.14412 13.254 8.76412 12.99 8.50012C12.734 8.22812 12.37 8.09212 11.898 8.09212C11.426 8.09212 11.054 8.22412 10.782 8.48812C10.518 8.75212 10.386 9.13212 10.386 9.62812V13.6001C10.386 14.0961 10.518 14.4801 10.782 14.7521C11.054 15.0161 11.426 15.1481 11.898 15.1481C12.37 15.1481 12.734 15.0161 12.99 14.7521C13.254 14.4801 13.386 14.0961 13.386 13.6001H14.466C14.466 14.3761 14.234 14.9921 13.77 15.4481C13.306 15.8961 12.682 16.1201 11.898 16.1201Z" fill="var(--color-text)" id="icon-128-text"></path></svg><span>Undo<wbr/>Service</span></a></li>
 <li><a href="../interfaces/NgUndoAction.html"><svg class="tsd-kind-icon" width="24" height="24" viewBox="0 0 24 24"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-interface)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6" id="icon-256-path"></rect><path d="M9.51 16V15.016H11.298V8.224H9.51V7.24H14.19V8.224H12.402V15.016H14.19V16H9.51Z" fill="var(--color-text)" id="icon-256-text"></path></svg><span>Ng<wbr/>Undo<wbr/>Action</span></a></li>
 <li><a href="../interfaces/NgUndoState.html"><svg class="tsd-kind-icon" width="24" height="24" viewBox="0 0 24 24"><use href="#icon-256-path"></use><use href="#icon-256-text"></use></svg><span>Ng<wbr/>Undo<wbr/>State</span></a></li>
+<li><a href="../interfaces/Settings.html"><svg class="tsd-kind-icon" width="24" height="24" viewBox="0 0 24 24"><use href="#icon-256-path"></use><use href="#icon-256-text"></use></svg><span>Settings</span></a></li>
 <li><a href="../interfaces/StateWatchMap.html"><svg class="tsd-kind-icon" width="24" height="24" viewBox="0 0 24 24"><use href="#icon-256-path"></use><use href="#icon-256-text"></use></svg><span>State<wbr/>Watch<wbr/>Map</span></a></li>
 <li><a href="../interfaces/UndoState.html"><svg class="tsd-kind-icon" width="24" height="24" viewBox="0 0 24 24"><use href="#icon-256-path"></use><use href="#icon-256-text"></use></svg><span>Undo<wbr/>State</span></a></li>
 <li><a href="../variables/HISTORY_STATE_KEY.html"><svg class="tsd-kind-icon" width="24" height="24" viewBox="0 0 24 24"><rect fill="var(--color-icon-background)" stroke="var(--color-ts-variable)" stroke-width="1.5" x="1" y="1" width="22" height="22" rx="6" id="icon-32-path"></rect><path d="M11.106 16L8.85 7.24H9.966L11.454 13.192C11.558 13.608 11.646 13.996 11.718 14.356C11.79 14.708 11.842 14.976 11.874 15.16C11.906 14.976 11.954 14.708 12.018 14.356C12.09 13.996 12.178 13.608 12.282 13.192L13.758 7.24H14.85L12.582 16H11.106Z" fill="var(--color-text)" id="icon-32-text"></path></svg><span>HISTORY_<wbr/>STATE_<wbr/>KEY</span></a></li>