eddev 2.0.0-beta.122 → 2.0.0-beta.124

package/dist/app/lib/routing/hooks/useSearchParams.d.ts

@@ -1,10 +1,81 @@
+/**
+ * Search param API object.
+ */
 export type SearchParamAPI<T> = {
+    /**
+     * Set an individual parameter value by key.
+     *
+     * If the value is an array, then one or more `key[]` parameters will be set. Otherwise, a single `key` parameter will be set.
+     *
+     * If the value is `null` or `undefined`, the parameter will be removed from the query string.
+     *
+     * @param key The search parameter name
+     * @param value The value to set
+     */
     set<K extends keyof T>(key: K, value: T[K]): void;
-    setAll: (value: T) => void;
+    /**
+     * Set multiple parameters at once.
+     *
+     * @param value
+     * @returns
+     */
+    setAll: (value: Partial<T>) => void;
+    /**
+     * Returns a memoized setter function for a specific key.
+     *
+     * This is useful when you want to pass a setter function to a child component, without needing to pass the entire API object.
+     *
+     * For example:
+     * ```tsx
+     * <input value={params.mode} onChange={api.setter("mode")} />
+     * ```
+     *
+     * @param key The search parameter name
+     * @returns (value: T) => void
+     */
     setter<K extends keyof T>(key: K): (value: T[K]) => void;
+    /**
+     * Reset all parameters to their default values.
+     */
     reset(): void;
+    /**
+     * Gets the current value of a parameter. In most cases, you should use the `params` object returned from `useSearchParams` instead of this method.
+     */
     get<K extends keyof T>(key: K): T[K];
 };
-export declare function useSearchParams<T extends {
-    [K: string]: any;
-}>(defaultValue: T): [T, SearchParamAPI<T>];
+/**
+ * Provides type-safe read/write access to query string parameters, integrating with the routing system.
+ *
+ * - Call `useSearchParams` with a default value object, which defines the expected shape of the query string parameters.
+ * - Only keys that are present in the default value object will be handled, and all others will be ignored.
+ * - Arrays of values are supported, and you should use a default value of `[]` for that key. You may want to cast the default parameter as an array of the expected type (eg. `myValue: [] as string[]`) to ensure that the parameter type is correct.
+ * - This hook returns a tuple with the current query string parameters object, and an API object with methods to interact with the query string. See {@link SearchParamAPI} for more details.
+ *
+ * For example:
+ * ```tsx
+ * const [params, api] = useSearchParams({
+ *  mode: "list" as "list" | "grid",
+ *  page: 1,
+ *  tags: [] as string[],
+ * })
+ *
+ * api.set("mode", "grid")
+ * api.set("tags", ["tag1", "tag2"])
+ * ```
+ *
+ * Note that if a parameter is set back to it's default value, it'll actually be _removed_ from the updated query string, keeping the URL clean when only the default values are set.
+ *
+ * ```tsx
+ * api.set("mode", "grid")
+ *   // url becomes: "/?mode=grid"
+ *   // params.mode === 'grid'
+ *
+ * api.set("mode", "list")
+ *   // url becomes: "/"
+ *   // params.mode === 'list'
+ * ```
+ *
+ * @param defaultValue - The default value object, defining the expected shape of the query string parameters.
+ * @returns A tuple of the resolve parameter object, and a {@link SearchParamAPI} object with methods to interact with the query string.
+ */
+export declare function useSearchParams<T extends object>(defaultValue: T): [T, SearchParamAPI<T>];

package/dist/app/lib/routing/hooks/useSearchParams.js

@@ -1,30 +1,89 @@
-import { useMemo } from "react";
+import { useMemo, useRef } from "react";
 import { useRoute } from "./useRoute.js";
 import { useRouter } from "./useRouter.js";
+import { parseQuery } from "../utils.js";
+import { hash } from "object-code";
+/**
+ * Provides type-safe read/write access to query string parameters, integrating with the routing system.
+ *
+ * - Call `useSearchParams` with a default value object, which defines the expected shape of the query string parameters.
+ * - Only keys that are present in the default value object will be handled, and all others will be ignored.
+ * - Arrays of values are supported, and you should use a default value of `[]` for that key. You may want to cast the default parameter as an array of the expected type (eg. `myValue: [] as string[]`) to ensure that the parameter type is correct.
+ * - This hook returns a tuple with the current query string parameters object, and an API object with methods to interact with the query string. See {@link SearchParamAPI} for more details.
+ *
+ * For example:
+ * ```tsx
+ * const [params, api] = useSearchParams({
+ *  mode: "list" as "list" | "grid",
+ *  page: 1,
+ *  tags: [] as string[],
+ * })
+ *
+ * api.set("mode", "grid")
+ * api.set("tags", ["tag1", "tag2"])
+ * ```
+ *
+ * Note that if a parameter is set back to it's default value, it'll actually be _removed_ from the updated query string, keeping the URL clean when only the default values are set.
+ *
+ * ```tsx
+ * api.set("mode", "grid")
+ *   // url becomes: "/?mode=grid"
+ *   // params.mode === 'grid'
+ *
+ * api.set("mode", "list")
+ *   // url becomes: "/"
+ *   // params.mode === 'list'
+ * ```
+ *
+ * @param defaultValue - The default value object, defining the expected shape of the query string parameters.
+ * @returns A tuple of the resolve parameter object, and a {@link SearchParamAPI} object with methods to interact with the query string.
+ */
 export function useSearchParams(defaultValue) {
     const route = useRoute();
     const replaceQuery = useRouter((r) => r.replaceQuery);
-    const result = useMemo(() => ({
+    const merged = useMemo(() => ({
         ...defaultValue,
         ...route.query,
     }), [route.query]);
+    const values = useRef(merged);
+    values.current = merged;
+    // Memoized setters
+    const setters = useMemo(() => ({}), []);
+    // Gets the current value, directly from the source.
+    function get() {
+        if (env.client) {
+            return { ...defaultValue, ...parseQuery(document.location.search) };
+        }
+        else {
+            return merged;
+        }
+    }
+    // Main update function
     const update = (patch) => {
-        const value = { ...result, ...patch };
+        const value = { ...get(), ...patch };
         for (let key in defaultValue) {
-            if (defaultValue[key] === value[key] || [null, undefined].includes(value[key])) {
+            if (hash(defaultValue[key]) === hash(value[key]) || [null, undefined].includes(value[key])) {
                 delete value[key];
             }
         }
+        values.current = value;
         replaceQuery(value);
     };
     return [
-        result,
-        {
-            set: (key, value) => update({ ...result, [key]: value }),
-            setAll: (value) => update(value),
-            setter: (key) => (value) => update({ ...result, [key]: value }),
+        values.current,
+        useMemo(() => ({
+            set: (key, value) => update({ [key]: value }),
+            setAll: (value) => update({
+                ...defaultValue,
+                ...value,
+            }),
+            setter: (key) => {
+                if (!setters[key])
+                    setters[key] = (value) => update({ [key]: value });
+                return setters[key];
+            },
             reset: () => update({}),
-            get: (key) => result[key],
-        },
+            get: (key) => values.current[key],
+        }), []),
     ];
 }

package/dist/node/cli/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "2.0.0-beta.122";
+export declare const VERSION = "2.0.0-beta.124";

package/dist/node/cli/version.js

@@ -1 +1 @@
-export const VERSION = "2.0.0-beta.122";
+export const VERSION = "2.0.0-beta.124";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eddev",
-  "version": "2.0.0-beta.122",
+  "version": "2.0.0-beta.124",
   "description": "",
   "main": "index.js",
   "type": "module",