@sladg/apex-state 3.4.1 → 3.5.0

package/README.md

@@ -58,7 +58,7 @@ const UserForm = () => {
 
 | Feature | Description | Details |
 |---|---|---|
-| **Type-safe paths** | `DeepKey<T>` / `DeepValue<T, P>` — compile-time path safety | |
+| **Type-safe paths** | `DeepKey<T>` / `DeepValue<T, P>` — compile-time path safety with configurable depth | |
 | **Concerns** | Validation (Zod), BoolLogic conditions, dynamic text | [Concerns Guide](docs/guides/CONCERNS_GUIDE.md) |
 | **Side effects** | Sync paths, flip paths, aggregations, listeners | [Side Effects Guide](docs/SIDE_EFFECTS_GUIDE.md) |
 | **WASM mode** | Rust-powered pipeline for bulk operations (up to 367x faster) | [Architecture](docs/WASM_ARCHITECTURE.md) |
@@ -402,6 +402,61 @@ store.useConcerns('wildcards', {
 const nestedPath = `books.${_('b1')}.products.${_('p1')}.legs.${_('l1')}.notional`
 ```
 
+## Type-Safe Paths with Configurable Depth
+
+Deeply nested state types can cause TypeScript errors like **TS2589 ("Type instantiation is excessively deep")** or slow IDE autocomplete. `DeepKey<T, Depth>` solves this with a configurable recursion limit — reduce depth for wide types to speed up compilation, increase it for deeply nested structures, and get clear feedback when the limit is reached.
+
+```typescript
+type State = {
+  user: { name: string; address: { street: string; city: string } }
+  count: number
+}
+
+// DeepKey<State> = "user" | "count" | "user.name" | "user.address" | "user.address.street" | "user.address.city"
+type AllPaths = DeepKey<State>
+```
+
+### Default Depth
+
+`DefaultDepth` is set to **20** — enough for most real-world types. Uses loop unrolling (2 levels per recursion call) to stay well within TypeScript's recursion limits while supporting deeply nested structures.
+
+### Custom Depth
+
+Tune the depth limit per use-site to balance **compilation speed vs path coverage**:
+
+```typescript
+// Shallow — faster tsc for wide types with many top-level keys
+type ShallowPaths = DeepKey<State, 10>
+
+// Deeper — for types nested beyond 20 levels (e.g., recursive data models)
+type DeepPaths = DeepKey<State, 30>
+```
+
+### Depth Limit Marker (`??`)
+
+When `DeepKey` hits the depth limit on an object type, or encounters an **`any`-typed property** (unknowable structure), it emits a `??` marker in IDE autocomplete:
+
+```
+some.deep.path.??    ← depth limit reached
+data.payload.??      ← property typed as `any`
+```
+
+This tells you exactly where path generation stopped. To fix it: increase depth (`DeepKey<T, 30>`), restructure your type, or replace `any` with a concrete type.
+
+### Depth Propagation
+
+The `Depth` parameter propagates to all dependent types, keeping the entire type system consistent:
+
+```typescript
+// All accept a Depth parameter (defaults to DefaultDepth = 20)
+type Paths = DeepKey<State, 10>
+type BoolPaths = DeepKeyFiltered<State, boolean, 10>
+type Syncs = SyncPair<State, 10>
+type Logic = BoolLogic<State, 10>
+type Effects = SideEffects<State, Meta, 10>
+type Clear = ClearPathRule<State, 10>
+```
+
 ## Testing with the Mock Module
 
 ```tsx

package/dist/index.d.ts

@@ -21,6 +21,10 @@ type HASH_KEY = '[*]';
  * Supports nested objects up to depth 20 to handle deeply nested data structures.
  * Handles arrays and complex object hierarchies.
  *
+ * Uses loop unrolling: processes 2 nesting levels per recursion call,
+ * halving recursion depth while preserving bottom-up evaluation that
+ * TypeScript can cache (no prefix parameter).
+ *
  * Examples of supported paths:
  * - Simple: "name", "email"
  * - Nested: "user.address.street"
@@ -38,14 +42,84 @@ type HASH_KEY = '[*]';
  *
  * // DeepKey<User> = "name" | "address" | "address.street" | "address.city"
  * ```
+ *
+ * @example Custom depth — reduce for faster compilation on wide types
+ * ```typescript
+ * // Only traverse 10 levels deep instead of the default 20
+ * type ShallowPaths = DeepKey<User, 10>
+ * ```
+ *
+ * @example Depth limit marker — `??` appears at the cutoff point
+ * ```typescript
+ * // If a type is nested deeper than Depth, autocomplete shows:
+ * // "some.deep.path.??" — signaling you should increase depth or restructure
+ * type Paths = DeepKey<VeryDeepType, 6>
+ * ```
  */
 
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 type IsAny$1<T> = 0 extends 1 & T ? true : false;
-type DeepKey<T, Depth extends number = 20> = Depth extends 0 ? never : IsAny$1<T> extends true ? never : T extends Primitive ? never : T extends readonly any[] ? never : string extends keyof T ? HASH_KEY | (T[string] extends Primitive ? never : T[string] extends readonly any[] ? never : DeepKey<T[string], Prev<Depth>> extends infer DK ? DK extends string ? `${HASH_KEY}.${DK}` : never : never) : {
-    [K in keyof T & (string | number)]: `${K & string}` | (T[K] extends Primitive ? never : T[K] extends readonly any[] ? never : DeepKey<T[K], Prev<Depth>> extends infer DK ? DK extends string ? `${K & string}.${DK}` : never : never);
+/**
+ * Default recursion depth for DeepKey and all types that depend on it.
+ * Change this single value to adjust the depth limit across the entire type system.
+ *
+ * Propagates to: SyncPair, FlipPair, AggregationPair, ComputationPair,
+ * BoolLogic, SideEffects, DeepKeyFiltered, ClearPathRule.
+ *
+ * @example Override per-call instead of changing the default
+ * ```typescript
+ * type Shallow = DeepKey<MyState, 10>    // reduced depth
+ * type Deeper = DeepKey<MyState, 30>     // increased depth
+ * ```
+ */
+type DefaultDepth = 20;
+/**
+ * Marker emitted when DeepKey reaches its depth limit on an object type,
+ * or when it encounters an `any`-typed property (unknowable structure).
+ * Appears as `some.deep.path.??` in autocomplete, signaling the cutoff point.
+ * Users seeing this can increase depth: `DeepKey<T, 30>` or restructure their type.
+ */
+type DepthLimitMarker = '??';
+type DeepKey<T, Depth extends number = DefaultDepth> = DeepKeyUnrolled<T, Depth> & string;
+/**
+ * DeepKey with `??` marker paths excluded. Use in types that resolve path values
+ * (DeepValue, DeepKeyFiltered, PathsWithSameValueAs) where `??` would fail resolution.
+ * DeepKey itself keeps `??` for IDE autocomplete visibility.
+ */
+type ResolvableDeepKey<T, Depth extends number = DefaultDepth> = Exclude<DeepKey<T, Depth>, `${string}??` | '??'>;
+/**
+ * Loop-unrolled DeepKey: processes 2 nesting levels per recursion call.
+ *
+ * For each key K of T:
+ *   - Emit K (level 1 path)
+ *   - If T[K] is an object, inline level 2:
+ *     - For each key K2 of T[K]:
+ *       - Emit `${K}.${K2}` (level 2 path)
+ *       - If T[K][K2] is an object, recurse with `${K}.${K2}.${DeepKeyUnrolled}`
+ *
+ * Key insight: DeepKeyUnrolled<T, Depth> has NO prefix parameter,
+ * so identical sub-types at the same depth are cached by TypeScript.
+ * Template literal distribution (`${prefix}.${union}`) is handled natively
+ * by TypeScript without extra type instantiation overhead.
+ */
+type DeepKeyUnrolled<T, Depth extends number> = Depth extends 0 ? T extends Primitive | readonly any[] ? never : DepthLimitMarker : IsAny$1<T> extends true ? never : T extends Primitive ? never : T extends readonly any[] ? never : string extends keyof T ? HASH_KEY | (IsAny$1<T[string]> extends true ? `${HASH_KEY}.${DepthLimitMarker}` : NonNullable<T[string]> extends Primitive | readonly any[] ? never : RecordLevel2<NonNullable<T[string]>, HASH_KEY, Depth>) : {
+    [K in keyof T & (string | number)]: (K & string) | (IsAny$1<T[K]> extends true ? `${K & string}.${DepthLimitMarker}` : NonNullable<T[K]> extends Primitive | readonly any[] ? never : ConcreteLevel2<NonNullable<T[K]>, K & string, Depth>);
 }[keyof T & (string | number)];
-type Prev<N extends number> = N extends 20 ? 19 : N extends 19 ? 18 : N extends 18 ? 17 : N extends 17 ? 16 : N extends 16 ? 15 : N extends 15 ? 14 : N extends 14 ? 13 : N extends 13 ? 12 : N extends 12 ? 11 : N extends 11 ? 10 : N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ? 7 : N extends 7 ? 6 : N extends 6 ? 5 : N extends 5 ? 4 : N extends 4 ? 3 : N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : never;
+/**
+ * Level 2 expansion for concrete-key objects.
+ * Enumerates V's keys and uses inline template literal distribution for level 3+.
+ */
+type ConcreteLevel2<V, ParentKey extends string, Depth extends number> = IsAny$1<V> extends true ? `${ParentKey}.${DepthLimitMarker}` : V extends Primitive ? never : V extends readonly any[] ? never : string extends keyof V ? `${ParentKey}.${HASH_KEY}` | (IsAny$1<V[string]> extends true ? `${ParentKey}.${HASH_KEY}.${DepthLimitMarker}` : NonNullable<V[string]> extends Primitive | readonly any[] ? never : `${ParentKey}.${HASH_KEY}.${DeepKeyUnrolled<NonNullable<V[string]>, Prev2<Depth>> & string}`) : {
+    [K2 in keyof V & (string | number)]: `${ParentKey}.${K2 & string}` | (IsAny$1<V[K2]> extends true ? `${ParentKey}.${K2 & string}.${DepthLimitMarker}` : NonNullable<V[K2]> extends Primitive | readonly any[] ? never : `${ParentKey}.${K2 & string}.${DeepKeyUnrolled<NonNullable<V[K2]>, Prev2<Depth>> & string}`);
+}[keyof V & (string | number)];
+/**
+ * Level 2 expansion for Record-value objects.
+ * When level 1 was a Record, its value type V is expanded at level 2.
+ */
+type RecordLevel2<V, ParentKey extends string, Depth extends number> = IsAny$1<V> extends true ? `${ParentKey}.${DepthLimitMarker}` : V extends Primitive ? never : V extends readonly any[] ? never : string extends keyof V ? `${ParentKey}.${HASH_KEY}` | (IsAny$1<V[string]> extends true ? `${ParentKey}.${HASH_KEY}.${DepthLimitMarker}` : NonNullable<V[string]> extends Primitive | readonly any[] ? never : `${ParentKey}.${HASH_KEY}.${DeepKeyUnrolled<NonNullable<V[string]>, Prev2<Depth>> & string}`) : {
+    [K2 in keyof V & (string | number)]: `${ParentKey}.${K2 & string}` | (IsAny$1<V[K2]> extends true ? `${ParentKey}.${K2 & string}.${DepthLimitMarker}` : NonNullable<V[K2]> extends Primitive | readonly any[] ? never : `${ParentKey}.${K2 & string}.${DeepKeyUnrolled<NonNullable<V[K2]>, Prev2<Depth>> & string}`);
+}[keyof V & (string | number)];
+type Prev2<N extends number> = N extends 20 ? 18 : N extends 19 ? 17 : N extends 18 ? 16 : N extends 17 ? 15 : N extends 16 ? 14 : N extends 15 ? 13 : N extends 14 ? 12 : N extends 13 ? 11 : N extends 12 ? 10 : N extends 11 ? 9 : N extends 10 ? 8 : N extends 9 ? 7 : N extends 8 ? 6 : N extends 7 ? 5 : N extends 6 ? 4 : N extends 5 ? 3 : N extends 4 ? 2 : N extends 3 ? 1 : N extends 2 ? 0 : N extends 1 ? 0 : never;
 
 /**
  * Boolean logic DSL type definitions
@@ -90,28 +164,28 @@ type ComparableValue = string | number | boolean | null | undefined;
  * const isExpensive: BoolLogic<State> = { GT: ['product.price', 100] }
  * ```
  */
-type BoolLogic<STATE> = {
-    IS_EQUAL: [DeepKey<STATE>, ComparableValue];
+type BoolLogic<STATE, Depth extends number = DefaultDepth> = {
+    IS_EQUAL: [DeepKey<STATE, Depth>, ComparableValue];
 } | {
-    EXISTS: DeepKey<STATE>;
+    EXISTS: DeepKey<STATE, Depth>;
 } | {
-    IS_EMPTY: DeepKey<STATE>;
+    IS_EMPTY: DeepKey<STATE, Depth>;
 } | {
-    AND: BoolLogic<STATE>[];
+    AND: BoolLogic<STATE, Depth>[];
 } | {
-    OR: BoolLogic<STATE>[];
+    OR: BoolLogic<STATE, Depth>[];
 } | {
-    NOT: BoolLogic<STATE>;
+    NOT: BoolLogic<STATE, Depth>;
 } | {
-    GT: [DeepKey<STATE>, number];
+    GT: [DeepKey<STATE, Depth>, number];
 } | {
-    LT: [DeepKey<STATE>, number];
+    LT: [DeepKey<STATE, Depth>, number];
 } | {
-    GTE: [DeepKey<STATE>, number];
+    GTE: [DeepKey<STATE, Depth>, number];
 } | {
-    LTE: [DeepKey<STATE>, number];
+    LTE: [DeepKey<STATE, Depth>, number];
 } | {
-    IN: [DeepKey<STATE>, ComparableValue[]];
+    IN: [DeepKey<STATE, Depth>, ComparableValue[]];
 };
 
 /**
@@ -261,14 +335,14 @@ interface ValidationSchema<T = unknown> {
  * Can be a schema for the path's own value type, or a scoped schema
  * targeting a different path in the same state.
  */
-type ValidationStateInput<DATA, PATH extends DeepKey<DATA>> = {
+type ValidationStateInput<DATA, PATH extends DeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = {
     schema: ValidationSchema<DeepValue<DATA, PATH>>;
 } | {
-    [SCOPE in DeepKey<DATA>]: {
+    [SCOPE in ResolvableDeepKey<DATA, Depth>]: {
         scope: SCOPE;
         schema: ValidationSchema<DeepValue<DATA, SCOPE>>;
     };
-}[DeepKey<DATA>];
+}[ResolvableDeepKey<DATA, Depth>];
 /**
  * Get the appropriate registration config type for a concern at a given path.
  *
@@ -277,14 +351,14 @@ type ValidationStateInput<DATA, PATH extends DeepKey<DATA>> = {
  * - Template-based concerns: fixed { template: string }
  * - Custom concerns: fall back to Record<string, unknown>
  */
-type ConcernConfigFor<C, DATA extends object, PATH extends DeepKey<DATA>> = C extends {
+type ConcernConfigFor<C, DATA extends object, PATH extends DeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = C extends {
     name: 'validationState';
-} ? ValidationStateInput<DATA, PATH> : C extends {
+} ? ValidationStateInput<DATA, PATH, Depth> : C extends {
     evaluate: (props: infer P) => any;
 } ? P extends {
     boolLogic: any;
 } ? {
-    boolLogic: BoolLogic<DATA>;
+    boolLogic: BoolLogic<DATA, Depth>;
 } : Omit<P, 'state' | 'path' | 'value'> : Record<string, unknown>;
 /**
  * Extract the return type from a concern's evaluate function
@@ -340,11 +414,11 @@ type EvaluatedConcerns<CONCERNS extends readonly any[]> = {
  * }
  * ```
  */
-type ConcernRegistrationMap<DATA extends object, CONCERNS extends readonly any[] = readonly any[]> = Partial<{
-    [PATH in DeepKey<DATA>]: Partial<{
+type ConcernRegistrationMap<DATA extends object, CONCERNS extends readonly any[] = readonly any[], Depth extends number = DefaultDepth> = Partial<{
+    [PATH in DeepKey<DATA, Depth>]: Partial<{
         [C in CONCERNS[number] as C extends {
             name: string;
-        } ? C['name'] : never]: ConcernConfigFor<C, DATA, PATH>;
+        } ? C['name'] : never]: ConcernConfigFor<C, DATA, PATH, Depth>;
     }>;
 }>;
 
@@ -378,10 +452,16 @@ type ConcernRegistrationMap<DATA extends object, CONCERNS extends readonly any[]
  *
  * Uses mapped type with conditional filtering - maps over all possible paths,
  * keeps those matching the target type, and extracts the union.
+ *
+ * @example Custom depth — propagates to DeepKey
+ * ```typescript
+ * // Only number paths, limited to 10 levels deep
+ * type ShallowNumbers = DeepKeyFiltered<State, number, 10>
+ * ```
  */
-type DeepKeyFiltered<T, U> = {
-    [K in DeepKey<T>]: DeepValue<T, K> extends U ? K : never;
-}[DeepKey<T>];
+type DeepKeyFiltered<T, U, Depth extends number = DefaultDepth> = {
+    [K in ResolvableDeepKey<T, Depth>]: NonNullable<DeepValue<T, K>> extends U ? K : never;
+}[ResolvableDeepKey<T, Depth>];
 
 /**
  * PathsOfSameValue - Type-safe path tuples for side effects
@@ -407,19 +487,28 @@ type DeepKeyFiltered<T, U> = {
 /**
  * Get all paths in DATA that have the same value type as the value at PATH
  */
-type PathsWithSameValueAs<DATA extends object, PATH extends DeepKey<DATA>> = {
-    [K in DeepKey<DATA>]: DeepValue<DATA, K> extends DeepValue<DATA, PATH> ? DeepValue<DATA, PATH> extends DeepValue<DATA, K> ? K : never : never;
-}[DeepKey<DATA>];
+type PathsWithSameValueAs<DATA extends object, PATH extends ResolvableDeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = {
+    [K in ResolvableDeepKey<DATA, Depth>]: NonNullable<DeepValue<DATA, K>> extends NonNullable<DeepValue<DATA, PATH>> ? NonNullable<DeepValue<DATA, PATH>> extends NonNullable<DeepValue<DATA, K>> ? K : never : never;
+}[ResolvableDeepKey<DATA, Depth>];
 /**
  * A tuple of two paths that must have the same value type.
  * Format: [path1, path2]
  *
  * @example
  * const pair: SyncPair<State> = ['user.email', 'profile.email']
+ *
+ * @example Custom depth — propagates to DeepKey and PathsWithSameValueAs
+ * ```typescript
+ * // Limit path traversal to 10 levels
+ * const shallow: SyncPair<State, 10> = ['user.email', 'profile.email']
+ * ```
  */
-type SyncPair<DATA extends object> = {
-    [P1 in DeepKey<DATA>]: [P1, PathsWithSameValueAs<DATA, P1>];
-}[DeepKey<DATA>];
+type SyncPair<DATA extends object, Depth extends number = DefaultDepth> = {
+    [P1 in ResolvableDeepKey<DATA, Depth>]: [
+        P1,
+        PathsWithSameValueAs<DATA, P1, Depth>
+    ];
+}[ResolvableDeepKey<DATA, Depth>];
 /**
  * A tuple of two paths for flip (alias for SyncPair)
  * Format: [path1, path2]
@@ -427,7 +516,7 @@ type SyncPair<DATA extends object> = {
  * @example
  * const pair: FlipPair<State> = ['isActive', 'isInactive']
  */
-type FlipPair<DATA extends object> = SyncPair<DATA>;
+type FlipPair<DATA extends object, Depth extends number = DefaultDepth> = SyncPair<DATA, Depth>;
 /**
  * A tuple for aggregation: [target, source] or [target, source, excludeWhen]
  * First element (left) is ALWAYS the target (aggregated) path.
@@ -443,9 +532,9 @@ type FlipPair<DATA extends object> = SyncPair<DATA>;
  *   ['total', 'price2', { IS_EQUAL: ['price2.disabled', true] }],
  * ]
  */
-type AggregationPair<DATA extends object> = {
-    [P1 in DeepKey<DATA>]: [P1, PathsWithSameValueAs<DATA, P1>] | [P1, PathsWithSameValueAs<DATA, P1>, BoolLogic<DATA>];
-}[DeepKey<DATA>];
+type AggregationPair<DATA extends object, Depth extends number = DefaultDepth> = {
+    [P1 in ResolvableDeepKey<DATA, Depth>]: [P1, PathsWithSameValueAs<DATA, P1, Depth>] | [P1, PathsWithSameValueAs<DATA, P1, Depth>, BoolLogic<DATA, Depth>];
+}[ResolvableDeepKey<DATA, Depth>];
 /**
  * Supported computation operations for numeric reduction.
  */
@@ -467,9 +556,14 @@ type ComputationOp = 'SUM' | 'AVG';
  *   ['AVG', 'average', 'score2'],
  * ]
  */
-type ComputationPair<DATA extends object> = {
-    [TARGET in DeepKeyFiltered<DATA, number>]: [ComputationOp, TARGET, DeepKeyFiltered<DATA, number>] | [ComputationOp, TARGET, DeepKeyFiltered<DATA, number>, BoolLogic<DATA>];
-}[DeepKeyFiltered<DATA, number>];
+type ComputationPair<DATA extends object, Depth extends number = DefaultDepth> = {
+    [TARGET in DeepKeyFiltered<DATA, number, Depth>]: [ComputationOp, TARGET, DeepKeyFiltered<DATA, number, Depth>] | [
+        ComputationOp,
+        TARGET,
+        DeepKeyFiltered<DATA, number, Depth>,
+        BoolLogic<DATA, Depth>
+    ];
+}[DeepKeyFiltered<DATA, number, Depth>];
 
 /** Recursively makes all properties required, stripping undefined */
 type DeepRequired<T> = {
@@ -839,12 +933,12 @@ type OnStateListener<DATA extends object = object, SUB_STATE = DATA, META extend
  * }
  * ```
  */
-interface ListenerRegistration<DATA extends object = object, META extends GenericMeta = GenericMeta> {
+interface ListenerRegistration<DATA extends object = object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> {
     /**
      * Path to watch - only changes under this path will trigger the listener
      * null = watch all top-level paths
      */
-    path: DeepKey<DATA> | null;
+    path: DeepKey<DATA, Depth> | null;
     /**
      * Scope for state and changes presentation
      * - If null: state is full DATA, changes use FULL paths
@@ -852,7 +946,7 @@ interface ListenerRegistration<DATA extends object = object, META extends Generi
      *
      * Note: Changes are filtered based on `path`, even when scope is null
      */
-    scope: DeepKey<DATA> | null;
+    scope: DeepKey<DATA, Depth> | null;
     fn: OnStateListener<DATA, any, META>;
 }
 interface ListenerHandlerRef {
@@ -1075,7 +1169,7 @@ declare const prebuiltsNamespace: {
 
 type index_ValidationError = ValidationError;
 type index_ValidationStateConcern = ValidationStateConcern;
-type index_ValidationStateInput<DATA, PATH extends DeepKey<DATA>> = ValidationStateInput<DATA, PATH>;
+type index_ValidationStateInput<DATA, PATH extends DeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = ValidationStateInput<DATA, PATH, Depth>;
 type index_ValidationStateResult = ValidationStateResult;
 declare const index_disabledWhen: typeof disabledWhen;
 declare const index_dynamicLabel: typeof dynamicLabel;
@@ -1130,13 +1224,9 @@ declare const defaultConcerns: readonly [ValidationStateConcern, ConcernType<"di
  * - targets: paths to set to null
  * - expandMatch: if true, [*] in targets expands to ALL keys (not just matched key)
  */
-type ClearPathRule<DATA extends object> = [
-    DeepKey<DATA>[],
-    DeepKey<DATA>[],
-    {
-        expandMatch?: boolean;
-    }?
-];
+type ClearPathRule<DATA extends object, Depth extends number = DefaultDepth> = [DeepKey<DATA, Depth>[], DeepKey<DATA, Depth>[], {
+    expandMatch?: boolean;
+}?];
 /**
  * Side effects configuration for useSideEffects hook
  *
@@ -1185,37 +1275,37 @@ type ClearPathRule<DATA extends object> = [
  * })
  * ```
  */
-interface SideEffects<DATA extends object, META extends GenericMeta = GenericMeta> {
+interface SideEffects<DATA extends object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> {
     /**
      * Sync paths - keeps specified paths synchronized
      * Format: [path1, path2] - both paths stay in sync
      */
-    syncPaths?: SyncPair<DATA>[];
+    syncPaths?: SyncPair<DATA, Depth>[];
     /**
      * Flip paths - keeps specified paths with opposite values
      * Format: [path1, path2] - paths have inverse boolean values
      */
-    flipPaths?: FlipPair<DATA>[];
+    flipPaths?: FlipPair<DATA, Depth>[];
     /**
      * Aggregations - aggregates sources into target
      * Format: [target, source] - target is ALWAYS first (left)
      * Multiple pairs can point to same target for multi-source aggregation
      */
-    aggregations?: AggregationPair<DATA>[];
+    aggregations?: AggregationPair<DATA, Depth>[];
     /**
      * Clear paths - "when X changes, set Y to null"
      * Format: [triggers[], targets[], { expandMatch?: boolean }?]
      * - Default: [*] in target correlates with trigger's [*] (same key)
      * - expandMatch: true → [*] in target expands to ALL keys
      */
-    clearPaths?: ClearPathRule<DATA>[];
+    clearPaths?: ClearPathRule<DATA, Depth>[];
     /**
      * Computations - numeric reduction operations (SUM, AVG)
      * 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)
      */
-    computations?: ComputationPair<DATA>[];
+    computations?: ComputationPair<DATA, Depth>[];
     /**
      * Listeners - react to state changes with scoped state
      */