better-preact-use-state 1.0.4 → 1.0.5

package/README.md

@@ -4,7 +4,7 @@ A utility that improves Preact's `useState` to be safer and more convenient. Pro
 
 ## Overview
 
-Preact's `useState` can cause unintended behavior when you want to hold a function as a state. `better-preact-use-state` solves this problem and is a utility designed for safer state management. It is designed as a drop-in replacement for Preact's `useState` hook, with added functionality. `better-preact-use-state` also provides a simplified hook, `useBoolState`, specifically for boolean state.
+Preact's `useState` hands back a single setter that accepts either the next value or an updater function, so the two cannot be told apart by type. `better-preact-use-state` is a utility designed for safer state management: its `setState` accepts only the next value, and it also hands back `updateState` and `resetState`. It is designed as a drop-in replacement for Preact's `useState` hook, with added functionality. `better-preact-use-state` also provides a simplified hook, `useBoolState`, specifically for boolean state.
 
 ## Installation
 
@@ -30,27 +30,34 @@ pnpm add better-preact-use-state
 
 ```tsx
 import { useState } from 'better-preact-use-state';
+import type * as Preact from 'preact';
+import { useCallback } from 'preact/hooks';
 
-const MyComponent: FunctionalComponent = () => {
-    const [name, setName] = useState('John Doe');
+export const MyComponent = (): Preact.JSX.Element => {
+    const [userName, setUserName] = useState('John Doe');
 
-    const [count, setCount, { updateState: updateCount }] = useState(0);
+    const [count, , { updateState: updateCount }] = useState(0);
 
-    const onNameChange = useCallback((event) => {
-        setName(event.target.value);
-    }, []);
+    const onNameInput: Preact.InputEventHandler<HTMLInputElement> = useCallback(
+        (ev) => {
+            setUserName(ev.currentTarget.value);
+        },
+        [setUserName],
+    );
 
     const incrementCount = useCallback(() => {
         updateCount((x) => x + 1);
-    }, []);
+    }, [updateCount]);
 
     return (
         <div>
             <p>{`Count: ${count}`}</p>
-            <button onClick={incrementCount}>{'Increment'}</button>
+            <button type={'button'} onClick={incrementCount}>
+                {'Increment'}
+            </button>
 
-            <p>{`Name: ${name}`}</p>
-            <input type="text" value={name} onChange={onNameChange} />
+            <p>{`Name: ${userName}`}</p>
+            <input type={'text'} value={userName} onInput={onNameInput} />
         </div>
     );
 };
@@ -62,18 +69,25 @@ const MyComponent: FunctionalComponent = () => {
 
 ```tsx
 import { useBoolState } from 'better-preact-use-state';
+import type * as Preact from 'preact';
 
-const MyComponent = () => {
-    const [isOpen, { setTrue: open, setFalse: close, toggleState }] =
+export const MyComponent = (): Preact.JSX.Element => {
+    const [isOpen, { setTrue: openPanel, setFalse: closePanel, toggleState }] =
         useBoolState(false);
 
     return (
         <div>
             <p>{`Is Open: ${isOpen ? 'Yes' : 'No'}`}</p>
-            <button onClick={open}>{'Open'}</button>
-            <button onClick={close}>{'Close'}</button>
-            <button onClick={toggleState}>{'Toggle'}</button>
+            <button type={'button'} onClick={openPanel}>
+                {'Open'}
+            </button>
+            <button type={'button'} onClick={closePanel}>
+                {'Close'}
+            </button>
             {/* Toggles the boolean value */}
+            <button type={'button'} onClick={toggleState}>
+                {'Toggle'}
+            </button>
         </div>
     );
 };
@@ -83,8 +97,8 @@ const MyComponent = () => {
 
 ### `useState`
 
-```typescript
-const [state, setState, { updateState, resetState }] = useState<T>(initialState: T);
+```ts
+const [state, setState, { updateState, resetState }] = useState(initialState);
 ```
 
 - `state`: The current state.
@@ -94,24 +108,27 @@ const [state, setState, { updateState, resetState }] = useState<T>(initialState:
 
 #### `updateState`
 
-```typescript
-updateState(updateFn: (v: T) => T): void;
+```ts
+updateState: (updateFn: (v: T) => T) => void;
 ```
 
 Updates the state by passing a function `updateFn` that takes the current state as an argument and returns the new state.
 
 #### `resetState`
 
-```typescript
-resetState(): void;
+```ts
+resetState: () => void;
 ```
 
-Resets the state to the initial value.
+Resets the state to the value it was created with: the first render's `initialState`, as `useState` reads it, whatever is passed later. Its identity never changes.
 
 ### `useBoolState`
 
-```typescript
-const [state, { setState, setTrue, setFalse, resetState, toggleState, updateState }] = useBoolState(initialState: boolean);
+```ts
+const [
+    state,
+    { setState, setTrue, setFalse, resetState, toggleState, updateState },
+] = useBoolState(initialState);
 ```
 
 - `state`: The current boolean value.
@@ -124,67 +141,66 @@ const [state, { setState, setTrue, setFalse, resetState, toggleState, updateStat
 
 #### `setState`
 
-```typescript
-setState(next: boolean): void;
+```ts
+setState: (next: boolean) => void;
 ```
 
 Sets the state to the provided boolean value.
 
 #### `setTrue`
 
-```typescript
-setTrue(): void;
+```ts
+setTrue: () => void;
 ```
 
 Sets the state to `true`.
 
 #### `setFalse`
 
-```typescript
-setFalse(): void;
+```ts
+setFalse: () => void;
 ```
 
 Sets the state to `false`.
 
 #### `resetState`
 
-```typescript
-resetState(): void;
+```ts
+resetState: () => void;
 ```
 
-Resets the state to the initial value.
+Resets the state to the value it was created with: the first render's `initialState`, as `useState` reads it, whatever is passed later. Its identity never changes.
 
 #### `toggleState`
 
-```typescript
-toggleState(): void;
+```ts
+toggleState: () => void;
 ```
 
 Toggles the current boolean value.
 
 #### `updateState`
 
-```typescript
-updateState(updateFn: (v: boolean) => boolean): void;
+```ts
+updateState: (updateFn: (v: boolean) => boolean) => void;
 ```
 
 Updates the state by passing a function `updateFn` that takes the current state as an argument and returns the new state. This is useful for updates that depend on the current state.
 
 ## Benefits of this library
 
-With Preact's standard `useState`, attempting to store a function as state can lead to unexpected behavior (the function being interpreted as an updater function). `better-preact-use-state` solves this issue and, by providing `updateState`, allows functions to be safely held as state. Also, `resetState` lets you easily return the state to its initial value. `useBoolState` simplifies boolean state management in Preact, offering several advantages over directly using useState for booleans.
-
-### Example Use Case
+With Preact's standard `useState`, `setState` accepts either the next value or an updater function, and nothing in the types tells the two apart. `better-preact-use-state` separates them: `setState` is typed to accept only the next value, and an update that depends on the current value goes through `updateState` explicitly. `resetState` lets you easily return the state to its initial value. `useBoolState` simplifies boolean state management in Preact, offering several advantages over directly using `useState` for booleans.
 
-Useful when you want to hold a function as state.
+### Holding a function as state
 
-```typescript
-const [fn, setFn, { updateState: updateFn }] = useState(initialFn); // Holds a function as state
+The initial value and the argument of `setState` are passed to Preact's `useState` as they are, so a function given to either is still called as a lazy initializer or an updater, just as with Preact's own hook. To hold a function as state, wrap it in an object:
 
-// In Preact's standard useState, `setFn(nextFn)` interprets nextFn as an update function.
+```ts
+const [{ fn }, setFn] = useState({ fn: initialFn });
 
-// If you want to update the state with an update function, you can use updateState instead.
-updateFn((currentFn) => nextFn);
+const onReplace = useCallback((): void => {
+    setFn({ fn: nextFn });
+}, [setFn, nextFn]);
 ```
 
 ## License

package/dist/use-state.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"use-state.d.mts","sourceRoot":"","sources":["../src/use-state.mts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ,GAAI,CAAC,gBACV,CAAC,KACd,SAAS,CACV,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,EAC3B,OAAO,EAAE,QAAQ,CAAC;IAChB,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAC7C,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC,CAaH,CAAC"}
+{"version":3,"file":"use-state.d.mts","sourceRoot":"","sources":["../src/use-state.mts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ,GAAI,CAAC,gBACV,CAAC,KACd,SAAS,CACV,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,EAC3B,OAAO,EAAE,QAAQ,CAAC;IAChB,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAC7C,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC,CAkBH,CAAC"}

package/dist/use-state.mjs

@@ -1,9 +1,13 @@
 import * as Preact from 'preact/hooks';
 export const useState = (initialState) => {
     const [state, setState] = Preact.useState(initialState);
+
+
+
+    const [initial] = Preact.useState(initialState);
     const resetState = Preact.useCallback(() => {
-        setState(() => initialState);
-    }, [initialState]);
+        setState(() => initial);
+    }, [initial]);
     const updateState = Preact.useCallback((updateFn) => {
         setState(updateFn);
     }, []);

package/dist/use-state.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-state.mjs","sourceRoot":"","sources":["../src/use-state.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AAEvC,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,YAAe,EAQf,EAAE;IACF,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAI,YAAY,CAAC,CAAC;IAE3D,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;QACzC,QAAQ,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC;IAC/B,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAEnB,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAqB,EAAE,EAAE;QAC/D,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;AACxD,CAAC,CAAC"}
+{"version":3,"file":"use-state.mjs","sourceRoot":"","sources":["../src/use-state.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AAEvC,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,YAAe,EAQf,EAAE;IACF,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAI,YAAY,CAAC,CAAC;IAE3D,6EAA6E;IAC7E,0EAA0E;IAC1E,uEAAuE;IACvE,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAI,YAAY,CAAC,CAAC;IAEnD,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;QACzC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAqB,EAAE,EAAE;QAC/D,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;AACxD,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-preact-use-state",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "description": "useState that also hands back the setters you would otherwise write by hand: updateState, resetState, and setTrue / setFalse / toggleState for booleans.",
   "keywords": [
@@ -33,24 +33,27 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "eslint": "10.9.1",
-    "eslint-config-typed": "5.11.2",
-    "eslint-plugin-ts-data-forge": "0.7.0",
-    "eslint-plugin-ts-type-forge": "0.8.1",
-    "npm-run-all2": "9.0.3",
+    "@testing-library/preact": "3.2.4",
+    "@vitest/browser-playwright": "5.0.5",
+    "eslint": "10.13.0",
+    "eslint-config-typed": "7.14.0",
+    "eslint-plugin-ts-data-forge": "0.13.1",
+    "eslint-plugin-ts-type-forge": "0.8.26",
+    "npm-run-all2": "9.0.4",
+    "playwright": "1.64.1",
     "preact": "10.29.8",
-    "prettier": "3.9.6",
+    "prettier": "3.9.10",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
-    "ts-data-forge": "14.6.3",
-    "ts-repo-utils": "10.6.0",
-    "tsx": "4.23.12"
+    "ts-data-forge": "15.0.1",
+    "ts-repo-utils": "11.0.1",
+    "tsx": "4.23.15"
   },
   "peerDependencies": {
     "preact": ">=10.0.0"
   },
   "engines": {
-    "node": ">=22.22.2",
+    "node": ">=22.23.4",
     "pnpm": ">=9.0.0"
   },
   "publishConfig": {
@@ -59,18 +62,24 @@
   },
   "scripts": {
     "build": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/build.mts",
-    "build:min": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/build.mts --skip-check",
     "check:ext": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/check-ext.mts",
-    "fmt": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-uncommitted.mts --cwd .",
-    "fmt:diff": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-diff-from.mts origin/main --cwd .",
-    "fmt:full": "pnpm run z:prettier .",
-    "gi": "run-s gi:src fmt",
-    "gi:src": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/gen-index-ts.mts ./src --index-ext .mts --export-ext .mjs --target-ext .mts",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "tsc": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
-    "tscw": "node ../../node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
-    "type-check": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
-    "z:prettier": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --ignore-path ../../.gitignore --ignore-unknown --no-error-on-unmatched-pattern --write"
+    "check:lint": "node ../../tools/scripts/cmd/assert-deps-built.mts && oxlint . && eslint .",
+    "check:test": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest:node run",
+    "check:test:browser": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest --project='Browser' run",
+    "check:types": "node ../../tools/scripts/cmd/assert-deps-built.mts && node ../../node_modules/typescript-native/bin/tsc --noEmit",
+    "doc": "run-s gen:readme",
+    "fix:fmt": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-uncommitted.mts --cwd .",
+    "fix:fmt:diff": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-diff-from.mts origin/main --cwd .",
+    "fix:fmt:full": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../tools/scripts/cmd/format-package.mts",
+    "fix:lint": "node ../../tools/scripts/cmd/assert-deps-built.mts && oxlint . --fix && eslint . --fix",
+    "fmt": "pnpm run fix:fmt",
+    "gen": "run-s gen:index gen:readme",
+    "gen:index": "run-s gen:index:src fix:fmt",
+    "gen:index:src": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/gen-index-ts.mts ./src --index-ext .mts --export-ext .mjs --target-ext .mts",
+    "gen:readme": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples.mts",
+    "test": "pnpm run check:test",
+    "watch:types": "node ../../node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
+    "z:vitest": "vitest --config ./configs/vitest.config.mts",
+    "z:vitest:node": "pnpm run z:vitest --project='Node.js'"
   }
 }

package/src/use-state.mts

@@ -12,9 +12,14 @@ export const useState = <T,>(
 ] => {
   const [state, setState] = Preact.useState<T>(initialState);
 
+  // The value the state was created with, read once as `useState` reads it, so
+  // that `resetState` neither follows a later argument nor changes identity
+  // when one is passed (an object literal is a new one on every render).
+  const [initial] = Preact.useState<T>(initialState);
+
   const resetState = Preact.useCallback(() => {
-    setState(() => initialState);
-  }, [initialState]);
+    setState(() => initial);
+  }, [initial]);
 
   const updateState = Preact.useCallback((updateFn: (v: T) => T) => {
     setState(updateFn);