/**
 * REST resource composable for CRUD operations with optimistic updates,
 * form submission, and reactive caching built on the bQuery fetch layer.
 *
 * @module bquery/reactive
 */
import { Signal } from './core';
import { type AsyncDataStatus, type UseFetchOptions } from './async-data';
import { type HttpClient, type HttpRequestConfig, type HttpResponse } from './http';
/** HTTP method shortcuts available on a resource. */
export interface ResourceActions<T> {
    /** Fetch the resource (GET). */
    fetch: () => Promise<T | undefined>;
    /** Create a new item (POST). */
    create: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
    /** Replace the resource (PUT). */
    update: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
    /** Partially update the resource (PATCH). */
    patch: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
    /** Delete the resource (DELETE). */
    remove: () => Promise<void>;
}
/** Options for `useResource()`. */
export interface UseResourceOptions<T = unknown> extends Omit<UseFetchOptions<T>, 'method' | 'body'> {
    /** Enable optimistic updates for mutating operations (default: false). */
    optimistic?: boolean;
    /** Called after any successful mutation (create / update / patch / remove). */
    onMutationSuccess?: (data: T | undefined, action: string) => void;
    /** Called after a failed mutation, receives the error and action name. */
    onMutationError?: (error: Error, action: string) => void;
}
/** Return value of `useResource()`. */
export interface UseResourceReturn<T> {
    /** Reactive resource data. */
    data: Signal<T | undefined>;
    /** Last error. */
    error: Signal<Error | null>;
    /** Lifecycle status for the initial fetch. */
    status: Signal<AsyncDataStatus>;
    /** Whether the initial fetch is pending. */
    pending: {
        readonly value: boolean;
        peek(): boolean;
    };
    /** Whether any mutation is in progress. */
    isMutating: {
        readonly value: boolean;
        peek(): boolean;
    };
    /** CRUD actions. */
    actions: ResourceActions<T>;
    /** Refresh the resource (re-GET). */
    refresh: () => Promise<T | undefined>;
    /** Clear data, error, and status. */
    clear: () => void;
    /** Dispose all reactive state and prevent future operations. */
    dispose: () => void;
}
/**
 * Reactive REST resource composable providing CRUD operations.
 *
 * Binds a base URL to a resource and exposes `fetch`, `create`, `update`,
 * `patch`, and `remove` helpers with optional optimistic updates.
 *
 * @template T - Resource data type
 * @param url - Resource endpoint URL or getter
 * @param options - Fetch and resource options
 * @returns Reactive resource state with CRUD actions
 *
 * @example
 * ```ts
 * import { useResource } from '@bquery/bquery/reactive';
 *
 * const user = useResource<User>('/api/users/1', {
 *   baseUrl: 'https://api.example.com',
 *   optimistic: true,
 * });
 *
 * // Read
 * await user.actions.fetch();
 *
 * // Update
 * await user.actions.patch({ name: 'Ada' });
 *
 * // Delete
 * await user.actions.remove();
 * ```
 */
export declare const useResource: <T = unknown>(url: string | URL | (() => string | URL), options?: UseResourceOptions<T>) => UseResourceReturn<T>;
/** Options for `useSubmit()`. */
export interface UseSubmitOptions<TResponse = unknown> extends Omit<UseFetchOptions<TResponse>, 'body' | 'immediate'> {
    /** HTTP method (default: `'POST'`). */
    method?: string;
}
/** Return value of `useSubmit()`. */
export interface UseSubmitReturn<TResponse = unknown> {
    /** Last response data. */
    data: Signal<TResponse | undefined>;
    /** Last error. */
    error: Signal<Error | null>;
    /** Current status. */
    status: Signal<AsyncDataStatus>;
    /** Whether the submission is pending. */
    pending: {
        readonly value: boolean;
        peek(): boolean;
    };
    /** Submit data to the endpoint. */
    submit: (body: Record<string, unknown> | FormData | BodyInit) => Promise<TResponse | undefined>;
    /** Reset state. */
    clear: () => void;
}
/**
 * Reactive form submission composable.
 *
 * Provides a `submit()` function that sends data to an endpoint with
 * reactive status, data, and error signals.
 *
 * @template TResponse - Response data type
 * @param url - Submission endpoint URL
 * @param options - Fetch options (method defaults to POST)
 * @returns Reactive submission state with `submit()` and `clear()`
 *
 * @example
 * ```ts
 * import { useSubmit } from '@bquery/bquery/reactive';
 *
 * const form = useSubmit<{ id: number }>('/api/users', {
 *   baseUrl: 'https://api.example.com',
 *   headers: { 'x-csrf': token },
 * });
 *
 * const result = await form.submit({ name: 'Ada', email: 'ada@example.com' });
 * console.log(form.status.value); // 'success'
 * ```
 */
export declare const useSubmit: <TResponse = unknown>(url: string | URL, options?: UseSubmitOptions<TResponse>) => UseSubmitReturn<TResponse>;
/** Typed CRUD methods for a REST endpoint. */
export interface RestClient<T = unknown> {
    /** GET all items. */
    list: (config?: HttpRequestConfig) => Promise<HttpResponse<T[]>>;
    /** GET a single item by ID. */
    get: (id: string | number, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
    /** POST a new item. */
    create: (body: Partial<T> | Record<string, unknown>, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
    /** PUT (full replace) an item by ID. */
    update: (id: string | number, body: Partial<T> | Record<string, unknown>, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
    /** PATCH (partial update) an item by ID. */
    patch: (id: string | number, body: Partial<T> | Record<string, unknown>, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
    /** DELETE an item by ID. */
    remove: (id: string | number, config?: HttpRequestConfig) => Promise<HttpResponse<void>>;
    /** The underlying HttpClient instance. */
    http: HttpClient;
}
/**
 * Create a typed REST client for a specific API resource.
 *
 * Wraps `createHttp()` and maps standard CRUD operations to their
 * conventional REST endpoints (`GET /`, `GET /:id`, `POST /`, `PUT /:id`,
 * `PATCH /:id`, `DELETE /:id`).
 *
 * @template T - Resource item type
 * @param baseUrl - Base URL of the resource (e.g. `https://api.example.com/users`)
 * @param defaults - Default request configuration merged into every call
 * @returns Typed REST client with `list`, `get`, `create`, `update`, `patch`, `remove`
 *
 * @example
 * ```ts
 * import { createRestClient } from '@bquery/bquery/reactive';
 *
 * interface User { id: number; name: string; email: string }
 *
 * const users = createRestClient<User>('https://api.example.com/users', {
 *   headers: { authorization: '******' },
 *   timeout: 10_000,
 * });
 *
 * const { data: allUsers } = await users.list();
 * const { data: user } = await users.get(1);
 * const { data: created } = await users.create({ name: 'Ada' });
 * await users.update(1, { name: 'Ada', email: 'ada@example.com' });
 * await users.patch(1, { email: 'new@example.com' });
 * await users.remove(1);
 * ```
 */
export declare const createRestClient: <T = unknown>(baseUrl: string, defaults?: HttpRequestConfig) => RestClient<T>;
/** Extract a unique identifier from an item. */
export type IdExtractor<T> = (item: T) => string | number;
/** Options for `useResourceList()`. */
export interface UseResourceListOptions<T = unknown> extends Omit<UseFetchOptions<T[]>, 'method' | 'body'> {
    /** Extract the unique ID from each item (default: `item.id`). */
    getId?: IdExtractor<T>;
    /** Enable optimistic list mutations (default: false). */
    optimistic?: boolean;
    /** Called after a successful list mutation. */
    onMutationSuccess?: (action: string) => void;
    /** Called after a failed list mutation. */
    onMutationError?: (error: Error, action: string) => void;
}
/** CRUD actions for a list resource. */
export interface ResourceListActions<T> {
    /** Refresh the list (GET). */
    fetch: () => Promise<T[] | undefined>;
    /** Add a new item to the list (POST). */
    add: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
    /** Update an existing item (PUT) by ID. */
    update: (id: string | number, body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
    /** Partially update an existing item (PATCH) by ID. */
    patch: (id: string | number, body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
    /** Remove an item from the list (DELETE) by ID. */
    remove: (id: string | number) => Promise<void>;
}
/** Return value of `useResourceList()`. */
export interface UseResourceListReturn<T> {
    /** Reactive list data. */
    data: Signal<T[] | undefined>;
    /** Last error. */
    error: Signal<Error | null>;
    /** Lifecycle status. */
    status: Signal<AsyncDataStatus>;
    /** Whether the list fetch is pending. */
    pending: {
        readonly value: boolean;
        peek(): boolean;
    };
    /** Whether any mutation is in progress. */
    isMutating: {
        readonly value: boolean;
        peek(): boolean;
    };
    /** CRUD actions. */
    actions: ResourceListActions<T>;
    /** Refresh the list. */
    refresh: () => Promise<T[] | undefined>;
    /** Clear data, error, and status. */
    clear: () => void;
    /** Dispose all reactive state. */
    dispose: () => void;
}
/**
 * Reactive list/collection CRUD composable with optimistic add, remove, and update.
 *
 * Fetches a list of items and provides typed CRUD helpers that update the
 * reactive array optimistically or after server confirmation.
 *
 * @template T - Item type
 * @param url - List endpoint URL or getter
 * @param options - Fetch and list options
 * @returns Reactive list state with CRUD actions
 *
 * @example
 * ```ts
 * import { useResourceList } from '@bquery/bquery/reactive';
 *
 * interface Todo { id: number; title: string; done: boolean }
 *
 * const todos = useResourceList<Todo>('/api/todos', {
 *   baseUrl: 'https://api.example.com',
 *   optimistic: true,
 *   getId: (t) => t.id,
 * });
 *
 * await todos.actions.add({ title: 'Buy milk', done: false });
 * await todos.actions.patch(1, { done: true });
 * await todos.actions.remove(1);
 * ```
 */
export declare const useResourceList: <T = unknown>(url: string | URL | (() => string | URL), options?: UseResourceListOptions<T>) => UseResourceListReturn<T>;
/**
 * Deduplicate identical in-flight requests or operations keyed by `key`.
 *
 * If an operation with the same key is already in flight, reuse its promise
 * instead of starting a new one. Once the operation completes, the entry is removed.
 *
 * @param key - Cache key for the in-flight operation (for HTTP, typically URL + serialized query)
 * @param execute - The operation function to run if no duplicate is in flight
 * @returns The shared result promise for callers using the same key concurrently
 *
 * @example
 * ```ts
 * import { deduplicateRequest, createHttp } from '@bquery/bquery/reactive';
 *
 * const api = createHttp({ baseUrl: 'https://api.example.com' });
 *
 * // Both calls share the same in-flight operation
 * const [a, b] = await Promise.all([
 *   deduplicateRequest('/users', () => api.get('/users')),
 *   deduplicateRequest('/users', () => api.get('/users')),
 * ]);
 * ```
 */
export declare function deduplicateRequest<T>(key: string, execute: () => Promise<T>): Promise<T>;
//# sourceMappingURL=rest.d.ts.map