reselect-kit 1.0.0

package/src/keys/__tests__/arrayComposeKeySelectors.test.ts

@@ -0,0 +1,52 @@
+import { arrayComposeKeySelectors } from '../arrayComposeKeySelectors';
+import { createPropSelector } from '../../createPropSelector';
+import { isComposedKeySelector } from '../createKeySelectorComposer';
+
+describe('arrayComposeKeySelectors', () => {
+  const firstPropSelector = createPropSelector<{ value1: number }>().value1();
+  const secondPropSelector = createPropSelector<{
+    value2: number;
+  }>().value2();
+  const thirdPropSelector = createPropSelector<{ value3: number }>().value3();
+
+  test('should return composed key selector', () => {
+    const keySelector = arrayComposeKeySelectors(
+      firstPropSelector,
+      secondPropSelector,
+      thirdPropSelector,
+    );
+
+    expect(isComposedKeySelector(keySelector)).toBeTruthy();
+  });
+
+  test('should return array of results from input selectors', () => {
+    const keySelector = arrayComposeKeySelectors(
+      firstPropSelector,
+      secondPropSelector,
+      thirdPropSelector,
+    );
+
+    const key: unknown = keySelector(expect.anything(), {
+      value1: 1,
+      value2: 2,
+      value3: 3,
+    });
+
+    expect(key).toEqual([1, 2, 3]);
+  });
+
+  test('should return flat array', () => {
+    const keySelector = arrayComposeKeySelectors(
+      firstPropSelector,
+      arrayComposeKeySelectors(secondPropSelector, thirdPropSelector),
+    );
+
+    const key: unknown = keySelector(expect.anything(), {
+      value1: 1,
+      value2: 2,
+      value3: 3,
+    });
+
+    expect(key).toEqual([1, 2, 3]);
+  });
+});

package/src/keys/__tests__/createKeySelectorCreator.test.ts

@@ -0,0 +1,246 @@
+import { createCachedSelector } from '@veksa/re-reselect';
+import { createPropSelector } from '../../createPropSelector';
+import { createKeySelectorCreator } from '../createKeySelectorCreator';
+import { createPathSelector } from '../../createPathSelector';
+import { createAdaptedSelector } from '../../createAdaptedSelector';
+import { createChainSelector } from '../../createChainSelector';
+import { stringComposeKeySelectors } from '../stringComposeKeySelectors';
+
+describe('createKeySelectorCreator', () => {
+  const keySelectorCreator = createKeySelectorCreator(stringComposeKeySelectors);
+
+  const firstKeySelector = createPropSelector<{
+    firstProp: string;
+  }>().firstProp();
+
+  const secondKeySelector = createPropSelector<{
+    secondProp: string;
+  }>().secondProp();
+
+  const thirdKeySelector = createPropSelector<{
+    thirdProp: { value: string };
+  }>().thirdProp.value();
+
+  const firstSelector = createCachedSelector(
+    firstKeySelector,
+    () => undefined,
+  )({
+    keySelector: firstKeySelector,
+  });
+
+  const secondSelector = createCachedSelector(secondKeySelector, () => ({
+    someValue: 'someValue',
+  }))({
+    keySelector: secondKeySelector,
+  });
+
+  test('should compose result selector key with delimiter', () => {
+    const keySelector = keySelectorCreator({
+      inputSelectors: [firstSelector, secondSelector],
+    });
+
+    const firstProp = 'firstProp';
+    const secondProp = 'secondProp';
+
+    const key = keySelector(expect.anything(), {
+      firstProp,
+      secondProp,
+    }) as unknown;
+
+    expect(key).toBe(`${firstProp}:${secondProp}`);
+  });
+
+  test('should use own keySelector in composition', () => {
+    const keySelector = keySelectorCreator({
+      keySelector: firstKeySelector,
+      inputSelectors: [secondSelector],
+    });
+
+    const firstProp = 'firstProp';
+    const secondProp = 'secondProp';
+
+    const key = keySelector(expect.anything(), {
+      firstProp,
+      secondProp,
+    } as { firstProp: string }) as unknown;
+
+    expect(key).toBe(`${firstProp}:${secondProp}`);
+  });
+
+  test('should compose any number of selectors', () => {
+    const keySelector = keySelectorCreator({
+      keySelector: thirdKeySelector,
+      inputSelectors: [firstSelector, secondSelector],
+    });
+
+    const firstProp = 'firstProp';
+    const secondProp = 'secondProp';
+    const thirdProp = { value: 'thirdProp' };
+
+    const key = keySelector(expect.anything(), {
+      firstProp,
+      secondProp,
+      thirdProp,
+    } as { thirdProp: { value: string } }) as unknown;
+
+    expect(key).toBe(`${thirdProp.value}:${firstProp}:${secondProp}`);
+  });
+
+  test('should not duplicate selectors if they are equal', () => {
+    const keySelector = keySelectorCreator({
+      keySelector: firstKeySelector,
+      inputSelectors: [firstSelector, firstSelector, firstSelector],
+    });
+
+    const firstProp = 'firstProp';
+
+    const key = keySelector(expect.anything(), {
+      firstProp,
+    }) as unknown;
+
+    expect(key).toBe(firstProp);
+    expect(keySelector).toBe(firstKeySelector);
+  });
+
+  test(
+    'should be able extract keySelector from wrapped dependencies ' +
+      '(adaptedSelector, boundSelector and pathSelector)',
+    () => {
+      const inputSelector = createPathSelector(
+        createAdaptedSelector(secondSelector, (props: { altSecondProp: string }) => ({
+          secondProp: `alt ${props.altSecondProp}`,
+        })),
+      ).someValue();
+
+      const keySelector = keySelectorCreator({
+        keySelector: firstKeySelector,
+        inputSelectors: [inputSelector],
+      });
+
+      const firstProp = 'firstProp';
+      const altSecondProp = 'secondProp';
+
+      const key = keySelector(expect.anything(), {
+        firstProp,
+        altSecondProp,
+      } as { firstProp: string }) as unknown;
+
+      expect(key).toBe(`${firstProp}:alt ${altSecondProp}`);
+    },
+  );
+
+  test('should be able extract keySelector from chainSelector', () => {
+    const inputSelector = createChainSelector(firstSelector)
+      .chain(() => secondSelector)
+      .build();
+
+    const keySelector = keySelectorCreator({
+      keySelector: thirdKeySelector,
+      inputSelectors: [inputSelector],
+    });
+
+    const firstProp = 'firstProp';
+    const secondProp = 'secondProp';
+    const thirdProp = { value: 'thirdProp' };
+
+    const key = keySelector(expect.anything(), {
+      firstProp,
+      secondProp,
+      thirdProp,
+    } as { thirdProp: { value: string } }) as unknown;
+
+    expect(key).toBe(`${thirdProp.value}:${firstProp}:${secondProp}`);
+  });
+
+  test('should can be used as real keySelectorCreator', () => {
+    const cachedSelector = createCachedSelector(
+      [firstSelector, secondSelector],
+      () => undefined,
+    )({
+      keySelectorCreator,
+    });
+
+    const { keySelector } = cachedSelector;
+    const firstProp = 'firstProp';
+    const secondProp = 'secondProp';
+
+    const key = keySelector(expect.anything(), {
+      firstProp,
+      secondProp,
+    }) as unknown;
+
+    expect(key).toBe(`${firstProp}:${secondProp}`);
+  });
+
+  test('should flat output key selector', () => {
+    const inputKeySelector = createPropSelector<{
+      prop: string;
+    }>().prop();
+
+    const keySelector = keySelectorCreator({
+      keySelector: stringComposeKeySelectors(inputKeySelector, inputKeySelector),
+      inputSelectors: [
+        createCachedSelector(
+          inputKeySelector,
+          () => undefined,
+        )({
+          keySelector: stringComposeKeySelectors(inputKeySelector, inputKeySelector),
+        }),
+        createCachedSelector(
+          inputKeySelector,
+          () => undefined,
+        )({
+          keySelector: stringComposeKeySelectors(inputKeySelector, inputKeySelector),
+        }),
+      ],
+    });
+
+    const prop = 'prop';
+
+    const key = keySelector(expect.anything(), {
+      prop,
+    }) as unknown;
+
+    expect(key).toBe(`${prop}`);
+  });
+
+  test(
+    'should flat output key selector ' + '(even if prop selectors are declared independently)',
+    () => {
+      const keySelector = keySelectorCreator({
+        keySelector: stringComposeKeySelectors(
+          createPropSelector<{ prop: string }>().prop(),
+          createPropSelector<{ prop: string }>().prop(),
+        ),
+        inputSelectors: [
+          createCachedSelector(
+            createPropSelector<{ prop: string }>().prop(),
+            () => undefined,
+          )({
+            keySelector: stringComposeKeySelectors(
+              createPropSelector<{ prop: string }>().prop(),
+              createPropSelector<{ prop: string }>().prop(),
+            ),
+          }),
+          createCachedSelector(
+            createPropSelector<{ prop: string }>().prop(),
+            () => undefined,
+          )({
+            keySelector: stringComposeKeySelectors(
+              createPropSelector<{ prop: string }>().prop(),
+              createPropSelector<{ prop: string }>().prop(),
+            ),
+          }),
+        ],
+      });
+
+      const prop = 'prop';
+
+      const key = keySelector(expect.anything(), {
+        prop,
+      }) as unknown;
+
+      expect(key).toBe(`${prop}`);
+    },
+  );
+});

package/src/keys/__tests__/stringComposeKeySelectors.test.ts

@@ -0,0 +1,52 @@
+import { stringComposeKeySelectors } from '../stringComposeKeySelectors';
+import { createPropSelector } from '../../createPropSelector';
+import { isComposedKeySelector } from '../createKeySelectorComposer';
+
+describe('stringComposeKeySelectors', () => {
+  const firstPropSelector = createPropSelector<{ value1: number }>().value1();
+  const secondPropSelector = createPropSelector<{
+    value2: number;
+  }>().value2();
+  const thirdPropSelector = createPropSelector<{ value3: number }>().value3();
+
+  test('should return composed key selector', () => {
+    const keySelector = stringComposeKeySelectors(
+      firstPropSelector,
+      secondPropSelector,
+      thirdPropSelector,
+    );
+
+    expect(isComposedKeySelector(keySelector)).toBeTruthy();
+  });
+
+  test('should return string with results from input selectors', () => {
+    const keySelector = stringComposeKeySelectors(
+      firstPropSelector,
+      secondPropSelector,
+      thirdPropSelector,
+    );
+
+    const key: unknown = keySelector(expect.anything(), {
+      value1: 1,
+      value2: 2,
+      value3: 3,
+    });
+
+    expect(key).toEqual('1:2:3');
+  });
+
+  test('should return flat string', () => {
+    const keySelector = stringComposeKeySelectors(
+      firstPropSelector,
+      stringComposeKeySelectors(secondPropSelector, thirdPropSelector),
+    );
+
+    const key: unknown = keySelector(expect.anything(), {
+      value1: 1,
+      value2: 2,
+      value3: 3,
+    });
+
+    expect(key).toEqual('1:2:3');
+  });
+});

package/src/keys/arrayComposeKeySelectors.ts

@@ -0,0 +1,20 @@
+import { createKeySelectorComposer } from './createKeySelectorComposer';
+
+export const arrayComposeKeySelectors = createKeySelectorComposer(
+  (...keySelectors) =>
+    (state, props) => {
+      let keyPath: unknown[] = [];
+
+      for (let i = 0; i < keySelectors.length; i += 1) {
+        const key: unknown = keySelectors[i](state, props);
+
+        if (Array.isArray(key)) {
+          keyPath = keyPath.concat(key);
+        } else {
+          keyPath.push(key);
+        }
+      }
+
+      return keyPath;
+    },
+);

package/src/keys/createKeySelectorComposer.ts

@@ -0,0 +1,68 @@
+import { KeySelector } from '@veksa/re-reselect';
+import { UnionToIntersection } from '../types';
+
+export const composedKeySelectorSymbol = Symbol.for('ComposedKeySelector');
+
+/**
+ * The loosest shape a key selector can take: a function of `state` plus any
+ * number of extra arguments (props, ...). Used for variadic tuple inference.
+ */
+type AnyKeySelector = KeySelector<any>;
+
+/** Intersection of every input key selector's `state` argument. */
+type ComposedState<Ks extends readonly AnyKeySelector[]> = UnionToIntersection<
+  { [Index in keyof Ks]: Parameters<Ks[Index]>[0] }[number]
+>;
+
+/** Union of every input key selector's `props` argument (position 1), if any. */
+type PropsUnion<Ks extends readonly AnyKeySelector[]> = {
+  [Index in keyof Ks]: Parameters<Ks[Index]> extends [any, infer Props, ...any[]] ? Props : never;
+}[number];
+
+/** Intersection of every input key selector's `props`, or `never` if none are parametric. */
+type ComposedProps<Ks extends readonly AnyKeySelector[]> = [PropsUnion<Ks>] extends [never]
+  ? never
+  : UnionToIntersection<PropsUnion<Ks>>;
+
+/**
+ * The key selector produced by a {@link KeySelectorComposer}: a function that
+ * intersects the `state` (and `props`, when any input is parametric) of every
+ * composed key selector, tagged with the original inputs as `dependencies`.
+ */
+export type OutputKeySelector<S, P, D extends readonly AnyKeySelector[]> = ([P] extends [never]
+  ? (state: S) => unknown
+  : (state: S, props: P) => unknown) & {
+  dependencies: D;
+};
+
+/**
+ * Composes N key selectors into a single one. A single variadic signature with
+ * tuple inference replaces the former per-arity overload set.
+ */
+export type KeySelectorComposer = <Ks extends readonly AnyKeySelector[]>(
+  ...keySelectors: Ks
+) => OutputKeySelector<ComposedState<Ks>, ComposedProps<Ks>, Ks>;
+
+export function isComposedKeySelector(
+  keySelector: AnyKeySelector,
+): keySelector is AnyKeySelector & { dependencies: AnyKeySelector[] } {
+  return 'dependencies' in keySelector && composedKeySelectorSymbol in keySelector;
+}
+
+export function createKeySelectorComposer(
+  baseKeySelectorComposer: (...keySelectors: AnyKeySelector[]) => AnyKeySelector,
+): KeySelectorComposer {
+  return ((...keySelectors: AnyKeySelector[]) => {
+    const resultSelector = baseKeySelectorComposer(...keySelectors) as AnyKeySelector & {
+      dependencies: AnyKeySelector[];
+    };
+
+    resultSelector.dependencies = keySelectors;
+
+    Object.defineProperty(resultSelector, composedKeySelectorSymbol, {
+      value: true,
+    });
+
+    return resultSelector;
+  }) as KeySelectorComposer;
+}

package/src/keys/createKeySelectorCreator.ts

@@ -0,0 +1,106 @@
+import { KeySelector } from '@veksa/re-reselect';
+import { isPropSelector } from '../createPropSelector';
+import { isComposedKeySelector, KeySelectorComposer } from './createKeySelectorComposer';
+import { arePathsEqual } from '../_helpers/arePathsEqual';
+import { defaultKeySelector } from './defaultKeySelector';
+import { isCachedSelector } from '../_helpers/isCachedSelector';
+
+const areSelectorsEqual = (selector: unknown, another: unknown) => {
+  if (selector === another) {
+    return true;
+  }
+
+  if (isPropSelector(selector) && isPropSelector(another)) {
+    return arePathsEqual(selector.path, another.path);
+  }
+
+  return false;
+};
+
+const flatKeySelectors = <S>(keySelectors: KeySelector<S>[]) => {
+  const result: typeof keySelectors = [];
+
+  for (let i = 0; i < keySelectors.length; i += 1) {
+    const keySelector = keySelectors[i];
+
+    if (isComposedKeySelector(keySelector)) {
+      result.push(...flatKeySelectors(keySelector.dependencies));
+    } else {
+      result.push(keySelector);
+    }
+  }
+
+  return result;
+};
+
+const uniqKeySelectors = <S>(keySelectors: KeySelector<S>[]) => {
+  const result: typeof keySelectors = [];
+
+  for (let i = 0; i < keySelectors.length; i += 1) {
+    const keySelector = keySelectors[i];
+
+    const isKeySelectorAdded = result.some((resultKeySelector) =>
+      areSelectorsEqual(keySelector, resultKeySelector),
+    );
+    if (!isKeySelectorAdded) {
+      result.push(keySelector);
+    }
+  }
+
+  return result;
+};
+
+export const excludeDefaultSelectors = <S>(keySelectors: KeySelector<S>[]) => {
+  const result: typeof keySelectors = [];
+
+  for (let i = 0; i < keySelectors.length; i += 1) {
+    const keySelector = keySelectors[i];
+
+    if (keySelector !== defaultKeySelector) {
+      result.push(keySelector);
+    }
+  }
+
+  return result;
+};
+
+export function createKeySelectorCreator(
+  keySelectorComposer: KeySelectorComposer,
+): <S, D>(selectorInputs: { inputSelectors: D; keySelector?: KeySelector<S> }) => KeySelector<S> {
+  return <S>({
+    inputSelectors,
+    keySelector,
+  }: {
+    inputSelectors: unknown;
+    keySelector?: KeySelector<S>;
+  }) => {
+    let keySelectors: KeySelector<S>[] = [];
+
+    if (keySelector) {
+      keySelectors.push(keySelector);
+    }
+
+    (inputSelectors as unknown[]).forEach((selector) => {
+      if (isCachedSelector(selector)) {
+        keySelectors.push(selector.keySelector);
+      }
+    });
+
+    keySelectors = flatKeySelectors(keySelectors);
+    keySelectors = uniqKeySelectors(keySelectors);
+    keySelectors = excludeDefaultSelectors(keySelectors);
+
+    if (keySelectors.length === 0) {
+      return defaultKeySelector;
+    }
+
+    if (keySelectors.length === 1) {
+      const [resultSelector] = keySelectors;
+      return resultSelector;
+    }
+
+    // The composer infers a `UnionToIntersection` state from the runtime array,
+    // which TS can't see as identical to `S`; narrow it back for the caller.
+    return keySelectorComposer(...keySelectors) as KeySelector<S>;
+  };
+}

package/src/keys/defaultKeySelector.ts

@@ -0,0 +1 @@
+export const defaultKeySelector = () => '<DefaultKey>';

package/src/keys/stringComposeKeySelectors.ts

@@ -0,0 +1,15 @@
+import { createKeySelectorComposer } from './createKeySelectorComposer';
+
+export const stringComposeKeySelectors = createKeySelectorComposer(
+  (...keySelectors) =>
+    (state, props) => {
+      let key: unknown = keySelectors[0](state, props);
+
+      for (let i = 1; i < keySelectors.length; i += 1) {
+        key += ':';
+        key += keySelectors[i](state, props);
+      }
+
+      return key;
+    },
+);

package/src/types.ts

@@ -0,0 +1,43 @@
+import { Selector, SelectorArray } from '@veksa/reselect';
+import { OutputCachedSelector } from '@veksa/re-reselect';
+
+/**
+ * A selector carrying optional debug metadata. In the unified model a
+ * "parametric" selector is simply a selector whose `Params` tuple is non-empty,
+ * so a single type covers both cases.
+ *
+ * @template Params - Extra arguments beyond `state` (e.g. `[Props]`).
+ * @template D - The selector's dependency tuple, surfaced for debug tooling.
+ */
+export type NamedSelector<S, R, Params extends readonly any[] = [], D = unknown[]> = Selector<
+  S,
+  R,
+  Params
+> & {
+  selectorName?: string;
+  dependencies?: D;
+};
+
+/**
+ * Back-compat alias: a parametric selector is a {@link NamedSelector} whose
+ * single extra argument is `Props`.
+ */
+export type NamedParametricSelector<S, P, R, D = unknown[]> = NamedSelector<S, R, [P], D>;
+
+export type ReReselectSelector = OutputCachedSelector<SelectorArray, unknown>;
+
+export type CachedSelector = Pick<ReReselectSelector, 'cache' | 'keySelector'> &
+  Partial<ReReselectSelector>;
+
+export type Path = string[];
+
+/**
+ * Turns a union `A | B | C` into the intersection `A & B & C`. Not exported by
+ * reselect, so kept here for the selector-composition helpers that need to
+ * intersect the `state`/`props` of several selectors.
+ */
+export type UnionToIntersection<Union> = (
+  Union extends unknown ? (distributed: Union) => void : never
+) extends (merged: infer Intersection) => void
+  ? Intersection
+  : never;

package/src/vitest-globals.d.ts

@@ -0,0 +1 @@
+/// <reference types="vitest/globals" />