floppy-disk 2.2.0 → 2.3.0-beta.2

package/README.md

@@ -28,28 +28,39 @@ import { createQuery, createMutation } from 'floppy-disk'; // 8.4 kB (gzipped: 2
 
 ## Key Features
 
-- Create store ✅
-  - Yes, it also support middleware & set/get state outside component ✅
-  - Store event (`onSubscribe`, `onUnsubscribe`, etc.) ✅
-  - Use store as local state manager ✅
-- Create stores (yes, it's plural) ✅ \*_controlled with a store key_
-- Create query ✅
-  - Dedupe multiple request ✅
-  - Auto-update stale data (stale-while-revalidate) ✅
-  - Enable/disable query ✅
-  - Auto-fetch or manual (lazy query) ✅
-  - Retry on error (retry count, retry delay) ✅
-  - SSR/SSG's initial query data ✅
-  - Optimistic update ✅
-  - Invalidate query ✅
-  - Reset query ✅
-  - Query with param (query key) ✅
-  - Infinite query ✅
-  - Get query data outside component ✅
-  - Custom reactivity ✅
-  - Fetching mechanisms are agnostically built on promises ✅
-    - Can be used with literally any asynchronous data fetching client, including GraphQL ✅
-- Create mutation ✅
+- **Create Store**
+  - Get/set store inside/outside component
+  - Custom reactivity (like `useEffect`'s dependency array)
+  - Support middleware
+  - Set state interception
+  - Store event (`onSubscribe`, `onUnsubscribe`, etc.)
+  - Use store as local state manager
+- **Create Stores**
+  - Same as store, but controlled with a store key
+- **Create Query & Mutation**
+  - Backend agnostic (support GraphQL & any async function)
+  - TypeScript ready
+  - SSR/SSG support
+  - Custom reactivity (we choose when to re-render)
+  - **Create query**
+    - Dedupe multiple request
+    - Auto-fetch on mount or manual (lazy query)
+    - Enable/disable query
+    - Serve stale data while revalidating
+    - Retry on error (customizable)
+    - Optimistic update
+    - Invalidate query
+    - Reset query
+    - Query with param (query key)
+    - Paginated/infinite query
+    - Prefetch query
+    - Fetch from inside/outside component
+    - Get query state inside/outside component
+    - Suspense mode
+  - **Create mutation**
+    - Mutate from inside/outside component
+    - Get mutation state inside/outside component
+  - ... and [a lot more](https://floppy-disk.vercel.app/)
 
 <br>
 
@@ -661,10 +672,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
 

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

@@ -1,3 +1,5 @@
+/// <reference types="react" />
+import { FunctionComponent } from 'preact';
 import { CreateStoresOptions, StoreKey, UseStores } from './create-stores';
 export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown> = {
     /**
@@ -14,8 +16,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 +191,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 +225,15 @@ 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>;
+    Render: (props: {
+        queryKey?: TKey | null;
+        loading?: FunctionComponent<TKey>;
+        success?: FunctionComponent<TKey>;
+        error?: FunctionComponent<TKey>;
+    }) => JSX.Element;
 };
 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

@@ -1,3 +1,4 @@
+import { h as createElement } from 'preact';
 import { useState } from 'preact/hooks';
 import { hasValue, identityFn, noop } from '../utils';
 import { createStores } from './create-stores';
@@ -56,7 +57,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 +115,7 @@ export const createQuery = (queryFn, options = {}) => {
                         hasNextPage: hasValue(newPageParam),
                     });
                     onSuccess(response, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .catch((error) => {
                     const prevState = get();
@@ -147,20 +149,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 +344,23 @@ 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;
+    };
+    const defaultElement = () => null;
+    useQuery.Render = (props) => {
+        const { queryKey, loading = defaultElement, success = defaultElement, error = defaultElement, } = props;
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(queryKey);
+        if (state.data)
+            return createElement(success, state.key);
+        return createElement(state.isLoading ? loading : error, state.key);
+    };
     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

@@ -1,3 +1,4 @@
+import { FunctionComponent } from 'react';
 import { CreateStoresOptions, StoreKey, UseStores } from './create-stores';
 export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown> = {
     /**
@@ -14,8 +15,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 +190,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 +224,15 @@ 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>;
+    Render: (props: {
+        queryKey?: TKey | null;
+        loading?: FunctionComponent<TKey>;
+        success?: FunctionComponent<TKey>;
+        error?: FunctionComponent<TKey>;
+    }) => JSX.Element;
 };
 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

@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { createElement, useState } from 'react';
 import { hasValue, identityFn, noop } from '../utils';
 import { createStores } from './create-stores';
 const getDecision = (value, param, { ifTrue, ifAlways }) => {
@@ -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,23 @@ 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;
+    };
+    const defaultElement = () => null;
+    useQuery.Render = (props) => {
+        const { queryKey, loading = defaultElement, success = defaultElement, error = defaultElement, } = props;
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(queryKey);
+        if (state.data)
+            return createElement(success, state.key);
+        return createElement(state.isLoading ? loading : error, state.key);
+    };
     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

@@ -1,3 +1,5 @@
+/// <reference types="react" />
+import { FunctionComponent } from 'preact';
 import { CreateStoresOptions, StoreKey, UseStores } from './create-stores';
 export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown> = {
     /**
@@ -14,8 +16,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 +191,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 +225,15 @@ 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>;
+    Render: (props: {
+        queryKey?: TKey | null;
+        loading?: FunctionComponent<TKey>;
+        success?: FunctionComponent<TKey>;
+        error?: FunctionComponent<TKey>;
+    }) => JSX.Element;
 };
 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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createQuery = void 0;
+const preact_1 = require("preact");
 const hooks_1 = require("preact/hooks");
 const utils_1 = require("../utils");
 const create_stores_1 = require("./create-stores");
@@ -59,7 +60,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 +118,7 @@ const createQuery = (queryFn, options = {}) => {
                         hasNextPage: (0, utils_1.hasValue)(newPageParam),
                     });
                     onSuccess(response, stateBeforeCallQuery);
+                    resolve(get());
                 })
                     .catch((error) => {
                     const prevState = get();
@@ -150,20 +152,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 +347,24 @@ 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;
+    };
+    const defaultElement = () => null;
+    useQuery.Render = (props) => {
+        const { queryKey, loading = defaultElement, success = defaultElement, error = defaultElement, } = props;
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(queryKey);
+        if (state.data)
+            return (0, preact_1.h)(success, state.key);
+        return (0, preact_1.h)(state.isLoading ? loading : error, state.key);
+    };
     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

@@ -1,3 +1,4 @@
+import { FunctionComponent } from 'react';
 import { CreateStoresOptions, StoreKey, UseStores } from './create-stores';
 export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown> = {
     /**
@@ -14,8 +15,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 +190,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 +224,15 @@ 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>;
+    Render: (props: {
+        queryKey?: TKey | null;
+        loading?: FunctionComponent<TKey>;
+        success?: FunctionComponent<TKey>;
+        error?: FunctionComponent<TKey>;
+    }) => JSX.Element;
 };
 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,24 @@ 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;
+    };
+    const defaultElement = () => null;
+    useQuery.Render = (props) => {
+        const { queryKey, loading = defaultElement, success = defaultElement, error = defaultElement, } = props;
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const state = useQuery(queryKey);
+        if (state.data)
+            return (0, react_1.createElement)(success, state.key);
+        return (0, react_1.createElement)(state.isLoading ? loading : error, state.key);
+    };
     return useQuery;
 };
 exports.createQuery = createQuery;

package/package.json

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