@tanstack/react-optimistic/dist/esm/useCollection.d.ts

React hooks for optimistic updates

import { Collection, preloadCollection, CollectionConfig, SortedMap, Transaction } from '@tanstack/optimistic';
export { preloadCollection };
/**
 * Hook that provides access to all collections
 *
 * @returns A Map of all collections with their states and transactions
 */
export declare function useCollections(): Map<string, {
    state: Map<unknown, unknown>;
    transactions: SortedMap<string, Transaction>;
}>;
/**
 * Hook to use a specific collection with React
 *
 * @template T - Type of data in the collection
 * @template R - Return type of the selector function
 * @param config - Configuration for the collection
 * @param selector - TODO Optional selector function to transform the collection data
 * @returns Object containing collection data and CRUD operations
 */
export declare function useCollection<T extends object>(config: CollectionConfig<T>): {
    /**
     * The collection data as a Map with keys as identifiers
     */
    state: Map<string, T>;
    /**
     * The collection data as an Array of data
     */
    data: Array<T>;
    /**
     * Updates an existing item in the collection
     *
     * @param item - The item to update (must exist in collection)
     * @param configOrCallback - Update configuration or callback function
     * @param maybeCallback - Callback function if config was provided
     * @returns {Transaction} A Transaction object representing the update operation
     * @throws {SchemaValidationError} If the updated data fails schema validation
     * @throws {Error} If mutationFn is not provided in the collection config
     * @example
     * // Update a single item
     * update(todo, (draft) => { draft.completed = true })
     *
     * // Update multiple items
     * update([todo1, todo2], (drafts) => {
     *   drafts.forEach(draft => { draft.completed = true })
     * })
     *
     * // Update with metadata
     * update(todo, { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
     */
    update: Collection<T>[`update`];
    /**
     * Inserts a new item or items into the collection
     *
     * @param data - Single item or array of items to insert
     * @param config - Optional configuration including key(s) and metadata
     * @returns {Transaction} A Transaction object representing the insert operation
     * @throws {SchemaValidationError} If the data fails schema validation
     * @throws {Error} If more keys provided than items to insert
     * @throws {Error} If mutationFn is not provided in the collection config
     * @example
     * // Insert a single item
     * insert({ text: "Buy groceries", completed: false })
     *
     * // Insert multiple items
     * insert([
     *   { text: "Buy groceries", completed: false },
     *   { text: "Walk dog", completed: false }
     * ])
     *
     * // Insert with custom key
     * insert({ text: "Buy groceries" }, { key: "grocery-task" })
     */
    insert: Collection<T>[`insert`];
    /**
     * Deletes an item or items from the collection
     *
     * @param items - Item(s) to delete (must exist in collection) or their key(s)
     * @param config - Optional configuration including metadata
     * @returns {Transaction} A Transaction object representing the delete operation
     * @throws {Error} If mutationFn is not provided in the collection config
     * @example
     * // Delete a single item
     * delete(todo)
     *
     * // Delete multiple items
     * delete([todo1, todo2])
     *
     * // Delete with metadata
     * delete(todo, { metadata: { reason: "completed" } })
     */
    delete: Collection<T>[`delete`];
};
export declare function useCollection<T extends object, R>(config: CollectionConfig<T>, selector: (d: Map<string, T>) => R): {
    /**
     * The collection data as a Map with keys as identifiers
     */
    state: Map<string, T>;
    /**
     * The collection data as an Array of items
     */
    data: Array<T>;
    /**
     * Updates an existing item in the collection
     *
     * @param item - The item to update (must exist in collection)
     * @param configOrCallback - Update configuration or callback function
     * @param maybeCallback - Callback function if config was provided
     * @returns {Transaction} A Transaction object representing the update operation
     * @throws {SchemaValidationError} If the updated data fails schema validation
     * @throws {Error} If mutationFn is not provided in the collection config
     * @example
     * // Update a single item
     * update(todo, (draft) => { draft.completed = true })
     *
     * // Update multiple items
     * update([todo1, todo2], (drafts) => {
     *   drafts.forEach(draft => { draft.completed = true })
     * })
     *
     * // Update with metadata
     * update(todo, { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
     */
    update: Collection<T>[`update`];
    /**
     * Inserts a new item or items into the collection
     *
     * @param data - Single item or array of items to insert
     * @param config - Optional configuration including key(s) and metadata
     * @returns {Transaction} A Transaction object representing the insert operation
     * @throws {SchemaValidationError} If the data fails schema validation
     * @throws {Error} If more keys provided than items to insert
     * @throws {Error} If mutationFn is not provided in the collection config
     * @example
     * // Insert a single item
     * insert({ text: "Buy groceries", completed: false })
     *
     * // Insert multiple items
     * insert([
     *   { text: "Buy groceries", completed: false },
     *   { text: "Walk dog", completed: false }
     * ])
     *
     * // Insert with custom key
     * insert({ text: "Buy groceries" }, { key: "grocery-task" })
     */
    insert: Collection<T>[`insert`];
    /**
     * Deletes an item or items from the collection
     *
     * @param items - Item(s) to delete (must exist in collection) or their key(s)
     * @param config - Optional configuration including metadata
     * @returns {Transaction} A Transaction object representing the delete operation
     * @throws {Error} If mutationFn is not provided in the collection config
     * @example
     * // Delete a single item
     * delete(todo)
     *
     * // Delete multiple items
     * delete([todo1, todo2])
     *
     * // Delete with metadata
     * delete(todo, { metadata: { reason: "completed" } })
     */
    delete: Collection<T>[`delete`];
};
/**
 * Performs a shallow comparison between two objects
 * Used for equality checking in React hooks
 *
 * @template T - Type of objects to compare
 * @param objA - First object
 * @param objB - Second object
 * @returns True if objects are shallowly equal, false otherwise
 */
export declare function shallow<T>(objA: T, objB: T): boolean;