floppy-disk 3.0.0-experimental.1 → 3.0.0

package/README.md

@@ -1,818 +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).
-Both are awesome state manager. That's why this Floppy Disk library behaves like them, but with small DX improvement, **more power**, and **less bundle size**.
+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.
 
-**Bundle Size Comparison:**
+Comparison: https://github.com/afiiif/floppy-disk/tree/beta/comparison
 
-```js
-import { create } from 'zustand'; // 3.3 kB (gzipped: 1.5 kB)
-import { createStore } from 'floppy-disk'; // 1.4 kB (gzipped: 750 B) 🎉
+Demo: https://afiiif.github.io/floppy-disk/
 
-import {
-  QueryClient,
-  QueryClientProvider,
-  useQuery,
-  useInfiniteQuery,
-  useMutation,
-} from '@tanstack/react-query'; // 31.7 kB kB (gzipped: 9.2 kB)
-import { createQuery, createMutation } from 'floppy-disk'; // 9.7 kB (gzipped: 3.3 kB) 🎉
-```
+**Installation:**
 
-- Using Zustand & React-Query: https://demo-zustand-react-query.vercel.app/  
-  👉 Total: **309.21 kB**
-- Using Floppy Disk: https://demo-floppy-disk.vercel.app/  
-  👉 Total: **272.63 kB** 🎉
-
-## Key Features
-
-- **Create Store**
-  - Get/set store inside/outside component
-  - Very simple way to customize the reactivity (a.k.a. state update subscription)
-  - Support middleware
-  - Set state interception
-  - Store event (`onSubscribe`, `onUnsubscribe`, etc.)
-  - Use store as local state manager
-- **Create Stores**
-  - Same as store, but controlled with a store key
-- **Create Query & Mutation**
-  - Backend agnostic (support GraphQL & any async function)
-  - TypeScript ready
-  - SSR/SSG support
-  - Custom reactivity (we choose when to re-render)
-  - **Create query**
-    - Dedupe multiple request
-    - Auto-fetch on mount or manual (lazy query)
-    - Enable/disable query
-    - Serve stale data while revalidating
-    - Retry on error (customizable)
-    - Optimistic update
-    - Invalidate query
-    - Reset query
-    - Query with param (query key)
-    - Paginated/infinite query
-    - Prefetch query
-    - Fetch from inside/outside component
-    - Get query state inside/outside component
-    - Suspense mode
-  - **Create mutation**
-    - Mutate from inside/outside component
-    - Get mutation state inside/outside component
-  - ... and [a lot more](https://floppy-disk.vercel.app/)
-
-<br>
-
----
-
-<p align="center">
-  View official documentation on <a href="https://floppy-disk.vercel.app/">floppy-disk.vercel.app</a>
-</p>
-
----
-
-<br>
-
-## Table of Contents
-
-- [Key Features](#key-features)
-- [Table of Contents](#table-of-contents)
-- [Store](#store)
-  - [Basic Concept](#basic-concept)
-  - [Advanced Concept](#advanced-concept)
-- [Stores](#stores)
-- [Query \& Mutation](#query--mutation)
-  - [Query State \& Network Fetching State](#query-state--network-fetching-state)
-  - [Inherited from createStores](#inherited-from-createstores)
-  - [Single Query](#single-query)
-  - [Single Query with Params](#single-query-with-params)
-  - [Paginated Query or Infinite Query](#paginated-query-or-infinite-query)
-  - [Mutation](#mutation)
-- [Important Notes](#important-notes)
-
-## Store
-
-### Basic Concept
-
-Create a store.
-
-```js
-import { createStore } from 'floppy-disk';
-
-const useCatStore = createStore(({ set }) => ({
-  age: 0,
-  isSleeping: false,
-  increaseAge: () => set((state) => ({ age: state.age + 1 })),
-  reset: () => set({ age: 0, isSleeping: false }),
-}));
 ```
-
-Use the hook anywhere, no providers are needed.
-
-```jsx
-function Cat() {
-  const { age } = useCatStore((state) => [state.age]);
-  return <div>Cat's age: {age}</div>;
-}
-
-function Control() {
-  const { increaseAge } = useCatStore((state) => [state.increaseAge]);
-  return <button onClick={increaseAge}>Increase cat's age</button>;
-}
+npm install floppy-disk
 ```
 
-> Example: [https://codesandbox.io/.../examples/react/basic](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/basic)
-
-Control the reactivity. The concept is same as useEffect dependency array.
-
-```jsx
-function YourComponent() {
-  const { age, isSleeping } = useCatStore();
-  // Will re-render every state change    ^
-  ...
-}
+## Global Store
 
-function YourComponent() {
-  const { age, isSleeping } = useCatStore((state) => [state.isSleeping]);
-  // Will only re-render when isSleeping is updated   ^
-  // Update on age won't cause re-render this component
-  ...
-}
+Here's how to create and use a store:
 
-function YourComponent() {
-  const { age, isSleeping } = useCatStore((state) => [state.age, state.isSleeping]);
-  // Will re-render when age or isSleeping is updated ^
-  ...
-}
+```tsx
+import { createStore } from 'floppy-disk/react';
 
-function YourComponent() {
-  const { age, isSleeping } = useCatStore((state) => [state.age > 3]);
-  // Will only re-render when (age>3) is updated
-  ...
-}
+const useDigimon = createStore({
+  age: 3,
+  level: 'Rookie',
+});
 ```
 
-> Example: [https://codesandbox.io/.../examples/react/custom-reactivity](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/custom-reactivity)
+You can use the store both inside and outside of React components.
 
-Reading/writing state and reacting to changes outside of 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.
+}
 
-```js
-const alertCatAge = () => {
-  alert(useCatStore.get().age);
-};
+function Control() {
+  return (
+    <>
+      <button onClick={() => {
+        // You can setState directly
+        useDigimon.setState(prev => ({ age: prev.age + 1 }));
+      }}>
+        Increase digimon's age
+      </button>
 
-const toggleIsSleeping = () => {
-  useCatStore.set((state) => ({ isSleeping: !state.isSleeping }));
-};
+      <button onClick={evolve}>Evolve</button>
+    </>
+  );
+}
 
-const unsub = useCatStore.subscribe(
-  // Action
-  (state) => {
-    console.log('The value of age is changed!', state.age);
-  },
-  // Reactivity dependency (just like useEffect dependency mentioned above)
-  (state) => [state.age],
-  // ^If not set, the action will be triggered on every state change
-);
-```
+// You can create a custom actions
+const evolve = () => {
+  const { level } = useDigimon.getState();
 
-### Advanced Concept
+  const order = ['In-Training', 'Rookie', 'Champion', 'Ultimate'];
+  const nextLevel = order[order.indexOf(level) + 1];
 
-Set the state **silently** (without broadcast the state change to **any subscribers**).
+  if (!nextLevel) return console.warn('Already at ultimate level');
 
-```jsx
-const decreaseAgeSilently = () => {
-  useCatStore.set((state) => ({ age: state.age }), true);
-  //                                               ^silent param
+  useDigimon.setState({ level: nextLevel });
 };
-//                👇 Will not re-render
-function Cat() {
-  const { age } = useCatStore((state) => [state.age]);
-  return <div>Cat's age: {age}</div>;
-}
 ```
 
-Store events & interception.
+### Differences from Zustand
 
-```js
-const useCatStore = createStore(
-  ({ set }) => ({
-    age: 0,
-    isSleeping: false,
-    increaseAge: () => set((state) => ({ age: state.age + 1 })),
-    reset: () => set({ age: 0, isSleeping: false }),
-  }),
-  {
-    onFirstSubscribe: (state) => {
-      console.log('onFirstSubscribe', state);
-    },
-    onSubscribe: (state) => {
-      console.log('onSubscribe', state);
-    },
-    onUnsubscribe: (state) => {
-      console.log('onUnsubscribe', state);
-    },
-    onLastUnsubscribe: (state) => {
-      console.log('onLastUnsubscribe', state);
-    },
-    intercept: (nextState, prevState) => {
-      if (nextState.age !== prevState.age) {
-        return { ...nextState, isSleeping: false };
-      }
-      return nextState;
-    },
-  },
-);
-```
+If you're coming from Zustand, this should feel very familiar.\
+Key differences:
 
-> Example:  
-> [https://codesandbox.io/.../examples/react/store-event](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/store-event)  
-> [https://codesandbox.io/.../examples/react/intercept](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/intercept)
-
-Let's go wild using IIFE.
-
-```js
-const useCatStore = createStore(
-  ({ set }) => ({
-    age: 0,
-    isSleeping: false,
-    increaseAge: () => set((state) => ({ age: state.age + 1 })),
-    reset: () => set({ age: 0, isSleeping: false }),
-  }),
-  (() => {
-    const validateCat = () => {
-      console.info('Window focus event triggered...');
-      const { age } = useCatStore.get();
-      if (age > 5) useCatStore.set({ age: 1 });
-    };
-    return {
-      onFirstSubscribe: () => window.addEventListener('focus', validateCat),
-      onLastUnsubscribe: () => window.removeEventListener('focus', validateCat),
-    };
-  })(),
-);
-```
+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.
 
-Prevent re-render using `Watch`.
+Zustand examples:
 
-```jsx
-function CatPage() {
-  const { age } = useCatStore((state) => [state.age]);
-  // If age changed, this component will re-render which will cause
-  // HeavyComponent1 & HeavyComponent2 to be re-rendered as well.
-  return (
-    <main>
-      <HeavyComponent1 />
-      <div>Cat's age: {age}</div>
-      <HeavyComponent2 />
-    </main>
-  );
-}
+```tsx
+const useExample1 = create(123);
 
-// Optimized
-function CatPageOptimized() {
-  return (
-    <main>
-      <HeavyComponent1 />
-      <useCatStore.Watch
-        selectDeps={(state) => [state.age]}
-        render={({ age }) => {
-          return <div>Cat's age: {age}</div>;
-        }}
-      />
-      <HeavyComponent2 />
-    </main>
-  );
-}
+const useExample2 = create(set => ({
+  value: 1,
+  inc: () => set(prev => ({ value: prev.value + 1 })),
+}));
 ```
 
-> Example: [https://codesandbox.io/.../examples/react/watch-component](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/watch-component)
+FloppyDisk equivalents:
 
-Want a local state instead of global state?  
-Or, want to set the initial state inside component?
+```tsx
+const useExample1 = createStore({ value: 123 });
 
-```jsx
-const [CatStoreProvider, useCatStoreContext] = withContext(() =>
-  createStore(({ set }) => ({
-    age: 0,
-    isSleeping: false,
-    increaseAge: () => set((state) => ({ age: state.age + 1 })),
-    reset: () => set({ age: 0, isSleeping: false }),
-  })),
-);
+// 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 }));
 
-function Parent() {
-  return (
-    <>
-      <CatStoreProvider>
-        <CatAge />
-        <CatIsSleeping />
-        <WillNotReRenderAsCatStateChanged />
-      </CatStoreProvider>
-
-      <CatStoreProvider>
-        <CatAge />
-        <CatIsSleeping />
-        <WillNotReRenderAsCatStateChanged />
-      </CatStoreProvider>
-
-      <CatStoreProvider onInitialize={(store) => store.set({ age: 99 })}>
-        <CatAge />
-        <CatIsSleeping />
-        <WillNotReRenderAsCatStateChanged />
-      </CatStoreProvider>
-    </>
-  );
-}
-
-function CatAge() {
-  const { age } = useCatStoreContext()((state) => [state.age]);
-  return <div>Age: {age}</div>;
-}
-function CatIsSleeping() {
-  const useCatStore = useCatStoreContext();
-  const { isSleeping } = useCatStore((state) => [state.isSleeping]);
-  return (
-    <>
-      <div>Is Sleeping: {String(isSleeping)}</div>
-      <button onClick={useCatStore.get().increaseAge}>Increase cat age</button>
-    </>
-  );
-}
+// However, it's still possible if you understand how closures work:
+const useExample2Alt = createStore({
+  value: 1,
+  inc: () => useExample2Alt.setState(prev => ({ value: prev.value + 1 })),
+});
 ```
 
-> Example: [https://codesandbox.io/.../examples/react/local-state](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/local-state)
+## Async State (Query & Mutation)
 
-Set default reactivity.
+FloppyDisk also provides a powerful async state layer, inspired by [TanStack-Query](https://tanstack.com/query) but with a simpler API.
 
-```jsx
-const useCatStore = createStore(
-  ({ set }) => ({
-    age: 0,
-    isSleeping: false,
-    increaseAge: () => set((state) => ({ age: state.age + 1 })),
-    reset: () => set({ age: 0, isSleeping: false }),
-  }),
-  {
-    defaultDeps: (state) => [state.age], // 👈
-  },
-);
+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.
 
-function Cat() {
-  const { age } = useCatStore();
-  //                          ^will only re-render when age changed
-  return <div>Cat's age: {age}</div>;
-}
-```
+Because of that, we intentionally avoid terms like "fetch" or "refetch".\
+Instead, we use:
 
-## Stores
+- **execute** → run the async operation (same as "fetch" in TanStack-Query)
+- **revalidate** → re-run while keeping existing data (same as "refetch" in TanStack-Query)
 
-The concept is same as [store](#store), but this can be used for multiple stores.
+### Query vs Mutation
 
-You need to specify the store key (an object) as identifier.
+<details>
 
-```js
-import { createStores } from 'floppy-disk';
+<summary>Query → Read Operations</summary>
 
-const useCatStores = createStores(
-  ({ set, get, key }) => ({
-    //         ^store key
-    age: 0,
-    isSleeping: false,
-    increaseAge: () => set((state) => ({ age: state.age + 1 })),
-    reset: () => set({ age: 0, isSleeping: false }),
-  }),
-  {
-    onBeforeChangeKey: (nextKey, prevKey) => {
-      console.log('Store key changed', nextKey, prevKey);
-    },
-    // ... same as createStore
-  },
-);
+Queries are designed for reading data.\
+They assume:
 
-function CatPage() {
-  const [catId, setCatId] = useState(1);
+- no side effects
+- no data mutation
+- safe to run multiple times
 
-  return (
-    <>
-      <div>Current cat id: {catId}</div>
-      <button onClick={() => setCatId((prev) => prev - 1)}>Prev cat</button>
-      <button onClick={() => setCatId((prev) => prev + 1)}>Next cat</button>
+Because of this, queries come with helpful defaults:
 
-      <Cat catId={catId} />
-      <Control catId={catId} />
-    </>
-  );
-}
+- ✅ Retry mechanism (for transient failures)
+- ✅ Revalidation (keep data fresh automatically)
+- ✅ Caching & staleness control
 
-function Cat({ catId }) {
-  const { age } = useCatStores({ catId }, (state) => [state.age]);
-  return <div>Cat's age: {age}</div>;
-}
-
-function Control({ catId }) {
-  const { increaseAge } = useCatStores({ catId }, (state) => [state.increaseAge]);
-  return <button onClick={increaseAge}>Increase cat's age</button>;
-}
-```
+Use queries when:
 
-> Example: [https://codesandbox.io/.../examples/react/stores](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/stores)
+- fetching data
+- reading from storage
+- running idempotent async logic
 
-<br><br>
+</details>
 
-<p align="center">
-  — ✨ 💾 ✨ —
-</p>
-<br>
+<details>
 
-## Query & Mutation
+<summary>Mutation → Write Operations</summary>
 
-With the power of `createStores` function and a bit creativity, we can easily create a hook just like `useQuery` and `useInfiniteQuery` in [React-Query](https://tanstack.com/query) using `createQuery` function.
+Mutations are designed for changing data.\
+Examples:
 
-It can dedupe multiple request, handle caching, auto-update stale data, handle retry on error, handle infinite query, and many more. With the flexibility given in `createStores`, you can extend its power according to your needs.
+- insert
+- update
+- delete
+- triggering side effects
 
-### Query State & Network Fetching State
+Because mutations are **not safe to repeat blindly**, FloppyDisk does **not** include:
 
-There are 2 types of state: query (data) state & network fetching state.
+- ❌ automatic retry
+- ❌ automatic revalidation
+- ❌ implicit re-execution
 
-`status`, `isLoading`, `isSuccess`, `isError` is a query data state.  
-It has no relation with network fetching state. ⚠️  
-Here is the flow of the query data state:
+This is intentional.\
+Mutations should be explicit and controlled, not automatic.
 
-- Initial state when there is no data fetched.  
-  `{ status: 'loading', isLoading: true, isSuccess: false, isError: false }`
-- After data fetching:
-  - If success
-    `{ status: 'success', isLoading: false, isSuccess: true, isError: false }`
-  - If error
-    `{ status: 'error', isLoading: false, isSuccess: false, isError: true }`
-- After data fetched successfully, you will **always** get this state:  
-  `{ status: 'success', isLoading: false, isSuccess: true, isError: false }`
-  - If a refetch is fired and got error, the state would be:  
-    `{ status: 'success', isLoading: false, isSuccess: true, isError: false, isRefetchError: true }`  
-    The previouse success response will be kept.
+If you need retry mechanism, then you can always add it manually.
 
-For network fetching state, we use `isWaiting`.  
-The value will be `true` if the query is called and still waiting for the response.
+</details>
 
-### Inherited from createStores
+### Single Query
 
-The `createQuery` function inherits functionality from the `createStores` function, allowing us to perform the same result and actions available in `createStores`.
+Create a query using `createQuery`:
 
 ```tsx
-const useMyQuery = createQuery(myQueryFn, {
-  // 👇 Same as createStores options
-  defaultDeps: undefined,
-  onFirstSubscribe: (state) => console.log('onFirstSubscribe', state),
-  onSubscribe: (state) => console.log('onSubscribe', state),
-  onUnsubscribe: (state) => console.log('onUnsubscribe', state),
-  onLastUnsubscribe: (state) => console.log('onLastUnsubscribe', state),
-  onBeforeChangeKey: (nextKey, prevKey) => console.log('Store key changed', nextKey, prevKey),
-
-  // ... other createQuery options
-});
-```
+import { createQuery } from 'floppy-disk/react';
 
-Custom reactivity (dependency array) also works:
+const myCoolQuery = createQuery(
+  myAsyncFn,
+  // { staleTime: 5000, revalidateOnFocus: false } <-- optional options
+);
 
-```tsx
-function QueryLoader() {
-  // This component doesn't care whether the query is success or error.
-  // It just listening to network fetching state. 👇
-  const { isWaiting } = useMyQuery((state) => [state.isWaiting]);
-  return <div>Is network fetching? {String(isWaiting)}</div>;
+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>;
 }
 ```
 
-### Single Query
+### Query State: Two Independent Dimensions
 
-```jsx
-const useGitHubQuery = createQuery(async () => {
-  const res = await fetch('https://api.github.com/repos/afiiif/floppy-disk');
-  if (res.ok) return res.json();
-  throw res;
-});
+FloppyDisk tracks two things separately:
 
-function SingleQuery() {
-  const { isLoading, data } = useGitHubQuery();
+- Is it running? → `isPending`\
+  (value: `boolean`)
+- What's the result? → `state`\
+  (value: `INITIAL | 'SUCCESS' | 'ERROR' | 'SUCCESS_BUT_REVALIDATION_ERROR'`)
 
-  if (isLoading) return <div>Loading...</div>;
+They are **independent**.
 
-  return (
-    <div>
-      <h1>{data.name}</h1>
-      <p>{data.description}</p>
-      <strong>⭐️ {data.stargazers_count}</strong>
-      <strong>🍴 {data.forks_count}</strong>
-    </div>
-  );
-}
-```
+### Automatic Re-render Optimization
 
-> Example: [https://codesandbox.io/.../examples/react/query](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/query)
+Just like the global store, FloppyDisk tracks usage automatically:
 
-Actions:
+```tsx
+const { data } = useMyQuery();
+// ^Only data changes will trigger a re-render
 
-Normally, we don't need reactivity for the actions.
-Therefore, using `get` method will be better, since it will not re-render the component when a query state changed.
+const value = useMyQuery().data?.foo.bar.baz;
+// ^Only data.foo.bar.baz changes will trigger a re-render
+```
 
-```jsx
-function Actions() {
-  const { fetch, forceFetch, reset } = useGitHubQuery.get();
+### Keyed Query (Dynamic Params)
 
-  // Or like this:
-  // const { isLoading, data, error, fetch, forceFetch, reset } = useGitHubQuery();
+You can create parameterized queries:
 
-  return (
-    <>
-      <button onClick={fetch}>Call query if the query data is stale</button>
-      <button onClick={forceFetch}>Call query</button>
-      <button onClick={reset}>Reset query</button>
-    </>
-  );
-}
-```
+```tsx
+import { getUserById, type GetUserByIdResponse } from '../utils';
 
-Options:
+type MyQueryParam = { id: string };
 
-```jsx
-const useGitHubQuery = createQuery(
-  async () => {
-    const res = await fetch('https://api.github.com/repos/afiiif/floppy-disk');
-    if (res.ok) return res.json();
-    throw res;
-  },
-  {
-    fetchOnMount: false,
-    enabled: () => !!useUserQuery.get().data?.user,
-    select: (response) => response.name,
-    staleTime: Infinity, // Never stale
-    retry: 0, // No retry
-    onSuccess: (response) => {},
-    onError: (error) => {},
-    onSettled: () => {},
-  },
+const userQuery = createQuery<GetUserByIdResponse, MyQueryParam>(
+  getUserById,
+  // { staleTime: 5000, revalidateOnFocus: false } <-- optional options
 );
-
-function MyComponent() {
-  const { data, response } = useGitHubQuery();
-  /**
-   * Since in option we select the data like this:
-   * select: (response) => response.name
-   *
-   * The return will be:
-   * {
-   *   response: { id: 677863376, name: "floppy-disk", ... },
-   *   data: "floppy-disk",
-   *   ...
-   * }
-   */
-}
 ```
 
-Get data or do something outside component:
+Use it with parameters:
 
-```jsx
-const getData = () => console.log(useGitHubQuery.get().data);
-const resetQuery = () => useGitHubQuery.get().reset();
-
-// Works just like createStores
-useMyQuery.get(/* ... */);
-useMyQuery.set(/* ... */);
-useMyQuery.subscribe(/* ... */);
-useMyQuery.getSubscribers(/* ... */);
+```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>;
+}
 ```
 
-### Single Query with Params
+Each unique parameter creates its own cache entry.
 
-```jsx
-const usePokemonQuery = createQuery(async ({ pokemon }) => {
-  const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${pokemon}`);
-  if (res.ok) return res.json();
-  throw res;
-});
+### Infinite Query
 
-function PokemonPage() {
-  const [currentPokemon, setCurrentPokemon] = useState();
-  const { isLoading, data } = usePokemonQuery({ pokemon: currentPokemon });
+FloppyDisk does **not provide** a dedicated "infinite query" API.\
+Instead, it embraces a simpler and more flexible approach:
 
-  if (isLoading) return <div>Loading...</div>;
+> Infinite queries are just **composition** + **recursion**.
 
-  return (
-    <div>
-      <h1>{data.name}</h1>
-      <div>Weight: {data.weight}</div>
-    </div>
-  );
-}
-```
+Why? Because async state is already powerful enough:
 
-> Example: [https://codesandbox.io/.../examples/react/query-with-param](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/query-with-param)
+- keyed queries handle parameters
+- components handle composition
+- recursion handles pagination
 
-Get data or do something outside component:
+No special abstraction needed.
 
-```jsx
-const getDitto = () => {
-  console.log(usePokemonQuery.get({ pokemon: 'ditto' }).data);
-};
+Here is the example on how to implement infinite query properly:
 
-const resetDitto = () => {
-  usePokemonQuery.get({ pokemon: 'ditto' }).reset();
+```tsx
+type GetPostParams = {
+  cursor?: string; // For pagination
+};
+type GetPostsResponse = {
+  posts: Post[];
+  meta: { nextCursor: string };
 };
 
-function Actions() {
-  return (
-    <>
-      <button onClick={getDitto}>Get Ditto Data</button>
-      <button onClick={resetDitto}>Reset Ditto</button>
-    </>
-  );
-}
-```
-
-### Paginated Query or Infinite Query
-
-```jsx
-const usePokemonsInfQuery = createQuery(
-  async (_, { pageParam = 0 }) => {
-    const res = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=10&offset=${pageParam}`);
-    if (res.ok) return res.json();
-    throw res;
-  },
+const postsQuery = createQuery<GetPostsResponse, GetPostParams>(
+  getPosts,
   {
-    select: (response, { data = [] }) => [...data, ...response.results],
-    getNextPageParam: (lastPageResponse, i) => {
-      if (i > 5) return undefined; // Return undefined means you have reached the end of the pages
-      return i * 10;
-    },
+    staleTime: Infinity,
+    revalidateOnFocus: false,
+    revalidateOnReconnect: false,
   },
 );
 
-function PokemonListPage() {
-  const { data = [], fetchNextPage, hasNextPage, isWaitingNextPage } = usePokemonsInfQuery();
+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 (
-    <div>
-      {data.map((pokemon) => (
-        <div key={pokemon.name}>{pokemon.name}</div>
+    <>
+      {data.posts.map(post => (
+        <PostCard key={post.id} post={post} />
       ))}
-      {isWaitingNextPage ? (
-        <div>Loading more...</div>
-      ) : (
-        hasNextPage && <button onClick={fetchNextPage}>Load more</button>
+      {data.meta.nextCursor && (
+        <LoadMore nextCursor={data.meta.nextCursor} />
       )}
-    </div>
+    </>
   );
 }
-```
-
-> Example: [https://codesandbox.io/.../examples/react/infinite-query](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/infinite-query)
-
-**Note:**
 
-- The default stale time is 3 seconds.
-- The default error retry attempt is 1 time, and retry delay is 2 seconds.
-- The default reactivity of a query is:  
-  `(s) => [s.data, s.error, s.isWaitingNextPage, s.hasNextPage]`
-  - Note that by default, subscribers don't listen to `isWaiting` state.
-  - You can change the `defaultDeps` on `createQuery` options.
+function LoadMore({ nextCursor }: { nextCursor?: string }) {
+  const [isNextPageRequested, setIsNextPageRequested] = useState(() => {
+    const stateOfNextPageQuery = postsQuery({ cursor: nextCursor }).getState();
+    return stateOfNextPageQuery.isPending || stateOfNextPageQuery.isSuccess;
+  });
 
-### Mutation
+  if (isNextPageRequested) {
+    return <Page cursor={nextCursor} />;
+  }
 
-```jsx
-const useLoginMutation = createMutation(
-  async (variables) => {
-    const res = await axios.post('/auth/login', {
-      email: variables.email,
-      password: variables.password,
-    });
-    return res.data;
-  },
-  {
-    onSuccess: (response, variables) => {
-      console.log(`Logged in as ${variables.email}`);
-      console.log(`Access token: ${response.data.accessToken}`);
-    },
-  },
-);
-
-function Login() {
-  const { mutate, isWaiting } = useLoginMutation();
-  const showToast = useToast();
   return (
-    <div>
-      <button
-        disabled={isWaiting}
-        onClick={() => {
-          mutate({ email: 'foo@bar.baz', password: 's3cREt' }).then(({ response, error }) => {
-            if (error) {
-              showToast('Login failed');
-            } else {
-              showToast('Login success');
-            }
-          });
-        }}
-      >
-        Login
-      </button>
-    </div>
+    <ReachingBottomObserver
+      onReachBottom={() => setIsNextPageRequested(true)}
+    />
   );
 }
 ```
 
-Optimistic update:
+When implementing infinite queries, it is **highly recommended to disable automatic revalidation**.
 
-```jsx
-function SaveProduct() {
-  const { mutate, isWaiting } = useEditProductMutation();
-  const { getValues } = useFormContext();
+Why?\
+In an infinite list, users may scroll through many pages ("_doom-scrolling_").\
+If revalidation is triggered:
 
-  return (
-    <button
-      disabled={isWaiting}
-      onClick={() => {
-        const payload = getValues();
-
-        const { revert, invalidate } = useProductQuery.optimisticUpdate({
-          key: { id: payload.id },
-          response: payload,
-        });
-
-        mutate(payload).then(({ response, error }) => {
-          if (error) {
-            revert();
-          }
-          invalidate();
-        });
-      }}
-    >
-      Save
-    </button>
-  );
-}
-```
+- All previously loaded pages may re-execute
+- Content at the top may change without the user noticing
+- Layout shifts can occur unexpectedly
 
-> Example: [https://codesandbox.io/.../examples/react/mutation](https://codesandbox.io/p/sandbox/github/afiiif/floppy-disk-site/tree/main/examples/react/mutation)
+This leads to a **confusing and unstable user experience**.\
+Revalidating dozens of previously viewed pages rarely provides value to the user.
 
-<br><br>
+## SSR Guidance
 
-<p align="center">
-  — ✨ 💾 ✨ —
-</p>
-<br>
+FloppyDisk is designed primarily for **client-side [sync/async] state**.
 
-## Important Notes
+If your data is already fetched on the server (e.g. via SSR/ISR, Server Components, or Server Actions), then:
 
-Don't mutate. (unless you use Immer JS library or something similar)
+> **You most likely don't need this library.**
 
-```js
-import { createStore } from 'floppy-disk';
+This is the same philosophy as TanStack Query. 💡
 
-const useCartStore = createStore(({ set, get }) => ({
-  products: [],
-  addProduct: (newProduct) => {
-    const currentProducts = get().products;
-    product.push(newProduct); // ❌ Don't mutate
-    set({ product });
-  },
-}));
-```
+In many cases, developers mix SSR/ISR with client-side state because they want:
 
-Don't use conditional reactivity selector.
+1. Data to be rendered into HTML on the server
+2. The ability to **revalidate it on the client**
 
-```jsx
-function Cat({ isSomething }) {
-  const { age } = useCatStore(isSomething ? (state) => [state.age] : null); // ❌
-  const { age } = useCatStore((state) => (isSomething ? [state.age] : [state.isSleeping])); // ❌
-  return <div>Cat's age: {age}</div>;
-}
-```
+A common (but inefficient) approach is:
 
-No need to memoize the reactivity selector.
+- fetch on the server
+- hydrate it into a client-side cache
+- then revalidate using a query library
 
-```jsx
-function Cat() {
-  const selectAge = useCallback((state) => [state.age], []); // ❌
-  const { age } = useCatStore(selectAge);
-  return <div>Cat's age: {age}</div>;
-}
-```
+While this works, it introduces additional complexity.
 
-No need to memoize the store key / query key.
+Instead, we encourage a simpler approach:
 
-```jsx
-function PokemonsPage() {
-  const queryKey = useMemo(() => ({ generation: 'ii', sort: 'asc' }), []); // ❌
-  const { isLoading, data } = usePokemonsQuery(queryKey);
-  return <div>...</div>;
-}
-```
+> If your data is fetched on the server, revalidate it using **your framework's built-in mechanism** (e.g. Next.js route revalidation).
 
-<br>
+Because of this philosophy, FloppyDisk **does not support** hydrating server-fetched data into the client store.
 
----
+This keeps the mental model clean:
 
-<p align="center">
-  View official documentation on <a href="https://floppy-disk.vercel.app/">floppy-disk.vercel.app</a>
-</p>
+- server data → handled by the framework
+- client async state → handled by FloppyDisk