@jsenv/navi 0.18.19 → 0.18.21

package/dist/jsenv_navi.js

@@ -630,109 +630,6 @@ const stringifyForDisplay = (
   return String(value);
 };
 
-/**
- * Reactively runs an action whenever the params derived from signals change.
- *
- * @param {object} action - The action to run.
- * @param {Function} deriveActionParamsFromSignals - A function that reads signals and returns
- *   the params to pass to the action. It is re-evaluated automatically whenever a signal it
- *   read changes. Return `false`/`null`/`undefined` to skip running the action.
- * @param {object} [options]
- * @param {number} [options.debounce] - When set, the action is only run once the derived params
- *   have been stable for this many milliseconds. Useful to avoid firing a backend call on every
- *   keystroke: set `debounce: 500` and the request is sent only after the user stops interacting
- *   with the filters for 500 ms.
- *
- *   Example — auto-refresh a result list while the user tweaks filters:
- *   ```js
- *   actionRunEffect(searchAction, () => ({
- *     query: querySignal.value,
- *     page: pageSignal.value,
- *   }), { debounce: 500 });
- *   ```
- *   The action will not fire while the user is actively changing filters; it fires once
- *   they pause for half a second.
- */
-const actionRunEffect = (
-  action,
-  deriveActionParamsFromSignals,
-  { debounce, meta } = {},
-) => {
-  let lastTruthyParams;
-  let actionParamsSignal = computed(() => {
-    const params = deriveActionParamsFromSignals();
-    action.debug(
-      `Derived params for action "${action}": ${stringifyForDisplay(params)}`,
-    );
-    if (!params) {
-      // normalize falsy values to undefined so that any falsy value ends up in the same state of "don't run the action"
-      return undefined;
-    }
-    if (params && typeof params.then === "function") {
-      {
-        console.warn(
-          `actionRunEffect second arg is returning a promise. This is not supported, the function should be sync and return params to give to the action`,
-        );
-      }
-    }
-    if (lastTruthyParams === undefined) {
-      lastTruthyParams = params;
-    }
-    return params;
-  });
-  if (debounce) {
-    actionParamsSignal = debounceSignal(actionParamsSignal, {
-      delay: debounce,
-    });
-  }
-
-  const actionRunnedByThisEffect = action.bindParams(actionParamsSignal, {
-    syncParams: debounce ? actionParamsSignal.flush : undefined,
-    onChange: (actionTarget, actionTargetPrevious, { explicitRunIntent }) => {
-      if (explicitRunIntent) {
-        // The caller already issued an explicit run/rerun/prerun/reset/abort —
-        // don't attempt to also auto-run from the params change to avoid double-runs.
-        action.debug(
-          `"${actionTarget}": explicit run intent detected -> skipping auto-run from params change`,
-        );
-        return;
-      }
-      if (!actionTargetPrevious && actionTarget) {
-        // first run
-        if (!actionTarget.params) {
-          // falsy params, don't run
-          return;
-        }
-        actionTarget.run({ reason: "truthy params first run" });
-        return;
-      }
-
-      if (
-        actionTargetPrevious &&
-        !actionTargetPrevious.isPrerun &&
-        actionTarget
-      ) {
-        // params changed
-        if (!actionTarget.params) {
-          // falsy params, don't run
-          actionTargetPrevious.abort("abortOnFalsyParams");
-          return;
-        }
-        if (compareTwoJsValues(lastTruthyParams, actionTarget.params)) {
-          actionTarget.run({ reason: "params restored to last truthy value" });
-        } else {
-          actionTarget.rerun({ reason: "params modified" });
-        }
-      }
-    },
-    meta,
-  });
-  if (actionParamsSignal.peek()) {
-    actionRunnedByThisEffect.run({ reason: "initial truthy params" });
-  }
-  return actionRunnedByThisEffect;
-};
-
 /**
  * jsenv/navi - createJsValueWeakMap
  *
@@ -1478,6 +1375,7 @@ const createAction = (callback, rootOptions = {}) => {
       keepOldData = false,
       meta = {},
 
+      outputSignal,
       completeSideEffect,
     } = options;
     if (!Object.hasOwn(options, "params")) {
@@ -1896,6 +1794,9 @@ const createAction = (callback, rootOptions = {}) => {
             valueSignal.value = value;
             runningStateSignal.value = COMPLETED;
             const data = dataSignal.value;
+            if (outputSignal) {
+              outputSignal.value = data;
+            }
             onComplete?.(data, action);
             completeSideEffect?.(action);
           });
@@ -2012,6 +1913,9 @@ const createAction = (callback, rootOptions = {}) => {
           if (!keepOldData) {
             valueSignal.value = valueInitial;
           }
+          if (outputSignal) {
+            outputSignal.value = null;
+          }
           isPrerunSignal.value = true;
           runningStateSignal.value = IDLE;
         });
@@ -2386,6 +2290,110 @@ const COMPLETED_ACTION = createAction(() => undefined, {
 });
 getActionPrivateProperties(COMPLETED_ACTION).performRun({});
 
+/**
+ * Reactively runs an action whenever the params derived from signals change.
+ *
+ * @param {object} action - The action to run.
+ * @param {Function} deriveActionParamsFromSignals - A function that reads signals and returns
+ *   the params to pass to the action. It is re-evaluated automatically whenever a signal it
+ *   read changes. Return `false`/`null`/`undefined` to skip running the action.
+ * @param {object} [options]
+ * @param {number} [options.debounce] - When set, the action is only run once the derived params
+ *   have been stable for this many milliseconds. Useful to avoid firing a backend call on every
+ *   keystroke: set `debounce: 500` and the request is sent only after the user stops interacting
+ *   with the filters for 500 ms.
+ *
+ *   Example — auto-refresh a result list while the user tweaks filters:
+ *   ```js
+ *   actionRunEffect(searchAction, () => ({
+ *     query: querySignal.value,
+ *     page: pageSignal.value,
+ *   }), { debounce: 500 });
+ *   ```
+ *   The action will not fire while the user is actively changing filters; it fires once
+ *   they pause for half a second.
+ */
+const actionRunEffect = (
+  action,
+  deriveActionParamsFromSignals,
+  { debounce, meta } = {},
+) => {
+  if (typeof action === "function") action = createAction(action);
+  let lastTruthyParams;
+  let actionParamsSignal = computed(() => {
+    const params = deriveActionParamsFromSignals();
+    action.debug(
+      `Derived params for action "${action}": ${stringifyForDisplay(params)}`,
+    );
+    if (!params) {
+      // normalize falsy values to undefined so that any falsy value ends up in the same state of "don't run the action"
+      return undefined;
+    }
+    if (params && typeof params.then === "function") {
+      {
+        console.warn(
+          `actionRunEffect second arg is returning a promise. This is not supported, the function should be sync and return params to give to the action`,
+        );
+      }
+    }
+    if (lastTruthyParams === undefined) {
+      lastTruthyParams = params;
+    }
+    return params;
+  });
+  if (debounce) {
+    actionParamsSignal = debounceSignal(actionParamsSignal, {
+      delay: debounce,
+    });
+  }
+
+  const actionRunnedByThisEffect = action.bindParams(actionParamsSignal, {
+    syncParams: debounce ? actionParamsSignal.flush : undefined,
+    onChange: (actionTarget, actionTargetPrevious, { explicitRunIntent }) => {
+      if (explicitRunIntent) {
+        // The caller already issued an explicit run/rerun/prerun/reset/abort —
+        // don't attempt to also auto-run from the params change to avoid double-runs.
+        action.debug(
+          `"${actionTarget}": explicit run intent detected -> skipping auto-run from params change`,
+        );
+        return;
+      }
+      if (!actionTargetPrevious && actionTarget) {
+        // first run
+        if (!actionTarget.params) {
+          // falsy params, don't run
+          return;
+        }
+        actionTarget.run({ reason: "truthy params first run" });
+        return;
+      }
+
+      if (
+        actionTargetPrevious &&
+        !actionTargetPrevious.isPrerun &&
+        actionTarget
+      ) {
+        // params changed
+        if (!actionTarget.params) {
+          // falsy params, don't run
+          actionTargetPrevious.abort("abortOnFalsyParams");
+          return;
+        }
+        if (compareTwoJsValues(lastTruthyParams, actionTarget.params)) {
+          actionTarget.run({ reason: "params restored to last truthy value" });
+        } else {
+          actionTarget.rerun({ reason: "params modified" });
+        }
+      }
+    },
+    meta,
+  });
+  if (actionParamsSignal.peek()) {
+    actionRunnedByThisEffect.run({ reason: "initial truthy params" });
+  }
+  return actionRunnedByThisEffect;
+};
+
 const useActionData = (action) => {
   if (!action) {
     return undefined;