floppy-disk 2.2.0-beta.3 → 2.3.0-beta.1

package/README.md

@@ -661,10 +661,11 @@ function PokemonListPage() {
 **Note:**
 
 - The default stale time is 3 seconds.
-- The default error retry attempt is 1 time, and retry delay is 3 seconds.
-- The default reactivity of a query is `(s) => [s.data, s.error]`.  
-  (For paginated: `(s) => [s.data, s.error, s.isWaitingNextPage, s.hasNextPage]`)
-- You can change the `defaultDeps` on `createQuery` options.
+- 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.
 
 ### Mutation
 
@@ -724,6 +725,7 @@ function SaveProduct() {
 
         const { revert, invalidate } = useProductQuery.optimisticUpdate({
           key: { id: payload.id },
+          response: payload,
         });
 
         mutate(payload).then(({ response, error }) => {
@@ -795,3 +797,11 @@ function PokemonsPage() {
   return <div>...</div>;
 }
 ```
+
+<br>
+
+---
+
+<p align="center">
+  View official documentation on <a href="https://floppy-disk.vercel.app/">floppy-disk.vercel.app</a>
+</p>

package/esm/preact/create-mutation.d.ts

@@ -12,7 +12,9 @@ export type MutationState<TVar, TResponse = any, TError = unknown> = {
     error: TError | null;
     errorUpdatedAt: number | null;
     /**
-     * Mutate function is a promise that will always resolve.
+     * Mutate function.
+     *
+     * @returns Promise that will always get resolved.
      */
     mutate: TVar extends undefined ? () => Promise<{
         response?: TResponse;

package/esm/preact/create-query.d.ts

@@ -14,8 +14,10 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     fetch: () => void;
     /**
      * Will be called even if the data is still fresh (not stale).
+     *
+     * @returns Promise that will always get resolved.
      */
-    forceFetch: () => void;
+    forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError>>;
     /**
      * Fetch next page if has next page.
      *
@@ -187,7 +189,7 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
      * IMPORTANT NOTE: Put this on the root component or parent component, before any component subscribed!
      */
     setInitialResponse: (options: {
-        key?: TKey;
+        key?: TKey | null;
         response: TResponse;
         skipRevalidation?: boolean;
     }) => void;
@@ -221,5 +223,9 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
         revert: () => void;
         invalidate: () => void;
     };
+    /**
+     * Use query with suspense mode.
+     */
+    suspend: (key?: TKey | null) => QueryState<TKey, TResponse, TData, TError>;
 };
 export declare const createQuery: <TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown>(queryFn: (key: TKey, state: QueryState<TKey, TResponse, TData, TError>) => Promise<TResponse>, options?: CreateQueryOptions<TKey, TResponse, TData, TError>) => UseQuery<TKey, TResponse, TData, TError>;

package/esm/preact/create-query.js

@@ -56,7 +56,7 @@ export const createQuery = (queryFn, options = {}) => {
             const delay = (typeof retryDelay === 'function' ? retryDelay(error, prevState) : retryDelay) || 0;
             return { shouldRetry, delay };
         };
-        const forceFetch = () => {
+        const forceFetch = () => new Promise((resolve) => {
             const responseAllPages = [];
             const newPageParams = [undefined];
             let pageParam = undefined;
@@ -114,6 +114,7 @@ export const createQuery = (queryFn, options = {}) => {
                         hasNextPage: hasValue(newPageParam),
                     });
                     onSuccess(response, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .catch((error) => {
                     const prevState = get();
@@ -147,20 +148,21 @@ export const createQuery = (queryFn, options = {}) => {
                             pageParam,
                             hasNextPage: hasValue(pageParam),
                         });
-                    if (shouldRetry) {
+                    if (shouldRetry && typeof window !== 'undefined') {
                         retryTimeoutId.set(keyHash, window.setTimeout(() => {
                             set({ retryCount: prevState.retryCount + 1 });
                             callQuery();
                         }, delay));
                     }
                     onError(error, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .finally(() => {
                     onSettled(stateBeforeCallQuery);
                 });
             };
             callQuery();
-        };
+        });
         const fetch = () => {
             const { responseUpdatedAt } = get();
             const isStale = Date.now() > Number(responseUpdatedAt) + staleTime;
@@ -341,5 +343,14 @@ export const createQuery = (queryFn, options = {}) => {
         const invalidate = () => useQuery.invalidateSpecificKey(key);
         return { revert, invalidate };
     };
+    useQuery.suspend = (key) => {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(key);
+        if (state.isLoading)
+            throw state.forceFetch();
+        if (state.isError)
+            throw state.error;
+        return state;
+    };
     return useQuery;
 };

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

@@ -12,7 +12,9 @@ export type MutationState<TVar, TResponse = any, TError = unknown> = {
     error: TError | null;
     errorUpdatedAt: number | null;
     /**
-     * Mutate function is a promise that will always resolve.
+     * Mutate function.
+     *
+     * @returns Promise that will always get resolved.
      */
     mutate: TVar extends undefined ? () => Promise<{
         response?: TResponse;

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

@@ -14,8 +14,10 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     fetch: () => void;
     /**
      * Will be called even if the data is still fresh (not stale).
+     *
+     * @returns Promise that will always get resolved.
      */
-    forceFetch: () => void;
+    forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError>>;
     /**
      * Fetch next page if has next page.
      *
@@ -187,7 +189,7 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
      * IMPORTANT NOTE: Put this on the root component or parent component, before any component subscribed!
      */
     setInitialResponse: (options: {
-        key?: TKey;
+        key?: TKey | null;
         response: TResponse;
         skipRevalidation?: boolean;
     }) => void;
@@ -221,5 +223,9 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
         revert: () => void;
         invalidate: () => void;
     };
+    /**
+     * Use query with suspense mode.
+     */
+    suspend: (key?: TKey | null) => QueryState<TKey, TResponse, TData, TError>;
 };
 export declare const createQuery: <TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown>(queryFn: (key: TKey, state: QueryState<TKey, TResponse, TData, TError>) => Promise<TResponse>, options?: CreateQueryOptions<TKey, TResponse, TData, TError>) => UseQuery<TKey, TResponse, TData, TError>;

package/esm/react/create-query.js

@@ -56,7 +56,7 @@ export const createQuery = (queryFn, options = {}) => {
             const delay = (typeof retryDelay === 'function' ? retryDelay(error, prevState) : retryDelay) || 0;
             return { shouldRetry, delay };
         };
-        const forceFetch = () => {
+        const forceFetch = () => new Promise((resolve) => {
             const responseAllPages = [];
             const newPageParams = [undefined];
             let pageParam = undefined;
@@ -114,6 +114,7 @@ export const createQuery = (queryFn, options = {}) => {
                         hasNextPage: hasValue(newPageParam),
                     });
                     onSuccess(response, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .catch((error) => {
                     const prevState = get();
@@ -147,20 +148,21 @@ export const createQuery = (queryFn, options = {}) => {
                             pageParam,
                             hasNextPage: hasValue(pageParam),
                         });
-                    if (shouldRetry) {
+                    if (shouldRetry && typeof window !== 'undefined') {
                         retryTimeoutId.set(keyHash, window.setTimeout(() => {
                             set({ retryCount: prevState.retryCount + 1 });
                             callQuery();
                         }, delay));
                     }
                     onError(error, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .finally(() => {
                     onSettled(stateBeforeCallQuery);
                 });
             };
             callQuery();
-        };
+        });
         const fetch = () => {
             const { responseUpdatedAt } = get();
             const isStale = Date.now() > Number(responseUpdatedAt) + staleTime;
@@ -341,5 +343,14 @@ export const createQuery = (queryFn, options = {}) => {
         const invalidate = () => useQuery.invalidateSpecificKey(key);
         return { revert, invalidate };
     };
+    useQuery.suspend = (key) => {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(key);
+        if (state.isLoading)
+            throw state.forceFetch();
+        if (state.isError)
+            throw state.error;
+        return state;
+    };
     return useQuery;
 };

package/lib/preact/create-mutation.d.ts

@@ -12,7 +12,9 @@ export type MutationState<TVar, TResponse = any, TError = unknown> = {
     error: TError | null;
     errorUpdatedAt: number | null;
     /**
-     * Mutate function is a promise that will always resolve.
+     * Mutate function.
+     *
+     * @returns Promise that will always get resolved.
      */
     mutate: TVar extends undefined ? () => Promise<{
         response?: TResponse;

package/lib/preact/create-query.d.ts

@@ -14,8 +14,10 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     fetch: () => void;
     /**
      * Will be called even if the data is still fresh (not stale).
+     *
+     * @returns Promise that will always get resolved.
      */
-    forceFetch: () => void;
+    forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError>>;
     /**
      * Fetch next page if has next page.
      *
@@ -187,7 +189,7 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
      * IMPORTANT NOTE: Put this on the root component or parent component, before any component subscribed!
      */
     setInitialResponse: (options: {
-        key?: TKey;
+        key?: TKey | null;
         response: TResponse;
         skipRevalidation?: boolean;
     }) => void;
@@ -221,5 +223,9 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
         revert: () => void;
         invalidate: () => void;
     };
+    /**
+     * Use query with suspense mode.
+     */
+    suspend: (key?: TKey | null) => QueryState<TKey, TResponse, TData, TError>;
 };
 export declare const createQuery: <TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown>(queryFn: (key: TKey, state: QueryState<TKey, TResponse, TData, TError>) => Promise<TResponse>, options?: CreateQueryOptions<TKey, TResponse, TData, TError>) => UseQuery<TKey, TResponse, TData, TError>;

package/lib/preact/create-query.js

@@ -59,7 +59,7 @@ const createQuery = (queryFn, options = {}) => {
             const delay = (typeof retryDelay === 'function' ? retryDelay(error, prevState) : retryDelay) || 0;
             return { shouldRetry, delay };
         };
-        const forceFetch = () => {
+        const forceFetch = () => new Promise((resolve) => {
             const responseAllPages = [];
             const newPageParams = [undefined];
             let pageParam = undefined;
@@ -117,6 +117,7 @@ const createQuery = (queryFn, options = {}) => {
                         hasNextPage: (0, utils_1.hasValue)(newPageParam),
                     });
                     onSuccess(response, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .catch((error) => {
                     const prevState = get();
@@ -150,20 +151,21 @@ const createQuery = (queryFn, options = {}) => {
                             pageParam,
                             hasNextPage: (0, utils_1.hasValue)(pageParam),
                         });
-                    if (shouldRetry) {
+                    if (shouldRetry && typeof window !== 'undefined') {
                         retryTimeoutId.set(keyHash, window.setTimeout(() => {
                             set({ retryCount: prevState.retryCount + 1 });
                             callQuery();
                         }, delay));
                     }
                     onError(error, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .finally(() => {
                     onSettled(stateBeforeCallQuery);
                 });
             };
             callQuery();
-        };
+        });
         const fetch = () => {
             const { responseUpdatedAt } = get();
             const isStale = Date.now() > Number(responseUpdatedAt) + staleTime;
@@ -344,6 +346,15 @@ const createQuery = (queryFn, options = {}) => {
         const invalidate = () => useQuery.invalidateSpecificKey(key);
         return { revert, invalidate };
     };
+    useQuery.suspend = (key) => {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(key);
+        if (state.isLoading)
+            throw state.forceFetch();
+        if (state.isError)
+            throw state.error;
+        return state;
+    };
     return useQuery;
 };
 exports.createQuery = createQuery;

package/lib/react/create-mutation.d.ts

@@ -12,7 +12,9 @@ export type MutationState<TVar, TResponse = any, TError = unknown> = {
     error: TError | null;
     errorUpdatedAt: number | null;
     /**
-     * Mutate function is a promise that will always resolve.
+     * Mutate function.
+     *
+     * @returns Promise that will always get resolved.
      */
     mutate: TVar extends undefined ? () => Promise<{
         response?: TResponse;

package/lib/react/create-query.d.ts

@@ -14,8 +14,10 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     fetch: () => void;
     /**
      * Will be called even if the data is still fresh (not stale).
+     *
+     * @returns Promise that will always get resolved.
      */
-    forceFetch: () => void;
+    forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError>>;
     /**
      * Fetch next page if has next page.
      *
@@ -187,7 +189,7 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
      * IMPORTANT NOTE: Put this on the root component or parent component, before any component subscribed!
      */
     setInitialResponse: (options: {
-        key?: TKey;
+        key?: TKey | null;
         response: TResponse;
         skipRevalidation?: boolean;
     }) => void;
@@ -221,5 +223,9 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
         revert: () => void;
         invalidate: () => void;
     };
+    /**
+     * Use query with suspense mode.
+     */
+    suspend: (key?: TKey | null) => QueryState<TKey, TResponse, TData, TError>;
 };
 export declare const createQuery: <TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown>(queryFn: (key: TKey, state: QueryState<TKey, TResponse, TData, TError>) => Promise<TResponse>, options?: CreateQueryOptions<TKey, TResponse, TData, TError>) => UseQuery<TKey, TResponse, TData, TError>;

package/lib/react/create-query.js

@@ -59,7 +59,7 @@ const createQuery = (queryFn, options = {}) => {
             const delay = (typeof retryDelay === 'function' ? retryDelay(error, prevState) : retryDelay) || 0;
             return { shouldRetry, delay };
         };
-        const forceFetch = () => {
+        const forceFetch = () => new Promise((resolve) => {
             const responseAllPages = [];
             const newPageParams = [undefined];
             let pageParam = undefined;
@@ -117,6 +117,7 @@ const createQuery = (queryFn, options = {}) => {
                         hasNextPage: (0, utils_1.hasValue)(newPageParam),
                     });
                     onSuccess(response, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .catch((error) => {
                     const prevState = get();
@@ -150,20 +151,21 @@ const createQuery = (queryFn, options = {}) => {
                             pageParam,
                             hasNextPage: (0, utils_1.hasValue)(pageParam),
                         });
-                    if (shouldRetry) {
+                    if (shouldRetry && typeof window !== 'undefined') {
                         retryTimeoutId.set(keyHash, window.setTimeout(() => {
                             set({ retryCount: prevState.retryCount + 1 });
                             callQuery();
                         }, delay));
                     }
                     onError(error, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .finally(() => {
                     onSettled(stateBeforeCallQuery);
                 });
             };
             callQuery();
-        };
+        });
         const fetch = () => {
             const { responseUpdatedAt } = get();
             const isStale = Date.now() > Number(responseUpdatedAt) + staleTime;
@@ -344,6 +346,15 @@ const createQuery = (queryFn, options = {}) => {
         const invalidate = () => useQuery.invalidateSpecificKey(key);
         return { revert, invalidate };
     };
+    useQuery.suspend = (key) => {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(key);
+        if (state.isLoading)
+            throw state.forceFetch();
+        if (state.isError)
+            throw state.error;
+        return state;
+    };
     return useQuery;
 };
 exports.createQuery = createQuery;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "floppy-disk",
-  "version": "2.2.0-beta.3",
+  "version": "2.3.0-beta.1",
   "description": "FloppyDisk - lightweight, simple, and powerful state management library",
   "keywords": [
     "state",