floppy-disk 2.5.0-beta.2 → 2.5.0

package/lib/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 | undefined;
-    errorUpdatedAt: number | null;
+    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;
     /**
@@ -100,7 +110,7 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     isError: false;
     data: undefined;
     response: undefined;
-    responseUpdatedAt: null;
+    responseUpdatedAt: undefined;
 } | {
     status: 'success';
     isLoading: false;
@@ -108,7 +118,7 @@ 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;
@@ -116,10 +126,10 @@ export type QueryState<TKey extends StoreKey = StoreKey, TResponse = any, TData
     isError: true;
     data: undefined;
     response: undefined;
-    responseUpdatedAt: null;
+    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/lib/react/create-query.js

@@ -17,9 +17,9 @@ const INITIAL_QUERY_STATE = {
     isOptimisticData: false,
     data: undefined,
     response: undefined,
-    responseUpdatedAt: null,
+    responseUpdatedAt: undefined,
     error: undefined,
-    errorUpdatedAt: null,
+    errorUpdatedAt: undefined,
     retryCount: 0,
     isGoingToRetry: false,
     pageParam: undefined,
@@ -56,11 +56,11 @@ 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 || !(0, utils_1.getValueOrComputedValue)(enabled, key))
                 return resolve(state);
@@ -115,7 +115,7 @@ const createQuery = (queryFn, options = {}) => {
                         response,
                         responseUpdatedAt: Date.now(),
                         error: undefined,
-                        errorUpdatedAt: null,
+                        errorUpdatedAt: undefined,
                         retryCount: 0,
                         pageParam: newPageParam,
                         pageParams: newPageParams,
@@ -180,7 +180,7 @@ const createQuery = (queryFn, options = {}) => {
         });
         const fetch = () => {
             const { responseUpdatedAt } = get();
-            const isStale = Date.now() > Number(responseUpdatedAt) + staleTime;
+            const isStale = Date.now() > (responseUpdatedAt || 0) + staleTime;
             if (!isStale)
                 return;
             forceFetch();
@@ -338,7 +338,7 @@ const createQuery = (queryFn, options = {}) => {
                 isSuccess: true,
                 isError: false,
                 response,
-                responseUpdatedAt: skipRevalidation ? Date.now() : null,
+                responseUpdatedAt: skipRevalidation ? Date.now() : undefined,
                 data: select(response, { key: key, data: undefined }),
                 pageParam: newPageParam,
                 pageParams: [undefined, newPageParam],
@@ -358,14 +358,14 @@ 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();
     };

package/lib/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/lib/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/package.json

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