stunk 2.8.1 → 3.0.0-beta.1

package/dist/use-react/index.d.cts

@@ -1,98 +1,52 @@
-import { C as Chunk } from '../core-DMY69lzg.cjs';
+import { C as Chunk } from '../core-DsoxfUCH.cjs';
+import { P as PaginatedAsyncChunk, a as PaginationState, A as AsyncChunk, I as InfiniteAsyncChunk, M as Mutation, b as MutationResult } from '../mutation-Txd2ni6w.cjs';
 
 /**
- * A lightweight hook that subscribes to a chunk and returns its current value, along with setters, selector, reset and destroy.
- * Ensures reactivity and prevents unnecessary re-renders.
+ * Subscribes to a chunk and returns its current value along with `set`, `reset`, and `destroy`.
+ *
+ * Pass an optional `selector` to derive a slice of the value and avoid
+ * unnecessary re-renders when unrelated fields change.
+ *
+ * @param chunk - The chunk to subscribe to.
+ * @param selector - Optional function to select a derived value.
+ * @returns `[value, set, reset, destroy]`
+ *
+ * @example
+ * const [count, setCount, reset] = useChunk(countChunk);
+ *
+ * @example
+ * // Only re-renders when `name` changes
+ * const [name, setUser] = useChunk(userChunk, u => u.name);
  */
 declare function useChunk<T, S = T>(chunk: Chunk<T>, selector?: (value: T) => S): readonly [S, (valueOrUpdater: T | ((currentValue: T) => T)) => void, () => void, () => void];
 
 /**
- * A hook for creating a read-only derived value from a chunk.
- * Ensures reactivity and updates when the source chunk changes.
- */
-declare function useDerive<T, D>(chunk: Chunk<T>, fn: (value: T) => D): D;
-
-type ChunkValue<T> = T extends Chunk<infer U> ? U : never;
-type DependencyValues<T extends Chunk<any>[]> = {
-    [K in keyof T]: T[K] extends Chunk<any> ? ChunkValue<T[K]> : never;
-};
-
-/**
- * A hook that computes a value based on multiple chunks.
- * Automatically re-computes when any dependency changes.
- */
-declare function useComputed<TDeps extends Chunk<any>[], TResult>(dependencies: [...TDeps], computeFn: (...args: DependencyValues<TDeps>) => TResult): TResult;
-
-/**
- * A lightweight hook that subscribes to a chunk and returns only its current value.
- * Useful for read-only components that don't need to update the chunk.
+ * Subscribes to a chunk and returns only its current value.
+ * Use this in read-only components that never need to call `set`.
+ *
+ * @param chunk - The chunk to subscribe to.
+ * @param selector - Optional function to select a derived value.
+ *
+ * @example
+ * const name = useChunkValue(userChunk, u => u.name);
  */
 declare function useChunkValue<T, S = T>(chunk: Chunk<T>, selector?: (value: T) => S): S;
 
-/**
- * A hook that subscribes to a specific property of a chunk.
- * This optimizes renders by only updating when the selected property changes.
- */
-declare function useChunkProperty<T, K extends keyof T>(chunk: Chunk<T>, property: K): T[K];
-
-/**
- * Hook to read values from multiple chunks at once.
- * Only re-renders when any of the chunk values change.
- */
-declare function useChunkValues<T extends Chunk<any>[]>(chunks: [...T]): {
-    [K in keyof T]: T[K] extends Chunk<infer U> ? U : never;
-};
-
-interface AsyncState<T, E extends Error> {
-    loading: boolean;
-    error: E | null;
-    data: T | null;
-    lastFetched?: number;
-}
-interface PaginationState {
-    page: number;
-    pageSize: number;
-    total?: number;
-    hasMore?: boolean;
-}
-interface AsyncStateWithPagination<T, E extends Error> extends AsyncState<T, E> {
-    pagination?: PaginationState;
-}
-interface AsyncChunk<T, E extends Error = Error> extends Chunk<AsyncStateWithPagination<T, E>> {
-    /** Force reload data */
-    reload: (params?: any) => Promise<void>;
-    /** Smart refresh - respects stale time */
-    refresh: (params?: any) => Promise<void>;
-    /** Mutate data directly */
-    mutate: (mutator: (currentData: T | null) => T) => void;
-    /** Reset to initial state */
-    reset: () => void;
-    /** Clean up intervals */
-    cleanup: () => void;
-}
-interface PaginatedAsyncChunk<T, E extends Error = Error> extends AsyncChunk<T, E> {
-    /** Load next page */
-    nextPage: () => Promise<void>;
-    /** Load previous page */
-    prevPage: () => Promise<void>;
-    /** Go to specific page */
-    goToPage: (page: number) => Promise<void>;
-    /** Reset pagination to first page */
-    resetPagination: () => Promise<void>;
-}
-
 interface UseAsyncChunkResult<T, E extends Error, P extends Record<string, any>> {
     data: T | null;
     loading: boolean;
     error: E | null;
     lastFetched?: number;
+    /** True when showing stale data while a new fetch is in progress (keepPreviousData: true) */
+    isPlaceholderData: boolean;
     reload: (params?: Partial<P>) => Promise<void>;
     refresh: (params?: Partial<P>) => Promise<void>;
     mutate: (mutator: (currentData: T | null) => T) => void;
     reset: () => void;
 }
 interface UseAsyncChunkResultWithParams<T, E extends Error, P extends Record<string, any>> extends UseAsyncChunkResult<T, E, P> {
-    setParams: (params: Partial<P>) => void;
+    setParams: (params: Partial<Record<keyof P, P[keyof P] | null>>) => void;
+    clearParams: () => void;
 }
 interface UseAsyncChunkResultWithPagination<T, E extends Error, P extends Record<string, any>> extends UseAsyncChunkResult<T, E, P> {
     pagination?: PaginationState;
@@ -103,39 +57,122 @@ interface UseAsyncChunkResultWithPagination<T, E extends Error, P extends Record
 }
 interface UseAsyncChunkResultWithParamsAndPagination<T, E extends Error, P extends Record<string, any>> extends UseAsyncChunkResultWithParams<T, E, P>, Omit<UseAsyncChunkResultWithPagination<T, E, P>, keyof UseAsyncChunkResult<T, E, P>> {
 }
-/**
- * A hook that handles asynchronous state with built-in reactivity.
- * Provides loading, error, and data states with full asyncChunk functionality.
- */
 interface UseAsyncChunkOptions<P extends Record<string, any> = {}> {
-    /** Initial parameters to pass to the fetcher */
+    /** Initial parameters to pass to the fetcher on mount */
     initialParams?: Partial<P>;
-    /** Force fetch on mount, even without params (default: false) */
+    /**
+     * Force a fetch on mount even when the chunk has no params.
+     * Ignored if initialParams is provided.
+     * (default: false)
+     */
     fetchOnMount?: boolean;
 }
 declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T, E> & {
     setParams: (params: Partial<P>) => void;
-}, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResultWithParamsAndPagination<T, E, P>;
-declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T, E>, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResultWithPagination<T, E, P>;
+}, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResultWithParamsAndPagination<T, E, P>;
+declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T, E>, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResultWithPagination<T, E, P>;
 declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: AsyncChunk<T, E> & {
     setParams: (params: Partial<P>) => void;
-}, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResultWithParams<T, E, P>;
-declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: AsyncChunk<T, E>, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResult<T, E, P>;
+}, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResultWithParams<T, E, P>;
+declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: AsyncChunk<T, E>, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResult<T, E, P>;
 
 interface UseInfiniteAsyncChunkOptions<P extends Record<string, any>> extends Omit<UseAsyncChunkOptions<P>, 'initialParams'> {
-    /** Initial parameters (page and pageSize added automatically) */
+    /** Initial parameters — page and pageSize are managed automatically */
     initialParams?: Omit<Partial<P>, 'page' | 'pageSize'>;
-    /** Enable auto-loading on scroll (default: true) */
+    /** Automatically load next page when sentinel enters viewport (default: true) */
     autoLoad?: boolean;
-    /** Intersection observer threshold (default: 1.0) */
+    /** IntersectionObserver threshold — 0.0 to 1.0 (default: 1.0) */
     threshold?: number;
 }
+interface UseInfiniteAsyncChunkResult<T, E extends Error, P extends Record<string, any>> {
+    data: T[] | null;
+    loading: boolean;
+    error: E | null;
+    lastFetched?: number;
+    isPlaceholderData: boolean;
+    /** True when fetching a new page while existing data is already loaded */
+    isFetchingMore: boolean;
+    /** True if more pages are available */
+    hasMore: boolean;
+    reload: (params?: Partial<P>) => Promise<void>;
+    refresh: (params?: Partial<P>) => Promise<void>;
+    mutate: (mutator: (currentData: T[] | null) => T[]) => void;
+    reset: () => void;
+    nextPage: () => Promise<void>;
+    prevPage: () => Promise<void>;
+    goToPage: (page: number) => Promise<void>;
+    resetPagination: () => Promise<void>;
+    /** Manually trigger loading the next page */
+    loadMore: () => void;
+    /** Attach this ref to a sentinel element at the bottom of your list */
+    observerTarget: React.RefObject<HTMLElement>;
+}
 /**
- * Hook for infinite scroll functionality.
- * Automatically loads more data when scrolling to the bottom.
+ * Subscribes to an infinite async chunk and wires up automatic infinite scroll.
+ *
+ * Attach `observerTarget` to a sentinel element at the bottom of your list —
+ * the next page loads automatically when it enters the viewport.
+ * Use `loadMore()` for manual triggering.
+ *
+ * @param chunk - An `InfiniteAsyncChunk` instance.
+ * @param options.autoLoad - Auto-load on scroll (default: true).
+ * @param options.threshold - IntersectionObserver threshold 0.0–1.0 (default: 1.0).
+ * @param options.initialParams - Initial params excluding `page` and `pageSize`.
+ *
+ * @example
+ * const { data, loading, hasMore, observerTarget, loadMore } = useInfiniteAsyncChunk(postsChunk);
+ *
+ * return (
+ *   <>
+ *     {data?.map(post => <Post key={post.id} {...post} />)}
+ *     <div ref={observerTarget} />
+ *   </>
+ * );
  */
-declare function useInfiniteAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T[], E> & {
-    setParams: (params: Partial<P>) => void;
-}, options?: UseInfiniteAsyncChunkOptions<P>): any;
+declare function useInfiniteAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(chunk: InfiniteAsyncChunk<T, E, P>, options?: UseInfiniteAsyncChunkOptions<P>): UseInfiniteAsyncChunkResult<T, E, P>;
+
+interface UseMutationResult<TData, TError extends Error = Error, TVariables = void> {
+    /** Current mutation state */
+    loading: boolean;
+    data: TData | null;
+    error: TError | null;
+    isSuccess: boolean;
+    /**
+     * Execute the mutation. Always resolves — never throws.
+     * Safe to fire and forget, or await for local UI control.
+     *
+     * @example
+     * // Fire and forget
+     * mutate({ title: 'Hello' });
+     *
+     * // Await for local control — no try/catch needed
+     * const { data, error } = await mutate({ title: 'Hello' });
+     * if (!error) router.push('/posts');
+     */
+    mutate: TVariables extends void ? () => Promise<MutationResult<TData, TError>> : (variables: TVariables) => Promise<MutationResult<TData, TError>>;
+    /** Reset mutation state back to initial */
+    reset: () => void;
+}
+/**
+ * Subscribes to a mutation instance and returns its reactive state with `mutate` and `reset`.
+ *
+ * @param mutation - A `mutation()` instance from `stunk/query`.
+ *
+ * @example
+ * const createPost = mutation(
+ *   async (data: NewPost) => fetchAPI('/posts', { method: 'POST', body: data }),
+ *   { invalidates: [postsChunk] }
+ * );
+ *
+ * function CreatePostForm() {
+ *   const { mutate, loading, error, isSuccess } = useMutation(createPost);
+ *
+ *   const handleSubmit = async (data: NewPost) => {
+ *     const { error } = await mutate(data);
+ *     if (!error) router.push('/posts');
+ *   };
+ * }
+ */
+declare function useMutation<TData, TError extends Error = Error, TVariables = void>(mutation: Mutation<TData, TError, TVariables>): UseMutationResult<TData, TError, TVariables>;
 
-export { useAsyncChunk, useChunk, useChunkProperty, useChunkValue, useChunkValues, useComputed, useDerive, useInfiniteAsyncChunk };
+export { type UseMutationResult, useAsyncChunk, useChunk, useChunkValue, useInfiniteAsyncChunk, useMutation };

package/dist/use-react/index.d.ts

@@ -1,98 +1,52 @@
-import { C as Chunk } from '../core-DMY69lzg.js';
+import { C as Chunk } from '../core-DsoxfUCH.js';
+import { P as PaginatedAsyncChunk, a as PaginationState, A as AsyncChunk, I as InfiniteAsyncChunk, M as Mutation, b as MutationResult } from '../mutation-BGXZyZXA.js';
 
 /**
- * A lightweight hook that subscribes to a chunk and returns its current value, along with setters, selector, reset and destroy.
- * Ensures reactivity and prevents unnecessary re-renders.
+ * Subscribes to a chunk and returns its current value along with `set`, `reset`, and `destroy`.
+ *
+ * Pass an optional `selector` to derive a slice of the value and avoid
+ * unnecessary re-renders when unrelated fields change.
+ *
+ * @param chunk - The chunk to subscribe to.
+ * @param selector - Optional function to select a derived value.
+ * @returns `[value, set, reset, destroy]`
+ *
+ * @example
+ * const [count, setCount, reset] = useChunk(countChunk);
+ *
+ * @example
+ * // Only re-renders when `name` changes
+ * const [name, setUser] = useChunk(userChunk, u => u.name);
  */
 declare function useChunk<T, S = T>(chunk: Chunk<T>, selector?: (value: T) => S): readonly [S, (valueOrUpdater: T | ((currentValue: T) => T)) => void, () => void, () => void];
 
 /**
- * A hook for creating a read-only derived value from a chunk.
- * Ensures reactivity and updates when the source chunk changes.
- */
-declare function useDerive<T, D>(chunk: Chunk<T>, fn: (value: T) => D): D;
-
-type ChunkValue<T> = T extends Chunk<infer U> ? U : never;
-type DependencyValues<T extends Chunk<any>[]> = {
-    [K in keyof T]: T[K] extends Chunk<any> ? ChunkValue<T[K]> : never;
-};
-
-/**
- * A hook that computes a value based on multiple chunks.
- * Automatically re-computes when any dependency changes.
- */
-declare function useComputed<TDeps extends Chunk<any>[], TResult>(dependencies: [...TDeps], computeFn: (...args: DependencyValues<TDeps>) => TResult): TResult;
-
-/**
- * A lightweight hook that subscribes to a chunk and returns only its current value.
- * Useful for read-only components that don't need to update the chunk.
+ * Subscribes to a chunk and returns only its current value.
+ * Use this in read-only components that never need to call `set`.
+ *
+ * @param chunk - The chunk to subscribe to.
+ * @param selector - Optional function to select a derived value.
+ *
+ * @example
+ * const name = useChunkValue(userChunk, u => u.name);
  */
 declare function useChunkValue<T, S = T>(chunk: Chunk<T>, selector?: (value: T) => S): S;
 
-/**
- * A hook that subscribes to a specific property of a chunk.
- * This optimizes renders by only updating when the selected property changes.
- */
-declare function useChunkProperty<T, K extends keyof T>(chunk: Chunk<T>, property: K): T[K];
-
-/**
- * Hook to read values from multiple chunks at once.
- * Only re-renders when any of the chunk values change.
- */
-declare function useChunkValues<T extends Chunk<any>[]>(chunks: [...T]): {
-    [K in keyof T]: T[K] extends Chunk<infer U> ? U : never;
-};
-
-interface AsyncState<T, E extends Error> {
-    loading: boolean;
-    error: E | null;
-    data: T | null;
-    lastFetched?: number;
-}
-interface PaginationState {
-    page: number;
-    pageSize: number;
-    total?: number;
-    hasMore?: boolean;
-}
-interface AsyncStateWithPagination<T, E extends Error> extends AsyncState<T, E> {
-    pagination?: PaginationState;
-}
-interface AsyncChunk<T, E extends Error = Error> extends Chunk<AsyncStateWithPagination<T, E>> {
-    /** Force reload data */
-    reload: (params?: any) => Promise<void>;
-    /** Smart refresh - respects stale time */
-    refresh: (params?: any) => Promise<void>;
-    /** Mutate data directly */
-    mutate: (mutator: (currentData: T | null) => T) => void;
-    /** Reset to initial state */
-    reset: () => void;
-    /** Clean up intervals */
-    cleanup: () => void;
-}
-interface PaginatedAsyncChunk<T, E extends Error = Error> extends AsyncChunk<T, E> {
-    /** Load next page */
-    nextPage: () => Promise<void>;
-    /** Load previous page */
-    prevPage: () => Promise<void>;
-    /** Go to specific page */
-    goToPage: (page: number) => Promise<void>;
-    /** Reset pagination to first page */
-    resetPagination: () => Promise<void>;
-}
-
 interface UseAsyncChunkResult<T, E extends Error, P extends Record<string, any>> {
     data: T | null;
     loading: boolean;
     error: E | null;
     lastFetched?: number;
+    /** True when showing stale data while a new fetch is in progress (keepPreviousData: true) */
+    isPlaceholderData: boolean;
     reload: (params?: Partial<P>) => Promise<void>;
     refresh: (params?: Partial<P>) => Promise<void>;
     mutate: (mutator: (currentData: T | null) => T) => void;
     reset: () => void;
 }
 interface UseAsyncChunkResultWithParams<T, E extends Error, P extends Record<string, any>> extends UseAsyncChunkResult<T, E, P> {
-    setParams: (params: Partial<P>) => void;
+    setParams: (params: Partial<Record<keyof P, P[keyof P] | null>>) => void;
+    clearParams: () => void;
 }
 interface UseAsyncChunkResultWithPagination<T, E extends Error, P extends Record<string, any>> extends UseAsyncChunkResult<T, E, P> {
     pagination?: PaginationState;
@@ -103,39 +57,122 @@ interface UseAsyncChunkResultWithPagination<T, E extends Error, P extends Record
 }
 interface UseAsyncChunkResultWithParamsAndPagination<T, E extends Error, P extends Record<string, any>> extends UseAsyncChunkResultWithParams<T, E, P>, Omit<UseAsyncChunkResultWithPagination<T, E, P>, keyof UseAsyncChunkResult<T, E, P>> {
 }
-/**
- * A hook that handles asynchronous state with built-in reactivity.
- * Provides loading, error, and data states with full asyncChunk functionality.
- */
 interface UseAsyncChunkOptions<P extends Record<string, any> = {}> {
-    /** Initial parameters to pass to the fetcher */
+    /** Initial parameters to pass to the fetcher on mount */
     initialParams?: Partial<P>;
-    /** Force fetch on mount, even without params (default: false) */
+    /**
+     * Force a fetch on mount even when the chunk has no params.
+     * Ignored if initialParams is provided.
+     * (default: false)
+     */
     fetchOnMount?: boolean;
 }
 declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T, E> & {
     setParams: (params: Partial<P>) => void;
-}, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResultWithParamsAndPagination<T, E, P>;
-declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T, E>, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResultWithPagination<T, E, P>;
+}, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResultWithParamsAndPagination<T, E, P>;
+declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T, E>, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResultWithPagination<T, E, P>;
 declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: AsyncChunk<T, E> & {
     setParams: (params: Partial<P>) => void;
-}, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResultWithParams<T, E, P>;
-declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: AsyncChunk<T, E>, options?: UseAsyncChunkOptions<P> | Partial<P>): UseAsyncChunkResult<T, E, P>;
+}, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResultWithParams<T, E, P>;
+declare function useAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: AsyncChunk<T, E>, options?: UseAsyncChunkOptions<P>): UseAsyncChunkResult<T, E, P>;
 
 interface UseInfiniteAsyncChunkOptions<P extends Record<string, any>> extends Omit<UseAsyncChunkOptions<P>, 'initialParams'> {
-    /** Initial parameters (page and pageSize added automatically) */
+    /** Initial parameters — page and pageSize are managed automatically */
     initialParams?: Omit<Partial<P>, 'page' | 'pageSize'>;
-    /** Enable auto-loading on scroll (default: true) */
+    /** Automatically load next page when sentinel enters viewport (default: true) */
     autoLoad?: boolean;
-    /** Intersection observer threshold (default: 1.0) */
+    /** IntersectionObserver threshold — 0.0 to 1.0 (default: 1.0) */
     threshold?: number;
 }
+interface UseInfiniteAsyncChunkResult<T, E extends Error, P extends Record<string, any>> {
+    data: T[] | null;
+    loading: boolean;
+    error: E | null;
+    lastFetched?: number;
+    isPlaceholderData: boolean;
+    /** True when fetching a new page while existing data is already loaded */
+    isFetchingMore: boolean;
+    /** True if more pages are available */
+    hasMore: boolean;
+    reload: (params?: Partial<P>) => Promise<void>;
+    refresh: (params?: Partial<P>) => Promise<void>;
+    mutate: (mutator: (currentData: T[] | null) => T[]) => void;
+    reset: () => void;
+    nextPage: () => Promise<void>;
+    prevPage: () => Promise<void>;
+    goToPage: (page: number) => Promise<void>;
+    resetPagination: () => Promise<void>;
+    /** Manually trigger loading the next page */
+    loadMore: () => void;
+    /** Attach this ref to a sentinel element at the bottom of your list */
+    observerTarget: React.RefObject<HTMLElement>;
+}
 /**
- * Hook for infinite scroll functionality.
- * Automatically loads more data when scrolling to the bottom.
+ * Subscribes to an infinite async chunk and wires up automatic infinite scroll.
+ *
+ * Attach `observerTarget` to a sentinel element at the bottom of your list —
+ * the next page loads automatically when it enters the viewport.
+ * Use `loadMore()` for manual triggering.
+ *
+ * @param chunk - An `InfiniteAsyncChunk` instance.
+ * @param options.autoLoad - Auto-load on scroll (default: true).
+ * @param options.threshold - IntersectionObserver threshold 0.0–1.0 (default: 1.0).
+ * @param options.initialParams - Initial params excluding `page` and `pageSize`.
+ *
+ * @example
+ * const { data, loading, hasMore, observerTarget, loadMore } = useInfiniteAsyncChunk(postsChunk);
+ *
+ * return (
+ *   <>
+ *     {data?.map(post => <Post key={post.id} {...post} />)}
+ *     <div ref={observerTarget} />
+ *   </>
+ * );
  */
-declare function useInfiniteAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(asyncChunk: PaginatedAsyncChunk<T[], E> & {
-    setParams: (params: Partial<P>) => void;
-}, options?: UseInfiniteAsyncChunkOptions<P>): any;
+declare function useInfiniteAsyncChunk<T, E extends Error = Error, P extends Record<string, any> = {}>(chunk: InfiniteAsyncChunk<T, E, P>, options?: UseInfiniteAsyncChunkOptions<P>): UseInfiniteAsyncChunkResult<T, E, P>;
+
+interface UseMutationResult<TData, TError extends Error = Error, TVariables = void> {
+    /** Current mutation state */
+    loading: boolean;
+    data: TData | null;
+    error: TError | null;
+    isSuccess: boolean;
+    /**
+     * Execute the mutation. Always resolves — never throws.
+     * Safe to fire and forget, or await for local UI control.
+     *
+     * @example
+     * // Fire and forget
+     * mutate({ title: 'Hello' });
+     *
+     * // Await for local control — no try/catch needed
+     * const { data, error } = await mutate({ title: 'Hello' });
+     * if (!error) router.push('/posts');
+     */
+    mutate: TVariables extends void ? () => Promise<MutationResult<TData, TError>> : (variables: TVariables) => Promise<MutationResult<TData, TError>>;
+    /** Reset mutation state back to initial */
+    reset: () => void;
+}
+/**
+ * Subscribes to a mutation instance and returns its reactive state with `mutate` and `reset`.
+ *
+ * @param mutation - A `mutation()` instance from `stunk/query`.
+ *
+ * @example
+ * const createPost = mutation(
+ *   async (data: NewPost) => fetchAPI('/posts', { method: 'POST', body: data }),
+ *   { invalidates: [postsChunk] }
+ * );
+ *
+ * function CreatePostForm() {
+ *   const { mutate, loading, error, isSuccess } = useMutation(createPost);
+ *
+ *   const handleSubmit = async (data: NewPost) => {
+ *     const { error } = await mutate(data);
+ *     if (!error) router.push('/posts');
+ *   };
+ * }
+ */
+declare function useMutation<TData, TError extends Error = Error, TVariables = void>(mutation: Mutation<TData, TError, TVariables>): UseMutationResult<TData, TError, TVariables>;
 
-export { useAsyncChunk, useChunk, useChunkProperty, useChunkValue, useChunkValues, useComputed, useDerive, useInfiniteAsyncChunk };
+export { type UseMutationResult, useAsyncChunk, useChunk, useChunkValue, useInfiniteAsyncChunk, useMutation };

package/dist/use-react/index.js

@@ -1 +1 @@
-import {useState,useEffect,useCallback,useRef,useMemo}from'react';var U=new Set,V=new Map,N=0;function T(e,r=[]){if(e===null)throw new Error("Initial value cannot be null.");let t=e,n=new Set,s=N++,i=()=>{n.forEach(f=>f(t));};V.set(s,{notify:i});let o=()=>{n.size!==0&&(i());},u=()=>t,l=f=>{let h;typeof f=="function"?h=f(t):h=f,E(t,h);let p=j(h,r);p!==t&&(t=p,o());},a=f=>{if(typeof f!="function")throw new Error("Callback must be a function.");return n.add(f),f(t),()=>n.delete(f)};return {get:u,set:l,subscribe:a,derive:f=>{if(typeof f!="function")throw new Error("Derive function must be a function.");let h=f(t),p=T(h),b=a(()=>{let v=f(t);p.set(v);}),A=p.destroy;return p.destroy=()=>{b(),A();},p},reset:()=>{t=e,o();},destroy:()=>{n.clear(),t=e,U.delete(s),V.delete(s);}}}function j(e,r){if(e===null)throw new Error("Value cannot be null.");let t=e;for(let n=0;n<r.length;n++){let s=r[n],i=typeof s=="function"?s:s.fn,o=typeof s=="function"?`index ${n}`:s.name||`index ${n}`;try{let u=i(t);if(u===void 0)break;if(u===null)throw new Error(`Middleware "${o}" returned null value.`);t=u;}catch(u){let l=u instanceof Error?u.message:String(u);throw new Error(`Middleware "${o}" threw an error: ${l}`)}}return t}function x(e,r){if(e===r)return  true;if(!e||!r||typeof e!=typeof r)return  false;if(Array.isArray(e)&&Array.isArray(r)){if(e.length!==r.length)return  false;for(let t=0;t<e.length;t++)if(e[t]!==r[t])return  false;return  true}if(typeof e=="object"&&typeof r=="object"){let t=Object.keys(e),n=Object.keys(r);if(t.length!==n.length)return  false;for(let s of t)if(!Object.prototype.hasOwnProperty.call(r,s)||e[s]!==r[s])return  false;return  true}return  false}function E(e,r,t=""){if(typeof e=="object"&&e!==null&&typeof r=="object"&&r!==null){if(Array.isArray(e)&&Array.isArray(r)){if(e.length>0&&typeof e[0]=="object")for(let n=0;n<r.length;n++)E(e[0],r[n],`${t}[${n}]`);}else if(!Array.isArray(e)&&!Array.isArray(r)){let n=Object.keys(e),s=Object.keys(r),i=s.filter(o=>!n.includes(o));i.length>0&&(console.error(`\u{1F6A8} Stunk: Unknown properties detected at '${t||"root"}': ${i.join(", ")}. This might cause bugs.`),console.error("Expected keys:",n),console.error("Received keys:",s));for(let o of n)E(e[o],r[o],t?`${t}.${o}`:o);}}}function R(e,r,t={}){let{useShallowEqual:n=false}=t,s=e.get(),i=r(s),o=T(i),u=()=>{let a=e.get(),c=r(a);s=a,(n?!x(c,i):c!==i)&&(i=c,o.set(c));},l=e.subscribe(u);return {get:()=>o.get(),set:()=>{throw new Error("Cannot set values directly on a selector. Modify the source chunk instead.")},subscribe:o.subscribe,derive:a=>R(o,a,t),reset:()=>{throw new Error("Cannot reset a selector chunk. Reset the source chunk instead.")},destroy:()=>{l(),o.destroy();}}}function k(e,r){let t=r?R(e,r):e,[n,s]=useState(()=>t.get());useEffect(()=>{let l=t.subscribe(a=>{s(()=>a);});return ()=>l()},[t]);let i=useCallback(l=>{e.set(l);},[e]),o=useCallback(()=>{e.reset();},[e]),u=useCallback(()=>{e.destroy();},[e]);return [n,i,o,u]}function J(e,r){let t=useRef(r);useEffect(()=>{t.current=r;},[r]);let n=useMemo(()=>e.derive(i=>t.current(i)),[e]),[s]=k(n);return s}function K(e,r){let t=e.map(a=>a.get()),n=r(...t),s=T(n),i=s.set,o=false,u=()=>{let a=false;for(let c=0;c<e.length;c++){let y=e[c].get();y!==t[c]&&(t[c]=y,a=true);}if(a){let c=r(...t);c!==n&&(typeof c!="object"||typeof n!="object"||!x(c,n))&&(n=c,i(c)),o=false;}},l=e.map(a=>a.subscribe(()=>{o=true,u();}));return {...s,get:()=>(o&&u(),n),recompute:u,isDirty:()=>o,set:()=>{throw new Error("Cannot set values directly on computed. Modify the source chunk instead.")},reset:()=>(e.forEach(a=>{typeof a.reset=="function"&&a.reset();}),o=true,u(),n),destroy:()=>{l.forEach(a=>a()),s.destroy?.();}}}function Z(e,r){let t=useMemo(()=>K(e,r),[...e]),[n,s]=useState(()=>t.get());return useEffect(()=>{let i=t.subscribe(o=>{s(o);});return ()=>{i();}},[t]),n}function D(e,r){let[t]=k(e,r);return t}function ee(e,r){let t=useMemo(()=>n=>n[r],[r]);return D(e,t)}function ne(e){let[r,t]=useState(()=>e.map(n=>n.get()));return useEffect(()=>{let n=e.map((s,i)=>s.subscribe(o=>{t(u=>{let l=[...u];return l[i]=o,l});}));return ()=>{n.forEach(s=>s());}},[e]),r}function C(e){return "nextPage"in e}function W(e){return "setParams"in e}function O(e,r){let{initialParams:t,fetchOnMount:n}=typeof r=="object"&&("initialParams"in r||"fetchOnMount"in r)?r:{initialParams:r,fetchOnMount:false},[s,i]=useState(()=>e.get()),o=useRef(null);(!o.current||o.current.chunk!==e)&&(o.current={chunk:e,initialParams:t,fetchOnMount:n}),useEffect(()=>e.subscribe(g=>{i(g);}),[e]),useEffect(()=>{let d=o.current,g=d?.initialParams,q=d?.fetchOnMount;g&&W(e)?e.setParams(g):q&&!g&&e.reload();},[e]),useEffect(()=>()=>{e.cleanup();},[e]);let u=useCallback(d=>e.reload(d),[e]),l=useCallback(d=>e.refresh(d),[e]),a=useCallback(d=>e.mutate(d),[e]),c=useCallback(()=>e.reset(),[e]),y=useCallback(d=>{"setParams"in e&&e.setParams(d);},[e]),P=useCallback(()=>C(e)?e.nextPage():Promise.resolve(),[e]),f=useCallback(()=>C(e)?e.prevPage():Promise.resolve(),[e]),h=useCallback(d=>C(e)?e.goToPage(d):Promise.resolve(),[e]),p=useCallback(()=>C(e)?e.resetPagination():Promise.resolve(),[e]),{data:b,loading:A,error:v,lastFetched:$,pagination:I}=s,w={data:b,loading:A,error:v,lastFetched:$,reload:u,refresh:l,mutate:a,reset:c};if(W(e)&&(w.setParams=y),C(e)){let d=w;d.pagination=I,d.nextPage=P,d.prevPage=f,d.goToPage=h,d.resetPagination=p;}return w}function ce(e,r={}){let{initialParams:t,autoLoad:n=true,threshold:s=1,...i}=r,o=useRef(null),u=O(e,{initialParams:{...t,page:1,pageSize:e.get().pagination?.pageSize||10},...i}),{loading:l,pagination:a,nextPage:c}=u;useEffect(()=>{if(!n)return;let P=new IntersectionObserver(h=>{h[0].isIntersecting&&!l&&a?.hasMore&&c();},{threshold:s}),f=o.current;return f&&P.observe(f),()=>{f&&P.unobserve(f);}},[l,a?.hasMore,c,n,s]);let y=useCallback(()=>{!l&&a?.hasMore&&c();},[l,a?.hasMore,c]);return {...u,loadMore:y,observerTarget:o,hasMore:a?.hasMore??false,isFetchingMore:l&&(u.data?.length??0)>0}}export{O as useAsyncChunk,k as useChunk,ee as useChunkProperty,D as useChunkValue,ne as useChunkValues,Z as useComputed,J as useDerive,ce as useInfiniteAsyncChunk};
+import {a}from'../chunk-KWDC37TK.js';import {b}from'../chunk-3DOB632D.js';import {useState,useEffect,useCallback,useRef}from'react';function k(e,s,t={}){let{useShallowEqual:i=false}=t,u=e.get(),n=s(u),a$1=a(n),P=()=>{let m=e.get(),l=s(m);(i?!b(l,n):l!==n)&&(n=l,a$1.set(l));},o=e.subscribe(P),{set:d,reset:T,...E}=a$1;return {...E,derive:m=>k(a$1,m,t),destroy:()=>{o(),a$1.destroy();}}}function U(e,s){let t=s?k(e,s):e,[i,u]=useState(()=>t.get());useEffect(()=>{let o=t.subscribe(d=>{u(()=>d);});return ()=>o()},[t]);let n=useCallback(o=>{e.set(o);},[e]),a=useCallback(()=>{e.reset();},[e]),P=useCallback(()=>{e.destroy();},[e]);return [i,n,a,P]}function _(e,s){let[t]=U(e,s);return t}function x(e){return "nextPage"in e}function M(e){return "setParams"in e}function G(e){return "clearParams"in e}function O(e,s={}){let{initialParams:t,fetchOnMount:i=false}=s,[u,n]=useState(()=>e.get()),a=useRef({initialParams:t,fetchOnMount:i});a.current={initialParams:t,fetchOnMount:i},useEffect(()=>{n(e.get());let r=e.subscribe(q=>{n(q);}),{initialParams:D,fetchOnMount:F}=a.current;return D&&M(e)?e.setParams(D):F&&e.reload(),()=>{r(),e.cleanup();}},[e]);let P=useCallback(r=>e.reload(r),[e]),o=useCallback(r=>e.refresh(r),[e]),d=useCallback(r=>e.mutate(r),[e]),T=useCallback(()=>e.reset(),[e]),E=useCallback(r=>{M(e)&&e.setParams(r);},[e]),m=useCallback(()=>{G(e)&&e.clearParams();},[e]),l=useCallback(()=>x(e)?e.nextPage():Promise.resolve(),[e]),f=useCallback(()=>x(e)?e.prevPage():Promise.resolve(),[e]),h=useCallback(r=>x(e)?e.goToPage(r):Promise.resolve(),[e]),y=useCallback(()=>x(e)?e.resetPagination():Promise.resolve(),[e]),{data:b,loading:v,error:p,lastFetched:g,isPlaceholderData:C=false,pagination:w}=u,A={data:b,loading:v,error:p,lastFetched:g,isPlaceholderData:C,reload:P,refresh:o,mutate:d,reset:T};if(M(e)&&(A.setParams=E,A.clearParams=m),x(e)){let r=A;r.pagination=w,r.nextPage=l,r.prevPage=f,r.goToPage=h,r.resetPagination=y;}return A}function N(e,s={}){let{initialParams:t,autoLoad:i=true,threshold:u=1,fetchOnMount:n}=s,a=O(e,{...t&&{initialParams:t},fetchOnMount:n}),{loading:P,pagination:o,nextPage:d,data:T,error:E,isPlaceholderData:m}=a,l=useRef(P),f=useRef(o?.hasMore??false),h=useRef(d);l.current=P,f.current=o?.hasMore??false,h.current=d;let y=useRef(null);useEffect(()=>{if(!i||typeof window>"u"||!("IntersectionObserver"in window))return;let p=new IntersectionObserver(C=>{C[0].isIntersecting&&!l.current&&f.current&&h.current();},{threshold:u}),g=y.current;return g&&p.observe(g),()=>{g&&p.unobserve(g),p.disconnect();}},[i,u]);let b=useCallback(()=>{!l.current&&f.current&&h.current();},[]),v=P&&T!==null&&T.length>0&&(o?.page??1)>1;return {...a,data:T,error:E,isPlaceholderData:m??false,isFetchingMore:v,hasMore:o?.hasMore??false,loadMore:b,observerTarget:y}}function Y(e){let[s,t]=useState(()=>e.get());useEffect(()=>(t(e.get()),e.subscribe(a=>{t(a);})),[e]);let i=useCallback((...n)=>e.mutate(...n),[e]),u=useCallback(()=>e.reset(),[e]);return {loading:s.loading,data:s.data,error:s.error,isSuccess:s.isSuccess,mutate:i,reset:u}}export{O as useAsyncChunk,U as useChunk,_ as useChunkValue,N as useInfiniteAsyncChunk,Y as useMutation};