floppy-disk 3.6.1 → 3.7.0-beta.1

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

@@ -44,17 +44,7 @@ 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;
-};
+export declare const INITIAL_STATE: MutationState<any, any, any>;
 /**
  * Configuration options for a mutation.
  *

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

@@ -63,15 +63,149 @@ export type QueryState<TData, TError> = {
     error: TError;
     errorUpdatedAt: number;
 });
+type Internal<TData, TError> = {
+    isInvalidated?: boolean;
+    promise?: Promise<QueryState<TData, TError>> | undefined;
+    promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
+    retryTimeoutId?: number;
+    retryResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
+    garbageCollectionTimeoutId?: number;
+    rollbackData?: TData | undefined;
+};
+type AdditionalStoreApi<TData, TError> = {
+    /**
+     * A deterministic hash string derived from the query variable.
+     *
+     * Used as the unique identifier for this query instance in the internal cache.
+     *
+     * @remarks
+     * - Structurally identical variables will produce the same hash.
+     */
+    variableHash: string;
+    /**
+     * Sets initial data for the query if it has not been initialized.
+     *
+     * @param data - Initial data
+     * @param revalidate - Whether to mark the data as invalidated (will trigger revalidation)
+     *
+     * @returns `true` if the data was set, `false` otherwise
+     *
+     * @remarks
+     * - Only applies when the query is in the `INITIAL` state.
+     * - Useful for hydration or preloaded data.
+     */
+    setInitialData: (data: TData, revalidate?: boolean) => boolean;
+    /**
+     * Executes the query function.
+     *
+     * @param options - Execution options
+     * @param options.overwriteOngoingExecution - Whether to start a new execution instead of reusing an ongoing one (default: `true`)
+     *
+     * @returns A promise resolving to the latest query state
+     *
+     * @remarks
+     * - By default, each call **starts a new execution** even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     * - Handles:
+     *   - Pending state
+     *   - Success state
+     *   - Error state
+     *   - Retry logic
+     */
+    execute: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Re-executes the query if needed based on freshness or invalidation.
+     *
+     * @param options - Revalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns The current state if still fresh, otherwise a promise of the new state
+     *
+     * @remarks
+     * - Skips execution if data is still fresh (`staleTime`) **AND** the query has not been invalidated.
+     * - If execution is not skipped, by default it will start a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    revalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Marks the query as invalidated and optionally triggers re-execution.
+     *
+     * @param options - Invalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns `true` if execution was triggered, `false` otherwise
+     *
+     * @remarks
+     * - Invalidated queries are treated as stale regardless of `staleTime`.
+     * - The next `revalidate` will always execute until a successful result clears the invalidation.
+     * - If there are active subscribers: Execution is triggered immediately.
+     * - Otherwise: The query remains invalidated and will execute on the next revalidation.
+     * - By default, starts a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    invalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => boolean;
+    /**
+     * Resets the query state to its initial state.
+     *
+     * @remarks
+     * - Cancels retry logic and ignores any ongoing execution results.
+     */
+    reset: () => void;
+    /**
+     * Deletes the query store for the current variable.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers.
+     */
+    delete: () => boolean;
+    /**
+     * Performs an optimistic update on the query data.
+     *
+     * @param data - Optimistic data to set
+     *
+     * @returns Controls for managing the optimistic update
+     *
+     * @remarks
+     * - Temporarily replaces the current data.
+     * - Stores previous data for rollback.
+     * - Commonly used with mutations for instant UI updates.
+     *
+     * @example
+     * const { rollback, revalidate } = query.optimisticUpdate(newData);
+     */
+    optimisticUpdate: (data: TData) => {
+        revalidate: () => Promise<QueryState<TData, TError>>;
+        rollback: () => TData;
+    };
+    /**
+     * Restores the data before the last optimistic update.
+     *
+     * @returns The restored data
+     *
+     * @remarks
+     * - Should be used if an optimistic update fails.
+     */
+    rollbackOptimisticUpdate: () => TData;
+    /**
+     * Internal data, do not mutate!
+     */
+    internal: Readonly<Internal<TData, TError>>;
+};
 /**
  * Configuration options for a query.
  *
  * @remarks
  * Controls caching, retry behavior, lifecycle, and side effects of an async operation.
  */
-export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, {
-    variableHash: string;
-}> & {
+export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, AdditionalStoreApi<TData, TError>> & {
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
@@ -219,19 +353,19 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
     initialData?: never;
     initialDataIsStale?: never;
 })) => QueryState<TData, TError>) & {
-    variableHash: string;
+    setState: (value: SetStateInput<QueryState<TData, TError>>) => void;
+    getState: () => QueryState<TData, TError>;
+    subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<QueryState<TData, TError>>) => () => void;
+    getSubscriberCount: () => number;
     /**
-     * Internal data, do not mutate!
+     * A deterministic hash string derived from the query variable.
+     *
+     * Used as the unique identifier for this query instance in the internal cache.
+     *
+     * @remarks
+     * - Structurally identical variables will produce the same hash.
      */
-    metadata: {
-        isInvalidated?: boolean;
-        promise?: Promise<QueryState<TData, TError>> | undefined;
-        promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
-        retryTimeoutId?: number;
-        retryResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
-        garbageCollectionTimeoutId?: number;
-        rollbackData?: TData | undefined;
-    };
+    variableHash: string;
     /**
      * Sets initial data for the query if it has not been initialized.
      *
@@ -344,10 +478,10 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
      * - Should be used if an optimistic update fails.
      */
     rollbackOptimisticUpdate: () => TData;
-    subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<QueryState<TData, TError>>) => () => void;
-    getSubscriberCount: () => number;
-    getState: () => QueryState<TData, TError>;
-    setState: (value: SetStateInput<QueryState<TData, TError>>) => void;
+    /**
+     * Internal data, do not mutate!
+     */
+    internal: Readonly<Internal<TData, TError>>;
 }) & {
     /**
      * Executes all query instances.
@@ -382,3 +516,4 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
      */
     resetAll: () => void;
 };
+export {};

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

@@ -1,8 +1,37 @@
-import { type InitStoreOptions } from "../vanilla.mjs";
+import { type InitStoreOptions, type StoreApi } from "../vanilla.mjs";
 type GoodInputForHash = string | number | boolean | null | Date;
 export type StoreKey = GoodInputForHash | {
     [key: string | number]: StoreKey | StoreKey[];
 };
+type AdditionalStoreApi<TKey> = {
+    /**
+     * The original key used to identify this store instance.\
+     * This value is not hashed and is preserved as-is.
+     */
+    key: TKey;
+    /**
+     * A deterministic hash string derived from {@link key}.
+     *
+     * Used internally as the unique identifier for caching and retrieving store instances.
+     *
+     * @remarks
+     * - Guarantees that structurally identical keys produce the same hash.
+     */
+    keyHash: string;
+    /**
+     * Deletes this store instance from the internal cache.
+     *
+     * @returns `true` if the store was successfully deleted, otherwise `false`.
+     *
+     * @remarks
+     * - If there are active subscribers, the deletion is ignored and `false` is returned.
+     * - When deletion succeeds:
+     *   - The store is removed from the cache.
+     *   - Its state is reset to the initial state.
+     * - Intended for manual cleanup of unused or ephemeral stores.
+     */
+    delete: () => boolean;
+};
 /**
  * Creates a factory for multiple stores identified by a key.
  *
@@ -36,23 +65,12 @@ export type StoreKey = GoodInputForHash | {
  *
  * @see https://floppy-disk.vercel.app/docs/stores
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, {
-    key: TKey;
-    keyHash: string;
-}>) => (key?: TKey) => ((options?: {
+export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, AdditionalStoreApi<TKey>>) => (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").SetStateInput<TState>) => void;
-    getState: () => TState;
-    subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<TState>) => () => void;
-    getSubscriberCount: () => number;
-    key: TKey;
-    keyHash: string;
-};
+}) => TState) & StoreApi<TState> & AdditionalStoreApi<TKey>;
 export {};

package/esm/react.mjs

@@ -102,11 +102,7 @@ const createStores = (initialState, options) => {
       store.key = key;
       store.keyHash = keyHash;
       stores.set(keyHash, store);
-    }
-    const useStore = (options2) => useStoreState(store, options2);
-    return Object.assign(useStore, {
-      ...store,
-      delete: () => {
+      store.delete = () => {
         if (store.getSubscriberCount() > 0) {
           console.warn(
             "Cannot delete store while it still has active subscribers. Unsubscribe all listeners before deleting the store."
@@ -115,8 +111,10 @@ const createStores = (initialState, options) => {
         }
         store.setState(initialState);
         return stores.delete(keyHash);
-      }
-    });
+      };
+    }
+    const useStore = (options2) => useStoreState(store, options2);
+    return Object.assign(useStore, store);
   };
   return getStore;
 };
@@ -156,8 +154,8 @@ const createQuery = (queryFn, options = {}) => {
     onFirstSubscribe: (state, store) => {
       var _a;
       (_a = options.onFirstSubscribe) == null ? void 0 : _a.call(options, state, store);
-      const { metadata, revalidate: revalidate2 } = internals.get(store);
-      clearTimeout(metadata.garbageCollectionTimeoutId);
+      const { internal, revalidate: revalidate2 } = store;
+      clearTimeout(internal.garbageCollectionTimeoutId);
       if (isClient) {
         if (revalidateOnFocus) {
           focusListeners.add(revalidate2);
@@ -178,15 +176,15 @@ const createQuery = (queryFn, options = {}) => {
     onLastUnsubscribe: (state, store) => {
       var _a;
       (_a = options.onLastUnsubscribe) == null ? void 0 : _a.call(options, state, store);
-      const { metadata, revalidate: revalidate2 } = internals.get(store);
-      clearTimeout(metadata.retryTimeoutId);
-      if (metadata.retryResolver) {
+      const { internal, revalidate: revalidate2 } = store;
+      clearTimeout(internal.retryTimeoutId);
+      if (internal.retryResolver) {
         store.setState({ willRetryAt: void 0 });
-        metadata.retryResolver(store.getState());
-        metadata.retryResolver = void 0;
+        internal.retryResolver(store.getState());
+        internal.retryResolver = void 0;
       }
-      metadata.garbageCollectionTimeoutId = setTimeout(() => {
-        if (metadata.promiseResolver || metadata.retryResolver) {
+      internal.garbageCollectionTimeoutId = setTimeout(() => {
+        if (internal.promiseResolver || internal.retryResolver) {
           store.setState(initialState);
         } else {
           stores.delete(variableHash);
@@ -210,14 +208,13 @@ const createQuery = (queryFn, options = {}) => {
       }
     }
   });
-  const internals = /* @__PURE__ */ new WeakMap();
-  const configureInternals = (store, variable) => ({
-    metadata: {},
+  const getApis = (store, variable) => ({
+    internal: {},
     setInitialData: (data, revalidate2 = false) => {
       const state = store.getState();
       if (state.state === "INITIAL" && state.data === void 0) {
-        const { metadata } = internals.get(store);
-        if (revalidate2) metadata.isInvalidated = true;
+        const { internal } = store;
+        if (revalidate2) internal.isInvalidated = true;
         store.setState({
           state: "SUCCESS",
           isSuccess: true,
@@ -235,28 +232,28 @@ const createQuery = (queryFn, options = {}) => {
       return revalidate(store, variable, overwriteOngoingExecution);
     },
     invalidate: (options2) => {
-      const { metadata } = internals.get(store);
-      metadata.isInvalidated = true;
+      const { internal } = store;
+      internal.isInvalidated = true;
       if (store.getSubscriberCount() > 0) {
-        internals.get(store).execute(options2);
+        store.execute(options2);
         return true;
       }
       return false;
     },
     reset: () => {
       var _a, _b;
-      const { metadata } = internals.get(store);
-      clearTimeout(metadata.retryTimeoutId);
-      if (metadata.retryResolver || metadata.promiseResolver) {
+      const { internal } = store;
+      clearTimeout(internal.retryTimeoutId);
+      if (internal.retryResolver || internal.promiseResolver) {
         console.debug(
           "Ongoing query execution was ignored due to reset(). The result will not update the store state."
         );
-        (_a = metadata.promiseResolver) == null ? void 0 : _a.call(metadata, initialState);
-        (_b = metadata.retryResolver) == null ? void 0 : _b.call(metadata, initialState);
-        metadata.promiseResolver = void 0;
-        metadata.retryResolver = void 0;
+        (_a = internal.promiseResolver) == null ? void 0 : _a.call(internal, initialState);
+        (_b = internal.retryResolver) == null ? void 0 : _b.call(internal, initialState);
+        internal.promiseResolver = void 0;
+        internal.retryResolver = void 0;
       }
-      metadata.promise = void 0;
+      internal.promise = void 0;
       store.setState(initialState);
     },
     delete: () => {
@@ -266,35 +263,36 @@ const createQuery = (queryFn, options = {}) => {
         );
         return false;
       }
-      internals.get(store).reset();
+      store.reset();
       return stores.delete(store.variableHash);
     },
     optimisticUpdate: (optimisticData) => {
-      const { metadata, revalidate: revalidate2, rollbackOptimisticUpdate } = internals.get(store);
-      metadata.rollbackData = store.getState().data;
+      const { internal, revalidate: revalidate2, rollbackOptimisticUpdate } = store;
+      internal.rollbackData = store.getState().data;
       store.setState({ data: optimisticData });
       return { revalidate: revalidate2, rollback: rollbackOptimisticUpdate };
     },
     rollbackOptimisticUpdate: () => {
-      const { metadata } = internals.get(store);
-      store.setState({ data: metadata.rollbackData });
-      return metadata.rollbackData;
+      const { internal } = store;
+      store.setState({ data: internal.rollbackData });
+      return internal.rollbackData;
     }
   });
   const execute = async (store, variable, overwriteOngoingExecution = false) => {
-    const { metadata } = internals.get(store);
-    if (!overwriteOngoingExecution && metadata.promise) return metadata.promise;
-    clearTimeout(metadata.retryTimeoutId);
+    const { internal: _internal } = store;
+    const internal = _internal;
+    if (!overwriteOngoingExecution && internal.promise) return internal.promise;
+    clearTimeout(internal.retryTimeoutId);
     const createPromise = () => {
       const promise = new Promise((resolve) => {
-        metadata.promiseResolver = resolve;
+        internal.promiseResolver = resolve;
         const stateBeforeExecute = store.getState();
         store.setState({
           isPending: true,
           isRevalidating: stateBeforeExecute.state === "SUCCESS",
           willRetryAt: void 0,
-          isRetrying: !!metadata.retryResolver,
-          retryCount: metadata.retryResolver ? stateBeforeExecute.retryCount + 1 : 0
+          isRetrying: !!internal.retryResolver,
+          retryCount: internal.retryResolver ? stateBeforeExecute.retryCount + 1 : 0
         });
         queryFn(variable, stateBeforeExecute, store.variableHash).then((data) => {
           var _a;
@@ -303,8 +301,8 @@ const createQuery = (queryFn, options = {}) => {
               "Query function returned undefined. Successful responses must not be undefined."
             );
           }
-          if (!metadata.promiseResolver) return;
-          if (promise !== metadata.promise) return resolve(metadata.promise);
+          if (!internal.promiseResolver) return;
+          if (promise !== internal.promise) return resolve(internal.promise);
           const now = Date.now();
           store.setState({
             isPending: false,
@@ -320,17 +318,17 @@ const createQuery = (queryFn, options = {}) => {
             error: void 0,
             errorUpdatedAt: void 0
           });
-          metadata.isInvalidated = false;
-          metadata.rollbackData = data;
+          internal.isInvalidated = false;
+          internal.rollbackData = data;
           resolve(store.getState());
-          (_a = metadata.retryResolver) == null ? void 0 : _a.call(metadata, store.getState());
-          metadata.retryResolver = void 0;
+          (_a = internal.retryResolver) == null ? void 0 : _a.call(internal, store.getState());
+          internal.retryResolver = void 0;
           onSuccess(data, variable, stateBeforeExecute);
           onSettled(variable, stateBeforeExecute);
         }).catch((error) => {
           var _a;
-          if (!metadata.promiseResolver && !metadata.retryResolver) return;
-          if (promise !== metadata.promise) return resolve(metadata.promise);
+          if (!internal.promiseResolver && !internal.retryResolver) return;
+          if (promise !== internal.promise) return resolve(internal.promise);
           const nextState = {
             ...store.getState(),
             isPending: false,
@@ -340,8 +338,8 @@ const createQuery = (queryFn, options = {}) => {
           const [shouldRetry, retryDelay] = shouldRetryFn(error, nextState);
           const hasSubscriber = store.getSubscriberCount() > 0;
           if (shouldRetry && hasSubscriber) {
-            metadata.retryResolver = resolve;
-            metadata.retryTimeoutId = setTimeout(createPromise, retryDelay);
+            internal.retryResolver = resolve;
+            internal.retryTimeoutId = setTimeout(createPromise, retryDelay);
             store.setState({
               isPending: false,
               isRevalidating: false,
@@ -366,31 +364,31 @@ const createQuery = (queryFn, options = {}) => {
             });
             const state = store.getState();
             resolve(state);
-            (_a = metadata.retryResolver) == null ? void 0 : _a.call(metadata, state);
-            metadata.retryResolver = void 0;
+            (_a = internal.retryResolver) == null ? void 0 : _a.call(internal, state);
+            internal.retryResolver = void 0;
             if (onError) onError(error, variable, stateBeforeExecute);
             else console.error(state);
             onSettled(variable, stateBeforeExecute);
           }
         }).finally(() => {
-          if (metadata.promise === promise) {
-            metadata.promise = void 0;
-            metadata.promiseResolver = void 0;
+          if (internal.promise === promise) {
+            internal.promise = void 0;
+            internal.promiseResolver = void 0;
           }
         });
       });
-      metadata.promise = promise;
+      internal.promise = promise;
       return promise;
     };
     return createPromise();
   };
   const revalidate = async (store, variable, overwriteOngoingExecution) => {
-    const { metadata } = internals.get(store);
-    if (!overwriteOngoingExecution && metadata.promise) return metadata.promise;
+    const { internal } = store;
+    if (!overwriteOngoingExecution && internal.promise) return internal.promise;
     const state = store.getState();
     if (state.dataUpdatedAt) {
       const isFresh = state.dataUpdatedAt + staleTime > Date.now();
-      if (isFresh && !metadata.isInvalidated) return state;
+      if (isFresh && !internal.isInvalidated) return state;
     }
     return execute(store, variable, overwriteOngoingExecution);
   };
@@ -407,7 +405,16 @@ const createQuery = (queryFn, options = {}) => {
       );
       store.variableHash = variableHash;
       stores.set(variableHash, store);
-      internals.set(store, configureInternals(store, variable));
+      const apis = getApis(store, variable);
+      store.setInitialData = apis.setInitialData;
+      store.execute = apis.execute;
+      store.revalidate = apis.revalidate;
+      store.invalidate = apis.invalidate;
+      store.reset = apis.reset;
+      store.delete = apis.delete;
+      store.optimisticUpdate = apis.optimisticUpdate;
+      store.rollbackOptimisticUpdate = apis.rollbackOptimisticUpdate;
+      store.internal = apis.internal;
     }
     const useStore = (options2 = {}) => {
       const {
@@ -475,15 +482,11 @@ const createQuery = (queryFn, options = {}) => {
       return trackedState;
     };
     return Object.assign(useStore, {
-      subscribe: store.subscribe,
-      getSubscriberCount: store.getSubscriberCount,
-      getState: store.getState,
+      ...store,
       setState: (value) => {
         console.debug("Manual setState (not via provided actions) on query store");
         store.setState(value);
-      },
-      ...internals.get(store),
-      variableHash
+      }
     });
   };
   return Object.assign(getStore, {
@@ -494,7 +497,7 @@ const createQuery = (queryFn, options = {}) => {
      * - Useful for bulk refetching.
      */
     executeAll: (options2) => {
-      stores.forEach((store) => internals.get(store).execute(options2));
+      stores.forEach((store) => store.execute(options2));
     },
     /**
      * Revalidates all query instances.
@@ -503,7 +506,7 @@ const createQuery = (queryFn, options = {}) => {
      * - Only re-fetches stale queries.
      */
     revalidateAll: (options2) => {
-      stores.forEach((store) => internals.get(store).revalidate(options2));
+      stores.forEach((store) => store.revalidate(options2));
     },
     /**
      * Invalidates all query instances.
@@ -513,13 +516,13 @@ const createQuery = (queryFn, options = {}) => {
      * - Invalidated queries bypass `staleTime` until successfully executed again.
      */
     invalidateAll: (options2) => {
-      stores.forEach((store) => internals.get(store).invalidate(options2));
+      stores.forEach((store) => store.invalidate(options2));
     },
     /**
      * Resets all query instances.
      */
     resetAll: () => {
-      stores.forEach((store) => internals.get(store).reset());
+      stores.forEach((store) => store.reset());
     }
   });
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "floppy-disk",
   "description": "Lightweight unified state management for sync and async data.",
   "private": false,
-  "version": "3.6.1",
+  "version": "3.7.0-beta.1",
   "keywords": [
     "utilities",
     "store",

package/react/create-mutation.d.ts

@@ -44,17 +44,7 @@ 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;
-};
+export declare const INITIAL_STATE: MutationState<any, any, any>;
 /**
  * Configuration options for a mutation.
  *

package/react/create-query.d.ts

@@ -63,15 +63,149 @@ export type QueryState<TData, TError> = {
     error: TError;
     errorUpdatedAt: number;
 });
+type Internal<TData, TError> = {
+    isInvalidated?: boolean;
+    promise?: Promise<QueryState<TData, TError>> | undefined;
+    promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
+    retryTimeoutId?: number;
+    retryResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
+    garbageCollectionTimeoutId?: number;
+    rollbackData?: TData | undefined;
+};
+type AdditionalStoreApi<TData, TError> = {
+    /**
+     * A deterministic hash string derived from the query variable.
+     *
+     * Used as the unique identifier for this query instance in the internal cache.
+     *
+     * @remarks
+     * - Structurally identical variables will produce the same hash.
+     */
+    variableHash: string;
+    /**
+     * Sets initial data for the query if it has not been initialized.
+     *
+     * @param data - Initial data
+     * @param revalidate - Whether to mark the data as invalidated (will trigger revalidation)
+     *
+     * @returns `true` if the data was set, `false` otherwise
+     *
+     * @remarks
+     * - Only applies when the query is in the `INITIAL` state.
+     * - Useful for hydration or preloaded data.
+     */
+    setInitialData: (data: TData, revalidate?: boolean) => boolean;
+    /**
+     * Executes the query function.
+     *
+     * @param options - Execution options
+     * @param options.overwriteOngoingExecution - Whether to start a new execution instead of reusing an ongoing one (default: `true`)
+     *
+     * @returns A promise resolving to the latest query state
+     *
+     * @remarks
+     * - By default, each call **starts a new execution** even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     * - Handles:
+     *   - Pending state
+     *   - Success state
+     *   - Error state
+     *   - Retry logic
+     */
+    execute: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Re-executes the query if needed based on freshness or invalidation.
+     *
+     * @param options - Revalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns The current state if still fresh, otherwise a promise of the new state
+     *
+     * @remarks
+     * - Skips execution if data is still fresh (`staleTime`) **AND** the query has not been invalidated.
+     * - If execution is not skipped, by default it will start a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    revalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => Promise<QueryState<TData, TError>>;
+    /**
+     * Marks the query as invalidated and optionally triggers re-execution.
+     *
+     * @param options - Invalidation options
+     * @param options.overwriteOngoingExecution - Whether to overwrite an ongoing execution (default: `true`)
+     *
+     * @returns `true` if execution was triggered, `false` otherwise
+     *
+     * @remarks
+     * - Invalidated queries are treated as stale regardless of `staleTime`.
+     * - The next `revalidate` will always execute until a successful result clears the invalidation.
+     * - If there are active subscribers: Execution is triggered immediately.
+     * - Otherwise: The query remains invalidated and will execute on the next revalidation.
+     * - By default, starts a new execution even if one is already in progress.
+     * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
+     */
+    invalidate: (options?: {
+        overwriteOngoingExecution?: boolean;
+    }) => boolean;
+    /**
+     * Resets the query state to its initial state.
+     *
+     * @remarks
+     * - Cancels retry logic and ignores any ongoing execution results.
+     */
+    reset: () => void;
+    /**
+     * Deletes the query store for the current variable.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers.
+     */
+    delete: () => boolean;
+    /**
+     * Performs an optimistic update on the query data.
+     *
+     * @param data - Optimistic data to set
+     *
+     * @returns Controls for managing the optimistic update
+     *
+     * @remarks
+     * - Temporarily replaces the current data.
+     * - Stores previous data for rollback.
+     * - Commonly used with mutations for instant UI updates.
+     *
+     * @example
+     * const { rollback, revalidate } = query.optimisticUpdate(newData);
+     */
+    optimisticUpdate: (data: TData) => {
+        revalidate: () => Promise<QueryState<TData, TError>>;
+        rollback: () => TData;
+    };
+    /**
+     * Restores the data before the last optimistic update.
+     *
+     * @returns The restored data
+     *
+     * @remarks
+     * - Should be used if an optimistic update fails.
+     */
+    rollbackOptimisticUpdate: () => TData;
+    /**
+     * Internal data, do not mutate!
+     */
+    internal: Readonly<Internal<TData, TError>>;
+};
 /**
  * Configuration options for a query.
  *
  * @remarks
  * Controls caching, retry behavior, lifecycle, and side effects of an async operation.
  */
-export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, {
-    variableHash: string;
-}> & {
+export type QueryOptions<TData, TVariable extends StoreKey, TError = Error> = InitStoreOptions<QueryState<TData, TError>, AdditionalStoreApi<TData, TError>> & {
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
@@ -219,19 +353,19 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
     initialData?: never;
     initialDataIsStale?: never;
 })) => QueryState<TData, TError>) & {
-    variableHash: string;
+    setState: (value: SetStateInput<QueryState<TData, TError>>) => void;
+    getState: () => QueryState<TData, TError>;
+    subscribe: (subscriber: import("../vanilla.ts").Subscriber<QueryState<TData, TError>>) => () => void;
+    getSubscriberCount: () => number;
     /**
-     * Internal data, do not mutate!
+     * A deterministic hash string derived from the query variable.
+     *
+     * Used as the unique identifier for this query instance in the internal cache.
+     *
+     * @remarks
+     * - Structurally identical variables will produce the same hash.
      */
-    metadata: {
-        isInvalidated?: boolean;
-        promise?: Promise<QueryState<TData, TError>> | undefined;
-        promiseResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
-        retryTimeoutId?: number;
-        retryResolver?: ((value: QueryState<TData, TError> | PromiseLike<QueryState<TData, TError>>) => void) | undefined;
-        garbageCollectionTimeoutId?: number;
-        rollbackData?: TData | undefined;
-    };
+    variableHash: string;
     /**
      * Sets initial data for the query if it has not been initialized.
      *
@@ -344,10 +478,10 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
      * - Should be used if an optimistic update fails.
      */
     rollbackOptimisticUpdate: () => TData;
-    subscribe: (subscriber: import("../vanilla.ts").Subscriber<QueryState<TData, TError>>) => () => void;
-    getSubscriberCount: () => number;
-    getState: () => QueryState<TData, TError>;
-    setState: (value: SetStateInput<QueryState<TData, TError>>) => void;
+    /**
+     * Internal data, do not mutate!
+     */
+    internal: Readonly<Internal<TData, TError>>;
 }) & {
     /**
      * Executes all query instances.
@@ -382,3 +516,4 @@ export declare const createQuery: <TData, TVariable extends StoreKey = never, TE
      */
     resetAll: () => void;
 };
+export {};

package/react/create-stores.d.ts

@@ -1,8 +1,37 @@
-import { type InitStoreOptions } from "../vanilla.ts";
+import { type InitStoreOptions, type StoreApi } from "../vanilla.ts";
 type GoodInputForHash = string | number | boolean | null | Date;
 export type StoreKey = GoodInputForHash | {
     [key: string | number]: StoreKey | StoreKey[];
 };
+type AdditionalStoreApi<TKey> = {
+    /**
+     * The original key used to identify this store instance.\
+     * This value is not hashed and is preserved as-is.
+     */
+    key: TKey;
+    /**
+     * A deterministic hash string derived from {@link key}.
+     *
+     * Used internally as the unique identifier for caching and retrieving store instances.
+     *
+     * @remarks
+     * - Guarantees that structurally identical keys produce the same hash.
+     */
+    keyHash: string;
+    /**
+     * Deletes this store instance from the internal cache.
+     *
+     * @returns `true` if the store was successfully deleted, otherwise `false`.
+     *
+     * @remarks
+     * - If there are active subscribers, the deletion is ignored and `false` is returned.
+     * - When deletion succeeds:
+     *   - The store is removed from the cache.
+     *   - Its state is reset to the initial state.
+     * - Intended for manual cleanup of unused or ephemeral stores.
+     */
+    delete: () => boolean;
+};
 /**
  * Creates a factory for multiple stores identified by a key.
  *
@@ -36,23 +65,12 @@ export type StoreKey = GoodInputForHash | {
  *
  * @see https://floppy-disk.vercel.app/docs/stores
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, {
-    key: TKey;
-    keyHash: string;
-}>) => (key?: TKey) => ((options?: {
+export declare const createStores: <TState extends Record<string, any>, TKey extends StoreKey>(initialState: TState, options?: InitStoreOptions<TState, AdditionalStoreApi<TKey>>) => (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").SetStateInput<TState>) => void;
-    getState: () => TState;
-    subscribe: (subscriber: import("../vanilla.ts").Subscriber<TState>) => () => void;
-    getSubscriberCount: () => number;
-    key: TKey;
-    keyHash: string;
-};
+}) => TState) & StoreApi<TState> & AdditionalStoreApi<TKey>;
 export {};

package/react.js

@@ -104,11 +104,7 @@ const createStores = (initialState, options) => {
       store.key = key;
       store.keyHash = keyHash;
       stores.set(keyHash, store);
-    }
-    const useStore = (options2) => useStoreState(store, options2);
-    return Object.assign(useStore, {
-      ...store,
-      delete: () => {
+      store.delete = () => {
         if (store.getSubscriberCount() > 0) {
           console.warn(
             "Cannot delete store while it still has active subscribers. Unsubscribe all listeners before deleting the store."
@@ -117,8 +113,10 @@ const createStores = (initialState, options) => {
         }
         store.setState(initialState);
         return stores.delete(keyHash);
-      }
-    });
+      };
+    }
+    const useStore = (options2) => useStoreState(store, options2);
+    return Object.assign(useStore, store);
   };
   return getStore;
 };
@@ -158,8 +156,8 @@ const createQuery = (queryFn, options = {}) => {
     onFirstSubscribe: (state, store) => {
       var _a;
       (_a = options.onFirstSubscribe) == null ? void 0 : _a.call(options, state, store);
-      const { metadata, revalidate: revalidate2 } = internals.get(store);
-      clearTimeout(metadata.garbageCollectionTimeoutId);
+      const { internal, revalidate: revalidate2 } = store;
+      clearTimeout(internal.garbageCollectionTimeoutId);
       if (vanilla.isClient) {
         if (revalidateOnFocus) {
           focusListeners.add(revalidate2);
@@ -180,15 +178,15 @@ const createQuery = (queryFn, options = {}) => {
     onLastUnsubscribe: (state, store) => {
       var _a;
       (_a = options.onLastUnsubscribe) == null ? void 0 : _a.call(options, state, store);
-      const { metadata, revalidate: revalidate2 } = internals.get(store);
-      clearTimeout(metadata.retryTimeoutId);
-      if (metadata.retryResolver) {
+      const { internal, revalidate: revalidate2 } = store;
+      clearTimeout(internal.retryTimeoutId);
+      if (internal.retryResolver) {
         store.setState({ willRetryAt: void 0 });
-        metadata.retryResolver(store.getState());
-        metadata.retryResolver = void 0;
+        internal.retryResolver(store.getState());
+        internal.retryResolver = void 0;
       }
-      metadata.garbageCollectionTimeoutId = setTimeout(() => {
-        if (metadata.promiseResolver || metadata.retryResolver) {
+      internal.garbageCollectionTimeoutId = setTimeout(() => {
+        if (internal.promiseResolver || internal.retryResolver) {
           store.setState(initialState);
         } else {
           stores.delete(variableHash);
@@ -212,14 +210,13 @@ const createQuery = (queryFn, options = {}) => {
       }
     }
   });
-  const internals = /* @__PURE__ */ new WeakMap();
-  const configureInternals = (store, variable) => ({
-    metadata: {},
+  const getApis = (store, variable) => ({
+    internal: {},
     setInitialData: (data, revalidate2 = false) => {
       const state = store.getState();
       if (state.state === "INITIAL" && state.data === void 0) {
-        const { metadata } = internals.get(store);
-        if (revalidate2) metadata.isInvalidated = true;
+        const { internal } = store;
+        if (revalidate2) internal.isInvalidated = true;
         store.setState({
           state: "SUCCESS",
           isSuccess: true,
@@ -237,28 +234,28 @@ const createQuery = (queryFn, options = {}) => {
       return revalidate(store, variable, overwriteOngoingExecution);
     },
     invalidate: (options2) => {
-      const { metadata } = internals.get(store);
-      metadata.isInvalidated = true;
+      const { internal } = store;
+      internal.isInvalidated = true;
       if (store.getSubscriberCount() > 0) {
-        internals.get(store).execute(options2);
+        store.execute(options2);
         return true;
       }
       return false;
     },
     reset: () => {
       var _a, _b;
-      const { metadata } = internals.get(store);
-      clearTimeout(metadata.retryTimeoutId);
-      if (metadata.retryResolver || metadata.promiseResolver) {
+      const { internal } = store;
+      clearTimeout(internal.retryTimeoutId);
+      if (internal.retryResolver || internal.promiseResolver) {
         console.debug(
           "Ongoing query execution was ignored due to reset(). The result will not update the store state."
         );
-        (_a = metadata.promiseResolver) == null ? void 0 : _a.call(metadata, initialState);
-        (_b = metadata.retryResolver) == null ? void 0 : _b.call(metadata, initialState);
-        metadata.promiseResolver = void 0;
-        metadata.retryResolver = void 0;
+        (_a = internal.promiseResolver) == null ? void 0 : _a.call(internal, initialState);
+        (_b = internal.retryResolver) == null ? void 0 : _b.call(internal, initialState);
+        internal.promiseResolver = void 0;
+        internal.retryResolver = void 0;
       }
-      metadata.promise = void 0;
+      internal.promise = void 0;
       store.setState(initialState);
     },
     delete: () => {
@@ -268,35 +265,36 @@ const createQuery = (queryFn, options = {}) => {
         );
         return false;
       }
-      internals.get(store).reset();
+      store.reset();
       return stores.delete(store.variableHash);
     },
     optimisticUpdate: (optimisticData) => {
-      const { metadata, revalidate: revalidate2, rollbackOptimisticUpdate } = internals.get(store);
-      metadata.rollbackData = store.getState().data;
+      const { internal, revalidate: revalidate2, rollbackOptimisticUpdate } = store;
+      internal.rollbackData = store.getState().data;
       store.setState({ data: optimisticData });
       return { revalidate: revalidate2, rollback: rollbackOptimisticUpdate };
     },
     rollbackOptimisticUpdate: () => {
-      const { metadata } = internals.get(store);
-      store.setState({ data: metadata.rollbackData });
-      return metadata.rollbackData;
+      const { internal } = store;
+      store.setState({ data: internal.rollbackData });
+      return internal.rollbackData;
     }
   });
   const execute = async (store, variable, overwriteOngoingExecution = false) => {
-    const { metadata } = internals.get(store);
-    if (!overwriteOngoingExecution && metadata.promise) return metadata.promise;
-    clearTimeout(metadata.retryTimeoutId);
+    const { internal: _internal } = store;
+    const internal = _internal;
+    if (!overwriteOngoingExecution && internal.promise) return internal.promise;
+    clearTimeout(internal.retryTimeoutId);
     const createPromise = () => {
       const promise = new Promise((resolve) => {
-        metadata.promiseResolver = resolve;
+        internal.promiseResolver = resolve;
         const stateBeforeExecute = store.getState();
         store.setState({
           isPending: true,
           isRevalidating: stateBeforeExecute.state === "SUCCESS",
           willRetryAt: void 0,
-          isRetrying: !!metadata.retryResolver,
-          retryCount: metadata.retryResolver ? stateBeforeExecute.retryCount + 1 : 0
+          isRetrying: !!internal.retryResolver,
+          retryCount: internal.retryResolver ? stateBeforeExecute.retryCount + 1 : 0
         });
         queryFn(variable, stateBeforeExecute, store.variableHash).then((data) => {
           var _a;
@@ -305,8 +303,8 @@ const createQuery = (queryFn, options = {}) => {
               "Query function returned undefined. Successful responses must not be undefined."
             );
           }
-          if (!metadata.promiseResolver) return;
-          if (promise !== metadata.promise) return resolve(metadata.promise);
+          if (!internal.promiseResolver) return;
+          if (promise !== internal.promise) return resolve(internal.promise);
           const now = Date.now();
           store.setState({
             isPending: false,
@@ -322,17 +320,17 @@ const createQuery = (queryFn, options = {}) => {
             error: void 0,
             errorUpdatedAt: void 0
           });
-          metadata.isInvalidated = false;
-          metadata.rollbackData = data;
+          internal.isInvalidated = false;
+          internal.rollbackData = data;
           resolve(store.getState());
-          (_a = metadata.retryResolver) == null ? void 0 : _a.call(metadata, store.getState());
-          metadata.retryResolver = void 0;
+          (_a = internal.retryResolver) == null ? void 0 : _a.call(internal, store.getState());
+          internal.retryResolver = void 0;
           onSuccess(data, variable, stateBeforeExecute);
           onSettled(variable, stateBeforeExecute);
         }).catch((error) => {
           var _a;
-          if (!metadata.promiseResolver && !metadata.retryResolver) return;
-          if (promise !== metadata.promise) return resolve(metadata.promise);
+          if (!internal.promiseResolver && !internal.retryResolver) return;
+          if (promise !== internal.promise) return resolve(internal.promise);
           const nextState = {
             ...store.getState(),
             isPending: false,
@@ -342,8 +340,8 @@ const createQuery = (queryFn, options = {}) => {
           const [shouldRetry, retryDelay] = shouldRetryFn(error, nextState);
           const hasSubscriber = store.getSubscriberCount() > 0;
           if (shouldRetry && hasSubscriber) {
-            metadata.retryResolver = resolve;
-            metadata.retryTimeoutId = setTimeout(createPromise, retryDelay);
+            internal.retryResolver = resolve;
+            internal.retryTimeoutId = setTimeout(createPromise, retryDelay);
             store.setState({
               isPending: false,
               isRevalidating: false,
@@ -368,31 +366,31 @@ const createQuery = (queryFn, options = {}) => {
             });
             const state = store.getState();
             resolve(state);
-            (_a = metadata.retryResolver) == null ? void 0 : _a.call(metadata, state);
-            metadata.retryResolver = void 0;
+            (_a = internal.retryResolver) == null ? void 0 : _a.call(internal, state);
+            internal.retryResolver = void 0;
             if (onError) onError(error, variable, stateBeforeExecute);
             else console.error(state);
             onSettled(variable, stateBeforeExecute);
           }
         }).finally(() => {
-          if (metadata.promise === promise) {
-            metadata.promise = void 0;
-            metadata.promiseResolver = void 0;
+          if (internal.promise === promise) {
+            internal.promise = void 0;
+            internal.promiseResolver = void 0;
           }
         });
       });
-      metadata.promise = promise;
+      internal.promise = promise;
       return promise;
     };
     return createPromise();
   };
   const revalidate = async (store, variable, overwriteOngoingExecution) => {
-    const { metadata } = internals.get(store);
-    if (!overwriteOngoingExecution && metadata.promise) return metadata.promise;
+    const { internal } = store;
+    if (!overwriteOngoingExecution && internal.promise) return internal.promise;
     const state = store.getState();
     if (state.dataUpdatedAt) {
       const isFresh = state.dataUpdatedAt + staleTime > Date.now();
-      if (isFresh && !metadata.isInvalidated) return state;
+      if (isFresh && !internal.isInvalidated) return state;
     }
     return execute(store, variable, overwriteOngoingExecution);
   };
@@ -409,7 +407,16 @@ const createQuery = (queryFn, options = {}) => {
       );
       store.variableHash = variableHash;
       stores.set(variableHash, store);
-      internals.set(store, configureInternals(store, variable));
+      const apis = getApis(store, variable);
+      store.setInitialData = apis.setInitialData;
+      store.execute = apis.execute;
+      store.revalidate = apis.revalidate;
+      store.invalidate = apis.invalidate;
+      store.reset = apis.reset;
+      store.delete = apis.delete;
+      store.optimisticUpdate = apis.optimisticUpdate;
+      store.rollbackOptimisticUpdate = apis.rollbackOptimisticUpdate;
+      store.internal = apis.internal;
     }
     const useStore = (options2 = {}) => {
       const {
@@ -477,15 +484,11 @@ const createQuery = (queryFn, options = {}) => {
       return trackedState;
     };
     return Object.assign(useStore, {
-      subscribe: store.subscribe,
-      getSubscriberCount: store.getSubscriberCount,
-      getState: store.getState,
+      ...store,
       setState: (value) => {
         console.debug("Manual setState (not via provided actions) on query store");
         store.setState(value);
-      },
-      ...internals.get(store),
-      variableHash
+      }
     });
   };
   return Object.assign(getStore, {
@@ -496,7 +499,7 @@ const createQuery = (queryFn, options = {}) => {
      * - Useful for bulk refetching.
      */
     executeAll: (options2) => {
-      stores.forEach((store) => internals.get(store).execute(options2));
+      stores.forEach((store) => store.execute(options2));
     },
     /**
      * Revalidates all query instances.
@@ -505,7 +508,7 @@ const createQuery = (queryFn, options = {}) => {
      * - Only re-fetches stale queries.
      */
     revalidateAll: (options2) => {
-      stores.forEach((store) => internals.get(store).revalidate(options2));
+      stores.forEach((store) => store.revalidate(options2));
     },
     /**
      * Invalidates all query instances.
@@ -515,13 +518,13 @@ const createQuery = (queryFn, options = {}) => {
      * - Invalidated queries bypass `staleTime` until successfully executed again.
      */
     invalidateAll: (options2) => {
-      stores.forEach((store) => internals.get(store).invalidate(options2));
+      stores.forEach((store) => store.invalidate(options2));
     },
     /**
      * Resets all query instances.
      */
     resetAll: () => {
-      stores.forEach((store) => internals.get(store).reset());
+      stores.forEach((store) => store.reset());
     }
   });
 };