@promoboxx/use-filter 1.0.2

package/.eslintrc.js

@@ -0,0 +1,19 @@
+module.exports = {
+  extends: [
+    // Base config applies to all projects.
+    '@promoboxx/eslint-config',
+    // If the project uses prettier:
+    '@promoboxx/eslint-config/prettier',
+    // If the project uses jest:
+    '@promoboxx/eslint-config/jest',
+    // If the project uses react:
+    '@promoboxx/eslint-config/react',
+    // If the project uses graphql:
+    // '@promoboxx/eslint-config/graphql',
+  ],
+  parserOptions: {
+    // If the project uses graphql, set the path/url to your schema below.
+    // skipGraphQLConfig: true,
+    // schema: 'node_modules/@promoboxx/graphql-server-types/graphql.schema.json',
+  },
+}

package/.github/workflows/main.yml

@@ -0,0 +1,32 @@
+name: CI
+on: push
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Cache node modules
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.npm
+            **/node_modules
+          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
+
+      # https://github.community/t/github-actions-bot-email-address/17204/5
+      - name: Prep for git push
+        run: |
+          git config --local user.name "${{secrets.GH_BOT_NAME}}"
+          git config --local user.email "41898282+${{secrets.GH_BOT_NAME}}@users.noreply.github.com"
+          git remote set-url origin "https://${{secrets.GH_BOT_NAME}}:${{secrets.GH_TOKEN}}@github.com/${GITHUB_REPOSITORY}.git"
+
+      - 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

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

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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.
+
+### 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

@@ -0,0 +1,31 @@
+prepare-env:
+ifeq ($(CI),true)
+	npm ci --ignore-scripts
+else
+	npm install
+endif
+
+prepare-when-local:
+ifneq ($(CI),true)
+	$(MAKE) prepare-env
+endif
+
+start: test
+
+build: prepare-when-local
+	rm -rf dist/
+	npx tsc
+
+test: prepare-when-local
+ifeq ($(CI),true)
+	npx jest --ci
+else
+	npx jest --watch
+endif
+
+deploy:
+ifeq ($(GITHUB_REF),refs/heads/main)
+	npx standard-version
+	git push origin --tags HEAD
+	npm publish
+endif

package/jest.config.js

@@ -0,0 +1,196 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+const config = {
+  // All imported modules in your tests should be mocked automatically
+  // automock: false,
+
+  // Stop running tests after `n` failures
+  // bail: 0,
+
+  // The directory where Jest should store its cached dependency information
+  // cacheDirectory: "/tmp/jest_rs",
+
+  // Automatically clear mock calls and instances between every test
+  clearMocks: true,
+
+  // Indicates whether the coverage information should be collected while executing the test
+  // collectCoverage: false,
+
+  // An array of glob patterns indicating a set of files for which coverage information should be collected
+  // collectCoverageFrom: undefined,
+
+  // The directory where Jest should output its coverage files
+  // coverageDirectory: undefined,
+
+  // An array of regexp pattern strings used to skip coverage collection
+  // coveragePathIgnorePatterns: [
+  //   "/node_modules/"
+  // ],
+
+  // Indicates which provider should be used to instrument code for coverage
+  coverageProvider: 'v8',
+
+  // A list of reporter names that Jest uses when writing coverage reports
+  // coverageReporters: [
+  //   "json",
+  //   "text",
+  //   "lcov",
+  //   "clover"
+  // ],
+
+  // An object that configures minimum threshold enforcement for coverage results
+  // coverageThreshold: undefined,
+
+  // A path to a custom dependency extractor
+  // dependencyExtractor: undefined,
+
+  // Make calling deprecated APIs throw helpful error messages
+  // errorOnDeprecated: false,
+
+  // Force coverage collection from ignored files using an array of glob patterns
+  // forceCoverageMatch: [],
+
+  // A path to a module which exports an async function that is triggered once before all test suites
+  // globalSetup: undefined,
+
+  // A path to a module which exports an async function that is triggered once after all test suites
+  // globalTeardown: undefined,
+
+  // A set of global variables that need to be available in all test environments
+  // globals: {},
+
+  // The maximum amount of workers used to run your tests. Can be specified as % or a number. E.g. maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker number. maxWorkers: 2 will use a maximum of 2 workers.
+  // maxWorkers: "50%",
+
+  // An array of directory names to be searched recursively up from the requiring module's location
+  // moduleDirectories: [
+  //   "node_modules"
+  // ],
+
+  // An array of file extensions your modules use
+  // moduleFileExtensions: [
+  //   "js",
+  //   "jsx",
+  //   "ts",
+  //   "tsx",
+  //   "json",
+  //   "node"
+  // ],
+
+  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
+  // moduleNameMapper: {},
+
+  // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
+  // modulePathIgnorePatterns: [],
+
+  // Activates notifications for test results
+  // notify: false,
+
+  // An enum that specifies notification mode. Requires { notify: true }
+  // notifyMode: "failure-change",
+
+  // A preset that is used as a base for Jest's configuration
+  preset: 'ts-jest/presets/js-with-ts',
+
+  // Run tests from one or more projects
+  // projects: undefined,
+
+  // Use this configuration option to add custom reporters to Jest
+  // reporters: undefined,
+
+  // Automatically reset mock state between every test
+  // resetMocks: false,
+
+  // Reset the module registry before running each individual test
+  // resetModules: false,
+
+  // A path to a custom resolver
+  // resolver: undefined,
+
+  // Automatically restore mock state between every test
+  // restoreMocks: false,
+
+  // The root directory that Jest should scan for tests and modules within
+  // rootDir: undefined,
+
+  // A list of paths to directories that Jest should use to search for files in
+  // roots: [
+  //   "<rootDir>"
+  // ],
+
+  // Allows you to use a custom runner instead of Jest's default test runner
+  // runner: "jest-runner",
+
+  // The paths to modules that run some code to configure or set up the testing environment before each test
+  // setupFiles: [],
+
+  // A list of paths to modules that run some code to configure or set up the testing framework before each test
+  // setupFilesAfterEnv: [],
+
+  // The number of seconds after which a test is considered as slow and reported as such in the results.
+  // slowTestThreshold: 5,
+
+  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
+  // snapshotSerializers: [],
+
+  // The test environment that will be used for testing
+  testEnvironment: 'jsdom',
+
+  // Options that will be passed to the testEnvironment
+  // testEnvironmentOptions: {},
+
+  // Adds a location field to test results
+  // testLocationInResults: false,
+
+  // The glob patterns Jest uses to detect test files
+  // testMatch: [
+  //   "**/__tests__/**/*.[jt]s?(x)",
+  //   "**/?(*.)+(spec|test).[tj]s?(x)"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
+  // testPathIgnorePatterns: [
+  //   "/node_modules/"
+  // ],
+
+  // The regexp pattern or array of patterns that Jest uses to detect test files
+  // testRegex: [],
+
+  // This option allows the use of a custom results processor
+  // testResultsProcessor: undefined,
+
+  // This option allows use of a custom test runner
+  // testRunner: "jest-circus/runner",
+
+  // This option sets the URL for the jsdom environment. It is reflected in properties such as location.href
+  // testURL: "http://localhost",
+
+  // Setting this value to "fake" allows the use of fake timers for functions such as "setTimeout"
+  // timers: "real",
+
+  // A map from regular expressions to paths to transformers
+  // transform: undefined,
+
+  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
+  // transformIgnorePatterns: [
+  //   "/node_modules/",
+  //   "\\.pnp\\.[^\\/]+$"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
+  // unmockedModulePathPatterns: undefined,
+
+  // Indicates whether each individual test should be reported during the run
+  verbose: true,
+
+  // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
+  // watchPathIgnorePatterns: [],
+
+  // Whether to use watchman for file crawling
+  // watchman: true,
+}
+
+module.exports = config

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@promoboxx/use-filter",
+  "version": "1.0.2",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@promoboxx/eslint-config": "^2.3.0",
+    "@testing-library/react": "^12.0.0",
+    "@types/jest": "^26.0.24",
+    "@types/react": "^17.0.14",
+    "eslint": "^7.30.0",
+    "jest": "^27.0.6",
+    "prettier": "^2.3.2",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "ts-jest": "^27.0.3",
+    "typescript": "^4.3.5"
+  }
+}

package/prettier.config.js

@@ -0,0 +1 @@
+module.exports = require('@promoboxx/eslint-config/prettier.config')

package/src/lib/buildDefaultFilterInfo.ts

@@ -0,0 +1,35 @@
+import { FilterInfo } from '../useFilter'
+
+import getOffsetFromPage from './getOffsetFromPage'
+import getPageFromOffset from './getPageFromOffset'
+
+function buildDefaultFilterInfo<T>(
+  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,
+    ...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

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

package/src/lib/getPageFromOffset.ts

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

package/src/lib/shallowEqual.test.ts

@@ -0,0 +1,71 @@
+import shallowEqual from './shallowEqual'
+
+describe('shallowEqual', () => {
+  it('should return true if arguments fields are equal', () => {
+    expect(
+      shallowEqual({ a: 1, b: 2, c: undefined }, { a: 1, b: 2, c: undefined }),
+    ).toBe(true)
+
+    expect(shallowEqual({ a: 1, b: 2, c: 3 }, { a: 1, b: 2, c: 3 })).toBe(true)
+
+    const o = {}
+    expect(shallowEqual({ a: 1, b: 2, c: o }, { a: 1, b: 2, c: o })).toBe(true)
+
+    const d = function () {
+      return 1
+    }
+    expect(shallowEqual({ a: 1, b: 2, c: o, d }, { a: 1, b: 2, c: o, d })).toBe(
+      true,
+    )
+  })
+
+  it('should return false if arguments fields are different function identities', () => {
+    expect(
+      shallowEqual(
+        {
+          a: 1,
+          b: 2,
+          d() {
+            return 1
+          },
+        },
+        {
+          a: 1,
+          b: 2,
+          d() {
+            return 1
+          },
+        },
+      ),
+    ).toBe(false)
+  })
+
+  it('should return false if first argument has too many keys', () => {
+    expect(shallowEqual({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 })).toBe(false)
+  })
+
+  it('should return false if second argument has too many keys', () => {
+    expect(shallowEqual({ a: 1, b: 2 }, { a: 1, b: 2, c: 3 })).toBe(false)
+  })
+
+  it('should return false if arguments have different keys', () => {
+    expect(
+      shallowEqual({ a: 1, b: 2, c: undefined }, { a: 1, bb: 2, c: undefined }),
+    ).toBe(false)
+  })
+
+  it('should compare two NaN values', () => {
+    expect(shallowEqual(NaN, NaN)).toBe(true)
+  })
+
+  it('should compare empty objects, with false', () => {
+    expect(shallowEqual({}, false)).toBe(false)
+    expect(shallowEqual(false, {})).toBe(false)
+    expect(shallowEqual([], false)).toBe(false)
+    expect(shallowEqual(false, [])).toBe(false)
+  })
+
+  it('should compare two zero values', () => {
+    expect(shallowEqual(0, 0)).toBe(true)
+  })
+})

package/src/lib/shallowEqual.ts

@@ -0,0 +1,26 @@
+const shallowEqual = (objA: any, objB: any) => {
+  if (Object.is(objA, objB)) {
+    return true
+  }
+
+  if (typeof objA !== 'object' || !objA || typeof objB !== 'object' || !objB) {
+    return false
+  }
+
+  const keysA = Object.keys(objA)
+  const keysB = Object.keys(objB)
+
+  if (keysA.length !== keysB.length) {
+    return false
+  }
+
+  for (const key of keysA) {
+    if (!Object.is(objA[key], objB[key])) {
+      return false
+    }
+  }
+
+  return true
+}
+
+export default shallowEqual

package/src/store/index.ts

@@ -0,0 +1,21 @@
+import { FilterInfo } from '../useFilter'
+
+export interface FilterStore {
+  getFilter(namespace: string): FilterInfo<any> | null | undefined
+  saveFilter(namespace: string, filter: FilterInfo<any>): void
+  clear(): void
+}
+
+let store: FilterStore | undefined
+
+export function setFilterStore(newStore: FilterStore) {
+  store = newStore
+}
+
+export function getFilterStore() {
+  if (!store) {
+    throw new Error('A store must be set with setFilterStore')
+  }
+
+  return store
+}

package/src/store/memoryStore.ts

@@ -0,0 +1,19 @@
+import { FilterInfo } from '../useFilter'
+
+import { FilterStore } from '.'
+
+let filters: Record<string, FilterInfo<any>> = {}
+
+const memoryStore: FilterStore = {
+  getFilter(namespace) {
+    return filters[namespace]
+  },
+  saveFilter(namespace, filter) {
+    filters[namespace] = filter
+  },
+  clear() {
+    filters = {}
+  },
+}
+
+export default memoryStore

package/src/useFilter.test.tsx

@@ -0,0 +1,449 @@
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import React, { useState } from 'react'
+
+import buildDefaultFilterInfo from './lib/buildDefaultFilterInfo'
+import { setFilterStore } from './store'
+import memoryStore from './store/memoryStore'
+import useFilter, { FilterInfo } from './useFilter'
+
+describe('useFilter', () => {
+  const defaultFilterInfo = buildDefaultFilterInfo({
+    filter: {
+      foo: 'bar',
+    },
+  })
+
+  it('calls on mount', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    expect(onChangeMock).toHaveBeenCalledTimes(1)
+    expect(onChangeMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({ filter: { foo: 'bar' } }),
+    )
+  })
+
+  it('calls when data changes', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('updateFilterButton'))
+    })
+    expect(onChangeMock).toHaveBeenCalledTimes(2)
+    expect(onChangeMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({ filter: { foo: '42' } }),
+    )
+  })
+
+  it('uses shallowEqual be default', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('updateFilterButton'))
+    })
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('updateFilterButton'))
+    })
+    // 2 is still the correct number of times, as there is one from the initial
+    // mount and the other from updateFilter.
+    expect(onChangeMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('can reset and keeps defaults', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('resetFilterButton'))
+    })
+    expect(onChangeMock).toHaveBeenCalledTimes(2)
+    expect(onChangeMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({ filter: { foo: 'bar' } }),
+    )
+  })
+
+  it('can setSort', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('setSortButton'))
+    })
+    expect(onChangeMock).toHaveBeenCalledTimes(2)
+    expect(onChangeMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({ filter: { foo: 'bar' }, sort: 'foo:bar' }),
+    )
+  })
+
+  it('renders the current filter', async () => {
+    await setup({ defaultFilterInfo })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ filter: { foo: 'bar' } }),
+    )
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('updateFilterButton'))
+    })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ filter: { foo: '42' } }),
+    )
+  })
+
+  it('handles onChange.filterInfo', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ totalResults: 1 }),
+    )
+
+    // Say the server response with a new totalResults.
+    onChangeMock.mockImplementation(() => ({
+      filterInfo: {
+        totalResults: 100,
+      },
+    }))
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('forceRefreshButton'))
+    })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ totalResults: 100 }),
+    )
+  })
+
+  it('handles onChange.filterInfo.totalResults', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    // Say the server response with a new totalResults.
+    onChangeMock.mockImplementation(() => ({
+      filterInfo: {
+        totalResults: 99,
+      },
+    }))
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('forceRefreshButton'))
+    })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ totalResults: 99 }),
+    )
+  })
+
+  // it("handles onChange.data", async () => {
+  //   onChangeMock.mockImplementation((filterInfo) => ({
+  //     data: [{ name: filterInfo.filter.foo }],
+  //   }));
+
+  //   getByTestId(wrapper, "updateFilterButton").simulate("click");
+  //   await actWrapperUpdate(wrapper);
+
+  //   expect(JSON.parse(getByTestId(wrapper, "responseDataJson").text())).toEqual(
+  //     [{ name: "42" }]
+  //   );
+
+  //   getByTestId(wrapper, "resetFilterButton").simulate("click");
+  //   await actWrapperUpdate(wrapper);
+
+  //   expect(JSON.parse(getByTestId(wrapper, "responseDataJson").text())).toEqual(
+  //     [{ name: "bar" }]
+  //   );
+  // });
+
+  it('handles async onChange.filterInfo', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ totalResults: 1 }),
+    )
+
+    // Say the server response with a new totalResults.
+    onChangeMock.mockImplementation(() =>
+      Promise.resolve({
+        filterInfo: {
+          totalResults: 100,
+        },
+      }),
+    )
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('forceRefreshButton'))
+    })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ totalResults: 100 }),
+    )
+  })
+
+  it('handles async onChange.filterInfo.totalResults', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo })
+
+    // Say the server response with a new totalResults.
+    onChangeMock.mockImplementation(() =>
+      Promise.resolve({
+        filterInfo: {
+          totalResults: 99,
+        },
+      }),
+    )
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('forceRefreshButton'))
+    })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ totalPages: 5 }),
+    )
+  })
+
+  // it("handles async onChange.data", async () => {
+  //   onChangeMock.mockImplementation((filterInfo) =>
+  //     Promise.resolve({
+  //       data: [{ name: filterInfo.filter.foo }],
+  //     })
+  //   );
+
+  //   getByTestId(wrapper, "updateFilterButton").simulate("click");
+  //   await actWrapperUpdate(wrapper);
+
+  //   expect(JSON.parse(getByTestId(wrapper, "responseDataJson").text())).toEqual(
+  //     [{ name: "42" }]
+  //   );
+
+  //   getByTestId(wrapper, "resetFilterButton").simulate("click");
+  //   await actWrapperUpdate(wrapper);
+
+  //   expect(JSON.parse(getByTestId(wrapper, "responseDataJson").text())).toEqual(
+  //     [{ name: "bar" }]
+  //   );
+  // });
+
+  it('persists across mounts', async () => {
+    const { onChangeMock, ExampleComponent } = await setup({
+      defaultFilterInfo,
+    })
+
+    const ToggleComponent = () => {
+      const [shouldShow, setShouldShow] = useState(true)
+
+      return (
+        <div>
+          <button
+            data-testid="toggleShouldShow"
+            onClick={() => setShouldShow(!shouldShow)}
+          />
+          {shouldShow ? <ExampleComponent /> : null}
+        </div>
+      )
+    }
+
+    // Simulate the filter being visible.
+    await actAndWait(() => {
+      // Cleanup the render done in `setup`.
+      cleanup()
+      render(<ToggleComponent />)
+    })
+    expect(screen.queryByTestId('updateFilterButton')).toBeTruthy()
+
+    // Simulate removing the filter.
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('toggleShouldShow'))
+    })
+    expect(screen.queryByTestId('updateFilterButton')).toBeFalsy()
+
+    // Simulate the filter being visible, again.
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('toggleShouldShow'))
+    })
+    expect(screen.queryByTestId('updateFilterButton')).toBeTruthy()
+
+    // onChange should still only be called once.
+    expect(onChangeMock).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('page based', () => {
+  const defaultFilterInfo = buildDefaultFilterInfo({
+    filter: {
+      foo: 'bar',
+    },
+    pageSize: 20,
+    page: 2,
+  })
+
+  const children: Wut = (wut) => (
+    <button data-testid="setPageButton" onClick={() => wut.setPage(3)} />
+  )
+
+  it('accepts initial page', async () => {
+    await setup({ defaultFilterInfo, children })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ page: 2, offset: 20 }),
+    )
+  })
+
+  it('can set page', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo, children })
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('setPageButton'))
+    })
+
+    expect(onChangeMock).toHaveBeenCalledTimes(2)
+    expect(onChangeMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({ page: 3, offset: 40 }),
+    )
+  })
+
+  it('can handle onChange.filterInfo.page', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo, children })
+
+    // Intentionally respond with numbers that don't match what the button
+    // actually does.
+    // This is to test the actual response, the view updates immediately.
+    onChangeMock.mockImplementation(() => ({
+      filterInfo: {
+        page: 20,
+      },
+    }))
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('setPageButton'))
+    })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ page: 20, offset: 380 }),
+    )
+  })
+})
+
+describe('offset based', () => {
+  const defaultFilterInfo = buildDefaultFilterInfo({
+    filter: {
+      foo: 'bar',
+    },
+    pageSize: 20,
+    offset: 80,
+  })
+
+  const children: Wut = (wut) => (
+    <button data-testid="setOffsetButton" onClick={() => wut.setOffset(100)} />
+  )
+
+  it('accepts initial offset', async () => {
+    await setup({ defaultFilterInfo, children })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ offset: 80, page: 5 }),
+    )
+  })
+
+  it('can set offset', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo, children })
+
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('setOffsetButton'))
+    })
+
+    expect(onChangeMock).toHaveBeenCalledTimes(2)
+    expect(onChangeMock).toHaveBeenLastCalledWith(
+      expect.objectContaining({ page: 6, offset: 100 }),
+    )
+  })
+
+  it('can handle onChange.filterInfo.offset', async () => {
+    const { onChangeMock } = await setup({ defaultFilterInfo, children })
+
+    // Intentionally respond with numbers that don't match what the button
+    // actually does.
+    // This is to test the actual response, the view updates immediately.
+    onChangeMock.mockImplementation(() => ({
+      filterInfo: {
+        offset: 380,
+      },
+    }))
+    await actAndWait(() => {
+      fireEvent.click(screen.getByTestId('setOffsetButton'))
+    })
+
+    expect(safeJsonParse(screen.getByTestId('filterJson').textContent)).toEqual(
+      expect.objectContaining({ page: 20, offset: 380 }),
+    )
+  })
+})
+
+function wait(n = 0) {
+  return new Promise((resolve) => setTimeout(resolve, n))
+}
+
+function safeJsonParse(input: string | undefined | null = '') {
+  if (input) {
+    return JSON.parse(input)
+  }
+}
+
+async function actAndWait(fn: () => void, n = 0) {
+  act(fn)
+  await act(async () => {
+    await wait(n)
+  })
+  // You'd think you could just write this:
+  //     await act(async () => {
+  //       fn();
+  //       await wait(n);
+  //     });
+  // But for some reason, doing it that way needs a longer wait duration than
+  // just a single tick. /shrug.
+}
+
+type Wut = (wut: ReturnType<typeof useFilter>) => React.ReactNode
+
+async function setup<TFilterInfo extends FilterInfo<any>>(options: {
+  defaultFilterInfo: TFilterInfo
+  children?: Wut
+}) {
+  memoryStore.clear()
+  setFilterStore(memoryStore)
+
+  const onChangeMock = jest.fn()
+
+  const ExampleComponent = () => {
+    const wut = useFilter('namespace', {
+      defaultFilterInfo: options.defaultFilterInfo,
+      debounceDuration: 0,
+      onChange: onChangeMock,
+    })
+
+    return (
+      <div>
+        {options.children?.(wut)}
+        <button
+          data-testid="updateFilterButton"
+          onClick={() => wut.updateFilter({ foo: '42' })}
+        />
+        <button
+          data-testid="resetFilterButton"
+          onClick={() => wut.resetFilter()}
+        />
+        <button
+          data-testid="forceRefreshButton"
+          onClick={() => wut.forceRefresh()}
+        />
+        <button
+          data-testid="setSortButton"
+          onClick={() => wut.setSort('foo:bar')}
+        />
+        <div data-testid="filterJson">{JSON.stringify(wut.filterInfo)}</div>
+        {/* <div data-testid="responseDataJson">
+            {JSON.stringify(wut.responseData)}
+          </div> */}
+      </div>
+    )
+  }
+
+  await actAndWait(() => {
+    render(<ExampleComponent />)
+  })
+
+  return {
+    onChangeMock,
+    ExampleComponent,
+  }
+}

package/src/useFilter.ts

@@ -0,0 +1,280 @@
+import { useEffect, useRef, useCallback, useState } from 'react'
+
+import buildDefaultFilterInfo from './lib/buildDefaultFilterInfo'
+import getOffsetFromPage from './lib/getOffsetFromPage'
+import getPageFromOffset from './lib/getPageFromOffset'
+import shallowEqual from './lib/shallowEqual'
+import { getFilterStore } from './store'
+
+type MaybePromise<T> = T | Promise<T>
+
+interface UseFilterOptions<TFilter, TResult> {
+  defaultFilterInfo?: Partial<FilterInfo<TFilter>>
+  shouldForceRunOnMount?: boolean
+  onChange: (
+    filterInfo: FilterInfo<TFilter>,
+  ) => MaybePromise<UseFilterOnChangeResult<TFilter, TResult>>
+  debounceDuration?: number
+}
+
+function useFilter<T>(namespace: string, options: UseFilterOptions<T, any>) {
+  const [filterInfo, setFilterInfoState] = useState<
+    FilterInfo<T> | null | undefined
+  >(() => getFilterStore().getFilter(namespace))
+
+  const setFilterInfo = useCallback(
+    (filterInfo: FilterInfo<T>, skipFetch = false) => {
+      setFilterInfoState((previousFilterInfo) => {
+        let lastRefreshAt: number | undefined
+
+        if (skipFetch) {
+          lastRefreshAt = previousFilterInfo?.lastRefreshAt
+        } else {
+          lastRefreshAt = new Date().getTime()
+        }
+
+        if (!lastRefreshAt) {
+          throw new Error()
+        }
+
+        return {
+          ...filterInfo,
+          lastRefreshAt,
+        }
+      })
+    },
+    [],
+  )
+
+  const ctxRef = useRef<
+    Pick<
+      UseFilterOptions<T, any>,
+      'onChange' | 'debounceDuration' | 'defaultFilterInfo'
+    > & { namespace: typeof namespace }
+  >({
+    namespace,
+    onChange: options.onChange,
+    debounceDuration: options.debounceDuration,
+    defaultFilterInfo: options.defaultFilterInfo,
+  })
+
+  const [isLoading, setIsLoading] = useState(!filterInfo)
+  const doesFilterExist = useRef(!!filterInfo)
+  const lastRefreshAtRef = useRef(
+    // if shouldForceRunOnMount is set, always use -1
+    // otherwise, try grabbing lastRefreshAt
+    // then, just use -1 cause there's no other option
+    options.shouldForceRunOnMount
+      ? -1
+      : filterInfo
+      ? filterInfo.lastRefreshAt
+      : -1,
+  )
+
+  // Call onChange when data changes.
+  useEffect(() => {
+    setIsLoading(true)
+
+    // If there is no existing filter info, set it to the defaults and return.
+    // This same effect will trigger next go.
+    if (!filterInfo) {
+      setFilterInfo(buildDefaultFilterInfo(ctxRef.current.defaultFilterInfo))
+      return
+    }
+
+    // If the lastRefreshAt hasn't changed, don't make a request.
+    if (lastRefreshAtRef.current === filterInfo.lastRefreshAt) {
+      setIsLoading(false)
+      return
+    }
+
+    const timeout = setTimeout(
+      () => {
+        lastRefreshAtRef.current = filterInfo.lastRefreshAt
+        const response = ctxRef.current.onChange(filterInfo)
+        getFilterStore().saveFilter(namespace, filterInfo)
+
+        if (!response) {
+          setIsLoading(false)
+          return
+        }
+
+        function handleResponse(response?: UseFilterOnChangeResult<T, any>) {
+          if (!filterInfo) {
+            return
+          }
+
+          if (!response) {
+            return
+          }
+
+          if (response.filterInfo) {
+            const extra: Partial<FilterInfo<T>> = {}
+            const {
+              page,
+              offset,
+              totalResults,
+              pageSize,
+              ...filterInfoFromResponse
+            } = response.filterInfo
+
+            const pageSizeNumber = Number(pageSize || filterInfo.pageSize)
+
+            if (page != null && offset == null) {
+              extra.offset = getOffsetFromPage(page, pageSizeNumber)
+              extra.page = page
+              // If there's an offset but no page, set the page.
+            } else if (page == null && offset != null) {
+              const offsetNumber = Number(offset)
+              extra.offset = offsetNumber
+              extra.page = getPageFromOffset(offsetNumber, pageSizeNumber)
+            }
+
+            if (totalResults) {
+              extra.totalResults = Number(totalResults)
+              extra.totalPages = Math.ceil(extra.totalResults / pageSizeNumber)
+            }
+
+            // TODO Don't do anther request here????
+            setFilterInfo(
+              {
+                ...filterInfo,
+                ...filterInfoFromResponse,
+                ...extra,
+              },
+              true,
+            )
+          }
+        }
+
+        if (isPromise(response)) {
+          response.then(handleResponse).finally(() => setIsLoading(false))
+        } else {
+          handleResponse(response)
+          setIsLoading(false)
+        }
+      },
+      ctxRef.current.debounceDuration != null
+        ? ctxRef.current.debounceDuration
+        : 500,
+    )
+
+    return () => {
+      if (timeout) {
+        clearTimeout(timeout)
+      }
+    }
+  }, [filterInfo, setFilterInfo, namespace])
+
+  return {
+    isLoading,
+    doesFilterExist: doesFilterExist.current,
+    filterInfo: filterInfo || buildDefaultFilterInfo(options.defaultFilterInfo),
+
+    updateFilter(filter: T) {
+      if (!filterInfo) {
+        throw new Error()
+      }
+
+      const nextFilter = {
+        ...filterInfo.filter,
+        ...filter,
+      }
+
+      if (shallowEqual(filterInfo.filter, nextFilter)) {
+        return
+      }
+
+      setFilterInfo({
+        ...filterInfo,
+        offset: 0,
+        page: 1,
+        totalResults: 1,
+        totalPages: 1,
+        filter: nextFilter,
+      })
+    },
+
+    resetFilter() {
+      setFilterInfo(buildDefaultFilterInfo(options.defaultFilterInfo))
+    },
+
+    setOffset(offset: number | string) {
+      if (!filterInfo) {
+        throw new Error()
+      }
+
+      const offsetNumber = Number(offset)
+
+      setFilterInfo({
+        ...filterInfo,
+        offset: offsetNumber,
+        page: getPageFromOffset(offsetNumber, filterInfo.pageSize),
+      })
+    },
+
+    setPage(page: number | string) {
+      if (!filterInfo) {
+        throw new Error()
+      }
+
+      const pageNumber = Number(page)
+
+      setFilterInfo({
+        ...filterInfo,
+        offset: getOffsetFromPage(pageNumber, filterInfo.pageSize),
+        page: pageNumber,
+      })
+    },
+
+    setSort(sort: string | undefined) {
+      if (!filterInfo) {
+        throw new Error()
+      }
+
+      setFilterInfo({
+        ...filterInfo,
+        sort,
+      })
+    },
+
+    forceRefresh() {
+      if (!filterInfo) {
+        throw new Error()
+      }
+
+      setFilterInfo({
+        ...filterInfo,
+        lastRefreshAt: new Date().getTime(),
+      })
+    },
+  }
+}
+
+export default useFilter
+
+export interface FilterInfo<TFilter> {
+  filter: TFilter
+  offset: number
+  page: number
+  sort?: string
+  pageSize: number
+  lastRefreshAt: number
+  totalResults: number
+  totalPages: number
+}
+
+type UseFilterOnChangeResult<TFilter, TResult> = void | {
+  filterInfo?: Partial<
+    Omit<FilterInfo<TFilter>, 'totalResults' | 'offset' | 'pageSize'> & {
+      totalResults: string | number
+      offset: string | number
+      pageSize: string | number
+    }
+  >
+  data?: TResult
+}
+
+function isPromise(t?: any): t is Promise<any> {
+  return !!t?.then
+}

package/tsconfig.json

@@ -0,0 +1,75 @@
+{
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig.json to read more about this file */
+
+    /* Basic Options */
+    // "incremental": true,                         /* Enable incremental compilation */
+    "target": "es5" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', 'ES2021', or 'ESNEXT'. */,
+    "module": "commonjs" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
+    "lib": [
+      "DOM",
+      "es2018"
+    ] /* Specify library files to be included in the compilation. */,
+    // "allowJs": true,                             /* Allow javascript files to be compiled. */
+    // "checkJs": true,                             /* Report errors in .js files. */
+    "jsx": "react" /* Specify JSX code generation: 'preserve', 'react-native', 'react', 'react-jsx' or 'react-jsxdev'. */,
+    // "declaration": true,                         /* Generates corresponding '.d.ts' file. */
+    // "declarationMap": true,                      /* Generates a sourcemap for each corresponding '.d.ts' file. */
+    // "sourceMap": true,                           /* Generates corresponding '.map' file. */
+    // "outFile": "./",                             /* Concatenate and emit output to single file. */
+    "outDir": "./dist" /* Redirect output structure to the directory. */,
+    "rootDir": "./src" /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */,
+    // "composite": true,                           /* Enable project compilation */
+    // "tsBuildInfoFile": "./",                     /* Specify file to store incremental compilation information */
+    // "removeComments": true,                      /* Do not emit comments to output. */
+    // "noEmit": true,                              /* Do not emit outputs. */
+    // "importHelpers": true,                       /* Import emit helpers from 'tslib'. */
+    // "downlevelIteration": true,                  /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
+    // "isolatedModules": true,                     /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
+
+    /* Strict Type-Checking Options */
+    "strict": true /* Enable all strict type-checking options. */,
+    // "noImplicitAny": true,                       /* Raise error on expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,                    /* Enable strict null checks. */
+    // "strictFunctionTypes": true,                 /* Enable strict checking of function types. */
+    // "strictBindCallApply": true,                 /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
+    // "strictPropertyInitialization": true,        /* Enable strict checking of property initialization in classes. */
+    // "noImplicitThis": true,                      /* Raise error on 'this' expressions with an implied 'any' type. */
+    // "alwaysStrict": true,                        /* Parse in strict mode and emit "use strict" for each source file. */
+
+    /* Additional Checks */
+    // "noUnusedLocals": true,                      /* Report errors on unused locals. */
+    // "noUnusedParameters": true,                  /* Report errors on unused parameters. */
+    // "noImplicitReturns": true,                   /* Report error when not all code paths in function return a value. */
+    // "noFallthroughCasesInSwitch": true,          /* Report errors for fallthrough cases in switch statement. */
+    // "noUncheckedIndexedAccess": true,            /* Include 'undefined' in index signature results */
+    // "noImplicitOverride": true,                  /* Ensure overriding members in derived classes are marked with an 'override' modifier. */
+    // "noPropertyAccessFromIndexSignature": true,  /* Require undeclared properties from index signatures to use element accesses. */
+
+    /* Module Resolution Options */
+    // "moduleResolution": "node",                  /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
+    // "baseUrl": "./",                             /* Base directory to resolve non-absolute module names. */
+    // "paths": {},                                 /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
+    // "rootDirs": [],                              /* List of root folders whose combined content represents the structure of the project at runtime. */
+    // "typeRoots": [],                             /* List of folders to include type definitions from. */
+    // "types": [],                                 /* Type declaration files to be included in compilation. */
+    // "allowSyntheticDefaultImports": true,        /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
+    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+    // "preserveSymlinks": true,                    /* Do not resolve the real path of symlinks. */
+    // "allowUmdGlobalAccess": true,                /* Allow accessing UMD globals from modules. */
+
+    /* Source Map Options */
+    // "sourceRoot": "",                            /* Specify the location where debugger should locate TypeScript files instead of source locations. */
+    // "mapRoot": "",                               /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,                     /* Emit a single file with source maps instead of having a separate file. */
+    // "inlineSources": true,                       /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
+
+    /* Experimental Options */
+    // "experimentalDecorators": true,              /* Enables experimental support for ES7 decorators. */
+    // "emitDecoratorMetadata": true,               /* Enables experimental support for emitting type metadata for decorators. */
+
+    /* Advanced Options */
+    "skipLibCheck": true /* Skip type checking of declaration files. */,
+    "forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */
+  }
+}