floppy-disk 3.0.1 → 3.1.0

package/README.md

@@ -365,34 +365,39 @@ Revalidating dozens of previously viewed pages rarely provides value to the user
 
 ## SSR Guidance
 
-FloppyDisk is designed primarily for **client-side [sync/async] state**.
+Examples for using stores and queries in SSR with isolated data (no shared state between users).
 
-If your data is already fetched on the server (e.g. via SSR/ISR, Server Components, or Server Actions), then:
+### Initialize Store State from Server
 
-> **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:
+```tsx
+const useCountStore = createStore({ count: 0 });
 
-- fetch on the server
-- hydrate it into a client-side cache
-- then revalidate using a query library
+function Page({ initialCount }) {
+  const { count } = useCountStore({
+    initialState: { count: initialCount }, // e.g. 3
+  });
 
-While this works, it introduces additional complexity.
+  return <>count is {count}</>; // Output: count is 3
+}
+```
 
-Instead, we encourage a simpler approach:
+### Initialize Query Data from Server
 
-> If your data is fetched on the server, revalidate it using **your framework's built-in mechanism** (e.g. Next.js route revalidation).
+```tsx
+async function MyServerComponent() {
+  const data = await getData(); // e.g. { count: 3 }
+  return <MyClientComponent initialData={data} />;
+}
 
-Because of this philosophy, FloppyDisk **does not support** hydrating server-fetched data into the client store.
+const myQuery = createQuery(getData);
+const useMyQuery = myQuery();
 
-This keeps the mental model clean:
+function MyClientComponent({ initialData }) {
+  const { data } = useMyQuery({
+    initialData: initialData,
+    // initialDataIsStale: true <-- Optional, default to false (no immediate revalidation)
+  });
 
-- server data → handled by the framework
-- client async state → handled by FloppyDisk
+  return <>count is {data.count}</>; // Output: count is 3
+}
+```

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

@@ -182,7 +182,33 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * // While loading userId=2, still show userId=1 data
      * useQuery({ id: userId }, { keepPreviousData: true });
      */ keepPreviousData?: boolean;
-}) => QueryState<TData, TError>) & {
+} & ({
+    /**
+     * Initial data used on first render (and will also update the store state right after that)
+     *
+     * If provided, `initialData` will be applied **once per query-store instance**
+     */
+    initialData: TData;
+    /**
+     * Whether the provided `initialData` should be treated as stale.
+     *
+     * @remarks
+     * - If `true`, a revalidation (refetch) will be triggered immediately.
+     * - If `false` (default), `initialData` is treated as fresh and will not be revalidated.
+     *
+     * @default false
+     *
+     * @example
+     * useQuery({
+     *   initialData: dataFromSSR,
+     *   initialDataIsStale: true, // force refetch
+     * });
+     */
+    initialDataIsStale?: boolean;
+} | {
+    initialData?: never;
+    initialDataIsStale?: never;
+})) => QueryState<TData, TError>) & {
     metadata: {
         isInvalidated?: boolean;
         promise?: Promise<QueryState<TData, TError>> | undefined;

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

@@ -25,4 +25,9 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  *
  * 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>) => (() => TState) & import("../vanilla.d.mts").StoreApi<TState>;
+export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => ((options?: {
+    /**
+     * Initial state used on first render (and will also update the store state right after that)
+     */
+    initialState?: Partial<TState>;
+}) => TState) & import("../vanilla.d.mts").StoreApi<TState>;

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

@@ -30,7 +30,14 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  *   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) => (() => TState) & {
+export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => ((options?: {
+    /**
+     * Initial state used on first render (and will also update the store state right after that)
+     *
+     *  If provided, `initialState` will be applied **once per store instance**
+     */
+    initialState?: Partial<TState>;
+}) => TState) & {
     delete: () => boolean;
     setState: (value: import("../vanilla.d.mts").SetState<TState>) => void;
     getState: () => TState;

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

@@ -4,10 +4,14 @@ 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[]>];
+export declare const NO_INITIAL_VALUE: {};
+export declare const useStoreStateWithInitializer: <TState extends Record<string, any>>(store: StoreApi<TState>, initialState?: Partial<TState>) => readonly [TState, import("react").RefObject<WeakMap<StoreApi<TState>, number>>];
 /**
  * React hook for subscribing to a store using automatic dependency tracking.
  *
  * @param store - The store instance to subscribe to
+ * @param options - Optional configuration
+ * @param options.initialState - Initial state used on first render (and will also update the store state right after that)
  *
  * @returns A proxied version of the store state
  *
@@ -17,12 +21,14 @@ export declare const useStoreStateProxy: <TState extends Record<string, any>>(st
  * - 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.
+ * - If provided, `initialState` will be applied **once per store instance**
  *
  * @example
  * 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>>(storeState: TState, subscribe: StoreApi<TState>["subscribe"]) => TState;
+export declare const useStoreState: <TState extends Record<string, any>>(store: StoreApi<TState>, options?: {
+    initialState?: Partial<TState>;
+}) => TState;
 export {};

package/esm/react.mjs

@@ -49,11 +49,24 @@ const useStoreStateProxy = (storeState) => {
   }, [storeState]);
   return [trackedState, usedPathsRef];
 };
-const useStoreState = (storeState, subscribe) => {
-  const [trackedState, usedPathsRef] = useStoreStateProxy(storeState);
+const NO_INITIAL_VALUE = {};
+const useStoreStateWithInitializer = (store, initialState = NO_INITIAL_VALUE) => {
+  const initiatedAt = useRef(new WeakMap([[store, 0]]));
+  useIsomorphicLayoutEffect(() => {
+    if (initialState === NO_INITIAL_VALUE || initiatedAt.current.get(store)) return;
+    store.setState(initialState);
+    initiatedAt.current.set(store, Date.now());
+  }, [store, initialState]);
+  const storeState = store.getState();
+  const finalState = initialState === NO_INITIAL_VALUE || initiatedAt.current.get(store) ? storeState : { ...storeState, ...initialState };
+  return [finalState, initiatedAt];
+};
+const useStoreState = (store, options = {}) => {
+  const [state] = useStoreStateWithInitializer(store, options.initialState);
+  const [trackedState, usedPathsRef] = useStoreStateProxy(state);
   const [, reRender] = useState({});
   useIsomorphicLayoutEffect(() => {
-    return subscribe((nextState, prevState, changedKeys) => {
+    return store.subscribe((nextState, prevState, changedKeys) => {
       const paths = compressPaths(usedPathsRef.current);
       for (const path of paths) {
         const rootKey = path[0];
@@ -63,13 +76,13 @@ const useStoreState = (storeState, subscribe) => {
         if (!Object.is(prevVal, nextVal)) return reRender({});
       }
     });
-  }, [subscribe]);
+  }, [store]);
   return trackedState;
 };
 
 const createStore = (initialState, options) => {
   const store = initStore(initialState, options);
-  const useStore = () => useStoreState(store.getState(), store.subscribe);
+  const useStore = (options2) => useStoreState(store, options2);
   return Object.assign(useStore, store);
 };
 
@@ -84,7 +97,7 @@ const createStores = (initialState, options) => {
       store = initStore(initialState, options);
       stores.set(keyHash, store);
     }
-    const useStore = () => useStoreState(store.getState(), store.subscribe);
+    const useStore = (options2) => useStoreState(store, options2);
     return Object.assign(useStore, {
       ...store,
       delete: () => {
@@ -367,8 +380,20 @@ const createQuery = (queryFn, options = {}) => {
       internals.set(store, configureInternals(store, variable, variableHash));
     }
     const useStore = (options2 = {}) => {
-      const { revalidateOnMount = true, keepPreviousData } = options2;
-      const storeState = store.getState();
+      const {
+        initialData = NO_INITIAL_VALUE,
+        initialDataIsStale = false,
+        revalidateOnMount = true,
+        keepPreviousData
+      } = options2;
+      const [storeState, initialDataInitiatedAt] = useStoreStateWithInitializer(
+        store,
+        initialData === NO_INITIAL_VALUE ? void 0 : {
+          state: "SUCCESS",
+          isSuccess: true,
+          data: initialData
+        }
+      );
       const prevState = useRef({});
       let storeStateToBeUsed = storeState;
       if (storeState.state !== "INITIAL") {
@@ -404,8 +429,16 @@ const createQuery = (queryFn, options = {}) => {
         });
       }, [store]);
       useIsomorphicLayoutEffect(() => {
-        if (revalidateOnMount !== false) revalidate(store, variable, false);
-      }, [store, revalidateOnMount]);
+        if (revalidateOnMount !== false) {
+          if (!initialDataIsStale) {
+            const dataInitiatedAt = initialDataInitiatedAt.current.get(store);
+            if (dataInitiatedAt && dataInitiatedAt + staleTime > Date.now()) {
+              return;
+            }
+          }
+          revalidate(store, variable, false);
+        }
+      }, [store, revalidateOnMount, initialDataIsStale]);
       if (keepPreviousData) {
         !!trackedState.error;
       }
@@ -483,7 +516,7 @@ const createMutation = (mutationFn, options = {}) => {
   let ongoingPromise;
   const resolveFns = /* @__PURE__ */ new Set([]);
   const store = initStore(initialState, options);
-  const useStore = () => useStoreState(store.getState(), store.subscribe);
+  const useStore = () => useStoreState(store);
   const execute = (variable) => {
     let currentResolveFn;
     const stateBeforeExecute = store.getState();

package/esm/vanilla/store.d.mts

@@ -51,6 +51,12 @@ export type InitStoreOptions<TState extends Record<string, any>> = {
     onSubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onLastUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    /**
+     * Called whenever the state changes, without counting as a subscriber.
+     * Acts like a "spy" on state updates.
+     * Useful for devtools, logging, or debugging state changes.
+     */
+    onStateChange?: (state: TState, prevState: TState, changedKeys: Array<keyof TState>) => void;
     /**
      * By default, calling `setState` on the server is disallowed to prevent shared state across requests.
      * Set this to `true` only if you explicitly intend to mutate state during server execution.

package/esm/vanilla.mjs

@@ -35,6 +35,7 @@ const initStore = (initialState, options = {}) => {
     onSubscribe = noop,
     onUnsubscribe = noop,
     onLastUnsubscribe = noop,
+    onStateChange = noop,
     allowSetStateServerSide = false
   } = options;
   const subscribers = /* @__PURE__ */ new Set();
@@ -68,6 +69,7 @@ const initStore = (initialState, options = {}) => {
     }
     if (changedKeys.length === 0) return;
     state = { ...prevState, ...newValue };
+    onStateChange(state, prevState, changedKeys);
     [...subscribers].forEach((subscriber) => subscriber(state, prevState, changedKeys));
   };
   const storeApi = {

package/package.json

@@ -2,7 +2,7 @@
   "name": "floppy-disk",
   "description": "Lightweight, simple, and powerful state management library",
   "private": false,
-  "version": "3.0.1",
+  "version": "3.1.0",
   "keywords": [
     "utilities",
     "store",

package/react/create-query.d.ts

@@ -182,7 +182,33 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * // While loading userId=2, still show userId=1 data
      * useQuery({ id: userId }, { keepPreviousData: true });
      */ keepPreviousData?: boolean;
-}) => QueryState<TData, TError>) & {
+} & ({
+    /**
+     * Initial data used on first render (and will also update the store state right after that)
+     *
+     * If provided, `initialData` will be applied **once per query-store instance**
+     */
+    initialData: TData;
+    /**
+     * Whether the provided `initialData` should be treated as stale.
+     *
+     * @remarks
+     * - If `true`, a revalidation (refetch) will be triggered immediately.
+     * - If `false` (default), `initialData` is treated as fresh and will not be revalidated.
+     *
+     * @default false
+     *
+     * @example
+     * useQuery({
+     *   initialData: dataFromSSR,
+     *   initialDataIsStale: true, // force refetch
+     * });
+     */
+    initialDataIsStale?: boolean;
+} | {
+    initialData?: never;
+    initialDataIsStale?: never;
+})) => QueryState<TData, TError>) & {
     metadata: {
         isInvalidated?: boolean;
         promise?: Promise<QueryState<TData, TError>> | undefined;

package/react/create-store.d.ts

@@ -25,4 +25,9 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  *
  * 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>) => (() => TState) & import("../vanilla.ts").StoreApi<TState>;
+export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => ((options?: {
+    /**
+     * Initial state used on first render (and will also update the store state right after that)
+     */
+    initialState?: Partial<TState>;
+}) => TState) & import("../vanilla.ts").StoreApi<TState>;

package/react/create-stores.d.ts

@@ -30,7 +30,14 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  *   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) => (() => TState) & {
+export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => ((options?: {
+    /**
+     * Initial state used on first render (and will also update the store state right after that)
+     *
+     *  If provided, `initialState` will be applied **once per store instance**
+     */
+    initialState?: Partial<TState>;
+}) => TState) & {
     delete: () => boolean;
     setState: (value: import("../vanilla.ts").SetState<TState>) => void;
     getState: () => TState;

package/react/use-store.d.ts

@@ -4,10 +4,14 @@ 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[]>];
+export declare const NO_INITIAL_VALUE: {};
+export declare const useStoreStateWithInitializer: <TState extends Record<string, any>>(store: StoreApi<TState>, initialState?: Partial<TState>) => readonly [TState, import("react").RefObject<WeakMap<StoreApi<TState>, number>>];
 /**
  * React hook for subscribing to a store using automatic dependency tracking.
  *
  * @param store - The store instance to subscribe to
+ * @param options - Optional configuration
+ * @param options.initialState - Initial state used on first render (and will also update the store state right after that)
  *
  * @returns A proxied version of the store state
  *
@@ -17,12 +21,14 @@ export declare const useStoreStateProxy: <TState extends Record<string, any>>(st
  * - 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.
+ * - If provided, `initialState` will be applied **once per store instance**
  *
  * @example
  * 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>>(storeState: TState, subscribe: StoreApi<TState>["subscribe"]) => TState;
+export declare const useStoreState: <TState extends Record<string, any>>(store: StoreApi<TState>, options?: {
+    initialState?: Partial<TState>;
+}) => TState;
 export {};

package/react.js

@@ -51,11 +51,24 @@ const useStoreStateProxy = (storeState) => {
   }, [storeState]);
   return [trackedState, usedPathsRef];
 };
-const useStoreState = (storeState, subscribe) => {
-  const [trackedState, usedPathsRef] = useStoreStateProxy(storeState);
+const NO_INITIAL_VALUE = {};
+const useStoreStateWithInitializer = (store, initialState = NO_INITIAL_VALUE) => {
+  const initiatedAt = react.useRef(new WeakMap([[store, 0]]));
+  useIsomorphicLayoutEffect(() => {
+    if (initialState === NO_INITIAL_VALUE || initiatedAt.current.get(store)) return;
+    store.setState(initialState);
+    initiatedAt.current.set(store, Date.now());
+  }, [store, initialState]);
+  const storeState = store.getState();
+  const finalState = initialState === NO_INITIAL_VALUE || initiatedAt.current.get(store) ? storeState : { ...storeState, ...initialState };
+  return [finalState, initiatedAt];
+};
+const useStoreState = (store, options = {}) => {
+  const [state] = useStoreStateWithInitializer(store, options.initialState);
+  const [trackedState, usedPathsRef] = useStoreStateProxy(state);
   const [, reRender] = react.useState({});
   useIsomorphicLayoutEffect(() => {
-    return subscribe((nextState, prevState, changedKeys) => {
+    return store.subscribe((nextState, prevState, changedKeys) => {
       const paths = compressPaths(usedPathsRef.current);
       for (const path of paths) {
         const rootKey = path[0];
@@ -65,13 +78,13 @@ const useStoreState = (storeState, subscribe) => {
         if (!Object.is(prevVal, nextVal)) return reRender({});
       }
     });
-  }, [subscribe]);
+  }, [store]);
   return trackedState;
 };
 
 const createStore = (initialState, options) => {
   const store = vanilla.initStore(initialState, options);
-  const useStore = () => useStoreState(store.getState(), store.subscribe);
+  const useStore = (options2) => useStoreState(store, options2);
   return Object.assign(useStore, store);
 };
 
@@ -86,7 +99,7 @@ const createStores = (initialState, options) => {
       store = vanilla.initStore(initialState, options);
       stores.set(keyHash, store);
     }
-    const useStore = () => useStoreState(store.getState(), store.subscribe);
+    const useStore = (options2) => useStoreState(store, options2);
     return Object.assign(useStore, {
       ...store,
       delete: () => {
@@ -369,8 +382,20 @@ const createQuery = (queryFn, options = {}) => {
       internals.set(store, configureInternals(store, variable, variableHash));
     }
     const useStore = (options2 = {}) => {
-      const { revalidateOnMount = true, keepPreviousData } = options2;
-      const storeState = store.getState();
+      const {
+        initialData = NO_INITIAL_VALUE,
+        initialDataIsStale = false,
+        revalidateOnMount = true,
+        keepPreviousData
+      } = options2;
+      const [storeState, initialDataInitiatedAt] = useStoreStateWithInitializer(
+        store,
+        initialData === NO_INITIAL_VALUE ? void 0 : {
+          state: "SUCCESS",
+          isSuccess: true,
+          data: initialData
+        }
+      );
       const prevState = react.useRef({});
       let storeStateToBeUsed = storeState;
       if (storeState.state !== "INITIAL") {
@@ -406,8 +431,16 @@ const createQuery = (queryFn, options = {}) => {
         });
       }, [store]);
       useIsomorphicLayoutEffect(() => {
-        if (revalidateOnMount !== false) revalidate(store, variable, false);
-      }, [store, revalidateOnMount]);
+        if (revalidateOnMount !== false) {
+          if (!initialDataIsStale) {
+            const dataInitiatedAt = initialDataInitiatedAt.current.get(store);
+            if (dataInitiatedAt && dataInitiatedAt + staleTime > Date.now()) {
+              return;
+            }
+          }
+          revalidate(store, variable, false);
+        }
+      }, [store, revalidateOnMount, initialDataIsStale]);
       if (keepPreviousData) {
         !!trackedState.error;
       }
@@ -485,7 +518,7 @@ const createMutation = (mutationFn, options = {}) => {
   let ongoingPromise;
   const resolveFns = /* @__PURE__ */ new Set([]);
   const store = vanilla.initStore(initialState, options);
-  const useStore = () => useStoreState(store.getState(), store.subscribe);
+  const useStore = () => useStoreState(store);
   const execute = (variable) => {
     let currentResolveFn;
     const stateBeforeExecute = store.getState();

package/vanilla/store.d.ts

@@ -51,6 +51,12 @@ export type InitStoreOptions<TState extends Record<string, any>> = {
     onSubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onLastUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    /**
+     * Called whenever the state changes, without counting as a subscriber.
+     * Acts like a "spy" on state updates.
+     * Useful for devtools, logging, or debugging state changes.
+     */
+    onStateChange?: (state: TState, prevState: TState, changedKeys: Array<keyof TState>) => void;
     /**
      * By default, calling `setState` on the server is disallowed to prevent shared state across requests.
      * Set this to `true` only if you explicitly intend to mutate state during server execution.

package/vanilla.js

@@ -37,6 +37,7 @@ const initStore = (initialState, options = {}) => {
     onSubscribe = noop,
     onUnsubscribe = noop,
     onLastUnsubscribe = noop,
+    onStateChange = noop,
     allowSetStateServerSide = false
   } = options;
   const subscribers = /* @__PURE__ */ new Set();
@@ -70,6 +71,7 @@ const initStore = (initialState, options = {}) => {
     }
     if (changedKeys.length === 0) return;
     state = { ...prevState, ...newValue };
+    onStateChange(state, prevState, changedKeys);
     [...subscribers].forEach((subscriber) => subscriber(state, prevState, changedKeys));
   };
   const storeApi = {