hooks: add HookMutationResult + result helpers; refactor hooks and option sanitizers; export helpers

Introduce HookSuccessResult, HookFailureResult, HookMutationResult and factory helpers
(createHookSuccessResult / createHookFailureResult). Refactor useSecret and useSecureStorage
to return the unified HookMutationResult and use the new factories. Simplify option
sanitization by stripping hook-only flags with destructuring. Export the new helpers from
the package entrypoint.

Author: mCodex

src/hooks/index.ts

@@ -3,6 +3,11 @@ export {
   type HookErrorOptions,
   type AsyncState,
   type VoidAsyncState,
+  type HookMutationResult,
+  type HookSuccessResult,
+  type HookFailureResult,
+  createHookSuccessResult,
+  createHookFailureResult,
 } from './types'
 export {
   useSecretItem,

src/hooks/types.ts

@@ -46,6 +46,27 @@ export interface VoidAsyncState {
   readonly isPending: boolean
 }
 
+/**
+ * Successful outcome produced by hook mutation helpers.
+ */
+export interface HookSuccessResult {
+  readonly success: true
+  readonly error?: undefined
+}
+
+/**
+ * Failure outcome produced by hook mutation helpers.
+ */
+export interface HookFailureResult {
+  readonly success: false
+  readonly error: HookError
+}
+
+/**
+ * Combined type returned by hook mutation helpers (`saveSecret`, `clearAll`, ...).
+ */
+export type HookMutationResult = HookSuccessResult | HookFailureResult
+
 /**
  * Factory used to initialise {@link AsyncState} values.
  */
@@ -68,3 +89,17 @@ export function createInitialVoidState(): VoidAsyncState {
     isPending: false,
   }
 }
+
+/**
+ * Helper used to return a canonical success result from mutation helpers.
+ */
+export function createHookSuccessResult(): HookSuccessResult {
+  return { success: true }
+}
+
+/**
+ * Helper used to return a canonical failure result from mutation helpers.
+ */
+export function createHookFailureResult(error: HookError): HookFailureResult {
+  return { success: false, error }
+}

src/hooks/useSecret.ts

@@ -4,8 +4,12 @@ import type {
   SensitiveInfoOptions,
 } from '../sensitive-info.nitro'
 import { deleteItem, setItem } from '../core/storage'
-import { HookError } from './types'
-import type { AsyncState } from './types'
+import {
+  createHookFailureResult,
+  createHookSuccessResult,
+  type HookMutationResult,
+  type AsyncState,
+} from './types'
 import { useSecretItem, type UseSecretItemOptions } from './useSecretItem'
 import createHookError from './error-utils'
 
@@ -19,27 +23,21 @@ export type UseSecretOptions = UseSecretItemOptions
  * Result bag returned by {@link useSecret}.
  */
 export interface UseSecretResult extends AsyncState<SensitiveInfoItem> {
-  readonly saveSecret: (
-    value: string
-  ) => Promise<{ success: boolean; error?: HookError }>
-  readonly deleteSecret: () => Promise<{ success: boolean; error?: HookError }>
+  readonly saveSecret: (value: string) => Promise<HookMutationResult>
+  readonly deleteSecret: () => Promise<HookMutationResult>
   readonly refetch: () => Promise<void>
 }
 
 /**
  * Removes hook-specific flags before delegating to the storage module.
  */
-const stripHookFlags = (options: UseSecretOptions): SensitiveInfoOptions => {
-  const sanitized = { ...options } as Record<string, unknown>
-  delete sanitized.skip
-  delete sanitized.includeValue
-  return sanitized as SensitiveInfoOptions
-}
-
 const normalizeMutationOptions = (
   options?: UseSecretOptions
-): SensitiveInfoOptions | undefined =>
-  options ? stripHookFlags(options) : undefined
+): SensitiveInfoOptions | undefined => {
+  if (!options) return undefined
+  const { skip: _skip, includeValue: _includeValue, ...core } = options
+  return core as SensitiveInfoOptions
+}
 
 /**
  * Maintains a secure item while exposing imperative helpers to mutate or refresh it.
@@ -63,14 +61,14 @@ export function useSecret(
       try {
         await setItem(key, value, normalizeMutationOptions(options))
         await refetch()
-        return { success: true } as const
+        return createHookSuccessResult()
       } catch (errorLike) {
         const hookError = createHookError(
           'useSecret.saveSecret',
           errorLike,
           'Check the access control requirements for this key.'
         )
-        return { success: false, error: hookError } as const
+        return createHookFailureResult(hookError)
       }
     },
     [key, options, refetch]
@@ -80,14 +78,14 @@ export function useSecret(
     try {
       await deleteItem(key, normalizeMutationOptions(options))
       await refetch()
-      return { success: true } as const
+      return createHookSuccessResult()
     } catch (errorLike) {
       const hookError = createHookError(
         'useSecret.deleteSecret',
         errorLike,
         'Ensure the user completed biometric prompts or that the key is spelled correctly.'
       )
-      return { success: false, error: hookError } as const
+      return createHookFailureResult(hookError)
     }
   }, [key, options, refetch])
 

src/hooks/useSecureStorage.ts

@@ -4,7 +4,12 @@ import type {
   SensitiveInfoOptions,
 } from '../sensitive-info.nitro'
 import { clearService, deleteItem, getAllItems, setItem } from '../core/storage'
-import { HookError } from './types'
+import {
+  HookError,
+  createHookFailureResult,
+  createHookSuccessResult,
+  type HookMutationResult,
+} from './types'
 import useAsyncLifecycle from './useAsyncLifecycle'
 import useStableOptions from './useStableOptions'
 import createHookError from './error-utils'
@@ -32,10 +37,8 @@ const DEFAULTS: Required<
 const extractCoreOptions = (
   options: UseSecureStorageOptions
 ): SensitiveInfoOptions => {
-  const sanitized = { ...options } as Record<string, unknown>
-  delete sanitized.skip
-  delete sanitized.includeValues
-  return sanitized as SensitiveInfoOptions
+  const { skip: _skip, includeValues: _includeValues, ...core } = options
+  return core as SensitiveInfoOptions
 }
 
 /**
@@ -48,11 +51,9 @@ export interface UseSecureStorageResult {
   readonly saveSecret: (
     key: string,
     value: string
-  ) => Promise<{ success: boolean; error?: HookError }>
-  readonly removeSecret: (
-    key: string
-  ) => Promise<{ success: boolean; error?: HookError }>
-  readonly clearAll: () => Promise<{ success: boolean; error?: HookError }>
+  ) => Promise<HookMutationResult>
+  readonly removeSecret: (key: string) => Promise<HookMutationResult>
+  readonly clearAll: () => Promise<HookMutationResult>
   readonly refreshItems: () => Promise<void>
 }
 
@@ -134,7 +135,7 @@ export function useSecureStorage(
         if (mountedRef.current) {
           await fetchItems()
         }
-        return { success: true } as const
+        return createHookSuccessResult()
       } catch (errorLike) {
         const hookError = createHookError(
           'useSecureStorage.saveSecret',
@@ -144,7 +145,7 @@ export function useSecureStorage(
         if (mountedRef.current) {
           setError(hookError)
         }
-        return { success: false, error: hookError } as const
+        return createHookFailureResult(hookError)
       }
     },
     [fetchItems, mountedRef, stableOptions]
@@ -157,7 +158,7 @@ export function useSecureStorage(
         if (mountedRef.current) {
           setItems((prev) => prev.filter((item) => item.key !== key))
         }
-        return { success: true } as const
+        return createHookSuccessResult()
       } catch (errorLike) {
         const hookError = createHookError(
           'useSecureStorage.removeSecret',
@@ -167,7 +168,7 @@ export function useSecureStorage(
         if (mountedRef.current) {
           setError(hookError)
         }
-        return { success: false, error: hookError } as const
+        return createHookFailureResult(hookError)
       }
     },
     [mountedRef, stableOptions]
@@ -180,7 +181,7 @@ export function useSecureStorage(
         setItems([])
         setError(null)
       }
-      return { success: true } as const
+      return createHookSuccessResult()
     } catch (errorLike) {
       const hookError = createHookError(
         'useSecureStorage.clearAll',
@@ -190,7 +191,7 @@ export function useSecureStorage(
       if (mountedRef.current) {
         setError(hookError)
       }
-      return { success: false, error: hookError } as const
+      return createHookFailureResult(hookError)
     }
   }, [mountedRef, stableOptions])
 

src/index.ts

@@ -1,5 +1,24 @@
 /* eslint-disable no-restricted-exports -- Preserve the default export for backwards compatibility. */
 
+export type {
+  AccessControl,
+  AuthenticationPrompt,
+  MutationResult,
+  SecurityAvailability,
+  SecurityLevel,
+  SensitiveInfo as SensitiveInfoModule,
+  SensitiveInfoSpec,
+  SensitiveInfoDeleteRequest,
+  SensitiveInfoEnumerateRequest,
+  SensitiveInfoGetRequest,
+  SensitiveInfoHasRequest,
+  SensitiveInfoItem,
+  SensitiveInfoOptions,
+  SensitiveInfoSetRequest,
+  StorageBackend,
+  StorageMetadata,
+} from './sensitive-info.nitro'
+
 /**
  * Core storage helpers that mirror the native Nitro surface.
  */
@@ -22,12 +41,17 @@ export { default } from './core/storage'
  */
 export {
   HookError,
+  createHookFailureResult,
+  createHookSuccessResult,
   useHasSecret,
   useSecret,
   useSecretItem,
   useSecureOperation,
   useSecureStorage,
   useSecurityAvailability,
+  type HookFailureResult,
+  type HookMutationResult,
+  type HookSuccessResult,
   type UseHasSecretOptions,
   type UseHasSecretResult,
   type UseSecretItemOptions,