@1money/hooks 0.1.1 → 0.1.3

package/es/index.d.ts

@@ -9,3 +9,5 @@ export { default as useSyncState } from './useSyncState';
 export { default as useUpdateEffect } from './useUpdateEffect';
 export { default as useLayoutState, useTimeoutLock } from './useLayoutState';
 export type { Updater } from './useLayoutState';
+export { default as useQueryState, queryString, queryNumber, queryBoolean, queryJson, } from './useQueryState';
+export type { Parser, Serializer, QueryStateOptions, } from './useQueryState';

package/es/index.js

@@ -8,4 +8,5 @@ export { default as usePrevious } from "./usePrevious";
 export { default as useSafeState } from "./useSafeState";
 export { default as useSyncState } from "./useSyncState";
 export { default as useUpdateEffect } from "./useUpdateEffect";
-export { default as useLayoutState, useTimeoutLock } from "./useLayoutState";
+export { default as useLayoutState, useTimeoutLock } from "./useLayoutState";
+export { default as useQueryState, queryString, queryNumber, queryBoolean, queryJson } from "./useQueryState";

package/es/useLatest/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 /**
  * A hook that returns a ref object whose `.current` property is always
  * updated to the latest value. Useful for accessing the latest value

package/es/useQueryState/index.d.ts

@@ -0,0 +1,75 @@
+/** Turn a raw query string into a typed value. */
+export type Parser<T> = (value: string) => T;
+/** Turn a typed value back into a query string. */
+export type Serializer<T> = (value: T) => string;
+export interface QueryStateOptions<T> {
+    /**
+     * Parse the raw `string` read from the URL into `T`.
+     * Defaults to identity (the raw string).
+     */
+    parser?: Parser<T>;
+    /**
+     * Serialize `T` back into a `string` for the URL.
+     * Defaults to `String(value)`.
+     */
+    serializer?: Serializer<T>;
+    /**
+     * Value returned when the param is absent from
+     * the URL. When set, the hook never returns
+     * `null`.
+     */
+    defaultValue?: T;
+    /**
+     * How the URL is mutated:
+     * - `'replace'` (default) — `history.replaceState`,
+     *   does not add a history entry.
+     * - `'push'` — `history.pushState`, back/forward
+     *   navigates between values.
+     */
+    history?: 'push' | 'replace';
+}
+type SetQueryState<T> = (value: T | null | ((prev: T | null) => T | null)) => void;
+/** Identity parser used when none is supplied. */
+export declare const queryString: Parser<string>;
+/** Parse a numeric query param. `NaN` for non-numbers. */
+export declare const queryNumber: Parser<number>;
+/** Parse a boolean query param. Only `'true'` is true. */
+export declare const queryBoolean: Parser<boolean>;
+/** Parse a JSON-encoded query param. */
+export declare const queryJson: Parser<unknown>;
+/**
+ * Sync a piece of React state with a URL query
+ * parameter, so it survives refreshes and is
+ * shareable via the link.
+ *
+ * Reading is reactive via Next's `useSearchParams`;
+ * writing goes through the native
+ * `history.pushState/replaceState`, which the Next.js
+ * App Router intercepts and syncs back into
+ * `useSearchParams` *without* a server round-trip (no
+ * route re-render, no scroll-to-top). Because the
+ * value is reactive, using it as a SWR/React Query key
+ * makes dependent requests refetch automatically.
+ *
+ * Constraints (inherited from `useSearchParams`):
+ * - Next.js App Router only; the calling component
+ *   must be a Client Component (`'use client'`).
+ * - On statically rendered routes, wrap the consumer
+ *   in `<Suspense>`; otherwise that subtree opts into
+ *   client-side rendering. During prerender the param
+ *   reads as absent, so `value` falls back to
+ *   `defaultValue ?? null`.
+ *
+ * @param key The query parameter name
+ * @param options Parsing, serialization and history
+ *   behaviour
+ * @returns A `[value, setValue]` tuple. `setValue`
+ *   accepts a value, an updater function, or `null`
+ *   to remove the param.
+ */
+declare function useQueryState(key: string): [string | null, SetQueryState<string>];
+declare function useQueryState<T>(key: string, options: QueryStateOptions<T> & {
+    defaultValue: T;
+}): [T, SetQueryState<T>];
+declare function useQueryState<T>(key: string, options: QueryStateOptions<T>): [T | null, SetQueryState<T>];
+export default useQueryState;

package/es/useQueryState/index.js

@@ -0,0 +1,110 @@
+'use client';
+
+import { useSearchParams } from 'next/navigation';
+import useMemoizedFn from "../useMemoizedFn";
+
+/** Turn a raw query string into a typed value. */
+
+/** Turn a typed value back into a query string. */
+
+/** Identity parser used when none is supplied. */
+export var queryString = function queryString(value) {
+  return value;
+};
+
+/** Parse a numeric query param. `NaN` for non-numbers. */
+export var queryNumber = function queryNumber(value) {
+  return Number(value);
+};
+
+/** Parse a boolean query param. Only `'true'` is true. */
+export var queryBoolean = function queryBoolean(value) {
+  return value === 'true';
+};
+
+/** Parse a JSON-encoded query param. */
+export var queryJson = function queryJson(value) {
+  return JSON.parse(value);
+};
+var isBrowser = typeof window !== 'undefined';
+
+/**
+ * Sync a piece of React state with a URL query
+ * parameter, so it survives refreshes and is
+ * shareable via the link.
+ *
+ * Reading is reactive via Next's `useSearchParams`;
+ * writing goes through the native
+ * `history.pushState/replaceState`, which the Next.js
+ * App Router intercepts and syncs back into
+ * `useSearchParams` *without* a server round-trip (no
+ * route re-render, no scroll-to-top). Because the
+ * value is reactive, using it as a SWR/React Query key
+ * makes dependent requests refetch automatically.
+ *
+ * Constraints (inherited from `useSearchParams`):
+ * - Next.js App Router only; the calling component
+ *   must be a Client Component (`'use client'`).
+ * - On statically rendered routes, wrap the consumer
+ *   in `<Suspense>`; otherwise that subtree opts into
+ *   client-side rendering. During prerender the param
+ *   reads as absent, so `value` falls back to
+ *   `defaultValue ?? null`.
+ *
+ * @param key The query parameter name
+ * @param options Parsing, serialization and history
+ *   behaviour
+ * @returns A `[value, setValue]` tuple. `setValue`
+ *   accepts a value, an updater function, or `null`
+ *   to remove the param.
+ */
+
+// eslint-disable-next-line no-redeclare
+
+// eslint-disable-next-line no-redeclare
+
+// eslint-disable-next-line no-redeclare
+function useQueryState(key) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var parser = options.parser,
+    _options$serializer = options.serializer,
+    serializer = _options$serializer === void 0 ? String : _options$serializer,
+    defaultValue = options.defaultValue,
+    _options$history = options.history,
+    history = _options$history === void 0 ? 'replace' : _options$history;
+  var parse = function parse(raw) {
+    if (raw === null) {
+      return defaultValue !== null && defaultValue !== void 0 ? defaultValue : null;
+    }
+    return parser ? parser(raw) : raw;
+  };
+
+  // Reactive read. Next re-renders consumers when the
+  // URL changes (including our own history writes).
+  var searchParams = useSearchParams();
+  var value = parse(searchParams.get(key));
+  var set = useMemoizedFn(function (next) {
+    if (!isBrowser) {
+      return;
+    }
+    // Build from the live URL (not the captured
+    // `searchParams`) so consecutive writes in one
+    // tick see each other's result.
+    var params = new URLSearchParams(window.location.search);
+    var resolved = typeof next === 'function' ? next(parse(params.get(key))) : next;
+    if (resolved === null || resolved === undefined) {
+      params.delete(key);
+    } else {
+      params.set(key, serializer(resolved));
+    }
+    var search = params.toString();
+    var url = window.location.pathname + (search ? "?".concat(search) : '') + window.location.hash;
+    if (history === 'push') {
+      window.history.pushState(null, '', url);
+    } else {
+      window.history.replaceState(null, '', url);
+    }
+  });
+  return [value, set];
+}
+export default useQueryState;

package/lib/index.d.ts

@@ -9,3 +9,5 @@ export { default as useSyncState } from './useSyncState';
 export { default as useUpdateEffect } from './useUpdateEffect';
 export { default as useLayoutState, useTimeoutLock } from './useLayoutState';
 export type { Updater } from './useLayoutState';
+export { default as useQueryState, queryString, queryNumber, queryBoolean, queryJson, } from './useQueryState';
+export type { Parser, Serializer, QueryStateOptions, } from './useQueryState';

package/lib/index.js

@@ -29,6 +29,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  queryBoolean: () => import_useQueryState.queryBoolean,
+  queryJson: () => import_useQueryState.queryJson,
+  queryNumber: () => import_useQueryState.queryNumber,
+  queryString: () => import_useQueryState.queryString,
   useControlledState: () => import_useControlledState.default,
   useEventCallback: () => import_useEventCallback.default,
   useLatest: () => import_useLatest.default,
@@ -36,6 +40,7 @@ __export(index_exports, {
   useLayoutState: () => import_useLayoutState.default,
   useMemoizedFn: () => import_useMemoizedFn.default,
   usePrevious: () => import_usePrevious.default,
+  useQueryState: () => import_useQueryState.default,
   useSafeState: () => import_useSafeState.default,
   useSyncState: () => import_useSyncState.default,
   useTimeoutLock: () => import_useLayoutState.useTimeoutLock,
@@ -52,8 +57,13 @@ var import_useSafeState = __toESM(require("./useSafeState"));
 var import_useSyncState = __toESM(require("./useSyncState"));
 var import_useUpdateEffect = __toESM(require("./useUpdateEffect"));
 var import_useLayoutState = __toESM(require("./useLayoutState"));
+var import_useQueryState = __toESM(require("./useQueryState"));
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  queryBoolean,
+  queryJson,
+  queryNumber,
+  queryString,
   useControlledState,
   useEventCallback,
   useLatest,
@@ -61,6 +71,7 @@ var import_useLayoutState = __toESM(require("./useLayoutState"));
   useLayoutState,
   useMemoizedFn,
   usePrevious,
+  useQueryState,
   useSafeState,
   useSyncState,
   useTimeoutLock,

package/lib/useLatest/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 /**
  * A hook that returns a ref object whose `.current` property is always
  * updated to the latest value. Useful for accessing the latest value

package/lib/useQueryState/index.d.ts

@@ -0,0 +1,75 @@
+/** Turn a raw query string into a typed value. */
+export type Parser<T> = (value: string) => T;
+/** Turn a typed value back into a query string. */
+export type Serializer<T> = (value: T) => string;
+export interface QueryStateOptions<T> {
+    /**
+     * Parse the raw `string` read from the URL into `T`.
+     * Defaults to identity (the raw string).
+     */
+    parser?: Parser<T>;
+    /**
+     * Serialize `T` back into a `string` for the URL.
+     * Defaults to `String(value)`.
+     */
+    serializer?: Serializer<T>;
+    /**
+     * Value returned when the param is absent from
+     * the URL. When set, the hook never returns
+     * `null`.
+     */
+    defaultValue?: T;
+    /**
+     * How the URL is mutated:
+     * - `'replace'` (default) — `history.replaceState`,
+     *   does not add a history entry.
+     * - `'push'` — `history.pushState`, back/forward
+     *   navigates between values.
+     */
+    history?: 'push' | 'replace';
+}
+type SetQueryState<T> = (value: T | null | ((prev: T | null) => T | null)) => void;
+/** Identity parser used when none is supplied. */
+export declare const queryString: Parser<string>;
+/** Parse a numeric query param. `NaN` for non-numbers. */
+export declare const queryNumber: Parser<number>;
+/** Parse a boolean query param. Only `'true'` is true. */
+export declare const queryBoolean: Parser<boolean>;
+/** Parse a JSON-encoded query param. */
+export declare const queryJson: Parser<unknown>;
+/**
+ * Sync a piece of React state with a URL query
+ * parameter, so it survives refreshes and is
+ * shareable via the link.
+ *
+ * Reading is reactive via Next's `useSearchParams`;
+ * writing goes through the native
+ * `history.pushState/replaceState`, which the Next.js
+ * App Router intercepts and syncs back into
+ * `useSearchParams` *without* a server round-trip (no
+ * route re-render, no scroll-to-top). Because the
+ * value is reactive, using it as a SWR/React Query key
+ * makes dependent requests refetch automatically.
+ *
+ * Constraints (inherited from `useSearchParams`):
+ * - Next.js App Router only; the calling component
+ *   must be a Client Component (`'use client'`).
+ * - On statically rendered routes, wrap the consumer
+ *   in `<Suspense>`; otherwise that subtree opts into
+ *   client-side rendering. During prerender the param
+ *   reads as absent, so `value` falls back to
+ *   `defaultValue ?? null`.
+ *
+ * @param key The query parameter name
+ * @param options Parsing, serialization and history
+ *   behaviour
+ * @returns A `[value, setValue]` tuple. `setValue`
+ *   accepts a value, an updater function, or `null`
+ *   to remove the param.
+ */
+declare function useQueryState(key: string): [string | null, SetQueryState<string>];
+declare function useQueryState<T>(key: string, options: QueryStateOptions<T> & {
+    defaultValue: T;
+}): [T, SetQueryState<T>];
+declare function useQueryState<T>(key: string, options: QueryStateOptions<T>): [T | null, SetQueryState<T>];
+export default useQueryState;

package/lib/useQueryState/index.js

@@ -0,0 +1,94 @@
+"use client";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/useQueryState/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  queryBoolean: () => queryBoolean,
+  queryJson: () => queryJson,
+  queryNumber: () => queryNumber,
+  queryString: () => queryString
+});
+module.exports = __toCommonJS(index_exports);
+var import_navigation = require("next/navigation");
+var import_useMemoizedFn = __toESM(require("../useMemoizedFn"));
+var queryString = (value) => value;
+var queryNumber = (value) => Number(value);
+var queryBoolean = (value) => value === "true";
+var queryJson = (value) => JSON.parse(value);
+var isBrowser = typeof window !== "undefined";
+function useQueryState(key, options = {}) {
+  const {
+    parser,
+    serializer = String,
+    defaultValue,
+    history = "replace"
+  } = options;
+  const parse = (raw) => {
+    if (raw === null) {
+      return defaultValue ?? null;
+    }
+    return parser ? parser(raw) : raw;
+  };
+  const searchParams = (0, import_navigation.useSearchParams)();
+  const value = parse(searchParams.get(key));
+  const set = (0, import_useMemoizedFn.default)((next) => {
+    if (!isBrowser) {
+      return;
+    }
+    const params = new URLSearchParams(
+      window.location.search
+    );
+    const resolved = typeof next === "function" ? next(
+      parse(params.get(key))
+    ) : next;
+    if (resolved === null || resolved === void 0) {
+      params.delete(key);
+    } else {
+      params.set(key, serializer(resolved));
+    }
+    const search = params.toString();
+    const url = window.location.pathname + (search ? `?${search}` : "") + window.location.hash;
+    if (history === "push") {
+      window.history.pushState(null, "", url);
+    } else {
+      window.history.replaceState(null, "", url);
+    }
+  });
+  return [value, set];
+}
+var index_default = useQueryState;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  queryBoolean,
+  queryJson,
+  queryNumber,
+  queryString
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1money/hooks",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "React hooks for 1money front-end projects",
   "main": "lib/index.js",
   "module": "es/index.js",
@@ -41,6 +41,11 @@
       "import": "./es/useLayoutState/index.js",
       "require": "./lib/useLayoutState/index.js"
     },
+    "./useQueryState": {
+      "types": "./es/useQueryState/index.d.ts",
+      "import": "./es/useQueryState/index.js",
+      "require": "./lib/useQueryState/index.js"
+    },
     "./useMemoizedFn": {
       "types": "./es/useMemoizedFn/index.d.ts",
       "import": "./es/useMemoizedFn/index.js",
@@ -85,8 +90,14 @@
     "url": "https://github.com/1Money-Co/1money-hooks"
   },
   "peerDependencies": {
+    "next": ">=14.0.0",
     "react": ">=16.8.0"
   },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "license": "MIT",
   "devDependencies": {
     "@eslint/js": "^9.39.4",
@@ -103,6 +114,7 @@
     "father": "^4.6.17",
     "globals": "^15.15.0",
     "jsdom": "^29.0.2",
+    "next": "^14.2.0",
     "prettier": "~3.5.3",
     "react": "^19.1.0",
     "react-dom": "^19.2.4",