@sladg/apex-state 3.7.3 → 3.9.0

package/dist/index.js

@@ -1752,7 +1752,7 @@ var filterAndRelativize = (changes, listenerPath) => {
   return result;
 };
 var processListeners = (changes, store, currentState) => {
-  const { listeners, sortedListenerPaths } = store._internal.graphs;
+  const { listeners: listeners2, sortedListenerPaths } = store._internal.graphs;
   const { queue } = store._internal.processing;
   const effectiveChanges = [];
   for (const change of changes) {
@@ -1767,7 +1767,7 @@ var processListeners = (changes, store, currentState) => {
     (a, b) => getPathDepth(b[0]) - getPathDepth(a[0])
   );
   for (const listenerPath of sortedListenerPaths) {
-    const pathListeners = listeners.get(listenerPath);
+    const pathListeners = listeners2.get(listenerPath);
     const relevantChanges = filterAndRelativize(sortedChanges, listenerPath);
     for (const registration of pathListeners) {
       processListener({
@@ -2068,12 +2068,12 @@ var processChangesWasm = (store, initialChanges) => {
 
 // src/sideEffects/prebuilts/aggregation.ts
 import { effect as effect3 } from "valtio-reactive";
-var registerAggregations = (store, id, aggregationPairs) => {
+var registerAggregations = (store, id, aggregationPairs2) => {
   const { aggregations } = store._internal.registrations;
   const disposeCallbacks = [];
   const targets = /* @__PURE__ */ new Set();
   const sources = /* @__PURE__ */ new Set();
-  for (const [target, source] of aggregationPairs) {
+  for (const [target, source] of aggregationPairs2) {
     targets.add(target);
     sources.add(source);
   }
@@ -2085,7 +2085,7 @@ var registerAggregations = (store, id, aggregationPairs) => {
     }
   }
   const byTarget = /* @__PURE__ */ new Map();
-  for (const [target, source] of aggregationPairs) {
+  for (const [target, source] of aggregationPairs2) {
     const existing = byTarget.get(target) ?? [];
     existing.push(source);
     byTarget.set(target, existing);
@@ -2162,30 +2162,33 @@ var validateScopeAndPath = (path, scope) => {
 };
 var registerListenerLegacy = (store, registration) => {
   const { graphs } = store._internal;
-  const { listeners, listenerHandlers } = graphs;
-  validateScopeAndPath(registration.path, registration.scope);
+  const { listeners: listeners2, listenerHandlers } = graphs;
+  if (registration.scope === void 0) {
+    registration.scope = registration.path;
+  }
+  validateScopeAndPath(registration.path, registration.scope ?? null);
   const subscriberId = nextSubscriberId++;
   const mapKey = registration.path ?? "";
-  const existing = listeners.get(mapKey) ?? [];
+  const existing = listeners2.get(mapKey) ?? [];
   const originalFn = registration.fn;
   registration.fn = (changes, state) => store._internal.timing.run("listeners", () => originalFn(changes, state), {
     path: mapKey,
     name: "listener"
   });
-  listeners.set(mapKey, [...existing, registration]);
+  listeners2.set(mapKey, [...existing, registration]);
   listenerHandlers.set(subscriberId, {
     scope: registration.scope,
     fn: registration.fn
   });
   updateSortedListenerPaths(graphs);
   return () => {
-    const list = listeners.get(mapKey);
+    const list = listeners2.get(mapKey);
     if (list) {
       const filtered = list.filter((l) => l !== registration);
       if (filtered.length > 0) {
-        listeners.set(mapKey, filtered);
+        listeners2.set(mapKey, filtered);
       } else {
-        listeners.delete(mapKey);
+        listeners2.delete(mapKey);
       }
       updateSortedListenerPaths(graphs);
     }
@@ -2264,17 +2267,20 @@ var registerSyncPairsBatch = (store, pairs) => {
 var registerSideEffectsImpl = (store, id, effects) => {
   const cleanups = [];
   if (effects.syncPaths) {
-    const cleanup = registerSyncPairsBatch(store, effects.syncPaths);
+    const pairs = effects.syncPaths;
+    const cleanup = registerSyncPairsBatch(store, pairs);
     cleanups.push(cleanup);
   }
   if (effects.flipPaths) {
-    for (const [path1, path2] of effects.flipPaths) {
+    const pairs = effects.flipPaths;
+    for (const [path1, path2] of pairs) {
       const cleanup = registerFlipPair(store, path1, path2);
       cleanups.push(cleanup);
     }
   }
   if (effects.aggregations) {
-    const cleanup = registerAggregations(store, id, effects.aggregations);
+    const pairs = effects.aggregations;
+    const cleanup = registerAggregations(store, id, pairs);
     cleanups.push(cleanup);
   }
   if (effects.listeners) {
@@ -2299,12 +2305,12 @@ var registerSideEffects = (store, id, effects) => store._internal.timing.run(
 // src/sideEffects/registration.wasm-impl.ts
 var nextSubscriberId2 = 0;
 var registerSideEffects2 = (store, id, effects) => {
-  const syncPairs = effects.syncPaths ?? [];
-  const flipPairs = effects.flipPaths ?? [];
-  const aggregationPairs = (effects.aggregations ?? []).map(
+  const syncPairs2 = effects.syncPaths ?? [];
+  const flipPairs2 = effects.flipPaths ?? [];
+  const aggregationPairs2 = (effects.aggregations ?? []).map(
     ([target, source, condition]) => condition ? [target, source, JSON.stringify(condition)] : [target, source]
   );
-  const computationPairs = (effects.computations ?? []).map(
+  const computationPairs2 = (effects.computations ?? []).map(
     ([op, target, source, condition]) => condition ? [
       op,
       target,
@@ -2316,10 +2322,11 @@ var registerSideEffects2 = (store, id, effects) => {
     triggers,
     targets: opts?.expandMatch ? targets.map((t) => t.replace(/\[\*\]/g, "[**]")) : targets
   }));
-  const listeners = effects.listeners?.map((listener) => {
+  const listeners2 = effects.listeners?.map((listener) => {
     const { listenerHandlers } = store._internal.graphs;
     const subscriberId = nextSubscriberId2++;
     const originalFn = listener.fn;
+    const effectiveScope = listener.scope === void 0 ? listener.path : listener.scope;
     const mapKey = listener.path ?? "";
     const wrappedFn = (changes, state) => store._internal.timing.run(
       "listeners",
@@ -2330,27 +2337,27 @@ var registerSideEffects2 = (store, id, effects) => {
       }
     );
     listenerHandlers.set(subscriberId, {
-      scope: listener.scope,
+      scope: effectiveScope,
       fn: wrappedFn
     });
     return {
       subscriber_id: subscriberId,
       topic_path: listener.path ?? "",
-      scope_path: listener.scope ?? ""
+      scope_path: effectiveScope ?? ""
     };
   });
   const pipeline = store._internal.pipeline;
   const registrationId = `sideEffects-${id}`;
   const result = pipeline.registerSideEffects({
     registration_id: registrationId,
-    ...syncPairs.length > 0 && { sync_pairs: syncPairs },
-    ...flipPairs.length > 0 && { flip_pairs: flipPairs },
-    ...aggregationPairs.length > 0 && { aggregation_pairs: aggregationPairs },
-    ...computationPairs.length > 0 && {
-      computation_pairs: computationPairs
+    ...syncPairs2.length > 0 && { sync_pairs: syncPairs2 },
+    ...flipPairs2.length > 0 && { flip_pairs: flipPairs2 },
+    ...aggregationPairs2.length > 0 && { aggregation_pairs: aggregationPairs2 },
+    ...computationPairs2.length > 0 && {
+      computation_pairs: computationPairs2
     },
     ...clearPaths && clearPaths.length > 0 && { clear_paths: clearPaths },
-    ...listeners && listeners.length > 0 && { listeners }
+    ...listeners2 && listeners2.length > 0 && { listeners: listeners2 }
   });
   if (result.sync_changes.length > 0) {
     applyBatch(
@@ -2373,9 +2380,9 @@ var registerSideEffects2 = (store, id, effects) => {
   const cleanup = () => {
     pipeline.unregisterSideEffects(registrationId);
     effects.listeners?.forEach((_listener, index) => {
-      if (listeners && listeners[index]) {
+      if (listeners2 && listeners2[index]) {
         store._internal.graphs.listenerHandlers.delete(
-          listeners[index].subscriber_id
+          listeners2[index].subscriber_id
         );
       }
     });
@@ -2847,6 +2854,119 @@ var createProvider = (storeConfig) => {
   return Provider;
 };
 
+// src/utils/pair-helpers.ts
+var syncPairs = () => (pairs) => pairs;
+var flipPairs = () => (pairs) => pairs;
+var aggregationPairs = () => (pairs) => pairs;
+var computationPairs = () => (pairs) => pairs;
+var listeners = () => (items) => items;
+
+// src/store/warm-pair-helpers.ts
+var createWarmPairHelpers = () => ({
+  /**
+   * Pre-warmed sync pair validator — DATA type is already bound.
+   * Validates that both paths in each pair resolve to the same value type.
+   * Pass the result to `useSideEffects` as `syncPaths`.
+   *
+   * @example
+   * ```typescript
+   * const { useSideEffects, syncPairs } = createGenericStore<MyState>()
+   *
+   * // Type-safe — no need to repeat <MyState>
+   * const syncs = syncPairs([
+   *   ['user.email', 'profile.email'],   // ✓ both string
+   *   ['user.age', 'profile.age'],       // ✓ both number
+   * ])
+   *
+   * // Inside a component:
+   * useSideEffects('my-syncs', { syncPaths: syncs })
+   * ```
+   */
+  syncPairs: syncPairs(),
+  /**
+   * Pre-warmed flip pair validator — DATA type is already bound.
+   * Validates that both paths in each pair resolve to the same value type.
+   * Used for inverted boolean synchronization. Pass the result to `useSideEffects` as `flipPaths`.
+   *
+   * @example
+   * ```typescript
+   * const { useSideEffects, flipPairs } = createGenericStore<MyState>()
+   *
+   * const flips = flipPairs([
+   *   ['isExpanded', 'isCollapsed'],  // ✓ both boolean
+   * ])
+   *
+   * // Inside a component:
+   * useSideEffects('my-flips', { flipPaths: flips })
+   * ```
+   */
+  flipPairs: flipPairs(),
+  /**
+   * Pre-warmed aggregation pair validator — DATA type is already bound.
+   * Each pair is `[target, source]` or `[target, source, BoolLogic]`.
+   * Validates that target and source resolve to the same value type.
+   * Pass the result to `useSideEffects` as `aggregations`.
+   *
+   * @example
+   * ```typescript
+   * const { useSideEffects, aggregationPairs } = createGenericStore<MyState>()
+   *
+   * const aggs = aggregationPairs([
+   *   ['total', 'price1'],
+   *   ['total', 'price2', { IS_EQUAL: ['price2.disabled', true] }],
+   * ])
+   *
+   * // Inside a component:
+   * useSideEffects('my-aggs', { aggregations: aggs })
+   * ```
+   */
+  aggregationPairs: aggregationPairs(),
+  /**
+   * Pre-warmed computation pair validator — DATA type is already bound.
+   * Each pair is `[op, target, source]` or `[op, target, source, BoolLogic]`.
+   * Both target and source must be number paths.
+   * Pass the result to `useSideEffects` as `computations`.
+   *
+   * @example
+   * ```typescript
+   * const { useSideEffects, computationPairs } = createGenericStore<MyState>()
+   *
+   * const comps = computationPairs([
+   *   ['SUM', 'total', 'price1'],
+   *   ['AVG', 'average', 'score1'],
+   * ])
+   *
+   * // Inside a component:
+   * useSideEffects('my-comps', { computations: comps })
+   * ```
+   */
+  computationPairs: computationPairs(),
+  /**
+   * Pre-warmed listener validator — DATA type is already bound.
+   * Validates path/scope relationships and derives fn types from scope.
+   * Pass the result to `useSideEffects` as `listeners`.
+   *
+   * @example
+   * ```typescript
+   * const { useSideEffects, listeners } = createGenericStore<MyState>()
+   *
+   * const myListeners = listeners([
+   *   {
+   *     path: 'user.profile.name',
+   *     scope: 'user.profile',
+   *     fn: (changes, state) => {
+   *       // state is typed as MyState['user']['profile']
+   *       return undefined
+   *     }
+   *   },
+   * ])
+   *
+   * useSideEffects('my-listeners', { listeners: myListeners })
+   * ```
+   */
+  listeners: listeners()
+});
+
 // src/store/create-store.ts
 var createGenericStore = (config) => {
   const Provider = createProvider(config);
@@ -2947,7 +3067,8 @@ var createGenericStore = (config) => {
     useSideEffects,
     useConcerns,
     withConcerns,
-    withMeta
+    withMeta,
+    ...createWarmPairHelpers()
   };
 };
 
@@ -3106,7 +3227,9 @@ var applyChangesToObject = (obj, changes) => {
 };
 export {
   _,
+  aggregationPairs,
   applyChangesToObject,
+  computationPairs,
   createGenericStore,
   deepClone,
   defaultConcerns,
@@ -3114,14 +3237,17 @@ export {
   evaluateBoolLogic,
   extractPlaceholders,
   findConcern,
+  flipPairs,
   hashKey,
   interpolateTemplate,
   is,
+  listeners,
   prebuilts_exports as prebuilts,
   registerFlipPair,
   registerListenerLegacy,
   registerSideEffects,
   registerSyncPairsBatch,
+  syncPairs,
   useBufferedField,
   useKeyboardSelect,
   useThrottledField,