floppy-disk 3.0.0-beta.2 → 3.0.0-beta.4

package/README.md

@@ -1,3 +1,370 @@
-# Floppy Disk 💾
+# FloppyDisk.ts 💾
 
 A lightweight, simple, and powerful state management library.
+
+This library was highly-inspired by [Zustand](https://www.npmjs.com/package/zustand) and [TanStack-Query](https://tanstack.com/query), they're awesome state manager.
+FloppyDisk provides a very similar developer experience (DX), while introducing additional features and a smaller bundle size.
+
+Comparison: https://github.com/afiiif/floppy-disk/tree/beta/comparison
+
+Demo: https://afiiif.github.io/floppy-disk/
+
+**Installation:**
+
+```
+npm install floppy-disk
+```
+
+## Global Store
+
+Here's how to create and use a store:
+
+```tsx
+import { createStore } from 'floppy-disk/react';
+
+const useDigimon = createStore({
+  age: 3,
+  level: 'Rookie',
+});
+```
+
+You can use the store both inside and outside of React components.
+
+```tsx
+function MyDigimon() {
+  const { age } = useDigimon();
+  return <div>Digimon age: {age}</div>;
+  // This component will only re-render when `age` changes.
+  // Changes to `level` will NOT trigger a re-render.
+}
+
+function Control() {
+  return (
+    <>
+      <button onClick={() => {
+        // You can setState directly
+        useDigimon.setState(prev => ({ age: prev.age + 1 }));
+      }}>
+        Increase digimon's age
+      </button>
+
+      <button onClick={evolve}>Evolve</button>
+    </>
+  );
+}
+
+// You can create a custom actions
+const evolve = () => {
+  const { level } = useDigimon.getState();
+
+  const order = ['In-Training', 'Rookie', 'Champion', 'Ultimate'];
+  const nextLevel = order[order.indexOf(level) + 1];
+
+  if (!nextLevel) return console.warn('Already at ultimate level');
+
+  useDigimon.setState({ level: nextLevel });
+};
+```
+
+### Differences from Zustand
+
+If you're coming from Zustand, this should feel very familiar.\
+Key differences:
+
+1. **No Selectors Needed**\
+   You don't need selectors when using hooks.
+   FloppyDisk automatically tracks which parts of the state are used and optimizes re-renders accordingly.
+2. **Object-Only Store Initialization**\
+   In FloppyDisk, stores **must** be initialized with an object. Primitive values or function initializers are not allowed.
+
+Zustand examples:
+
+```tsx
+const useExample1 = create(123);
+
+const useExample2 = create(set => ({
+  value: 1,
+  inc: () => set(prev => ({ value: prev.value + 1 })),
+}));
+```
+
+FloppyDisk equivalents:
+
+```tsx
+const useExample1 = createStore({ value: 123 });
+
+// Unlike Zustand, defining actions inside the store is **discouraged** in FloppyDisk.
+// This improves tree-shakeability and keeps your store minimal.
+const useExample2 = createStore({ value: 1 });
+const inc = () => useExample2.setState(prev => ({ value: prev.value + 1 }));
+
+// However, it's still possible if you understand how closures work:
+const useExample2Alt = createStore({
+  value: 1,
+  inc: () => useExample2Alt.setState(prev => ({ value: prev.value + 1 })),
+});
+```
+
+## Async State (Query & Mutation)
+
+FloppyDisk also provides a powerful async state layer, inspired by [TanStack-Query](https://tanstack.com/query) but with a simpler API.
+
+It is agnostic to the type of async operation,
+it works with any Promise-based operation—whether it's a network request, local computation, storage access, or something else.
+
+Because of that, we intentionally avoid terms like "fetch" or "refetch".\
+Instead, we use:
+
+- **execute** → run the async operation (same as "fetch" in TanStack-Query)
+- **revalidate** → re-run while keeping existing data (same as "refetch" in TanStack-Query)
+
+### Query vs Mutation
+
+<details>
+
+<summary>Query → Read Operations</summary>
+
+Queries are designed for reading data.\
+They assume:
+
+- no side effects
+- no data mutation
+- safe to run multiple times
+
+Because of this, queries come with helpful defaults:
+
+- ✅ Retry mechanism (for transient failures)
+- ✅ Revalidation (keep data fresh automatically)
+- ✅ Caching & staleness control
+
+Use queries when:
+
+- fetching data
+- reading from storage
+- running idempotent async logic
+
+</details>
+
+<details>
+
+<summary>Mutation → Write Operations</summary>
+
+Mutations are designed for changing data.\
+Examples:
+
+- insert
+- update
+- delete
+- triggering side effects
+
+Because mutations are **not safe to repeat blindly**, FloppyDisk does **not** include:
+
+- ❌ automatic retry
+- ❌ automatic revalidation
+- ❌ implicit re-execution
+
+This is intentional.\
+Mutations should be explicit and controlled, not automatic.
+
+If you need retry mechanism, then you can always add it manually.
+
+</details>
+
+### Single Query
+
+Create a query using `createQuery`:
+
+```tsx
+import { createQuery } from 'floppy-disk/react';
+
+const myCoolQuery = createQuery(
+  myAsyncFn,
+  // { staleTime: 5000, revalidateOnFocus: false } <-- optional options
+);
+
+const useMyCoolQuery = myCoolQuery();
+
+// Use it inside your component:
+
+function MyComponent() {
+  const query = useMyCoolQuery();
+  if (query.state === 'INITIAL') return <div>Loading...</div>;
+  if (query.error) return <div>Error: {query.error.message}</div>;
+  return <div>{JSON.stringify(query.data)}</div>;
+}
+```
+
+### Query State: Two Independent Dimensions
+
+FloppyDisk tracks two things separately:
+
+- Is it running? → `isPending`\
+  (value: `boolean`)
+- What's the result? → `state`\
+  (value: `INITIAL | 'SUCCESS' | 'ERROR' | 'SUCCESS_BUT_REVALIDATION_ERROR'`)
+
+They are **independent**.
+
+### Automatic Re-render Optimization
+
+Just like the global store, FloppyDisk tracks usage automatically:
+
+```tsx
+const { data } = useMyQuery();
+// ^Only data changes will trigger a re-render
+
+const value = useMyQuery().data?.foo.bar.baz;
+// ^Only data.foo.bar.baz changes will trigger a re-render
+```
+
+### Keyed Query (Dynamic Params)
+
+You can create parameterized queries:
+
+```tsx
+import { getUserById, type GetUserByIdResponse } from '../utils';
+
+type MyQueryParam = { id: string };
+
+const userQuery = createQuery<GetUserByIdResponse, MyQueryParam>(
+  getUserById,
+  // { staleTime: 5000, revalidateOnFocus: false } <-- optional options
+);
+```
+
+Use it with parameters:
+
+```tsx
+function UserDetail({ id }) {
+  const useUserQuery = userQuery({ id: 1 });
+  const query = useUserQuery();
+  if (query.state === 'INITIAL') return <div>Loading...</div>;
+  if (query.error) return <div>Error: {query.error.message}</div>;
+  return <div>{JSON.stringify(query.data)}</div>;
+}
+```
+
+Each unique parameter creates its own cache entry.
+
+### Infinite Query
+
+FloppyDisk does **not provide** a dedicated "infinite query" API.\
+Instead, it embraces a simpler and more flexible approach:
+
+> Infinite queries are just **composition** + **recursion**.
+
+Why? Because async state is already powerful enough:
+
+- keyed queries handle parameters
+- components handle composition
+- recursion handles pagination
+
+No special abstraction needed.
+
+Here is the example on how to implement infinite query properly:
+
+```tsx
+type GetPostParams = {
+  cursor?: string; // For pagination
+};
+type GetPostsResponse = {
+  posts: Post[];
+  meta: { nextCursor: string };
+};
+
+const postsQuery = createQuery<GetPostsResponse, GetPostParams>(
+  getPosts,
+  {
+    staleTime: Infinity,
+    revalidateOnFocus: false,
+    revalidateOnReconnect: false,
+  },
+);
+
+function Main() {
+  return <Page cursor={undefined} />;
+}
+
+function Page({ cursor }: { cursor?: string }) {
+  const usePostsQuery = postsQuery({ cursor });
+  const { state, data, error } = usePostsQuery();
+
+  if (state === 'INITIAL') return <div>Loading...</div>;
+  if (error) return <div>Error</div>;
+
+  return (
+    <>
+      {data.posts.map(post => (
+        <PostCard key={post.id} post={post} />
+      ))}
+      {data.meta.nextCursor && (
+        <LoadMore nextCursor={data.meta.nextCursor} />
+      )}
+    </>
+  );
+}
+
+function LoadMore({ nextCursor }: { nextCursor?: string }) {
+  const [isNextPageRequested, setIsNextPageRequested] = useState(() => {
+    const stateOfNextPageQuery = postsQuery({ cursor: nextCursor }).getState();
+    return stateOfNextPageQuery.isPending || stateOfNextPageQuery.isSuccess;
+  });
+
+  if (isNextPageRequested) {
+    return <Page cursor={nextCursor} />;
+  }
+
+  return (
+    <ReachingBottomObserver
+      onReachBottom={() => setIsNextPageRequested(true)}
+    />
+  );
+}
+```
+
+When implementing infinite queries, it is **highly recommended to disable automatic revalidation**.
+
+Why?\
+In an infinite list, users may scroll through many pages ("_doom-scrolling_").\
+If revalidation is triggered:
+
+- All previously loaded pages may re-execute
+- Content at the top may change without the user noticing
+- Layout shifts can occur unexpectedly
+
+This leads to a **confusing and unstable user experience**.\
+Revalidating dozens of previously viewed pages rarely provides value to the user.
+
+## SSR Guidance
+
+FloppyDisk is designed primarily for **client-side [sync/async] state**.
+
+If your data is already fetched on the server (e.g. via SSR/ISR, Server Components, or Server Actions), then:
+
+> **You most likely don't need this library.**
+
+This is the same philosophy as TanStack Query. 💡
+
+In many cases, developers mix SSR/ISR with client-side state because they want:
+
+1. Data to be rendered into HTML on the server
+2. The ability to **revalidate it on the client**
+
+A common (but inefficient) approach is:
+
+- fetch on the server
+- hydrate it into a client-side cache
+- then revalidate using a query library
+
+While this works, it introduces additional complexity.
+
+Instead, we encourage a simpler approach:
+
+> If your data is fetched on the server, revalidate it using **your framework's built-in mechanism** (e.g. Next.js route revalidation).
+
+Because of this philosophy, FloppyDisk **does not support** hydrating server-fetched data into the client store.
+
+This keeps the mental model clean:
+
+- server data → handled by the framework
+- client async state → handled by FloppyDisk

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

@@ -44,6 +44,17 @@ export type MutationState<TData, TVariable, TError> = {
     error: TError;
     errorUpdatedAt: number;
 });
+export declare const INITIAL_STATE: {
+    state: string;
+    isPending: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    variable: undefined;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    error: undefined;
+    errorUpdatedAt: undefined;
+};
 /**
  * Configuration options for a mutation.
  *
@@ -52,15 +63,18 @@ export type MutationState<TData, TVariable, TError> = {
  */
 export type MutationOptions<TData, TVariable, TError = Error> = InitStoreOptions<MutationState<TData, TVariable, TError>> & {
     /**
-     * Called when the mutation succeeds.
+     * Called when the mutation succeeds.\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
      */
     onSuccess?: (data: TData, variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
     /**
-     * Called when the mutation fails.
+     * Called when the mutation fails.\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
      */
     onError?: (error: TError, variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
     /**
-     * Called after the mutation settles (either success or error).
+     * Called after the mutation settles (either success or error).\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
      */
     onSettled?: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
 };
@@ -78,8 +92,10 @@ export type MutationOptions<TData, TVariable, TError = Error> = InitStoreOptions
  * - Mutations are **not cached** and only track the latest execution.
  * - Designed for operations that change data (e.g. create, update, delete).
  * - No retry mechanism is provided by default.
- * - Each execution overwrites the previous state.
  * - 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.
  *
  * @example
  * const useCreateUser = createMutation(async (input) => {
@@ -111,9 +127,9 @@ export declare const createMutation: <TData, TVariable = undefined, TError = Err
      * - `{ error, variable }` on failure
      *
      * @remarks
-     * - If a mutation is already in progress, a warning is logged.
-     * - Concurrent executions are allowed but may lead to race conditions.
      * - 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;
@@ -128,8 +144,8 @@ export declare const createMutation: <TData, TVariable = undefined, TError = Err
      * Resets the mutation state back to its initial state.
      *
      * @remarks
-     * - Does not cancel any ongoing request.
-     * - If a request is still pending, its result may override the reset state.
+     * - Does not cancel any ongoing execution.
+     * - If an execution is still pending, its result may override the reset state.
      */
     reset: () => void;
 };

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

@@ -159,11 +159,13 @@ export type QueryOptions<TData, TVariable extends Record<string, any>, TError =
  */
 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 execute automatically on mount.
+     * Whether the query should be ravalidated automatically on mount.
+     *
+     * Revalidate means execute the queryFn **if stale/invalidated**.
      *
      * @default true
      */
-    enabled?: boolean;
+    revalidateOnMount?: boolean;
     /**
      * Whether to keep previous successful data while a new variable is loading.
      *

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.d.mts

@@ -3,4 +3,5 @@ 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';

package/esm/react.mjs

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useEffect, useState, useRef, useMemo } from 'react';
+import { useLayoutEffect, useEffect, useState, useRef, useMemo, useCallback } from 'react';
 import { isClient, initStore, getHash, noop } from 'floppy-disk/vanilla';
 
 const useIsomorphicLayoutEffect = isClient ? useLayoutEffect : useEffect;
@@ -128,7 +128,7 @@ const createQuery = (queryFn, options = {}) => {
     onSettled = noop,
     shouldRetry: shouldRetryFn = (_, s) => s.retryCount === 0 ? [true, 1500] : [false]
   } = options;
-  const initialState = INITIAL_STATE$1;
+  const initialState = { ...INITIAL_STATE$1 };
   const stores = /* @__PURE__ */ new Map();
   const configureStoreEvents = () => ({
     ...options,
@@ -367,7 +367,7 @@ const createQuery = (queryFn, options = {}) => {
       internals.set(store, configureInternals(store, variable, variableHash));
     }
     const useStore = (options2 = {}) => {
-      const { enabled = true, keepPreviousData } = options2;
+      const { revalidateOnMount = true, keepPreviousData } = options2;
       const storeState = store.getState();
       const prevState = useRef({});
       let storeStateToBeUsed = storeState;
@@ -380,7 +380,7 @@ const createQuery = (queryFn, options = {}) => {
         storeStateToBeUsed = { ...storeState, ...prevState.current };
       }
       const [trackedState, usedPathsRef] = useStoreStateProxy(
-        enabled && storeState.state === "INITIAL" ? (
+        revalidateOnMount && storeState.state === "INITIAL" ? (
           // Optimize rendering on initial state
           // Do { isPending: true } → result
           // instead of { isPending: false } → { isPending: true } → result
@@ -404,8 +404,8 @@ const createQuery = (queryFn, options = {}) => {
         });
       }, [store]);
       useIsomorphicLayoutEffect(() => {
-        if (enabled !== false) revalidate(store, variable, false);
-      }, [store, enabled]);
+        if (revalidateOnMount !== false) revalidate(store, variable, false);
+      }, [store, revalidateOnMount]);
       if (keepPreviousData) {
         !!trackedState.error;
       }
@@ -479,19 +479,26 @@ const INITIAL_STATE = {
 };
 const createMutation = (mutationFn, options = {}) => {
   const { onSuccess = noop, onError, onSettled = noop } = options;
-  const initialState = INITIAL_STATE;
+  const initialState = { ...INITIAL_STATE };
+  let ongoingPromise;
+  const resolveFns = /* @__PURE__ */ new Set([]);
   const store = initStore(initialState, options);
   const useStore = () => useStoreState(store.getState(), store.subscribe);
   const execute = (variable) => {
+    let currentResolveFn;
     const stateBeforeExecute = store.getState();
     if (stateBeforeExecute.isPending) {
       console.warn(
-        "Mutation executed while a previous execution is still pending. This may cause race conditions or unexpected state updates."
+        "A mutation was executed while a previous execution is still pending. The previous execution will be ignored (latest execution wins)."
       );
     }
     store.setState({ isPending: true });
-    return new Promise((resolve) => {
+    const promise = new Promise((resolve) => {
+      currentResolveFn = resolve;
       mutationFn(variable, stateBeforeExecute).then((data) => {
+        if (promise !== ongoingPromise) {
+          return resolve({ data, variable });
+        }
         store.setState({
           state: "SUCCESS",
           isPending: false,
@@ -504,8 +511,12 @@ const createMutation = (mutationFn, options = {}) => {
           errorUpdatedAt: void 0
         });
         resolve({ data, variable });
+        resolveFns.clear();
         onSuccess(data, variable, stateBeforeExecute);
       }).catch((error) => {
+        if (promise !== ongoingPromise) {
+          return resolve({ error, variable });
+        }
         store.setState({
           state: "ERROR",
           isPending: false,
@@ -518,12 +529,19 @@ const createMutation = (mutationFn, options = {}) => {
           errorUpdatedAt: Date.now()
         });
         resolve({ error, variable });
+        resolveFns.clear();
         if (onError) onError(error, variable, stateBeforeExecute);
         else console.error(store.getState());
       }).finally(() => {
+        if (promise !== ongoingPromise) return;
         onSettled(variable, stateBeforeExecute);
+        ongoingPromise = void 0;
       });
     });
+    if (ongoingPromise) resolveFns.forEach((resolveFn) => resolveFn(promise));
+    resolveFns.add(currentResolveFn);
+    ongoingPromise = promise;
+    return promise;
   };
   return Object.assign(useStore, {
     subscribe: store.subscribe,
@@ -550,17 +568,17 @@ const createMutation = (mutationFn, options = {}) => {
      * - `{ error, variable }` on failure
      *
      * @remarks
-     * - If a mutation is already in progress, a warning is logged.
-     * - Concurrent executions are allowed but may lead to race conditions.
      * - 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,
     /**
      * Resets the mutation state back to its initial state.
      *
      * @remarks
-     * - Does not cancel any ongoing request.
-     * - If a request is still pending, its result may override the reset state.
+     * - Does not cancel any ongoing execution.
+     * - If an execution is still pending, its result may override the reset state.
      */
     reset: () => {
       if (store.getState().isPending) {
@@ -573,4 +591,107 @@ const createMutation = (mutationFn, options = {}) => {
   });
 };
 
-export { createMutation, createQuery, createStore, createStores, useIsomorphicLayoutEffect, useStoreState };
+const useMutation = (mutationFn, options = {}) => {
+  const { onSuccess = noop, onError, onSettled = noop } = options;
+  const callbackRef = useRef({ onSuccess, onError, onSettled });
+  callbackRef.current.onSuccess = onSuccess;
+  callbackRef.current.onError = onError;
+  callbackRef.current.onSettled = onSettled;
+  const stateRef = useRef({ ...INITIAL_STATE });
+  const [, reRender] = useState({});
+  const refs = useRef({
+    mutationFn,
+    ongoingPromise: void 0,
+    resolveFns: /* @__PURE__ */ new Set()
+  });
+  refs.current.mutationFn = mutationFn;
+  const execute = useCallback((variable) => {
+    let currentResolveFn;
+    const stateBeforeExecute = stateRef.current;
+    if (stateBeforeExecute.isPending) {
+      console.warn(
+        "A mutation was executed while a previous execution is still pending. The previous execution will be ignored (latest execution wins)."
+      );
+    }
+    stateRef.current.isPending = true;
+    reRender({});
+    const promise = new Promise(
+      (resolve) => {
+        currentResolveFn = resolve;
+        refs.current.mutationFn(variable, stateBeforeExecute).then((data) => {
+          if (promise !== refs.current.ongoingPromise) {
+            return resolve({ data, variable });
+          }
+          stateRef.current = {
+            state: "SUCCESS",
+            isPending: false,
+            isSuccess: true,
+            isError: false,
+            variable,
+            data,
+            dataUpdatedAt: Date.now(),
+            error: void 0,
+            errorUpdatedAt: void 0
+          };
+          reRender({});
+          resolve({ data, variable });
+          refs.current.resolveFns.clear();
+          callbackRef.current.onSuccess(data, variable, stateBeforeExecute);
+        }).catch((error) => {
+          if (promise !== refs.current.ongoingPromise) {
+            return resolve({ error, variable });
+          }
+          stateRef.current = {
+            state: "ERROR",
+            isPending: false,
+            isSuccess: false,
+            isError: true,
+            variable,
+            data: void 0,
+            dataUpdatedAt: void 0,
+            error,
+            errorUpdatedAt: Date.now()
+          };
+          reRender({});
+          resolve({ error, variable });
+          refs.current.resolveFns.clear();
+          if (callbackRef.current.onError) {
+            callbackRef.current.onError(error, variable, stateBeforeExecute);
+          } else {
+            console.error(stateRef.current);
+          }
+        }).finally(() => {
+          if (promise !== refs.current.ongoingPromise) return;
+          callbackRef.current.onSettled(variable, stateBeforeExecute);
+          refs.current.ongoingPromise = void 0;
+        });
+      }
+    );
+    if (refs.current.ongoingPromise) {
+      refs.current.resolveFns.forEach((resolveFn) => resolveFn(promise));
+    }
+    refs.current.resolveFns.add(currentResolveFn);
+    refs.current.ongoingPromise = promise;
+    return promise;
+  }, []);
+  const reset = useCallback(() => {
+    if (stateRef.current.isPending) {
+      console.warn(
+        "Mutation state was reset while a request is still pending. The request will continue, but its result may override the reset state."
+      );
+    }
+    stateRef.current = { ...INITIAL_STATE };
+    reRender({});
+  }, []);
+  const r = [
+    stateRef.current,
+    {
+      execute,
+      reset,
+      getLatestState: () => stateRef.current
+    }
+  ];
+  return r;
+};
+
+export { createMutation, createQuery, createStore, createStores, useIsomorphicLayoutEffect, useMutation, useStoreState };

package/package.json

@@ -2,7 +2,7 @@
   "name": "floppy-disk",
   "description": "Lightweight, simple, and powerful state management library",
   "private": false,
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.4",
   "publishConfig": {
     "tag": "beta"
   },

package/react/create-mutation.d.ts

@@ -44,6 +44,17 @@ export type MutationState<TData, TVariable, TError> = {
     error: TError;
     errorUpdatedAt: number;
 });
+export declare const INITIAL_STATE: {
+    state: string;
+    isPending: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    variable: undefined;
+    data: undefined;
+    dataUpdatedAt: undefined;
+    error: undefined;
+    errorUpdatedAt: undefined;
+};
 /**
  * Configuration options for a mutation.
  *
@@ -52,15 +63,18 @@ export type MutationState<TData, TVariable, TError> = {
  */
 export type MutationOptions<TData, TVariable, TError = Error> = InitStoreOptions<MutationState<TData, TVariable, TError>> & {
     /**
-     * Called when the mutation succeeds.
+     * Called when the mutation succeeds.\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
      */
     onSuccess?: (data: TData, variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
     /**
-     * Called when the mutation fails.
+     * Called when the mutation fails.\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
      */
     onError?: (error: TError, variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
     /**
-     * Called after the mutation settles (either success or error).
+     * Called after the mutation settles (either success or error).\
+     * If multiple concurrent executions happened, only the latest execution triggers this callback.
      */
     onSettled?: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable, TError>) => void;
 };
@@ -78,8 +92,10 @@ export type MutationOptions<TData, TVariable, TError = Error> = InitStoreOptions
  * - Mutations are **not cached** and only track the latest execution.
  * - Designed for operations that change data (e.g. create, update, delete).
  * - No retry mechanism is provided by default.
- * - Each execution overwrites the previous state.
  * - 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.
  *
  * @example
  * const useCreateUser = createMutation(async (input) => {
@@ -111,9 +127,9 @@ export declare const createMutation: <TData, TVariable = undefined, TError = Err
      * - `{ error, variable }` on failure
      *
      * @remarks
-     * - If a mutation is already in progress, a warning is logged.
-     * - Concurrent executions are allowed but may lead to race conditions.
      * - 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;
@@ -128,8 +144,8 @@ export declare const createMutation: <TData, TVariable = undefined, TError = Err
      * Resets the mutation state back to its initial state.
      *
      * @remarks
-     * - Does not cancel any ongoing request.
-     * - If a request is still pending, its result may override the reset state.
+     * - Does not cancel any ongoing execution.
+     * - If an execution is still pending, its result may override the reset state.
      */
     reset: () => void;
 };

package/react/create-query.d.ts

@@ -159,11 +159,13 @@ export type QueryOptions<TData, TVariable extends Record<string, any>, TError =
  */
 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 execute automatically on mount.
+     * Whether the query should be ravalidated automatically on mount.
+     *
+     * Revalidate means execute the queryFn **if stale/invalidated**.
      *
      * @default true
      */
-    enabled?: boolean;
+    revalidateOnMount?: boolean;
     /**
      * Whether to keep previous successful data while a new variable is loading.
      *

package/react/use-mutation.d.ts

@@ -0,0 +1,82 @@
+import { type MutationOptions, type MutationState } from './create-mutation';
+/**
+ * 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/react.d.ts

@@ -3,4 +3,5 @@ export { useStoreState } from './react/use-store';
 export * from './react/create-store';
 export * from './react/create-stores';
 export * from './react/create-query';
-export * from './react/create-mutation';
+export { createMutation, type MutationOptions, type MutationState, } from './react/create-mutation';
+export * from './react/use-mutation';

package/react.js

@@ -130,7 +130,7 @@ const createQuery = (queryFn, options = {}) => {
     onSettled = vanilla.noop,
     shouldRetry: shouldRetryFn = (_, s) => s.retryCount === 0 ? [true, 1500] : [false]
   } = options;
-  const initialState = INITIAL_STATE$1;
+  const initialState = { ...INITIAL_STATE$1 };
   const stores = /* @__PURE__ */ new Map();
   const configureStoreEvents = () => ({
     ...options,
@@ -369,7 +369,7 @@ const createQuery = (queryFn, options = {}) => {
       internals.set(store, configureInternals(store, variable, variableHash));
     }
     const useStore = (options2 = {}) => {
-      const { enabled = true, keepPreviousData } = options2;
+      const { revalidateOnMount = true, keepPreviousData } = options2;
       const storeState = store.getState();
       const prevState = react.useRef({});
       let storeStateToBeUsed = storeState;
@@ -382,7 +382,7 @@ const createQuery = (queryFn, options = {}) => {
         storeStateToBeUsed = { ...storeState, ...prevState.current };
       }
       const [trackedState, usedPathsRef] = useStoreStateProxy(
-        enabled && storeState.state === "INITIAL" ? (
+        revalidateOnMount && storeState.state === "INITIAL" ? (
           // Optimize rendering on initial state
           // Do { isPending: true } → result
           // instead of { isPending: false } → { isPending: true } → result
@@ -406,8 +406,8 @@ const createQuery = (queryFn, options = {}) => {
         });
       }, [store]);
       useIsomorphicLayoutEffect(() => {
-        if (enabled !== false) revalidate(store, variable, false);
-      }, [store, enabled]);
+        if (revalidateOnMount !== false) revalidate(store, variable, false);
+      }, [store, revalidateOnMount]);
       if (keepPreviousData) {
         !!trackedState.error;
       }
@@ -481,19 +481,26 @@ const INITIAL_STATE = {
 };
 const createMutation = (mutationFn, options = {}) => {
   const { onSuccess = vanilla.noop, onError, onSettled = vanilla.noop } = options;
-  const initialState = INITIAL_STATE;
+  const initialState = { ...INITIAL_STATE };
+  let ongoingPromise;
+  const resolveFns = /* @__PURE__ */ new Set([]);
   const store = vanilla.initStore(initialState, options);
   const useStore = () => useStoreState(store.getState(), store.subscribe);
   const execute = (variable) => {
+    let currentResolveFn;
     const stateBeforeExecute = store.getState();
     if (stateBeforeExecute.isPending) {
       console.warn(
-        "Mutation executed while a previous execution is still pending. This may cause race conditions or unexpected state updates."
+        "A mutation was executed while a previous execution is still pending. The previous execution will be ignored (latest execution wins)."
       );
     }
     store.setState({ isPending: true });
-    return new Promise((resolve) => {
+    const promise = new Promise((resolve) => {
+      currentResolveFn = resolve;
       mutationFn(variable, stateBeforeExecute).then((data) => {
+        if (promise !== ongoingPromise) {
+          return resolve({ data, variable });
+        }
         store.setState({
           state: "SUCCESS",
           isPending: false,
@@ -506,8 +513,12 @@ const createMutation = (mutationFn, options = {}) => {
           errorUpdatedAt: void 0
         });
         resolve({ data, variable });
+        resolveFns.clear();
         onSuccess(data, variable, stateBeforeExecute);
       }).catch((error) => {
+        if (promise !== ongoingPromise) {
+          return resolve({ error, variable });
+        }
         store.setState({
           state: "ERROR",
           isPending: false,
@@ -520,12 +531,19 @@ const createMutation = (mutationFn, options = {}) => {
           errorUpdatedAt: Date.now()
         });
         resolve({ error, variable });
+        resolveFns.clear();
         if (onError) onError(error, variable, stateBeforeExecute);
         else console.error(store.getState());
       }).finally(() => {
+        if (promise !== ongoingPromise) return;
         onSettled(variable, stateBeforeExecute);
+        ongoingPromise = void 0;
       });
     });
+    if (ongoingPromise) resolveFns.forEach((resolveFn) => resolveFn(promise));
+    resolveFns.add(currentResolveFn);
+    ongoingPromise = promise;
+    return promise;
   };
   return Object.assign(useStore, {
     subscribe: store.subscribe,
@@ -552,17 +570,17 @@ const createMutation = (mutationFn, options = {}) => {
      * - `{ error, variable }` on failure
      *
      * @remarks
-     * - If a mutation is already in progress, a warning is logged.
-     * - Concurrent executions are allowed but may lead to race conditions.
      * - 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,
     /**
      * Resets the mutation state back to its initial state.
      *
      * @remarks
-     * - Does not cancel any ongoing request.
-     * - If a request is still pending, its result may override the reset state.
+     * - Does not cancel any ongoing execution.
+     * - If an execution is still pending, its result may override the reset state.
      */
     reset: () => {
       if (store.getState().isPending) {
@@ -575,9 +593,113 @@ const createMutation = (mutationFn, options = {}) => {
   });
 };
 
+const useMutation = (mutationFn, options = {}) => {
+  const { onSuccess = vanilla.noop, onError, onSettled = vanilla.noop } = options;
+  const callbackRef = react.useRef({ onSuccess, onError, onSettled });
+  callbackRef.current.onSuccess = onSuccess;
+  callbackRef.current.onError = onError;
+  callbackRef.current.onSettled = onSettled;
+  const stateRef = react.useRef({ ...INITIAL_STATE });
+  const [, reRender] = react.useState({});
+  const refs = react.useRef({
+    mutationFn,
+    ongoingPromise: void 0,
+    resolveFns: /* @__PURE__ */ new Set()
+  });
+  refs.current.mutationFn = mutationFn;
+  const execute = react.useCallback((variable) => {
+    let currentResolveFn;
+    const stateBeforeExecute = stateRef.current;
+    if (stateBeforeExecute.isPending) {
+      console.warn(
+        "A mutation was executed while a previous execution is still pending. The previous execution will be ignored (latest execution wins)."
+      );
+    }
+    stateRef.current.isPending = true;
+    reRender({});
+    const promise = new Promise(
+      (resolve) => {
+        currentResolveFn = resolve;
+        refs.current.mutationFn(variable, stateBeforeExecute).then((data) => {
+          if (promise !== refs.current.ongoingPromise) {
+            return resolve({ data, variable });
+          }
+          stateRef.current = {
+            state: "SUCCESS",
+            isPending: false,
+            isSuccess: true,
+            isError: false,
+            variable,
+            data,
+            dataUpdatedAt: Date.now(),
+            error: void 0,
+            errorUpdatedAt: void 0
+          };
+          reRender({});
+          resolve({ data, variable });
+          refs.current.resolveFns.clear();
+          callbackRef.current.onSuccess(data, variable, stateBeforeExecute);
+        }).catch((error) => {
+          if (promise !== refs.current.ongoingPromise) {
+            return resolve({ error, variable });
+          }
+          stateRef.current = {
+            state: "ERROR",
+            isPending: false,
+            isSuccess: false,
+            isError: true,
+            variable,
+            data: void 0,
+            dataUpdatedAt: void 0,
+            error,
+            errorUpdatedAt: Date.now()
+          };
+          reRender({});
+          resolve({ error, variable });
+          refs.current.resolveFns.clear();
+          if (callbackRef.current.onError) {
+            callbackRef.current.onError(error, variable, stateBeforeExecute);
+          } else {
+            console.error(stateRef.current);
+          }
+        }).finally(() => {
+          if (promise !== refs.current.ongoingPromise) return;
+          callbackRef.current.onSettled(variable, stateBeforeExecute);
+          refs.current.ongoingPromise = void 0;
+        });
+      }
+    );
+    if (refs.current.ongoingPromise) {
+      refs.current.resolveFns.forEach((resolveFn) => resolveFn(promise));
+    }
+    refs.current.resolveFns.add(currentResolveFn);
+    refs.current.ongoingPromise = promise;
+    return promise;
+  }, []);
+  const reset = react.useCallback(() => {
+    if (stateRef.current.isPending) {
+      console.warn(
+        "Mutation state was reset while a request is still pending. The request will continue, but its result may override the reset state."
+      );
+    }
+    stateRef.current = { ...INITIAL_STATE };
+    reRender({});
+  }, []);
+  const r = [
+    stateRef.current,
+    {
+      execute,
+      reset,
+      getLatestState: () => stateRef.current
+    }
+  ];
+  return r;
+};
+
 exports.createMutation = createMutation;
 exports.createQuery = createQuery;
 exports.createStore = createStore;
 exports.createStores = createStores;
 exports.useIsomorphicLayoutEffect = useIsomorphicLayoutEffect;
+exports.useMutation = useMutation;
 exports.useStoreState = useStoreState;