reselect-kit 1.0.0

package/src/createCachedSequenceSelector.ts

@@ -0,0 +1,18 @@
+import { createSelector, Selector } from '@veksa/reselect';
+import { createCachedSelector, PolymorphicCachedOptions } from '@veksa/re-reselect';
+import { createSequenceSelector } from './createSequenceSelector';
+
+export function createCachedSequenceSelector<S, R>(
+  selectors: Selector<S, R>[],
+): (options: PolymorphicCachedOptions<Selector<S, R>[], R[]>) => Selector<S, R[]>;
+
+export function createCachedSequenceSelector<S, P, R>(
+  selectors: Selector<S, R, [P]>[],
+): (options: PolymorphicCachedOptions<Selector<S, R, [P]>[], R[]>) => Selector<S, R[], [P]>;
+
+export function createCachedSequenceSelector(selectors: any): any {
+  return createSequenceSelector(
+    selectors,
+    createCachedSelector as unknown as typeof createSelector,
+  );
+}

package/src/createCachedStructuredSelector.ts

@@ -0,0 +1,44 @@
+import { createSelector, Selector, SelectorResultsMap, SelectorsObject } from '@veksa/reselect';
+import { createCachedSelector, PolymorphicCachedOptions } from '@veksa/re-reselect';
+import { createStructuredSelector } from './createStructuredSelector';
+import { UnionToIntersection } from './types';
+
+/** Intersection of the `state` argument of every selector in the object. */
+type StructuredState<M extends SelectorsObject> = UnionToIntersection<
+  { [K in keyof M]: Parameters<M[K]>[0] }[keyof M]
+>;
+
+/** Union of the `props` argument (position 1) of every parametric selector. */
+type StructuredPropsUnion<M extends SelectorsObject> = {
+  [K in keyof M]: Parameters<M[K]> extends [any, infer Props, ...any[]] ? Props : never;
+}[keyof M];
+
+/** The extra-arguments tuple: `[Props]` when any selector is parametric, else `[]`. */
+type StructuredParams<M extends SelectorsObject> = [StructuredPropsUnion<M>] extends [never]
+  ? []
+  : [UnionToIntersection<StructuredPropsUnion<M>>];
+
+/** The input selectors as reselect sees them, used to type the cached options. */
+type StructuredInputs<M extends SelectorsObject> = Selector<
+  StructuredState<M>,
+  unknown,
+  StructuredParams<M>
+>[];
+
+/**
+ * A single variadic signature replaces the former `Selector` / `ParametricSelector`
+ * conditional: `state` and `props` are derived from the selectors object, so a
+ * parametric input keeps its props type without a separate overload.
+ */
+export function createCachedStructuredSelector<M extends SelectorsObject>(
+  selectors: M,
+): (
+  options: PolymorphicCachedOptions<StructuredInputs<M>, SelectorResultsMap<M>>,
+) => Selector<StructuredState<M>, SelectorResultsMap<M>, StructuredParams<M>>;
+
+export function createCachedStructuredSelector(selectors: any): any {
+  return createStructuredSelector(
+    selectors,
+    createCachedSelector as unknown as typeof createSelector,
+  );
+}

package/src/createChainSelector.ts

@@ -0,0 +1,230 @@
+import { createSelectorCreator, Selector } from '@veksa/reselect';
+import { createCachedSelector, ICacheObject, KeySelector } from '@veksa/re-reselect';
+import { KeySelectorComposer } from './keys/createKeySelectorComposer';
+import { isCachedSelector } from './_helpers/isCachedSelector';
+import { defaultKeySelector } from './keys/defaultKeySelector';
+import { stringComposeKeySelectors } from './keys/stringComposeKeySelectors';
+import { createKeySelectorCreator } from './keys/createKeySelectorCreator';
+import { runInDebug, withDebugName } from './debug/withDebugName';
+import { defineDynamicSelectorName } from './_helpers/defineDynamicSelectorName';
+import { getSelectorName } from './_helpers/getSelectorName';
+import { generateSelectorKey } from './_helpers/generateSelectorKey';
+import { stringifyFunction } from './_helpers/stringifyFunction';
+
+export type SelectorChain<R1, S1, R2> = (result: R1) => Selector<S1, R2>;
+
+export type ParametricSelectorChain<R1, S1, P1, R2> = (result: R1) => Selector<S1, R2, [P1]>;
+
+export type SelectorChainHierarchy<
+  C extends SelectorChain<any, any, any>,
+  H extends SelectorChainHierarchy<any, any>,
+> = C & { parentChain?: H };
+
+export type ParametricSelectorChainHierarchy<
+  C extends ParametricSelectorChain<any, any, any, any>,
+  H extends ParametricSelectorChainHierarchy<any, any>,
+> = C & { parentChain?: H };
+
+export type CreateSelectorOptions<SelectorCreator extends typeof createSelectorCreator> = {
+  selectorCreator: ReturnType<SelectorCreator>;
+  cacheObject: ICacheObject;
+};
+
+export type ChainSelectorOptions<
+  SelectorCreator extends typeof createSelectorCreator = typeof createSelectorCreator,
+> = {
+  createSelectorOptions?: () => CreateSelectorOptions<SelectorCreator>;
+  keySelectorComposer?: KeySelectorComposer;
+};
+
+interface ChainSelectorResult<S1, R1> {
+  chain: <S2, R2 = any>(
+    fn: SelectorChain<R1, S2, R2>,
+    chainOptions?: ChainSelectorOptions,
+  ) => ChainSelectorResult<S1 & S2, R2>;
+  map: <R2>(
+    fn: (result: R1) => R2,
+    mapOptions?: ChainSelectorOptions,
+  ) => ChainSelectorResult<S1, R2>;
+  build: () => Selector<S1, R1, []> & {
+    chainHierarchy: SelectorChainHierarchy<any, any> | undefined;
+  };
+}
+
+interface ParametricChainSelectorResult<S1, P1, R1> {
+  chain: <S2, P2 = unknown, R2 = any>(
+    fn: ParametricSelectorChain<R1, S2, P2, R2>,
+    chainOptions?: ChainSelectorOptions,
+  ) => ParametricChainSelectorResult<S1 & S2, P1 & P2, R2>;
+  map: <R2>(
+    fn: (result: R1) => R2,
+    mapOptions?: ChainSelectorOptions,
+  ) => ParametricChainSelectorResult<S1, P1, R2>;
+  build: () => Selector<S1, R1, [P1]> & {
+    chainHierarchy: ParametricSelectorChainHierarchy<any, any> | undefined;
+  };
+}
+
+export function createChainSelector<S1, R1>(
+  selector: Selector<S1, R1>,
+  options?: ChainSelectorOptions,
+  prevChain?: SelectorChainHierarchy<any, any>,
+): ChainSelectorResult<S1, R1>;
+
+export function createChainSelector<S1, P1, R1>(
+  selector: Selector<S1, R1, [P1]>,
+  options?: ChainSelectorOptions,
+  prevChain?: ParametricSelectorChainHierarchy<any, any>,
+): ParametricChainSelectorResult<S1, P1, R1>;
+
+export function createChainSelector<S1, P1, R1>(
+  selector: any,
+  options?: ChainSelectorOptions,
+  prevChain?: any,
+): any {
+  const chain = <S2, P2, R2>(fn: any, chainOptions?: ChainSelectorOptions) => {
+    const combinedOptions = {
+      ...options,
+      ...chainOptions,
+    };
+
+    const keySelector = isCachedSelector(selector) ? selector.keySelector : defaultKeySelector;
+
+    const { createSelectorOptions = () => ({}), keySelectorComposer = stringComposeKeySelectors } =
+      combinedOptions;
+
+    const keySelectorCreator = createKeySelectorCreator(keySelectorComposer);
+
+    const higherOrderSelector = createCachedSelector(
+      [selector],
+      fn,
+    )({
+      ...createSelectorOptions(),
+      keySelector,
+    });
+
+    withDebugName(higherOrderSelector, () => {
+      const baseName = getSelectorName(selector);
+
+      return `higher order for ${baseName} (${stringifyFunction(fn)})`;
+    });
+
+    type CombineSelector = Selector<S1 & S2, R1 & R2, [P1 & P2]> & {
+      dependencies: any;
+      cache: ICacheObject;
+      keySelector?: KeySelector<S1 & S2>;
+    };
+
+    const combinedSelector: CombineSelector = (state: S1 & S2, props: P1 & P2): R1 & R2 => {
+      const derivedSelector: any = (higherOrderSelector as any)(state, props);
+
+      runInDebug(() => {
+        // Debug-only: shows the branch this call took. Nothing outside the debug
+        // tooling reads it, so in production it was an array allocated per call and
+        // abandoned. The static `[higherOrderSelector]` below still stands.
+        combinedSelector.dependencies = [higherOrderSelector, derivedSelector];
+
+        const derivedSelectorName = getSelectorName(derivedSelector);
+
+        if (!derivedSelectorName) {
+          defineDynamicSelectorName(derivedSelector, () => {
+            const baseName = getSelectorName(selector);
+            const derivedSelectorKey = generateSelectorKey(derivedSelector);
+
+            return `derived from ${baseName} (${derivedSelectorKey})`;
+          });
+        }
+
+        defineDynamicSelectorName(combinedSelector, () => {
+          const baseName = getSelectorName(selector);
+          const dependencyName = getSelectorName(derivedSelector);
+
+          return `${baseName} (chained by ${dependencyName})`;
+        });
+      });
+
+      return derivedSelector(state, props);
+    };
+
+    combinedSelector.dependencies = [higherOrderSelector];
+    combinedSelector.cache = higherOrderSelector.cache;
+
+    /**
+     * The derived selector's key selector, memoized on the derived selector itself.
+     *
+     * This used to be a second `createCachedSelector` over `[higherOrderSelector]`,
+     * which meant every key computation paid a whole extra cached-selector layer —
+     * its own key computation, its own cache lookup, and its own evaluation of
+     * `higherOrderSelector` — to produce a value that depends on nothing but the
+     * derived selector. A `WeakMap` keyed on that selector is the same mapping with
+     * none of the layer, and it shares across cache keys rather than per key.
+     *
+     * Note what is deliberately *not* memoized: the `(state, props)` pair. `props`
+     * is mutated in place by `createBoundSelector`, so two calls can pass the same
+     * object reference with different contents, and a reference-keyed cache would
+     * hand back a stale selector.
+     */
+    const derivedKeySelectors = new WeakMap<object, KeySelector<S1 & S2>>();
+
+    combinedSelector.keySelector = (state: S1 & S2, props: P1 & P2) => {
+      const derivedSelector: any = (higherOrderSelector as any)(state, props);
+
+      let derivedKeySelector = derivedKeySelectors.get(derivedSelector);
+
+      if (derivedKeySelector === undefined) {
+        derivedKeySelector = keySelectorCreator({
+          inputSelectors: [higherOrderSelector, derivedSelector],
+        }) as KeySelector<S1 & S2>;
+
+        derivedKeySelectors.set(derivedSelector, derivedKeySelector);
+      }
+
+      return (derivedKeySelector as any)(state, props);
+    };
+
+    withDebugName(combinedSelector, () => {
+      const baseName = getSelectorName(selector);
+
+      return `${baseName} (will be chained ${stringifyFunction(fn)})`;
+    });
+
+    const nextPrevChain = Object.assign(fn, {
+      parentChain: prevChain,
+    });
+
+    return createChainSelector<S1 & S2, P1 & P2, R1 & R2>(
+      combinedSelector,
+      combinedOptions,
+      nextPrevChain,
+    );
+  };
+
+  const map = <R2>(fn: (result: R1) => R2, mapOptions?: ChainSelectorOptions) => {
+    const mapSelector = (result: R1) => {
+      const output = fn(result);
+      const mapSelector = () => output;
+
+      withDebugName(mapSelector, () => {
+        const baseName = getSelectorName(selector);
+
+        return `mapped from ${baseName} (${stringifyFunction(fn)})`;
+      });
+
+      return mapSelector;
+    };
+
+    return chain(mapSelector, mapOptions);
+  };
+
+  const build = () => {
+    return Object.assign(selector, {
+      chainHierarchy: prevChain,
+    });
+  };
+
+  return {
+    chain,
+    map,
+    build,
+  };
+}

package/src/createEmptySelector.ts

@@ -0,0 +1,27 @@
+import { Selector } from '@veksa/reselect';
+import { CachedSelector } from './types';
+import { isCachedSelector } from './_helpers/isCachedSelector';
+import { defaultKeySelector } from './keys/defaultKeySelector';
+
+/**
+ * Creates a selector that always resolves to `undefined`. Used as the "no link"
+ * branch of a chain (e.g. an optional relation that isn't present).
+ *
+ * When the base selector is cached, the empty selector is tagged with
+ * {@link defaultKeySelector} so that it still passes {@link isCachedSelector}
+ * and takes part in key-selector composition. The default key is deliberately
+ * the only cache-related metadata copied: an empty selector has no result to
+ * memoize, so it needs no `cache` / `getMatchingSelector` of its own, and the
+ * default key is dropped by `excludeDefaultSelectors` during composition.
+ */
+export const createEmptySelector = <S, R>(
+  baseSelector: Selector<S, R, any[]>,
+): Selector<S, R | undefined> => {
+  const emptySelector = () => undefined;
+
+  if (isCachedSelector(baseSelector)) {
+    (emptySelector as unknown as CachedSelector).keySelector = defaultKeySelector;
+  }
+
+  return emptySelector;
+};

package/src/createPathSelector.ts

@@ -0,0 +1,208 @@
+import { Selector } from '@veksa/reselect';
+import { NamedParametricSelector, NamedSelector, Path } from './types';
+import { isObject } from './_helpers/isObject';
+import { withDebugName } from './debug/withDebugName';
+import { getSelectorName } from './_helpers/getSelectorName';
+
+export type Defined<T> = Exclude<T, undefined>;
+
+export type IsOptional<T> = undefined extends T ? true : null extends T ? true : false;
+
+export type IsObject<T> = T extends object ? true : false;
+
+export type PathSelector<S, R, D> = NamedSelector<S, R, [], D> & {
+  path: Path;
+};
+
+export type PathParametricSelector<S, P, R, D> = NamedParametricSelector<S, P, R, D> & {
+  path: Path;
+};
+
+type Required<T> = { [P in keyof T]-?: Exclude<T[P], undefined | null> };
+
+export type RequiredSelectorBuilder<S, R, D> = R extends object
+  ? { [K in keyof R]: () => PathSelector<S, NonNullable<R[K]>, D> }
+  : {};
+
+export type OptionalSelectorBuilder<S, R, D> = ((
+  defaultValue?: R,
+) => PathSelector<S, R extends undefined ? Defined<R> : R, D>) &
+  (R extends object
+    ? { [K in keyof Required<R>]: () => PathSelector<S, NonNullable<R[K]>, D> }
+    : {});
+
+export type RequiredParametricSelectorBuilder<S, P, R, D> = R extends object
+  ? { [K in keyof R]: () => PathParametricSelector<S, P, NonNullable<R[K]>, D> }
+  : {};
+
+export type OptionalParametricSelectorBuilder<S, P, R, D> = ((
+  defaultValue?: R,
+) => PathParametricSelector<S, P, R extends undefined ? Defined<R> : R, D>) &
+  (R extends object
+    ? { [K in keyof Required<R>]: () => PathParametricSelector<S, P, NonNullable<R[K]>, D> }
+    : {});
+
+export type RequiredObjectSelectorWrapper<S, R, D> = {
+  [K in keyof R]-?: IsOptional<R[K]> extends true
+    ? OptionalPathSelectorType<S, R[K], D>
+    : RequiredPathSelectorType<S, R[K], D>;
+};
+
+export type OptionalObjectSelectorWrapper<S, R, D> = {
+  [K in keyof R]-?: OptionalPathSelectorType<S, R[K], D>;
+};
+
+export type RequiredObjectParametricSelectorWrapper<S, P, R, D> = {
+  [K in keyof R]-?: IsOptional<R[K]> extends true
+    ? OptionalPathParametricSelectorType<S, P, R[K], D>
+    : RequiredPathParametricSelectorType<S, P, R[K], D>;
+};
+
+export type OptionalObjectParametricSelectorWrapper<S, P, R, D> = {
+  [K in keyof R]-?: OptionalPathParametricSelectorType<S, P, R[K], D>;
+};
+
+export type RequiredArraySelectorWrapper<S, R, D> = {
+  length: RequiredPathSelectorType<S, number, D>;
+
+  [K: number]: IsOptional<R> extends true
+    ? OptionalPathSelectorType<S, R, D>
+    : RequiredPathSelectorType<S, R, D>;
+};
+
+export type OptionalArraySelectorWrapper<S, R, D> = {
+  length: RequiredPathSelectorType<S, number, D>;
+
+  [K: number]: OptionalPathSelectorType<S, R, D>;
+};
+
+export type RequiredArrayParametricSelectorWrapper<S, P, R, D> = {
+  length: RequiredPathParametricSelectorType<S, P, number, D>;
+
+  [K: number]: IsOptional<R> extends true
+    ? OptionalPathParametricSelectorType<S, P, R, D>
+    : RequiredPathParametricSelectorType<S, P, R, D>;
+};
+
+export type OptionalArrayParametricSelectorWrapper<S, P, R, D> = {
+  length: RequiredPathParametricSelectorType<S, P, number, D>;
+
+  [K: number]: OptionalPathParametricSelectorType<S, P, R, D>;
+};
+
+export type RequiredDataSelectorWrapper<S, R, D> = R extends unknown[]
+  ? RequiredArraySelectorWrapper<S, R[number], D>
+  : IsObject<R> extends true
+    ? RequiredObjectSelectorWrapper<S, R, D>
+    : RequiredSelectorBuilder<S, R, D>;
+
+export type OptionalDataSelectorWrapper<S, R, D> = R extends unknown[]
+  ? OptionalArraySelectorWrapper<S, R[number], D>
+  : IsObject<R> extends true
+    ? OptionalObjectSelectorWrapper<S, R, D>
+    : OptionalSelectorBuilder<S, R, D>;
+
+export type RequiredDataParametricSelectorWrapper<S, P, R, D> = R extends unknown[]
+  ? RequiredArrayParametricSelectorWrapper<S, P, R[number], D>
+  : IsObject<R> extends true
+    ? RequiredObjectParametricSelectorWrapper<S, P, R, D>
+    : RequiredParametricSelectorBuilder<S, P, R, D>;
+
+export type OptionalDataParametricSelectorWrapper<S, P, R, D> = R extends unknown[]
+  ? OptionalArrayParametricSelectorWrapper<S, P, R[number], D>
+  : IsObject<R> extends true
+    ? OptionalObjectParametricSelectorWrapper<S, P, R, D>
+    : OptionalParametricSelectorBuilder<S, P, R, D>;
+
+export type RequiredPathSelectorType<S, R, D> = RequiredSelectorBuilder<S, R, D> &
+  RequiredDataSelectorWrapper<S, NonNullable<R>, D>;
+
+export type OptionalPathSelectorType<S, R, D> = OptionalSelectorBuilder<S, R, D> &
+  OptionalDataSelectorWrapper<S, NonNullable<R>, D>;
+
+export type RequiredPathParametricSelectorType<S, P, R, D> = RequiredParametricSelectorBuilder<
+  S,
+  P,
+  R,
+  D
+> &
+  RequiredDataParametricSelectorWrapper<S, P, NonNullable<R>, D>;
+
+export type OptionalPathParametricSelectorType<S, P, R, D> = OptionalParametricSelectorBuilder<
+  S,
+  P,
+  R,
+  D
+> &
+  OptionalDataParametricSelectorWrapper<S, P, NonNullable<R>, D>;
+
+const defaultVoidFunction = () => {
+  return;
+};
+
+/** @internal */
+export const innerCreatePathSelector = (
+  baseSelector: (...args: unknown[]) => unknown,
+  path: Path = [],
+  applyMeta: (selector: unknown) => void = defaultVoidFunction,
+): unknown => {
+  const pathLength = path.length;
+
+  const proxyTarget = (defaultValue?: unknown) => {
+    function resultSelector(state?: unknown, props?: unknown) {
+      // Selectors are almost always reached as `(state)` or `(state, props)`, and
+      // dispatching those two arities directly keeps `arguments` out of the hot
+      // path. The arity is matched exactly rather than always passing two: reselect
+      // memoizes on the argument list, so handing a one-argument selector a second
+      // `undefined` would change its cache key.
+      let result: unknown;
+
+      if (arguments.length === 2) {
+        result = baseSelector(state, props);
+      } else if (arguments.length === 1) {
+        result = baseSelector(state);
+      } else {
+        result = baseSelector.apply(null, arguments as unknown as unknown[]);
+      }
+
+      for (let i = 0; i < pathLength && isObject(result); i += 1) {
+        result = result[path[i]];
+      }
+
+      // For optional properties, we want to exclude undefined from the return type
+      // but still return undefined if the property doesn't exist
+      return result === undefined ? defaultValue : result;
+    }
+
+    Object.assign(resultSelector, baseSelector, { path });
+    resultSelector.dependencies = [baseSelector];
+
+    applyMeta(resultSelector);
+
+    withDebugName(resultSelector, () => {
+      const baseName = getSelectorName(baseSelector);
+
+      return [baseName, ...path].join('.');
+    });
+
+    return resultSelector;
+  };
+
+  return new Proxy(proxyTarget, {
+    get: (_target, key) => {
+      return innerCreatePathSelector(baseSelector, [...path, String(key)], applyMeta);
+    },
+  });
+};
+
+export function createPathSelector<S, R, P = void>(
+  baseSelector: P extends void ? Selector<S, R> : Selector<S, R, [P]>,
+): P extends void
+  ? IsOptional<R> extends true
+    ? OptionalPathSelectorType<S, R, [Selector<S, R>]>
+    : RequiredPathSelectorType<S, R, [Selector<S, R>]>
+  : IsOptional<R> extends true
+    ? OptionalPathParametricSelectorType<S, P, R, [Selector<S, R, [P]>]>
+    : RequiredPathParametricSelectorType<S, P, R, [Selector<S, R, [P]>]> {
+  return innerCreatePathSelector(baseSelector as (...args: unknown[]) => unknown) as any;
+}

package/src/createPropSelector.ts

@@ -0,0 +1,28 @@
+import { Selector } from '@veksa/reselect';
+import { innerCreatePathSelector, RequiredPathParametricSelectorType } from './createPathSelector';
+import { Path } from './types';
+
+const propSelectorSymbol = Symbol.for('PropSelector');
+
+export const isPropSelector = (selector: unknown): selector is { path: Path } => {
+  return selector instanceof Object && propSelectorSymbol in selector;
+};
+
+export function createPropSelector<P>(): RequiredPathParametricSelectorType<
+  unknown,
+  P,
+  P,
+  [Selector<unknown, P, [P]>]
+> {
+  const propsSelector = (_state: unknown, props: unknown) => props;
+
+  const applyMeta = (selector: unknown) => {
+    Object.defineProperty(selector, propSelectorSymbol, { value: true });
+  };
+
+  return innerCreatePathSelector(
+    propsSelector,
+    [],
+    applyMeta,
+  ) as RequiredPathParametricSelectorType<unknown, P, P, [Selector<unknown, P, [P]>]>;
+}

package/src/createSegmentSelector.ts

@@ -0,0 +1,6 @@
+export function createSegmentSelector<State, SelectedSegment extends State | State[keyof State]>(
+  fn: (state: State) => SelectedSegment,
+  initial: SelectedSegment,
+): (state: State) => SelectedSegment {
+  return (state: State) => fn(state) ?? initial;
+}

package/src/createSequenceSelector.ts

@@ -0,0 +1,15 @@
+import { createSelector, Selector } from '@veksa/reselect';
+
+export function createSequenceSelector<S, R>(
+  selectors: Selector<S, R>[],
+  selectorCreator?: typeof createSelector,
+): Selector<S, R[]>;
+
+export function createSequenceSelector<S, P, R>(
+  selectors: Selector<S, R, [P]>[],
+  selectorCreator?: typeof createSelector,
+): Selector<S, R[], [P]>;
+
+export function createSequenceSelector(selectors: any, selectorCreator = createSelector) {
+  return selectorCreator(selectors, (...results: unknown[]) => results);
+}

package/src/createStructuredSelector.ts

@@ -0,0 +1,3 @@
+import { createStructuredSelector as reselectStructuredSelector } from '@veksa/reselect';
+
+export const createStructuredSelector = reselectStructuredSelector;

package/src/debug/__tests__/debug.test.ts

@@ -0,0 +1,20 @@
+import { afterEach, describe, expect, test } from 'vitest';
+import { isDebugMode, setDebugMode } from '../debug';
+
+describe('debug mode', () => {
+  afterEach(() => {
+    setDebugMode(false);
+  });
+
+  test('is disabled by default', () => {
+    expect(isDebugMode()).toBe(false);
+  });
+
+  test('reflects the value set via setDebugMode', () => {
+    setDebugMode(true);
+    expect(isDebugMode()).toBe(true);
+
+    setDebugMode(false);
+    expect(isDebugMode()).toBe(false);
+  });
+});

package/src/debug/debug.ts

@@ -0,0 +1,7 @@
+let debugMode = false;
+
+export const isDebugMode = () => debugMode;
+
+export const setDebugMode = (value: boolean) => {
+  debugMode = value;
+};

package/src/debug/withDebugName.ts

@@ -0,0 +1,28 @@
+import { defineDynamicSelectorName } from '../_helpers/defineDynamicSelectorName';
+import { isDebugMode } from './debug';
+
+/**
+ * Runs `callback` only outside production and only while debug mode is enabled.
+ * Centralizes the `NODE_ENV` / `isDebugMode` guard that the selector factories
+ * would otherwise repeat around every debug-name assignment.
+ */
+export const runInDebug = (callback: () => void) => {
+  /* istanbul ignore else  */
+  if (process.env.NODE_ENV !== 'production') {
+    /* istanbul ignore else  */
+    if (isDebugMode()) {
+      callback();
+    }
+  }
+};
+
+/**
+ * Assigns a lazily-computed debug name to `selector`, guarded by
+ * {@link runInDebug}. Covers the common single-name case; use `runInDebug`
+ * directly when a block needs to name several selectors at once.
+ */
+export const withDebugName = (selector: unknown, selectorNameGetter: () => string) => {
+  runInDebug(() => {
+    defineDynamicSelectorName(selector, selectorNameGetter);
+  });
+};

package/src/index.ts

@@ -0,0 +1,26 @@
+/* istanbul ignore file */
+/* Helpers */
+export { createSegmentSelector } from './createSegmentSelector';
+export { createPathSelector } from './createPathSelector';
+export { createPropSelector } from './createPropSelector';
+export { createBoundSelector } from './createBoundSelector';
+export { createEmptySelector } from './createEmptySelector';
+export { createAdaptedSelector } from './createAdaptedSelector';
+export { createChainSelector, type ChainSelectorOptions } from './createChainSelector';
+export { createCachedSequenceSelector } from './createCachedSequenceSelector';
+export { createCachedStructuredSelector } from './createCachedStructuredSelector';
+
+/* Key Selector Composition */
+export { defaultKeySelector } from './keys/defaultKeySelector';
+export { createKeySelectorComposer } from './keys/createKeySelectorComposer';
+export { stringComposeKeySelectors } from './keys/stringComposeKeySelectors';
+export { arrayComposeKeySelectors } from './keys/arrayComposeKeySelectors';
+export { createKeySelectorCreator } from './keys/createKeySelectorCreator';
+
+export { setDebugMode, isDebugMode } from './debug/debug';
+
+/* Cache */
+export { initGarbageCollector, IntervalMapCache } from './cache/intervalMapCache';
+export { TreeCache } from './cache/TreeCache';
+
+export { useSelector } from './_hooks/useSelector';