@usefy/use-object-state 0.19.0

package/README.md

@@ -0,0 +1,187 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-object-state</h1>
+
+<p align="center">
+  <strong>Object state with immutable partial updates (patch/merge) and reset</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-object-state"><img src="https://img.shields.io/npm/v/@usefy/use-object-state.svg?style=flat-square&color=007acc" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@usefy/use-object-state"><img src="https://img.shields.io/npm/dm/@usefy/use-object-state.svg?style=flat-square&color=007acc" alt="npm downloads" /></a>
+  <a href="https://bundlephobia.com/package/@usefy/use-object-state"><img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-object-state?style=flat-square&color=007acc" alt="bundle size" /></a>
+  <a href="https://github.com/mirunamu00/usefy/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@usefy/use-object-state.svg?style=flat-square&color=007acc" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api">API</a> •
+  <a href="#testing">Testing</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://mirunamu00.github.io/usefy/?path=/docs/hooks-useobjectstate--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`useObjectState` is part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem — a collection of production-ready, TypeScript-first, SSR-safe React hooks. It manages object state with immutable partial updates and reset — the ergonomic middle ground between `useState` (which replaces the whole value) and `useReducer` (which makes you write a reducer).
+
+It returns a `useState`-style tuple `[state, patch, reset]`. `patch` shallow-merges a partial into the current state **immutably**, so you update one field without spreading the whole object yourself, and `reset` restores the initial value (or a provided one).
+
+## Features
+
+- **Partial merge** — `patch({ field })` shallow-merges immutably (`{ ...prev, ...partial }`); untouched keys are preserved by reference
+- **Functional updater** — `patch(prev => ({ ... }))` computes the next patch from the current state
+- **Reset** — `reset()` restores the captured initial value; `reset(next)` swaps in a provided object
+- **Stable actions** — `patch` and `reset` keep a stable identity for the component's lifetime (safe as `useEffect` dependencies)
+- **Lazy init** — accepts a factory (run once), just like `useState`; the produced value is cached for `reset()`
+- **SSR- & StrictMode-safe** — pure state logic, no side effects, no globals
+- **TypeScript-first** — full type inference and exported types
+- **Tiny & tree-shakeable** — zero dependencies, published as its own package
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-object-state
+
+# yarn
+yarn add @usefy/use-object-state
+
+# pnpm
+pnpm add @usefy/use-object-state
+```
+
+Requires React 18 or 19 (`peerDependencies: "react": "^18.0.0 || ^19.0.0"`).
+
+## Quick Start
+
+```tsx
+import { useObjectState } from "@usefy/use-object-state";
+
+interface FormState {
+  name: string;
+  email: string;
+  subscribe: boolean;
+}
+
+function SignupForm() {
+  const [form, patch, reset] = useObjectState<FormState>({
+    name: "",
+    email: "",
+    subscribe: false,
+  });
+
+  return (
+    <form>
+      <input
+        value={form.name}
+        onChange={(e) => patch({ name: e.target.value })}
+      />
+      <input
+        value={form.email}
+        onChange={(e) => patch({ email: e.target.value })}
+      />
+      <label>
+        <input
+          type="checkbox"
+          checked={form.subscribe}
+          onChange={(e) => patch({ subscribe: e.target.checked })}
+        />
+        Subscribe
+      </label>
+      <button type="button" onClick={() => reset()}>
+        Reset
+      </button>
+    </form>
+  );
+}
+```
+
+## API
+
+### `useObjectState<T extends object>(initialState)`
+
+Returns a `[state, patch, reset]` tuple.
+
+#### Parameters
+
+| Parameter      | Type                        | Description                                                                          |
+| -------------- | --------------------------- | ------------------------------------------------------------------------------------ |
+| `initialState` | `T \| (() => T)`            | The initial object, or a factory returning it (evaluated once on mount, then cached) |
+
+`T` must be a plain object/record — this hook is for objects, not arrays (use [`useList`](https://www.npmjs.com/package/@usefy/use-list)) or primitives (use `useState`).
+
+#### Returns `[state, patch, reset]`
+
+| Item    | Type                    | Description                                                       |
+| ------- | ----------------------- | ---------------------------------------------------------------- |
+| `state` | `T`                     | The current object                                               |
+| `patch` | `ObjectStatePatch<T>`   | Immutably shallow-merge a `Partial<T>` (or a functional updater) |
+| `reset` | `ObjectStateReset<T>`   | Restore the initial value, or set a provided object              |
+
+#### `patch(partial | updater)`
+
+```tsx
+patch({ field: newValue });                 // shallow-merge a partial
+patch((prev) => ({ count: prev.count + 1 })); // compute the patch from prev
+```
+
+- Accepts a `Partial<T>` and shallow-merges it immutably: `{ ...prev, ...partial }`. It always produces a **new** object; the previous state is never mutated.
+- Also accepts a functional updater `(prev: T) => Partial<T>` for when the next value depends on the current one.
+- Only the provided keys change; untouched keys are preserved by reference.
+- **Every `patch` triggers a re-render** — there is no shallow-equality dedupe (matching `react-use`'s `useSetState`). This keeps the semantics simple and predictable; add your own guard if you need to skip no-ops.
+
+#### `reset(next?)`
+
+```tsx
+reset();              // back to the initial state captured on mount
+reset(nextState);     // set to the provided object instead
+```
+
+- `reset()` restores the value captured on mount. If a lazy initializer was used, the value it produced is cached once and reused — the initializer is **not** re-run.
+- `reset(nextState)` replaces the state with the provided object.
+
+### Shallow-merge caveat
+
+The merge is **shallow** — a nested object in the patch replaces the previous nested object wholesale, it is not deep-merged:
+
+```tsx
+const [state, patch] = useObjectState({ user: { name: "Alice", age: 30 } });
+patch({ user: { name: "Bob" } });
+// state.user is now { name: "Bob" } — `age` is gone.
+
+// Spread the nested object yourself to update one nested field:
+patch({ user: { ...state.user, name: "Bob" } });
+```
+
+### Types
+
+```tsx
+import {
+  useObjectState,
+  type ObjectStateInitializer,
+  type ObjectStatePatch,
+  type ObjectStateReset,
+  type UseObjectStateReturn,
+} from "@usefy/use-object-state";
+```
+
+## Testing
+
+📊 <a href="https://mirunamu00.github.io/usefy/coverage/use-object-state/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages) — **22 tests**, 100% statement coverage.
+
+## License
+
+MIT © [mirunamu](https://github.com/mirunamu00)
+
+This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo.

package/dist/index.d.mts

@@ -0,0 +1,148 @@
+/**
+ * Accepted initial value for {@link useObjectState}.
+ *
+ * Mirrors `useState`'s lazy-initializer support: pass a plain object, or a
+ * function returning one (evaluated **once** on mount). The resolved value is
+ * captured for {@link ObjectStateReset | reset()}.
+ *
+ * @template T - The object shape held in state.
+ *
+ * @example
+ * ```ts
+ * useObjectState({ name: "", age: 0 });         // direct object
+ * useObjectState(() => ({ name: "", age: 0 })); // lazy (run once)
+ * ```
+ */
+type ObjectStateInitializer<T extends object> = T | (() => T);
+/**
+ * The `patch` updater returned by {@link useObjectState}.
+ *
+ * Shallow-merges a partial into the current state **immutably** — it always
+ * produces a brand-new object (`{ ...prev, ...partial }`) and never mutates the
+ * previous state. Only the provided keys change; untouched keys are preserved by
+ * reference.
+ *
+ * Two forms are accepted:
+ * - a `Partial<T>` object — merged directly, and
+ * - a functional updater `(prev: T) => Partial<T>` — computes the partial from
+ *   the current state (use this when the next value depends on the previous one).
+ *
+ * The merge is **shallow**: a nested object in the partial replaces the previous
+ * nested object wholesale, it is not deep-merged.
+ *
+ * @template T - The object shape held in state.
+ */
+type ObjectStatePatch<T extends object> = (patch: Partial<T> | ((prev: T) => Partial<T>)) => void;
+/**
+ * The `reset` action returned by {@link useObjectState}.
+ *
+ * - `reset()` — restores the state to the initial value captured on mount (if a
+ *   lazy initializer was used, the value it produced is cached once and reused;
+ *   the initializer is not re-run).
+ * - `reset(nextState)` — replaces the state with the provided object instead.
+ *
+ * @template T - The object shape held in state.
+ */
+type ObjectStateReset<T extends object> = (nextState?: T) => void;
+/**
+ * Return type of {@link useObjectState}: a tuple of the current state, the
+ * `patch` updater, and the `reset` action — mirroring the `useState` tuple shape
+ * but with partial-merge semantics.
+ *
+ * @template T - The object shape held in state.
+ */
+type UseObjectStateReturn<T extends object> = [
+    T,
+    ObjectStatePatch<T>,
+    ObjectStateReset<T>
+];
+
+/**
+ * A React hook for managing object state with immutable partial updates
+ * (patch/merge) and reset — the ergonomic middle ground between `useState`
+ * (replace the whole value) and `useReducer` (write a reducer).
+ *
+ * Returns a `useState`-style tuple `[state, patch, reset]`:
+ *
+ * - **`patch`** shallow-merges a `Partial<T>` into the current state
+ *   **immutably** (`{ ...prev, ...partial }`), producing a brand-new object on
+ *   every call and never mutating the previous state. Only the provided keys
+ *   change; untouched keys are preserved by reference. It also accepts a
+ *   functional updater `(prev) => Partial<T>` when the next value depends on the
+ *   previous one.
+ * - **`reset`** restores the state to the initial value captured on mount, or —
+ *   when passed an argument — to that object instead.
+ *
+ * Both `patch` and `reset` are referentially stable for the lifetime of the
+ * component (safe to use as `useEffect` dependencies). The hook is pure state
+ * logic, so it is SSR-safe and StrictMode-safe.
+ *
+ * @remarks
+ * - **Objects only.** Intended for plain objects/records (`T extends object`),
+ *   not arrays or primitives — for array state use `useList`, and for a single
+ *   value use `useState`.
+ * - **Shallow merge.** A nested object in the patch replaces the previous nested
+ *   object wholesale; it is not deep-merged. Spread the nested object yourself
+ *   (`patch({ user: { ...state.user, name } })`) to update one nested field.
+ * - **Every patch re-renders.** No shallow-equality dedupe is performed — like
+ *   `react-use`'s `useSetState`, each `patch` commits a new object and triggers
+ *   a render, even if the merged values are unchanged. This keeps the semantics
+ *   simple and predictable; wrap in your own guard if you need to skip no-ops.
+ * - **Lazy init is cached once.** If a function initializer is passed, it runs a
+ *   single time on mount and the produced value is reused by `reset()`; the
+ *   initializer is not re-evaluated on reset.
+ *
+ * @template T - The object shape held in state.
+ * @param initialState - The initial object, or a factory returning it (run once).
+ * @returns `[state, patch, reset]`
+ *
+ * @example
+ * ```tsx
+ * interface FormState {
+ *   name: string;
+ *   email: string;
+ *   subscribe: boolean;
+ * }
+ *
+ * function SignupForm() {
+ *   const [form, patch, reset] = useObjectState<FormState>({
+ *     name: "",
+ *     email: "",
+ *     subscribe: false,
+ *   });
+ *
+ *   return (
+ *     <form>
+ *       <input
+ *         value={form.name}
+ *         onChange={(e) => patch({ name: e.target.value })}
+ *       />
+ *       <input
+ *         value={form.email}
+ *         onChange={(e) => patch({ email: e.target.value })}
+ *       />
+ *       <label>
+ *         <input
+ *           type="checkbox"
+ *           checked={form.subscribe}
+ *           onChange={(e) => patch({ subscribe: e.target.checked })}
+ *         />
+ *         Subscribe
+ *       </label>
+ *       <button type="button" onClick={() => reset()}>Reset</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Functional patch + reset to a provided object
+ * const [counter, patch, reset] = useObjectState({ count: 0, step: 1 });
+ * patch((prev) => ({ count: prev.count + prev.step })); // compute from prev
+ * reset({ count: 10, step: 5 });                         // reset to a new object
+ * ```
+ */
+declare function useObjectState<T extends object>(initialState: ObjectStateInitializer<T>): UseObjectStateReturn<T>;
+
+export { type ObjectStateInitializer, type ObjectStatePatch, type ObjectStateReset, type UseObjectStateReturn, useObjectState };

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Accepted initial value for {@link useObjectState}.
+ *
+ * Mirrors `useState`'s lazy-initializer support: pass a plain object, or a
+ * function returning one (evaluated **once** on mount). The resolved value is
+ * captured for {@link ObjectStateReset | reset()}.
+ *
+ * @template T - The object shape held in state.
+ *
+ * @example
+ * ```ts
+ * useObjectState({ name: "", age: 0 });         // direct object
+ * useObjectState(() => ({ name: "", age: 0 })); // lazy (run once)
+ * ```
+ */
+type ObjectStateInitializer<T extends object> = T | (() => T);
+/**
+ * The `patch` updater returned by {@link useObjectState}.
+ *
+ * Shallow-merges a partial into the current state **immutably** — it always
+ * produces a brand-new object (`{ ...prev, ...partial }`) and never mutates the
+ * previous state. Only the provided keys change; untouched keys are preserved by
+ * reference.
+ *
+ * Two forms are accepted:
+ * - a `Partial<T>` object — merged directly, and
+ * - a functional updater `(prev: T) => Partial<T>` — computes the partial from
+ *   the current state (use this when the next value depends on the previous one).
+ *
+ * The merge is **shallow**: a nested object in the partial replaces the previous
+ * nested object wholesale, it is not deep-merged.
+ *
+ * @template T - The object shape held in state.
+ */
+type ObjectStatePatch<T extends object> = (patch: Partial<T> | ((prev: T) => Partial<T>)) => void;
+/**
+ * The `reset` action returned by {@link useObjectState}.
+ *
+ * - `reset()` — restores the state to the initial value captured on mount (if a
+ *   lazy initializer was used, the value it produced is cached once and reused;
+ *   the initializer is not re-run).
+ * - `reset(nextState)` — replaces the state with the provided object instead.
+ *
+ * @template T - The object shape held in state.
+ */
+type ObjectStateReset<T extends object> = (nextState?: T) => void;
+/**
+ * Return type of {@link useObjectState}: a tuple of the current state, the
+ * `patch` updater, and the `reset` action — mirroring the `useState` tuple shape
+ * but with partial-merge semantics.
+ *
+ * @template T - The object shape held in state.
+ */
+type UseObjectStateReturn<T extends object> = [
+    T,
+    ObjectStatePatch<T>,
+    ObjectStateReset<T>
+];
+
+/**
+ * A React hook for managing object state with immutable partial updates
+ * (patch/merge) and reset — the ergonomic middle ground between `useState`
+ * (replace the whole value) and `useReducer` (write a reducer).
+ *
+ * Returns a `useState`-style tuple `[state, patch, reset]`:
+ *
+ * - **`patch`** shallow-merges a `Partial<T>` into the current state
+ *   **immutably** (`{ ...prev, ...partial }`), producing a brand-new object on
+ *   every call and never mutating the previous state. Only the provided keys
+ *   change; untouched keys are preserved by reference. It also accepts a
+ *   functional updater `(prev) => Partial<T>` when the next value depends on the
+ *   previous one.
+ * - **`reset`** restores the state to the initial value captured on mount, or —
+ *   when passed an argument — to that object instead.
+ *
+ * Both `patch` and `reset` are referentially stable for the lifetime of the
+ * component (safe to use as `useEffect` dependencies). The hook is pure state
+ * logic, so it is SSR-safe and StrictMode-safe.
+ *
+ * @remarks
+ * - **Objects only.** Intended for plain objects/records (`T extends object`),
+ *   not arrays or primitives — for array state use `useList`, and for a single
+ *   value use `useState`.
+ * - **Shallow merge.** A nested object in the patch replaces the previous nested
+ *   object wholesale; it is not deep-merged. Spread the nested object yourself
+ *   (`patch({ user: { ...state.user, name } })`) to update one nested field.
+ * - **Every patch re-renders.** No shallow-equality dedupe is performed — like
+ *   `react-use`'s `useSetState`, each `patch` commits a new object and triggers
+ *   a render, even if the merged values are unchanged. This keeps the semantics
+ *   simple and predictable; wrap in your own guard if you need to skip no-ops.
+ * - **Lazy init is cached once.** If a function initializer is passed, it runs a
+ *   single time on mount and the produced value is reused by `reset()`; the
+ *   initializer is not re-evaluated on reset.
+ *
+ * @template T - The object shape held in state.
+ * @param initialState - The initial object, or a factory returning it (run once).
+ * @returns `[state, patch, reset]`
+ *
+ * @example
+ * ```tsx
+ * interface FormState {
+ *   name: string;
+ *   email: string;
+ *   subscribe: boolean;
+ * }
+ *
+ * function SignupForm() {
+ *   const [form, patch, reset] = useObjectState<FormState>({
+ *     name: "",
+ *     email: "",
+ *     subscribe: false,
+ *   });
+ *
+ *   return (
+ *     <form>
+ *       <input
+ *         value={form.name}
+ *         onChange={(e) => patch({ name: e.target.value })}
+ *       />
+ *       <input
+ *         value={form.email}
+ *         onChange={(e) => patch({ email: e.target.value })}
+ *       />
+ *       <label>
+ *         <input
+ *           type="checkbox"
+ *           checked={form.subscribe}
+ *           onChange={(e) => patch({ subscribe: e.target.checked })}
+ *         />
+ *         Subscribe
+ *       </label>
+ *       <button type="button" onClick={() => reset()}>Reset</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Functional patch + reset to a provided object
+ * const [counter, patch, reset] = useObjectState({ count: 0, step: 1 });
+ * patch((prev) => ({ count: prev.count + prev.step })); // compute from prev
+ * reset({ count: 10, step: 5 });                         // reset to a new object
+ * ```
+ */
+declare function useObjectState<T extends object>(initialState: ObjectStateInitializer<T>): UseObjectStateReturn<T>;
+
+export { type ObjectStateInitializer, type ObjectStatePatch, type ObjectStateReset, type UseObjectStateReturn, useObjectState };

package/dist/index.js

@@ -0,0 +1,53 @@
+"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 index_exports = {};
+__export(index_exports, {
+  useObjectState: () => useObjectState
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useObjectState.ts
+var import_react = require("react");
+function resolveInitial(initial) {
+  return typeof initial === "function" ? initial() : initial;
+}
+function useObjectState(initialState) {
+  const initialRef = (0, import_react.useRef)(null);
+  if (initialRef.current === null) {
+    initialRef.current = resolveInitial(initialState);
+  }
+  const [state, setState] = (0, import_react.useState)(initialRef.current);
+  const patch = (0, import_react.useCallback)((update) => {
+    setState((prev) => {
+      const partial = typeof update === "function" ? update(prev) : update;
+      return { ...prev, ...partial };
+    });
+  }, []);
+  const reset = (0, import_react.useCallback)((nextState) => {
+    setState(nextState !== void 0 ? nextState : initialRef.current);
+  }, []);
+  return [state, patch, reset];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useObjectState
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useObjectState.ts"],"sourcesContent":["export { useObjectState } from \"./useObjectState\";\nexport type {\n  ObjectStateInitializer,\n  ObjectStatePatch,\n  ObjectStateReset,\n  UseObjectStateReturn,\n} from \"./types\";\n","import { useCallback, useRef, useState } from \"react\";\nimport type {\n  ObjectStateInitializer,\n  ObjectStatePatch,\n  ObjectStateReset,\n  UseObjectStateReturn,\n} from \"./types\";\n\n/**\n * Resolve an {@link ObjectStateInitializer} to a concrete object. A function\n * initializer is invoked once; a direct object is returned as-is.\n */\nfunction resolveInitial<T extends object>(initial: ObjectStateInitializer<T>): T {\n  return typeof initial === \"function\" ? (initial as () => T)() : initial;\n}\n\n/**\n * A React hook for managing object state with immutable partial updates\n * (patch/merge) and reset — the ergonomic middle ground between `useState`\n * (replace the whole value) and `useReducer` (write a reducer).\n *\n * Returns a `useState`-style tuple `[state, patch, reset]`:\n *\n * - **`patch`** shallow-merges a `Partial<T>` into the current state\n *   **immutably** (`{ ...prev, ...partial }`), producing a brand-new object on\n *   every call and never mutating the previous state. Only the provided keys\n *   change; untouched keys are preserved by reference. It also accepts a\n *   functional updater `(prev) => Partial<T>` when the next value depends on the\n *   previous one.\n * - **`reset`** restores the state to the initial value captured on mount, or —\n *   when passed an argument — to that object instead.\n *\n * Both `patch` and `reset` are referentially stable for the lifetime of the\n * component (safe to use as `useEffect` dependencies). The hook is pure state\n * logic, so it is SSR-safe and StrictMode-safe.\n *\n * @remarks\n * - **Objects only.** Intended for plain objects/records (`T extends object`),\n *   not arrays or primitives — for array state use `useList`, and for a single\n *   value use `useState`.\n * - **Shallow merge.** A nested object in the patch replaces the previous nested\n *   object wholesale; it is not deep-merged. Spread the nested object yourself\n *   (`patch({ user: { ...state.user, name } })`) to update one nested field.\n * - **Every patch re-renders.** No shallow-equality dedupe is performed — like\n *   `react-use`'s `useSetState`, each `patch` commits a new object and triggers\n *   a render, even if the merged values are unchanged. This keeps the semantics\n *   simple and predictable; wrap in your own guard if you need to skip no-ops.\n * - **Lazy init is cached once.** If a function initializer is passed, it runs a\n *   single time on mount and the produced value is reused by `reset()`; the\n *   initializer is not re-evaluated on reset.\n *\n * @template T - The object shape held in state.\n * @param initialState - The initial object, or a factory returning it (run once).\n * @returns `[state, patch, reset]`\n *\n * @example\n * ```tsx\n * interface FormState {\n *   name: string;\n *   email: string;\n *   subscribe: boolean;\n * }\n *\n * function SignupForm() {\n *   const [form, patch, reset] = useObjectState<FormState>({\n *     name: \"\",\n *     email: \"\",\n *     subscribe: false,\n *   });\n *\n *   return (\n *     <form>\n *       <input\n *         value={form.name}\n *         onChange={(e) => patch({ name: e.target.value })}\n *       />\n *       <input\n *         value={form.email}\n *         onChange={(e) => patch({ email: e.target.value })}\n *       />\n *       <label>\n *         <input\n *           type=\"checkbox\"\n *           checked={form.subscribe}\n *           onChange={(e) => patch({ subscribe: e.target.checked })}\n *         />\n *         Subscribe\n *       </label>\n *       <button type=\"button\" onClick={() => reset()}>Reset</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Functional patch + reset to a provided object\n * const [counter, patch, reset] = useObjectState({ count: 0, step: 1 });\n * patch((prev) => ({ count: prev.count + prev.step })); // compute from prev\n * reset({ count: 10, step: 5 });                         // reset to a new object\n * ```\n */\nexport function useObjectState<T extends object>(\n  initialState: ObjectStateInitializer<T>\n): UseObjectStateReturn<T> {\n  // Capture the resolved initial value exactly once so `reset()` can restore it\n  // without re-running a lazy initializer. `T extends object`, so the resolved\n  // value is never null — the null sentinel safely means \"not yet resolved\".\n  const initialRef = useRef<T | null>(null);\n  if (initialRef.current === null) {\n    initialRef.current = resolveInitial(initialState);\n  }\n\n  const [state, setState] = useState<T>(initialRef.current);\n\n  const patch = useCallback<ObjectStatePatch<T>>((update) => {\n    setState((prev) => {\n      const partial =\n        typeof update === \"function\" ? update(prev) : update;\n      // Immutable shallow merge — always a brand-new object; `prev` is untouched.\n      return { ...prev, ...partial };\n    });\n  }, []);\n\n  const reset = useCallback<ObjectStateReset<T>>((nextState) => {\n    setState(nextState !== undefined ? nextState : (initialRef.current as T));\n  }, []);\n\n  return [state, patch, reset];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAA8C;AAY9C,SAAS,eAAiC,SAAuC;AAC/E,SAAO,OAAO,YAAY,aAAc,QAAoB,IAAI;AAClE;AAwFO,SAAS,eACd,cACyB;AAIzB,QAAM,iBAAa,qBAAiB,IAAI;AACxC,MAAI,WAAW,YAAY,MAAM;AAC/B,eAAW,UAAU,eAAe,YAAY;AAAA,EAClD;AAEA,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAAY,WAAW,OAAO;AAExD,QAAM,YAAQ,0BAAiC,CAAC,WAAW;AACzD,aAAS,CAAC,SAAS;AACjB,YAAM,UACJ,OAAO,WAAW,aAAa,OAAO,IAAI,IAAI;AAEhD,aAAO,EAAE,GAAG,MAAM,GAAG,QAAQ;AAAA,IAC/B,CAAC;AAAA,EACH,GAAG,CAAC,CAAC;AAEL,QAAM,YAAQ,0BAAiC,CAAC,cAAc;AAC5D,aAAS,cAAc,SAAY,YAAa,WAAW,OAAa;AAAA,EAC1E,GAAG,CAAC,CAAC;AAEL,SAAO,CAAC,OAAO,OAAO,KAAK;AAC7B;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,26 @@
+// src/useObjectState.ts
+import { useCallback, useRef, useState } from "react";
+function resolveInitial(initial) {
+  return typeof initial === "function" ? initial() : initial;
+}
+function useObjectState(initialState) {
+  const initialRef = useRef(null);
+  if (initialRef.current === null) {
+    initialRef.current = resolveInitial(initialState);
+  }
+  const [state, setState] = useState(initialRef.current);
+  const patch = useCallback((update) => {
+    setState((prev) => {
+      const partial = typeof update === "function" ? update(prev) : update;
+      return { ...prev, ...partial };
+    });
+  }, []);
+  const reset = useCallback((nextState) => {
+    setState(nextState !== void 0 ? nextState : initialRef.current);
+  }, []);
+  return [state, patch, reset];
+}
+export {
+  useObjectState
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useObjectState.ts"],"sourcesContent":["import { useCallback, useRef, useState } from \"react\";\nimport type {\n  ObjectStateInitializer,\n  ObjectStatePatch,\n  ObjectStateReset,\n  UseObjectStateReturn,\n} from \"./types\";\n\n/**\n * Resolve an {@link ObjectStateInitializer} to a concrete object. A function\n * initializer is invoked once; a direct object is returned as-is.\n */\nfunction resolveInitial<T extends object>(initial: ObjectStateInitializer<T>): T {\n  return typeof initial === \"function\" ? (initial as () => T)() : initial;\n}\n\n/**\n * A React hook for managing object state with immutable partial updates\n * (patch/merge) and reset — the ergonomic middle ground between `useState`\n * (replace the whole value) and `useReducer` (write a reducer).\n *\n * Returns a `useState`-style tuple `[state, patch, reset]`:\n *\n * - **`patch`** shallow-merges a `Partial<T>` into the current state\n *   **immutably** (`{ ...prev, ...partial }`), producing a brand-new object on\n *   every call and never mutating the previous state. Only the provided keys\n *   change; untouched keys are preserved by reference. It also accepts a\n *   functional updater `(prev) => Partial<T>` when the next value depends on the\n *   previous one.\n * - **`reset`** restores the state to the initial value captured on mount, or —\n *   when passed an argument — to that object instead.\n *\n * Both `patch` and `reset` are referentially stable for the lifetime of the\n * component (safe to use as `useEffect` dependencies). The hook is pure state\n * logic, so it is SSR-safe and StrictMode-safe.\n *\n * @remarks\n * - **Objects only.** Intended for plain objects/records (`T extends object`),\n *   not arrays or primitives — for array state use `useList`, and for a single\n *   value use `useState`.\n * - **Shallow merge.** A nested object in the patch replaces the previous nested\n *   object wholesale; it is not deep-merged. Spread the nested object yourself\n *   (`patch({ user: { ...state.user, name } })`) to update one nested field.\n * - **Every patch re-renders.** No shallow-equality dedupe is performed — like\n *   `react-use`'s `useSetState`, each `patch` commits a new object and triggers\n *   a render, even if the merged values are unchanged. This keeps the semantics\n *   simple and predictable; wrap in your own guard if you need to skip no-ops.\n * - **Lazy init is cached once.** If a function initializer is passed, it runs a\n *   single time on mount and the produced value is reused by `reset()`; the\n *   initializer is not re-evaluated on reset.\n *\n * @template T - The object shape held in state.\n * @param initialState - The initial object, or a factory returning it (run once).\n * @returns `[state, patch, reset]`\n *\n * @example\n * ```tsx\n * interface FormState {\n *   name: string;\n *   email: string;\n *   subscribe: boolean;\n * }\n *\n * function SignupForm() {\n *   const [form, patch, reset] = useObjectState<FormState>({\n *     name: \"\",\n *     email: \"\",\n *     subscribe: false,\n *   });\n *\n *   return (\n *     <form>\n *       <input\n *         value={form.name}\n *         onChange={(e) => patch({ name: e.target.value })}\n *       />\n *       <input\n *         value={form.email}\n *         onChange={(e) => patch({ email: e.target.value })}\n *       />\n *       <label>\n *         <input\n *           type=\"checkbox\"\n *           checked={form.subscribe}\n *           onChange={(e) => patch({ subscribe: e.target.checked })}\n *         />\n *         Subscribe\n *       </label>\n *       <button type=\"button\" onClick={() => reset()}>Reset</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Functional patch + reset to a provided object\n * const [counter, patch, reset] = useObjectState({ count: 0, step: 1 });\n * patch((prev) => ({ count: prev.count + prev.step })); // compute from prev\n * reset({ count: 10, step: 5 });                         // reset to a new object\n * ```\n */\nexport function useObjectState<T extends object>(\n  initialState: ObjectStateInitializer<T>\n): UseObjectStateReturn<T> {\n  // Capture the resolved initial value exactly once so `reset()` can restore it\n  // without re-running a lazy initializer. `T extends object`, so the resolved\n  // value is never null — the null sentinel safely means \"not yet resolved\".\n  const initialRef = useRef<T | null>(null);\n  if (initialRef.current === null) {\n    initialRef.current = resolveInitial(initialState);\n  }\n\n  const [state, setState] = useState<T>(initialRef.current);\n\n  const patch = useCallback<ObjectStatePatch<T>>((update) => {\n    setState((prev) => {\n      const partial =\n        typeof update === \"function\" ? update(prev) : update;\n      // Immutable shallow merge — always a brand-new object; `prev` is untouched.\n      return { ...prev, ...partial };\n    });\n  }, []);\n\n  const reset = useCallback<ObjectStateReset<T>>((nextState) => {\n    setState(nextState !== undefined ? nextState : (initialRef.current as T));\n  }, []);\n\n  return [state, patch, reset];\n}\n"],"mappings":";AAAA,SAAS,aAAa,QAAQ,gBAAgB;AAY9C,SAAS,eAAiC,SAAuC;AAC/E,SAAO,OAAO,YAAY,aAAc,QAAoB,IAAI;AAClE;AAwFO,SAAS,eACd,cACyB;AAIzB,QAAM,aAAa,OAAiB,IAAI;AACxC,MAAI,WAAW,YAAY,MAAM;AAC/B,eAAW,UAAU,eAAe,YAAY;AAAA,EAClD;AAEA,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAY,WAAW,OAAO;AAExD,QAAM,QAAQ,YAAiC,CAAC,WAAW;AACzD,aAAS,CAAC,SAAS;AACjB,YAAM,UACJ,OAAO,WAAW,aAAa,OAAO,IAAI,IAAI;AAEhD,aAAO,EAAE,GAAG,MAAM,GAAG,QAAQ;AAAA,IAC/B,CAAC;AAAA,EACH,GAAG,CAAC,CAAC;AAEL,QAAM,QAAQ,YAAiC,CAAC,cAAc;AAC5D,aAAS,cAAc,SAAY,YAAa,WAAW,OAAa;AAAA,EAC1E,GAAG,CAAC,CAAC;AAEL,SAAO,CAAC,OAAO,OAAO,KAAK;AAC7B;","names":[]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@usefy/use-object-state",
+  "version": "0.19.0",
+  "description": "A React hook for object state with immutable partial updates (patch/merge) and reset",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mirunamu00/usefy.git",
+    "directory": "packages/hooks/use-object-state"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "object",
+    "state",
+    "setState",
+    "merge",
+    "patch",
+    "immutable",
+    "useObjectState"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}