floppy-disk 2.5.0-beta.1 → 2.5.0-beta.3

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

@@ -1,6 +1,7 @@
 import { FunctionComponent } from 'react';
+import { Maybe } from '../utils';
 import { CreateStoresOptions, StoreKey, UseStores } from './create-stores';
-export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown> = {
+export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown, TPageParam = any> = {
     /**
      * Query store key, an object that will be hashed into a string as a query store identifier.
      */
@@ -18,17 +19,17 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
      *
      * @returns Promise that will always get resolved.
      */
-    forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError>>;
+    forceFetch: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
     /**
      * Fetch next page if has next page.
      *
      * If the data is empty, it will just fetch the first page.
      *
-     * You can ignore this if your query is not paginated.
+     * You can ignore this if your query is not an infinite query.
      *
      * @returns Promise that will always get resolved.
      */
-    fetchNextPage: () => Promise<QueryState<TKey, TResponse, TData, TError>>;
+    fetchNextPage: () => Promise<QueryState<TKey, TResponse, TData, TError, TPageParam>>;
     /**
      * Set query state (data, error, etc) to initial state.
      */
@@ -40,7 +41,7 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
      *
      * IMPORTANT NOTE: This won't work well on infinite query.
      */
-    optimisticUpdate: (response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError>) => TResponse)) => {
+    optimisticUpdate: (response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => TResponse)) => {
         revert: () => void;
         invalidate: () => void;
     };
@@ -54,14 +55,19 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     isWaitingNextPage: boolean;
     isRefetching: boolean;
     isRefetchError: boolean;
+    /**
+     * Will be `true` if the response/data comes from the previous query key.
+     *
+     * @see `keepPreviousData` option
+     */
     isPreviousData: boolean;
     isOptimisticData: boolean;
-    error: TError | null;
-    errorUpdatedAt: number | null;
+    error: TError | undefined;
+    errorUpdatedAt: number | undefined;
     retryCount: number;
     isGoingToRetry: boolean;
-    pageParam: any;
-    pageParams: any[];
+    pageParam: Maybe<TPageParam>;
+    pageParams: Maybe<TPageParam>[];
     hasNextPage: boolean;
     retryNextPageCount: number;
     isGoingToRetryNextPage: boolean;
@@ -77,6 +83,8 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
      *
      * It has no relation with network fetching state.
      * If you're looking for network fetching state, use `isWaiting` instead.
+     *
+     * @see https://floppy-disk.vercel.app/docs/query/introduction#query-state--network-fetching-state
      */
     status: 'loading';
     /**
@@ -84,6 +92,8 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
      *
      * It has no relation with network fetching state.
      * If you're looking for network fetching state, use `isWaiting` instead.
+     *
+     * @see https://floppy-disk.vercel.app/docs/query/introduction#query-state--network-fetching-state
      */
     isLoading: true;
     /**
@@ -98,9 +108,9 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
      * If data fetched successfully but then an error occured, `isError` will be `false` but `isRefetchError` will be `true`.
      */
     isError: false;
-    data: null;
-    response: null;
-    responseUpdatedAt: null;
+    data: undefined;
+    response: undefined;
+    responseUpdatedAt: undefined;
 } | {
     status: 'success';
     isLoading: false;
@@ -108,18 +118,18 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     isError: false;
     data: TData;
     response: TResponse;
-    responseUpdatedAt: number | null;
+    responseUpdatedAt: number | undefined;
 } | {
     status: 'error';
     isLoading: false;
     isSuccess: false;
     isError: true;
-    data: null;
-    response: null;
-    responseUpdatedAt: null;
+    data: undefined;
+    response: undefined;
+    responseUpdatedAt: undefined;
 });
-export type CreateQueryOptions<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown> = CreateStoresOptions<TKey, QueryState<TKey, TResponse, TData, TError>> & {
-    select?: (response: TResponse, state: Pick<QueryState<TKey, TResponse, TData, TError>, 'data' | 'key'>) => TData;
+export type CreateQueryOptions<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown, TPageParam = any> = CreateStoresOptions<TKey, QueryState<TKey, TResponse, TData, TError, TPageParam>> & {
+    select?: (response: TResponse, state: Pick<QueryState<TKey, TResponse, TData, TError, TPageParam>, 'data' | 'key'>) => TData;
     /**
      * Stale time in miliseconds.
      *
@@ -160,29 +170,31 @@ export type CreateQueryOptions<TKey extends StoreKey = StoreKey, TResponse = any
      *
      * Defaults to `1`.
      */
-    retry?: number | ((error: TError, prevState: QueryState<TKey, TResponse, TData, TError>) => number);
+    retry?: number | ((error: TError, prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => number);
     /**
      * Error retry delay in miliseconds.
      *
      * Defaults to `2000` (2 seconds).
      */
-    retryDelay?: number | ((error: TError, prevState: QueryState<TKey, TResponse, TData, TError>) => number);
+    retryDelay?: number | ((error: TError, prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => number);
     /**
-     * If set to `true`, previous `data` will be kept when fetching new data because the query key changed.
+     * Used for lagged query.
      *
-     * This will only happened if there is no `data` in the next query.
+     * If set to `true`, then:
+     * when the query key changed and there is no `data` in the next query key cache,
+     * the previous query key cache `data` will be used while fetching new data.
      */
     keepPreviousData?: boolean;
     /**
      * Only set this if you have an infinite query.
      *
-     * This function should return a variable that will be used when fetching next page (`pageParam`).
+     * This function should return a variable that will be stored as `pageParam` that can be used when fetching next page.
      */
-    getNextPageParam?: (lastPage: TResponse, index: number) => any;
-    onBeforeFetch?: (cancel: () => void, state: QueryState<TKey, TResponse, TData, TError>) => void;
-    onSuccess?: (response: TResponse, stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError>) => void;
-    onError?: (error: TError, stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError>) => void;
-    onSettled?: (stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError>) => void;
+    getNextPageParam?: (lastPage: TResponse, index: number) => Maybe<TPageParam>;
+    onBeforeFetch?: (cancel: () => void, state: QueryState<TKey, TResponse, TData, TError, TPageParam>) => void;
+    onSuccess?: (response: TResponse, stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError, TPageParam>) => void;
+    onError?: (error: TError, stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError, TPageParam>) => void;
+    onSettled?: (stateBeforeCallQuery: QueryState<TKey, TResponse, TData, TError, TPageParam>) => void;
     /**
      * Cache time in miliseconds.
      *
@@ -203,9 +215,9 @@ export type CreateQueryOptions<TKey extends StoreKey = StoreKey, TResponse = any
      *
      * @see https://floppy-disk.vercel.app/docs/query/polling
      */
-    refetchInterval?: number | false | ((state: QueryState<TKey, TResponse, TData, TError>) => number | false);
+    refetchInterval?: number | false | ((state: QueryState<TKey, TResponse, TData, TError, TPageParam>) => number | false);
 };
-export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown> = UseStores<TKey, QueryState<TKey, TResponse, TData, TError>> & {
+export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown, TPageParam = any> = UseStores<TKey, QueryState<TKey, TResponse, TData, TError, TPageParam>> & {
     /**
      * Set query's initial response.
      *
@@ -214,7 +226,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 | null;
+        key?: Maybe<TKey>;
         response: TResponse;
         skipRevalidation?: boolean;
     }) => void;
@@ -225,7 +237,7 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
     /**
      * Set query state (data, error, etc) to initial state.
      */
-    resetSpecificKey: (key?: TKey | null) => void;
+    resetSpecificKey: (key?: Maybe<TKey>) => void;
     /**
      * Invalidate query means marking a query as stale, and will refetch only if the query is active (has subscriber)
      */
@@ -233,7 +245,7 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
     /**
      * Invalidate query means marking a query as stale, and will refetch only if the query is active (has subscriber)
      */
-    invalidateSpecificKey: (key?: TKey | null) => void;
+    invalidateSpecificKey: (key?: Maybe<TKey>) => void;
     /**
      * Optimistic update.
      *
@@ -242,8 +254,8 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
      * IMPORTANT NOTE: This won't work well on infinite query.
      */
     optimisticUpdate: (options: {
-        key?: TKey | null;
-        response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError>) => TResponse);
+        key?: Maybe<TKey>;
+        response: TResponse | ((prevState: QueryState<TKey, TResponse, TData, TError, TPageParam>) => TResponse);
     }) => {
         revert: () => void;
         invalidate: () => void;
@@ -251,11 +263,11 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
     /**
      * Use query with suspense mode.
      */
-    suspend: (key?: TKey | null) => Extract<QueryState<TKey, TResponse, TData, TError>, {
+    suspend: (key?: Maybe<TKey>) => Extract<QueryState<TKey, TResponse, TData, TError, TPageParam>, {
         status: 'success';
     }>;
     Render: (props: {
-        queryKey?: TKey | null;
+        queryKey?: Maybe<TKey>;
         loading?: FunctionComponent<TKey>;
         success?: FunctionComponent<TKey>;
         error?: FunctionComponent<TKey>;
@@ -264,4 +276,4 @@ export type UseQuery<TKey extends StoreKey = StoreKey, TResponse = any, TData =
 /**
  * @see https://floppy-disk.vercel.app/docs/api#createquery
  */
-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>;
+export declare const createQuery: <TKey extends StoreKey = StoreKey, TResponse = any, TData = TResponse, TError = unknown, TPageParam = any>(queryFn: (key: TKey, state: QueryState<TKey, TResponse, TData, TError, TPageParam>) => Promise<TResponse>, options?: CreateQueryOptions<TKey, TResponse, TData, TError, TPageParam>) => UseQuery<TKey, TResponse, TData, TError, TPageParam>;

package/esm/react/create-query.js

@@ -12,11 +12,11 @@ const INITIAL_QUERY_STATE = {
     isRefetchError: false,
     isPreviousData: false,
     isOptimisticData: false,
-    data: null,
-    response: null,
-    responseUpdatedAt: null,
-    error: null,
-    errorUpdatedAt: null,
+    data: undefined,
+    response: undefined,
+    responseUpdatedAt: undefined,
+    error: undefined,
+    errorUpdatedAt: undefined,
     retryCount: 0,
     isGoingToRetry: false,
     pageParam: undefined,
@@ -53,11 +53,11 @@ export const createQuery = (queryFn, options = {}) => {
             return { shouldRetry: retryCount < maxRetryCount, delay };
         };
         const forceFetch = () => new Promise((resolve) => {
+            const state = get();
             const responseAllPages = [];
-            const newPageParams = [undefined];
-            let pageParam = undefined;
+            const newPageParams = [state.pageParams[0]];
+            let pageParam = state.pageParams[0];
             clearTimeout(refetchIntervalTimeoutId.get(keyHash));
-            const state = get();
             const { isWaiting, isLoading, pageParams } = state;
             if (isWaiting || !getValueOrComputedValue(enabled, key))
                 return resolve(state);
@@ -108,11 +108,11 @@ export const createQuery = (queryFn, options = {}) => {
                         isOptimisticData: false,
                         data: responseAllPages.reduce((prev, responseCurrentPage) => {
                             return select(responseCurrentPage, { key, data: prev });
-                        }, null),
+                        }, undefined),
                         response,
                         responseUpdatedAt: Date.now(),
-                        error: null,
-                        errorUpdatedAt: null,
+                        error: undefined,
+                        errorUpdatedAt: undefined,
                         retryCount: 0,
                         pageParam: newPageParam,
                         pageParams: newPageParams,
@@ -127,7 +127,6 @@ export const createQuery = (queryFn, options = {}) => {
                     }
                     set(nextState);
                     onSuccess(response, stateBeforeCallQuery);
-                    resolve(get());
                 })
                     .catch((error) => {
                     const prevState = get();
@@ -141,7 +140,7 @@ export const createQuery = (queryFn, options = {}) => {
                             data: responseAllPages.length
                                 ? responseAllPages.reduce((prev, response) => {
                                     return select(response, { key, data: prev });
-                                }, null)
+                                }, undefined)
                                 : prevState.data,
                             error,
                             errorUpdatedAt,
@@ -154,7 +153,7 @@ export const createQuery = (queryFn, options = {}) => {
                             status: 'error',
                             isLoading: false,
                             isError: true,
-                            data: null,
+                            data: undefined,
                             error,
                             errorUpdatedAt,
                             isGoingToRetry: shouldRetry,
@@ -168,17 +167,17 @@ export const createQuery = (queryFn, options = {}) => {
                         }, delay));
                     }
                     onError(error, stateBeforeCallQuery);
-                    resolve(get());
                 })
                     .finally(() => {
                     onSettled(stateBeforeCallQuery);
+                    resolve(get());
                 });
             };
             callQuery();
         });
         const fetch = () => {
             const { responseUpdatedAt } = get();
-            const isStale = Date.now() > Number(responseUpdatedAt) + staleTime;
+            const isStale = Date.now() > (responseUpdatedAt || 0) + staleTime;
             if (!isStale)
                 return;
             forceFetch();
@@ -217,7 +216,6 @@ export const createQuery = (queryFn, options = {}) => {
                     hasNextPage: hasValue(newPageParam),
                 });
                 onSuccess(response, stateBeforeCallQuery);
-                resolve(get());
             })
                 .catch((error) => {
                 const prevState = get();
@@ -236,10 +234,10 @@ export const createQuery = (queryFn, options = {}) => {
                     }, delay));
                 }
                 onError(error, stateBeforeCallQuery);
-                resolve(get());
             })
                 .finally(() => {
                 onSettled(stateBeforeCallQuery);
+                resolve(get());
             });
         });
         return {
@@ -337,8 +335,8 @@ export const createQuery = (queryFn, options = {}) => {
                 isSuccess: true,
                 isError: false,
                 response,
-                responseUpdatedAt: skipRevalidation ? Date.now() : null,
-                data: select(response, { key: key, data: null }),
+                responseUpdatedAt: skipRevalidation ? Date.now() : undefined,
+                data: select(response, { key: key, data: undefined }),
                 pageParam: newPageParam,
                 pageParams: [undefined, newPageParam],
                 hasNextPage: hasValue(newPageParam),
@@ -357,14 +355,14 @@ export const createQuery = (queryFn, options = {}) => {
     useQuery.invalidate = () => {
         useQuery.getStores().forEach((store) => {
             const { get, set, getSubscribers } = store;
-            set({ responseUpdatedAt: null });
+            set({ responseUpdatedAt: undefined });
             if (getSubscribers().size > 0)
                 get().forceFetch();
         });
     };
     useQuery.invalidateSpecificKey = (key) => {
         const { get, set, getSubscribers } = useQuery.getStore(key);
-        set({ responseUpdatedAt: null });
+        set({ responseUpdatedAt: undefined });
         if (getSubscribers().size > 0)
             get().forceFetch();
     };
@@ -376,7 +374,7 @@ export const createQuery = (queryFn, options = {}) => {
         useQuery.set(key, {
             isOptimisticData: true,
             response: optimisticResponse,
-            data: select(optimisticResponse, { key: key, data: null }),
+            data: select(optimisticResponse, { key: key, data: undefined }),
         });
         preventReplaceResponse.set(prevState.keyHash, true);
         const revert = () => {

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

@@ -1,6 +1,6 @@
+import { Maybe } from '../utils';
 import { InitStoreOptions, InitStoreReturn, SelectDeps, SetStoreData, StoreData, Subscribers } from '../vanilla';
 import { WatchProps } from './create-store';
-type Maybe<T> = T | null | undefined;
 export type StoreKey = Record<string, any> | undefined;
 export type StoresInitializer<TKey extends StoreKey = StoreKey, T extends StoreData = StoreData> = (api: {
     get: () => T;
@@ -50,4 +50,3 @@ export type CreateStoresOptions<TKey extends StoreKey = StoreKey, T extends Stor
  * @see https://floppy-disk.vercel.app/docs/api#createstores
  */
 export declare const createStores: <TKey extends StoreKey = StoreKey, T extends StoreData = StoreData>(initializer: StoresInitializer<TKey, T>, options?: CreateStoresOptions<TKey, T>) => UseStores<TKey, T>;
-export {};

package/esm/utils/index.d.ts

@@ -3,3 +3,4 @@ export declare const identityFn: <T>(value: T) => T;
 export declare const hasValue: (value: any) => boolean;
 export declare const hashStoreKey: (obj?: any) => string;
 export declare const getValueOrComputedValue: <T, P extends any[]>(valueOrComputeValueFn: T | ((...params: P) => T), ...params: P) => T;
+export type Maybe<T> = T | null | undefined;

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

@@ -7,10 +7,10 @@ export type MutationState<TVar, TResponse = any, TError = unknown> = {
     isWaiting: boolean;
     isSuccess: boolean;
     isError: boolean;
-    response: TResponse | null;
-    responseUpdatedAt: number | null;
-    error: TError | null;
-    errorUpdatedAt: number | null;
+    response: TResponse | undefined;
+    responseUpdatedAt: number | undefined;
+    error: TError | undefined;
+    errorUpdatedAt: number | undefined;
     /**
      * Mutate function.
      *

package/lib/preact/create-mutation.js

@@ -12,10 +12,10 @@ const createMutation = (mutationFn, options = {}) => {
         isWaiting: false,
         isSuccess: false,
         isError: false,
-        response: null,
-        responseUpdatedAt: null,
-        error: null,
-        errorUpdatedAt: null,
+        response: undefined,
+        responseUpdatedAt: undefined,
+        error: undefined,
+        errorUpdatedAt: undefined,
         mutate: ((variables) => {
             set({ isWaiting: true });
             const stateBeforeMutate = get();
@@ -29,8 +29,8 @@ const createMutation = (mutationFn, options = {}) => {
                         isError: false,
                         response,
                         responseUpdatedAt: Date.now(),
-                        error: null,
-                        errorUpdatedAt: null,
+                        error: undefined,
+                        errorUpdatedAt: undefined,
                     });
                     onSuccess(response, variables, stateBeforeMutate);
                     resolve({ response, variables });