@promoboxx/use-filter 2.0.0 → 2.0.1

package/dist/esm/store/localStorageStore.mjs

@@ -0,0 +1,32 @@
+//#region src/store/localStorageStore.ts
+const prefix = "useFilter";
+const localStorageStore = {
+	getFilter(namespace) {
+		const item = localStorage.getItem(`${prefix}/${namespace}/filter`);
+		if (item) {
+			return JSON.parse(item);
+		}
+	},
+	saveFilter(namespace, filter) {
+		localStorage.setItem(`${prefix}/${namespace}/filter`, JSON.stringify(filter));
+	},
+	getData(namespace) {
+		const item = localStorage.getItem(`${prefix}/${namespace}/data`);
+		if (item) {
+			return JSON.parse(item);
+		}
+	},
+	saveData(namespace, data) {
+		localStorage.setItem(`${prefix}/${namespace}/data`, JSON.stringify(data));
+	},
+	clear() {
+		for (const key in localStorage) {
+			if (key.startsWith(prefix)) {
+				localStorage.removeItem(key);
+			}
+		}
+	}
+};
+
+//#endregion
+export { localStorageStore as default };

package/dist/esm/store/memoryStore.d.mts

@@ -0,0 +1,6 @@
+import { FilterStore } from "./index.mjs";
+
+//#region src/store/memoryStore.d.ts
+declare const memoryStore: FilterStore;
+//#endregion
+export { memoryStore as default };

package/dist/esm/store/memoryStore.mjs

@@ -0,0 +1,24 @@
+//#region src/store/memoryStore.ts
+let cachedFilters = {};
+let cachedData = {};
+const memoryStore = {
+	getFilter(namespace) {
+		return cachedFilters[namespace];
+	},
+	saveFilter(namespace, filter) {
+		cachedFilters[namespace] = filter;
+	},
+	getData(namespace) {
+		return cachedData[namespace];
+	},
+	saveData(namespace, data) {
+		cachedData[namespace] = data;
+	},
+	clear() {
+		cachedFilters = {};
+		cachedData = {};
+	}
+};
+
+//#endregion
+export { memoryStore as default };

package/dist/esm/store/reduxHelpers/createActions.d.mts

@@ -0,0 +1,16 @@
+//#region src/store/reduxHelpers/createActions.d.ts
+interface CreateActions {
+  <Namespace extends string, PayloadCreatorMap extends ReduxPayloadCreatorMap>(namespace: Namespace, actions: PayloadCreatorMap): ReduxActionCreatorMap<Namespace, PayloadCreatorMap>;
+}
+type ReduxPayloadCreatorMap = Record<string, (...args: any[]) => any>;
+type ReduxActionCreatorMap<Namespace extends string, PayloadCreatorMap extends ReduxPayloadCreatorMap> = { [Type in keyof PayloadCreatorMap]: Type extends string ? ReduxActionCreator<Namespace, Type, PayloadCreatorMap[Type]> : undefined };
+interface ReduxActionCreator<Namespace extends string = string, Type extends string = string, Fn extends (...args: any[]) => any = (...args: any[]) => any> {
+  (...args: Parameters<Fn>): {
+    type: `${Namespace}/${Type}`;
+    payload: ReturnType<Fn>;
+  };
+  actionType: `${Namespace}/${Type}`;
+}
+declare const createActions: CreateActions;
+//#endregion
+export { ReduxActionCreator, ReduxActionCreatorMap, createActions as default };

package/dist/esm/store/reduxHelpers/createActions.mjs

@@ -0,0 +1,15 @@
+//#region src/store/reduxHelpers/createActions.ts
+const createActions = (namespace, payloadCreatorMap) => {
+	const actionCreators = {};
+	for (const key in payloadCreatorMap) {
+		actionCreators[key] = ((...args) => ({
+			type: `${namespace}/${key}`,
+			payload: payloadCreatorMap[key](...args)
+		}));
+		actionCreators[key].actionType = `${namespace}/${key}`;
+	}
+	return actionCreators;
+};
+
+//#endregion
+export { createActions as default };

package/dist/esm/store/reduxHelpers/createReducer.d.mts

@@ -0,0 +1,11 @@
+import { ReduxActionCreator } from "./createActions.mjs";
+import { Action } from "redux";
+
+//#region src/store/reduxHelpers/createReducer.d.ts
+interface ReduxReducerBuilder<State> {
+  addHandler: <ActionCreator extends ReduxActionCreator>(actionCreator: ActionCreator, handler: (state: State, action: ReturnType<ActionCreator>) => State) => ReduxReducerBuilder<State>;
+  addCase: <HandlerAction extends Action>(actionType: string, handler: (state: State, action: HandlerAction) => State) => ReduxReducerBuilder<State>;
+}
+declare function createReducer<State>(initialState: State, builderFn: (builder: ReduxReducerBuilder<State>) => void): (state: State | undefined, action: Action) => State;
+//#endregion
+export { createReducer as default };

package/dist/esm/store/reduxHelpers/createReducer.mjs

@@ -0,0 +1,24 @@
+//#region src/store/reduxHelpers/createReducer.ts
+function createReducer(initialState, builderFn) {
+	const handlers = {};
+	const builder = {
+		addHandler: (actionCreator, handler) => {
+			handlers[actionCreator.actionType] = handler;
+			return builder;
+		},
+		addCase: (actionType, handler) => {
+			handlers[actionType] = handler;
+			return builder;
+		}
+	};
+	builderFn(builder);
+	return (state = initialState, action) => {
+		if (handlers[action.type]) {
+			return handlers[action.type](state, action);
+		}
+		return state;
+	};
+}
+
+//#endregion
+export { createReducer as default };

package/dist/esm/store/reduxStore.d.mts

@@ -0,0 +1,18 @@
+import { FilterStore } from "./index.mjs";
+import { FilterInfo } from "../useFilter.mjs";
+import { Store } from "redux";
+
+//#region src/store/reduxStore.d.ts
+interface CreateReduxStoreConfig {
+  store: Store<{
+    useFilter: UseFilterReduxState;
+  }>;
+}
+declare function createReduxStore(config: CreateReduxStoreConfig): FilterStore;
+interface UseFilterReduxState {
+  data: Record<string, any>;
+  filters: Record<string, FilterInfo<any>>;
+}
+declare const useFilterReduxReducer: (state: UseFilterReduxState | undefined, action: import("redux").Action) => UseFilterReduxState;
+//#endregion
+export { createReduxStore, useFilterReduxReducer };

package/dist/esm/store/reduxStore.mjs

@@ -0,0 +1,61 @@
+import createActions from "./reduxHelpers/createActions.mjs";
+import createReducer from "./reduxHelpers/createReducer.mjs";
+
+//#region src/store/reduxStore.ts
+function createReduxStore(config) {
+	const reduxStoreStore = {
+		getFilter: (namespace) => {
+			return config.store.getState().useFilter.filters[namespace];
+		},
+		saveFilter: (namespace, filter) => {
+			config.store.dispatch(actions.saveFilter(namespace, filter));
+		},
+		getData: (namespace) => {
+			return config.store.getState().useFilter.data[namespace];
+		},
+		saveData: (namespace, data) => {
+			config.store.dispatch(actions.saveData(namespace, data));
+		},
+		clear: () => {
+			config.store.dispatch(actions.clear());
+		}
+	};
+	return reduxStoreStore;
+}
+const actions = createActions("useFilter", {
+	saveData: (namespace, data) => ({
+		namespace,
+		data
+	}),
+	saveFilter: (namespace, filter) => ({
+		namespace,
+		filter
+	}),
+	clear: () => undefined
+});
+const initialState = {
+	data: {},
+	filters: {}
+};
+const useFilterReduxReducer = createReducer(initialState, (builder) => {
+	builder.addHandler(actions.saveFilter, (state, action) => ({
+		...state,
+		filters: {
+			...state.filters,
+			[action.payload.namespace]: action.payload.filter
+		}
+	})).addHandler(actions.saveData, (state, action) => ({
+		...state,
+		data: {
+			...state.data,
+			[action.payload.namespace]: action.payload.data
+		}
+	})).addHandler(actions.clear, (state) => ({
+		...state,
+		filters: {},
+		data: {}
+	}));
+});
+
+//#endregion
+export { createReduxStore, useFilterReduxReducer };

package/dist/esm/store/urlParamStore.d.mts

@@ -0,0 +1,8 @@
+import { FilterStore } from "./index.mjs";
+
+//#region src/store/urlParamStore.d.ts
+declare const createUrlParamStore: () => FilterStore;
+declare function replaceQueryParams(newParams: string): void;
+declare function naivelyParseExistingParams(): any;
+//#endregion
+export { createUrlParamStore, naivelyParseExistingParams, replaceQueryParams };

package/dist/esm/store/urlParamStore.mjs

@@ -0,0 +1,63 @@
+import qs from "qs";
+
+//#region src/store/urlParamStore.ts
+const createUrlParamStore = () => {
+	const urlParamStore = {
+		getFilter(namespace) {
+			const parsed = naivelyParseExistingParams();
+			const parsedInfo = parsed[`info.${namespace}`];
+			const parsedFilter = parsed[`filter.${namespace}`];
+			if (parsedInfo || parsedFilter) {
+				const { page, offset, pageSize, ...rest } = parsedInfo || {};
+				return {
+					...{
+						page: 1 / page ? +page : undefined,
+						pageSize: 1 / pageSize ? +pageSize : undefined,
+						offset: 1 / offset ? +offset : undefined,
+						...rest
+					},
+					filter: parsedFilter
+				};
+			}
+		},
+		saveFilter(namespace, filterInfo) {
+			const parsed = naivelyParseExistingParams();
+			const clonedInfo = { ...filterInfo };
+			const clonedFilter = filterInfo.filter;
+			delete clonedInfo.filter;
+			delete clonedInfo.lastRefreshAt;
+			delete clonedInfo.shouldRunImmediately;
+			delete clonedInfo.totalResults;
+			delete clonedInfo.totalPages;
+			delete clonedInfo.nextCursor;
+			parsed[`filter.${namespace}`] = clonedFilter;
+			parsed[`info.${namespace}`] = clonedInfo;
+			replaceQueryParams(qs.stringify(parsed));
+		},
+		clear() {
+			const parsed = naivelyParseExistingParams();
+			for (const key in parsed) {
+				if (key.startsWith("filter.") || key.startsWith("info.")) {
+					delete parsed[key];
+				}
+			}
+			replaceQueryParams(qs.stringify(parsed));
+		},
+		getData() {
+			return undefined;
+		},
+		saveData() {}
+	};
+	return urlParamStore;
+};
+function replaceQueryParams(newParams) {
+	const nextUrl = new URL(window.location.toString());
+	nextUrl.search = newParams;
+	window.history.replaceState(undefined, "", nextUrl.toString());
+}
+function naivelyParseExistingParams() {
+	return qs.parse(window.location.search.substring(1));
+}
+
+//#endregion
+export { createUrlParamStore, naivelyParseExistingParams, replaceQueryParams };

package/dist/esm/useFilter.d.mts

@@ -0,0 +1,106 @@
+import { FilterStore } from "./store/index.mjs";
+
+//#region src/useFilter.d.ts
+type MaybePromise<T> = T | Promise<T>;
+interface UseFilterOptions<TFilter extends Record<string, unknown>, TResult> {
+  /**
+   * Default values for your filter. When calling `.reset` your filter will be
+   * set to this.
+   * Changing these values does not cause a call to happen.
+   */
+  defaultFilterInfo?: Partial<FilterInfo<TFilter>>;
+  /**
+   * Enable this if you are not using the data caching of this hook.
+   */
+  shouldForceRunOnMount?: boolean;
+  /**
+   * Called whenever the filter changes.
+   */
+  onChange: (filterInfo: FilterInfo<TFilter>, reason: UseFilterUpdateReason) => MaybePromise<UseFilterOnChangeResult<TFilter, TResult>>;
+  /**
+   * In case you want to change the default debounce duration.
+   */
+  debounceDuration?: number;
+  onBeforeSaveFilter?: (filterInfo: FilterInfo<TFilter>) => FilterInfo<TFilter>;
+  store?: FilterStore;
+}
+interface FilterApi<TFilter extends Record<string, unknown>, TResult> {
+  /**
+   * Whether the system is debouncing or waiting for your `onChange` to finish.
+   */
+  isLoading: boolean;
+  /**
+   * Any cached data for this filter.
+   */
+  data: TResult | null | undefined;
+  /**
+   * Access to the filter and its metadata.
+   */
+  filterInfo: FilterInfo<TFilter>;
+  /**
+   * Whether the filter existed in the system when the component mounted.
+   * @deprecated
+   */
+  doesFilterExist: boolean;
+  /**
+   * Why the last update happened.
+   */
+  updateReason: UseFilterUpdateReason;
+  /**
+   * Update one or more values in your filter.
+   */
+  updateFilter: (filter: Partial<TFilter>, shouldRunImmediately?: boolean) => void;
+  /**
+   * Resets the filter back to `defaultFilterInfo`.
+   */
+  resetFilter: (shouldRunImmediately?: boolean) => void;
+  /**
+   * Changes the offset. Will update `page`.
+   */
+  setOffset: (offset: number | string, shouldRunImmediately?: boolean) => void;
+  /**
+   * Changes the page. Will update `offset`.
+   */
+  setPage: (page: number | string, shouldRunImmediately?: boolean) => void;
+  /**
+   * Changes the page size.
+   */
+  setPageSize: (pageSize: number | string, shouldRunImmediately?: boolean) => void;
+  /**
+   * Change the sort method.
+   */
+  setSort: (sort: string | undefined, shouldRunImmediately?: boolean) => void;
+  /**
+   * Changes the cursor.
+   */
+  setCursor: (cursor: string | null | undefined, shouldRunImmediately?: boolean) => void;
+  /**
+   * Forces a refresh of the filter.
+   */
+  forceRefresh: (shouldRunImmediately?: boolean) => void;
+}
+type UseFilterUpdateReason = 'initial' | 'filter' | 'pagination';
+declare function useFilter<TFilter extends Record<string, unknown>, TResult>(namespace: string, options: UseFilterOptions<TFilter, TResult>): FilterApi<TFilter, TResult>;
+interface FilterInfo<TFilter extends Record<string, unknown>> {
+  filter: TFilter;
+  offset: number;
+  page: number;
+  sort?: string;
+  pageSize: number;
+  lastRefreshAt: number;
+  totalResults: number;
+  totalPages: number;
+  shouldRunImmediately: boolean;
+  cursor?: string | null;
+  nextCursor?: string | null;
+}
+type UseFilterOnChangeResult<TFilter extends Record<string, unknown>, TResult> = void | {
+  filterInfo?: Partial<Omit<FilterInfo<TFilter>, 'totalResults' | 'offset' | 'pageSize'> & {
+    totalResults: string | number;
+    offset: string | number;
+    pageSize: string | number;
+  }>;
+  data?: TResult;
+};
+//#endregion
+export { FilterApi, FilterInfo, UseFilterUpdateReason, useFilter as default };

package/dist/esm/useFilter.mjs

@@ -0,0 +1,251 @@
+import getOffsetFromPage from "./lib/getOffsetFromPage.mjs";
+import getPageFromOffset from "./lib/getPageFromOffset.mjs";
+import buildDefaultFilterInfo from "./lib/buildDefaultFilterInfo.mjs";
+import shallowEqual from "./lib/shallowEqual.mjs";
+import { getFilterStore } from "./store/index.mjs";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/useFilter.ts
+function useFilter(namespace, options) {
+	const ctxRefValue = {
+		namespace,
+		onChange: options.onChange,
+		debounceDuration: options.debounceDuration,
+		defaultFilterInfo: options.defaultFilterInfo,
+		onBeforeSaveFilter: options.onBeforeSaveFilter,
+		store: options.store
+	};
+	const ctxRef = useRef(ctxRefValue);
+	useEffect(() => {
+		ctxRef.current = ctxRefValue;
+	});
+	const [filterInfo, setFilterInfoState] = useState(() => {
+		const fromStore = getFilterStore(ctxRef.current.store).getFilter(namespace);
+		if (fromStore) {
+			const filterInfo = buildDefaultFilterInfo({
+				...fromStore,
+				shouldRunImmediately: true,
+				filter: {
+					...options.defaultFilterInfo?.filter,
+					...fromStore.filter
+				}
+			});
+			return filterInfo;
+		}
+	});
+	const [data, setData] = useState(() => getFilterStore(ctxRef.current.store).getData(namespace));
+	const [isLoading, setIsLoading] = useState(!filterInfo);
+	const doesFilterExist = useRef(!!filterInfo);
+	const lastRefreshAtRef = useRef(options.shouldForceRunOnMount ? -1 : filterInfo ? filterInfo.lastRefreshAt : -1);
+	const updateReasonRef = useRef("initial");
+	useEffect(() => {
+		setIsLoading(true);
+		if (!filterInfo) {
+			setFilterInfoState({
+				...buildDefaultFilterInfo(ctxRef.current.defaultFilterInfo),
+				shouldRunImmediately: true
+			});
+			return;
+		}
+		if (lastRefreshAtRef.current === filterInfo.lastRefreshAt) {
+			setIsLoading(false);
+			return;
+		}
+		const makeRequest = () => {
+			lastRefreshAtRef.current = filterInfo.lastRefreshAt;
+			const response = ctxRef.current.onChange(filterInfo, updateReasonRef.current);
+			getFilterStore(ctxRef.current.store).saveFilter(namespace, ctxRef.current.onBeforeSaveFilter ? ctxRef.current.onBeforeSaveFilter(filterInfo) : filterInfo);
+			if (!response) {
+				setIsLoading(false);
+				return;
+			}
+			function handleResponse(response) {
+				if (!response) {
+					return;
+				}
+				if (response.filterInfo) {
+					setFilterInfoState((previous) => {
+						invariant(!!response.filterInfo, "");
+						invariant(previous != null, "handleResponse called without filterInfo");
+						const extra = {};
+						const { page, offset, totalResults, pageSize, nextCursor, ...filterInfoFromResponse } = response.filterInfo;
+						const pageSizeNumber = Number(pageSize || previous.pageSize);
+						if (page != null && offset == null) {
+							extra.offset = getOffsetFromPage(page, pageSizeNumber);
+							extra.page = page;
+						} else if (page == null && offset != null) {
+							const offsetNumber = Number(offset);
+							extra.offset = offsetNumber;
+							extra.page = getPageFromOffset(offsetNumber, pageSizeNumber);
+						}
+						if ("totalResults" in response.filterInfo) {
+							extra.totalResults = Number(totalResults || 0);
+							extra.totalPages = Math.ceil(extra.totalResults / pageSizeNumber);
+						}
+						if ("nextCursor" in response.filterInfo) {
+							extra.nextCursor = nextCursor;
+						}
+						return {
+							...previous,
+							...filterInfoFromResponse,
+							...extra
+						};
+					});
+				}
+				if (response.data) {
+					setData(response.data);
+					getFilterStore(ctxRef.current.store).saveData(namespace, response.data);
+				}
+			}
+			if (isPromise(response)) {
+				response.then(handleResponse).finally(() => setIsLoading(false));
+			} else {
+				handleResponse(response);
+				setIsLoading(false);
+			}
+		};
+		let timeout = undefined;
+		if (filterInfo.shouldRunImmediately) {
+			makeRequest();
+		} else {
+			timeout = setTimeout(makeRequest, ctxRef.current.debounceDuration != null ? ctxRef.current.debounceDuration : 500);
+		}
+		return () => {
+			if (timeout) {
+				clearTimeout(timeout);
+			}
+		};
+	}, [filterInfo, namespace]);
+	const api = {
+		isLoading,
+		data,
+		doesFilterExist: doesFilterExist.current,
+		filterInfo: filterInfo || buildDefaultFilterInfo(options.defaultFilterInfo),
+		updateReason: updateReasonRef.current,
+		updateFilter: useCallback((filter, shouldRunImmediately = false) => {
+			updateReasonRef.current = "filter";
+			setFilterInfoState((previous) => {
+				invariant(previous != null, "updateFilter called without filterInfo");
+				const nextFilter = {
+					...previous.filter,
+					...filter
+				};
+				if (shallowEqual(previous.filter, nextFilter)) {
+					return previous;
+				}
+				return {
+					...previous,
+					offset: 0,
+					page: 1,
+					totalResults: 1,
+					totalPages: 1,
+					filter: nextFilter,
+					lastRefreshAt: new Date().getTime(),
+					cursor: undefined,
+					nextCursor: undefined,
+					shouldRunImmediately
+				};
+			});
+		}, []),
+		resetFilter: useCallback((shouldRunImmediately = false) => {
+			updateReasonRef.current = "filter";
+			setFilterInfoState({
+				...buildDefaultFilterInfo(ctxRef.current.defaultFilterInfo),
+				lastRefreshAt: new Date().getTime(),
+				shouldRunImmediately
+			});
+		}, []),
+		setOffset: useCallback((offset, shouldRunImmediately = false) => {
+			updateReasonRef.current = "pagination";
+			setFilterInfoState((previous) => {
+				invariant(previous != null, "setOffset called without filterInfo");
+				const offsetNumber = Number(offset);
+				return {
+					...previous,
+					offset: offsetNumber,
+					page: getPageFromOffset(offsetNumber, previous.pageSize),
+					lastRefreshAt: new Date().getTime(),
+					shouldRunImmediately
+				};
+			});
+		}, []),
+		setPage: useCallback((page, shouldRunImmediately = false) => {
+			updateReasonRef.current = "pagination";
+			setFilterInfoState((previous) => {
+				invariant(previous != null, "setPage called without filterInfo");
+				const pageNumber = Number(page);
+				return {
+					...previous,
+					offset: getOffsetFromPage(pageNumber, previous.pageSize),
+					page: pageNumber,
+					lastRefreshAt: new Date().getTime(),
+					shouldRunImmediately
+				};
+			});
+		}, []),
+		setPageSize: useCallback((pageSize, shouldRunImmediately = false) => {
+			updateReasonRef.current = "pagination";
+			setFilterInfoState((previous) => {
+				invariant(previous != null, "setPageSize called without filterInfo");
+				const pageSizeNumber = Number(pageSize);
+				const page = getPageFromOffset(previous.offset, pageSizeNumber);
+				const offset = getOffsetFromPage(page, pageSizeNumber);
+				return {
+					...previous,
+					pageSize: pageSizeNumber,
+					offset,
+					page,
+					lastRefreshAt: new Date().getTime(),
+					shouldRunImmediately
+				};
+			});
+		}, []),
+		setSort: useCallback((sort, shouldRunImmediately = false) => {
+			updateReasonRef.current = "filter";
+			setFilterInfoState((previous) => {
+				invariant(previous != null, "setSort called without filterInfo");
+				return {
+					...previous,
+					sort,
+					lastRefreshAt: new Date().getTime(),
+					shouldRunImmediately
+				};
+			});
+		}, []),
+		setCursor: useCallback((cursor, shouldRunImmediately = false) => {
+			setFilterInfoState((previous) => {
+				updateReasonRef.current = "pagination";
+				invariant(previous != null, "setCursor called without filterInfo");
+				return {
+					...previous,
+					cursor,
+					lastRefreshAt: new Date().getTime(),
+					shouldRunImmediately
+				};
+			});
+		}, []),
+		forceRefresh: useCallback((shouldRunImmediately = false) => {
+			updateReasonRef.current = "filter";
+			setFilterInfoState((previous) => {
+				invariant(previous != null, "forceRefresh called without filterInfo");
+				return {
+					...previous,
+					lastRefreshAt: new Date().getTime(),
+					shouldRunImmediately
+				};
+			});
+		}, [])
+	};
+	return api;
+}
+function invariant(input, message) {
+	if (!input) {
+		throw new Error(`Invariant error: ${message}`);
+	}
+}
+function isPromise(t) {
+	return !!t?.then;
+}
+
+//#endregion
+export { useFilter as default };