reselect-kit 1.0.0

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

@@ -0,0 +1,188 @@
+import { FlatMapCache, createCachedSelector } from '@veksa/re-reselect';
+import { IntervalMapCache } from '../intervalMapCache';
+import { TreeCache } from '../TreeCache';
+
+describe('TreeCache', () => {
+  test('should validate key', () => {
+    let cache = new TreeCache({});
+
+    let actual: boolean;
+    actual = cache.isValidCacheKey(['1', 2]);
+    expect(actual).toBeTruthy();
+
+    actual = cache.isValidCacheKey(['1', {}]);
+    expect(actual).toBeFalsy();
+
+    cache = new TreeCache({
+      cacheObjectCreator: () => new FlatMapCache(),
+    });
+
+    actual = cache.isValidCacheKey(['1', 2]);
+    expect(actual).toBeTruthy();
+
+    actual = cache.isValidCacheKey(['1', {}]);
+    expect(actual).toBeTruthy();
+  });
+
+  test('should normalize scalar key', () => {
+    let cache = new TreeCache({});
+
+    let actual: boolean;
+    actual = cache.isValidCacheKey({});
+    expect(actual).toBeFalsy();
+
+    cache = new TreeCache({
+      cacheObjectCreator: () => new FlatMapCache(),
+    });
+
+    actual = cache.isValidCacheKey({});
+    expect(actual).toBeTruthy();
+  });
+
+  test('should return undefined if there is not value for key', () => {
+    const cache = new TreeCache({});
+
+    let actual: unknown;
+    actual = cache.get(['some', 'deep', 'key']);
+    expect(actual).toBeUndefined();
+
+    cache.set(['some', 'deep'], expect.anything());
+    actual = cache.get(['some', 'deep', 'key']);
+    expect(actual).toBeUndefined();
+  });
+
+  test('should return undefined if key path is short', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+
+    cache.set(['some', 'deep', 'key'], selectorFn);
+    const actual = cache.get(['some', 'deep']);
+    expect(actual).toBeUndefined();
+  });
+
+  test('should set value in key path', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+
+    cache.set(['some', 'deep', 'key'], selectorFn);
+    const actual = cache.get(['some', 'deep', 'key']);
+    expect(actual).toBe(selectorFn);
+  });
+
+  test('should remove value in key path', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+
+    let actual: unknown;
+    cache.set(['some', 'deep', 'key'], selectorFn);
+    actual = cache.get(['some', 'deep', 'key']);
+    expect(actual).toBe(selectorFn);
+
+    cache.remove(['some', 'deep', 'key']);
+    actual = cache.get(['some', 'deep', 'key']);
+    expect(actual).toBeUndefined();
+  });
+
+  test('should do nothing if there is not value for removable key', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+
+    cache.set(['some', 'deep'], selectorFn);
+    cache.remove(['some', 'deep', 'key']);
+
+    const actual = cache.get(['some', 'deep']);
+    expect(actual).toBe(selectorFn);
+  });
+
+  test('should clear values', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+    const otherSelectorFn = () => undefined;
+
+    cache.set(['some', 'deep', 'key'], selectorFn);
+    cache.set(['some', 'other', 'key'], otherSelectorFn);
+    expect(cache.get(['some', 'deep', 'key'])).toBe(selectorFn);
+    expect(cache.get(['some', 'other', 'key'])).toBe(otherSelectorFn);
+
+    cache.clear();
+    expect(cache.get(['some', 'deep', 'key'])).toBeUndefined();
+    expect(cache.get(['some', 'other', 'key'])).toBeUndefined();
+  });
+
+  test('should back a cached selector without rebinding its validator', () => {
+    /**
+     * `TreeCache.isValidCacheKey` reads `this.root`, so it only answers when the
+     * cached selector calls it as a method on the cache. A selector that detaches
+     * the validator into a local and calls it bare leaves `this` undefined and
+     * throws on the very first lookup, which makes a TreeCache-backed selector
+     * unusable rather than merely slow — and dropping the validator instead is no
+     * escape, since the default one rejects the array keys this cache exists to
+     * index.
+     */
+    const cache = new TreeCache({
+      cacheObjectCreator: () => new IntervalMapCache(),
+    });
+
+    type State = { items: Record<number, number> };
+    type Props = { id: number; kind: string };
+
+    const selector = createCachedSelector(
+      (state: State, props: Props) => state.items[props.id],
+      (value: number) => value * 2,
+    )({
+      // A composite key is the whole reason to reach for TreeCache: it indexes the
+      // array level by level instead of stringifying it.
+      keySelector: (_state: State, props: Props) => [props.id, props.kind],
+      cacheObject: cache,
+    });
+
+    const state = { items: { 1: 21 } };
+
+    expect(selector(state, { id: 1, kind: 'a' })).toBe(42);
+    expect(selector(state, { id: 1, kind: 'a' })).toBe(42);
+    expect(selector.recomputations()).toBe(1);
+  });
+
+  test('should treat a scalar key as a one-level path', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+
+    cache.set('key', selectorFn);
+
+    // The scalar and the single-element path address the same node, so `get` must
+    // not be able to tell them apart.
+    expect(cache.get('key')).toBe(selectorFn);
+    expect(cache.get(['key'])).toBe(selectorFn);
+
+    expect(cache.get('missing')).toBeUndefined();
+
+    cache.set(['other'], selectorFn);
+    expect(cache.get('other')).toBe(selectorFn);
+
+    cache.remove('key');
+    expect(cache.get('key')).toBeUndefined();
+    expect(cache.get(['key'])).toBeUndefined();
+  });
+
+  test('should return undefined for a scalar key that addresses an inner node', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+
+    cache.set(['some', 'deep'], selectorFn);
+
+    // `some` exists as a node but holds no selector of its own.
+    expect(cache.get('some')).toBeUndefined();
+  });
+
+  test('should persist values in middle of tree', () => {
+    const cache = new TreeCache({});
+    const selectorFn = () => undefined;
+    const otherSelectorFn = () => undefined;
+
+    cache.set(['some', 'deep'], selectorFn);
+    cache.set(['some', 'deep', 'key'], otherSelectorFn);
+
+    expect(cache.get(['some', 'deep'])).toBe(selectorFn);
+    expect(cache.get(['some', 'deep', 'key'])).toBe(otherSelectorFn);
+  });
+});

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

@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+type IntervalMapCacheModule = typeof import('../intervalMapCache');
+
+describe('IntervalMapCache', () => {
+  let IntervalMapCache: IntervalMapCacheModule['IntervalMapCache'];
+  let initGarbageCollector: IntervalMapCacheModule['initGarbageCollector'];
+
+  beforeEach(async () => {
+    // Fresh module state per test: the cache store, id counter and the
+    // garbage-collector guard all live at module scope.
+    vi.resetModules();
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+
+    const mod = await import('../intervalMapCache');
+    IntervalMapCache = mod.IntervalMapCache;
+    initGarbageCollector = mod.initGarbageCollector;
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  test('stores and reads values by key', () => {
+    const cache = new IntervalMapCache();
+    const value = { value: 1 };
+
+    cache.set('key', value);
+    expect(cache.get('key')).toBe(value);
+  });
+
+  test('returns undefined for a missing key', () => {
+    const cache = new IntervalMapCache();
+    expect(cache.get('missing')).toBeUndefined();
+  });
+
+  test('removes a value by key', () => {
+    const cache = new IntervalMapCache();
+
+    cache.set('key', { value: 1 });
+    cache.remove('key');
+    expect(cache.get('key')).toBeUndefined();
+  });
+
+  test('clears all values of the instance', () => {
+    const cache = new IntervalMapCache();
+
+    cache.set('a', 1);
+    cache.set('b', 2);
+    cache.clear();
+
+    expect(cache.get('a')).toBeUndefined();
+    expect(cache.get('b')).toBeUndefined();
+  });
+
+  test('keeps instances isolated from each other', () => {
+    const first = new IntervalMapCache();
+    const second = new IntervalMapCache();
+
+    first.set('key', 'first');
+    second.set('key', 'second');
+
+    expect(first.get('key')).toBe('first');
+    expect(second.get('key')).toBe('second');
+  });
+
+  // Bug #3: remove() threw on an instance that was never written to.
+  test('remove does nothing for an instance that was never written to', () => {
+    const cache = new IntervalMapCache();
+    expect(() => cache.remove('missing')).not.toThrow();
+  });
+
+  // Bug #1: the garbage collector iterated the wrong object and never evicted.
+  test('garbage collector evicts entries older than the cache lifetime', () => {
+    const cache = new IntervalMapCache();
+    initGarbageCollector();
+
+    cache.set('key', { value: 1 });
+    expect(cache.get('key')).toEqual({ value: 1 });
+
+    // Advance past two GC cycles without touching the entry.
+    vi.advanceTimersByTime(25000);
+
+    expect(cache.get('key')).toBeUndefined();
+  });
+
+  // Bug #2: the timestamp was frozen at construction time, so touching an entry
+  // via get() must refresh its lifetime and keep it alive across GC cycles.
+  test('accessing an entry refreshes its lifetime', () => {
+    const cache = new IntervalMapCache();
+    initGarbageCollector();
+
+    cache.set('key', { value: 1 });
+
+    // Touch the entry within every GC cycle (cacheLifetime = 10000).
+    for (let i = 0; i < 3; i += 1) {
+      vi.advanceTimersByTime(8000);
+      cache.get('key');
+    }
+
+    expect(cache.get('key')).toEqual({ value: 1 });
+  });
+
+  // Bug #2: set() must stamp entries with the current time, not the time the
+  // instance was constructed.
+  test('set stamps entries with the current time, not the construction time', () => {
+    const cache = new IntervalMapCache();
+    initGarbageCollector();
+
+    // Long after construction, write a fresh entry.
+    vi.advanceTimersByTime(20000);
+    cache.set('key', { value: 1 });
+
+    // One more GC cycle: the entry is only 10000ms old, so it must survive.
+    vi.advanceTimersByTime(10000);
+
+    expect(cache.get('key')).toEqual({ value: 1 });
+  });
+
+  // Bug #4: initGarbageCollector() must be idempotent and not stack timers.
+  test('initGarbageCollector does not stack collectors when called repeatedly', () => {
+    const setTimeoutSpy = vi.spyOn(window, 'setTimeout');
+
+    initGarbageCollector();
+    initGarbageCollector();
+    initGarbageCollector();
+
+    expect(setTimeoutSpy).toHaveBeenCalledTimes(1);
+    setTimeoutSpy.mockRestore();
+  });
+});

package/src/cache/intervalMapCache.ts

@@ -0,0 +1,97 @@
+import { ICacheObject } from '@veksa/re-reselect';
+
+interface CacheEntry {
+  data: unknown;
+  time: number;
+}
+
+/**
+ * Buckets used to live in a module-level `Record<string, …>` keyed by an
+ * incrementing numeric id, which meant every `get` and `set` coerced that number to
+ * a string and re-read the global record — four times per cache hit in `get`.
+ * Holding the entries on the instance removes both, and a `Map` keeps non-string
+ * keys as they are instead of stringifying them.
+ */
+const buckets = new Set<IntervalMapCache>();
+
+const cacheLifetime = 10000;
+
+let garbageCollectorStarted = false;
+
+const runGarbageCollector = () => {
+  const currentTime = Date.now();
+
+  buckets.forEach((bucket) => {
+    if (bucket.sweep(currentTime)) {
+      // A bucket the sweep emptied is dropped from the registry, so a cache whose
+      // selector has been discarded stops being reachable from module scope and
+      // becomes collectable. Registration happens again on the next `set`, so a
+      // cache that is still in use simply re-enters.
+      buckets.delete(bucket);
+    }
+  });
+
+  window.setTimeout(runGarbageCollector, cacheLifetime);
+};
+
+export const initGarbageCollector = () => {
+  if (garbageCollectorStarted) {
+    return;
+  }
+
+  if (typeof window !== 'undefined') {
+    garbageCollectorStarted = true;
+    window.setTimeout(runGarbageCollector, cacheLifetime);
+  }
+};
+
+export class IntervalMapCache implements ICacheObject {
+  private entries = new Map<unknown, CacheEntry>();
+
+  public set(key: any, data: any) {
+    const entry = this.entries.get(key);
+
+    if (entry === undefined) {
+      buckets.add(this);
+      this.entries.set(key, { data, time: Date.now() });
+    } else {
+      entry.data = data;
+      entry.time = Date.now();
+    }
+  }
+
+  public get(key: any) {
+    const entry = this.entries.get(key);
+
+    if (entry === undefined) {
+      return undefined;
+    }
+
+    entry.time = Date.now();
+
+    return entry.data;
+  }
+
+  public remove(key: any) {
+    this.entries.delete(key);
+  }
+
+  public clear() {
+    this.entries.clear();
+    buckets.delete(this);
+  }
+
+  /**
+   * Drops entries untouched for longer than the lifetime. Returns whether the
+   * bucket is now empty, which is what lets the collector unregister it.
+   */
+  public sweep(currentTime: number) {
+    this.entries.forEach((entry, key) => {
+      if (currentTime - entry.time > cacheLifetime) {
+        this.entries.delete(key);
+      }
+    });
+
+    return this.entries.size === 0;
+  }
+}

package/src/createAdaptedSelector.ts

@@ -0,0 +1,75 @@
+import { Selector } from '@veksa/reselect';
+import { CachedSelector, NamedParametricSelector } from './types';
+import { withDebugName } from './debug/withDebugName';
+import { getSelectorName } from './_helpers/getSelectorName';
+import { isCachedSelector } from './_helpers/isCachedSelector';
+
+const generateMappingName = <P1 extends object, P2>(mapping: (props: P2) => P1) => {
+  if (mapping.name) {
+    return mapping.name;
+  }
+
+  const structure = mapping(
+    new Proxy(
+      {},
+      {
+        get: (_target, key) => key,
+      },
+    ) as P2,
+  );
+  const structureKeys = Object.keys(structure).join();
+  const structureValues = Object.values(structure).join();
+
+  return `${structureKeys} -> ${structureValues}`;
+};
+
+const innerCreateAdaptedSelector =
+  <S, P1, P2, R>(
+    baseSelector: Selector<S, R, [P1]>,
+    mapping: (props: P2) => P1,
+  ): NamedParametricSelector<S, P2, R> =>
+  (state: S, props: P2) => {
+    return baseSelector(state, mapping(props));
+  };
+
+export const createAdaptedSelector = <S, P1 extends object, P2, R>(
+  baseSelector: Selector<S, R, [P1]>,
+  mapping: (props: P2) => P1,
+) => {
+  const adaptedSelector = innerCreateAdaptedSelector(baseSelector, mapping);
+
+  Object.assign(adaptedSelector, baseSelector);
+  adaptedSelector.dependencies = [baseSelector];
+
+  withDebugName(adaptedSelector, () => {
+    const baseName = getSelectorName(baseSelector);
+    const mappingName = generateMappingName(mapping);
+
+    return `${baseName} (${mappingName})`;
+  });
+
+  if (isCachedSelector(baseSelector)) {
+    const cachedAdaptedSelector = adaptedSelector as unknown as CachedSelector;
+
+    if (baseSelector.getMatchingSelector) {
+      cachedAdaptedSelector.getMatchingSelector = innerCreateAdaptedSelector(
+        baseSelector.getMatchingSelector,
+        mapping,
+      );
+    }
+
+    if (baseSelector.removeMatchingSelector) {
+      cachedAdaptedSelector.removeMatchingSelector = innerCreateAdaptedSelector(
+        baseSelector.removeMatchingSelector,
+        mapping,
+      );
+    }
+
+    cachedAdaptedSelector.keySelector = innerCreateAdaptedSelector(
+      baseSelector.keySelector,
+      mapping,
+    );
+  }
+
+  return adaptedSelector;
+};

package/src/createBoundSelector.ts

@@ -0,0 +1,197 @@
+import { Selector } from '@veksa/reselect';
+import { CachedSelector, NamedParametricSelector, NamedSelector } from './types';
+import { isComposedKeySelector, KeySelectorComposer } from './keys/createKeySelectorComposer';
+import { isPropSelector } from './createPropSelector';
+import { excludeDefaultSelectors } from './keys/createKeySelectorCreator';
+import { stringComposeKeySelectors } from './keys/stringComposeKeySelectors';
+import { temporaryAssign } from './_helpers/temporaryAssign';
+import { withDebugName } from './debug/withDebugName';
+import { getSelectorName } from './_helpers/getSelectorName';
+import { isCachedSelector } from './_helpers/isCachedSelector';
+import { isObject } from './_helpers/isObject';
+import { getObjectPaths } from './_helpers/getObjectPaths';
+import { arePathsEqual } from './_helpers/arePathsEqual';
+import { defaultKeySelector } from './keys/defaultKeySelector';
+
+const generateBindingName = <P extends object>(binding: P) => {
+  const structure = Object.keys(binding).reduce(
+    (result, key) => ({
+      ...result,
+      [key]: '[*]',
+    }),
+    {},
+  );
+  const structureKeys = Object.keys(structure).join();
+  const structureValues = Object.values(structure).join();
+
+  return `${structureKeys} -> ${structureValues}`;
+};
+
+/**
+ * The special type to prevent binding of non optional props on optional values
+ */
+export type BoundSelector<S, P2, P1 extends Partial<P2>, R> =
+  P2 extends Pick<P1, keyof P2>
+    ? Exclude<keyof P1, keyof P2> extends never
+      ? NamedSelector<S, R>
+      : NamedParametricSelector<S, Omit<P1, keyof P2>, R>
+    : never;
+
+export type BoundSelectorOptions<S, P2, P1 extends Partial<P2>, R> = {
+  bindingStrategy?: (
+    baseSelector: Selector<S, R, [P1]>,
+    binding: P2,
+  ) => Selector<S, R, [Omit<P1, keyof P2>]>;
+  keySelectorComposer?: KeySelectorComposer;
+};
+
+const innerCreateBoundSelector = <S, P2, P1 extends Partial<P2>, R>(
+  baseSelector: Selector<S, R, [P1]>,
+  binding: P2,
+) => {
+  const boundSelector = (state: S, props: Omit<P1, keyof P2> | void) =>
+    baseSelector(state, {
+      ...props,
+      ...binding,
+    } as unknown as P1);
+
+  return boundSelector as BoundSelector<S, P2, P1, R>;
+};
+
+const createBoundInnerSelector = <S, P2 extends object, P1 extends Partial<P2>, R, OR extends R>(
+  baseSelector: Selector<S, R, [P1]>,
+  binding: P2,
+  options: BoundSelectorOptions<S, P2, P1, OR> = {},
+): BoundSelector<S, P2, P1, R> => {
+  const bindingStrategy =
+    (options.bindingStrategy as typeof innerCreateBoundSelector) ?? innerCreateBoundSelector;
+
+  const keySelectorComposer = options.keySelectorComposer ?? stringComposeKeySelectors;
+
+  const boundSelector = bindingStrategy(baseSelector, binding);
+
+  Object.assign(boundSelector, baseSelector);
+  boundSelector.dependencies = [baseSelector];
+
+  withDebugName(boundSelector, () => {
+    const baseName = getSelectorName(baseSelector);
+    const bindingName = generateBindingName(binding);
+
+    return `${baseName} (${bindingName})`;
+  });
+
+  if (isCachedSelector(baseSelector)) {
+    const cachedBoundSelector = boundSelector as unknown as CachedSelector;
+
+    if (baseSelector.getMatchingSelector) {
+      cachedBoundSelector.getMatchingSelector = bindingStrategy(
+        baseSelector.getMatchingSelector,
+        binding,
+      );
+    }
+
+    if (baseSelector.removeMatchingSelector) {
+      cachedBoundSelector.removeMatchingSelector = bindingStrategy(
+        baseSelector.removeMatchingSelector,
+        binding,
+      );
+    }
+
+    const baseKeySelector = baseSelector.keySelector;
+
+    if (isObject(binding)) {
+      const paths = getObjectPaths(binding);
+      let keySelectors = isComposedKeySelector(baseKeySelector)
+        ? baseKeySelector.dependencies
+        : [baseKeySelector];
+
+      keySelectors = excludeDefaultSelectors(keySelectors);
+
+      keySelectors = keySelectors
+        .filter(
+          (keySelector) =>
+            !isPropSelector(keySelector) ||
+            !paths.some((path) => arePathsEqual(keySelector.path, path)),
+        )
+        .map((keySelector) =>
+          isPropSelector(keySelector) ? keySelector : bindingStrategy(keySelector, binding),
+        );
+
+      if (keySelectors.length === 0) {
+        cachedBoundSelector.keySelector = defaultKeySelector;
+      } else if (keySelectors.length === 1) {
+        const [keySelector] = keySelectors;
+        cachedBoundSelector.keySelector = keySelector;
+      } else {
+        cachedBoundSelector.keySelector = keySelectorComposer(...keySelectors);
+      }
+    } else {
+      cachedBoundSelector.keySelector = bindingStrategy(baseKeySelector, binding);
+    }
+  }
+
+  return boundSelector;
+};
+
+export const createBoundSelector: typeof createBoundInnerSelector = (baseSelector, binding) => {
+  return createBoundInnerSelector(baseSelector, binding, {
+    bindingStrategy: (selector, bindingProps) => {
+      const source = bindingProps as unknown as Record<string, unknown>;
+      const keys = Object.keys(source);
+
+      /**
+       * Almost every binding is a single key — `bound(selector, { positionId })` —
+       * and specialising it removes the two allocations the generic path costs per
+       * call: the `{ result, rollback }` object and the `rollback` closure. On a
+       * graph with a bound selector per row those are the calls that dominate.
+       *
+       * The `delete` in the restore stays deliberately. Leaving the key behind as
+       * `undefined` would be cheaper — it avoids putting the caller's props object
+       * into dictionary mode — but it also changes the object's shape, and
+       * `useSelector` memoizes props shallowly: a props object that has grown an
+       * extra key never again compares equal to a freshly built one, so the
+       * memoization the binding exists to protect would be defeated.
+       */
+      if (keys.length === 1) {
+        const key = keys[0];
+        const value = source[key];
+
+        return (state, props) => {
+          const target = props as unknown as Record<string, unknown>;
+
+          if (typeof target !== 'object' || target === null) {
+            return selector(state, source as Parameters<typeof baseSelector>[1]);
+          }
+
+          const previous = target[key];
+
+          // A re-entrant call that finds the binding already applied has nothing to
+          // save and nothing to restore.
+          if (previous === value) {
+            return selector(state, props as Parameters<typeof baseSelector>[1]);
+          }
+
+          const had = Object.prototype.hasOwnProperty.call(target, key);
+          target[key] = value;
+
+          try {
+            return selector(state, props as Parameters<typeof baseSelector>[1]);
+          } finally {
+            if (had) {
+              target[key] = previous;
+            } else {
+              delete target[key];
+            }
+          }
+        };
+      }
+
+      return (state, props) => {
+        const { result: nextProps, rollback } = temporaryAssign(props, source);
+        const result = selector(state, nextProps as Parameters<typeof baseSelector>[1]);
+        rollback();
+        return result;
+      };
+    },
+  });
+};