@sladg/apex-state 3.9.1 → 3.11.2

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { ReactNode } from 'react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * Hash key type for Record-based paths
@@ -906,6 +905,30 @@ interface ConcernRegistration {
     dispose: () => void;
 }
 
+/**
+ * Pipeline Observer — Unified debug logging + Redux DevTools integration.
+ *
+ * Single interface that dispatches to:
+ * - Console logging (controlled by logPipeline / logListeners / logConcerns flags)
+ * - Redux DevTools (controlled by devtools flag) with nested tree-shaped state
+ *
+ * Call sites use one `observer.xyz()` call; the observer fans out internally.
+ * Zero runtime cost when all flags are false (returns no-op object).
+ */
+
+interface PipelineObserver {
+    pipelineStart: (label: string, input: unknown[]) => void;
+    phase1: (stateChanges: unknown[]) => void;
+    syncExpand: (changes: unknown[]) => void;
+    flipExpand: (changes: unknown[]) => void;
+    listenerDispatch: (subscriberId: number, fnName: string, scope: string, input: unknown[], output: unknown) => void;
+    validatorResult: (outputPath: string, input: unknown, result: unknown) => void;
+    phase2: (stateChanges: unknown[]) => void;
+    pipelineEnd: () => void;
+    concernEval: (path: string, name: string, value: unknown, result: unknown) => void;
+    destroy: () => void;
+}
+
 /**
  * Debug Timing Utilities
  *
@@ -947,6 +970,7 @@ interface DispatchEntry {
     dispatch_id: number;
     subscriber_id: number;
     scope_path: string;
+    topic_path: string;
     /** Indexes into ProcessResult.changes array. */
     input_change_ids: number[];
 }
@@ -1158,6 +1182,14 @@ interface DebugConfig {
     timingThreshold?: number;
     /** Enable tracking of processChanges calls and applied changes for testing/debugging */
     track?: boolean;
+    /** Log pipeline phases, state changes, sync/flip expansions */
+    logPipeline?: boolean;
+    /** Log listener dispatch inputs and outputs */
+    logListeners?: boolean;
+    /** Log concern evaluations and validator runs */
+    logConcerns?: boolean;
+    /** Connect to Redux DevTools Extension for state inspection */
+    devtools?: boolean;
 }
 /**
  * A single recorded processChanges invocation
@@ -1295,6 +1327,7 @@ interface InternalState<DATA extends object = object, META extends GenericMeta =
     registrations: Registrations;
     processing: ProcessingState<DATA, META>;
     timing: Timing;
+    observer: PipelineObserver;
     config: DeepRequired<StoreConfig>;
     /** Per-store WASM pipeline instance (null when using legacy implementation). */
     pipeline: WasmPipeline | null;
@@ -1636,20 +1669,17 @@ interface SideEffects<DATA extends object, META extends GenericMeta = GenericMet
     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;
-    };
+/**
+ * Explicit return type of createGenericStore.
+ *
+ * Defined as an interface so TypeScript references type aliases by name
+ * (e.g. `SideEffects<DATA, META>`) instead of expanding them inline.
+ * Without this, large DATA types (2800+ DeepKey paths) cause
+ * "inferred type exceeds the maximum length" (TS error) because the
+ * compiler tries to inline-expand every O(N²) pair type.
+ */
+interface GenericStoreApi<DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly ConcernType<string, any, any>[] = typeof defaultConcerns> {
+    Provider: (props: ProviderProps<DATA>) => React.JSX.Element;
     useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
         value: DeepValue<DATA, P>;
         setValue: (newValue: DeepValue<DATA, P>, meta?: META) => void;
@@ -1664,11 +1694,13 @@ declare const createGenericStore: <DATA extends object, META extends GenericMeta
     useConcerns: <CUSTOM extends readonly ConcernType<string, any, any>[] = readonly []>(id: string, registration: ConcernRegistrationMap<DATA, readonly [...CONCERNS, ...CUSTOM]>, customConcerns?: CUSTOM) => void;
     withConcerns: <SELECTION extends Partial<Record<Extract<CONCERNS[number], {
         name: string;
-    }>["name"], boolean>>>(selection: SELECTION) => {
+    }>['name'], boolean>>>(selection: SELECTION) => {
         useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
-            value: DATA extends readonly any[] ? DATA[number] : P extends `${infer First}.${infer Rest}` ? First extends keyof DATA ? DeepValue<NonNullable<DATA[First]>, Rest> : string extends keyof DATA ? First extends "[*]" ? DeepValue<DATA[keyof DATA & string], Rest> : unknown : unknown : P extends "[*]" ? string extends keyof DATA ? DATA[keyof DATA & string] : unknown : P extends keyof DATA ? DATA[P] : unknown;
-            setValue: (newValue: DATA extends readonly any[] ? DATA[number] : P extends `${infer First}.${infer Rest}` ? First extends keyof DATA ? DeepValue<NonNullable<DATA[First]>, Rest> : string extends keyof DATA ? First extends "[*]" ? DeepValue<DATA[keyof DATA & string], Rest> : unknown : unknown : P extends "[*]" ? string extends keyof DATA ? DATA[keyof DATA & string] : unknown : P extends keyof DATA ? DATA[P] : unknown, meta?: META) => void;
-        } & { [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends keyof EvaluatedConcerns<CONCERNS> ? EvaluatedConcerns<CONCERNS>[K] : never; };
+            value: DeepValue<DATA, P>;
+            setValue: (newValue: DeepValue<DATA, P>, meta?: META) => void;
+        } & {
+            [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends keyof EvaluatedConcerns<CONCERNS> ? EvaluatedConcerns<CONCERNS>[K] : never;
+        };
     };
     withMeta: (presetMeta: Partial<META>) => {
         useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
@@ -1676,9 +1708,26 @@ declare const createGenericStore: <DATA extends object, META extends GenericMeta
             setValue: (newValue: DeepValue<DATA, P>, meta?: META) => void;
         };
     };
-};
-/** Return type of createGenericStore — used by testing mock for 1:1 type safety */
-type GenericStoreApi<DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly ConcernType<string, any, any>[] = typeof defaultConcerns> = ReturnType<typeof createGenericStore<DATA, META, CONCERNS>>;
+    syncPairs: <T extends [ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>][]>(pairs: CheckSyncPairs<DATA, T>) => ValidatedSyncPairs<DATA>;
+    flipPairs: <T extends [ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>][]>(pairs: CheckSyncPairs<DATA, T>) => ValidatedFlipPairs<DATA>;
+    aggregationPairs: <T extends ([ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>] | [ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>, BoolLogic<DATA>])[]>(pairs: CheckAggregationPairs<DATA, T>) => ValidatedAggregationPairs<DATA>;
+    computationPairs: <T extends ([
+        ComputationOp,
+        DeepKeyFiltered<DATA, number>,
+        DeepKeyFiltered<DATA, number>
+    ] | [
+        ComputationOp,
+        DeepKeyFiltered<DATA, number>,
+        DeepKeyFiltered<DATA, number>,
+        BoolLogic<DATA>
+    ])[]>(pairs: CheckComputationPairs<DATA, T>) => ValidatedComputationPairs<DATA>;
+    listeners: <T extends readonly {
+        path: ResolvableDeepKey<DATA> | null;
+        scope?: ResolvableDeepKey<DATA> | null | undefined;
+        fn: (...args: any[]) => any;
+    }[]>(items: CheckListeners<DATA, META, T>) => ValidatedListeners<DATA, META>;
+}
+declare const createGenericStore: <DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly ConcernType<string, any, any>[] = typeof defaultConcerns>(config?: StoreConfig) => GenericStoreApi<DATA, META, CONCERNS>;
 
 /**
  * Minimal field interface that useBufferedField accepts
@@ -2214,28 +2263,30 @@ declare const is: {
  * Applies an array of changes to an object, returning a new object.
  */
 
+/** A change tuple: [path, value] or [path, value, anyMeta]. Meta is ignored. */
+type AnyChange<DATA> = {
+    [K in DeepKey<DATA>]: [K, DeepValue<DATA, K>] | [K, DeepValue<DATA, K>, ...unknown[]];
+}[DeepKey<DATA>];
 /**
  * Applies changes to an object, returning a new object with changes applied.
- * Does not mutate the original object.
+ * Does not mutate the original object. Meta fields on change tuples are ignored.
  *
  * @param obj - Source object
- * @param changes - Array of [path, value, meta] tuples
+ * @param changes - Array of [path, value] or [path, value, meta] tuples
  * @returns New object with changes applied
  *
  * @example
  * ```typescript
  * const state = { user: { name: 'Alice', age: 30 } }
- * const changes: ArrayOfChanges<typeof state> = [
- *   ['user.name', 'Bob', {}],
- *   ['user.age', 31, {}],
- * ]
- *
- * const newState = applyChangesToObject(state, changes)
+ * const newState = applyChangesToObject(state, [
+ *   ['user.name', 'Bob'],
+ *   ['user.age', 31],
+ * ])
  * // newState: { user: { name: 'Bob', age: 31 } }
  * // state is unchanged
  * ```
  */
-declare const applyChangesToObject: <T extends object>(obj: T, changes: ArrayOfChanges<T>) => T;
+declare const applyChangesToObject: <T extends object>(obj: T, changes: AnyChange<T>[]) => T;
 
 /**
  * Deep clone utility — single swap point for the cloning implementation.
@@ -2255,4 +2306,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 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 };
+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 PipelineObserver, type ProviderProps, STORE_DATA, type SelectOption, type SideEffects, type StoreConfig, type StoreInstance, type SyncPair, type ThrottleConfig, type ThrottleFieldInput, type TransformConfig, VALIDATED, type ValidatedAggregationPairs, type ValidatedComputationPairs, type ValidatedFlipPairs, type ValidatedListeners, type ValidatedSyncPairs, 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 };