@sladg/apex-state 3.7.3 → 3.9.1

package/dist/index.d.ts

@@ -497,9 +497,154 @@ type ConcernRegistrationMap<DATA extends object, CONCERNS extends readonly any[]
 }>;
 
 /**
- * PathsOfSameValue - Type-safe path tuples for side effects
+ * Lazy listener validators — O(N) base + O(K) per-listener validation
  *
- * Simple tuple-based API for syncPaths, flipPaths, and aggregations.
+ * These types power the `listeners()` helper function that scales to large state
+ * types without hitting TS2589.
+ *
+ * Unlike the direct `ListenerRegistration<DATA>[]` type which resolves
+ * `DeepKey<DATA>` for path/scope on every element, these validators only evaluate
+ * `DeepValue` for the K listeners you actually write.
+ *
+ * Valid listener combinations:
+ * 1. `{ path: string, fn }` — scope defaults to path → scoped state
+ * 2. `{ path: string, scope: null, fn }` — explicit null scope → full DATA
+ * 3. `{ path: string, scope: string, fn }` — scope must be prefix of path
+ * 4. `{ path: null, fn }` — watch everything, scope defaults to null → full DATA
+ * 5. `{ path: null, scope: null, fn }` — same as above, explicit
+ *
+ * **Inline fn restriction**: Fns with untyped (any) parameters are rejected.
+ * Use `OnStateListener<DATA, ScopedState>` to explicitly type your fn.
+ */
+
+/**
+ * True if Prefix is a dot-separated ancestor of Path (or equals Path).
+ *
+ * @example
+ * IsPrefixOf<'user', 'user'>          → true   (equal)
+ * IsPrefixOf<'user', 'user.name'>     → true   (parent)
+ * IsPrefixOf<'user', 'username'>      → false  (different segment)
+ * IsPrefixOf<'cart', 'user.name'>     → false  (unrelated)
+ */
+type IsPrefixOf<Prefix extends string, Path extends string> = Path extends Prefix ? true : Path extends `${Prefix}.${string}` ? true : false;
+/**
+ * Derive the sub-state type from scope.
+ * - null scope → full DATA
+ * - string scope → DeepValue<DATA, Scope>
+ *
+ * Uses `Scope & string` to satisfy DeepValue's string constraint
+ * when Scope is inferred from a mapped type.
+ */
+type ScopedState<DATA extends object, Scope> = Scope extends null ? DATA : Scope extends string ? DeepValue<DATA, Scope & string> : DATA;
+/**
+ * Extract the effective scope from a listener element.
+ *
+ * When 'scope' key exists with a non-undefined value, returns that value.
+ * When 'scope' key is missing or undefined, returns the path as default.
+ */
+type EffectiveScope<T, P> = 'scope' extends keyof T ? Exclude<T[keyof T & 'scope'], undefined> extends never ? P : Exclude<T[keyof T & 'scope'], undefined> : P;
+/**
+ * Detect if a function's first parameter is `any`.
+ * Uses the `0 extends 1 & T` trick: only true when T is `any`.
+ *
+ * When true, the fn has untyped parameters (e.g., `(_changes, _state) => ...`
+ * without explicit typing). We reject these to force users to use
+ * `OnStateListener<DATA, ScopedState>` for type safety.
+ */
+type HasAnyFirstParam<F> = F extends (...args: infer A) => any ? A extends [infer P1, ...any[]] ? 0 extends 1 & P1 ? true : false : false : false;
+/**
+ * Error marker type for untyped listener fns.
+ * Produces a clear error message when the user passes an untyped inline fn.
+ */
+type TypedFnRequired<DATA extends object, SUB_STATE, META extends GenericMeta> = OnStateListener<DATA, SUB_STATE, META> & {
+    __error: 'Listener fn must be explicitly typed. Use OnStateListener<DATA, ScopedState> or type the parameters directly.';
+};
+/**
+ * Returns the fn type for a listener element, rejecting untyped fns.
+ *
+ * When the user's fn has `any` params (implicit from inference), returns
+ * a branded error type that produces a clear type error.
+ * When the fn is explicitly typed (standalone or annotated), returns the
+ * expected OnStateListener type for assignability checking.
+ */
+type ValidatedFn<DATA extends object, META extends GenericMeta, SUB_STATE, F> = HasAnyFirstParam<F> extends true ? TypedFnRequired<DATA, SUB_STATE, META> : OnStateListener<DATA, SUB_STATE, META>;
+/**
+ * Validates a single listener element.
+ *
+ * When scope is omitted (undefined), it defaults to path:
+ * - path is string → fn gets DeepValue<DATA, path>
+ * - path is null → fn gets full DATA
+ *
+ * When scope is explicitly provided:
+ * - scope: null → fn gets full DATA
+ * - scope: string → must be prefix of path, fn gets DeepValue<DATA, scope>
+ *
+ * Rejects fns with untyped (any) parameters — forces explicit typing via
+ * OnStateListener<DATA, ScopedState>.
+ */
+type CheckListenerElement<DATA extends object, META extends GenericMeta, T> = T extends {
+    path: infer P;
+    fn: infer F;
+} ? EffectiveScope<T, P> extends infer ES ? [
+    P,
+    ES
+] extends [string, string] ? IsPrefixOf<ES & string, P & string> extends true ? 'scope' extends keyof T ? {
+    path: P;
+    scope: ES;
+    fn: ValidatedFn<DATA, META, ScopedState<DATA, ES>, F>;
+} : {
+    path: P;
+    scope?: undefined;
+    fn: ValidatedFn<DATA, META, ScopedState<DATA, ES>, F>;
+} : {
+    path: P;
+    scope: never;
+    fn: OnStateListener<DATA, never, META>;
+} : [
+    P,
+    ES
+] extends [string, null] ? {
+    path: P;
+    scope: null;
+    fn: ValidatedFn<DATA, META, DATA, F>;
+} : [
+    P,
+    ES
+] extends [null, null] ? 'scope' extends keyof T ? {
+    path: null;
+    scope: null;
+    fn: ValidatedFn<DATA, META, DATA, F>;
+} : {
+    path: null;
+    scope?: undefined;
+    fn: ValidatedFn<DATA, META, DATA, F>;
+} : T : T : T;
+/**
+ * Validates an array of listener objects lazily — O(K) where K = listeners written.
+ *
+ * Per element:
+ * 1. path must be ResolvableDeepKey<DATA> | null (enforced by function constraint)
+ * 2. scope is optional — defaults to path when omitted
+ * 3. When both non-null: scope must be prefix of path
+ * 4. fn must be explicitly typed (rejects untyped `any` params)
+ * 5. fn receives correctly-typed scoped state
+ */
+type CheckListeners<DATA extends object, META extends GenericMeta, T extends readonly {
+    path: string | null;
+    scope?: string | null | undefined;
+    fn: (...args: any[]) => any;
+}[], _Depth extends number = DefaultDepth> = {
+    [I in keyof T]: CheckListenerElement<DATA, META, T[I]>;
+};
+
+/**
+ * Direct pair types — O(N²) path unions for side effects
+ *
+ * These types enumerate all valid path combinations eagerly.
+ * Simple to use as type annotations but hit TS2589 at ~1,500 paths.
+ *
+ * For large state types, use the curried helper functions (syncPairs, flipPairs, etc.)
+ * which use lazy validators from `pair-validators.ts` instead.
  *
  * @example
  * ```typescript
@@ -527,6 +672,11 @@ type PathsWithSameValueAs<DATA extends object, PATH extends ResolvableDeepKey<DA
  * A tuple of two paths that must have the same value type.
  * Format: [path1, path2]
  *
+ * **Scaling note**: This type is O(N²) where N = number of paths. It hits TS2589
+ * at ~1,500 paths. For large state types, use the `syncPairs()` helper function
+ * or `store.syncPairs()` (pre-warmed from `createGenericStore`) instead —
+ * they scale to ~50K–80K paths.
+ *
  * @example
  * const pair: SyncPair<State> = ['user.email', 'profile.email']
  *
@@ -543,9 +693,12 @@ type SyncPair<DATA extends object, Depth extends number = DefaultDepth> = {
     ];
 }[ResolvableDeepKey<DATA, Depth>];
 /**
- * A tuple of two paths for flip (alias for SyncPair)
+ * A tuple of two paths for flip (alias for SyncPair).
  * Format: [path1, path2]
  *
+ * **Scaling note**: O(N²) — hits TS2589 at ~1,500 paths. Use `flipPairs()` helper
+ * or `store.flipPairs()` for large state types.
+ *
  * @example
  * const pair: FlipPair<State> = ['isActive', 'isInactive']
  */
@@ -558,6 +711,9 @@ type FlipPair<DATA extends object, Depth extends number = DefaultDepth> = SyncPa
  *
  * Multiple pairs can point to same target for multi-source aggregation.
  *
+ * **Scaling note**: O(N²) — hits TS2589 at ~1,500 paths. Use `aggregationPairs()` helper
+ * or `store.aggregationPairs()` for large state types.
+ *
  * @example
  * // target <- source (target is always first/left)
  * const aggs: AggregationPair<State>[] = [
@@ -581,6 +737,9 @@ type ComputationOp = 'SUM' | 'AVG';
  *
  * Multiple pairs can point to same target for multi-source computation.
  *
+ * **Scaling note**: O(N²) — hits TS2589 at ~1,500 paths. Use `computationPairs()` helper
+ * or `store.computationPairs()` for large state types.
+ *
  * @example
  * const comps: ComputationPair<State>[] = [
  *   ['SUM', 'total', 'price1'],
@@ -598,6 +757,70 @@ type ComputationPair<DATA extends object, Depth extends number = DefaultDepth> =
     ];
 }[DeepKeyFiltered<DATA, number, Depth>];
 
+/**
+ * Lazy pair validators — O(N) base + O(K) per-pair DeepValue check
+ *
+ * These types power the helper functions (syncPairs, flipPairs, etc.)
+ * that scale to large state types without hitting TS2589.
+ *
+ * Unlike the direct pair types (SyncPair, FlipPair, etc.) which are O(N²),
+ * these validators only evaluate DeepValue for the K pairs you actually write.
+ */
+
+/**
+ * Validates that two paths resolve to the same value type.
+ * Only evaluates DeepValue when P1, P2 are concrete literals — O(1) per pair.
+ * Wraps in [T] extends [U] to prevent distributive conditional.
+ *
+ * Returns [P1, P2] on match, [P1, never] on mismatch.
+ */
+type CheckPairValueMatch<DATA extends object, P1 extends string, P2 extends string, Depth extends number = DefaultDepth> = [P1] extends [ResolvableDeepKey<DATA, Depth>] ? [P2] extends [ResolvableDeepKey<DATA, Depth>] ? [NonNullable<DeepValue<DATA, P1>>] extends [
+    NonNullable<DeepValue<DATA, P2>>
+] ? [NonNullable<DeepValue<DATA, P2>>] extends [
+    NonNullable<DeepValue<DATA, P1>>
+] ? [P1, P2] : [P1, never] : [P1, never] : never : never;
+/**
+ * Validates an array of [P1, P2] sync/flip pairs lazily — O(K) where K = pairs written.
+ */
+type CheckSyncPairs<DATA extends object, T extends readonly [string, string][], Depth extends number = DefaultDepth> = {
+    [I in keyof T]: T[I] extends [
+        infer P1 extends string,
+        infer P2 extends string
+    ] ? CheckPairValueMatch<DATA, P1, P2, Depth> : T[I];
+};
+/**
+ * Validates that two paths both resolve to number.
+ * Returns [ComputationOp, P1, P2] or [ComputationOp, P1, P2, BoolLogic] on match.
+ */
+type CheckComputationPairValueMatch<DATA extends object, P1 extends string, P2 extends string, Depth extends number = DefaultDepth> = [P1] extends [DeepKeyFiltered<DATA, number, Depth>] ? [P2] extends [DeepKeyFiltered<DATA, number, Depth>] ? true : false : false;
+/**
+ * Validates an array of aggregation pairs: [target, source] or [target, source, BoolLogic].
+ * Each pair checks that target and source resolve to the same value type.
+ */
+type CheckAggregationPairs<DATA extends object, T extends readonly (readonly [string, string] | readonly [string, string, BoolLogic<DATA, Depth>])[], Depth extends number = DefaultDepth> = {
+    [I in keyof T]: T[I] extends readonly [
+        infer P1 extends string,
+        infer P2 extends string,
+        infer BL
+    ] ? CheckPairValueMatch<DATA, P1, P2, Depth> extends [P1, P2] ? [P1, P2, BL] : [P1, never, BL] : T[I] extends readonly [infer P1 extends string, infer P2 extends string] ? CheckPairValueMatch<DATA, P1, P2, Depth> : T[I];
+};
+/**
+ * Validates an array of computation pairs: [op, target, source] or [op, target, source, BoolLogic].
+ * Both target and source must be number paths.
+ */
+type CheckComputationPairs<DATA extends object, T extends readonly (readonly [ComputationOp, string, string] | readonly [ComputationOp, string, string, BoolLogic<DATA, Depth>])[], Depth extends number = DefaultDepth> = {
+    [I in keyof T]: T[I] extends readonly [
+        infer Op extends ComputationOp,
+        infer P1 extends string,
+        infer P2 extends string,
+        infer BL
+    ] ? CheckComputationPairValueMatch<DATA, P1, P2, Depth> extends true ? [Op, P1, P2, BL] : [Op, P1, never, BL] : T[I] extends readonly [
+        infer Op extends ComputationOp,
+        infer P1 extends string,
+        infer P2 extends string
+    ] ? CheckComputationPairValueMatch<DATA, P1, P2, Depth> extends true ? [Op, P1, P2] : [Op, P1, never] : T[I];
+};
+
 /** Recursively makes all properties required, stripping undefined */
 type DeepRequired<T> = {
     [K in keyof T]-?: NonNullable<T[K]> extends object ? DeepRequired<NonNullable<T[K]>> : NonNullable<T[K]>;
@@ -613,6 +836,56 @@ type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends reado
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;
 
+/**
+ * Validated pair branded types
+ *
+ * Phantom types for pre-validated pair arrays returned by helper functions
+ * (syncPairs, flipPairs, aggregationPairs, computationPairs).
+ *
+ * Brands serve two purposes:
+ * 1. SideEffects accepts them without re-resolving the O(N²) direct pair types
+ * 2. DATA generic prevents cross-store use (pairs from StoreA can't go to StoreB)
+ *
+ * Zero runtime cost — brands are erased at compile time.
+ */
+
+declare const VALIDATED: unique symbol;
+declare const STORE_DATA: unique symbol;
+/** Pre-validated sync pair array. Returned by `syncPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedSyncPairs<DATA extends object = object> = [
+    string,
+    string
+][] & {
+    [VALIDATED]: 'sync';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated flip pair array. Returned by `flipPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedFlipPairs<DATA extends object = object> = [
+    string,
+    string
+][] & {
+    [VALIDATED]: 'flip';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated aggregation pair array. Returned by `aggregationPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedAggregationPairs<DATA extends object = object> = ([string, string] | [string, string, unknown])[] & {
+    [VALIDATED]: 'aggregation';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated computation pair array. Returned by `computationPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedComputationPairs<DATA extends object = object> = ([ComputationOp, string, string] | [ComputationOp, string, string, unknown])[] & {
+    [VALIDATED]: 'computation';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated listener array. Returned by `listeners()`. Branded with DATA to prevent cross-store use.
+ * Uses intersection with ListenerRegistration[] so it's assignable to the listeners field
+ * without needing a union — preserving contextual typing for inline fn parameters.
+ */
+type ValidatedListeners<DATA extends object = object, META extends GenericMeta = GenericMeta> = ListenerRegistration<DATA, META>[] & {
+    [VALIDATED]: 'listeners';
+    [STORE_DATA]: DATA;
+};
+
 interface BaseConcernProps<STATE, PATH extends string> {
     state: STATE;
     path: PATH;
@@ -934,8 +1207,14 @@ interface Aggregation {
     targetPath: string;
     sourcePaths: string[];
 }
-/** Reacts to scoped changes - receives relative paths and scoped state. Only fires for NESTED paths, not the path itself. */
-type OnStateListener<DATA extends object = object, SUB_STATE = DATA, META extends GenericMeta = GenericMeta> = (changes: ArrayOfChanges<SUB_STATE, META>, state: SUB_STATE) => ArrayOfChanges<DATA, META> | undefined;
+/** Reacts to scoped changes - receives relative paths and scoped state. Only fires for NESTED paths, not the path itself.
+ * Both input changes and return changes use paths relative to scope (or full paths when scope is null).
+ *
+ * When SUB_STATE is `any` (as in ListenerRegistration's default), the return type falls back to
+ * ArrayOfChanges<DATA> to avoid DeepKey<any> resolving to never.
+ */
+type IsAnyState<T> = 0 extends 1 & T ? true : false;
+type OnStateListener<DATA extends object = object, SUB_STATE = DATA, META extends GenericMeta = GenericMeta> = (changes: ArrayOfChanges<SUB_STATE, META>, state: SUB_STATE) => IsAnyState<SUB_STATE> extends true ? ArrayOfChanges<DATA, META> | undefined : ArrayOfChanges<SUB_STATE, META> | undefined;
 /**
  * Listener registration with path (what to watch) and scope (how to present data)
  *
@@ -980,12 +1259,13 @@ interface ListenerRegistration<DATA extends object = object, META extends Generi
     path: DeepKey<DATA, Depth> | null;
     /**
      * Scope for state and changes presentation
+     * - If omitted/undefined: defaults to `path` (scoped state matching the watched path)
      * - If null: state is full DATA, changes use FULL paths
      * - If set: state is value at scope, changes use paths RELATIVE to scope
      *
      * Note: Changes are filtered based on `path`, even when scope is null
      */
-    scope: DeepKey<DATA, Depth> | null;
+    scope?: DeepKey<DATA, Depth> | null;
     fn: OnStateListener<DATA, any, META>;
 }
 interface ListenerHandlerRef {
@@ -1289,7 +1569,7 @@ type ClearPathRule<DATA extends object, Depth extends number = DefaultDepth> = [
  *       fn: (changes, state) => {
  *         // changes: [['name', 'Alice', {}]]  // RELATIVE to scope
  *         // state: user.profile sub-object
- *         return [['status', 'updated', {}]]  // Return FULL paths
+ *         return [['status', 'updated', {}]]  // Return SCOPED paths (relative to scope)
  *       }
  *     },
  *     {
@@ -1307,7 +1587,7 @@ type ClearPathRule<DATA extends object, Depth extends number = DefaultDepth> = [
  *       fn: (changes, state) => {
  *         // changes: [['data.strike', value, {}]]  // RELATIVE to scope
  *         // state: p.123.g.abc object
- *         return [['some.value.elsewhere', computed, {}]]  // FULL path
+ *         return [['data.computed', computed, {}]]  // SCOPED path (relative to scope)
  *       }
  *     }
  *   ]
@@ -1318,19 +1598,22 @@ interface SideEffects<DATA extends object, META extends GenericMeta = GenericMet
     /**
      * Sync paths - keeps specified paths synchronized
      * Format: [path1, path2] - both paths stay in sync
+     * Accepts direct `SyncPair<T>[]` or pre-validated result from `syncPairs()`.
      */
-    syncPaths?: SyncPair<DATA, Depth>[];
+    syncPaths?: SyncPair<DATA, Depth>[] | ValidatedSyncPairs<DATA>;
     /**
      * Flip paths - keeps specified paths with opposite values
      * Format: [path1, path2] - paths have inverse boolean values
+     * Accepts direct `FlipPair<T>[]` or pre-validated result from `flipPairs()`.
      */
-    flipPaths?: FlipPair<DATA, Depth>[];
+    flipPaths?: FlipPair<DATA, Depth>[] | ValidatedFlipPairs<DATA>;
     /**
      * Aggregations - aggregates sources into target
      * Format: [target, source] - target is ALWAYS first (left)
      * Multiple pairs can point to same target for multi-source aggregation
+     * Accepts direct `AggregationPair<T>[]` or pre-validated result from `aggregationPairs()`.
      */
-    aggregations?: AggregationPair<DATA, Depth>[];
+    aggregations?: AggregationPair<DATA, Depth>[] | ValidatedAggregationPairs<DATA>;
     /**
      * Clear paths - "when X changes, set Y to null"
      * Format: [triggers[], targets[], { expandMatch?: boolean }?]
@@ -1343,15 +1626,26 @@ interface SideEffects<DATA extends object, META extends GenericMeta = GenericMet
      * Format: [operation, target, source] - target is computed from sources
      * Multiple pairs can point to same target for multi-source computation
      * Unidirectional: source → target only (writes to target are no-op)
+     * Accepts direct `ComputationPair<T>[]` or pre-validated result from `computationPairs()`.
      */
-    computations?: ComputationPair<DATA, Depth>[];
+    computations?: ComputationPair<DATA, Depth>[] | ValidatedComputationPairs<DATA>;
     /**
      * Listeners - react to state changes with scoped state
+     * Accepts direct `ListenerRegistration<T>[]` or pre-validated result from `listeners()`.
      */
     listeners?: ListenerRegistration<DATA, META>[];
 }
 
 declare const createGenericStore: <DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly ConcernType<string, any, any>[] = typeof defaultConcerns>(config?: StoreConfig) => {
+    syncPairs: <T extends [Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>][]>(pairs: CheckSyncPairs<DATA, T, 20>) => ValidatedSyncPairs<DATA>;
+    flipPairs: <T extends [Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>][]>(pairs: CheckSyncPairs<DATA, T, 20>) => ValidatedFlipPairs<DATA>;
+    aggregationPairs: <T extends ([Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>] | [Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>, BoolLogic<DATA, 20>])[]>(pairs: CheckAggregationPairs<DATA, T, 20>) => ValidatedAggregationPairs<DATA>;
+    computationPairs: <T extends ([ComputationOp, DeepKeyFiltered<DATA, number, 20>, DeepKeyFiltered<DATA, number, 20>] | [ComputationOp, DeepKeyFiltered<DATA, number, 20>, DeepKeyFiltered<DATA, number, 20>, BoolLogic<DATA, 20>])[]>(pairs: CheckComputationPairs<DATA, T, 20>) => ValidatedComputationPairs<DATA>;
+    listeners: <T extends readonly {
+        path: Exclude<DeepKey<DATA, 20>, `${string}??`> | null;
+        scope?: Exclude<DeepKey<DATA, 20>, `${string}??`> | null | undefined;
+        fn: (...args: any[]) => any;
+    }[]>(items: CheckListeners<DATA, META, T, 20>) => ValidatedListeners<DATA, META>;
     Provider: {
         (props: ProviderProps<DATA>): react_jsx_runtime.JSX.Element;
         displayName: string;
@@ -1609,6 +1903,145 @@ declare const registerSyncPairsBatch: <DATA extends object, META extends Generic
 
 declare const registerSideEffects: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, id: string, effects: SideEffects<DATA, META>) => (() => void);
 
+/**
+ * Lazy-validated pair helper functions
+ *
+ * These curried helpers provide O(N) base type + O(K) per-pair validation,
+ * avoiding the O(N²) explosion of SyncPair/FlipPair/AggregationPair/ComputationPair
+ * on large state types (1500+ paths).
+ *
+ * Runtime behavior: identity function (returns input as-is).
+ * Type behavior: validates each pair via CheckSyncPairs / CheckAggregationPairs / CheckComputationPairs.
+ *
+ * **Why these exist**: The direct pair types (`SyncPair<T>`, `FlipPair<T>`, etc.) distribute
+ * over all N paths to build an O(N²) union of valid pairs. This hits TS2589 at ~1,500 paths.
+ * These helpers defer validation: the function constraint uses `ResolvableDeepKey<T>` (O(N))
+ * for autocomplete, then `CheckPairValueMatch` validates only the K pairs you actually write
+ * via `DeepValue` comparison (O(1) per pair).
+ *
+ * **Inference safety**: Parameter types use mapped types only (`{ [I in keyof T]: Check<T[I]> }`)
+ * — never `[...T] & MappedType<T>`. This avoids the TS inference competition where `[...T]`
+ * and a mapped type both try to infer T, causing tuple widening on small state types.
+ *
+ * **Branded returns**: Each helper returns a `Validated*` branded type so that
+ * `useSideEffects({ syncPaths: result })` skips the O(N²) re-validation.
+ *
+ * **Scaling limits** (measured on Apple M4 Pro):
+ * - ~82,500 paths (500 flat sectors, depth 4): PASS in 7.1s / 617 MB
+ * - ~52,800 paths (binary 6 levels, depth 9): PASS in 4.7s / 574 MB
+ * - ~105,600 paths (binary 7 levels, depth 10): TS2589
+ * - Practical limit: ~50K–80K paths, bounded by `ResolvableDeepKey` union resolution
+ *   at the function constraint, not by the validation logic.
+ * - Old `SyncPair<T>` hit TS2589 at ~1,500 paths — a ~30–50x improvement.
+ *
+ * @example
+ * ```typescript
+ * const syncs = syncPairs<State>()([
+ *   ['user.email', 'profile.email'],  // ✓ both string
+ *   ['user.age', 'profile.name'],     // ✗ number vs string → type error
+ * ])
+ * ```
+ */
+
+/**
+ * Lazy-validated sync pairs. Curried: `syncPairs<State>()(pairs)`.
+ *
+ * Provides autocomplete for valid paths (O(N)) and validates that both paths
+ * in each pair resolve to the same value type (O(K) per pair).
+ * Returns branded `ValidatedSyncPairs` — accepted by `useSideEffects` without re-validation.
+ *
+ * @example
+ * ```typescript
+ * const syncs = syncPairs<MyState>()([
+ *   ['user.email', 'profile.email'],
+ *   ['user.name', 'profile.name'],
+ * ])
+ * useSideEffects('my-syncs', { syncPaths: syncs })  // no O(N²) re-check
+ * ```
+ */
+declare const syncPairs: <DATA extends object, Depth extends number = DefaultDepth>() => <T extends [ResolvableDeepKey<DATA, Depth>, ResolvableDeepKey<DATA, Depth>][]>(pairs: CheckSyncPairs<DATA, T, Depth>) => ValidatedSyncPairs<DATA>;
+/**
+ * Lazy-validated flip pairs. Curried: `flipPairs<State>()(pairs)`.
+ *
+ * Identical to syncPairs — validates both paths resolve to the same value type.
+ * Returns branded `ValidatedFlipPairs` — accepted by `useSideEffects` without re-validation.
+ *
+ * @example
+ * ```typescript
+ * const flips = flipPairs<MyState>()([
+ *   ['isActive', 'isInactive'],
+ * ])
+ * useSideEffects('my-flips', { flipPaths: flips })  // no O(N²) re-check
+ * ```
+ */
+declare const flipPairs: <DATA extends object, Depth extends number = DefaultDepth>() => <T extends [ResolvableDeepKey<DATA, Depth>, ResolvableDeepKey<DATA, Depth>][]>(pairs: CheckSyncPairs<DATA, T, Depth>) => ValidatedFlipPairs<DATA>;
+/**
+ * Lazy-validated aggregation pairs. Curried: `aggregationPairs<State>()(pairs)`.
+ *
+ * Each pair is [target, source] or [target, source, BoolLogic].
+ * Validates that target and source resolve to the same value type.
+ * Returns branded `ValidatedAggregationPairs` — accepted by `useSideEffects` without re-validation.
+ *
+ * @example
+ * ```typescript
+ * const aggs = aggregationPairs<MyState>()([
+ *   ['total', 'price1'],
+ *   ['total', 'price2', { IS_EQUAL: ['price2.disabled', true] }],
+ * ])
+ * useSideEffects('my-aggs', { aggregations: aggs })  // no O(N²) re-check
+ * ```
+ */
+declare const aggregationPairs: <DATA extends object, Depth extends number = DefaultDepth>() => <T extends ([ResolvableDeepKey<DATA, Depth>, ResolvableDeepKey<DATA, Depth>] | [ResolvableDeepKey<DATA, Depth>, ResolvableDeepKey<DATA, Depth>, BoolLogic<DATA, Depth>])[]>(pairs: CheckAggregationPairs<DATA, T, Depth>) => ValidatedAggregationPairs<DATA>;
+/**
+ * Lazy-validated computation pairs. Curried: `computationPairs<State>()(pairs)`.
+ *
+ * Each pair is [op, target, source] or [op, target, source, BoolLogic].
+ * Validates that both target and source are number paths.
+ * Returns branded `ValidatedComputationPairs` — accepted by `useSideEffects` without re-validation.
+ *
+ * @example
+ * ```typescript
+ * const comps = computationPairs<MyState>()([
+ *   ['SUM', 'total', 'price1'],
+ *   ['AVG', 'average', 'score1'],
+ * ])
+ * useSideEffects('my-comps', { computations: comps })  // no O(N²) re-check
+ * ```
+ */
+declare const computationPairs: <DATA extends object, Depth extends number = DefaultDepth>() => <T extends ([ComputationOp, DeepKeyFiltered<DATA, number, Depth>, DeepKeyFiltered<DATA, number, Depth>] | [ComputationOp, DeepKeyFiltered<DATA, number, Depth>, DeepKeyFiltered<DATA, number, Depth>, BoolLogic<DATA, Depth>])[]>(pairs: CheckComputationPairs<DATA, T, Depth>) => ValidatedComputationPairs<DATA>;
+/**
+ * Lazy-validated listeners. Curried: `listeners<State>()(items)`.
+ *
+ * Provides autocomplete for valid paths (O(N)) and validates each listener:
+ * - path and scope are valid `ResolvableDeepKey<DATA>` or null
+ * - When both non-null: scope must be a dot-separated prefix of path
+ * - fn receives correctly-typed scoped state based on scope
+ *
+ * Returns branded `ValidatedListeners` — accepted by `useSideEffects` without re-validation.
+ *
+ * @example
+ * ```typescript
+ * const myListeners = listeners<MyState>()([
+ *   {
+ *     path: 'user.profile.name',
+ *     scope: 'user.profile',
+ *     fn: (changes, state) => {
+ *       // changes: ArrayOfChanges relative to user.profile scope
+ *       // state: typed as MyState['user']['profile']
+ *       // return: ArrayOfChanges relative to scope, or undefined
+ *       return [['name', `updated-${state.name}`, {}]]
+ *     }
+ *   },
+ * ])
+ * useSideEffects('my-listeners', { listeners: myListeners })
+ * ```
+ */
+declare const listeners: <DATA extends object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth>() => <T extends readonly {
+    path: ResolvableDeepKey<DATA, Depth> | null;
+    scope?: ResolvableDeepKey<DATA, Depth> | null | undefined;
+    fn: (...args: any[]) => any;
+}[]>(items: CheckListeners<DATA, META, T, Depth>) => ValidatedListeners<DATA, META>;
+
 declare const evaluateBoolLogic: <STATE extends object>(logic: BoolLogic<STATE>, state: STATE) => boolean;
 
 /**
@@ -1822,4 +2255,4 @@ declare const applyChangesToObject: <T extends object>(obj: T, changes: ArrayOfC
  */
 declare const deepClone: <T>(value: T) => T;
 
-export { type Aggregation, type AggregationPair, type ArrayOfChanges, type BaseConcernProps, type BoolLogic, type BufferedField, type ClearPathRule, type ComputationOp, type ComputationPair, type ConcernRegistration, type ConcernRegistrationMap, type ConcernType, type DebugConfig, type DebugTrack, type DebugTrackEntry, type DeepKey, type DeepKeyFiltered, type DeepPartial, type DeepRequired, type DeepValue, type EvaluatedConcerns, type ExtractEvaluateReturn, type FieldInput$2 as FieldInput, type FlipPair, type GenericMeta, type GenericStoreApi, type HASH_KEY, type KeyboardSelectConfig, type ListenerRegistration, type OnStateListener, type PathsWithSameValueAs, type ProviderProps, type SelectOption, type SideEffects, type StoreConfig, type StoreInstance, type SyncPair, type ThrottleConfig, type ThrottleFieldInput, type TransformConfig, type ValidationError, type ValidationSchema, type ValidationStateConcern, type ValidationStateInput, type ValidationStateResult, _, applyChangesToObject, createGenericStore, deepClone, defaultConcerns, dot, evaluateBoolLogic, extractPlaceholders, findConcern, hashKey, interpolateTemplate, is, index as prebuilts, registerFlipPair, registerListenerLegacy, registerSideEffects, registerSyncPairsBatch, useBufferedField, useKeyboardSelect, useThrottledField, useTransformedField };
+export { type Aggregation, type AggregationPair, type ArrayOfChanges, type BaseConcernProps, type BoolLogic, type BufferedField, type CheckAggregationPairs, type CheckComputationPairs, type CheckPairValueMatch, type CheckSyncPairs, type ClearPathRule, type ComputationOp, type ComputationPair, type ConcernRegistration, type ConcernRegistrationMap, type ConcernType, type DebugConfig, type DebugTrack, type DebugTrackEntry, type DeepKey, type DeepKeyFiltered, type DeepPartial, type DeepRequired, type DeepValue, type EvaluatedConcerns, type ExtractEvaluateReturn, type FieldInput$2 as FieldInput, type FlipPair, type GenericMeta, type GenericStoreApi, type HASH_KEY, type KeyboardSelectConfig, type ListenerRegistration, type OnStateListener, type PathsWithSameValueAs, type ProviderProps, type SelectOption, type SideEffects, type StoreConfig, type StoreInstance, type SyncPair, type ThrottleConfig, type ThrottleFieldInput, type TransformConfig, type ValidationError, type ValidationSchema, type ValidationStateConcern, type ValidationStateInput, type ValidationStateResult, _, aggregationPairs, applyChangesToObject, computationPairs, createGenericStore, deepClone, defaultConcerns, dot, evaluateBoolLogic, extractPlaceholders, findConcern, flipPairs, hashKey, interpolateTemplate, is, listeners, index as prebuilts, registerFlipPair, registerListenerLegacy, registerSideEffects, registerSyncPairsBatch, syncPairs, useBufferedField, useKeyboardSelect, useThrottledField, useTransformedField };