feat: add goTo utility (#4)

* docs: update docs listing * feat: add goTo utility function
valtiojs · Jan 8, 2024 · 1a3272b · 1a3272b
1 parent 8a38376
commit 1a3272b
Show file tree

Hide file tree

Showing 5 changed files with 94 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -6,9 +6,9 @@ https://valtio.pmnd.rs/docs/api/utils/proxyWithHistory
 
 ### Main Packages
 
-| Name                                       | Docs                                                                                                                    | Badges                                                                                                 |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| [valtio-history](packages/history-utility) | [website](https://valtio.pmnd.rs/docs/api/utils/proxyWithHistory) <br/> [api](packages/history-utility/docs/modules.md) | [![npm version](https://badge.fury.io/js/valtio-history.svg)](https://badge.fury.io/js/valtio-history) |
+| Name                                       | Docs                                                                                                                       | Badges                                                                                                 |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| [valtio-history](packages/history-utility) | - [website](https://valtio.pmnd.rs/docs/api/utils/proxyWithHistory) <br/>- [api](packages/history-utility/docs/modules.md) | [![npm version](https://badge.fury.io/js/valtio-history.svg)](https://badge.fury.io/js/valtio-history) |
 
 ---
 

diff --git a/packages/history-utility/README.md b/packages/history-utility/README.md
@@ -6,6 +6,8 @@ valtio utility for creating a proxy state with history tracking
 
 https://valtio.pmnd.rs/docs/api/utils/proxyWithHistory
 
+see detailed [api docs](https://github.com/valtiojs/valtio-history/blob/main/packages/history-utility/docs/modules.md) for more info.
+
 ---
 
 ## Migrating from `valtio/utils`

diff --git a/packages/history-utility/docs/modules.md b/packages/history-utility/docs/modules.md
@@ -35,7 +35,7 @@
 
 #### Defined in
 
-[packages/history-utility/src/history-utility.ts:26](https://github.com/valtiojs/valtio-history/blob/3130a40/packages/history-utility/src/history-utility.ts#L26)
+[packages/history-utility/src/history-utility.ts:26](https://github.com/valtiojs/valtio-history/blob/86c1430/packages/history-utility/src/history-utility.ts#L26)
 
 ---
 
@@ -59,7 +59,7 @@
 
 #### Defined in
 
-[packages/history-utility/src/history-utility.ts:10](https://github.com/valtiojs/valtio-history/blob/3130a40/packages/history-utility/src/history-utility.ts#L10)
+[packages/history-utility/src/history-utility.ts:10](https://github.com/valtiojs/valtio-history/blob/86c1430/packages/history-utility/src/history-utility.ts#L10)
 
 ## Functions
 
@@ -115,6 +115,7 @@ proxyObject
 | `clone`                | \<T\>(`value`: `T`) => `T`                                                                                            | utility to clone a snapshot                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `getCurrentChangeDate` | () => `undefined` \| `Date`                                                                                           | get the date when a node was entered into history.                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `getNode`              | (`index`: `number`) => `undefined` \| \{ `createdAt`: `Date` ; `snapshot`: `Snapshot`\<`V`\> ; `updatedAt?`: `Date` } | utility method to get a history node. The snapshot within this node is already cloned and will not affect the original value if updated.                                                                                                                                                                                                                                                                                                               |
+| `goTo`                 | (`index`: `number`) => `void`                                                                                         | a function to go to a specific index in history                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `history`              | [`History`](modules.md#history)\<`V`\> & `AsRef`                                                                      | an object holding the history of snapshots and other metadata <br> - history.index: the history index to the current snapshot <br> - history.nodes: the nodes of the history for each change <br> - history.wip: field for holding sandbox changes; used to avoid infinite loops<br>                                                                                                                                                                   |
 | `redo`                 | () => `void`                                                                                                          | a function to go forward in history                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `remove`               | (`index`: `number`) => `undefined` \| [`HistoryNode`](modules.md#historynode)\<`V`\>                                  | The remove method is only invoked when there are more than one nodes and when a valid index is provided. If the current index is removed, An index greater than the current index will be preferred as the next value.                                                                                                                                                                                                                                 |
@@ -135,4 +136,4 @@ const state = proxyWithHistory({
 
 #### Defined in
 
-[packages/history-utility/src/history-utility.ts:94](https://github.com/valtiojs/valtio-history/blob/3130a40/packages/history-utility/src/history-utility.ts#L94)
+[packages/history-utility/src/history-utility.ts:94](https://github.com/valtiojs/valtio-history/blob/86c1430/packages/history-utility/src/history-utility.ts#L94)
diff --git a/packages/history-utility/src/__tests__/history-utility.vanilla.spec.ts b/packages/history-utility/src/__tests__/history-utility.vanilla.spec.ts
@@ -386,4 +386,77 @@ describe('proxyWithHistory: vanilla', () => {
       ]);
     });
   });
+  describe('goTo', () => {
+    it('should be noop when invalid index is provided', async () => {
+      const state = proxyWithHistory({ count: 0 });
+
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+
+      expect(state.value.count).toEqual(5);
+      expect(state.history.nodes.length).toEqual(6);
+      expect(state.history.index).toEqual(5);
+      expect(state.history.nodes.map(mapNumbers)).toEqual([0, 1, 2, 3, 4, 5]);
+
+      state.goTo(100);
+      await Promise.resolve();
+
+      expect(state.value.count).toEqual(5);
+      expect(state.history.nodes.length).toEqual(6);
+      expect(state.history.index).toEqual(5);
+      expect(state.history.nodes.map(mapNumbers)).toEqual([0, 1, 2, 3, 4, 5]);
+    });
+
+    it('should set specified index when index is valid', async () => {
+      const state = proxyWithHistory({ count: 0 });
+
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+      state.value.count += 1;
+      await Promise.resolve();
+
+      expect(state.value.count).toEqual(5);
+      expect(state.history.nodes.length).toEqual(6);
+      expect(state.history.index).toEqual(5);
+      expect(state.history.nodes.map(mapNumbers)).toEqual([0, 1, 2, 3, 4, 5]);
+
+      state.goTo(1);
+      await Promise.resolve();
+
+      expect(state.value.count).toEqual(1);
+      expect(state.history.index).toEqual(1);
+      expect(state.history.nodes.length).toEqual(6);
+      expect(state.history.nodes.map(mapNumbers)).toEqual([0, 1, 2, 3, 4, 5]);
+
+      state.goTo(2);
+      await Promise.resolve();
+
+      expect(state.value.count).toEqual(2);
+      expect(state.history.index).toEqual(2);
+      expect(state.history.nodes.length).toEqual(6);
+      expect(state.history.nodes.map(mapNumbers)).toEqual([0, 1, 2, 3, 4, 5]);
+
+      state.goTo(4);
+      await Promise.resolve();
+
+      expect(state.value.count).toEqual(4);
+      expect(state.history.index).toEqual(4);
+      expect(state.history.nodes.length).toEqual(6);
+      expect(state.history.nodes.map(mapNumbers)).toEqual([0, 1, 2, 3, 4, 5]);
+    });
+  });
 });
diff --git a/packages/history-utility/src/history-utility.ts b/packages/history-utility/src/history-utility.ts
@@ -135,6 +135,18 @@ export function proxyWithHistory<V>(initialValue: V, skipSubscribe = false) {
      * utility to clone a snapshot
      */
     clone: deepClone,
+    /**
+     * a function to go to a specific index in history
+     */
+    goTo: (index: number) => {
+      const node = proxyObject.history.nodes[index];
+
+      if (!node) return;
+
+      proxyObject.history.wip = proxyObject.clone(node.snapshot);
+      proxyObject.value = proxyObject.history.wip as V;
+      proxyObject.history.index = index;
+    },
     /**
      * a function to return true if undo is available
      * @returns boolean