zustand-querystring 0.3.0 → 0.3.1

package/README.md

@@ -8,7 +8,6 @@ Examples:
 
 - [React](./examples/react/)
 - [NextJS](./examples/next/)
-- [Rakkas](./examples/rakkas/)
 
 Quickstart:
 
@@ -60,5 +59,26 @@ export const useStore = create<Store>()(
 querystring options:
 
 - <b>select</b> - the select option controls what part of the state is synced with the query string
-- <b>key: string</b> - the key option controls how the state is stored in the querystring (default: $)
+- <b>key: string</b> - the key option controls how the state is stored in the querystring (default: 'state')
 - <b>url</b> - the url option is used to provide the request url on the server side render
+- <b>format</b> - custom format for stringify/parse (default: JSON-based format)
+- <b>syncNull: boolean</b> - when true, null values that differ from initial state are synced to URL (default: false)
+- <b>syncUndefined: boolean</b> - when true, undefined values that differ from initial state are synced to URL (default: false)
+
+## Important Notes
+
+### State Diffing
+
+Only values that differ from the initial state are synced to the URL.
+
+### Null and Undefined Handling
+
+By default (`syncNull: false`, `syncUndefined: false`), `null` and `undefined` values are **not** synced to the URL. This means setting a value to `null` or `undefined` effectively "clears" it back to the initial state on page refresh.
+
+If you want to preserve `null` or `undefined` values in the URL (so they persist across refreshes), set `syncNull: true` or `syncUndefined: true` in options.
+
+### State Types
+
+- **Plain objects** (created with `{}`) are recursively compared with initial state - only changed properties are synced
+- **Arrays, Dates, RegExp, Maps, Sets, and class instances** are compared as atomic values - if any part changes, the entire value is synced
+- **Functions** are never synced to the URL

package/dist/index.d.mts

@@ -14,6 +14,8 @@ interface QueryStringOptions<T> {
         stringify: (value: DeepPartial<T>) => string;
         parse: (value: string) => DeepPartial<T>;
     };
+    syncNull?: boolean;
+    syncUndefined?: boolean;
 }
 type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T>) => StateCreator<T, Mps, Mcs>;
 declare const querystring: QueryString;

package/dist/index.d.ts

@@ -14,6 +14,8 @@ interface QueryStringOptions<T> {
         stringify: (value: DeepPartial<T>) => string;
         parse: (value: string) => DeepPartial<T>;
     };
+    syncNull?: boolean;
+    syncUndefined?: boolean;
 }
 type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T>) => StateCreator<T, Mps, Mcs>;
 declare const querystring: QueryString;

package/dist/index.js

@@ -38,17 +38,20 @@ function parse(str) {
 }
 
 // src/middleware.ts
-var compact = (newState, initialState) => {
+var compact = (newState, initialState, syncNull = false, syncUndefined = false) => {
   const output = {};
   Object.keys(newState).forEach((key) => {
-    if (newState[key] !== null && newState[key] !== void 0 && typeof newState[key] !== "function" && !(0, import_lodash_es.isEqual)(newState[key], initialState[key])) {
-      if (typeof newState[key] === "object" && !Array.isArray(newState[key])) {
-        const value = compact(newState[key], initialState[key]);
+    const newValue = newState[key];
+    const initialValue = initialState[key];
+    if (typeof newValue !== "function" && !(0, import_lodash_es.isEqual)(newValue, initialValue) && (syncNull || newValue !== null) && (syncUndefined || newValue !== void 0)) {
+      const isPlainObject = typeof newValue === "object" && newValue !== null && newValue !== void 0 && !Array.isArray(newValue) && newValue.constructor === Object;
+      if (isPlainObject && initialValue && typeof initialValue === "object") {
+        const value = compact(newValue, initialValue, syncNull, syncUndefined);
         if (value && Object.keys(value).length > 0) {
           output[key] = value;
         }
       } else {
-        output[key] = newState[key];
+        output[key] = newValue;
       }
     }
   });
@@ -80,6 +83,8 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
       stringify,
       parse
     },
+    syncNull: false,
+    syncUndefined: false,
     ...options
   };
   const getStateFromUrl = (url) => {
@@ -132,7 +137,12 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
     const setQuery = () => {
       const url = new URL(window.location.href);
       const selectedState = getSelectedState(get(), url.pathname);
-      const newCompacted = compact(selectedState, initialState);
+      const newCompacted = compact(
+        selectedState,
+        initialState,
+        defaultedOptions.syncNull,
+        defaultedOptions.syncUndefined
+      );
       const previous = url.search;
       const params = url.search.slice(1).split("&").filter(Boolean);
       let stateIndex = -1;

package/dist/index.mjs

@@ -10,17 +10,20 @@ function parse(str) {
 }
 
 // src/middleware.ts
-var compact = (newState, initialState) => {
+var compact = (newState, initialState, syncNull = false, syncUndefined = false) => {
   const output = {};
   Object.keys(newState).forEach((key) => {
-    if (newState[key] !== null && newState[key] !== void 0 && typeof newState[key] !== "function" && !isEqual(newState[key], initialState[key])) {
-      if (typeof newState[key] === "object" && !Array.isArray(newState[key])) {
-        const value = compact(newState[key], initialState[key]);
+    const newValue = newState[key];
+    const initialValue = initialState[key];
+    if (typeof newValue !== "function" && !isEqual(newValue, initialValue) && (syncNull || newValue !== null) && (syncUndefined || newValue !== void 0)) {
+      const isPlainObject = typeof newValue === "object" && newValue !== null && newValue !== void 0 && !Array.isArray(newValue) && newValue.constructor === Object;
+      if (isPlainObject && initialValue && typeof initialValue === "object") {
+        const value = compact(newValue, initialValue, syncNull, syncUndefined);
         if (value && Object.keys(value).length > 0) {
           output[key] = value;
         }
       } else {
-        output[key] = newState[key];
+        output[key] = newValue;
       }
     }
   });
@@ -52,6 +55,8 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
       stringify,
       parse
     },
+    syncNull: false,
+    syncUndefined: false,
     ...options
   };
   const getStateFromUrl = (url) => {
@@ -104,7 +109,12 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
     const setQuery = () => {
       const url = new URL(window.location.href);
       const selectedState = getSelectedState(get(), url.pathname);
-      const newCompacted = compact(selectedState, initialState);
+      const newCompacted = compact(
+        selectedState,
+        initialState,
+        defaultedOptions.syncNull,
+        defaultedOptions.syncUndefined
+      );
       const previous = url.search;
       const params = url.search.slice(1).split("&").filter(Boolean);
       let stateIndex = -1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zustand-querystring",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",