@promoboxx/use-filter 2.0.0 → 2.0.1

package/dist/esm/useSimpleFilter.d.mts

@@ -0,0 +1,89 @@
+import { FilterStore } from "./store/index.mjs";
+import { UseFilterUpdateReason } from "./useFilter.mjs";
+
+//#region src/useSimpleFilter.d.ts
+interface UseSimpleFilterOptions<TFilter> {
+  /**
+   * 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<SimpleFilterInfo<TFilter>>;
+  /**
+   * In case you want to change the default debounce duration.
+   */
+  debounceDuration?: number;
+  onBeforeSaveFilter?: (filterInfo: SimpleFilterInfo<TFilter>) => SimpleFilterInfo<TFilter>;
+  store?: FilterStore;
+}
+interface SimpleFilterApi<TFilter> {
+  /**
+   * Really more "is debouncing", since simple mode doesn't know when your code
+   * is doing anything.
+   */
+  isLoading: boolean;
+  /**
+   * Access to the filter and its metadata.
+   */
+  filterInfo: SimpleFilterInfo<TFilter>;
+  /**
+   * Same as the regular `filterInfo`, but updates in a debounced fashion.
+   */
+  debouncedFilterInfo: SimpleFilterInfo<TFilter>;
+  /**
+   * Why the last update happened.
+   */
+  updateReason: UseFilterUpdateReason;
+  /**
+   * Update one or more values in your filter.
+   */
+  updateFilter: (filter: Partial<TFilter>, shouldRunImmediately?: boolean) => void;
+  /**
+   * Does the boring math for you based on your `pageSize` and `totalResults`.
+   */
+  pagingInfo: (total: string | number | null | undefined) => {
+    totalResults: number;
+    totalPages: number;
+  };
+  /**
+   * 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, shouldRunImmediately?: boolean) => void;
+  /**
+   * Changes the cursor.
+   */
+  setCursor: (cursor: string | null | undefined, shouldRunImmediately?: boolean) => void;
+  /**
+   * Forces a refresh of the filter.
+   */
+  forceRefresh: (shouldRunImmediately?: boolean) => void;
+}
+interface SimpleFilterInfo<TFilter> {
+  filter: TFilter;
+  sort?: string;
+  offset: number;
+  page: number;
+  pageSize: number;
+  lastRefreshAt: number;
+  cursor?: string | null;
+  shouldRunImmediately: boolean;
+}
+declare function useSimpleFilter<TFilter extends Record<string, unknown>>(namespace: string, options: UseSimpleFilterOptions<TFilter>): SimpleFilterApi<TFilter>;
+//#endregion
+export { SimpleFilterApi, SimpleFilterInfo, useSimpleFilter as default };

package/dist/esm/useSimpleFilter.mjs

@@ -0,0 +1,198 @@
+import getOffsetFromPage from "./lib/getOffsetFromPage.mjs";
+import getPageFromOffset from "./lib/getPageFromOffset.mjs";
+import shallowEqual from "./lib/shallowEqual.mjs";
+import { getFilterStore } from "./store/index.mjs";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/useSimpleFilter.ts
+function useSimpleFilter(namespace, options) {
+	const ctxRefValue = {
+		namespace,
+		debounceDuration: options.debounceDuration,
+		defaultFilterInfo: options.defaultFilterInfo,
+		onBeforeSaveFilter: options.onBeforeSaveFilter,
+		store: options.store
+	};
+	const ctxRef = useRef(ctxRefValue);
+	useEffect(() => {
+		ctxRef.current = ctxRefValue;
+	});
+	const [isLoading, setIsLoading] = useState(false);
+	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;
+		} else {
+			return buildDefaultFilterInfo({
+				...options.defaultFilterInfo,
+				shouldRunImmediately: true
+			});
+		}
+	});
+	const [debouncedFilterInfo, setDebouncedFilterInfo] = useState(filterInfo);
+	const lastRefreshAtRef = useRef(-1);
+	const updateReasonRef = useRef("initial");
+	useEffect(() => {
+		setIsLoading(true);
+		if (lastRefreshAtRef.current === filterInfo.lastRefreshAt) {
+			setIsLoading(false);
+			return;
+		}
+		let timeout = undefined;
+		function makeRequest() {
+			lastRefreshAtRef.current = filterInfo.lastRefreshAt;
+			getFilterStore(ctxRef.current.store).saveFilter(ctxRef.current.namespace, ctxRef.current.onBeforeSaveFilter ? ctxRef.current.onBeforeSaveFilter(filterInfo) : filterInfo);
+			setDebouncedFilterInfo(filterInfo);
+			setIsLoading(false);
+		}
+		if (filterInfo.shouldRunImmediately) {
+			makeRequest();
+		} else {
+			timeout = setTimeout(makeRequest, ctxRef.current.debounceDuration ?? 500);
+		}
+		return () => {
+			if (timeout) {
+				clearTimeout(timeout);
+			}
+		};
+	}, [filterInfo]);
+	const previousTotalRef = useRef(0);
+	const api = {
+		isLoading,
+		filterInfo,
+		debouncedFilterInfo,
+		updateReason: updateReasonRef.current,
+		updateFilter: useCallback((filter, shouldRunImmediately = false) => {
+			updateReasonRef.current = "filter";
+			setFilterInfoState((previous) => {
+				const nextFilter = {
+					...previous.filter,
+					...filter
+				};
+				if (shallowEqual(previous.filter, nextFilter)) {
+					return previous;
+				}
+				return {
+					...previous,
+					shouldRunImmediately,
+					offset: 0,
+					page: 1,
+					totalResults: 1,
+					totalPages: 1,
+					filter: nextFilter,
+					cursor: undefined,
+					lastRefreshAt: new Date().getTime()
+				};
+			});
+		}, []),
+		pagingInfo: useCallback((total) => {
+			const normalized = Number(total == null ? previousTotalRef.current : total);
+			previousTotalRef.current = normalized;
+			return {
+				totalResults: normalized,
+				totalPages: Math.ceil(normalized / filterInfo.pageSize)
+			};
+		}, [filterInfo.pageSize]),
+		resetFilter: useCallback((shouldRunImmediately = false) => {
+			updateReasonRef.current = "filter";
+			setFilterInfoState({
+				...buildDefaultFilterInfo(ctxRef.current.defaultFilterInfo),
+				shouldRunImmediately
+			});
+		}, []),
+		setOffset: useCallback((offset, shouldRunImmediately = false) => {
+			updateReasonRef.current = "pagination";
+			const offsetNumber = Number(offset);
+			setFilterInfoState((previous) => ({
+				...previous,
+				offset: offsetNumber,
+				page: getPageFromOffset(offsetNumber, previous.pageSize),
+				lastRefreshAt: new Date().getTime(),
+				shouldRunImmediately
+			}));
+		}, []),
+		setPage: useCallback((page, shouldRunImmediately = false) => {
+			updateReasonRef.current = "pagination";
+			const pageNumber = Number(page);
+			setFilterInfoState((previous) => ({
+				...previous,
+				offset: getOffsetFromPage(pageNumber, previous.pageSize),
+				page: pageNumber,
+				lastRefreshAt: new Date().getTime(),
+				shouldRunImmediately
+			}));
+		}, []),
+		setPageSize: useCallback((pageSize, shouldRunImmediately = false) => {
+			updateReasonRef.current = "pagination";
+			setFilterInfoState((previous) => {
+				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) => ({
+				...previous,
+				sort,
+				lastRefreshAt: new Date().getTime(),
+				shouldRunImmediately
+			}));
+		}, []),
+		setCursor: useCallback((cursor, shouldRunImmediately = false) => {
+			updateReasonRef.current = "pagination";
+			setFilterInfoState((previous) => ({
+				...previous,
+				cursor,
+				lastRefreshAt: new Date().getTime(),
+				shouldRunImmediately
+			}));
+		}, []),
+		forceRefresh: useCallback((shouldRunImmediately = false) => {
+			updateReasonRef.current = "filter";
+			setFilterInfoState((previous) => ({
+				...previous,
+				lastRefreshAt: new Date().getTime(),
+				shouldRunImmediately
+			}));
+		}, [])
+	};
+	return api;
+}
+function buildDefaultFilterInfo(filterInfo = {}) {
+	const merged = {
+		filter: {},
+		sort: undefined,
+		pageSize: 20,
+		lastRefreshAt: new Date().getTime(),
+		offset: 0,
+		page: 1,
+		shouldRunImmediately: false,
+		...filterInfo
+	};
+	if (filterInfo.page != null && filterInfo.offset == null) {
+		merged.offset = getOffsetFromPage(filterInfo.page, merged.pageSize);
+	} else if (filterInfo.page == null && filterInfo.offset != null) {
+		merged.page = getPageFromOffset(filterInfo.offset, merged.pageSize);
+	}
+	return merged;
+}
+
+//#endregion
+export { useSimpleFilter as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promoboxx/use-filter",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "",
   "main": "./dist/cjs/useFilter.js",
   "module": "./dist/esm/useFilter.mjs",

package/.github/workflows/main.yml

@@ -1,38 +0,0 @@
-name: CI
-on: push
-
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v2
-
-      - uses: jdx/mise-action@v2
-
-      - name: Get pnpm store directory
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-
-      - uses: actions/cache@v3
-        name: Setup pnpm cache
-        with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
-
-      # https://github.community/t/github-actions-bot-email-address/17204/5
-      - name: Prep for git push
-        run: |
-          git config --local user.name "github-actions[bot]"
-          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
-
-      - name: Prep NPM
-        run: npm config set '//registry.npmjs.org/:_authToken' "${{secrets.NPM_TOKEN}}"
-
-      - run: make prepare-env
-      - run: make test
-      - run: make build
-      - run: make deploy

package/.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-  "typescript.tsdk": "node_modules/typescript/lib"
-}

package/CHANGELOG.md

@@ -1,185 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
-
-## 2.0.0 (2026-06-07)
-
-
-### ⚠ BREAKING CHANGES
-
-* ESM + CJS and various upgrades (#23)
-
-### Features
-
-* ESM + CJS and various upgrades ([#23](https://github.com/promoboxx/use-filter/issues/23)) ([e898ea7](https://github.com/promoboxx/use-filter/commit/e898ea782effbbaa21f3cfe71b44cd007a5c54d2))
-
-### 1.11.2 (2023-08-01)
-
-### 1.11.1 (2023-06-12)
-
-
-### Bug Fixes
-
-* Handle partial persisted `FilterInfo` / `TFilter` ([#21](https://github.com/promoboxx/use-filter/issues/21)) ([45e54ae](https://github.com/promoboxx/use-filter/commit/45e54ae960fdc2df2b37f8a9b59c2cc9dc5bc277))
-
-## 1.11.0 (2023-05-25)
-
-
-### Features
-
-* Add `store` to hooks ([#20](https://github.com/promoboxx/use-filter/issues/20)) ([d7232cd](https://github.com/promoboxx/use-filter/commit/d7232cdca3b660020acb8d82a7b2464e3237bd87))
-
-## 1.10.0 (2023-05-24)
-
-
-### Features
-
-* DEV-7161: URL param store ([#19](https://github.com/promoboxx/use-filter/issues/19)) ([ea658f3](https://github.com/promoboxx/use-filter/commit/ea658f3eb6343ddca8bfaa23af5b5cf4335f0428))
-
-### 1.9.1 (2023-03-27)
-
-
-### Bug Fixes
-
-* Better check for totalResults / nextCursor in onChange response ([#18](https://github.com/promoboxx/use-filter/issues/18)) ([3cecc45](https://github.com/promoboxx/use-filter/commit/3cecc45d12f36895498dbb9d38fdb0f1220ca3af))
-
-## 1.9.0 (2023-03-16)
-
-
-### Features
-
-* DEV-6808: Add `onBeforeSaveFilter` ([#17](https://github.com/promoboxx/use-filter/issues/17)) ([f1f6f0b](https://github.com/promoboxx/use-filter/commit/f1f6f0b5e9befcf9fc001223bbf1ddd9d39b1fed))
-
-### 1.8.3 (2023-03-16)
-
-
-### Bug Fixes
-
-* DEV-6994: Reset cursor when filters change ([#16](https://github.com/promoboxx/use-filter/issues/16)) ([9115b92](https://github.com/promoboxx/use-filter/commit/9115b9201d257afb9d1d0dcf7ddd7af23ad1abc9))
-
-### 1.8.2 (2022-12-07)
-
-### 1.8.1 (2022-12-04)
-
-## 1.8.0 (2022-11-25)
-
-
-### Features
-
-* Concept of "update reason" ([#14](https://github.com/promoboxx/use-filter/issues/14)) ([0b34cd3](https://github.com/promoboxx/use-filter/commit/0b34cd3854b2d49128998cb5a0fff9c05627ff31))
-
-## 1.7.0 (2022-11-25)
-
-
-### Features
-
-* Cursor Pagination ([#13](https://github.com/promoboxx/use-filter/issues/13)) ([4df58f6](https://github.com/promoboxx/use-filter/commit/4df58f6a24004a7655f1e5c4d97db4c05e0613d7))
-
-## 1.6.0 (2022-06-02)
-
-
-### Features
-
-* `setPageSize` helper ([#12](https://github.com/promoboxx/use-filter/issues/12)) ([364b1b8](https://github.com/promoboxx/use-filter/commit/364b1b80acdeef3a6464a2b8fcb1c2bea30ad54a))
-
-### 1.5.4 (2022-05-25)
-
-
-### Bug Fixes
-
-* When filter exists in useFilter, run immediately on mount ([#11](https://github.com/promoboxx/use-filter/issues/11)) ([50338e9](https://github.com/promoboxx/use-filter/commit/50338e91c0ddeff969e05a63450d90a368a63c08))
-
-### 1.5.3 (2022-05-21)
-
-
-### Bug Fixes
-
-* Simple mode immediate on mount ([#10](https://github.com/promoboxx/use-filter/issues/10)) ([c5b7023](https://github.com/promoboxx/use-filter/commit/c5b7023ed5e7c80b2948048a32e195ec0f36eacd))
-
-### 1.5.2 (2022-05-21)
-
-
-### Bug Fixes
-
-* "Advanced" mode is always immediate ([#9](https://github.com/promoboxx/use-filter/issues/9)) ([2a2fdad](https://github.com/promoboxx/use-filter/commit/2a2fdad8d80b9cf98a0729e8f360ed00f71b5e38))
-
-### 1.5.1 (2022-05-20)
-
-
-### Bug Fixes
-
-* Update package files ([#8](https://github.com/promoboxx/use-filter/issues/8)) ([c06fc1e](https://github.com/promoboxx/use-filter/commit/c06fc1ef8fc9ff6faf177a7535a4a03984c5c750))
-
-## 1.5.0 (2022-05-19)
-
-
-### Features
-
-* Add useSimpleFilter ([#7](https://github.com/promoboxx/use-filter/issues/7)) ([c103e8e](https://github.com/promoboxx/use-filter/commit/c103e8e675998099f0c990a2b062335e926fd869))
-
-## 1.4.0 (2022-05-16)
-
-
-### Features
-
-* Add `shouldRunImmediately` and refactor ([#6](https://github.com/promoboxx/use-filter/issues/6)) ([9f6bf0b](https://github.com/promoboxx/use-filter/commit/9f6bf0bc1be7563a1b29920a09a5794c02d506fc))
-
-## 1.3.0 (2021-07-18)
-
-
-### Features
-
-* Redux store ([#5](https://github.com/promoboxx/use-filter/issues/5)) ([f92bee6](https://github.com/promoboxx/use-filter/commit/f92bee6417f78117ab9ca4936c23b24647aac008))
-
-### 1.2.1 (2021-07-17)
-
-
-### Bug Fixes
-
-* some git stuff is needed ([2bb0f21](https://github.com/promoboxx/use-filter/commit/2bb0f2117c79fd1ba0b6a309db4234caf162f57b))
-
-## 1.2.0 (2021-07-16)
-
-
-### Features
-
-* Add localStorageStore ([#4](https://github.com/promoboxx/use-filter/issues/4)) ([a6087e2](https://github.com/promoboxx/use-filter/commit/a6087e2f07a3640799b840e128b96838cd8ef150))
-
-## 1.1.0 (2021-07-16)
-
-
-### Features
-
-* Add concept of data to useFilter ([#2](https://github.com/promoboxx/use-filter/issues/2)) ([563c5a9](https://github.com/promoboxx/use-filter/commit/563c5a959cdc22a0f8eba9dbb3dde7802df02b46))
-
-### 1.0.6 (2021-07-16)
-
-
-### Bug Fixes
-
-* dont deploy test files ([500151c](https://github.com/promoboxx/use-filter/commit/500151c04f75139c71baf29b2ad2dccefcd57db7))
-
-### 1.0.5 (2021-07-16)
-
-
-### Bug Fixes
-
-* declaration files ([4ce29e4](https://github.com/promoboxx/use-filter/commit/4ce29e43469ad4ade2d222c3b09f38ad8f89ca4c))
-
-### 1.0.4 (2021-07-16)
-
-
-### Bug Fixes
-
-* more release prep ([daf06ac](https://github.com/promoboxx/use-filter/commit/daf06acc94668fdc7f0905c120f5541b4b2d16e9))
-
-### 1.0.3 (2021-07-16)
-
-### 1.0.2 (2021-07-16)
-
-
-### Bug Fixes
-
-* proper secrets syntax ([afc9fe9](https://github.com/promoboxx/use-filter/commit/afc9fe9b177dda2961d82858ef43cc481f762950))
-
-### 1.0.1 (2021-07-16)

package/Makefile

@@ -1,25 +0,0 @@
-prepare-env:
-	pnpm install
-
-prepare-when-local:
-ifneq ($(CI),true)
-	$(MAKE) prepare-env
-endif
-
-start: test
-
-build: prepare-when-local
-	rm -rf dist/
-	./node_modules/.bin/tsc --noEmit
-	./node_modules/.bin/eslint --max-warnings 0 --ext js,jsx,ts,tsx,mjs,cjs src/
-	./node_modules/.bin/tsdown
-
-test: prepare-when-local
-	./node_modules/.bin/vitest
-
-deploy:
-ifeq ($(GITHUB_REF),refs/heads/main)
-	npx standard-version
-	git push origin --tags HEAD
-	npm publish
-endif

package/eslint.config.js

@@ -1,30 +0,0 @@
-import pbxxBase from '@promoboxx/eslint-config'
-import pbxxPrettier from '@promoboxx/eslint-config/prettier'
-import pbxxReact from '@promoboxx/eslint-config/react'
-
-/** @type {import('eslint').Linter.Config[]} */
-const config = [
-  ...pbxxBase,
-  ...pbxxPrettier,
-  ...pbxxReact,
-
-  {
-    files: ['**/*.test.{ts,tsx}'],
-    rules: {
-      '@typescript-eslint/no-non-null-assertion': 'off',
-    },
-  },
-
-  // TODO This project is old, and while it is a library, has way too many
-  // `any` and casts. Disabled for now, but should be re-enabled and fixed up
-  // over time.
-  {
-    files: ['**/*.{js,jsx,ts,tsx}'],
-    rules: {
-      '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/consistent-type-assertions': 'off',
-    },
-  },
-]
-
-export default config

package/mise.toml

@@ -1,3 +0,0 @@
-[tools]
-node = "24.16.0"
-pnpm = "11.5.0"

package/prettier.config.js

@@ -1,3 +0,0 @@
-import config from '@promoboxx/eslint-config/prettier.config'
-
-export default config

package/src/lib/buildDefaultFilterInfo.ts

@@ -1,36 +0,0 @@
-import type { FilterInfo } from '../useFilter'
-
-import getOffsetFromPage from './getOffsetFromPage'
-import getPageFromOffset from './getPageFromOffset'
-
-function buildDefaultFilterInfo<T extends Record<string, unknown>>(
-  filterInfo: Partial<FilterInfo<T>> = {},
-): FilterInfo<T> {
-  const merged: FilterInfo<T> = {
-    // Cast here to work around "'T' could be instantiated with an arbitrary
-    // type which could be unrelated to '{}'"
-    filter: {} as T,
-
-    sort: undefined,
-    pageSize: 20,
-    lastRefreshAt: new Date().getTime(),
-    totalResults: 1,
-    totalPages: 1,
-    offset: 0,
-    page: 1,
-    shouldRunImmediately: false,
-    ...filterInfo,
-  }
-
-  // If there's a page but no offset, set the offset.
-  if (filterInfo.page != null && filterInfo.offset == null) {
-    merged.offset = getOffsetFromPage(filterInfo.page, merged.pageSize)
-    // If there's an offset but no page, set the page.
-  } else if (filterInfo.page == null && filterInfo.offset != null) {
-    merged.page = getPageFromOffset(filterInfo.offset, merged.pageSize)
-  }
-
-  return merged
-}
-
-export default buildDefaultFilterInfo

package/src/lib/getOffsetFromPage.ts

@@ -1,5 +0,0 @@
-function getOffsetFromPage(page: number, pageSize: number) {
-  return pageSize * (page - 1)
-}
-
-export default getOffsetFromPage

package/src/lib/getPageFromOffset.ts

@@ -1,5 +0,0 @@
-function getPageFromOffset(offset: number, pageSize: number) {
-  return Math.floor(offset / pageSize) + 1
-}
-
-export default getPageFromOffset