usehookify 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivek Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# usehookify
+
+[![npm version](https://img.shields.io/npm/v/usehookify.svg)](https://www.npmjs.com/package/usehookify)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/vivekKumarSinghH/usehook-js/blob/main/LICENSE)
+
+A small, dependency-free React hooks library you can install as an npm
+package or copy directly into your project via a CLI — same maintained
+source either way.
+
+## Hooks
+
+| Hook | Category | Description |
+|---|---|---|
+| `useLocalStorage` | storage | Persist React state to the browser's localStorage, synced across re-renders. |
+| `useFetch` | network | Fetch data from a URL with loading/error state and a manual refetch. |
+| `useDebounce` | utility | Return a debounced version of a rapidly-changing value. |
+| `useToggle` | state | Manage a boolean value with a toggle function and an explicit setter. |
+
+## Install
+
+```bash
+npm install usehookify
+```
+
+```ts
+import { useLocalStorage } from 'usehookify'
+```
+
+## Or copy it directly — same source, no dependency
+
+```bash
+npx usehookify add useDebounce
+```
+
+```ts
+import { useDebounce } from './hooks/useDebounce'
+```
+
+Both paths ship the exact same, byte-identical source.
+
+## CLI
+
+```bash
+npx usehookify list
+```
+
+## Documentation
+
+Full API reference, parameters, and usage examples:
+[github.com/vivekKumarSinghH/usehook-js](https://github.com/vivekKumarSinghH/usehook-js)
+
+## License
+
+MIT © Vivek Kumar

package/dist/cli/bin.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+
+// src/cli/bin.ts
+import { Command } from "commander";
+
+// src/registry/hooks.ts
+var hooks = [
+  {
+    id: "useLocalStorage",
+    name: "useLocalStorage",
+    description: "Persist React state to the browser's localStorage, synced across re-renders.",
+    category: "storage",
+    sourceFile: "useLocalStorage.ts",
+    params: [
+      { name: "key", type: "string", description: "The localStorage key to read/write.", required: true },
+      {
+        name: "initialValue",
+        type: "T",
+        description: "Value used when nothing is stored yet, or on the server during SSR.",
+        required: true
+      }
+    ],
+    returns: "[T, (value: T | ((prev: T) => T)) => void]",
+    examples: [
+      {
+        title: "Basic usage",
+        code: "const [name, setName] = useLocalStorage('name', 'Anonymous')\n\nsetName('Ada')\nsetName((prev) => prev.toUpperCase())"
+      }
+    ]
+  },
+  {
+    id: "useFetch",
+    name: "useFetch",
+    description: "Fetch data from a URL with loading/error state and a manual refetch.",
+    category: "network",
+    sourceFile: "useFetch.ts",
+    params: [
+      { name: "url", type: "string", description: "The URL to fetch.", required: true },
+      {
+        name: "options",
+        type: "RequestInit",
+        description: "Standard fetch options (headers, method, body, etc.).",
+        required: false
+      }
+    ],
+    returns: "{ data: T | null, error: Error | null, loading: boolean, refetch: () => void }",
+    examples: [
+      {
+        title: "Basic usage",
+        code: "const { data, error, loading, refetch } = useFetch<Post[]>('/api/posts')\n\nif (loading) return <Spinner />\nif (error) return <ErrorBanner message={error.message} onRetry={refetch} />\nreturn <PostList posts={data} />"
+      }
+    ]
+  },
+  {
+    id: "useDebounce",
+    name: "useDebounce",
+    description: "Return a debounced version of a rapidly-changing value.",
+    category: "utility",
+    sourceFile: "useDebounce.ts",
+    params: [
+      { name: "value", type: "T", description: "The value to debounce.", required: true },
+      { name: "delayMs", type: "number", description: "Delay in milliseconds.", required: true }
+    ],
+    returns: "T",
+    examples: [
+      {
+        title: "Debounced search input",
+        code: "const [query, setQuery] = useState('')\nconst debouncedQuery = useDebounce(query, 300)\n\n// debouncedQuery only updates 300ms after the user stops typing"
+      }
+    ]
+  },
+  {
+    id: "useToggle",
+    name: "useToggle",
+    description: "Manage a boolean value with a toggle function and an explicit setter.",
+    category: "state",
+    sourceFile: "useToggle.ts",
+    params: [
+      {
+        name: "initial",
+        type: "boolean",
+        description: "Starting value. Defaults to false.",
+        required: false
+      }
+    ],
+    returns: "[boolean, () => void, (value: boolean) => void]",
+    examples: [
+      {
+        title: "Modal open/close state",
+        code: 'const [isOpen, toggleOpen, setOpen] = useToggle(false)\n\n// flip on button click:\ntoggleOpen()\n\n// force closed, e.g. from an "X" button \u2014 never toggles back open:\nsetOpen(false)'
+      }
+    ]
+  }
+];
+
+// src/cli/commands/list.ts
+function printHookList(hookList = hooks) {
+  if (hookList.length === 0) {
+    console.log("No hooks available yet.");
+    return;
+  }
+  for (const hook of hookList) {
+    console.log(`${hook.id}	${hook.name}	${hook.category}	${hook.description}`);
+  }
+}
+function registerListCommand(program2) {
+  program2.command("list").description("List every hook available in usehookify").action(() => printHookList());
+}
+
+// src/cli/commands/add.ts
+import path2 from "path";
+
+// src/infra/fileWriter.ts
+import { existsSync, mkdirSync, copyFileSync } from "fs";
+import { fileURLToPath } from "url";
+import path from "path";
+
+// src/cli/errors.ts
+var InvalidHookIdError = class extends Error {
+  constructor(hookId, validIds) {
+    super(`Unknown hook "${hookId}". Valid hooks: ${validIds.join(", ")}`);
+    this.hookId = hookId;
+    this.validIds = validIds;
+  }
+};
+var TargetExistsError = class extends Error {
+  constructor(path3) {
+    super(`"${path3}" already exists. Re-run with --force to overwrite.`);
+    this.path = path3;
+  }
+};
+
+// src/infra/fileWriter.ts
+function getHooksSourceDir() {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+  return path.join(packageRoot, "src", "hooks");
+}
+function writeHookFile(sourceFile, targetDir, options = {}) {
+  const sourcePath = path.join(getHooksSourceDir(), sourceFile);
+  const destPath = path.join(targetDir, sourceFile);
+  if (existsSync(destPath) && !options.force) {
+    throw new TargetExistsError(destPath);
+  }
+  mkdirSync(targetDir, { recursive: true });
+  copyFileSync(sourcePath, destPath);
+  return destPath;
+}
+
+// src/cli/commands/add.ts
+function resolveHook(hookId, hookList = hooks) {
+  const hook = hookList.find((h) => h.id === hookId);
+  if (!hook) {
+    throw new InvalidHookIdError(
+      hookId,
+      hookList.map((h) => h.id)
+    );
+  }
+  return hook;
+}
+function runAdd(hookId, options) {
+  const hook = resolveHook(hookId);
+  const targetDir = options.path ?? "./hooks";
+  const writtenPath = writeHookFile(hook.sourceFile, targetDir, { force: options.force });
+  const relativeFromCwd = path2.relative(process.cwd(), path2.resolve(targetDir));
+  const normalizedDir = relativeFromCwd.split(path2.sep).join("/");
+  const importDir = normalizedDir.startsWith(".") ? normalizedDir : `./${normalizedDir}`;
+  const importLine = `import { ${hook.name} } from '${importDir}/${hookId}'`;
+  return { writtenPath, importLine };
+}
+function registerAddCommand(program2) {
+  program2.command("add <hookId>").description("Copy a hook's source file into your project").option("-p, --path <dir>", "Directory to copy the hook into", "./hooks").option("-f, --force", "Overwrite the target file if it already exists", false).action((hookId, options) => {
+    try {
+      const { writtenPath, importLine } = runAdd(hookId, options);
+      console.log(`Copied to ${writtenPath}`);
+      console.log(`Add this import: ${importLine}`);
+    } catch (err) {
+      if (err instanceof InvalidHookIdError || err instanceof TargetExistsError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+        return;
+      }
+      throw err;
+    }
+  });
+}
+
+// src/cli/bin.ts
+var program = new Command();
+program.name("usehookify").description("usehookify CLI \u2014 list and copy React hooks").version("1.0.0");
+registerListCommand(program);
+registerAddCommand(program);
+program.parse(process.argv);

package/dist/index.cjs

@@ -0,0 +1,132 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  useDebounce: () => useDebounce,
+  useFetch: () => useFetch,
+  useLocalStorage: () => useLocalStorage,
+  useToggle: () => useToggle
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/hooks/useLocalStorage.ts
+var import_react = require("react");
+function readValue(key, initialValue) {
+  if (typeof window === "undefined") return initialValue;
+  try {
+    const stored = window.localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  } catch {
+    return initialValue;
+  }
+}
+function writeValue(key, value) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function useLocalStorage(key, initialValue) {
+  const [storedValue, setStoredValue] = (0, import_react.useState)(() => readValue(key, initialValue));
+  const setValue = (0, import_react.useCallback)(
+    (value) => {
+      setStoredValue((prev) => {
+        const next = value instanceof Function ? value(prev) : value;
+        writeValue(key, next);
+        return next;
+      });
+    },
+    [key]
+  );
+  return [storedValue, setValue];
+}
+
+// src/hooks/useFetch.ts
+var import_react2 = require("react");
+function useFetch(url, options) {
+  const [data, setData] = (0, import_react2.useState)(null);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const [loading, setLoading] = (0, import_react2.useState)(true);
+  const [version, setVersion] = (0, import_react2.useState)(0);
+  const mountedRef = (0, import_react2.useRef)(true);
+  (0, import_react2.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  (0, import_react2.useEffect)(() => {
+    setLoading(true);
+    setError(null);
+    fetch(url, options).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(`Request failed with status ${response.status}`);
+      }
+      return await response.json();
+    }).then((result) => {
+      if (!mountedRef.current) return;
+      setData(result);
+      setLoading(false);
+    }).catch((err) => {
+      if (!mountedRef.current) return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setLoading(false);
+    });
+  }, [url, version]);
+  const refetch = (0, import_react2.useCallback)(() => {
+    setVersion((v) => v + 1);
+  }, []);
+  return { data, error, loading, refetch };
+}
+
+// src/hooks/useDebounce.ts
+var import_react3 = require("react");
+function useDebounce(value, delayMs) {
+  const [debouncedValue, setDebouncedValue] = (0, import_react3.useState)(value);
+  (0, import_react3.useEffect)(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+  return debouncedValue;
+}
+
+// src/hooks/useToggle.ts
+var import_react4 = require("react");
+function useToggle(initial = false) {
+  const [value, setValue] = (0, import_react4.useState)(initial);
+  const toggle = (0, import_react4.useCallback)(() => {
+    setValue((prev) => !prev);
+  }, []);
+  const setExplicit = (0, import_react4.useCallback)((next) => {
+    setValue(next);
+  }, []);
+  return [value, toggle, setExplicit];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useDebounce,
+  useFetch,
+  useLocalStorage,
+  useToggle
+});

package/dist/index.d.cts

@@ -0,0 +1,16 @@
+type SetValue<T> = T | ((prev: T) => T);
+declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: SetValue<T>) => void];
+
+interface UseFetchResult<T> {
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+    refetch: () => void;
+}
+declare function useFetch<T>(url: string, options?: RequestInit): UseFetchResult<T>;
+
+declare function useDebounce<T>(value: T, delayMs: number): T;
+
+declare function useToggle(initial?: boolean): [boolean, () => void, (value: boolean) => void];
+
+export { useDebounce, useFetch, useLocalStorage, useToggle };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+type SetValue<T> = T | ((prev: T) => T);
+declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: SetValue<T>) => void];
+
+interface UseFetchResult<T> {
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+    refetch: () => void;
+}
+declare function useFetch<T>(url: string, options?: RequestInit): UseFetchResult<T>;
+
+declare function useDebounce<T>(value: T, delayMs: number): T;
+
+declare function useToggle(initial?: boolean): [boolean, () => void, (value: boolean) => void];
+
+export { useDebounce, useFetch, useLocalStorage, useToggle };

package/dist/index.js

@@ -0,0 +1,102 @@
+// src/hooks/useLocalStorage.ts
+import { useCallback, useState } from "react";
+function readValue(key, initialValue) {
+  if (typeof window === "undefined") return initialValue;
+  try {
+    const stored = window.localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  } catch {
+    return initialValue;
+  }
+}
+function writeValue(key, value) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function useLocalStorage(key, initialValue) {
+  const [storedValue, setStoredValue] = useState(() => readValue(key, initialValue));
+  const setValue = useCallback(
+    (value) => {
+      setStoredValue((prev) => {
+        const next = value instanceof Function ? value(prev) : value;
+        writeValue(key, next);
+        return next;
+      });
+    },
+    [key]
+  );
+  return [storedValue, setValue];
+}
+
+// src/hooks/useFetch.ts
+import { useCallback as useCallback2, useEffect, useRef, useState as useState2 } from "react";
+function useFetch(url, options) {
+  const [data, setData] = useState2(null);
+  const [error, setError] = useState2(null);
+  const [loading, setLoading] = useState2(true);
+  const [version, setVersion] = useState2(0);
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  useEffect(() => {
+    setLoading(true);
+    setError(null);
+    fetch(url, options).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(`Request failed with status ${response.status}`);
+      }
+      return await response.json();
+    }).then((result) => {
+      if (!mountedRef.current) return;
+      setData(result);
+      setLoading(false);
+    }).catch((err) => {
+      if (!mountedRef.current) return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setLoading(false);
+    });
+  }, [url, version]);
+  const refetch = useCallback2(() => {
+    setVersion((v) => v + 1);
+  }, []);
+  return { data, error, loading, refetch };
+}
+
+// src/hooks/useDebounce.ts
+import { useEffect as useEffect2, useState as useState3 } from "react";
+function useDebounce(value, delayMs) {
+  const [debouncedValue, setDebouncedValue] = useState3(value);
+  useEffect2(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+  return debouncedValue;
+}
+
+// src/hooks/useToggle.ts
+import { useCallback as useCallback3, useState as useState4 } from "react";
+function useToggle(initial = false) {
+  const [value, setValue] = useState4(initial);
+  const toggle = useCallback3(() => {
+    setValue((prev) => !prev);
+  }, []);
+  const setExplicit = useCallback3((next) => {
+    setValue(next);
+  }, []);
+  return [value, toggle, setExplicit];
+}
+export {
+  useDebounce,
+  useFetch,
+  useLocalStorage,
+  useToggle
+};

package/dist/registry/index.d.ts

@@ -0,0 +1,24 @@
+interface Param {
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+}
+interface Example {
+    title: string;
+    code: string;
+}
+interface HookMetadata {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    sourceFile: string;
+    params: Param[];
+    returns: string;
+    examples: Example[];
+}
+
+declare const hooks: HookMetadata[];
+
+export { type Example, type HookMetadata, type Param, hooks };

package/dist/registry/index.js

@@ -0,0 +1,92 @@
+// src/registry/hooks.ts
+var hooks = [
+  {
+    id: "useLocalStorage",
+    name: "useLocalStorage",
+    description: "Persist React state to the browser's localStorage, synced across re-renders.",
+    category: "storage",
+    sourceFile: "useLocalStorage.ts",
+    params: [
+      { name: "key", type: "string", description: "The localStorage key to read/write.", required: true },
+      {
+        name: "initialValue",
+        type: "T",
+        description: "Value used when nothing is stored yet, or on the server during SSR.",
+        required: true
+      }
+    ],
+    returns: "[T, (value: T | ((prev: T) => T)) => void]",
+    examples: [
+      {
+        title: "Basic usage",
+        code: "const [name, setName] = useLocalStorage('name', 'Anonymous')\n\nsetName('Ada')\nsetName((prev) => prev.toUpperCase())"
+      }
+    ]
+  },
+  {
+    id: "useFetch",
+    name: "useFetch",
+    description: "Fetch data from a URL with loading/error state and a manual refetch.",
+    category: "network",
+    sourceFile: "useFetch.ts",
+    params: [
+      { name: "url", type: "string", description: "The URL to fetch.", required: true },
+      {
+        name: "options",
+        type: "RequestInit",
+        description: "Standard fetch options (headers, method, body, etc.).",
+        required: false
+      }
+    ],
+    returns: "{ data: T | null, error: Error | null, loading: boolean, refetch: () => void }",
+    examples: [
+      {
+        title: "Basic usage",
+        code: "const { data, error, loading, refetch } = useFetch<Post[]>('/api/posts')\n\nif (loading) return <Spinner />\nif (error) return <ErrorBanner message={error.message} onRetry={refetch} />\nreturn <PostList posts={data} />"
+      }
+    ]
+  },
+  {
+    id: "useDebounce",
+    name: "useDebounce",
+    description: "Return a debounced version of a rapidly-changing value.",
+    category: "utility",
+    sourceFile: "useDebounce.ts",
+    params: [
+      { name: "value", type: "T", description: "The value to debounce.", required: true },
+      { name: "delayMs", type: "number", description: "Delay in milliseconds.", required: true }
+    ],
+    returns: "T",
+    examples: [
+      {
+        title: "Debounced search input",
+        code: "const [query, setQuery] = useState('')\nconst debouncedQuery = useDebounce(query, 300)\n\n// debouncedQuery only updates 300ms after the user stops typing"
+      }
+    ]
+  },
+  {
+    id: "useToggle",
+    name: "useToggle",
+    description: "Manage a boolean value with a toggle function and an explicit setter.",
+    category: "state",
+    sourceFile: "useToggle.ts",
+    params: [
+      {
+        name: "initial",
+        type: "boolean",
+        description: "Starting value. Defaults to false.",
+        required: false
+      }
+    ],
+    returns: "[boolean, () => void, (value: boolean) => void]",
+    examples: [
+      {
+        title: "Modal open/close state",
+        code: 'const [isOpen, toggleOpen, setOpen] = useToggle(false)\n\n// flip on button click:\ntoggleOpen()\n\n// force closed, e.g. from an "X" button \u2014 never toggles back open:\nsetOpen(false)'
+      }
+    ]
+  }
+];
+export {
+  hooks
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "usehookify",
+  "version": "1.0.0",
+  "description": "A small, dependency-free React hooks library — install as a package or copy via CLI, same source either way.",
+  "license": "MIT",
+  "author": "Vivek Kumar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vivekKumarSinghH/usehook-js.git",
+    "directory": "packages/usehook-js"
+  },
+  "keywords": ["react", "hooks", "react-hooks", "typescript", "cli"],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "default": "./dist/registry/index.js"
+    }
+  },
+  "files": ["dist", "src/hooks"],
+  "bin": {
+    "usehookify": "./dist/cli/bin.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings=0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "vitest": "^2.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "jsdom": "^25.0.0",
+    "@testing-library/react": "^16.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@types/react": "^18.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/hooks/useDebounce.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useDebounce } from './useDebounce'
+
+describe('useDebounce', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('returns the initial value immediately', () => {
+    const { result } = renderHook(() => useDebounce('a', 300))
+    expect(result.current).toBe('a')
+  })
+
+  it('returns the latest value only after the delay elapses', () => {
+    vi.useFakeTimers()
+    const { result, rerender } = renderHook(({ value }) => useDebounce(value, 300), {
+      initialProps: { value: 'a' },
+    })
+    rerender({ value: 'b' })
+    act(() => vi.advanceTimersByTime(299))
+    expect(result.current).toBe('a') // not yet
+    act(() => vi.advanceTimersByTime(1))
+    expect(result.current).toBe('b')
+  })
+
+  it('only keeps the last value when changed rapidly within the delay window', () => {
+    vi.useFakeTimers()
+    const { result, rerender } = renderHook(({ value }) => useDebounce(value, 300), {
+      initialProps: { value: 'a' },
+    })
+    rerender({ value: 'b' })
+    act(() => vi.advanceTimersByTime(150))
+    rerender({ value: 'c' }) // resets the timer before 'b' ever fires
+    act(() => vi.advanceTimersByTime(150))
+    expect(result.current).toBe('a') // still not settled — only 150ms since 'c'
+    act(() => vi.advanceTimersByTime(150))
+    expect(result.current).toBe('c') // 'b' was skipped entirely
+  })
+
+  it('does not update after unmounting mid-delay', () => {
+    vi.useFakeTimers()
+    const { unmount } = renderHook(({ value }) => useDebounce(value, 300), {
+      initialProps: { value: 'a' },
+    })
+    unmount()
+    expect(() => act(() => vi.advanceTimersByTime(300))).not.toThrow()
+  })
+})

package/src/hooks/useDebounce.ts

@@ -0,0 +1,17 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+export function useDebounce<T>(value: T, delayMs: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value)
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value)
+    }, delayMs)
+
+    return () => clearTimeout(timer)
+  }, [value, delayMs])
+
+  return debouncedValue
+}

package/src/hooks/useFetch.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { renderHook, waitFor, act } from '@testing-library/react'
+import { useFetch } from './useFetch'
+
+describe('useFetch', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('starts in a loading state with no data or error', () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => new Promise(() => {})) // never resolves — hold in loading
+    )
+    const { result } = renderHook(() => useFetch('/api/thing'))
+    expect(result.current).toMatchObject({ data: null, error: null, loading: true })
+  })
+
+  it('returns parsed data on a successful response', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() =>
+        Promise.resolve({ ok: true, json: () => Promise.resolve({ id: 1 }) } as Response)
+      )
+    )
+    const { result } = renderHook(() => useFetch<{ id: number }>('/api/thing'))
+    await waitFor(() => expect(result.current.loading).toBe(false))
+    expect(result.current.data).toEqual({ id: 1 })
+    expect(result.current.error).toBeNull()
+  })
+
+  it('surfaces a non-OK response as an error, never throwing', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.resolve({ ok: false, status: 404 } as Response))
+    )
+    const { result } = renderHook(() => useFetch('/api/missing'))
+    await waitFor(() => expect(result.current.loading).toBe(false))
+    expect(result.current.data).toBeNull()
+    expect(result.current.error).toBeInstanceOf(Error)
+  })
+
+  it('surfaces a rejected fetch as an error, never throwing', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(() => Promise.reject(new Error('network down')))
+    )
+    const { result } = renderHook(() => useFetch('/api/thing'))
+    await waitFor(() => expect(result.current.loading).toBe(false))
+    expect(result.current.error?.message).toBe('network down')
+  })
+
+  it('refetch() re-triggers the request and resets loading first', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({ n: 1 }) } as Response)
+      .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({ n: 2 }) } as Response)
+    vi.stubGlobal('fetch', fetchMock)
+
+    const { result } = renderHook(() => useFetch<{ n: number }>('/api/thing'))
+    await waitFor(() => expect(result.current.data).toEqual({ n: 1 }))
+
+    act(() => {
+      result.current.refetch()
+    })
+    // act() flushes the synchronous setLoading(true) before the mocked
+    // fetch's microtask resolves, so this is safe to assert immediately
+    // rather than via waitFor (which could miss a transient state that
+    // resolves within the same tick).
+    expect(result.current.loading).toBe(true)
+    await waitFor(() => expect(result.current.data).toEqual({ n: 2 }))
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not update state after unmounting mid-flight', async () => {
+    let resolveFetch: (value: Response) => void = () => {}
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        () =>
+          new Promise<Response>((resolve) => {
+            resolveFetch = resolve
+          })
+      )
+    )
+    const { unmount } = renderHook(() => useFetch('/api/thing'))
+    unmount()
+    resolveFetch({ ok: true, json: () => Promise.resolve({}) } as Response)
+    // If the hook updated state on an unmounted component, React would log
+    // an error/warning — asserting no throw here is the meaningful check.
+    await new Promise((r) => setTimeout(r, 0))
+  })
+})

package/src/hooks/useFetch.ts

@@ -0,0 +1,54 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export interface UseFetchResult<T> {
+  data: T | null
+  error: Error | null
+  loading: boolean
+  refetch: () => void
+}
+
+export function useFetch<T>(url: string, options?: RequestInit): UseFetchResult<T> {
+  const [data, setData] = useState<T | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [version, setVersion] = useState(0)
+  const mountedRef = useRef(true)
+
+  useEffect(() => {
+    mountedRef.current = true
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  useEffect(() => {
+    setLoading(true)
+    setError(null)
+
+    fetch(url, options)
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error(`Request failed with status ${response.status}`)
+        }
+        return (await response.json()) as T
+      })
+      .then((result) => {
+        if (!mountedRef.current) return
+        setData(result)
+        setLoading(false)
+      })
+      .catch((err: unknown) => {
+        if (!mountedRef.current) return
+        setError(err instanceof Error ? err : new Error(String(err)))
+        setLoading(false)
+      })
+  }, [url, version])
+
+  const refetch = useCallback(() => {
+    setVersion((v) => v + 1)
+  }, [])
+
+  return { data, error, loading, refetch }
+}

package/src/hooks/useLocalStorage.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useLocalStorage, readValue, writeValue } from './useLocalStorage'
+
+describe('useLocalStorage', () => {
+  beforeEach(() => {
+    window.localStorage.clear()
+  })
+
+  it('returns the initial value when nothing is stored yet', () => {
+    const { result } = renderHook(() => useLocalStorage('count', 0))
+    expect(result.current[0]).toBe(0)
+  })
+
+  it('reads an existing value from localStorage on mount', () => {
+    window.localStorage.setItem('count', JSON.stringify(42))
+    const { result } = renderHook(() => useLocalStorage('count', 0))
+    expect(result.current[0]).toBe(42)
+  })
+
+  it('falls back to the initial value when stored JSON is corrupted', () => {
+    window.localStorage.setItem('count', '{not valid json')
+    const { result } = renderHook(() => useLocalStorage('count', 0))
+    expect(result.current[0]).toBe(0)
+  })
+
+  it('updates state and persists when called with a direct value', () => {
+    const { result } = renderHook(() => useLocalStorage('count', 0))
+    act(() => {
+      result.current[1](5)
+    })
+    expect(result.current[0]).toBe(5)
+    expect(window.localStorage.getItem('count')).toBe('5')
+  })
+
+  it('updates state based on the previous value when called with an updater function', () => {
+    const { result } = renderHook(() => useLocalStorage('count', 0))
+    act(() => {
+      result.current[1]((prev) => prev + 1)
+    })
+    act(() => {
+      result.current[1]((prev) => prev + 1)
+    })
+    expect(result.current[0]).toBe(2)
+    expect(window.localStorage.getItem('count')).toBe('2')
+  })
+
+  it('re-reads the persisted value on a fresh mount (round-trip)', () => {
+    const first = renderHook(() => useLocalStorage('count', 0))
+    act(() => {
+      first.result.current[1](7)
+    })
+    first.unmount()
+    const second = renderHook(() => useLocalStorage('count', 0))
+    expect(second.result.current[0]).toBe(7)
+  })
+
+  it('keeps state correct even if persisting throws (e.g. quota exceeded)', () => {
+    const setItemSpy = vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new DOMException('QuotaExceededError')
+    })
+    const { result } = renderHook(() => useLocalStorage('count', 0))
+    act(() => {
+      result.current[1](9)
+    })
+    expect(result.current[0]).toBe(9)
+    setItemSpy.mockRestore()
+  })
+
+  describe("readValue (SSR guard, tested directly — avoids fighting jsdom's global window)", () => {
+    afterEach(() => {
+      vi.unstubAllGlobals()
+    })
+
+    it('returns the initial value when window is undefined', () => {
+      vi.stubGlobal('window', undefined)
+      expect(readValue('count', 7)).toBe(7)
+    })
+  })
+
+  describe('writeValue (SSR guard, tested directly)', () => {
+    afterEach(() => {
+      vi.unstubAllGlobals()
+    })
+
+    it('is a no-op when window is undefined — never throws', () => {
+      vi.stubGlobal('window', undefined)
+      expect(() => writeValue('count', 1)).not.toThrow()
+    })
+  })
+})

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,47 @@
+'use client'
+
+import { useCallback, useState } from 'react'
+
+export type SetValue<T> = T | ((prev: T) => T)
+
+export function readValue<T>(key: string, initialValue: T): T {
+  if (typeof window === 'undefined') return initialValue // SSR guard
+  try {
+    const stored = window.localStorage.getItem(key)
+    return stored ? (JSON.parse(stored) as T) : initialValue
+  } catch {
+    return initialValue // corrupt/foreign data in that key must not crash the caller
+  }
+}
+
+export function writeValue<T>(key: string, value: T): void {
+  if (typeof window === 'undefined') return // SSR guard — no-op if ever called server-side
+  try {
+    window.localStorage.setItem(key, JSON.stringify(value))
+  } catch {
+    // Quota exceeded, storage disabled, or a serialization error — in-memory
+    // state already updated by the caller; only persistence silently fails,
+    // matching this hook's contract of never throwing into the caller's
+    // render/update path.
+  }
+}
+
+export function useLocalStorage<T>(
+  key: string,
+  initialValue: T
+): [T, (value: SetValue<T>) => void] {
+  const [storedValue, setStoredValue] = useState<T>(() => readValue(key, initialValue))
+
+  const setValue = useCallback(
+    (value: SetValue<T>) => {
+      setStoredValue((prev) => {
+        const next = value instanceof Function ? value(prev) : value
+        writeValue(key, next)
+        return next
+      })
+    },
+    [key]
+  )
+
+  return [storedValue, setValue]
+}

package/src/hooks/useToggle.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useToggle } from './useToggle'
+
+describe('useToggle', () => {
+  it('defaults to false when no initial value is given', () => {
+    const { result } = renderHook(() => useToggle())
+    expect(result.current[0]).toBe(false)
+  })
+
+  it('starts at the given initial value', () => {
+    const { result } = renderHook(() => useToggle(true))
+    expect(result.current[0]).toBe(true)
+  })
+
+  it('flips the value when toggle is called', () => {
+    const { result } = renderHook(() => useToggle(false))
+    act(() => result.current[1]())
+    expect(result.current[0]).toBe(true)
+    act(() => result.current[1]())
+    expect(result.current[0]).toBe(false)
+  })
+
+  it('sets an explicit value regardless of the current value', () => {
+    const { result } = renderHook(() => useToggle(false))
+    act(() => result.current[2](true))
+    expect(result.current[0]).toBe(true)
+    act(() => result.current[2](true))
+    expect(result.current[0]).toBe(true)
+    act(() => result.current[2](false))
+    expect(result.current[0]).toBe(false)
+  })
+
+  it('keeps toggle and setValue referentially stable across re-renders', () => {
+    const { result, rerender } = renderHook(() => useToggle())
+    const [, firstToggle, firstSetValue] = result.current
+    rerender()
+    const [, secondToggle, secondSetValue] = result.current
+    expect(secondToggle).toBe(firstToggle)
+    expect(secondSetValue).toBe(firstSetValue)
+  })
+})

package/src/hooks/useToggle.ts

@@ -0,0 +1,17 @@
+'use client'
+
+import { useCallback, useState } from 'react'
+
+export function useToggle(initial = false): [boolean, () => void, (value: boolean) => void] {
+  const [value, setValue] = useState(initial)
+
+  const toggle = useCallback(() => {
+    setValue((prev) => !prev)
+  }, [])
+
+  const setExplicit = useCallback((next: boolean) => {
+    setValue(next)
+  }, [])
+
+  return [value, toggle, setExplicit]
+}