Refactor hooks: reducers, memoization, deepEqual

Rework hooks internals to improve stability and performance: replace several hook-local useState usages with reducers (useAsync, useMutation) and memoize returned objects to preserve referential identity. Add internal deepEqual and use it to stabilize option objects (useStableOptions, useSecureStorage) and avoid unnecessary callback recreations; introduce a frozen EMPTY_ITEMS fallback for stable empty lists. Update useSecurityAvailability and other hooks to return memoized state and expose createInitialAsyncState/createInitialVoidState from index. Example and docs updated: remove example/useAsyncAction, switch StorageCard to useSecureOperation with explicit handlers, and clarify per-component-instance caching and import path changes in HOOKS.md.

Author: mCodex

docs/HOOKS.md

@@ -322,9 +322,9 @@ interface SecurityAvailability {
 
 #### Features
 
-- ✅ Results automatically cached
-- ✅ Single native call per app lifecycle
-- ✅ Refetch on demand
+- ✅ Result cached **per component instance** — no native call on re-render
+- ✅ `refetch()` available to bypass the cache after settings changes
+- ✅ Previous data preserved on error
 
 #### Example
 
@@ -469,29 +469,19 @@ function LogoutButton() {
 All hooks work independently without any provider. Just import and use them directly in your components:
 
 ```tsx
-import { 
-  useSecureStorage, 
-  useSecurityAvailability 
-} from 'react-native-sensitive-info'
+import {
+  useSecureStorage,
+  useSecurityAvailability,
+} from 'react-native-sensitive-info/hooks'
 
 function MyComponent() {
   const { items } = useSecureStorage({ service: 'myapp' })
   const { data: capabilities } = useSecurityAvailability()
-  
-  // Results are cached automatically - no duplicate native calls
-  // even if used in multiple components
-}
-```
-
-**Automatic caching:**
-```tsx
-// Component A
-const { data: cap1 } = useSecurityAvailability()
 
-// Component B  
-const { data: cap2 } = useSecurityAvailability()
-
-// Both get the SAME cached result - only one native call made!
+  // Each hook instance keeps its own cache. Mounting `useSecurityAvailability`
+  // in two components issues two native reads (one per instance), but neither
+  // re-runs across re-renders unless you call `refetch()`.
+}
 ```
 
 ---
@@ -577,25 +567,20 @@ const refresh = useSecretItem('refreshToken')
 const apiKey = useSecretItem('apiKey')
 ```
 
-### 6. Share Capabilities Without Context
+### 6. Capability Caching Is Per-Instance
 
-Results are cached automatically - no duplicate native calls:
+Each `useSecurityAvailability` mount keeps its own cache, so re-renders never trigger a fresh
+native call. Multiple components mounting the hook will each issue one read — if you need a
+single source of truth, lift the hook into a parent and pass `data` down via props.
 
 ```tsx
-// ✅ GOOD: Multiple independent queries
-function ComponentA() {
-  const { data: cap1 } = useSecurityAvailability()
-  // Native call happens
-}
-
-function ComponentB() {
-  const { data: cap2 } = useSecurityAvailability()
-  // Returns cached result from ComponentA - no new native call!
+// ✅ Re-renders are free — first mount caches, subsequent renders reuse the value.
+function Capabilities() {
+  const { data, isLoading, refetch } = useSecurityAvailability()
+  // Call refetch() after the user changes biometric enrollment in system settings.
 }
 ```
 
-### 7. Optional Context for Deep Trees (if needed)
-
 ### 7. Accessing Security Capabilities
 
 Check what security features are available on the device:
@@ -768,8 +753,8 @@ function Component() {
 ```tsx
 import {
   useSecret,
-  useSecurityAvailability
-} from 'react-native-sensitive-info'
+  useSecurityAvailability,
+} from 'react-native-sensitive-info/hooks'
 
 function AuthenticationFlow() {
   const {

example/src/components/StorageCard.tsx

@@ -8,12 +8,14 @@ import {
 	type SensitiveInfoOptions,
 	setItem,
 } from 'react-native-sensitive-info'
-import { useSecureStorage } from 'react-native-sensitive-info/hooks'
+import {
+	useSecureOperation,
+	useSecureStorage,
+} from 'react-native-sensitive-info/hooks'
 import Button from './Button'
 import Field from './Field'
 import Section from './Section'
 import StatusLine from './StatusLine'
-import { useAsyncAction } from './useAsyncAction'
 
 interface StorageCardProps {
 	readonly readOptions: SensitiveInfoOptions
@@ -62,40 +64,52 @@ const StorageCard = ({ readOptions, writeOptions }: StorageCardProps) => {
 
 	const refresh = storage.refreshItems
 
-	const save = useAsyncAction(async () => {
-		if (!trimmedKey) return
-		await setItem(trimmedKey, value, writeOptions)
-		await refresh()
-		setStatus(`Saved “${trimmedKey}”.`)
-	})
+	const save = useSecureOperation()
+	const revealAction = useSecureOperation()
+	const remove = useSecureOperation()
+	const clearAll = useSecureOperation()
 
-	const revealAction = useAsyncAction(async () => {
-		if (!trimmedKey) return
-		// `getItem` is the only read needing `writeOptions` — it triggers the auth
-		// prompt for biometric-locked entries.
-		const item = await getItem(trimmedKey, writeOptions)
-		if (item?.value == null) return setStatus(`No value for “${trimmedKey}”.`)
-		setReveal({
-			key: trimmedKey,
-			value: item.value,
-			remaining: REVEAL_TTL_SECONDS,
+	const handleSave = () =>
+		void save.execute(async () => {
+			if (!trimmedKey) return
+			await setItem(trimmedKey, value, writeOptions)
+			await refresh()
+			setStatus(`Saved “${trimmedKey}”.`)
 		})
-	})
 
-	const remove = useAsyncAction(async () => {
-		if (!trimmedKey) return
-		await deleteItem(trimmedKey, writeOptions)
-		await refresh()
-		setReveal((prev) => (prev?.key === trimmedKey ? null : prev))
-		setStatus(`Deleted “${trimmedKey}”.`)
-	})
+	const handleReveal = () =>
+		void revealAction.execute(async () => {
+			if (!trimmedKey) return
+			// `getItem` is the only read needing `writeOptions` — it triggers the auth
+			// prompt for biometric-locked entries.
+			const item = await getItem(trimmedKey, writeOptions)
+			if (item?.value == null) {
+				setStatus(`No value for “${trimmedKey}”.`)
+				return
+			}
+			setReveal({
+				key: trimmedKey,
+				value: item.value,
+				remaining: REVEAL_TTL_SECONDS,
+			})
+		})
 
-	const clearAll = useAsyncAction(async () => {
-		await clearService(readOptions)
-		await refresh()
-		setReveal(null)
-		setStatus('Service cleared.')
-	})
+	const handleRemove = () =>
+		void remove.execute(async () => {
+			if (!trimmedKey) return
+			await deleteItem(trimmedKey, writeOptions)
+			await refresh()
+			setReveal((prev) => (prev?.key === trimmedKey ? null : prev))
+			setStatus(`Deleted “${trimmedKey}”.`)
+		})
+
+	const handleClearAll = () =>
+		void clearAll.execute(async () => {
+			await clearService(readOptions)
+			await refresh()
+			setReveal(null)
+			setStatus('Service cleared.')
+		})
 
 	const busy =
 		save.isPending ||
@@ -136,28 +150,28 @@ const StorageCard = ({ readOptions, writeOptions }: StorageCardProps) => {
 			<View style={styles.row}>
 				<Button
 					label="Save"
-					onPress={() => void save.run()}
+					onPress={handleSave}
 					disabled={!trimmedKey || busy}
 					isPending={save.isPending}
 					variant="primary"
 				/>
 				<Button
 					label={revealing ? `Hiding in ${reveal?.remaining}s` : 'Reveal'}
-					onPress={() => void revealAction.run()}
+					onPress={handleReveal}
 					disabled={!exists || busy || revealing}
 					isPending={revealAction.isPending}
 				/>
 				<Button
 					label="Delete"
-					onPress={() => void remove.run()}
+					onPress={handleRemove}
 					disabled={!exists || busy}
 					isPending={remove.isPending}
 					variant="danger"
 				/>
 			</View>
 
 			<Pressable
-				onPress={() => void clearAll.run()}
+				onPress={handleClearAll}
 				disabled={busy || empty}
 				style={({ pressed }) => [
 					styles.clearLink,

example/src/components/useAsyncAction.ts

@@ -2,6 +2,8 @@ export {
 	type AsyncState,
 	createHookFailureResult,
 	createHookSuccessResult,
+	createInitialAsyncState,
+	createInitialVoidState,
 	HookError,
 	type HookErrorOptions,
 	type HookFailureResult,

src/hooks/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Structural equality used by the hooks layer to keep memoized option references
+ * stable across renders.
+ *
+ * @remarks
+ * - Compares primitives with `Object.is` (correctly equating `NaN` and distinguishing `+0`/`-0`).
+ * - Recurses into plain objects and arrays.
+ * - Treats `{ a: undefined }` and `{}` as **different** (unlike `JSON.stringify`).
+ * - Compares own enumerable keys only — does not walk prototypes.
+ * - Returns `false` (rather than recursing) for instances of `Date`, `RegExp`, `Map`, `Set`,
+ *   functions, and any other non-plain object: option payloads are POJOs by contract, and these
+ *   types should never appear there. Guarding against them prevents accidental false positives.
+ *
+ * @internal
+ */
+export default function deepEqual(a: unknown, b: unknown): boolean {
+	if (Object.is(a, b)) return true
+	if (a === null || b === null) return false
+	if (typeof a !== 'object' || typeof b !== 'object') return false
+
+	const aIsArray = Array.isArray(a)
+	const bIsArray = Array.isArray(b)
+	if (aIsArray !== bIsArray) return false
+
+	if (aIsArray) {
+		const arrA = a as readonly unknown[]
+		const arrB = b as readonly unknown[]
+		if (arrA.length !== arrB.length) return false
+		for (let i = 0; i < arrA.length; i++) {
+			if (!deepEqual(arrA[i], arrB[i])) return false
+		}
+		return true
+	}
+
+	if (!isPlainObject(a) || !isPlainObject(b)) return false
+
+	const keysA = Object.keys(a)
+	const keysB = Object.keys(b)
+	if (keysA.length !== keysB.length) return false
+
+	for (const key of keysA) {
+		if (!Object.hasOwn(b, key)) return false
+		if (!deepEqual(a[key], b[key])) return false
+	}
+	return true
+}
+
+function isPlainObject(value: object): value is Record<string, unknown> {
+	const proto = Object.getPrototypeOf(value)
+	return proto === Object.prototype || proto === null
+}