refactor!: use options as second parameter

BREAKING CHANGE: This replaces skipSubscribe with options to configure proxyWithHistory
valtiojs · Jan 8, 2024 · f825975 · f825975
1 parent 1a3272b
commit f825975
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 13 deletions.
diff --git a/packages/history-utility/README.md b/packages/history-utility/README.md
@@ -47,8 +47,9 @@ export default function App() {
 }
 ```
 
-### Notable changes
+### Notable Breaking changes
 
 - the `history` object has changes
   - `history.snapshots` is renamed to `history.nodes`
   - a `HistoryNode` has the structure `{ snapshot: Snapshot<T>; createdAt: Date; updatedAt?: Date;  }`
+- The second parameter of `proxyWithHistory` is now an object instead of a `boolean`. `{ skipSubscribe?: boolean }`
diff --git a/packages/history-utility/docs/modules.md b/packages/history-utility/docs/modules.md
@@ -8,6 +8,7 @@
 
 - [History](modules.md#history)
 - [HistoryNode](modules.md#historynode)
+- [HistoryOptions](modules.md#historyoptions)
 
 ### Functions
 
@@ -35,7 +36,7 @@
 
 #### Defined in
 
-[packages/history-utility/src/history-utility.ts:26](https://github.com/valtiojs/valtio-history/blob/86c1430/packages/history-utility/src/history-utility.ts#L26)
+[packages/history-utility/src/history-utility.ts:26](https://github.com/valtiojs/valtio-history/blob/f4b7d5a/packages/history-utility/src/history-utility.ts#L26)
 
 ---
 
@@ -59,13 +60,29 @@
 
 #### Defined in
 
-[packages/history-utility/src/history-utility.ts:10](https://github.com/valtiojs/valtio-history/blob/86c1430/packages/history-utility/src/history-utility.ts#L10)
+[packages/history-utility/src/history-utility.ts:10](https://github.com/valtiojs/valtio-history/blob/f4b7d5a/packages/history-utility/src/history-utility.ts#L10)
+
+---
+
+### HistoryOptions
+
+Ƭ **HistoryOptions**: `Object`
+
+#### Type declaration
+
+| Name             | Type      | Description                                                       |
+| :--------------- | :-------- | :---------------------------------------------------------------- |
+| `skipSubscribe?` | `boolean` | determines if the internal subscribe behaviour should be skipped. |
+
+#### Defined in
+
+[packages/history-utility/src/history-utility.ts:41](https://github.com/valtiojs/valtio-history/blob/f4b7d5a/packages/history-utility/src/history-utility.ts#L41)
 
 ## Functions
 
 ### proxyWithHistory
 
-▸ **proxyWithHistory**\<`V`\>(`initialValue`, `skipSubscribe?`): `Object`
+▸ **proxyWithHistory**\<`V`\>(`initialValue`, `options?`): `Object`
 
 This creates a new proxy with history support (ProxyHistoryObject).
 It includes following main properties:<br>
@@ -97,10 +114,10 @@ Notes: <br>
 
 #### Parameters
 
-| Name            | Type      | Default value | Description                                                       |
-| :-------------- | :-------- | :------------ | :---------------------------------------------------------------- |
-| `initialValue`  | `V`       | `undefined`   | any object to track                                               |
-| `skipSubscribe` | `boolean` | `false`       | determines if the internal subscribe behaviour should be skipped. |
+| Name           | Type                                          | Description                                    |
+| :------------- | :-------------------------------------------- | :--------------------------------------------- |
+| `initialValue` | `V`                                           | any value to be tracked                        |
+| `options?`     | [`HistoryOptions`](modules.md#historyoptions) | use to configure the proxyWithHistory utility. |
 
 #### Returns
 
@@ -136,4 +153,4 @@ const state = proxyWithHistory({
 
 #### Defined in
 
-[packages/history-utility/src/history-utility.ts:94](https://github.com/valtiojs/valtio-history/blob/86c1430/packages/history-utility/src/history-utility.ts#L94)
+[packages/history-utility/src/history-utility.ts:101](https://github.com/valtiojs/valtio-history/blob/f4b7d5a/packages/history-utility/src/history-utility.ts#L101)
diff --git a/packages/history-utility/src/history-utility.ts b/packages/history-utility/src/history-utility.ts
@@ -38,6 +38,13 @@ export type History<T> = {
   index: number;
 };
 
+export type HistoryOptions = {
+  /**
+   * determines if the internal subscribe behaviour should be skipped.
+   */
+  skipSubscribe?: boolean;
+};
+
 const isObject = (value: unknown): value is object =>
   !!value && typeof value === 'object';
 
@@ -81,8 +88,8 @@ const deepClone = <T>(value: T): T => {
  * Notes: <br>
  * - Suspense/promise is not supported. <br>
  *
- * @param initialValue - any object to track
- * @param skipSubscribe - determines if the internal subscribe behaviour should be skipped.
+ * @param initialValue - any value to be tracked
+ * @param options - use to configure the proxyWithHistory utility.
  * @returns  proxyObject
  *
  * @example
@@ -91,7 +98,7 @@ const deepClone = <T>(value: T): T => {
  *   count: 1,
  * })
  */
-export function proxyWithHistory<V>(initialValue: V, skipSubscribe = false) {
+export function proxyWithHistory<V>(initialValue: V, options?: HistoryOptions) {
   const proxyObject = proxy({
     /**
      * any value to be tracked (does not have to be an object)
@@ -283,7 +290,7 @@ export function proxyWithHistory<V>(initialValue: V, skipSubscribe = false) {
 
   proxyObject.saveHistory();
 
-  if (!skipSubscribe) {
+  if (!options?.skipSubscribe) {
     proxyObject.subscribe();
   }