@alneas/appkit-react 0.1.0 → 0.3.0

package/dist/tools/lib/data-access/react-query.d.cts

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