query-optimistic 0.1.0

package/dist/react/index.d.mts

@@ -0,0 +1,213 @@
+import { C as CollectionDef, Q as QueryOptions, a as Optimistic, E as EntityDef, M as MutationDef } from '../types-BRxQA1mR.mjs';
+
+/** Options for useQuery hook */
+interface UseQueryHookOptions<TParams> extends QueryOptions {
+    /** Parameters to pass to the fetch function */
+    params?: TParams;
+    /** Enable pagination mode (infinite query) */
+    paginated?: boolean;
+    /** For paginated: get params for each page */
+    getPageParams?: (context: {
+        pageParam: number;
+    }) => TParams;
+    /** Custom query key (defaults to [def.name, params]) */
+    queryKey?: readonly unknown[];
+}
+/** Query state object (second element of tuple) */
+interface QueryState {
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+/** Pagination state object (third element of paginated tuple) */
+interface PaginationState {
+    hasNextPage: boolean;
+    fetchNextPage: () => void;
+    isFetchingNextPage: boolean;
+}
+/** Return type for collection queries: [data, queryState] */
+type QueryResult<T> = [
+    Optimistic<T>[] | undefined,
+    QueryState
+];
+/** Return type for paginated queries: [data, queryState, paginationState] */
+type PaginatedQueryResult<T> = [
+    Optimistic<T>[] | undefined,
+    QueryState,
+    PaginationState
+];
+/** Return type for entity queries: [data, queryState] */
+type EntityResult<T> = [
+    Optimistic<T> | undefined,
+    QueryState
+];
+/**
+ * Unified query hook for fetching data
+ *
+ * @example
+ * // Simple collection query
+ * const [data, query] = useQuery(postsQuery, { params: { limit: 10 } })
+ *
+ * @example
+ * // Paginated query
+ * const [data, query, pagination] = useQuery(postsQuery, {
+ *   paginated: true,
+ *   getPageParams: ({ pageParam }) => ({ page: pageParam, limit: 10 })
+ * })
+ * // pagination.fetchNextPage(), pagination.hasNextPage
+ *
+ * @example
+ * // Entity query
+ * const [user, query] = useQuery(userEntity, { params: userId })
+ */
+declare function useQuery<TData, TParams>(def: CollectionDef<TData, TParams>, options?: UseQueryHookOptions<TParams> & {
+    paginated: true;
+}): PaginatedQueryResult<TData>;
+declare function useQuery<TData, TParams>(def: CollectionDef<TData, TParams>, options?: UseQueryHookOptions<TParams>): QueryResult<TData>;
+declare function useQuery<TData, TParams>(def: EntityDef<TData, TParams>, options?: UseQueryHookOptions<TParams>): EntityResult<TData>;
+
+/** Extract entity type from a collection or entity definition */
+type InferEntity<T> = T extends CollectionDef<infer TData, any> ? TData & {} : T extends EntityDef<infer TData, any> ? TData & {} : never;
+/** Base optimistic config with shared properties */
+interface OptimisticConfigBase<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> {
+    /** Target collection/entity to update */
+    target: TTarget;
+    /** Whether to sync with server response (replace optimistic with real data) */
+    sync?: boolean;
+}
+/** Config for prepend/append actions - requires full entity */
+interface OptimisticPrependAppendConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'prepend' | 'append';
+    /** Data to prepend/append - must be a full entity */
+    data: (params: TParams) => NoInfer<InferEntity<TTarget>>;
+}
+/** Config for replace action */
+interface OptimisticReplaceConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'replace';
+    /** Data for replacement */
+    data: (params: TParams) => NoInfer<InferEntity<TTarget>>;
+    /** ID of item to replace */
+    id?: string | ((params: TParams) => string);
+    /** Filter function to find items to replace */
+    where?: (item: NoInfer<InferEntity<TTarget>>) => boolean;
+}
+/** Config for update action */
+interface OptimisticUpdateConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'update';
+    /** Partial data for update */
+    data?: (params: TParams) => Partial<NoInfer<InferEntity<TTarget>>>;
+    /** ID of item to update */
+    id?: string | ((params: TParams) => string);
+    /** Filter function to find items to update */
+    where?: (item: NoInfer<InferEntity<TTarget>>) => boolean;
+    /** Update function */
+    update?: (item: NoInfer<InferEntity<TTarget>>, params: TParams) => NoInfer<InferEntity<TTarget>>;
+}
+/** Config for delete action */
+interface OptimisticDeleteConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'delete';
+    /** ID of item to delete */
+    id?: string | ((params: TParams) => string);
+    /** Filter function to find items to delete */
+    where?: (item: NoInfer<InferEntity<TTarget>>) => boolean;
+}
+/** Optimistic update configuration - type inferred from target */
+type OptimisticConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> = OptimisticPrependAppendConfig<TTarget, TParams> | OptimisticReplaceConfig<TTarget, TParams> | OptimisticUpdateConfig<TTarget, TParams> | OptimisticDeleteConfig<TTarget, TParams>;
+/** Internal transaction type for batched mutations */
+interface MutationTransaction {
+    target: CollectionDef<any, any> | EntityDef<any, any>;
+    action: 'prepend' | 'append' | 'update' | 'delete' | 'replace';
+    data?: any;
+    id?: string;
+    where?: (item: any) => boolean;
+    update?: (item: any) => any;
+    sync?: boolean;
+}
+/** Internal collection channel for batched mutations */
+declare class BatchedCollectionChannel<TEntity> {
+    private readonly target;
+    private readonly transactions;
+    constructor(target: CollectionDef<TEntity, any>, transactions: MutationTransaction[]);
+    prepend(data: TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    append(data: TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    update(id: string, updateFn: (item: TEntity) => TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    delete(id: string): this;
+}
+/** Internal entity channel for batched mutations */
+declare class BatchedEntityChannel<TEntity> {
+    private readonly target;
+    private readonly transactions;
+    constructor(target: EntityDef<TEntity, any>, transactions: MutationTransaction[]);
+    update(updateFn: (item: TEntity) => TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    replace(data: TEntity, options?: {
+        sync?: boolean;
+    }): this;
+}
+/** Internal batched channel type */
+interface BatchedChannel {
+    <TEntity>(target: CollectionDef<TEntity, any>): BatchedCollectionChannel<TEntity>;
+    <TEntity>(target: EntityDef<TEntity, any>): BatchedEntityChannel<TEntity>;
+}
+/** Options for useMutation hook */
+interface UseMutationOptions<TParams, TResponse> {
+    /** Called when mutation starts */
+    onMutate?: (params: TParams) => void;
+    /** Called on success */
+    onSuccess?: (data: TResponse, params: TParams) => void;
+    /** Called on error */
+    onError?: (error: Error, params: TParams) => void;
+}
+/** Return type for useMutation */
+interface MutationResult<TParams, TResponse> {
+    mutate: (params: TParams) => void;
+    mutateAsync: (params: TParams) => Promise<TResponse>;
+    isLoading: boolean;
+    isPending: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    error: Error | null;
+    data: TResponse | undefined;
+    reset: () => void;
+}
+/**
+ * Mutation hook with simplified optimistic updates
+ *
+ * @example
+ * // Simple mutation
+ * const { mutate } = useMutation(createPost)
+ *
+ * @example
+ * // With optimistic update
+ * const { mutate } = useMutation(createPost, {
+ *   optimistic: {
+ *     target: postsQuery,
+ *     action: 'prepend',
+ *     data: (params) => ({ ...params, _id: 'temp-id' })
+ *   }
+ * })
+ *
+ * @example
+ * // Multiple optimistic updates
+ * const { mutate } = useMutation(deletePost, {
+ *   optimistic: [
+ *     { target: postsQuery, action: 'delete', id: (p) => p.postId },
+ *     { target: userStatsEntity, action: 'update', update: (stats) => ({ ...stats, postCount: stats.postCount - 1 }) }
+ *   ]
+ * })
+ */
+declare function useMutation<TParams, TResponse>(def: MutationDef<TParams, TResponse>, options?: UseMutationOptions<TParams, TResponse> & {
+    /** Optimistic update configuration - receives channel and params */
+    optimistic?: (channel: BatchedChannel, params: TParams) => void;
+}): MutationResult<TParams, TResponse>;
+
+export { type EntityResult, type MutationResult, type OptimisticConfig, type PaginatedQueryResult, type PaginationState, type QueryResult, type QueryState, type UseMutationOptions, type UseQueryHookOptions, useMutation, useQuery };

package/dist/react/index.d.ts

@@ -0,0 +1,213 @@
+import { C as CollectionDef, Q as QueryOptions, a as Optimistic, E as EntityDef, M as MutationDef } from '../types-BRxQA1mR.js';
+
+/** Options for useQuery hook */
+interface UseQueryHookOptions<TParams> extends QueryOptions {
+    /** Parameters to pass to the fetch function */
+    params?: TParams;
+    /** Enable pagination mode (infinite query) */
+    paginated?: boolean;
+    /** For paginated: get params for each page */
+    getPageParams?: (context: {
+        pageParam: number;
+    }) => TParams;
+    /** Custom query key (defaults to [def.name, params]) */
+    queryKey?: readonly unknown[];
+}
+/** Query state object (second element of tuple) */
+interface QueryState {
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+/** Pagination state object (third element of paginated tuple) */
+interface PaginationState {
+    hasNextPage: boolean;
+    fetchNextPage: () => void;
+    isFetchingNextPage: boolean;
+}
+/** Return type for collection queries: [data, queryState] */
+type QueryResult<T> = [
+    Optimistic<T>[] | undefined,
+    QueryState
+];
+/** Return type for paginated queries: [data, queryState, paginationState] */
+type PaginatedQueryResult<T> = [
+    Optimistic<T>[] | undefined,
+    QueryState,
+    PaginationState
+];
+/** Return type for entity queries: [data, queryState] */
+type EntityResult<T> = [
+    Optimistic<T> | undefined,
+    QueryState
+];
+/**
+ * Unified query hook for fetching data
+ *
+ * @example
+ * // Simple collection query
+ * const [data, query] = useQuery(postsQuery, { params: { limit: 10 } })
+ *
+ * @example
+ * // Paginated query
+ * const [data, query, pagination] = useQuery(postsQuery, {
+ *   paginated: true,
+ *   getPageParams: ({ pageParam }) => ({ page: pageParam, limit: 10 })
+ * })
+ * // pagination.fetchNextPage(), pagination.hasNextPage
+ *
+ * @example
+ * // Entity query
+ * const [user, query] = useQuery(userEntity, { params: userId })
+ */
+declare function useQuery<TData, TParams>(def: CollectionDef<TData, TParams>, options?: UseQueryHookOptions<TParams> & {
+    paginated: true;
+}): PaginatedQueryResult<TData>;
+declare function useQuery<TData, TParams>(def: CollectionDef<TData, TParams>, options?: UseQueryHookOptions<TParams>): QueryResult<TData>;
+declare function useQuery<TData, TParams>(def: EntityDef<TData, TParams>, options?: UseQueryHookOptions<TParams>): EntityResult<TData>;
+
+/** Extract entity type from a collection or entity definition */
+type InferEntity<T> = T extends CollectionDef<infer TData, any> ? TData & {} : T extends EntityDef<infer TData, any> ? TData & {} : never;
+/** Base optimistic config with shared properties */
+interface OptimisticConfigBase<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> {
+    /** Target collection/entity to update */
+    target: TTarget;
+    /** Whether to sync with server response (replace optimistic with real data) */
+    sync?: boolean;
+}
+/** Config for prepend/append actions - requires full entity */
+interface OptimisticPrependAppendConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'prepend' | 'append';
+    /** Data to prepend/append - must be a full entity */
+    data: (params: TParams) => NoInfer<InferEntity<TTarget>>;
+}
+/** Config for replace action */
+interface OptimisticReplaceConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'replace';
+    /** Data for replacement */
+    data: (params: TParams) => NoInfer<InferEntity<TTarget>>;
+    /** ID of item to replace */
+    id?: string | ((params: TParams) => string);
+    /** Filter function to find items to replace */
+    where?: (item: NoInfer<InferEntity<TTarget>>) => boolean;
+}
+/** Config for update action */
+interface OptimisticUpdateConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'update';
+    /** Partial data for update */
+    data?: (params: TParams) => Partial<NoInfer<InferEntity<TTarget>>>;
+    /** ID of item to update */
+    id?: string | ((params: TParams) => string);
+    /** Filter function to find items to update */
+    where?: (item: NoInfer<InferEntity<TTarget>>) => boolean;
+    /** Update function */
+    update?: (item: NoInfer<InferEntity<TTarget>>, params: TParams) => NoInfer<InferEntity<TTarget>>;
+}
+/** Config for delete action */
+interface OptimisticDeleteConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> extends OptimisticConfigBase<TTarget, TParams> {
+    action: 'delete';
+    /** ID of item to delete */
+    id?: string | ((params: TParams) => string);
+    /** Filter function to find items to delete */
+    where?: (item: NoInfer<InferEntity<TTarget>>) => boolean;
+}
+/** Optimistic update configuration - type inferred from target */
+type OptimisticConfig<TTarget extends CollectionDef<any, any> | EntityDef<any, any>, TParams> = OptimisticPrependAppendConfig<TTarget, TParams> | OptimisticReplaceConfig<TTarget, TParams> | OptimisticUpdateConfig<TTarget, TParams> | OptimisticDeleteConfig<TTarget, TParams>;
+/** Internal transaction type for batched mutations */
+interface MutationTransaction {
+    target: CollectionDef<any, any> | EntityDef<any, any>;
+    action: 'prepend' | 'append' | 'update' | 'delete' | 'replace';
+    data?: any;
+    id?: string;
+    where?: (item: any) => boolean;
+    update?: (item: any) => any;
+    sync?: boolean;
+}
+/** Internal collection channel for batched mutations */
+declare class BatchedCollectionChannel<TEntity> {
+    private readonly target;
+    private readonly transactions;
+    constructor(target: CollectionDef<TEntity, any>, transactions: MutationTransaction[]);
+    prepend(data: TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    append(data: TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    update(id: string, updateFn: (item: TEntity) => TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    delete(id: string): this;
+}
+/** Internal entity channel for batched mutations */
+declare class BatchedEntityChannel<TEntity> {
+    private readonly target;
+    private readonly transactions;
+    constructor(target: EntityDef<TEntity, any>, transactions: MutationTransaction[]);
+    update(updateFn: (item: TEntity) => TEntity, options?: {
+        sync?: boolean;
+    }): this;
+    replace(data: TEntity, options?: {
+        sync?: boolean;
+    }): this;
+}
+/** Internal batched channel type */
+interface BatchedChannel {
+    <TEntity>(target: CollectionDef<TEntity, any>): BatchedCollectionChannel<TEntity>;
+    <TEntity>(target: EntityDef<TEntity, any>): BatchedEntityChannel<TEntity>;
+}
+/** Options for useMutation hook */
+interface UseMutationOptions<TParams, TResponse> {
+    /** Called when mutation starts */
+    onMutate?: (params: TParams) => void;
+    /** Called on success */
+    onSuccess?: (data: TResponse, params: TParams) => void;
+    /** Called on error */
+    onError?: (error: Error, params: TParams) => void;
+}
+/** Return type for useMutation */
+interface MutationResult<TParams, TResponse> {
+    mutate: (params: TParams) => void;
+    mutateAsync: (params: TParams) => Promise<TResponse>;
+    isLoading: boolean;
+    isPending: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    error: Error | null;
+    data: TResponse | undefined;
+    reset: () => void;
+}
+/**
+ * Mutation hook with simplified optimistic updates
+ *
+ * @example
+ * // Simple mutation
+ * const { mutate } = useMutation(createPost)
+ *
+ * @example
+ * // With optimistic update
+ * const { mutate } = useMutation(createPost, {
+ *   optimistic: {
+ *     target: postsQuery,
+ *     action: 'prepend',
+ *     data: (params) => ({ ...params, _id: 'temp-id' })
+ *   }
+ * })
+ *
+ * @example
+ * // Multiple optimistic updates
+ * const { mutate } = useMutation(deletePost, {
+ *   optimistic: [
+ *     { target: postsQuery, action: 'delete', id: (p) => p.postId },
+ *     { target: userStatsEntity, action: 'update', update: (stats) => ({ ...stats, postCount: stats.postCount - 1 }) }
+ *   ]
+ * })
+ */
+declare function useMutation<TParams, TResponse>(def: MutationDef<TParams, TResponse>, options?: UseMutationOptions<TParams, TResponse> & {
+    /** Optimistic update configuration - receives channel and params */
+    optimistic?: (channel: BatchedChannel, params: TParams) => void;
+}): MutationResult<TParams, TResponse>;
+
+export { type EntityResult, type MutationResult, type OptimisticConfig, type PaginatedQueryResult, type PaginationState, type QueryResult, type QueryState, type UseMutationOptions, type UseQueryHookOptions, useMutation, useQuery };