@recats/cdeebee 3.0.0-beta.8 → 3.0.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { AsyncThunk } from '@reduxjs/toolkit';
 import { AsyncThunkConfig } from '@reduxjs/toolkit';
+import { Draft } from '@reduxjs/toolkit';
+import { PayloadAction } from '@reduxjs/toolkit';
 import { Slice } from '@reduxjs/toolkit';
 import { SliceSelectors } from '@reduxjs/toolkit';
-import { WritableDraft } from '@reduxjs/toolkit';
 
 declare type Append<P extends readonly (string | number)[], K extends string | number> = [...P, K];
 
@@ -10,22 +11,22 @@ declare type ArrayElement<T> = T extends readonly (infer U)[] ? U : T extends (i
 
 export declare function batchingUpdate<T extends Record<string, unknown>>(state: T, valueList: CdeebeeValueList<T>): void;
 
-declare interface CdeebeeActiveRequest {
+export declare interface CdeebeeActiveRequest {
     api: string;
     requestId: string;
 }
 
-declare interface CdeebeeHistoryState {
+export declare interface CdeebeeHistoryState {
     requestId: string;
     api: string;
     request: unknown;
 }
 
-declare type CdeebeeListStrategy<T> = Record<keyof T, CdeebeeStrategy>;
+export declare type CdeebeeListStrategy<T> = Record<keyof T, CdeebeeStrategy>;
 
 export declare type CdeebeeModule = 'history' | 'listener' | 'storage' | 'cancelation' | 'queryQueue';
 
-export declare interface CdeebeeRequestOptions<T> extends Partial<Pick<CdeebeeSettings<T>, 'fileKey' | 'bodyKey' | 'normalize' | 'listStrategy'>> {
+export declare interface CdeebeeRequestOptions<T> extends Partial<Pick<CdeebeeSettings<T>, 'fileKey' | 'bodyKey' | 'normalize'>> {
     api: string;
     files?: File[];
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
@@ -34,22 +35,26 @@ export declare interface CdeebeeRequestOptions<T> extends Partial<Pick<CdeebeeSe
     onResult?: (response: T) => void;
     ignore?: boolean;
     responseType?: 'json' | 'text' | 'blob';
+    listStrategy?: Partial<CdeebeeListStrategy<T>>;
+    historyClear?: boolean;
 }
 
 declare interface CdeebeeRequestState {
     active: CdeebeeActiveRequest[];
     errors: Record<string, CdeebeeHistoryState[]>;
     done: Record<string, CdeebeeHistoryState[]>;
+    lastResultIdList: Record<string, Record<string, string[]>>;
 }
 
 declare interface CdeebeeSettings<T> {
     modules: CdeebeeModule[];
     fileKey: string;
     bodyKey: string;
-    mergeWithData: unknown;
-    mergeWithHeaders: unknown;
+    mergeWithData: Record<string, unknown> | (() => Record<string, unknown>);
+    mergeWithHeaders: Record<string, string> | (() => Record<string, string>);
     listStrategy?: CdeebeeListStrategy<T>;
-    normalize?: <T>(storage: CdeebeeState<T>, result: T, strategyList: CdeebeeListStrategy<T>) => T;
+    normalize?: (storage: CdeebeeState<T>, result: unknown, strategyList: CdeebeeListStrategy<T>) => Record<string, unknown>;
+    maxHistorySize?: number;
 }
 
 export declare interface CdeebeeState<T> {
@@ -58,7 +63,7 @@ export declare interface CdeebeeState<T> {
     request: CdeebeeRequestState;
 }
 
-declare type CdeebeeStrategy = 'merge' | 'replace';
+declare type CdeebeeStrategy = 'merge' | 'replace' | 'skip';
 
 declare type CdeebeeValueItem<T> = NonEmptyPaths<T> extends infer P ? P extends readonly (string | number)[] ? {
     key: P;
@@ -67,12 +72,118 @@ declare type CdeebeeValueItem<T> = NonEmptyPaths<T> extends infer P ? P extends
 
 export declare type CdeebeeValueList<T> = ReadonlyArray<CdeebeeValueItem<T>>;
 
+/**
+ * Generic hook factory that creates a selector hook for cdeebee state.
+ * This allows the hooks to work with any Redux root state structure.
+ *
+ * @template RootState - The shape of the Redux root state
+ * @template Storage - The shape of the cdeebee storage
+ * @param selectCdeebee - Function to select the cdeebee slice from root state
+ * @returns An object containing all cdeebee hooks
+ */
+export declare function createCdeebeeHooks<RootState, Storage>(selectCdeebee: (state: RootState) => CdeebeeState<Storage>): {
+    useLoading: (apiList: string[]) => boolean;
+    useRequestHistory: (api: string) => CdeebeeHistoryState[];
+    useRequestErrors: (api: string) => CdeebeeHistoryState[];
+    useStorageList: <K extends keyof Storage>(listName: K) => Storage[K];
+    useStorage: () => Storage;
+    useIsLoading: () => boolean;
+    useLastResultIdList: <K extends keyof Storage>(api: string, listName: K) => string[];
+};
+
+export declare function defaultNormalize<T>(cdeebee: CdeebeeState<T>, response: IResponse, strategyList: CdeebeeListStrategy<T>): Record<string, ResponseValue>;
+
 export declare const factory: <T>(settings: CdeebeeSettings<T>, storage?: T) => Slice<CdeebeeState<T>, {
-set(state: WritableDraft<CdeebeeState<T>>, action: {
+set(state: {
+settings: {
+modules: CdeebeeModule[];
+fileKey: string;
+bodyKey: string;
+mergeWithData: (() => Record<string, unknown>) | {
+[x: string]: unknown;
+};
+mergeWithHeaders: (() => Record<string, string>) | {
+[x: string]: string;
+};
+listStrategy?: (CdeebeeListStrategy<T> | undefined extends infer V ? V extends object ? Draft<V> : V : never) | undefined;
+normalize?: ((storage: CdeebeeState<T>, result: unknown, strategyList: CdeebeeListStrategy<T>) => Record<string, unknown>) | undefined;
+maxHistorySize?: number | undefined;
+};
+storage: T extends infer V ? V extends object ? Draft<V> : V : never;
+request: {
+active: {
+api: string;
+requestId: string;
+}[];
+errors: {
+[x: string]: {
+requestId: string;
+api: string;
+request: unknown;
+}[];
+};
+done: {
+[x: string]: {
+requestId: string;
+api: string;
+request: unknown;
+}[];
+};
+lastResultIdList: {
+[x: string]: {
+[x: string]: string[];
+};
+};
+};
+}, action: {
 payload: CdeebeeValueList<T>;
 }): void;
+historyClear(state: {
+settings: {
+modules: CdeebeeModule[];
+fileKey: string;
+bodyKey: string;
+mergeWithData: (() => Record<string, unknown>) | {
+[x: string]: unknown;
+};
+mergeWithHeaders: (() => Record<string, string>) | {
+[x: string]: string;
+};
+listStrategy?: (CdeebeeListStrategy<T> | undefined extends infer V ? V extends object ? Draft<V> : V : never) | undefined;
+normalize?: ((storage: CdeebeeState<T>, result: unknown, strategyList: CdeebeeListStrategy<T>) => Record<string, unknown>) | undefined;
+maxHistorySize?: number | undefined;
+};
+storage: T extends infer V ? V extends object ? Draft<V> : V : never;
+request: {
+active: {
+api: string;
+requestId: string;
+}[];
+errors: {
+[x: string]: {
+requestId: string;
+api: string;
+request: unknown;
+}[];
+};
+done: {
+[x: string]: {
+requestId: string;
+api: string;
+request: unknown;
+}[];
+};
+lastResultIdList: {
+[x: string]: {
+[x: string]: string[];
+};
+};
+};
+}, action: PayloadAction<string | undefined>): void;
 }, "cdeebee", "cdeebee", SliceSelectors<CdeebeeState<T>>>;
 
+declare type IResponse = Record<string, ResponseValue>;
+
 declare type IsArray<T> = T extends readonly unknown[] ? true : T extends unknown[] ? true : false;
 
 declare type KeyOf<T> = Extract<keyof T, string | number>;
@@ -89,6 +200,81 @@ startedAt: string;
 endedAt: string;
 }, CdeebeeRequestOptions<unknown>, AsyncThunkConfig>;
 
+declare type ResponseValue = Record<string, unknown>;
+
+/**
+ * Standalone hook that can be used without createCdeebeeHooks.
+ * Assumes the cdeebee slice is at state.cdeebee.
+ *
+ * @returns true if any request is active
+ */
+export declare function useIsLoading<Storage = unknown>(): boolean;
+
+/**
+ * Standalone hook that can be used without createCdeebeeHooks.
+ * Assumes the cdeebee slice is at state.cdeebee.
+ *
+ * Get the list of IDs returned by the last successful request to an API for a specific list.
+ * Useful for filtering storage data to show only results from a specific request.
+ *
+ * @param api - The API endpoint
+ * @param listName - The name of the list in storage (typed from Storage)
+ * @returns Array of primary key IDs from the last response for that list
+ *
+ * @example
+ * const productList = useStorageList('productList');
+ * const lastIDList = useLastResultIdList('/api/search', 'productList');
+ * const displayResults = lastIDList.map(id => productList[id]).filter(Boolean);
+ */
+export declare function useLastResultIdList<Storage, K extends keyof Storage>(api: string, listName: K): string[];
+
+/**
+ * Standalone hook that can be used without createCdeebeeHooks.
+ * Assumes the cdeebee slice is at state.cdeebee.
+ *
+ * @param apiList - Array of API endpoints to check
+ * @returns true if any of the APIs are currently active/loading
+ *
+ * @example
+ * const isLoading = useLoading(['/api/forums', '/api/threads']);
+ */
+export declare function useLoading<Storage = unknown>(apiList: string[]): boolean;
+
+/**
+ * Standalone hook that can be used without createCdeebeeHooks.
+ * Assumes the cdeebee slice is at state.cdeebee.
+ *
+ * @param api - The API endpoint
+ * @returns Array of error history entries
+ */
+export declare function useRequestErrors<Storage = unknown>(api: string): CdeebeeHistoryState[];
+
+/**
+ * Standalone hook that can be used without createCdeebeeHooks.
+ * Assumes the cdeebee slice is at state.cdeebee.
+ *
+ * @param api - The API endpoint
+ * @returns Array of successful request history entries
+ */
+export declare function useRequestHistory<Storage = unknown>(api: string): CdeebeeHistoryState[];
+
+/**
+ * Standalone hook that can be used without createCdeebeeHooks.
+ * Assumes the cdeebee slice is at state.cdeebee.
+ *
+ * @returns The complete storage object
+ */
+export declare function useStorage<Storage>(): Storage;
+
+/**
+ * Standalone hook that can be used without createCdeebeeHooks.
+ * Assumes the cdeebee slice is at state.cdeebee.
+ *
+ * @param listName - The name of the list in storage
+ * @returns The list data
+ */
+export declare function useStorageList<Storage, K extends keyof Storage>(listName: K): Storage[K];
+
 declare type ValueAtPath<T, P extends readonly (string | number)[]> = P extends [] ? T : P extends readonly [infer K, ...infer R] ? K extends keyof T ? ValueAtPath<T[K], Extract<R, readonly (string | number)[]>> : T extends readonly (infer U)[] | (infer U)[] ? K extends number | `${number}` ? ValueAtPath<U, Extract<R, readonly (string | number)[]>> : never : never : never;
 
 export { }