floppy-disk 3.0.0-beta.1 → 3.0.0-beta.3

package/esm/react/create-query.d.mts

@@ -19,7 +19,7 @@ import { type InitStoreOptions, type SetState } from 'floppy-disk/vanilla';
  * @remarks
  * - Data and error are mutually exclusive except in `SUCCESS_BUT_REVALIDATION_ERROR`.
  */
-export type QueryState<TData> = {
+export type QueryState<TData, TError> = {
     isPending: boolean;
     isRevalidating: boolean;
     isRetrying: boolean;
@@ -46,7 +46,7 @@ export type QueryState<TData> = {
     isError: true;
     data: undefined;
     dataUpdatedAt: undefined;
-    error: any;
+    error: TError;
     errorUpdatedAt: number;
 } | {
     state: 'SUCCESS_BUT_REVALIDATION_ERROR';
@@ -54,7 +54,7 @@ export type QueryState<TData> = {
     isError: false;
     data: TData;
     dataUpdatedAt: number;
-    error: any;
+    error: TError;
     errorUpdatedAt: number;
 });
 /**
@@ -63,13 +63,13 @@ export type QueryState<TData> = {
  * @remarks
  * Controls caching, retry behavior, lifecycle, and side effects of an async operation.
  */
-export type QueryOptions<TData, TVariable extends Record<string, any>> = InitStoreOptions<QueryState<TData>> & {
+export type QueryOptions<TData, TVariable extends Record<string, any>, TError = Error> = InitStoreOptions<QueryState<TData, TError>> & {
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
-     * While fresh, revalidation will be skipped.
+     * While fresh, revalidation will be skipped unless explicitly invalidated.
      *
-     * @default 2500 ms (2.5 minutes)
+     * @default 2500 ms (2.5 seconds)
      */
     staleTime?: number;
     /**
@@ -95,15 +95,15 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
     /**
      * Called when the query succeeds.
      */
-    onSuccess?: (data: TData, variable: TVariable, stateBeforeExecute: QueryState<TData>) => void;
+    onSuccess?: (data: TData, variable: TVariable, stateBeforeExecute: QueryState<TData, TError>) => void;
     /**
      * Called when the query fails and will not retry.
      */
-    onError?: (error: any, variable: TVariable, stateBeforeExecute: QueryState<TData>) => void;
+    onError?: (error: TError, variable: TVariable, stateBeforeExecute: QueryState<TData, TError>) => void;
     /**
      * Called after the query settles (success or final failure).
      */
-    onSettled?: (variable: TVariable, stateBeforeExecute: QueryState<TData>) => void;
+    onSettled?: (variable: TVariable, stateBeforeExecute: QueryState<TData, TError>) => void;
     /**
      * Determines whether a failed query should retry.
      *
@@ -120,7 +120,7 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
      *   return [false];
      * }
      */
-    shouldRetry?: (error: any, currentState: QueryState<TData>) => [true, number] | [false];
+    shouldRetry?: (error: TError, currentState: QueryState<TData, TError>) => [true, number] | [false];
 };
 /**
  * Creates a query factory for managing cached async operations.
@@ -131,16 +131,20 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
  * @returns A function to retrieve or create a query instance by variable
  *
  * @remarks
- * - Queries are cached by a deterministic key derived from `variable`.
+ * - Queries are **keyed by variable** (via deterministic hashing).
  * - Each unique variable maps to its own store instance.
- * - Queries support:
- *   - Caching with `staleTime`
- *   - Explicit invalidation independent of freshness
- *   - Automatic garbage collection (`gcTime`)
- *   - Retry logic via `shouldRetry`
- *   - Background revalidation (focus / reconnect)
- * - Execution is deduplicated: multiple calls share the same in-flight promise.
- * - Ongoing executions can be optionally overwritten.
+ *
+ * Core features:
+ * - Caching via `staleTime`
+ * - Explicit invalidation (independent of freshness)
+ * - Retry logic via `shouldRetry`
+ * - Background revalidation (focus / reconnect)
+ * - Garbage collection via `gcTime`
+ *
+ * Execution behavior:
+ * - By default, executions **overwrite ongoing executions**
+ * - Set `overwriteOngoingExecution: false` to enable deduplication
+ * - Internal revalidation (focus/reconnect) uses deduplication by default
  *
  * @example
  * const userQuery = createQuery<UserDetail, { id: string }>(async ({ id }) => {
@@ -153,39 +157,38 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
  *   // ...
  * }
  */
-export declare const createQuery: <TData, TVariable extends Record<string, any> = never>(queryFn: (variable: TVariable, currentState: QueryState<TData>) => Promise<TData>, options?: QueryOptions<TData, TVariable>) => ((variable?: TVariable) => {
-    <TStateSlice = QueryState<TData>>(options?: {
-        /**
-         * Whether the query should execute automatically on mount.
-         *
-         * @default true
-         */
-        enabled?: boolean;
-        /**
-         * Whether to keep previous successful data while a new variable is loading.
-         *
-         * @remarks
-         * - Only applies when the query is in the `INITIAL` state (no data & no error).
-         * - Intended for variable changes:
-         *   when switching from one variable to another, the previous data is temporarily shown
-         *   while the new execution is in progress.
-         * - Once the new execution resolves (success or error), the previous data is no longer used.
-         * - Prevents UI flicker (e.g. empty/loading state) during transitions.
-         *
-         * @example
-         * // Switching from userId=1 → userId=2
-         * // While loading userId=2, still show userId=1 data
-         * useQuery({ id: userId }, { keepPreviousData: true });
-         */ keepPreviousData?: boolean;
-    }, selector?: (state: QueryState<TData>) => TStateSlice): TStateSlice;
-    <TStateSlice = QueryState<TData>>(selector?: (state: QueryState<TData>) => TStateSlice): TStateSlice;
-} & {
+export declare const createQuery: <TData, TVariable extends Record<string, any> = never, TError = Error>(queryFn: (variable: TVariable, currentState: QueryState<TData, TError>) => Promise<TData>, options?: QueryOptions<TData, TVariable, TError>) => ((variable?: TVariable) => ((options?: {
+    /**
+     * Whether the query should be ravalidated automatically on mount.
+     *
+     * Revalidate means execute the queryFn **if stale/invalidated**.
+     *
+     * @default true
+     */
+    revalidateOnMount?: boolean;
+    /**
+     * Whether to keep previous successful data while a new variable is loading.
+     *
+     * @remarks
+     * - Only applies when the query is in the `INITIAL` state (no data & no error).
+     * - Intended for variable changes:
+     *   when switching from one variable to another, the previous data is temporarily shown
+     *   while the new execution is in progress.
+     * - Once the new execution resolves (success or error), the previous data is no longer used.
+     * - Prevents UI flicker (e.g. empty/loading state) during transitions.
+     *
+     * @example
+     * // Switching from userId=1 → userId=2
+     * // While loading userId=2, still show userId=1 data
+     * useQuery({ id: userId }, { keepPreviousData: true });
+     */ keepPreviousData?: boolean;
+}) => QueryState<TData, TError>) & {
     metadata: {
         isInvalidated?: boolean;
-        promise?: Promise<QueryState<TData>> | undefined;
-        promiseResolver?: ((value: QueryState<TData> | PromiseLike<QueryState<TData>>) => void) | undefined;
+        promise?: Promise<QueryState<TData, TError>> | undefined;
+        promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
         retryTimeoutId?: number;
-        retryResolver?: ((value: QueryState<TData> | PromiseLike<QueryState<TData>>) => void) | undefined;
+        retryResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
         garbageCollectionTimeoutId?: number;
         rollbackData?: TData | undefined;
     };
@@ -211,7 +214,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * @returns A promise resolving to the latest query state
      *
      * @remarks
-     * - By default, each call starts a new execution even if one is already in progress.
+     * - By default, each call **starts a new execution** even if one is already in progress.
      * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
      * - Handles:
      *   - Pending state
@@ -221,7 +224,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      */
     execute: (options?: {
         overwriteOngoingExecution?: boolean;
-    }) => Promise<QueryState<TData>>;
+    }) => Promise<QueryState<TData, TError>>;
     /**
      * Re-executes the query if needed based on freshness or invalidation.
      *
@@ -237,7 +240,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      */
     revalidate: (options?: {
         overwriteOngoingExecution?: boolean;
-    }) => Promise<QueryState<TData>>;
+    }) => Promise<QueryState<TData, TError>>;
     /**
      * Marks the query as invalidated and optionally triggers re-execution.
      *
@@ -289,7 +292,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * const { rollback, revalidate } = query.optimisticUpdate(newData);
      */
     optimisticUpdate: (data: TData) => {
-        revalidate: () => Promise<QueryState<TData>>;
+        revalidate: () => Promise<QueryState<TData, TError>>;
         rollback: () => TData;
     };
     /**
@@ -301,10 +304,10 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * - Should be used if an optimistic update fails.
      */
     rollbackOptimisticUpdate: () => TData;
-    subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<QueryState<TData>>) => () => void;
-    getSubscribers: () => Set<import("../vanilla.d.mts").Subscriber<QueryState<TData>>>;
-    getState: () => QueryState<TData>;
-    setState: (value: SetState<QueryState<TData>>) => void;
+    subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<QueryState<TData, TError>>) => () => void;
+    getSubscribers: () => Set<import("../vanilla.d.mts").Subscriber<QueryState<TData, TError>>>;
+    getState: () => QueryState<TData, TError>;
+    setState: (value: SetState<QueryState<TData, TError>>) => void;
 }) & {
     /**
      * Executes all query instances.

package/esm/react/create-store.d.mts

@@ -12,14 +12,17 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  * @remarks
  * - Combines the vanilla store with React integration.
  * - The returned function can be used directly as a hook.
+ *   - The hook uses Proxy-based tracking to automatically detect which state fields are used.
+ *   - Components will only re-render when the accessed values change.
  *
  * @example
- * const useCounter = createStore({ count: 0 });
+ * const useMyStore = createStore({ foo: 1, bar: 2 });
  *
  * function Component() {
- *   const count = useCounter((s) => s.count);
+ *   const state = useMyStore();
+ *   return <div>{state.foo}</div>;
  * }
  *
- * useCounter.setState({ count: 1 });
+ * useMyStore.setState({ foo: 2 }); // only components using foo will re-render
  */
-export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (<TStateSlice = TState>(selector?: (state: TState) => TStateSlice) => TStateSlice) & import("../vanilla.d.mts").StoreApi<TState>;
+export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (() => TState) & import("../vanilla.d.mts").StoreApi<TState>;

package/esm/react/create-stores.d.mts

@@ -12,18 +12,25 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  * - Keys are deterministically hashed, ensuring stable identity.
  * - Stores are lazily created and cached.
  * - Each store has its own state, subscribers, and lifecycle.
+ * - Each returned store includes:
+ *   - React hook (with Proxy-based tracking)
+ *   - Store API methods
+ *   - `delete()` for manual cleanup
  * - Useful for scenarios like:
  *   - Query caches
  *   - Entity-based state
  *   - Dynamic instances
  *
  * @example
- * const getUserStore = createStores({ name: '' });
+ * const userStore = createStores<{ name: string }, { id: number }>({ name: '' });
  *
- * const userStore = getUserStore({ id: 1 });
- * const name = userStore((s) => s.name);
+ * function Component() {
+ *   const useUserStore = userStore({ id: 1 });
+ *   const state = useUserStore();
+ *   return <div>{state.name}</div>;
+ * }
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => (<TStateSlice = TState>(selector?: (state: TState) => TStateSlice) => TStateSlice) & {
+export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => (() => TState) & {
     delete: () => boolean;
     setState: (value: import("../vanilla.d.mts").SetState<TState>) => void;
     getState: () => TState;

package/esm/react/use-mutation.d.mts

@@ -0,0 +1,82 @@
+import { type MutationOptions, type MutationState } from './create-mutation.mjs';
+/**
+ * A hook for managing async mutation state.
+ *
+ * @param mutationFn - Async function that performs the mutation.
+ * Receives the input variable and the state snapshot before execution.
+ *
+ * @param options - Optional lifecycle callbacks:
+ * - `onSuccess(data, variable, stateBeforeExecute)`
+ * - `onError(error, variable, stateBeforeExecute)`
+ * - `onSettled(variable, stateBeforeExecute)`
+ *
+ * @returns A tuple containing:
+ * - state: The current mutation state (render snapshot)
+ * - controls: An object with mutation actions and helpers
+ *
+ * @remarks
+ * - No retry mechanism is provided by default.
+ * - The mutation always resolves (never throws): the result contains either `data` or `error`.
+ * - If multiple executions triggered at the same time:
+ *   - Only the latest execution is allowed to update the state.
+ *   - Results from previous executions are ignored if a newer one exists.
+ */
+export declare const useMutation: <TData, TVariable = undefined, TError = Error>(
+/**
+ * Async function that performs the mutation.
+ *
+ * @remarks
+ * - Does NOT need to be memoized (e.g. `useCallback`).
+ * - The latest function reference is always used internally.
+ */
+mutationFn: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => Promise<TData>, 
+/**
+ * Optional lifecycle callbacks.
+ *
+ * @remarks
+ * - Callbacks do NOT need to be memoized.
+ * - The latest callbacks are always used internally.
+ */
+options?: MutationOptions<TData, TVariable, TError>) => [MutationState<TData, TVariable, TError>, {
+    /**
+     * Executes the mutation.
+     *
+     * @param variable - Input passed to the mutation function
+     *
+     * @returns A promise that always resolves with:
+     * - `{ data, variable }` on success
+     * - `{ error, variable }` on failure
+     *
+     * @remarks
+     * - The promise never rejects to simplify async handling.
+     * - If a mutation is already in progress, a warning is logged.
+     * - When a new execution starts, all previous pending executions will resolve with the result of the latest execution.
+     */
+    execute: TVariable extends undefined ? () => Promise<{
+        variable: undefined;
+        data?: TData;
+        error?: TError;
+    }> : (variable: TVariable) => Promise<{
+        variable: TVariable;
+        data?: TData;
+        error?: TError;
+    }>;
+    /**
+     * Resets the mutation state back to its initial state.
+     *
+     * @remarks
+     * - Does not cancel any ongoing execution.
+     * - If an execution is still pending, its result may override the reset state.
+     */
+    reset: () => void;
+    /**
+     * Returns the latest mutation state directly from the internal ref.
+     *
+     * @returns The most up-to-date mutation state.
+     *
+     * @remarks
+     * - Unlike the `state` returned by the hook, this value is not tied to React render cycles.
+     * - Use this inside async flows or event handlers to avoid stale reads.
+     */
+    getLatestState: () => MutationState<TData, TVariable, TError>;
+}];

package/esm/react/use-store.d.mts

@@ -1,18 +1,28 @@
 import { type StoreApi } from 'floppy-disk/vanilla';
-export declare const useStoreUpdateNotifier: <TState extends Record<string, any>, TStateSlice = TState>(store: StoreApi<TState>, selector: (state: TState) => TStateSlice) => void;
+type Path = Array<string | number | symbol>;
+export declare const getValueByPath: (obj: any, path: Path) => any;
+export declare const isPrefixPath: (candidatePrefix: Path, targetPath: Path) => boolean;
+export declare const compressPaths: (paths: Path[]) => Path[];
+export declare const useStoreStateProxy: <TState extends Record<string, any>>(storeState: TState) => readonly [TState, import("react").RefObject<Path[]>];
 /**
- * React hook for subscribing to a store with optional state selection.
+ * React hook for subscribing to a store using automatic dependency tracking.
  *
  * @param store - The store instance to subscribe to
- * @param selector - Optional selector to derive a slice of state
  *
- * @returns The selected state slice (or full state if no selector is provided)
+ * @returns A proxied version of the store state
  *
  * @remarks
- * - The selector does **not** need to be memoized.
- * - The hook internally keeps the latest selector reference to avoid re-subscription.
+ * - This hook uses a **Proxy-based tracking mechanism** to detect which parts of the state are accessed during render.
+ * - The component will only re-render when the **accessed values actually change**.
+ * - State must be treated as **immutable**:
+ *   - Updates must replace objects rather than mutate them
+ *   - Otherwise, changes may not be detected
+ * - No selector or memoization is needed.
  *
  * @example
- * const count = useStoreState(store, (s) => s.count);
+ * const state = useStoreState(store);
+ * return <div>{state.user.name}</div>;
+ * // Component will only re-render if `user.name` changes
  */
-export declare const useStoreState: <TState extends Record<string, any>, TStateSlice = TState>(store: StoreApi<TState>, selector?: (state: TState) => TStateSlice) => TStateSlice;
+export declare const useStoreState: <TState extends Record<string, any>>(storeState: TState, subscribe: StoreApi<TState>["subscribe"]) => TState;
+export {};

package/esm/react.d.mts

@@ -1,6 +1,7 @@
 export * from './react/use-isomorphic-layout-effect.mjs';
-export * from './react/use-store.mjs';
+export { useStoreState } from './react/use-store.mjs';
 export * from './react/create-store.mjs';
 export * from './react/create-stores.mjs';
 export * from './react/create-query.mjs';
-export * from './react/create-mutation.mjs';
+export { createMutation, type MutationOptions, type MutationState, } from './react/create-mutation.mjs';
+export * from './react/use-mutation.mjs';