@alneas/appkit-react 0.1.0 → 0.2.0

package/dist/tools/lib/data-access/react-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"react-query.js","names":["tanstackQueryOptions","createQueryClient","QueryClient","useInvalidate","queryClient","useQueryClient","key","useMutationWithInvalidation","useMutation","options","keys","data","variables","context","findQueryOptions","queryOptions","collection","filter","adapterOptions","getAdapterCacheScope","adapter","findOneQueryOptions","id","aggregateQueryOptions","pipeline","useFind","useDataAccess","useQuery","useFindOne","useCreate","vars","useUpdate","useDelete","useCreateMany","useUpdateMany","useDeleteMany","useAggregate","aggOptions"],"sources":["../../../../src/tools/lib/data-access/react-query.tsx"],"sourcesContent":["import {\n  useQuery,\n  UseQueryOptions,\n  QueryClient,\n  useQueryClient,\n  useMutation,\n  UseMutationOptions,\n  MutationFunction,\n  queryOptions as tanstackQueryOptions,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport { DataAccessAdapter, Filter, QueryOptions } from './types';\nimport { useDataAccess } from './data-access-context';\nimport { getAdapterCacheScope } from './cache-scope';\n\nexport { useDataAccess } from './data-access-context';\n\n// --- Query Helpers (Merged from query.ts) ---\n\n/**\n * アプリケーション全体で使用する QueryClient を作成します。\n * デフォルト設定として、staleTime: 5分, retry: 1, refetchOnWindowFocus: false が設定されています。\n */\nexport function createQueryClient() {\n  return new QueryClient({\n    defaultOptions: {\n      queries: {\n        staleTime: 1000 * 60 * 5, // 5 minutes\n        retry: 1,\n        refetchOnWindowFocus: false,\n      },\n    },\n  });\n}\n\n/**\n * 指定したキーのクエリキャッシュを手動で無効化（再取得要求）するためのフックです。\n * @returns クエリキーを受け取り、無効化を実行する関数\n */\nexport function useInvalidate() {\n  const queryClient = useQueryClient();\n\n  return (key: QueryKey) => {\n    return queryClient.invalidateQueries({ queryKey: key });\n  };\n}\n\n/**\n * useMutation のラッパーフックです。\n * Mutation 成功時に、指定したキーまたは自動生成されたキーに基づいてクエリの無効化を行います。\n *\n * @param mutationFn - 実行する非同期関数\n * @param options.invalidateKeys - 無効化したいクエリキーの配列、または結果からキーを生成する関数\n */\nexport function useMutationWithInvalidation<\n  TData = unknown,\n  TError = unknown,\n  TVariables = void,\n  TContext = unknown,\n>(\n  mutationFn: MutationFunction<TData, TVariables>,\n  options?: UseMutationOptions<TData, TError, TVariables, TContext> & {\n    invalidateKeys?: QueryKey[] | ((data: TData, variables: TVariables) => QueryKey[]);\n  },\n) {\n  const queryClient = useQueryClient();\n\n  return useMutation({\n    mutationFn,\n    ...options,\n    onSuccess: async (data, variables, context) => {\n      if (options?.invalidateKeys) {\n        const keys =\n          typeof options.invalidateKeys === 'function'\n            ? options.invalidateKeys(data, variables)\n            : options.invalidateKeys;\n\n        await Promise.all(keys.map((key) => queryClient.invalidateQueries({ queryKey: key })));\n      }\n      // @ts-expect-error - Argument count mismatch between supported TanStack Query type versions\n      options?.onSuccess?.(data, variables, context);\n    },\n  });\n}\n\n// --- Query Options Factories ---\n\n/**\n * useFind および ensureQueryData 用の QueryOptions を生成します。\n *\n * @param adapter - DataAccessAdapter インスタンス\n * @param collection - コレクション名\n * @param filter - フィルタ条件\n * @param adapterOptions - クエリオプション\n * @returns TanStack Query 用のオプションオブジェクト\n */\nexport function findQueryOptions<T = unknown>(\n  adapter: DataAccessAdapter,\n  collection: string,\n  filter?: Filter,\n  adapterOptions?: QueryOptions,\n) {\n  return tanstackQueryOptions({\n    queryKey: [collection, 'list', filter, adapterOptions, getAdapterCacheScope(adapter)],\n    queryFn: ({ signal }) => adapter.find<T>(collection, filter, { ...adapterOptions, signal }),\n  });\n}\n\n/**\n * useFindOne および ensureQueryData 用の QueryOptions を生成します。\n *\n * @param adapter - DataAccessAdapter インスタンス\n * @param collection - コレクション名\n * @param id - ドキュメントID\n * @param adapterOptions - クエリオプション\n * @returns TanStack Query 用のオプションオブジェクト\n */\nexport function findOneQueryOptions<T = unknown>(\n  adapter: DataAccessAdapter,\n  collection: string,\n  id: string,\n  adapterOptions?: QueryOptions,\n) {\n  return tanstackQueryOptions({\n    queryKey: [collection, 'detail', id, adapterOptions, getAdapterCacheScope(adapter)],\n    queryFn: ({ signal }) => adapter.findOne<T>(collection, id, { ...adapterOptions, signal }),\n    enabled: !!id,\n  });\n}\n\n/**\n * useAggregate および ensureQueryData 用の QueryOptions を生成します。\n *\n * @param adapter - DataAccessAdapter インスタンス\n * @param collection - コレクション名\n * @param pipeline - Aggregation Pipeline\n * @param options - クエリオプション\n * @returns TanStack Query 用のオプションオブジェクト\n */\nexport function aggregateQueryOptions<T = unknown>(\n  adapter: DataAccessAdapter,\n  collection: string,\n  pipeline: unknown[],\n  options?: QueryOptions,\n) {\n  return tanstackQueryOptions({\n    queryKey: [collection, 'aggregate', pipeline, options, getAdapterCacheScope(adapter)],\n    queryFn: ({ signal }) => {\n      if (adapter.aggregate) {\n        return adapter.aggregate<T>(collection, pipeline, { ...options, signal });\n      }\n      throw new Error('Adapter does not support aggregate');\n    },\n  });\n}\n\n// --- Hooks ---\n\n/**\n * コレクションから複数のレコードを取得し、React Query による自動キャッシュを行います。\n *\n * @param collection - コレクション/テーブル名\n * @param filter - フィルタ条件 ($eq, $in, $gte など)\n * @param adapterOptions - ソート、取得制限、Populate などのオプション\n * @param queryOptions - React Query (useQuery) のオプション (enabled, staleTime など)\n * @returns useQuery の結果オブジェクト (data, isLoading, error等)\n *\n * @example\n * ```tsx\n * const { data: users, isLoading } = useFind<User>('users', { role: 'admin' }, { sort: { name: 1 }, limit: 50 });\n * ```\n */\nexport function useFind<T = unknown>(\n  collection: string,\n  filter?: Filter,\n  adapterOptions?: QueryOptions,\n  queryOptions?: Omit<UseQueryOptions<T[], Error>, 'queryKey' | 'queryFn'>,\n) {\n  const adapter = useDataAccess();\n  const options = findQueryOptions<T>(adapter, collection, filter, adapterOptions);\n  return useQuery({\n    ...options,\n    ...queryOptions,\n  } as UseQueryOptions<T[], Error>);\n}\n\n/**\n * ID指定で単一のデータを取得します。\n *\n * @param collection - 取得対象のコレクション/テーブル名\n * @param id - ドキュメント/レコードのID\n * @param adapterOptions - Populate などのクエリオプション\n * @param queryOptions - React Query (useQuery) のオプション\n * @returns useQuery の結果オブジェクト (data, isLoading, error等)\n */\nexport function useFindOne<T = unknown>(\n  collection: string,\n  id: string,\n  adapterOptions?: QueryOptions,\n  queryOptions?: Omit<UseQueryOptions<T | null, Error>, 'queryKey' | 'queryFn'>,\n) {\n  const adapter = useDataAccess();\n  const options = findOneQueryOptions<T>(adapter, collection, id, adapterOptions);\n  return useQuery({\n    ...options,\n    ...queryOptions,\n  } as UseQueryOptions<T | null, Error>);\n}\n\n/**\n * 新規データを作成するためのフックです。\n * 成功時にキャッシュの無効化（Invalidation）を自動的に行います。\n *\n * @param collection - 対象のコレクション/テーブル名\n * @param options.onSuccess - 成功時のコールバック\n * @param options.invalidateKeys - 無効化するクエリキー（デフォルトは `[[collection]]`）\n * @returns useMutation の結果オブジェクト (mutate, isLoading等)\n */\nexport function useCreate<\n  T = unknown,\n  TVariables = { data: Record<string, unknown>; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    onSuccess?: (data: T, variables: TVariables) => void;\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T, Error, TVariables>(\n    (variables) => {\n      const vars = variables as { data: Record<string, unknown>; options?: QueryOptions };\n      return adapter.create<T>(collection, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * データを更新するためのフックです。\n * 成功時にリストと詳細のキャッシュを自動的に無効化します。\n *\n * @param collection - 対象のコレクション/テーブル名\n * @param options.onSuccess - 成功時のコールバック\n * @param options.invalidateKeys - 無効化キー（デフォルトはリストと対象IDの詳細）\n * @returns useMutation の結果オブジェクト (mutate, isLoading等)\n */\nexport function useUpdate<\n  T = unknown,\n  TVariables = { id: string; data: Record<string, unknown>; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    onSuccess?: (data: T, variables: TVariables) => void;\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T, Error, TVariables>(\n    (variables) => {\n      const vars = variables as {\n        id: string;\n        data: Record<string, unknown>;\n        options?: QueryOptions;\n      };\n      return adapter.update<T>(collection, vars.id, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      // リストと、特定の詳細アイテムの両方のキャッシュを無効化する\n      invalidateKeys: (_data, variables) => {\n        const vars = variables as { id: string };\n        return (\n          options?.invalidateKeys || [\n            [collection, 'list'],\n            [collection, 'detail', vars.id],\n          ]\n        );\n      },\n    },\n  );\n}\n\n/**\n * データを削除するためのフックです。\n *\n * @param collection - 対象のコレクション/テーブル名\n * @param options.onSuccess - 成功時のコールバック\n * @param options.invalidateKeys - 無効化キー\n * @returns useMutation の結果オブジェクト (mutate, isLoading等)\n */\nexport function useDelete<T = unknown, TVariables = { id: string; options?: QueryOptions }>(\n  collection: string,\n  options?: {\n    onSuccess?: (data: T, variables: TVariables) => void;\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T, Error, TVariables>(\n    (variables) => {\n      const vars = (typeof variables === 'string' ? { id: variables } : variables) as {\n        id: string;\n        options?: QueryOptions;\n      };\n      return adapter.delete<T>(collection, vars.id, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * 複数のデータを一括作成するためのフックです。\n *\n * @param collection - 対象のコレクション/テーブル名\n * @param options.onSuccess - 成功時のコールバック\n * @param options.invalidateKeys - 無効化キー（デフォルトは `[[collection]]`）\n * @returns useMutation の結果オブジェクト (mutate, isLoading等)\n */\nexport function useCreateMany<\n  T = unknown,\n  TVariables = { data: Record<string, unknown>[]; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    onSuccess?: (data: T[], variables: TVariables) => void;\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T[], Error, TVariables>(\n    (variables) => {\n      const vars = variables as { data: Record<string, unknown>[]; options?: QueryOptions };\n      if (!adapter.createMany) throw new Error('Adapter does not support createMany');\n      return adapter.createMany<T>(collection, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * 条件に一致する複数のデータを一括更新するためのフックです。\n *\n * @param collection - 対象のコレクション/テーブル名\n * @param options.onSuccess - 成功時のコールバック\n * @param options.invalidateKeys - 無効化キー（デフォルトは `[[collection]]`）\n * @returns useMutation の結果オブジェクト (mutate, isLoading等)\n */\nexport function useUpdateMany<\n  T = unknown,\n  TVariables = { filter: Filter; data: Record<string, unknown>; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    onSuccess?: (data: T[], variables: TVariables) => void;\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T[], Error, TVariables>(\n    (variables) => {\n      const vars = variables as {\n        filter: Filter;\n        data: Record<string, unknown>;\n        options?: QueryOptions;\n      };\n      if (!adapter.updateMany) throw new Error('Adapter does not support updateMany');\n      return adapter.updateMany<T>(collection, vars.filter, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection], [collection, 'list']],\n    },\n  );\n}\n\n/**\n * 条件に一致する複数のデータを一括削除するためのフックです。\n *\n * @param collection - 対象のコレクション/テーブル名\n * @param options.onSuccess - 成功時のコールバック\n * @param options.invalidateKeys - 無効化キー（デフォルトは `[[collection]]`）\n * @returns useMutation の結果オブジェクト (mutate, isLoading等)\n */\nexport function useDeleteMany<T = unknown, TVariables = { filter: Filter; options?: QueryOptions }>(\n  collection: string,\n  options?: {\n    onSuccess?: (data: T[], variables: TVariables) => void;\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T[], Error, TVariables>(\n    (variables) => {\n      const vars = variables as { filter: Filter; options?: QueryOptions };\n      if (!adapter.deleteMany) throw new Error('Adapter does not support deleteMany');\n      return adapter.deleteMany<T>(collection, vars.filter, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * Aggregation Pipelineを実行するためのフックです。\n *\n * @param collection - 対象のコレクション/テーブル名\n * @param pipeline - Aggregation Pipeline\n * @param options - クエリオプション\n * @param queryOptions - React Query (useQuery) のオプション\n * @returns useQuery の結果オブジェクト (data, isLoading, error等)\n */\nexport function useAggregate<T = unknown>(\n  collection: string,\n  pipeline: unknown[],\n  options?: QueryOptions,\n  queryOptions?: Omit<UseQueryOptions<T[], Error>, 'queryKey' | 'queryFn'>,\n) {\n  const adapter = useDataAccess();\n  const aggOptions = aggregateQueryOptions<T>(adapter, collection, pipeline, options);\n  return useQuery({\n    ...aggOptions,\n    ...queryOptions,\n  } as UseQueryOptions<T[], Error>);\n}\n"],"mappings":"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"}
+{"version":3,"file":"react-query.js","names":["tanstackQueryOptions","createQueryClient","QueryClient","useInvalidate","queryClient","useQueryClient","key","useMutationWithInvalidation","useMutation","options","keys","data","variables","context","findQueryOptions","queryOptions","collection","filter","adapterOptions","getAdapterCacheScope","adapter","findOneQueryOptions","id","aggregateQueryOptions","pipeline","useFind","useDataAccess","useQuery","useFindOne","useCreate","vars","useUpdate","useDelete","useCreateMany","useUpdateMany","useDeleteMany","useAggregate","aggOptions"],"sources":["../../../../src/tools/lib/data-access/react-query.tsx"],"sourcesContent":["import {\n  useQuery,\n  UseQueryOptions,\n  QueryClient,\n  useQueryClient,\n  useMutation,\n  UseMutationOptions,\n  MutationFunction,\n  queryOptions as tanstackQueryOptions,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport { DataAccessAdapter, Filter, QueryOptions } from './types';\nimport { useDataAccess } from './data-access-context';\nimport { getAdapterCacheScope } from './cache-scope';\n\nexport { useDataAccess } from './data-access-context';\n\n// --- Query Helpers (Merged from query.ts) ---\n\n/**\n * Creates a TanStack QueryClient with five-minute stale time, one retry and no focus refetch.\n * @returns New caller-owned client; share one stable client for one application/auth domain.\n * @remarks No requests begin on construction. Supply it to QueryClientProvider; callers\n * own clearing/disposal and SSR request isolation. No CSS is required.\n * @example\n * ```ts\n * import { createQueryClient } from '@alneas/appkit-react/tools/data-access/react';\n * const queryClient = createQueryClient();\n * queryClient.clear();\n * ```\n */\nexport function createQueryClient() {\n  return new QueryClient({\n    defaultOptions: {\n      queries: {\n        staleTime: 1000 * 60 * 5, // 5 minutes\n        retry: 1,\n        refetchOnWindowFocus: false,\n      },\n    },\n  });\n}\n\n/**\n * Binds query invalidation to the nearest QueryClient.\n * @returns Function accepting a query key and resolving after TanStack prefix-matched invalidation/refetch work.\n * @throws Error outside QueryClientProvider.\n * @remarks The returned callback forwards invalidateQueries with queryKey only; it does\n * not establish authorization or choose a collection automatically. No CSS is required.\n * @example\n * ```tsx\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { createQueryClient, useInvalidate } from '@alneas/appkit-react/tools/data-access/react';\n * const client = createQueryClient();\n * function Refresh() { const invalidate = useInvalidate(); return <button onClick={() => { void invalidate(['tasks']); }}>Refresh</button>; }\n * export function Screen() { return <QueryClientProvider client={client}><Refresh /></QueryClientProvider>; }\n * ```\n */\nexport function useInvalidate() {\n  const queryClient = useQueryClient();\n\n  return (key: QueryKey) => {\n    return queryClient.invalidateQueries({ queryKey: key });\n  };\n}\n\n/**\n * Runs a TanStack mutation and invalidates only the explicitly configured query keys on success.\n * @typeParam TData - Resolved mutation result; defaults to unknown and may include undefined.\n * @typeParam TError - Mutation error exposed by TanStack Query; defaults to unknown.\n * @typeParam TVariables - Mutation input supplied to mutate/mutateAsync; defaults to void.\n * @typeParam TContext - Value returned by onMutate for later callbacks; defaults to unknown.\n * @param mutationFn - Host mutation function receiving variables and resolving TData; the host owns authorization and persistence.\n * @param options - TanStack mutation options plus invalidateKeys: a key array or synchronous factory\n * receiving the successful result and variables. Omitted invalidateKeys (or an empty array) invalidates nothing.\n * @returns The TanStack mutation result with status, data/error and mutate/mutateAsync controls.\n * @throws When rendered without a QueryClientProvider.\n * @remarks Requires an outer QueryClientProvider. Query keys use TanStack prefix matching.\n * On success, invalidations run concurrently and are awaited before options.onSuccess is called;\n * that callback's returned promise is not awaited by this wrapper. A key factory or invalidation\n * failure prevents that callback and propagates into mutation error handling. Mutation failures\n * are exposed through the mutation result and reject mutateAsync. This wrapper adds no retry,\n * rollback or default invalidation keys; useCreate/useUpdate supply their own defaults.\n * The normal TanStack options spread also permits options.mutationFn to override the first argument.\n * @example\n * ```tsx\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { createQueryClient, useMutationWithInvalidation } from '@alneas/appkit-react/tools/data-access/react';\n *\n * const queryClient = createQueryClient();\n * type SaveInput = { id: string; title: string };\n * type SaveResult = SaveInput | undefined;\n * function SaveButton({ save }: { save: (input: SaveInput) => Promise<SaveResult> }) {\n *   const mutation = useMutationWithInvalidation(save, {\n *     invalidateKeys: (_result, input) => [['tasks', 'detail', input.id]],\n *   });\n *   return <button onClick={() => mutation.mutate({ id: 'task-1', title: 'Review' })}>\n *     {mutation.data?.title ?? 'Save task'}\n *   </button>;\n * }\n * // Supply an authorized host implementation; this example does not fabricate persistence.\n * export function TaskEditor({ save }: { save: (input: SaveInput) => Promise<SaveResult> }) {\n *   return <QueryClientProvider client={queryClient}><SaveButton save={save} /></QueryClientProvider>;\n * }\n * ```\n */\nexport function useMutationWithInvalidation<\n  TData = unknown,\n  TError = unknown,\n  TVariables = void,\n  TContext = unknown,\n>(\n  mutationFn: MutationFunction<TData, TVariables>,\n  options?: UseMutationOptions<TData, TError, TVariables, TContext> & {\n    /** Optional explicit keys or result/variables key factory; omission invalidates nothing. */\n    invalidateKeys?: QueryKey[] | ((data: TData, variables: TVariables) => QueryKey[]);\n  },\n) {\n  const queryClient = useQueryClient();\n\n  return useMutation({\n    mutationFn,\n    ...options,\n    onSuccess: async (data, variables, context) => {\n      if (options?.invalidateKeys) {\n        const keys =\n          typeof options.invalidateKeys === 'function'\n            ? options.invalidateKeys(data, variables)\n            : options.invalidateKeys;\n\n        await Promise.all(keys.map((key) => queryClient.invalidateQueries({ queryKey: key })));\n      }\n      // @ts-expect-error - Argument count mismatch between supported TanStack Query type versions\n      options?.onSuccess?.(data, variables, context);\n    },\n  });\n}\n\n// --- Query Options Factories ---\n\n/**\n * Creates adapter-scoped TanStack options for listing records.\n * @typeParam T - Expected record/result shape; defaults to unknown and is not runtime validation.\n * @param adapter - Host adapter performing reads.\n * @param collection - Host collection/table name.\n * @param filter - Optional adapter-specific selection criteria.\n * @param adapterOptions - Optional sort/limit/populate/etc. forwarded with TanStack abort signal.\n * @returns Query key and queryFn options accepted by useQuery or QueryClient methods.\n * @remarks Key includes collection, operation, input options and adapter cache scope. No\n * request is made until queryFn executes. Query errors reject through TanStack; aggregate\n * queryFn rejects if the adapter lacks aggregate. Abort signal support is adapter-owned.\n * @example\n * ```ts\n * import type { ComponentProps } from 'react';\n * import { DataAccessProvider, findQueryOptions } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * export function optionsFor(adapter: DataAccessAdapter) { return findQueryOptions<{ id: string }>(adapter, 'tasks', {}, { limit: 20 }); }\n * ```\n */\nexport function findQueryOptions<T = unknown>(\n  adapter: DataAccessAdapter,\n  collection: string,\n  filter?: Filter,\n  adapterOptions?: QueryOptions,\n) {\n  return tanstackQueryOptions({\n    queryKey: [collection, 'list', filter, adapterOptions, getAdapterCacheScope(adapter)],\n    queryFn: ({ signal }) => adapter.find<T>(collection, filter, { ...adapterOptions, signal }),\n  });\n}\n\n/**\n * Creates adapter-scoped TanStack options for reading one record by ID.\n * @typeParam T - Expected record/result shape; defaults to unknown and is not runtime validation.\n * @param adapter - Host adapter performing reads.\n * @param collection - Host collection/table name.\n * @param id - Record identifier; a falsy ID disables the ordinary useQuery execution.\n * @param adapterOptions - Optional adapter query settings forwarded with TanStack abort signal.\n * @returns Query key and queryFn options accepted by useQuery or QueryClient methods.\n * @remarks Key includes collection, operation, input options and adapter cache scope. No\n * request is made until queryFn executes. Query errors reject through TanStack; aggregate\n * queryFn rejects if the adapter lacks aggregate. Abort signal support is adapter-owned.\n * @example\n * ```ts\n * import type { ComponentProps } from 'react';\n * import { DataAccessProvider, findOneQueryOptions } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * export function optionsFor(adapter: DataAccessAdapter) { return findOneQueryOptions<{ id: string }>(adapter, 'tasks', 'task-1'); }\n * ```\n */\nexport function findOneQueryOptions<T = unknown>(\n  adapter: DataAccessAdapter,\n  collection: string,\n  id: string,\n  adapterOptions?: QueryOptions,\n) {\n  return tanstackQueryOptions({\n    queryKey: [collection, 'detail', id, adapterOptions, getAdapterCacheScope(adapter)],\n    queryFn: ({ signal }) => adapter.findOne<T>(collection, id, { ...adapterOptions, signal }),\n    enabled: !!id,\n  });\n}\n\n/**\n * Creates adapter-scoped TanStack options for an aggregation pipeline.\n * @typeParam T - Expected record/result shape; defaults to unknown and is not runtime validation.\n * @param adapter - Host adapter performing reads.\n * @param collection - Host collection/table name.\n * @param pipeline - Adapter-specific aggregation stages.\n * @param options - Optional adapter settings forwarded with TanStack abort signal.\n * @returns Query key and queryFn options accepted by useQuery or QueryClient methods.\n * @remarks Key includes collection, operation, input options and adapter cache scope. No\n * request is made until queryFn executes. Query errors reject through TanStack; aggregate\n * queryFn rejects if the adapter lacks aggregate. Abort signal support is adapter-owned.\n * @example\n * ```ts\n * import type { ComponentProps } from 'react';\n * import { DataAccessProvider, aggregateQueryOptions } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * export function optionsFor(adapter: DataAccessAdapter) { return aggregateQueryOptions<{ count: number }>(adapter, 'tasks', []); }\n * ```\n */\nexport function aggregateQueryOptions<T = unknown>(\n  adapter: DataAccessAdapter,\n  collection: string,\n  pipeline: unknown[],\n  options?: QueryOptions,\n) {\n  return tanstackQueryOptions({\n    queryKey: [collection, 'aggregate', pipeline, options, getAdapterCacheScope(adapter)],\n    queryFn: ({ signal }) => {\n      if (adapter.aggregate) {\n        return adapter.aggregate<T>(collection, pipeline, { ...options, signal });\n      }\n      throw new Error('Adapter does not support aggregate');\n    },\n  });\n}\n\n// --- Hooks ---\n\n/**\n * Queries a collection list through the current adapter.\n * @typeParam T - Expected result record shape, default unknown; not runtime validation.\n * @param collection - Host collection/table name.\n * @param filter - Optional adapter filter.\n * @param adapterOptions - Optional sorting/limit/populate settings.\n * @param queryOptions - TanStack query overrides; omitted values use the generated options.\n * @returns TanStack query result with data/status/error and refetch controls.\n * @throws Error without DataAccessProvider or QueryClientProvider.\n * @remarks No CSS required. Adapter failures appear in query state; keys include adapter\n * scope and input options. Query signals are forwarded, but cancellation depends on the\n * adapter. The host owns backend authorization.\n * @example\n * ```tsx\n * import type { ComponentProps } from 'react';\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useFind } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * const client = createQueryClient();\n * function Content() { const query = useFind<{ id: string }>('tasks', {}, { limit: 20 }); return <output>{query.isPending ? 'Loading' : query.error ? 'Failed' : 'Ready'}</output>; }\n * export function DataScreen({ adapter }: { adapter: DataAccessAdapter }) { return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}><Content /></DataAccessProvider></QueryClientProvider>; }\n * ```\n */\nexport function useFind<T = unknown>(\n  collection: string,\n  filter?: Filter,\n  adapterOptions?: QueryOptions,\n  queryOptions?: Omit<UseQueryOptions<T[], Error>, 'queryKey' | 'queryFn'>,\n) {\n  const adapter = useDataAccess();\n  const options = findQueryOptions<T>(adapter, collection, filter, adapterOptions);\n  return useQuery({\n    ...options,\n    ...queryOptions,\n  } as UseQueryOptions<T[], Error>);\n}\n\n/**\n * Queries one record through the current adapter.\n * @typeParam T - Expected result record shape, default unknown; not runtime validation.\n * @param collection - Host collection/table name.\n * @param id - Record ID; empty ID disables the default query.\n * @param adapterOptions - Optional adapter read settings.\n * @param queryOptions - TanStack query overrides; omitted values use the generated options.\n * @returns TanStack query result with data/status/error and refetch controls. Data resolves to a record or null when absent.\n * @throws Error without DataAccessProvider or QueryClientProvider.\n * @remarks No CSS required. Adapter failures appear in query state; keys include adapter\n * scope and input options. Query signals are forwarded, but cancellation depends on the\n * adapter. The host owns backend authorization.\n * @example\n * ```tsx\n * import type { ComponentProps } from 'react';\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useFindOne } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * const client = createQueryClient();\n * function Content() { const query = useFindOne<{ id: string }>('tasks', 'task-1'); return <output>{query.isPending ? 'Loading' : query.error ? 'Failed' : 'Ready'}</output>; }\n * export function DataScreen({ adapter }: { adapter: DataAccessAdapter }) { return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}><Content /></DataAccessProvider></QueryClientProvider>; }\n * ```\n */\nexport function useFindOne<T = unknown>(\n  collection: string,\n  id: string,\n  adapterOptions?: QueryOptions,\n  queryOptions?: Omit<UseQueryOptions<T | null, Error>, 'queryKey' | 'queryFn'>,\n) {\n  const adapter = useDataAccess();\n  const options = findOneQueryOptions<T>(adapter, collection, id, adapterOptions);\n  return useQuery({\n    ...options,\n    ...queryOptions,\n  } as UseQueryOptions<T | null, Error>);\n}\n\n/**\n * Creates one record through the current data-access adapter and invalidates collection queries.\n * @typeParam T - Created record result returned by the adapter; defaults to unknown.\n * @typeParam TVariables - Mutation variables; must contain data and optional adapter options at runtime.\n * @param collection - Adapter collection/table name.\n * @param options - Optional onSuccess callback receiving the created result and variables, plus replacement\n * invalidation keys. Omitted invalidateKeys defaults to [[collection]]; [] disables invalidation.\n * @returns A mutation result whose mutate/mutateAsync accepts { data, options? } by default.\n * @throws When rendered without the required query or data-access provider.\n * @remarks Requires QueryClientProvider and DataAccessProvider with a real host adapter.\n * The adapter owns persistence, authorization and error semantics. Defaults are supplied by this\n * helper, not useMutationWithInvalidation. Callback promises are not awaited by that wrapper.\n * @example\n * ```tsx\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useCreate } from '@alneas/appkit-react/tools/data-access/react';\n * import type { ComponentProps } from 'react';\n * const client = createQueryClient();\n * function CreateTask() {\n *   const create = useCreate<{ id: string; title: string }>('tasks');\n *   return <button onClick={() => create.mutate({ data: { title: 'Review' } })}>Create</button>;\n * }\n * export function TaskCreator({ adapter }: Pick<ComponentProps<typeof DataAccessProvider>, 'adapter'>) {\n *   return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}>\n *     <CreateTask />\n *   </DataAccessProvider></QueryClientProvider>;\n * }\n * ```\n */\nexport function useCreate<\n  T = unknown,\n  TVariables = { data: Record<string, unknown>; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    /**\n     * Callback after successful mutation and awaited invalidations.\n     * @param data - Adapter result.\n     * @param variables - Original mutation variables.\n     * @returns No value; callback promise results are not awaited by the wrapper.\n     */\n    onSuccess?: (data: T, variables: TVariables) => void;\n    /**\n     * Optional replacement query keys using prefix matching; [] disables invalidation, omission uses this hook default.\n     */\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T, Error, TVariables>(\n    (variables) => {\n      const vars = variables as { data: Record<string, unknown>; options?: QueryOptions };\n      return adapter.create<T>(collection, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * Updates one record through the current adapter and invalidates list and matching detail queries.\n * @typeParam T - Updated record result returned by the adapter; defaults to unknown.\n * @typeParam TVariables - Mutation variables; must contain id, data and optional adapter options at runtime.\n * @param collection - Adapter collection/table name.\n * @param options - Optional onSuccess callback receiving the updated result and variables, plus replacement\n * invalidation keys. Omitted keys default to [[collection, 'list'], [collection, 'detail', variables.id]];\n * [] disables invalidation.\n * @returns A mutation result whose mutate/mutateAsync accepts { id, data, options? } by default.\n * @throws When rendered without the required query or data-access provider.\n * @remarks Requires QueryClientProvider and DataAccessProvider with a real host adapter.\n * The adapter determines update semantics, authorization, persistence and errors. Invalidation\n * defaults are supplied by this helper; the underlying wrapper has no automatic defaults.\n * @example\n * ```tsx\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useUpdate } from '@alneas/appkit-react/tools/data-access/react';\n * import type { ComponentProps } from 'react';\n * const client = createQueryClient();\n * function UpdateTask() {\n *   const update = useUpdate<{ id: string; title: string }>('tasks');\n *   return <button onClick={() => update.mutate({ id: 'task-1', data: { title: 'Reviewed' } })}>Update</button>;\n * }\n * export function TaskUpdater({ adapter }: Pick<ComponentProps<typeof DataAccessProvider>, 'adapter'>) {\n *   return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}>\n *     <UpdateTask />\n *   </DataAccessProvider></QueryClientProvider>;\n * }\n * ```\n */\nexport function useUpdate<\n  T = unknown,\n  TVariables = { id: string; data: Record<string, unknown>; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    /**\n     * Callback after successful mutation and awaited invalidations.\n     * @param data - Adapter result.\n     * @param variables - Original mutation variables.\n     * @returns No value; callback promise results are not awaited by the wrapper.\n     */\n    onSuccess?: (data: T, variables: TVariables) => void;\n    /**\n     * Optional replacement query keys using prefix matching; [] disables invalidation, omission uses this hook default.\n     */\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T, Error, TVariables>(\n    (variables) => {\n      const vars = variables as {\n        id: string;\n        data: Record<string, unknown>;\n        options?: QueryOptions;\n      };\n      return adapter.update<T>(collection, vars.id, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      // リストと、特定の詳細アイテムの両方のキャッシュを無効化する\n      invalidateKeys: (_data, variables) => {\n        const vars = variables as { id: string };\n        return (\n          options?.invalidateKeys || [\n            [collection, 'list'],\n            [collection, 'detail', vars.id],\n          ]\n        );\n      },\n    },\n  );\n}\n\n/**\n * Deletes one record through the current adapter.\n * @typeParam T - Adapter result record shape, defaults to unknown.\n * @typeParam TVariables - Mutation variables; must provide id and optional adapter options.\n * @param collection - Host collection/table name.\n * @param options - Optional successful-result callback and replacement invalidation keys.\n * @returns TanStack mutation result with explicit mutate/mutateAsync controls.\n * @throws Error without required providers; adapter failures reject mutateAsync and populate mutation error state.\n * @remarks Requires DataAccessProvider inside QueryClientProvider; no CSS. Omitted\n * invalidation keys default to [[collection]]; [] disables invalidation. Callback promise\n * results are not awaited by the underlying wrapper. Persistence, atomicity and\n * authorization are host-owned; no rollback is supplied.\n * @example\n * ```tsx\n * import type { ComponentProps } from 'react';\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useDelete } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * const client = createQueryClient();\n * function Action() { const mutation = useDelete('tasks'); return <button onClick={() => mutation.mutate({ id: 'task-1' })}>Run host mutation</button>; }\n * export function DataScreen({ adapter }: { adapter: DataAccessAdapter }) { return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}><Action /></DataAccessProvider></QueryClientProvider>; }\n * ```\n */\nexport function useDelete<T = unknown, TVariables = { id: string; options?: QueryOptions }>(\n  collection: string,\n  options?: {\n    /**\n     * Callback after successful mutation and awaited invalidations.\n     * @param data - Adapter result.\n     * @param variables - Original mutation variables.\n     * @returns No value; callback promise results are not awaited by the wrapper.\n     */\n    onSuccess?: (data: T, variables: TVariables) => void;\n    /**\n     * Optional replacement query keys using prefix matching; [] disables invalidation, omission uses this hook default.\n     */\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T, Error, TVariables>(\n    (variables) => {\n      const vars = (typeof variables === 'string' ? { id: variables } : variables) as {\n        id: string;\n        options?: QueryOptions;\n      };\n      return adapter.delete<T>(collection, vars.id, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * Creates multiple records through the current adapter.\n * @typeParam T - Adapter result record shape, defaults to unknown.\n * @typeParam TVariables - Mutation variables; must provide data array and optional adapter options.\n * @param collection - Host collection/table name.\n * @param options - Optional successful-result callback and replacement invalidation keys.\n * @returns TanStack mutation result with explicit mutate/mutateAsync controls.\n * @throws Error without required providers; mutation rejects if adapter lacks createMany or fails.\n * @remarks Requires DataAccessProvider inside QueryClientProvider; no CSS. Omitted\n * invalidation keys default to [[collection]]; [] disables invalidation. Callback promise\n * results are not awaited by the underlying wrapper. Persistence, atomicity and\n * authorization are host-owned; no rollback is supplied.\n * @example\n * ```tsx\n * import type { ComponentProps } from 'react';\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useCreateMany } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * const client = createQueryClient();\n * function Action() { const mutation = useCreateMany('tasks'); return <button onClick={() => mutation.mutate({ data: [{ title: 'Review' }] })}>Run host mutation</button>; }\n * export function DataScreen({ adapter }: { adapter: DataAccessAdapter }) { return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}><Action /></DataAccessProvider></QueryClientProvider>; }\n * ```\n */\nexport function useCreateMany<\n  T = unknown,\n  TVariables = { data: Record<string, unknown>[]; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    /**\n     * Callback after successful mutation and awaited invalidations.\n     * @param data - Adapter result.\n     * @param variables - Original mutation variables.\n     * @returns No value; callback promise results are not awaited by the wrapper.\n     */\n    onSuccess?: (data: T[], variables: TVariables) => void;\n    /**\n     * Optional replacement query keys using prefix matching; [] disables invalidation, omission uses this hook default.\n     */\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T[], Error, TVariables>(\n    (variables) => {\n      const vars = variables as { data: Record<string, unknown>[]; options?: QueryOptions };\n      if (!adapter.createMany) throw new Error('Adapter does not support createMany');\n      return adapter.createMany<T>(collection, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * Updates records matching an adapter filter.\n * @typeParam T - Adapter result record shape, defaults to unknown.\n * @typeParam TVariables - Mutation variables; must provide filter, data and optional adapter options.\n * @param collection - Host collection/table name.\n * @param options - Optional successful-result callback and replacement invalidation keys.\n * @returns TanStack mutation result with explicit mutate/mutateAsync controls.\n * @throws Error without required providers; mutation rejects if adapter lacks updateMany or fails.\n * @remarks Requires DataAccessProvider inside QueryClientProvider; no CSS. Omitted\n * invalidation keys default to [[collection], [collection, 'list']]; [] disables invalidation. Callback promise\n * results are not awaited by the underlying wrapper. Persistence, atomicity and\n * authorization are host-owned; no rollback is supplied.\n * @example\n * ```tsx\n * import type { ComponentProps } from 'react';\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useUpdateMany } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * const client = createQueryClient();\n * function Action() { const mutation = useUpdateMany('tasks'); return <button onClick={() => mutation.mutate({ filter: { state: 'draft' }, data: { state: 'reviewed' } })}>Run host mutation</button>; }\n * export function DataScreen({ adapter }: { adapter: DataAccessAdapter }) { return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}><Action /></DataAccessProvider></QueryClientProvider>; }\n * ```\n */\nexport function useUpdateMany<\n  T = unknown,\n  TVariables = { filter: Filter; data: Record<string, unknown>; options?: QueryOptions },\n>(\n  collection: string,\n  options?: {\n    /**\n     * Callback after successful mutation and awaited invalidations.\n     * @param data - Adapter result.\n     * @param variables - Original mutation variables.\n     * @returns No value; callback promise results are not awaited by the wrapper.\n     */\n    onSuccess?: (data: T[], variables: TVariables) => void;\n    /**\n     * Optional replacement query keys using prefix matching; [] disables invalidation, omission uses this hook default.\n     */\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T[], Error, TVariables>(\n    (variables) => {\n      const vars = variables as {\n        filter: Filter;\n        data: Record<string, unknown>;\n        options?: QueryOptions;\n      };\n      if (!adapter.updateMany) throw new Error('Adapter does not support updateMany');\n      return adapter.updateMany<T>(collection, vars.filter, vars.data, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection], [collection, 'list']],\n    },\n  );\n}\n\n/**\n * Deletes records matching an adapter filter.\n * @typeParam T - Adapter result record shape, defaults to unknown.\n * @typeParam TVariables - Mutation variables; must provide filter and optional adapter options.\n * @param collection - Host collection/table name.\n * @param options - Optional successful-result callback and replacement invalidation keys.\n * @returns TanStack mutation result with explicit mutate/mutateAsync controls.\n * @throws Error without required providers; mutation rejects if adapter lacks deleteMany or fails.\n * @remarks Requires DataAccessProvider inside QueryClientProvider; no CSS. Omitted\n * invalidation keys default to [[collection]]; [] disables invalidation. Callback promise\n * results are not awaited by the underlying wrapper. Persistence, atomicity and\n * authorization are host-owned; no rollback is supplied.\n * @example\n * ```tsx\n * import type { ComponentProps } from 'react';\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useDeleteMany } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * const client = createQueryClient();\n * function Action() { const mutation = useDeleteMany('tasks'); return <button onClick={() => mutation.mutate({ filter: { state: 'obsolete' } })}>Run host mutation</button>; }\n * export function DataScreen({ adapter }: { adapter: DataAccessAdapter }) { return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}><Action /></DataAccessProvider></QueryClientProvider>; }\n * ```\n */\nexport function useDeleteMany<T = unknown, TVariables = { filter: Filter; options?: QueryOptions }>(\n  collection: string,\n  options?: {\n    /**\n     * Callback after successful mutation and awaited invalidations.\n     * @param data - Adapter result.\n     * @param variables - Original mutation variables.\n     * @returns No value; callback promise results are not awaited by the wrapper.\n     */\n    onSuccess?: (data: T[], variables: TVariables) => void;\n    /**\n     * Optional replacement query keys using prefix matching; [] disables invalidation, omission uses this hook default.\n     */\n    invalidateKeys?: unknown[][];\n  },\n) {\n  const adapter = useDataAccess();\n  return useMutationWithInvalidation<T[], Error, TVariables>(\n    (variables) => {\n      const vars = variables as { filter: Filter; options?: QueryOptions };\n      if (!adapter.deleteMany) throw new Error('Adapter does not support deleteMany');\n      return adapter.deleteMany<T>(collection, vars.filter, vars.options);\n    },\n    {\n      onSuccess: options?.onSuccess,\n      invalidateKeys: options?.invalidateKeys || [[collection]],\n    },\n  );\n}\n\n/**\n * Queries an aggregation pipeline through the current adapter.\n * @typeParam T - Expected result record shape, default unknown; not runtime validation.\n * @param collection - Host collection/table name.\n * @param pipeline - Adapter-specific aggregation stages.\n * @param options - Optional adapter query settings.\n * @param queryOptions - TanStack query overrides; omitted values use the generated options.\n * @returns TanStack query result with data/status/error and refetch controls. Missing aggregate capability becomes a query error.\n * @throws Error without DataAccessProvider or QueryClientProvider.\n * @remarks No CSS required. Adapter failures appear in query state; keys include adapter\n * scope and input options. Query signals are forwarded, but cancellation depends on the\n * adapter. The host owns backend authorization.\n * @example\n * ```tsx\n * import type { ComponentProps } from 'react';\n * import { QueryClientProvider } from '@tanstack/react-query';\n * import { DataAccessProvider, createQueryClient, useAggregate } from '@alneas/appkit-react/tools/data-access/react';\n * type DataAccessAdapter = ComponentProps<typeof DataAccessProvider>['adapter'];\n * const client = createQueryClient();\n * function Content() { const query = useAggregate<{ count: number }>('tasks', []); return <output>{query.isPending ? 'Loading' : query.error ? 'Failed' : 'Ready'}</output>; }\n * export function DataScreen({ adapter }: { adapter: DataAccessAdapter }) { return <QueryClientProvider client={client}><DataAccessProvider adapter={adapter}><Content /></DataAccessProvider></QueryClientProvider>; }\n * ```\n */\nexport function useAggregate<T = unknown>(\n  collection: string,\n  pipeline: unknown[],\n  options?: QueryOptions,\n  queryOptions?: Omit<UseQueryOptions<T[], Error>, 'queryKey' | 'queryFn'>,\n) {\n  const adapter = useDataAccess();\n  const aggOptions = aggregateQueryOptions<T>(adapter, collection, pipeline, options);\n  return useQuery({\n    ...aggOptions,\n    ...queryOptions,\n  } as UseQueryOptions<T[], Error>);\n}\n"],"mappings":"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"}

package/dist/tools/lib/error/AppError.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"AppError.cjs","names":["require_errors_auth_account_exists_with_different_credential","require_errors_auth_email_already_in_use","require_errors_auth_invalid_email","require_errors_auth_network_request_failed","require_errors_auth_operation_not_allowed","require_errors_auth_requires_recent_login","require_errors_auth_too_many_requests","require_errors_auth_user_disabled","require_errors_auth_user_not_found","require_errors_auth_weak_password","require_errors_auth_wrong_password","require_errors_supabase_email_not_confirmed","require_errors_supabase_invalid_credentials","AppError","message","code","options","error","defaultDisplayMode","errorRecord","msg","TimeoutError","NetworkError","UnauthorizedError","NotFoundError","ValidationError"],"sources":["../../../../src/tools/lib/error/AppError.ts"],"sourcesContent":["import * as m from '../../paraglide/messages';\n\n/**\n * エラー表示モード\n * - inline: フォーム内のフィールド近くに表示\n * - notification: 画面上部のバナー通知\n * - dialog: モーダルダイアログ\n * - page: 全画面エラーページ\n */\nexport type ErrorDisplayMode = 'inline' | 'notification' | 'dialog' | 'page';\n\n/**\n * エラーの重要度\n */\nexport type ErrorSeverity = 'info' | 'warning' | 'error' | 'critical';\n\n/**\n * AppError: アプリケーション全体で使用するエラークラス\n *\n * @example\n * ```typescript\n * // 基本的な使用法\n * throw new AppError('auth/user-not-found', 'User not found');\n *\n * // 表示モード指定\n * throw new AppError('network/timeout', 'Request timed out', {\n *   displayMode: 'notification',\n *   severity: 'warning'\n * });\n *\n * // メタデータ付き\n * throw new AppError('validation/invalid-field', 'Invalid input', {\n *   displayMode: 'inline',\n *   metadata: { field: 'email' }\n * });\n * ```\n */\nexport class AppError extends Error {\n  /** エラーコード。i18n のキーとしても使用 (例: 'auth/user-not-found') */\n  readonly code: string;\n\n  /** 推奨される表示モード */\n  readonly displayMode: ErrorDisplayMode;\n\n  /** エラーの重要度 */\n  readonly severity: ErrorSeverity;\n\n  /** 追加のメタデータ (フィールド名、HTTP ステータスなど) */\n  readonly metadata?: Record<string, unknown>;\n\n  /** 元のエラー (ラップする場合) */\n  readonly originalError?: Error;\n\n  /**\n   * AppError の新しいインスタンスを生成します。\n   * @param code エラーコード\n   * @param message エラーメッセージ\n   * @param options 追加オプション\n   */\n  constructor(\n    code: string,\n    message: string,\n    options?: {\n      displayMode?: ErrorDisplayMode;\n      severity?: ErrorSeverity;\n      metadata?: Record<string, unknown>;\n      originalError?: Error;\n    },\n  ) {\n    super(message);\n    this.name = 'AppError';\n    this.code = code;\n    this.displayMode = options?.displayMode ?? 'notification';\n    this.severity = options?.severity ?? 'error';\n    this.metadata = options?.metadata;\n    this.originalError = options?.originalError;\n\n    // Error の prototype chain を正しく設定\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  /**\n   * 任意のエラーを AppError に変換します。\n   * Firebase, Supabase 等のエラーを自動的にコードマッピングします。\n   */\n  static from(error: unknown, defaultDisplayMode: ErrorDisplayMode = 'notification'): AppError {\n    if (error instanceof AppError) {\n      return error;\n    }\n\n    if (error instanceof Error) {\n      // Firebase Auth Error\n      if ('code' in error && typeof (error as { code: unknown }).code === 'string') {\n        const code = (error as { code: string }).code;\n        let message = error.message;\n\n        switch (code) {\n          case 'auth/invalid-email':\n            message = m.errors_auth_invalid_email();\n            break;\n          case 'auth/wrong-password':\n            message = m.errors_auth_wrong_password();\n            break;\n          case 'auth/user-not-found':\n            message = m.errors_auth_user_not_found();\n            break;\n          case 'auth/user-disabled':\n            message = m.errors_auth_user_disabled();\n            break;\n          case 'auth/too-many-requests':\n            message = m.errors_auth_too_many_requests();\n            break;\n          case 'auth/operation-not-allowed':\n            message = m.errors_auth_operation_not_allowed();\n            break;\n          case 'auth/email-already-in-use':\n            message = m.errors_auth_email_already_in_use();\n            break;\n          case 'auth/requires-recent-login':\n            message = m.errors_auth_requires_recent_login();\n            break;\n          case 'auth/credential-already-in-use':\n            message = m.errors_auth_account_exists_with_different_credential();\n            break;\n          case 'auth/weak-password':\n            message = m.errors_auth_weak_password();\n            break;\n          case 'auth/network-request-failed':\n            message = m.errors_auth_network_request_failed();\n            break;\n        }\n\n        return new AppError(code, message, {\n          displayMode: defaultDisplayMode,\n          originalError: error,\n        });\n      }\n\n      // Supabase/PostgreSQL Error\n      // Supabase errors often have 'code' and 'message'.\n      // We can also look for specific strings in the message if the code is generic.\n      if ('code' in error || 'message' in error) {\n        const errorRecord = error as { code?: unknown; message?: unknown };\n        const msg = typeof errorRecord.message === 'string' ? errorRecord.message : '';\n\n        // Supabase generic error message mapping\n        if (msg.includes('Invalid login credentials')) {\n          return new AppError(\n            'bg-auth/invalid-credentials',\n            m.errors_supabase_invalid_credentials(),\n            { displayMode: defaultDisplayMode, originalError: error },\n          );\n        }\n        if (msg.includes('Email not confirmed')) {\n          return new AppError(\n            'bg-auth/email-not-confirmed',\n            m.errors_supabase_email_not_confirmed(),\n            { displayMode: defaultDisplayMode, originalError: error },\n          );\n        }\n      }\n\n      // Generic Error\n      return new AppError('error/unknown', error.message, {\n        displayMode: defaultDisplayMode,\n        originalError: error,\n      });\n    }\n\n    // Unknown type\n    return new AppError('error/unknown', String(error), {\n      displayMode: defaultDisplayMode,\n    });\n  }\n\n  /**\n   * 文字列表現\n   */\n  toString(): string {\n    return `[${this.code}] ${this.message}`;\n  }\n\n  /**\n   * JSON シリアライズ用\n   */\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      displayMode: this.displayMode,\n      severity: this.severity,\n      metadata: this.metadata,\n    };\n  }\n}\n\n/**\n * ネットワークタイムアウトエラー\n */\nexport class TimeoutError extends AppError {\n  /**\n   * TimeoutError の新しいインスタンスを生成します。\n   * @param message エラーメッセージ\n   * @param duration タイムアウトした時間（ミリ秒）\n   */\n  constructor(message = 'The operation timed out', duration?: number) {\n    super('error/timeout', message, {\n      displayMode: 'notification',\n      severity: 'warning',\n      metadata: { duration },\n    });\n    this.name = 'TimeoutError';\n  }\n}\n\n/**\n * ネットワークエラー\n */\nexport class NetworkError extends AppError {\n  /**\n   * NetworkError の新しいインスタンスを生成します。\n   * @param message エラーメッセージ\n   */\n  constructor(message = 'Network error occurred') {\n    super('error/network', message, {\n      displayMode: 'notification',\n      severity: 'error',\n    });\n    this.name = 'NetworkError';\n  }\n}\n\n/**\n * 認証不足エラー\n */\nexport class UnauthorizedError extends AppError {\n  /**\n   * UnauthorizedError の新しいインスタンスを生成します。\n   * @param message エラーメッセージ\n   */\n  constructor(message = 'You are not authorized to perform this action') {\n    super('error/unauthorized', message, {\n      displayMode: 'dialog',\n      severity: 'error',\n    });\n    this.name = 'UnauthorizedError';\n  }\n}\n\n/**\n * リソースが見つからないエラー\n */\nexport class NotFoundError extends AppError {\n  /**\n   * NotFoundError の新しいインスタンスを生成します。\n   * @param message エラーメッセージ\n   * @param resource 見つからなかったリソース名\n   */\n  constructor(message = 'The requested resource was not found', resource?: string) {\n    super('error/not-found', message, {\n      displayMode: 'page',\n      severity: 'error',\n      metadata: { resource },\n    });\n    this.name = 'NotFoundError';\n  }\n}\n\n/**\n * バリデーションエラー\n */\nexport class ValidationError extends AppError {\n  /**\n   * ValidationError の新しいインスタンスを生成します。\n   * @param message エラーメッセージ\n   * @param fields フィールドごとのエラーマッピング\n   */\n  constructor(message: string, fields?: Record<string, string>) {\n    super('error/validation', message, {\n      displayMode: 'inline',\n      severity: 'warning',\n      metadata: { fields },\n    });\n    this.name = 'ValidationError';\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"AppError.cjs","names":["require_errors_auth_account_exists_with_different_credential","require_errors_auth_email_already_in_use","require_errors_auth_invalid_email","require_errors_auth_network_request_failed","require_errors_auth_operation_not_allowed","require_errors_auth_requires_recent_login","require_errors_auth_too_many_requests","require_errors_auth_user_disabled","require_errors_auth_user_not_found","require_errors_auth_weak_password","require_errors_auth_wrong_password","require_errors_supabase_email_not_confirmed","require_errors_supabase_invalid_credentials","AppError","message","code","options","error","defaultDisplayMode","errorRecord","msg","TimeoutError","NetworkError","UnauthorizedError","NotFoundError","ValidationError"],"sources":["../../../../src/tools/lib/error/AppError.ts"],"sourcesContent":["import * as m from '../../paraglide/messages';\n\n/**\n * Requested error presentation: inline field feedback, notification banner, modal dialog or full page.\n * @remarks This is metadata; a host renderer must display the error.\n * @see AppError for creation.\n */\nexport type ErrorDisplayMode = 'inline' | 'notification' | 'dialog' | 'page';\n\n/**\n * Presentation severity from informational through critical; does not change Error behavior.\n * @see AppError for creation.\n */\nexport type ErrorSeverity = 'info' | 'warning' | 'error' | 'critical';\n\n/**\n * Application Error carrying a code, display hint, severity and optional metadata/original error.\n * @remarks Presentation hints do not render UI or enforce authorization. Metadata is retained\n * by reference and included in toJSON; exclude secrets before displaying or serializing.\n * @example\n * ```ts\n * import { AppError } from '@alneas/appkit-react/tools/core';\n * const error = new AppError('validation/input', 'Review the input', { displayMode: 'inline', severity: 'warning' });\n * ```\n */\nexport class AppError extends Error {\n    /**\n   * Stable host error code, also usable for localized message lookup.\n   */\n  readonly code: string;\n\n    /**\n   * Recommended host display mode; defaults to notification.\n   */\n  readonly displayMode: ErrorDisplayMode;\n\n    /**\n   * Presentation severity; defaults to error.\n   */\n  readonly severity: ErrorSeverity;\n\n    /**\n   * Optional host metadata retained by reference and included in JSON serialization.\n   */\n  readonly metadata?: Record<string, unknown>;\n\n    /**\n   * Optional wrapped Error retained by reference; excluded from toJSON.\n   */\n  readonly originalError?: Error;\n\n  /**\n * Creates an Error with explicit application code and presentation metadata.\n * @param code - Host error identifier; no format validation is applied.\n * @param message - Error message stored by the Error base class.\n * @param options - Optional displayMode/severity (defaults notification/error), metadata and wrapped Error.\n * @example\n * ```ts\n * import { AppError } from '@alneas/appkit-react/tools/core';\n * const error = new AppError('error/example', 'Operation failed');\n * ```\n */\n  constructor(\n    code: string,\n    message: string,\n    options?: {\n      /**\n       * Presentation hint, default notification.\n       */\n      displayMode?: ErrorDisplayMode;\n      /**\n       * Presentation severity, default error.\n       */\n      severity?: ErrorSeverity;\n      /**\n       * Optional host metadata included by toJSON.\n       */\n      metadata?: Record<string, unknown>;\n      /**\n       * Optional wrapped Error, excluded from toJSON.\n       */\n      originalError?: Error;\n    },\n  ) {\n    super(message);\n    this.name = 'AppError';\n    this.code = code;\n    this.displayMode = options?.displayMode ?? 'notification';\n    this.severity = options?.severity ?? 'error';\n    this.metadata = options?.metadata;\n    this.originalError = options?.originalError;\n\n    // Error の prototype chain を正しく設定\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  /**\n * Converts an unknown value to AppError, preserving an existing AppError unchanged.\n * @param error - Error or arbitrary thrown value to normalize.\n * @param defaultDisplayMode - Hint for newly created wrappers; defaults to notification.\n * @returns Existing AppError identity, or a new wrapper. Error instances with a string code\n * retain that code and map selected known auth messages; other Errors use message matching\n * or error/unknown. Non-Error values are stringified as error/unknown.\n * @remarks Plain objects with code/message are not interpreted as Error instances. The\n * default display hint does not override an existing AppError. No UI is rendered.\n * @example\n * ```ts\n * import { AppError } from '@alneas/appkit-react/tools/core';\n * const error = AppError.from(new Error('Unavailable'), 'dialog');\n * ```\n */\n  static from(error: unknown, defaultDisplayMode: ErrorDisplayMode = 'notification'): AppError {\n    if (error instanceof AppError) {\n      return error;\n    }\n\n    if (error instanceof Error) {\n      // Firebase Auth Error\n      if ('code' in error && typeof (error as { code: unknown }).code === 'string') {\n        const code = (error as { code: string }).code;\n        let message = error.message;\n\n        switch (code) {\n          case 'auth/invalid-email':\n            message = m.errors_auth_invalid_email();\n            break;\n          case 'auth/wrong-password':\n            message = m.errors_auth_wrong_password();\n            break;\n          case 'auth/user-not-found':\n            message = m.errors_auth_user_not_found();\n            break;\n          case 'auth/user-disabled':\n            message = m.errors_auth_user_disabled();\n            break;\n          case 'auth/too-many-requests':\n            message = m.errors_auth_too_many_requests();\n            break;\n          case 'auth/operation-not-allowed':\n            message = m.errors_auth_operation_not_allowed();\n            break;\n          case 'auth/email-already-in-use':\n            message = m.errors_auth_email_already_in_use();\n            break;\n          case 'auth/requires-recent-login':\n            message = m.errors_auth_requires_recent_login();\n            break;\n          case 'auth/credential-already-in-use':\n            message = m.errors_auth_account_exists_with_different_credential();\n            break;\n          case 'auth/weak-password':\n            message = m.errors_auth_weak_password();\n            break;\n          case 'auth/network-request-failed':\n            message = m.errors_auth_network_request_failed();\n            break;\n        }\n\n        return new AppError(code, message, {\n          displayMode: defaultDisplayMode,\n          originalError: error,\n        });\n      }\n\n      // Supabase/PostgreSQL Error\n      // Supabase errors often have 'code' and 'message'.\n      // We can also look for specific strings in the message if the code is generic.\n      if ('code' in error || 'message' in error) {\n        const errorRecord = error as { code?: unknown; message?: unknown };\n        const msg = typeof errorRecord.message === 'string' ? errorRecord.message : '';\n\n        // Supabase generic error message mapping\n        if (msg.includes('Invalid login credentials')) {\n          return new AppError(\n            'bg-auth/invalid-credentials',\n            m.errors_supabase_invalid_credentials(),\n            { displayMode: defaultDisplayMode, originalError: error },\n          );\n        }\n        if (msg.includes('Email not confirmed')) {\n          return new AppError(\n            'bg-auth/email-not-confirmed',\n            m.errors_supabase_email_not_confirmed(),\n            { displayMode: defaultDisplayMode, originalError: error },\n          );\n        }\n      }\n\n      // Generic Error\n      return new AppError('error/unknown', error.message, {\n        displayMode: defaultDisplayMode,\n        originalError: error,\n      });\n    }\n\n    // Unknown type\n    return new AppError('error/unknown', String(error), {\n      displayMode: defaultDisplayMode,\n    });\n  }\n\n  /**\n * Formats the application code and message for display/logging.\n * @returns String in [code] message form; does not include metadata or stack.\n * @example\n * ```ts\n * import { AppError } from '@alneas/appkit-react/tools/core';\n * const error = new AppError('error/example', 'Unavailable').toString();\n * ```\n */\n  toString(): string {\n    return `[${this.code}] ${this.message}`;\n  }\n\n  /**\n * Selects enumerable presentation fields for JSON serialization.\n * @returns New object with name/code/message/displayMode/severity/metadata; stack and originalError are omitted.\n * @remarks Metadata remains referenced and may itself be non-serializable or sensitive.\n * @example\n * ```ts\n * import { AppError } from '@alneas/appkit-react/tools/core';\n * const error = new AppError('error/example', 'Unavailable').toJSON();\n * ```\n */\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      displayMode: this.displayMode,\n      severity: this.severity,\n      metadata: this.metadata,\n    };\n  }\n}\n\n/**\n * Represents an operation timeout with notification/warning presentation.\n * @remarks Construction does not start timers, perform a request or render error UI.\n * @example\n * ```ts\n * import { TimeoutError } from '@alneas/appkit-react/tools/core';\n * const error = new TimeoutError();\n * ```\n */\nexport class TimeoutError extends AppError {\n  /**\n * Creates an application error with code error/timeout.\n * @param message - Message, default The operation timed out.\n * @param duration - Optional timeout duration in milliseconds; retained in metadata.\n * @example\n * ```ts\n * import { TimeoutError } from '@alneas/appkit-react/tools/core';\n * const error = new TimeoutError();\n * ```\n */\n  constructor(message = 'The operation timed out', duration?: number) {\n    super('error/timeout', message, {\n      displayMode: 'notification',\n      severity: 'warning',\n      metadata: { duration },\n    });\n    this.name = 'TimeoutError';\n  }\n}\n\n/**\n * Represents a network failure with notification/error presentation.\n * @remarks Construction does not start timers, perform a request or render error UI.\n * @example\n * ```ts\n * import { NetworkError } from '@alneas/appkit-react/tools/core';\n * const error = new NetworkError();\n * ```\n */\nexport class NetworkError extends AppError {\n  /**\n * Creates an application error with code error/network.\n * @param message - Message, default Network error occurred.\n * @example\n * ```ts\n * import { NetworkError } from '@alneas/appkit-react/tools/core';\n * const error = new NetworkError();\n * ```\n */\n  constructor(message = 'Network error occurred') {\n    super('error/network', message, {\n      displayMode: 'notification',\n      severity: 'error',\n    });\n    this.name = 'NetworkError';\n  }\n}\n\n/**\n * Represents denied access with dialog/error presentation.\n * @remarks Construction does not start timers, perform a request or render error UI.\n * @example\n * ```ts\n * import { UnauthorizedError } from '@alneas/appkit-react/tools/core';\n * const error = new UnauthorizedError();\n * ```\n */\nexport class UnauthorizedError extends AppError {\n  /**\n * Creates an application error with code error/unauthorized.\n * @param message - Message, default You are not authorized to perform this action.\n * @example\n * ```ts\n * import { UnauthorizedError } from '@alneas/appkit-react/tools/core';\n * const error = new UnauthorizedError();\n * ```\n */\n  constructor(message = 'You are not authorized to perform this action') {\n    super('error/unauthorized', message, {\n      displayMode: 'dialog',\n      severity: 'error',\n    });\n    this.name = 'UnauthorizedError';\n  }\n}\n\n/**\n * Represents a missing resource with page/error presentation.\n * @remarks Construction does not start timers, perform a request or render error UI.\n * @example\n * ```ts\n * import { NotFoundError } from '@alneas/appkit-react/tools/core';\n * const error = new NotFoundError();\n * ```\n */\nexport class NotFoundError extends AppError {\n  /**\n * Creates an application error with code error/not-found.\n * @param message - Message, default The requested resource was not found.\n * @param resource - Optional missing resource name retained in metadata.\n * @example\n * ```ts\n * import { NotFoundError } from '@alneas/appkit-react/tools/core';\n * const error = new NotFoundError();\n * ```\n */\n  constructor(message = 'The requested resource was not found', resource?: string) {\n    super('error/not-found', message, {\n      displayMode: 'page',\n      severity: 'error',\n      metadata: { resource },\n    });\n    this.name = 'NotFoundError';\n  }\n}\n\n/**\n * Represents invalid input with inline/warning presentation.\n * @remarks Construction does not start timers, perform a request or render error UI.\n * @example\n * ```ts\n * import { ValidationError } from '@alneas/appkit-react/tools/core';\n * const error = new ValidationError('Invalid input');\n * ```\n */\nexport class ValidationError extends AppError {\n  /**\n * Creates an application error with code error/validation.\n * @param message - Required validation message.\n * @param fields - Optional per-field error messages retained in metadata.\n * @example\n * ```ts\n * import { ValidationError } from '@alneas/appkit-react/tools/core';\n * const error = new ValidationError('Invalid input');\n * ```\n */\n  constructor(message: string, fields?: Record<string, string>) {\n    super('error/validation', message, {\n      displayMode: 'inline',\n      severity: 'warning',\n      metadata: { fields },\n    });\n    this.name = 'ValidationError';\n  }\n}\n"],"mappings":"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"}

package/dist/tools/lib/error/AppError.d.cts

@@ -1,123 +1,217 @@
 /**
- * エラー表示モード
- * - inline: フォーム内のフィールド近くに表示
- * - notification: 画面上部のバナー通知
- * - dialog: モーダルダイアログ
- * - page: 全画面エラーページ
+ * Requested error presentation: inline field feedback, notification banner, modal dialog or full page.
+ * @remarks This is metadata; a host renderer must display the error.
+ * @see AppError for creation.
  */
 export type ErrorDisplayMode = 'inline' | 'notification' | 'dialog' | 'page';
 /**
- * エラーの重要度
+ * Presentation severity from informational through critical; does not change Error behavior.
+ * @see AppError for creation.
  */
 export type ErrorSeverity = 'info' | 'warning' | 'error' | 'critical';
 /**
- * AppError: アプリケーション全体で使用するエラークラス
- *
+ * Application Error carrying a code, display hint, severity and optional metadata/original error.
+ * @remarks Presentation hints do not render UI or enforce authorization. Metadata is retained
+ * by reference and included in toJSON; exclude secrets before displaying or serializing.
  * @example
- * ```typescript
- * // 基本的な使用法
- * throw new AppError('auth/user-not-found', 'User not found');
- *
- * // 表示モード指定
- * throw new AppError('network/timeout', 'Request timed out', {
- *   displayMode: 'notification',
- *   severity: 'warning'
- * });
- *
- * // メタデータ付き
- * throw new AppError('validation/invalid-field', 'Invalid input', {
- *   displayMode: 'inline',
- *   metadata: { field: 'email' }
- * });
+ * ```ts
+ * import { AppError } from '@alneas/appkit-react/tools/core';
+ * const error = new AppError('validation/input', 'Review the input', { displayMode: 'inline', severity: 'warning' });
  * ```
  */
 export declare class AppError extends Error {
-    /** エラーコード。i18n のキーとしても使用 (例: 'auth/user-not-found') */
+    /**
+   * Stable host error code, also usable for localized message lookup.
+   */
     readonly code: string;
-    /** 推奨される表示モード */
+    /**
+   * Recommended host display mode; defaults to notification.
+   */
     readonly displayMode: ErrorDisplayMode;
-    /** エラーの重要度 */
+    /**
+   * Presentation severity; defaults to error.
+   */
     readonly severity: ErrorSeverity;
-    /** 追加のメタデータ (フィールド名、HTTP ステータスなど) */
+    /**
+   * Optional host metadata retained by reference and included in JSON serialization.
+   */
     readonly metadata?: Record<string, unknown>;
-    /** 元のエラー (ラップする場合) */
+    /**
+   * Optional wrapped Error retained by reference; excluded from toJSON.
+   */
     readonly originalError?: Error;
     /**
-     * AppError の新しいインスタンスを生成します。
-     * @param code エラーコード
-     * @param message エラーメッセージ
-     * @param options 追加オプション
-     */
+   * Creates an Error with explicit application code and presentation metadata.
+   * @param code - Host error identifier; no format validation is applied.
+   * @param message - Error message stored by the Error base class.
+   * @param options - Optional displayMode/severity (defaults notification/error), metadata and wrapped Error.
+   * @example
+   * ```ts
+   * import { AppError } from '@alneas/appkit-react/tools/core';
+   * const error = new AppError('error/example', 'Operation failed');
+   * ```
+   */
     constructor(code: string, message: string, options?: {
+        /**
+         * Presentation hint, default notification.
+         */
         displayMode?: ErrorDisplayMode;
+        /**
+         * Presentation severity, default error.
+         */
         severity?: ErrorSeverity;
+        /**
+         * Optional host metadata included by toJSON.
+         */
         metadata?: Record<string, unknown>;
+        /**
+         * Optional wrapped Error, excluded from toJSON.
+         */
         originalError?: Error;
     });
     /**
-     * 任意のエラーを AppError に変換します。
-     * Firebase, Supabase 等のエラーを自動的にコードマッピングします。
-     */
+   * Converts an unknown value to AppError, preserving an existing AppError unchanged.
+   * @param error - Error or arbitrary thrown value to normalize.
+   * @param defaultDisplayMode - Hint for newly created wrappers; defaults to notification.
+   * @returns Existing AppError identity, or a new wrapper. Error instances with a string code
+   * retain that code and map selected known auth messages; other Errors use message matching
+   * or error/unknown. Non-Error values are stringified as error/unknown.
+   * @remarks Plain objects with code/message are not interpreted as Error instances. The
+   * default display hint does not override an existing AppError. No UI is rendered.
+   * @example
+   * ```ts
+   * import { AppError } from '@alneas/appkit-react/tools/core';
+   * const error = AppError.from(new Error('Unavailable'), 'dialog');
+   * ```
+   */
     static from(error: unknown, defaultDisplayMode?: ErrorDisplayMode): AppError;
     /**
-     * 文字列表現
-     */
+   * Formats the application code and message for display/logging.
+   * @returns String in [code] message form; does not include metadata or stack.
+   * @example
+   * ```ts
+   * import { AppError } from '@alneas/appkit-react/tools/core';
+   * const error = new AppError('error/example', 'Unavailable').toString();
+   * ```
+   */
     toString(): string;
     /**
-     * JSON シリアライズ用
-     */
+   * Selects enumerable presentation fields for JSON serialization.
+   * @returns New object with name/code/message/displayMode/severity/metadata; stack and originalError are omitted.
+   * @remarks Metadata remains referenced and may itself be non-serializable or sensitive.
+   * @example
+   * ```ts
+   * import { AppError } from '@alneas/appkit-react/tools/core';
+   * const error = new AppError('error/example', 'Unavailable').toJSON();
+   * ```
+   */
     toJSON(): Record<string, unknown>;
 }
 /**
- * ネットワークタイムアウトエラー
+ * Represents an operation timeout with notification/warning presentation.
+ * @remarks Construction does not start timers, perform a request or render error UI.
+ * @example
+ * ```ts
+ * import { TimeoutError } from '@alneas/appkit-react/tools/core';
+ * const error = new TimeoutError();
+ * ```
  */
 export declare class TimeoutError extends AppError {
     /**
-     * TimeoutError の新しいインスタンスを生成します。
-     * @param message エラーメッセージ
-     * @param duration タイムアウトした時間（ミリ秒）
-     */
+   * Creates an application error with code error/timeout.
+   * @param message - Message, default The operation timed out.
+   * @param duration - Optional timeout duration in milliseconds; retained in metadata.
+   * @example
+   * ```ts
+   * import { TimeoutError } from '@alneas/appkit-react/tools/core';
+   * const error = new TimeoutError();
+   * ```
+   */
     constructor(message?: string, duration?: number);
 }
 /**
- * ネットワークエラー
+ * Represents a network failure with notification/error presentation.
+ * @remarks Construction does not start timers, perform a request or render error UI.
+ * @example
+ * ```ts
+ * import { NetworkError } from '@alneas/appkit-react/tools/core';
+ * const error = new NetworkError();
+ * ```
  */
 export declare class NetworkError extends AppError {
     /**
-     * NetworkError の新しいインスタンスを生成します。
-     * @param message エラーメッセージ
-     */
+   * Creates an application error with code error/network.
+   * @param message - Message, default Network error occurred.
+   * @example
+   * ```ts
+   * import { NetworkError } from '@alneas/appkit-react/tools/core';
+   * const error = new NetworkError();
+   * ```
+   */
     constructor(message?: string);
 }
 /**
- * 認証不足エラー
+ * Represents denied access with dialog/error presentation.
+ * @remarks Construction does not start timers, perform a request or render error UI.
+ * @example
+ * ```ts
+ * import { UnauthorizedError } from '@alneas/appkit-react/tools/core';
+ * const error = new UnauthorizedError();
+ * ```
  */
 export declare class UnauthorizedError extends AppError {
     /**
-     * UnauthorizedError の新しいインスタンスを生成します。
-     * @param message エラーメッセージ
-     */
+   * Creates an application error with code error/unauthorized.
+   * @param message - Message, default You are not authorized to perform this action.
+   * @example
+   * ```ts
+   * import { UnauthorizedError } from '@alneas/appkit-react/tools/core';
+   * const error = new UnauthorizedError();
+   * ```
+   */
     constructor(message?: string);
 }
 /**
- * リソースが見つからないエラー
+ * Represents a missing resource with page/error presentation.
+ * @remarks Construction does not start timers, perform a request or render error UI.
+ * @example
+ * ```ts
+ * import { NotFoundError } from '@alneas/appkit-react/tools/core';
+ * const error = new NotFoundError();
+ * ```
  */
 export declare class NotFoundError extends AppError {
     /**
-     * NotFoundError の新しいインスタンスを生成します。
-     * @param message エラーメッセージ
-     * @param resource 見つからなかったリソース名
-     */
+   * Creates an application error with code error/not-found.
+   * @param message - Message, default The requested resource was not found.
+   * @param resource - Optional missing resource name retained in metadata.
+   * @example
+   * ```ts
+   * import { NotFoundError } from '@alneas/appkit-react/tools/core';
+   * const error = new NotFoundError();
+   * ```
+   */
     constructor(message?: string, resource?: string);
 }
 /**
- * バリデーションエラー
+ * Represents invalid input with inline/warning presentation.
+ * @remarks Construction does not start timers, perform a request or render error UI.
+ * @example
+ * ```ts
+ * import { ValidationError } from '@alneas/appkit-react/tools/core';
+ * const error = new ValidationError('Invalid input');
+ * ```
  */
 export declare class ValidationError extends AppError {
     /**
-     * ValidationError の新しいインスタンスを生成します。
-     * @param message エラーメッセージ
-     * @param fields フィールドごとのエラーマッピング
-     */
+   * Creates an application error with code error/validation.
+   * @param message - Required validation message.
+   * @param fields - Optional per-field error messages retained in metadata.
+   * @example
+   * ```ts
+   * import { ValidationError } from '@alneas/appkit-react/tools/core';
+   * const error = new ValidationError('Invalid input');
+   * ```
+   */
     constructor(message: string, fields?: Record<string, string>);
 }