@sladg/apex-state 3.5.0 → 3.6.0

package/dist/index.d.ts

@@ -121,6 +121,70 @@ type RecordLevel2<V, ParentKey extends string, Depth extends number> = IsAny$1<V
 }[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;
 
+/**
+ * DeepKeyFiltered - Filters paths by their resolved value type
+ *
+ * Returns only paths from DeepKey<T> that resolve to a specific type U.
+ * Useful for type-safe filtering of state paths by their value types.
+ *
+ * @example
+ * ```typescript
+ * type Data = {
+ *   isActive: boolean
+ *   name: string
+ *   count: number
+ *   user: { isAdmin: boolean }
+ * }
+ *
+ * // Only boolean paths
+ * type BoolPaths = DeepKeyFiltered<Data, boolean>
+ * // Result: "isActive" | "user.isAdmin"
+ *
+ * // Only string paths
+ * type StrPaths = DeepKeyFiltered<Data, string>
+ * // Result: "name"
+ * ```
+ */
+
+/**
+ * Filters DeepKey<T> to only include paths that resolve to type U.
+ *
+ * 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, Depth extends number = DefaultDepth> = {
+    [K in ResolvableDeepKey<T, Depth>]: NonNullable<DeepValue<T, K>> extends U ? K : never;
+}[ResolvableDeepKey<T, Depth>];
+
+/**
+ * DeepValue utility type
+ *
+ * Extracts the value type for a given dot-notation path string.
+ * Handles nested objects, arrays, and optional properties.
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   address: {
+ *     street: string
+ *     city: string
+ *   }
+ * }
+ *
+ * // DeepValue<User, "address.street"> = string
+ * // DeepValue<User, "address"> = { street: string, city: string }
+ * ```
+ */
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type DeepValue<T, Path extends string> = IsAny<T> extends true ? never : T extends readonly any[] ? T[number] : Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? DeepValue<T[First], Rest> : string extends keyof T ? First extends HASH_KEY ? DeepValue<T[string], Rest> : unknown : unknown : Path extends HASH_KEY ? string extends keyof T ? T[string] : unknown : Path extends keyof T ? T[Path] : unknown;
+
 /**
  * Boolean logic DSL type definitions
  *
@@ -129,9 +193,23 @@ type Prev2<N extends number> = N extends 20 ? 18 : N extends 19 ? 17 : N extends
  */
 
 /**
- * Primitive types that can be compared in BoolLogic expressions
+ * Path-value pair distributed over all valid paths.
+ * Each path is paired with its resolved value type, ensuring type safety.
+ * The distribution happens inside the tuple, not at the union level —
+ * this keeps BoolLogic's top-level union flat so `in` narrowing works.
+ */
+type PathValuePair<STATE, Depth extends number> = DeepKey<STATE, Depth> extends infer P ? P extends string ? [P, DeepValue<STATE, P>] : never : never;
+/**
+ * Path-value array pair for IN operator.
+ * Same distribution as PathValuePair but with array values.
+ */
+type PathValueArrayPair<STATE, Depth extends number> = DeepKey<STATE, Depth> extends infer P ? P extends string ? [P, DeepValue<STATE, P>[]] : never : never;
+/**
+ * Paths that resolve to number, plus `.length` on array-valued paths.
+ * Allows GT/LT/GTE/LTE to compare against array lengths without
+ * polluting DeepKey with virtual paths.
  */
-type ComparableValue = string | number | boolean | null | undefined;
+type NumericPaths<STATE, Depth extends number> = DeepKeyFiltered<STATE, number, Depth> | `${DeepKeyFiltered<STATE, readonly unknown[], Depth>}.length`;
 /**
  * Boolean logic DSL for conditional expressions
  *
@@ -139,33 +217,40 @@ type ComparableValue = string | number | boolean | null | undefined;
  * Used by concerns (disabledWhen, visibleWhen) and side effects.
  *
  * Operators:
- * - IS_EQUAL: Compare path value to expected value
+ * - IS_EQUAL: Compare path value to expected value (value must match path type)
  * - EXISTS: Check if path value is not null/undefined
  * - IS_EMPTY: Check if path value is empty (string/array/object)
  * - AND/OR/NOT: Boolean combinators
- * - GT/LT/GTE/LTE: Numeric comparisons
- * - IN: Check if path value is in allowed list
+ * - GT/LT/GTE/LTE: Numeric comparisons (only on number paths or array.length)
+ * - IN: Check if path value is in allowed list (values must match path type)
+ * - Shorthand: [path, value] tuple as shorthand for IS_EQUAL
  *
  * @example
  * ```typescript
  * // Simple equality check
  * const isAdmin: BoolLogic<State> = { IS_EQUAL: ['user.role', 'admin'] }
  *
- * // Combined conditions
+ * // Shorthand equality (equivalent to IS_EQUAL)
+ * const isAdmin2: BoolLogic<State> = ['user.role', 'admin']
+ *
+ * // Combined conditions with shorthand
  * const canEdit: BoolLogic<State> = {
  *   AND: [
- *     { IS_EQUAL: ['user.role', 'editor'] },
+ *     ['user.role', 'editor'],
  *     { EXISTS: 'document.id' },
- *     { NOT: { IS_EQUAL: ['document.status', 'locked'] } }
+ *     { NOT: ['document.status', 'locked'] }
  *   ]
  * }
  *
  * // Numeric comparison
  * const isExpensive: BoolLogic<State> = { GT: ['product.price', 100] }
+ *
+ * // Array length comparison
+ * const hasManyItems: BoolLogic<State> = { GT: ['cart.items.length', 5] }
  * ```
  */
 type BoolLogic<STATE, Depth extends number = DefaultDepth> = {
-    IS_EQUAL: [DeepKey<STATE, Depth>, ComparableValue];
+    IS_EQUAL: PathValuePair<STATE, Depth>;
 } | {
     EXISTS: DeepKey<STATE, Depth>;
 } | {
@@ -177,39 +262,16 @@ type BoolLogic<STATE, Depth extends number = DefaultDepth> = {
 } | {
     NOT: BoolLogic<STATE, Depth>;
 } | {
-    GT: [DeepKey<STATE, Depth>, number];
+    GT: [NumericPaths<STATE, Depth>, number];
 } | {
-    LT: [DeepKey<STATE, Depth>, number];
+    LT: [NumericPaths<STATE, Depth>, number];
 } | {
-    GTE: [DeepKey<STATE, Depth>, number];
+    GTE: [NumericPaths<STATE, Depth>, number];
 } | {
-    LTE: [DeepKey<STATE, Depth>, number];
+    LTE: [NumericPaths<STATE, Depth>, number];
 } | {
-    IN: [DeepKey<STATE, Depth>, ComparableValue[]];
-};
-
-/**
- * DeepValue utility type
- *
- * Extracts the value type for a given dot-notation path string.
- * Handles nested objects, arrays, and optional properties.
- *
- * @example
- * ```typescript
- * type User = {
- *   address: {
- *     street: string
- *     city: string
- *   }
- * }
- *
- * // DeepValue<User, "address.street"> = string
- * // DeepValue<User, "address"> = { street: string, city: string }
- * ```
- */
-
-type IsAny<T> = 0 extends 1 & T ? true : false;
-type DeepValue<T, Path extends string> = IsAny<T> extends true ? never : T extends readonly any[] ? T[number] : Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? DeepValue<T[First], Rest> : string extends keyof T ? First extends HASH_KEY ? DeepValue<T[string], Rest> : unknown : unknown : Path extends HASH_KEY ? string extends keyof T ? T[string] : unknown : Path extends keyof T ? T[Path] : unknown;
+    IN: PathValueArrayPair<STATE, Depth>;
+} | PathValuePair<STATE, Depth>;
 
 /**
  * GenericMeta interface
@@ -422,47 +484,6 @@ type ConcernRegistrationMap<DATA extends object, CONCERNS extends readonly any[]
     }>;
 }>;
 
-/**
- * DeepKeyFiltered - Filters paths by their resolved value type
- *
- * Returns only paths from DeepKey<T> that resolve to a specific type U.
- * Useful for type-safe filtering of state paths by their value types.
- *
- * @example
- * ```typescript
- * type Data = {
- *   isActive: boolean
- *   name: string
- *   count: number
- *   user: { isAdmin: boolean }
- * }
- *
- * // Only boolean paths
- * type BoolPaths = DeepKeyFiltered<Data, boolean>
- * // Result: "isActive" | "user.isAdmin"
- *
- * // Only string paths
- * type StrPaths = DeepKeyFiltered<Data, string>
- * // Result: "name"
- * ```
- */
-
-/**
- * Filters DeepKey<T> to only include paths that resolve to type U.
- *
- * 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, 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
  *