use-good-hooks 1.0.0

package/README.md

@@ -0,0 +1,343 @@
+# 🪝 use-good-hooks
+
+![React](https://img.shields.io/badge/React-19.0.0+-61DAFB?style=flat-square&logo=react&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178C6?style=flat-square&logo=typescript&logoColor=white)
+![Vite](https://img.shields.io/badge/Vite-6.2.0+-646CFF?style=flat-square&logo=vite&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
+[![Vitest](https://img.shields.io/badge/-Vitest-729B1B?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/)
+
+A collection of well-tested, performance-optimized React hooks for common web application patterns. These hooks help manage state, UI interactions, and browser features with clean, reusable abstractions.
+
+## 📦 Installation
+
+```bash
+# Using npm
+npm install use-good-hooks
+
+# Using yarn
+yarn add use-good-hooks
+
+# Using pnpm
+pnpm add use-good-hooks
+```
+
+## 🔌 Requirements
+
+- React 19.0.0+
+- Lodash 4.17.21+
+
+## 🧰 Available Hooks
+
+### `useDebounce`
+
+Debounces value changes to prevent rapid updates. Useful for search inputs, form validation, and other scenarios where you want to delay state updates until after a user has stopped changing the input.
+
+```typescript
+import { useDebounce } from 'use-good-hooks';
+
+function SearchComponent() {
+  const [searchTerm, setSearchTerm] = useState('');
+  const debouncedSearchTerm = useDebounce(searchTerm, 500); // 500ms delay
+
+  // API call will only happen 500ms after the user stops typing
+  useEffect(() => {
+    if (debouncedSearchTerm) {
+      searchAPI(debouncedSearchTerm);
+    }
+  }, [debouncedSearchTerm]);
+
+  return (
+    <input
+      type="text"
+      value={searchTerm}
+      onChange={(e) => setSearchTerm(e.target.value)}
+      placeholder="Search..."
+    />
+  );
+}
+```
+
+#### Parameters
+
+- `value`: The value to debounce
+- `delay`: (Optional) The delay in milliseconds (default: 300ms)
+
+#### Returns
+
+- The debounced value
+
+### `useThrottle`
+
+Limits the rate at which a value can update. Useful for scroll events, window resizing, and other high-frequency events.
+
+```typescript
+import { useThrottle } from 'use-good-hooks';
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0);
+  const throttledScrollY = useThrottle(scrollY, 200); // 200ms throttle
+
+  useEffect(() => {
+    const handleScroll = () => {
+      setScrollY(window.scrollY);
+    };
+
+    window.addEventListener('scroll', handleScroll);
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, []);
+
+  return <div>Throttled scroll position: {throttledScrollY}px</div>;
+}
+```
+
+#### Parameters
+
+- `value`: The value to throttle
+- `delay`: (Optional) The throttle interval in milliseconds (default: 300ms)
+
+#### Returns
+
+- The throttled value
+
+### `usePrev`
+
+Captures the previous value of a state or prop. Useful for comparing changes between renders.
+
+```typescript
+import { usePrev } from 'use-good-hooks';
+
+function Counter({ count }) {
+  const prevCount = usePrev(count);
+
+  return (
+    <div>
+      <p>Current count: {count}</p>
+      <p>Previous count: {prevCount ?? 'None'}</p>
+      <p>Direction: {count > prevCount ? 'Increasing' : count < prevCount ? 'Decreasing' : 'No change'}</p>
+    </div>
+  );
+}
+```
+
+#### Parameters
+
+- `value`: The value to track
+
+#### Returns
+
+- The previous value (undefined on first render)
+
+### `useDistinct`
+
+Detects distinct changes in values with support for deep comparison and custom equality checks. Useful for tracking whether complex objects have actually changed.
+
+```typescript
+import { useDistinct } from 'use-good-hooks';
+
+function UserProfileForm({ user }) {
+  const { distinct, value, prevValue } = useDistinct(user, { deep: true });
+
+  useEffect(() => {
+    if (distinct) {
+      console.log('User data changed from:', prevValue, 'to:', value);
+      // Perhaps save to backend or update UI
+    }
+  }, [distinct, prevValue, value]);
+
+  return (
+    <div>
+      <h2>Editing profile for: {user.name}</h2>
+      {distinct && <div className="alert">Unsaved changes!</div>}
+      {/* Form inputs */}
+    </div>
+  );
+}
+```
+
+#### Parameters
+
+- `inputValue`: The value to check for changes
+- `options`: (Optional) Configuration options:
+    - `deep`: Boolean to enable deep equality comparison (default: false)
+    - `compare`: Custom comparison function (a, b) => boolean
+    - `debounce`: Debounce time in milliseconds (default: 0)
+
+#### Returns
+
+- Object with:
+    - `distinct`: Boolean indicating if the value changed
+    - `prevValue`: The previous distinct value
+    - `value`: The current value
+
+### `useStorageState`
+
+Persists state to localStorage or sessionStorage with automatic serialization/deserialization.
+
+```typescript
+import { useStorageState } from 'use-good-hooks';
+
+function ThemePreferences() {
+  const [preferences, setPreferences, { removeKey }] = useStorageState('theme-prefs', {
+    darkMode: false,
+    fontSize: 'medium',
+    compactView: true
+  });
+
+  return (
+    <div>
+      <h2>Theme Settings</h2>
+      <label>
+        <input
+          type="checkbox"
+          checked={preferences.darkMode}
+          onChange={() => setPreferences({...preferences, darkMode: !preferences.darkMode})}
+        />
+        Dark Mode
+      </label>
+      {/* More settings */}
+      <button onClick={removeKey}>Reset to Defaults</button>
+    </div>
+  );
+}
+```
+
+#### Parameters
+
+- `key`: Storage key name
+- `initialState`: Default state if no stored value exists
+- `options`: (Optional) Configuration options:
+    - `storage`: 'local' or 'session' (default: 'local')
+    - `debounce`: Debounce time in milliseconds (default: 500)
+    - `onError`: Error callback function
+    - `omitKeys`: Array of keys to omit from storage or function (value, key) => boolean
+    - `pickKeys`: Array of keys to include in storage or function (value, key) => boolean
+
+#### Returns
+
+- Array with:
+    - State value
+    - State setter function
+    - Object with utility functions:
+        - `removeKey`: Function to clear the storage key
+
+### `useUrlState`
+
+Synchronizes state with URL query parameters. Great for shareable UI states, filters, pagination, and search terms.
+
+```typescript
+import { useUrlState } from 'use-good-hooks';
+
+function ProductFilter() {
+  const [filters, setFilters] = useUrlState({
+    category: '',
+    minPrice: 0,
+    maxPrice: 1000,
+    sortBy: 'newest'
+  }, {
+    url: new URL(window.location.href),
+    kebabCase: true,
+    omitValues: ['', 0]
+  });
+
+  return (
+    <div>
+      <select
+        value={filters.category}
+        onChange={(e) => setFilters({...filters, category: e.target.value})}
+      >
+        <option value="">All Categories</option>
+        <option value="electronics">Electronics</option>
+        <option value="clothing">Clothing</option>
+      </select>
+      {/* More filter controls */}
+    </div>
+  );
+}
+```
+
+#### Parameters
+
+- `initialState`: Default state if URL has no parameters
+- `options`: Configuration options:
+    - `url`: URL object to use (required)
+    - `debounce`: Debounce time in milliseconds (default: 500)
+    - `kebabCase`: Convert camelCase keys to kebab-case in URL (default: true)
+    - `prefix`: Optional prefix for URL parameters
+    - `onError`: Error callback function
+    - `omitKeys`: Array of keys to omit from URL or function (value, key) => boolean
+    - `pickKeys`: Array of keys to include in URL or function (value, key) => boolean
+    - `omitValues`: Array of values to omit from URL or function (value, key) => boolean
+
+#### Returns
+
+- Array with:
+    - State value
+    - State setter function
+
+## 🧪 Running Tests
+
+This library is thoroughly tested with Vitest and React Testing Library. To run the tests:
+
+```bash
+# Using npm
+npm test
+
+# Using yarn
+yarn test
+
+# Using pnpm
+pnpm test
+```
+
+## 🔄 How hooks update and optimize performance
+
+Each hook in this library is designed with performance in mind:
+
+1. `useDebounce` and `useThrottle` reduce unnecessary renders using Lodash's optimized implementations
+2. `useDistinct` avoids reference equality problems with optional deep comparison
+3. `useStorageState` batches storage updates to reduce expensive serialization/deserialization
+4. `useUrlState` efficiently handles URL synchronization with debouncing
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Start development server
+yarn dev
+
+# Run tests
+yarn test
+
+# Build the library
+yarn build
+
+# Lint and format the code
+yarn lint
+```
+
+## 🙏 Acknowledgements
+
+This project was built with:
+
+- [React](https://reactjs.org/)
+- [TypeScript](https://www.typescriptlang.org/)
+- [Vite](https://vitejs.dev/)
+- [Vitest](https://vitest.dev/)
+- [Lodash](https://lodash.com/)
+- [use-json](https://www.npmjs.com/package/use-json)
+- [use-qs](https://www.npmjs.com/package/use-qs)
+
+## 📝 License
+
+MIT © [Felipe Rohde](mailto:feliperohdee@gmail.com)
+
+## 👨‍💻 Author
+
+**Felipe Rohde**
+
+- Twitter: [@felipe_rohde](https://twitter.com/felipe_rohde)
+- Github: [@feliperohdee](https://github.com/feliperohdee)
+- Email: feliperohdee@gmail.com
+

package/dist-export/index.d.ts

@@ -0,0 +1 @@
+export { }

package/dist-export/index.js

@@ -0,0 +1,192 @@
+import t from "lodash";
+import { useState as S, useRef as b, useEffect as y, useCallback as D } from "react";
+import k from "use-json";
+import w from "use-qs";
+const _ = 300, R = (r, e = _) => {
+  const [l, d] = S(r), f = b(
+    t.debounce((p) => {
+      d(p);
+    }, e)
+  );
+  return y(() => {
+    f.current(r);
+  }, [r]), y(() => {
+    const p = f.current;
+    return () => {
+      p.cancel();
+    };
+  }, []), l;
+}, B = (r, e) => r === e, M = (r, e = {}) => {
+  const l = b(!1), d = b(e), f = b(r), p = b(
+    t.debounce((i) => {
+      const { compare: o, deep: s } = d.current;
+      !(t.isFunction(o) ? o : s ? t.isEqual : B)(i, f.current) && (F({
+        distinct: !0,
+        prevValue: f.current,
+        value: i
+      }), f.current = i);
+    }, d.current.debounce ?? 0)
+  ), [m, F] = S({
+    distinct: !1,
+    prevValue: void 0,
+    value: r
+  }), a = D(() => {
+    l.current = !1, F((i) => ({
+      ...i,
+      distinct: !1
+    }));
+  }, []);
+  return y(() => {
+    if (m.distinct && l.current) {
+      a();
+      return;
+    }
+    const i = p.current;
+    i(r);
+  }), y(() => {
+    m.distinct && (l.current = !0);
+  }, [m.distinct]), y(() => {
+    const i = p.current;
+    return () => {
+      i.cancel();
+    };
+  }, []), m;
+}, O = (r) => {
+  const e = b(void 0);
+  return y(() => {
+    e.current = r;
+  }), e.current;
+}, A = () => typeof window < "u", g = { browser: A }, K = 500, h = "local", U = (r, e) => t.isMap(e) ? {
+  __type: "Map",
+  value: Array.from(e.entries())
+} : t.isSet(e) ? {
+  __type: "Set",
+  value: Array.from(e)
+} : e, z = (r, e) => e && e.__type === "Map" ? new Map(e.value) : e && e.__type === "Set" ? new Set(e.value) : e, $ = (r, e, l) => {
+  const d = b(l || {}), f = b(!1), [p, m] = S(e), F = R(
+    p,
+    d.current.debounce ?? K
+  );
+  y(() => {
+    if (!g.browser() || !f.current)
+      return;
+    const {
+      storage: i = h,
+      onError: o,
+      omitKeys: s,
+      pickKeys: u
+    } = d.current, c = i === "local" ? localStorage : sessionStorage;
+    if (c)
+      try {
+        let n = F;
+        s && (t.size(s) || t.isFunction(s)) && (n = t.isFunction(s) ? t.omitBy(n, s) : t.omit(n, s)), u && (t.size(u) || t.isFunction(u)) && (n = t.isFunction(u) ? t.pickBy(n, u) : t.pick(n, u)), c.setItem(r, k.stringify(n, U));
+      } catch (n) {
+        o && o(n);
+      }
+  }, [r, F]), y(() => {
+    const {
+      storage: i = h,
+      omitKeys: o,
+      onError: s,
+      pickKeys: u
+    } = d.current;
+    try {
+      const c = i === "local" ? localStorage : sessionStorage, n = c == null ? void 0 : c.getItem(r);
+      if (n) {
+        let E = k.parse(n, z);
+        o && (t.size(o) || t.isFunction(o)) && (E = t.isFunction(o) ? t.omitBy(E, o) : t.omit(E, o)), u && (t.size(u) || t.isFunction(u)) && (E = t.isFunction(u) ? t.pickBy(E, u) : t.pick(E, u)), m(
+          t.isEmpty(E) ? e : t.merge({}, e, E)
+        );
+      }
+    } catch (c) {
+      s && s(c);
+    } finally {
+      f.current = !0;
+    }
+  }, []);
+  const a = D(() => {
+    if (!g.browser())
+      return;
+    m(e);
+    const { storage: i = h } = d.current, o = i === "local" ? localStorage : sessionStorage;
+    o == null || o.removeItem(r);
+  }, [r, e]);
+  return [p, m, { removeKey: a }];
+}, C = 300, v = (r, e = C) => {
+  const [l, d] = S(r), f = b(
+    t.throttle((p) => {
+      d(p);
+    }, e)
+  );
+  return y(() => {
+    f.current(r);
+  }, [r]), y(() => {
+    const p = f.current;
+    return () => {
+      p.cancel();
+    };
+  }, []), l;
+}, T = 500, x = (r, e) => {
+  const l = b(e), d = () => {
+    const {
+      kebabCase: F = !0,
+      omitKeys: a,
+      omitValues: i,
+      onError: o,
+      pickKeys: s,
+      prefix: u = "",
+      url: c
+    } = l.current;
+    if (!c.search)
+      return r;
+    try {
+      let n = w.parse(decodeURIComponent(c.search), {
+        case: F ? "kebab-case" : "camelCase",
+        omitValues: i,
+        prefix: u
+      });
+      return a && (t.size(a) || t.isFunction(a)) && (n = t.isFunction(a) ? t.omitBy(n, a) : t.omit(n, a)), s && (t.size(s) || t.isFunction(s)) && (n = t.isFunction(s) ? t.pickBy(n, s) : t.pick(n, s)), t.isEmpty(n) ? r : t.merge({}, r, n);
+    } catch (n) {
+      return o && o(n), r;
+    }
+  }, [f, p] = S(d), m = R(
+    f,
+    l.current.debounce ?? T
+  );
+  return y(() => {
+    if (!g.browser())
+      return;
+    const {
+      kebabCase: F = !0,
+      omitKeys: a,
+      omitValues: i,
+      onError: o,
+      pickKeys: s,
+      prefix: u = ""
+    } = l.current;
+    try {
+      let c = m;
+      a && (t.size(a) || t.isFunction(a)) && (c = t.isFunction(a) ? t.omitBy(c, a) : t.omit(c, a)), s && (t.size(s) || t.isFunction(s)) && (c = t.isFunction(s) ? t.pickBy(c, s) : t.pick(c, s));
+      const n = w.stringify(c, {
+        case: F ? "kebab-case" : "camelCase",
+        omitValues: i,
+        prefix: u
+      });
+      n ? window.history.replaceState(
+        {},
+        "",
+        `${window.location.pathname}${n}`
+      ) : window.history.replaceState({}, "", window.location.pathname);
+    } catch (c) {
+      o && o(c);
+    }
+  }, [m]), [f, p];
+};
+export {
+  R as useDebounce,
+  M as useDistinct,
+  O as usePrev,
+  $ as useStorageState,
+  v as useThrottle,
+  x as useUrlState
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+	"dependencies": {
+		"use-json": "^1.0.0",
+		"use-qs": "^1.0.4"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.19.0",
+		"@testing-library/dom": "^10.4.0",
+		"@testing-library/jest-dom": "^6.6.3",
+		"@testing-library/react": "^16.2.0",
+		"@types/lodash": "^4.17.16",
+		"@types/node": "^22.13.1",
+		"@types/react": "^19.0.8",
+		"@types/react-dom": "^19.0.3",
+		"@vitejs/plugin-react": "^4.3.4",
+		"clsx": "^2.1.1",
+		"eslint": "^9.19.0",
+		"eslint-plugin-react-hooks": "^5.0.0",
+		"eslint-plugin-react-refresh": "^0.4.18",
+		"globals": "^16.0.0",
+		"jsdom": "^26.0.0",
+		"lodash": "^4.17.21",
+		"prettier": "^3.4.2",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"typescript": "~5.8.2",
+		"typescript-eslint": "^8.22.0",
+		"vite": "^6.2.0",
+		"vite-plugin-dts": "^4.5.3",
+		"vitest": "^3.0.7"
+	},
+	"files": [
+		"dist-export"
+	],
+	"main": "dist-export/index.js",
+	"module": "index.ts",
+	"name": "use-good-hooks",
+	"peerDependencies": {
+		"lodash": "^4.17.21",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0"
+	},
+	"scripts": {
+		"build": "vite build",
+		"build:export": "yarn lint && yarn build --outDir ./dist-export --mode export",
+		"dev": "vite",
+		"lint": "prettier --write . && eslint .",
+		"test": "vitest"
+	},
+	"type": "module",
+	"version": "1.0.0"
+}