Add useAsyncQuery and refactor hooks/tests

Introduce a shared useAsyncQuery hook to centralize stable-options → skip → memoize → useAsync semantics and ensure consistent abort/skip behavior across hooks. Refactor useHasSecret and useSecretItem to use the new hook. Add deterministic test fixtures (buildTestItem/buildTestMetadata) and update unit tests to use them. Adjust error imports to prefer the public errors surface and remove legacy re-exports from src/internal/errors.ts. Bump package version to 6.0.0-rc.13. Files added: src/hooks/useAsyncQuery.ts, src/__tests__/__mocks__/fixtures.ts; files updated: multiple hooks, tests, and internal error helpers.

Author: mCodex

src/__tests__/__mocks__/fixtures.ts

@@ -0,0 +1,42 @@
+import type {
+	SensitiveInfoItem,
+	StorageMetadata,
+} from '../../sensitive-info.nitro'
+
+type MetadataOverrides = Partial<StorageMetadata>
+
+/**
+ * Builds a deterministic `StorageMetadata` for tests. Override any field by passing it in.
+ *
+ * @internal
+ */
+export const buildTestMetadata = (
+	overrides: MetadataOverrides = {}
+): StorageMetadata => ({
+	securityLevel: 'secureEnclave',
+	backend: 'keychain',
+	accessControl: 'secureEnclaveBiometry',
+	timestamp: 1,
+	...overrides,
+})
+
+/**
+ * Builds a deterministic `SensitiveInfoItem`. `metadata` overrides flow through to
+ * {@link buildTestMetadata}; top-level fields override the item shell.
+ *
+ * @internal
+ */
+export const buildTestItem = (
+	overrides: Partial<SensitiveInfoItem> & {
+		readonly metadata?: MetadataOverrides
+	} = {}
+): SensitiveInfoItem => {
+	const { metadata, ...rest } = overrides
+	return {
+		key: 'token',
+		service: 'auth',
+		value: undefined,
+		...rest,
+		metadata: buildTestMetadata(metadata),
+	}
+}

src/__tests__/hooks.useSecretItem.test.tsx

@@ -3,6 +3,7 @@ import { act, renderHook } from '@testing-library/react'
 import { getItem } from '../core/storage'
 import { HookError } from '../hooks/types'
 import { useSecretItem } from '../hooks/useSecretItem'
+import { buildTestItem } from './__mocks__/fixtures'
 
 jest.mock('../core/storage', () => ({
 	...jest.requireActual('../core/storage'),
@@ -17,17 +18,7 @@ describe('useSecretItem', () => {
 	})
 
 	it('returns the fetched item', async () => {
-		mockedGetItem.mockResolvedValueOnce({
-			key: 'token',
-			service: 'auth',
-			value: 'value',
-			metadata: {
-				securityLevel: 'secureEnclave',
-				backend: 'keychain',
-				accessControl: 'secureEnclaveBiometry',
-				timestamp: 1,
-			},
-		})
+		mockedGetItem.mockResolvedValueOnce(buildTestItem({ value: 'value' }))
 
 		const { result } = renderHook(
 			({ opts }: { opts: Parameters<typeof useSecretItem>[1] }) =>
@@ -82,16 +73,9 @@ describe('useSecretItem', () => {
 	})
 
 	it('allows manual refetching', async () => {
-		mockedGetItem.mockResolvedValueOnce(null).mockResolvedValueOnce({
-			key: 'token',
-			service: 'auth',
-			metadata: {
-				securityLevel: 'secureEnclave',
-				backend: 'keychain',
-				accessControl: 'secureEnclaveBiometry',
-				timestamp: 2,
-			},
-		})
+		mockedGetItem
+			.mockResolvedValueOnce(null)
+			.mockResolvedValueOnce(buildTestItem({ metadata: { timestamp: 2 } }))
 
 		const { result } = renderHook(
 			({ opts }: { opts: Parameters<typeof useSecretItem>[1] }) =>

src/__tests__/hooks.useSecureStorage.test.tsx

@@ -6,6 +6,7 @@ import {
 	type UseSecureStorageOptions,
 	useSecureStorage,
 } from '../hooks/useSecureStorage'
+import { buildTestItem, buildTestMetadata } from './__mocks__/fixtures'
 
 jest.mock('../core/storage', () => ({
 	...jest.requireActual('../core/storage'),
@@ -22,45 +23,6 @@ const mockedClearService = clearService as jest.MockedFunction<
 	typeof clearService
 >
 
-type MetadataOverrides = {
-	securityLevel?:
-		| 'secureEnclave'
-		| 'strongBox'
-		| 'biometry'
-		| 'deviceCredential'
-		| 'software'
-	backend?: 'keychain' | 'androidKeystore' | 'encryptedSharedPreferences'
-	accessControl?:
-		| 'secureEnclaveBiometry'
-		| 'biometryCurrentSet'
-		| 'biometryAny'
-		| 'devicePasscode'
-		| 'none'
-	timestamp?: number
-}
-
-function buildMetadata(overrides: MetadataOverrides = {}) {
-	return {
-		securityLevel: overrides.securityLevel ?? 'secureEnclave',
-		backend: overrides.backend ?? 'keychain',
-		accessControl: overrides.accessControl ?? 'secureEnclaveBiometry',
-		timestamp: overrides.timestamp ?? Date.now(),
-	}
-}
-
-const buildItem = (
-	overrides: MetadataOverrides & {
-		key?: string
-		service?: string
-		value?: string
-	} = {}
-) => ({
-	key: overrides.key ?? 'token',
-	service: overrides.service ?? 'auth',
-	value: overrides.value,
-	metadata: buildMetadata(overrides),
-})
-
 describe('useSecureStorage', () => {
 	beforeEach(() => {
 		mockedGetAllItems.mockReset()
@@ -79,7 +41,9 @@ describe('useSecureStorage', () => {
 		)
 
 	it('loads items on mount', async () => {
-		mockedGetAllItems.mockResolvedValueOnce([buildItem({ value: 'secret' })])
+		mockedGetAllItems.mockResolvedValueOnce([
+			buildTestItem({ value: 'secret' }),
+		])
 
 		const { result } = renderStorage({ service: 'auth', includeValues: true })
 
@@ -118,7 +82,7 @@ describe('useSecureStorage', () => {
 	it('exposes a refresh helper', async () => {
 		mockedGetAllItems
 			.mockResolvedValueOnce([])
-			.mockResolvedValueOnce([buildItem({ key: 'next' })])
+			.mockResolvedValueOnce([buildTestItem({ key: 'next' })])
 
 		const { result } = renderStorage({ service: 'auth' })
 
@@ -135,7 +99,7 @@ describe('useSecureStorage', () => {
 
 	it('saves items and refreshes the list', async () => {
 		mockedGetAllItems.mockResolvedValue([])
-		mockedSetItem.mockResolvedValueOnce({ metadata: buildMetadata() })
+		mockedSetItem.mockResolvedValueOnce({ metadata: buildTestMetadata() })
 
 		const { result } = renderStorage({ service: 'auth', includeValues: true })
 
@@ -171,7 +135,7 @@ describe('useSecureStorage', () => {
 
 	it('removes items locally when delete succeeds', async () => {
 		mockedGetAllItems.mockResolvedValueOnce([
-			buildItem({ key: 'token', value: 'secret' }),
+			buildTestItem({ key: 'token', value: 'secret' }),
 		])
 		mockedDeleteItem.mockResolvedValueOnce(true)
 
@@ -208,7 +172,7 @@ describe('useSecureStorage', () => {
 
 	it('clears the service and resets local state', async () => {
 		mockedGetAllItems.mockResolvedValueOnce([
-			buildItem({ key: 'token', value: 'secret' }),
+			buildTestItem({ key: 'token', value: 'secret' }),
 		])
 		mockedClearService.mockResolvedValueOnce()
 

src/__tests__/internal.errors.test.ts

@@ -1,4 +1,5 @@
-import { getErrorMessage, isNotFoundError } from '../internal/errors'
+import { isNotFoundError } from '../errors'
+import { getErrorMessage } from '../internal/errors'
 
 describe('internal/errors', () => {
 	describe('isNotFoundError', () => {

src/hooks/error-utils.ts

@@ -1,7 +1,5 @@
-import {
-	getErrorMessage,
-	isAuthenticationCanceledError as internalIsAuthenticationCanceledError,
-} from '../internal/errors'
+import { isAuthenticationCanceledError as internalIsAuthenticationCanceledError } from '../errors'
+import { getErrorMessage } from '../internal/errors'
 import { HookError } from './types'
 
 /**

src/hooks/useAsyncQuery.ts

@@ -0,0 +1,36 @@
+import { useCallback, useMemo } from 'react'
+import type { SensitiveInfoOptions } from '../sensitive-info.nitro'
+import useAsync, { type UseAsyncResult } from './useAsync'
+import useStableOptions from './useStableOptions'
+
+/**
+ * Shared "stable options → strip skip → memoize → useAsync" recipe used by every parameterized
+ * data-fetching hook. Keeps `useHasSecret`/`useSecretItem` (and friends) down to a single call
+ * site and ensures the abort/skip semantics stay consistent across the public surface.
+ *
+ * @internal
+ */
+const useAsyncQuery = <T, O extends { readonly skip?: boolean }>(
+	runner: (request: SensitiveInfoOptions) => Promise<T | null>,
+	defaults: Required<Pick<O, 'skip'>> & Partial<Omit<O, 'skip'>>,
+	operation: string,
+	options: O | undefined,
+	hint?: string
+): UseAsyncResult<T> => {
+	const stable = useStableOptions<O>(defaults as Partial<O>, options)
+	const { skip } = stable
+
+	const requestOptions = useMemo<SensitiveInfoOptions>(() => {
+		const { skip: _skip, ...rest } = stable
+		return rest as SensitiveInfoOptions
+	}, [stable])
+
+	const run = useCallback(
+		() => runner(requestOptions),
+		[runner, requestOptions]
+	)
+
+	return useAsync<T>(run, operation, { skip, hint })
+}
+
+export default useAsyncQuery

src/hooks/useHasSecret.ts

@@ -1,9 +1,7 @@
-import { useCallback, useMemo } from 'react'
 import { hasItem } from '../core/storage'
 import type { SensitiveInfoOptions } from '../sensitive-info.nitro'
 import type { AsyncState } from './types'
-import useAsync from './useAsync'
-import useStableOptions from './useStableOptions'
+import useAsyncQuery from './useAsyncQuery'
 
 export interface UseHasSecretOptions extends SensitiveInfoOptions {
 	/** Disable the automatic existence check while still exposing `refetch`. */
@@ -23,20 +21,11 @@ export function useHasSecret(
 	key: string,
 	options?: UseHasSecretOptions
 ): UseHasSecretResult {
-	const stable = useStableOptions<UseHasSecretOptions>(DEFAULTS, options)
-	const { skip } = stable
-	const requestOptions = useMemo<SensitiveInfoOptions>(() => {
-		const { skip: _s, ...rest } = stable
-		return rest
-	}, [stable])
-
-	const run = useCallback(
-		() => hasItem(key, requestOptions),
-		[key, requestOptions]
+	return useAsyncQuery<boolean, UseHasSecretOptions>(
+		(request) => hasItem(key, request),
+		DEFAULTS,
+		'useHasSecret.evaluate',
+		options,
+		'Most commonly triggered by an invalid key/service combination.'
 	)
-
-	return useAsync<boolean>(run, 'useHasSecret.evaluate', {
-		hint: 'Most commonly triggered by an invalid key/service combination.',
-		skip,
-	})
 }

src/hooks/useSecretItem.ts

@@ -1,12 +1,10 @@
-import { useCallback, useMemo } from 'react'
 import { getItem } from '../core/storage'
 import type {
 	SensitiveInfoItem,
 	SensitiveInfoOptions,
 } from '../sensitive-info.nitro'
 import type { AsyncState } from './types'
-import useAsync from './useAsync'
-import useStableOptions from './useStableOptions'
+import useAsyncQuery from './useAsyncQuery'
 
 export interface UseSecretItemOptions extends SensitiveInfoOptions {
 	/** When `false`, skip decrypting the value and return metadata only. Defaults to `true`. */
@@ -32,20 +30,11 @@ export function useSecretItem(
 	key: string,
 	options?: UseSecretItemOptions
 ): UseSecretItemResult {
-	const stable = useStableOptions<UseSecretItemOptions>(DEFAULTS, options)
-	const { skip } = stable
-	const requestOptions = useMemo<SensitiveInfoOptions>(() => {
-		const { skip: _s, ...rest } = stable
-		return rest as SensitiveInfoOptions
-	}, [stable])
-
-	const run = useCallback(
-		() => getItem(key, requestOptions),
-		[key, requestOptions]
+	return useAsyncQuery<SensitiveInfoItem, UseSecretItemOptions>(
+		(request) => getItem(key, request),
+		DEFAULTS,
+		'useSecretItem.fetch',
+		options,
+		'Verify that the key/service pair exists and that includeValue is allowed for the caller.'
 	)
-
-	return useAsync<SensitiveInfoItem>(run, 'useSecretItem.fetch', {
-		hint: 'Verify that the key/service pair exists and that includeValue is allowed for the caller.',
-		skip,
-	})
 }

src/internal/errors.ts

@@ -1,15 +1,9 @@
 /**
- * Legacy re-export surface kept for backward compatibility. New code should import from
- * `react-native-sensitive-info/errors` (or `src/errors.ts`) directly so that typed classes and
- * predicates tree-shake cleanly.
+ * Internal error helpers used by hook-side code paths. Public predicates and typed error classes
+ * live in `src/errors.ts` (exposed via the `react-native-sensitive-info/errors` subpath); import
+ * them from there directly.
  */
 
-export {
-	isAuthenticationCanceledError,
-	isNotFoundError,
-	toSensitiveInfoError,
-} from '../errors'
-
 /**
  * Extracts a human-readable message from arbitrary error values.
  */