reselect-kit 1.0.1 → 1.1.1

package/src/_hooks/__tests__/useSelectors.bench.ts

@@ -0,0 +1,160 @@
+import { createElement, Fragment, ReactNode } from 'react';
+import { bench, describe } from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+import { Provider } from '@veksa/react-redux';
+import { useSelector } from '../useSelector';
+import { useSelectors } from '../useSelectors';
+import { createCachedStructuredSelector } from '../../createCachedStructuredSelector';
+
+type Quote = {
+  bid: number;
+  ask: number;
+  last: number;
+  high: number;
+  low: number;
+  volume: number;
+};
+
+type State = { quotes: Record<string, Quote> };
+type Props = { symbol: string };
+
+const StoreProvider = Provider as unknown as (props: {
+  store: unknown;
+  children?: ReactNode;
+}) => ReactNode;
+
+// A quote table: one row per symbol, seven fields read per row.
+const ROWS = 100;
+
+const symbols = Array.from({ length: ROWS }, (_, index) => `SYM${index}`);
+
+const state: State = {
+  quotes: Object.fromEntries(
+    symbols.map((symbol, index) => [
+      symbol,
+      { bid: index, ask: index + 1, last: index, high: index + 2, low: index - 2, volume: index },
+    ]),
+  ),
+};
+
+const store = {
+  getState: () => state,
+  dispatch: (action: unknown) => action,
+  subscribe: () => () => undefined,
+  replaceReducer: () => undefined,
+} as unknown as never;
+
+const selectSymbol = (_state: State, props: Props) => props.symbol;
+const selectBid = (state: State, props: Props) => state.quotes[props.symbol].bid;
+const selectAsk = (state: State, props: Props) => state.quotes[props.symbol].ask;
+const selectLast = (state: State, props: Props) => state.quotes[props.symbol].last;
+const selectHigh = (state: State, props: Props) => state.quotes[props.symbol].high;
+const selectLow = (state: State, props: Props) => state.quotes[props.symbol].low;
+const selectVolume = (state: State, props: Props) => state.quotes[props.symbol].volume;
+
+const fields = {
+  symbol: selectSymbol,
+  bid: selectBid,
+  ask: selectAsk,
+  last: selectLast,
+  high: selectHigh,
+  low: selectLow,
+  volume: selectVolume,
+};
+
+// The alternative that already exists: one module-level cached structured
+// selector, read through a single `useSelector`. One subscription per row too,
+// but the memoization is shared by every row and keyed by symbol.
+const selectQuoteView = createCachedStructuredSelector(fields)(
+  (_state: State, props: Props) => props.symbol,
+);
+
+const HooksRow = ({ symbol }: Props) => {
+  const props = { symbol };
+
+  useSelector(selectSymbol, props);
+  useSelector(selectBid, props);
+  useSelector(selectAsk, props);
+  useSelector(selectLast, props);
+  useSelector(selectHigh, props);
+  useSelector(selectLow, props);
+  useSelector(selectVolume, props);
+
+  return null;
+};
+
+const BatchRow = ({ symbol }: Props) => {
+  useSelectors(fields, { symbol });
+
+  return null;
+};
+
+const StructuredRow = ({ symbol }: Props) => {
+  useSelector(selectQuoteView, { symbol });
+
+  return null;
+};
+
+const createTree = (Row: (props: Props) => ReactNode) => {
+  return ({ generation }: { generation: number }) => {
+    const children: ReactNode[] = [];
+
+    for (let index = 0; index < ROWS; index++) {
+      children.push(createElement(Row, { key: index, symbol: symbols[index] }));
+    }
+
+    return createElement(
+      StoreProvider,
+      { store },
+      createElement(Fragment, { key: generation }, ...children),
+    );
+  };
+};
+
+const trees = {
+  'useSelector x7': createTree(HooksRow),
+  useSelectors: createTree(BatchRow),
+  'structured selector': createTree(StructuredRow),
+};
+
+const benchRerender = (name: string, Tree: (props: { generation: number }) => ReactNode) => {
+  let mounted: ReturnType<typeof render> | null = null;
+  let generation = 0;
+
+  bench(
+    name,
+    () => {
+      // The key is stable: the same rows re-render, nothing remounts.
+      mounted!.rerender(createElement(Tree, { generation: 0 }));
+      generation++;
+    },
+    {
+      setup: () => {
+        mounted = render(createElement(Tree, { generation }));
+      },
+      teardown: () => {
+        cleanup();
+        mounted = null;
+      },
+    },
+  );
+};
+
+// A parent re-render of the whole table: no state change, no props change, so
+// nothing recomputes. This is subscription and hook overhead only.
+describe(`re-render ${ROWS} rows x 7 fields`, () => {
+  for (const [name, Tree] of Object.entries(trees)) {
+    benchRerender(name, Tree);
+  }
+});
+
+// Mount pays for the subscriptions themselves: 700 store listeners for the
+// per-field variant against 100 for the other two.
+describe(`mount ${ROWS} rows x 7 fields`, () => {
+  for (const [name, Tree] of Object.entries(trees)) {
+    bench(name, () => {
+      render(createElement(Tree, { generation: 0 }));
+      cleanup();
+    });
+  }
+});

package/src/_hooks/__tests__/useSelectors.test.ts

@@ -0,0 +1,219 @@
+import { createElement, ReactNode } from 'react';
+import { describe, expect, test, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { Provider } from '@veksa/react-redux';
+import { useSelectors } from '../useSelectors';
+
+// `children` is passed positionally (oxlint forbids it as a prop), so relax the
+// Provider's prop type to make `children` optional in the props object.
+const StoreProvider = Provider as unknown as (props: {
+  store: unknown;
+  children?: ReactNode;
+}) => ReactNode;
+
+type Quote = { bid: number; ask: number };
+type State = { quotes: Record<string, Quote>; ui: { theme: string } };
+type Props = { symbol: string };
+
+const initialState: State = {
+  quotes: { EURUSD: { bid: 1, ask: 2 } },
+  ui: { theme: 'dark' },
+};
+
+const createMockStore = (initial: State) => {
+  const listeners = new Set<() => void>();
+  let state = initial;
+
+  const store = {
+    getState: () => state,
+    dispatch: (next: State) => {
+      state = next;
+      listeners.forEach((listener) => listener());
+      return next;
+    },
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    replaceReducer: () => undefined,
+  };
+
+  return store;
+};
+
+const wrapperWith =
+  (store: unknown) =>
+  ({ children }: { children: ReactNode }) =>
+    createElement(StoreProvider, { store }, children);
+
+// react-redux notifies its listeners through a MessageChannel, so a dispatch
+// only reaches the components after the next macrotask.
+const dispatch = async (store: ReturnType<typeof createMockStore>, next: State) => {
+  await act(async () => {
+    store.dispatch(next);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+};
+
+const selectSymbol = (_state: State, props: Props) => props.symbol;
+const selectBid = (state: State, props: Props) => state.quotes[props.symbol].bid;
+const selectAsk = (state: State, props: Props) => state.quotes[props.symbol].ask;
+
+describe('useSelectors', () => {
+  test('returns every selector result keyed by its name', () => {
+    const store = createMockStore(initialState);
+
+    const { result } = renderHook(
+      () =>
+        useSelectors(
+          { symbol: selectSymbol, bid: selectBid, ask: selectAsk },
+          { symbol: 'EURUSD' },
+        ),
+      { wrapper: wrapperWith(store) },
+    );
+
+    expect(result.current).toEqual({ symbol: 'EURUSD', bid: 1, ask: 2 });
+  });
+
+  test('keeps the result reference across renders that changed nothing', () => {
+    const store = createMockStore(initialState);
+
+    const { result, rerender } = renderHook(
+      ({ props }) => useSelectors({ bid: selectBid, ask: selectAsk }, props),
+      {
+        wrapper: wrapperWith(store),
+        initialProps: { props: { symbol: 'EURUSD' } },
+      },
+    );
+
+    const first = result.current;
+    // A new-but-shallow-equal props object must not rebuild the batch.
+    rerender({ props: { symbol: 'EURUSD' } });
+
+    expect(result.current).toBe(first);
+  });
+
+  test('does not re-render when the update leaves every field untouched', async () => {
+    const store = createMockStore(initialState);
+    const renders = vi.fn();
+
+    const { result } = renderHook(
+      () => {
+        renders();
+        return useSelectors({ bid: selectBid, ask: selectAsk }, { symbol: 'EURUSD' });
+      },
+      { wrapper: wrapperWith(store) },
+    );
+
+    const first = result.current;
+    const rendersAfterMount = renders.mock.calls.length;
+
+    await dispatch(store, { ...initialState, ui: { theme: 'light' } });
+
+    expect(renders.mock.calls.length).toBe(rendersAfterMount);
+    expect(result.current).toBe(first);
+  });
+
+  test('keeps the result object when a tracked change leaves every value equal', async () => {
+    const store = createMockStore(initialState);
+    const bid = vi.fn(selectBid);
+    const ask = vi.fn(selectAsk);
+
+    const { result } = renderHook(() => useSelectors({ bid, ask }, { symbol: 'EURUSD' }), {
+      wrapper: wrapperWith(store),
+    });
+
+    const first = result.current;
+    const callsAfterMount = bid.mock.calls.length;
+
+    // A new `quotes` object holding the same numbers: the batch re-runs, because
+    // the segment it reads changed identity, but nothing it produced did — so
+    // the previous result object is handed back rather than an equal new one.
+    await dispatch(store, { ...initialState, quotes: { EURUSD: { bid: 1, ask: 2 } } });
+
+    expect(bid.mock.calls.length).toBeGreaterThan(callsAfterMount);
+    expect(ask.mock.calls.length).toBeGreaterThan(callsAfterMount);
+    expect(result.current).toBe(first);
+  });
+
+  test('rebuilds the result when a single field changes', async () => {
+    const store = createMockStore(initialState);
+
+    const { result } = renderHook(
+      () => useSelectors({ bid: selectBid, ask: selectAsk }, { symbol: 'EURUSD' }),
+      { wrapper: wrapperWith(store) },
+    );
+
+    const first = result.current;
+
+    await dispatch(store, { ...initialState, quotes: { EURUSD: { bid: 3, ask: 2 } } });
+
+    expect(result.current).not.toBe(first);
+    expect(result.current).toEqual({ bid: 3, ask: 2 });
+  });
+
+  test('re-runs the batch when props change without a state change', () => {
+    const store = createMockStore({
+      quotes: { EURUSD: { bid: 1, ask: 2 }, GBPUSD: { bid: 10, ask: 20 } },
+      ui: { theme: 'dark' },
+    });
+
+    const { result, rerender } = renderHook(
+      ({ props }) => useSelectors({ bid: selectBid, ask: selectAsk }, props),
+      {
+        wrapper: wrapperWith(store),
+        initialProps: { props: { symbol: 'EURUSD' } },
+      },
+    );
+
+    expect(result.current).toEqual({ bid: 1, ask: 2 });
+
+    rerender({ props: { symbol: 'GBPUSD' } });
+
+    expect(result.current).toEqual({ bid: 10, ask: 20 });
+  });
+
+  test('picks up a replaced selector in the batch', () => {
+    const store = createMockStore(initialState);
+
+    const { result, rerender } = renderHook(
+      ({ factor }) =>
+        useSelectors(
+          { bid: (state: State, props: Props) => state.quotes[props.symbol].bid * factor },
+          { symbol: 'EURUSD' },
+        ),
+      {
+        wrapper: wrapperWith(store),
+        initialProps: { factor: 1 },
+      },
+    );
+
+    expect(result.current).toEqual({ bid: 1 });
+
+    rerender({ factor: 10 });
+
+    expect(result.current).toEqual({ bid: 10 });
+  });
+
+  test('unfreezes frozen props before passing them to the selectors', () => {
+    const store = createMockStore(initialState);
+    let receivedProps: Props | undefined;
+
+    renderHook(
+      () =>
+        useSelectors(
+          {
+            bid: (state: State, props: Props) => {
+              receivedProps = props;
+              return state.quotes[props.symbol].bid;
+            },
+          },
+          Object.freeze({ symbol: 'EURUSD' }),
+        ),
+      { wrapper: wrapperWith(store) },
+    );
+
+    expect(Object.isFrozen(receivedProps)).toBe(false);
+    expect(receivedProps?.symbol).toBe('EURUSD');
+  });
+});

package/src/_hooks/selectorOptions.ts

@@ -0,0 +1,11 @@
+/**
+ * Hoisted: react-redux reads the options object on every render, so there is no
+ * reason to allocate a fresh one per call site per render. The dev-mode checks
+ * re-run the selector to compare results, which these hooks control themselves.
+ */
+export const selectorOptions = {
+  devModeChecks: {
+    stabilityCheck: 'never',
+    identityFunctionCheck: 'never',
+  },
+} as const;

package/src/_hooks/useSelector.ts

@@ -1,34 +1,76 @@
 import { shallowEqual, useSelector as useReduxSelector } from '@veksa/react-redux';
-import { useMemoWith } from './useMemoWith';
-import { useCallback, useMemo } from 'react';
+import { useRef } from 'react';
+import { unfreezeProps } from '../_helpers/unfreezeProps';
+import { selectorOptions } from './selectorOptions';
 
-export function useSelector<S extends object, R>(selector: (state: S) => R): R;
+type SelectorCache = {
+  props: unknown;
+  unfrozenProps: unknown;
+  selector: Function;
+  boundSelector: (state: unknown) => unknown;
+};
 
-export function useSelector<S extends object, P, R>(
-  selector: (state: S, props: P) => R,
-  props: P,
+/**
+ * Reads one selector from the store. Props are compared shallowly, so an inline
+ * object literal does not invalidate the selector on every render.
+ *
+ * A single variadic signature covers both the plain and the parametric case:
+ * `Params` is inferred from the selector itself and is empty when the selector
+ * takes nothing but `state`, so the props argument is required exactly when the
+ * selector declares one. `NoInfer` keeps the props argument out of that
+ * inference -- otherwise an inline object literal would widen `Params` instead
+ * of being checked against what the selector declares. It defaults to empty so
+ * that `useSelector<State, Result>(selector)` -- the call site of the former
+ * plain overload -- keeps compiling without spelling the tuple out.
+ *
+ * Use {@link useSelectors} to read several selectors through a single store
+ * subscription.
+ */
+export function useSelector<S extends object, R, Params extends readonly any[] = []>(
+  selector: (state: S, ...params: Params) => R,
+  ...params: NoInfer<Params>
 ): R;
 
 export function useSelector(selector: Function, ...params: any[]) {
   const props = params[0];
-  const memoizedProps = useMemoWith(props, shallowEqual);
-
-  // unfreeze props for performance optimization (see temporaryAssign.ts)
-  const unfrozenProps = useMemo(() => {
-    return Object.isFrozen(memoizedProps) ? { ...memoizedProps } : memoizedProps;
-  }, [memoizedProps]);
-
-  const memoizedPropsSelector = useCallback(
-    (state: unknown) => {
-      return selector(state, unfrozenProps);
-    },
-    [selector, unfrozenProps],
-  );
-
-  return useReduxSelector(memoizedPropsSelector, {
-    devModeChecks: {
-      stabilityCheck: 'never',
-      identityFunctionCheck: 'never',
-    },
-  });
+
+  // One ref cell instead of a memo-by-comparator hook, a `useMemo` and a
+  // `useCallback`: three hook slots and two dependency arrays per call site,
+  // none of which this hook needs — every transition it cares about is an
+  // explicit comparison it already performs.
+  const cacheRef = useRef<SelectorCache | null>(null);
+
+  let cache = cacheRef.current;
+
+  if (cache === null) {
+    const unfrozenProps = unfreezeProps(props);
+
+    cache = cacheRef.current = {
+      props,
+      unfrozenProps,
+      selector,
+      boundSelector: (state: unknown) => selector(state, unfrozenProps),
+    };
+  } else {
+    // A new-but-shallow-equal props object keeps the previous reference, so the
+    // bound selector stays stable across renders that changed nothing.
+    const propsChanged = !shallowEqual(props, cache.props);
+
+    if (propsChanged) {
+      cache.props = props;
+      cache.unfrozenProps = unfreezeProps(props);
+    }
+
+    if (propsChanged || cache.selector !== selector) {
+      const { unfrozenProps } = cache;
+
+      cache.selector = selector;
+      // react-redux memoizes the selection on the selector's identity, so a new
+      // identity is what makes it recompute when the state has not changed but
+      // the props or the selector have.
+      cache.boundSelector = (state: unknown) => selector(state, unfrozenProps);
+    }
+  }
+
+  return useReduxSelector(cache.boundSelector, selectorOptions);
 }

package/src/_hooks/useSelectors.ts

@@ -0,0 +1,162 @@
+import { shallowEqual, useSelector as useReduxSelector } from '@veksa/react-redux';
+import { SelectorResultsMap, SelectorsObject } from '@veksa/reselect';
+import { useRef } from 'react';
+import { unfreezeProps } from '../_helpers/unfreezeProps';
+import { MergedParams } from '../types';
+import { selectorOptions } from './selectorOptions';
+
+type SelectorsMap = Record<string, Function>;
+
+type SelectorsCache = {
+  keys: string[];
+  selectors: Function[];
+  props: unknown;
+  unfrozenProps: unknown;
+  results: unknown[];
+  value: Record<string, unknown> | null;
+  boundSelector: (state: unknown) => unknown;
+};
+
+const readSelectors = (cache: SelectorsCache, selectors: SelectorsMap) => {
+  const keys: string[] = [];
+  const fns: Function[] = [];
+
+  for (const key in selectors) {
+    if (Object.prototype.hasOwnProperty.call(selectors, key)) {
+      keys.push(key);
+      fns.push(selectors[key]);
+    }
+  }
+
+  cache.keys = keys;
+  cache.selectors = fns;
+  // Filled in ascending index order on the first run, so the array stays packed.
+  cache.results = [];
+  cache.value = null;
+};
+
+/**
+ * One pass over the incoming object instead of `shallowEqual`, which would
+ * allocate a key array for each side on every render of every call site. Key
+ * order is part of the comparison, so a renamed key is caught as well.
+ */
+const hasSameSelectors = (cache: SelectorsCache, selectors: SelectorsMap) => {
+  const { keys, selectors: fns } = cache;
+  let index = 0;
+
+  for (const key in selectors) {
+    if (Object.prototype.hasOwnProperty.call(selectors, key)) {
+      if (index === keys.length || keys[index] !== key || fns[index] !== selectors[key]) {
+        return false;
+      }
+
+      index++;
+    }
+  }
+
+  return index === keys.length;
+};
+
+/**
+ * The structured part: every selector runs, but the result object is rebuilt
+ * only when some field actually changed. An unchanged batch keeps its previous
+ * reference, so react-redux's default reference equality already bails out —
+ * no result allocation and no comparison pass on the steady path.
+ */
+const select = (cache: SelectorsCache, state: unknown) => {
+  const { keys, selectors, unfrozenProps, results } = cache;
+  const count = keys.length;
+
+  let changed = cache.value === null;
+
+  for (let index = 0; index < count; index++) {
+    const result = selectors[index](state, unfrozenProps);
+
+    if (!Object.is(result, results[index])) {
+      results[index] = result;
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    return cache.value;
+  }
+
+  const value: Record<string, unknown> = {};
+
+  for (let index = 0; index < count; index++) {
+    value[keys[index]] = results[index];
+  }
+
+  cache.value = value;
+
+  return value;
+};
+
+/**
+ * Reads a batch of selectors through a single store subscription and returns
+ * their results as one object.
+ *
+ * Seven `useSelector` calls in a row component mean seven store listeners,
+ * seven `useSyncExternalStore` instances and seven snapshot comparisons per
+ * dispatch. This collapses them into one of each; the trade-off is that any
+ * tracked state segment changing re-runs the whole batch, which for memoized
+ * selectors is a cache hit per field.
+ *
+ * The memoization lives in the component instance, so rows do not compete for
+ * a shared cache the way a module-level structured selector would.
+ */
+export function useSelectors<M extends SelectorsObject>(
+  selectors: M,
+  ...params: MergedParams<M>
+): SelectorResultsMap<M>;
+
+export function useSelectors(selectors: SelectorsMap, ...params: any[]) {
+  const props = params[0];
+
+  const cacheRef = useRef<SelectorsCache | null>(null);
+
+  let cache = cacheRef.current;
+
+  if (cache === null) {
+    const created: SelectorsCache = {
+      keys: [],
+      selectors: [],
+      props,
+      unfrozenProps: unfreezeProps(props),
+      results: [],
+      value: null,
+      boundSelector: (state: unknown) => select(created, state),
+    };
+
+    readSelectors(created, selectors);
+
+    cache = cacheRef.current = created;
+  } else {
+    // An object literal is a new reference on every render, so the batch is
+    // compared by content — the common case is the very same selectors.
+    const selectorsChanged = !hasSameSelectors(cache, selectors);
+    const propsChanged = !shallowEqual(props, cache.props);
+
+    if (selectorsChanged) {
+      readSelectors(cache, selectors);
+    }
+
+    if (propsChanged) {
+      cache.props = props;
+      cache.unfrozenProps = unfreezeProps(props);
+    }
+
+    if (selectorsChanged || propsChanged) {
+      // react-redux memoizes the selection on the selector's identity, so a new
+      // identity is what makes it recompute when the state has not changed but
+      // the batch or the props have. The closure reads the cell, so it never
+      // captures a stale batch.
+      const current = cache;
+
+      cache.boundSelector = (state: unknown) => select(current, state);
+    }
+  }
+
+  return useReduxSelector(cache.boundSelector, selectorOptions) as Record<string, unknown>;
+}

package/src/cache/__tests__/intervalMapCache.test.ts

@@ -36,6 +36,17 @@ describe('IntervalMapCache', () => {
     expect(cache.get('missing')).toBeUndefined();
   });
 
+  test('overwrites the value of a key that is already present', () => {
+    const cache = new IntervalMapCache();
+    const first = { value: 1 };
+    const second = { value: 2 };
+
+    cache.set('key', first);
+    cache.set('key', second);
+
+    expect(cache.get('key')).toBe(second);
+  });
+
   test('removes a value by key', () => {
     const cache = new IntervalMapCache();