slapflow 1.0.2 → 1.2.0

package/dist/index.cjs

@@ -20,14 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BUILTIN_ACTIONS: () => BUILTIN_ACTIONS,
+  BUILTIN_ACTION_NAMES: () => BUILTIN_ACTION_NAMES,
+  BUILTIN_CONDITIONS: () => BUILTIN_CONDITIONS,
+  BUILTIN_CONDITION_NAMES: () => BUILTIN_CONDITION_NAMES,
   PubSub: () => PubSub,
   catchError: () => catchError,
-  createActionsRegistry: () => createActionsRegistry,
-  createConditionsRegistry: () => createConditionsRegistry,
   createFlow: () => createFlow,
   createMemoryTraceSink: () => createMemoryTraceSink,
   createPubSub: () => createPubSub,
   createWS: () => createWS,
+  createWebSocket: () => createWebSocket,
   defineConfig: () => defineConfig,
   defineErrorReporter: () => defineErrorReporter
 });
@@ -36,9 +39,6 @@ module.exports = __toCommonJS(index_exports);
 // src/helpers/config/defineConfig.ts
 var defineConfig = (config) => config;
 
-// src/helpers/trace/cloneData.ts
-var cloneData = (data) => ({ ...data });
-
 // src/helpers/trace/createMemoryTraceSink.ts
 var createMemoryTraceSink = () => {
   const items = [];
@@ -50,22 +50,9 @@ var createMemoryTraceSink = () => {
   };
 };
 
-// src/helpers/errors/slapError.ts
-var slapError = (code, message, extras = {}) => ({ code, message, ...extras });
-
 // src/helpers/errors/defineErrorReporter.ts
 var defineErrorReporter = (handlers) => typeof handlers === "function" ? handlers : handlers.report;
 
-// src/errors.ts
-var SyncAsyncError = class extends Error {
-  slapError;
-  constructor(error) {
-    super(error.message);
-    this.name = "SyncAsyncError";
-    this.slapError = error;
-  }
-};
-
 // src/helpers/ids/createId.ts
 var alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 var idLength = 12;
@@ -87,14 +74,35 @@ var isBusEvent = (event) => {
   return typeof candidate.id === "string" && typeof candidate.topic === "string" && typeof candidate.occurredAt === "number" && typeof candidate.serialized === "string" && "parsed" in candidate && (candidate.origin === void 0 || typeof candidate.origin === "string");
 };
 
+// src/helpers/pubSub/matchesTopic.ts
+var matchesTopic = (topic, pattern) => {
+  if (!pattern.includes("*")) {
+    return topic === pattern;
+  }
+  const topicParts = topic.split(".");
+  const patternParts = pattern.split(".");
+  if (topicParts.length !== patternParts.length) {
+    return false;
+  }
+  return patternParts.every((part, index) => part === "*" || part === topicParts[index]);
+};
+
 // src/helpers/pubSub/serializeError.ts
 var serializeError = (error) => ({
   error: error instanceof Error ? error.message : String(error)
 });
 
-// src/pubSub.ts
+// src/createPubSub.ts
 var createPubSub = (options = {}) => {
   const subscribers = /* @__PURE__ */ new Map();
+  const wildcardSubscribers = /* @__PURE__ */ new Map();
+  const runHandler = (event, handler) => {
+    try {
+      handler(event);
+    } catch (error) {
+      options.onError?.({ type: "subscriber", event, error });
+    }
+  };
   const dispatch = (event) => {
     let dispatchedEvent;
     if (!isBusEvent(event)) {
@@ -108,10 +116,13 @@ var createPubSub = (options = {}) => {
       const handlers = subscribers.get(event.topic);
       if (handlers) {
         for (const handler of [...handlers]) {
-          try {
-            handler(event);
-          } catch (error) {
-            options.onError?.({ type: "subscriber", event, error });
+          runHandler(event, handler);
+        }
+      }
+      for (const [pattern, wildcardHandlers] of wildcardSubscribers) {
+        if (matchesTopic(event.topic, pattern)) {
+          for (const handler of [...wildcardHandlers]) {
+            runHandler(event, handler);
           }
         }
       }
@@ -120,23 +131,24 @@ var createPubSub = (options = {}) => {
     return dispatchedEvent;
   };
   const on = (event, handler) => {
-    const handlers = subscribers.get(event) ?? /* @__PURE__ */ new Set();
-    const listener = handler;
-    handlers.add(listener);
-    subscribers.set(event, handlers);
+    const registry = event.includes("*") ? wildcardSubscribers : subscribers;
+    const handlers = registry.get(event) ?? /* @__PURE__ */ new Set();
+    handlers.add(handler);
+    registry.set(event, handlers);
     return () => off(event, handler);
   };
   const off = (event, handler) => {
+    const registry = event.includes("*") ? wildcardSubscribers : subscribers;
     if (handler) {
-      const handlers = subscribers.get(event);
+      const handlers = registry.get(event);
       if (handlers) {
         handlers.delete(handler);
         if (handlers.size === 0) {
-          subscribers.delete(event);
+          registry.delete(event);
         }
       }
     } else {
-      subscribers.delete(event);
+      registry.delete(event);
     }
   };
   const emit = (topic, payload, emitOptions = {}) => {
@@ -178,6 +190,16 @@ var createPubSub = (options = {}) => {
 };
 var PubSub = createPubSub();
 
+// src/helpers/errors/syncAsyncError.ts
+var SyncAsyncError = class extends Error {
+  slapError;
+  constructor(error) {
+    super(error.message);
+    this.name = "SyncAsyncError";
+    this.slapError = error;
+  }
+};
+
 // src/helpers/actions/coreDelay.ts
 var coreDelay = async ({
   props,
@@ -214,10 +236,7 @@ var coreEmit = ({
 };
 
 // src/helpers/actions/coreFail.ts
-var coreFail = ({
-  props,
-  runtime
-}) => runtime.fail(String(props.reason ?? "failed"), props.data);
+var coreFail = ({ props, runtime }) => runtime.fail(String(props.reason ?? "failed"), props.data);
 
 // src/helpers/retry/getRetryDelay.ts
 var getRetryDelay = (attempt, options) => {
@@ -424,10 +443,7 @@ var corePatch = ({
 };
 
 // src/helpers/actions/coreSet.ts
-var coreSet = ({
-  props,
-  runtime
-}) => {
+var coreSet = ({ props, runtime }) => {
   const path = props.path;
   if (typeof path === "string") {
     runtime.set(path, props.value);
@@ -448,13 +464,10 @@ var coreSetData = ({
 };
 
 // src/helpers/actions/coreStop.ts
-var coreStop = ({
-  props,
-  runtime
-}) => runtime.stop(String(props.reason ?? "stopped"));
+var coreStop = ({ props, runtime }) => runtime.stop(String(props.reason ?? "stopped"));
 
-// src/registry/actions.ts
-var createActionsRegistry = () => /* @__PURE__ */ new Map([
+// src/helpers/actions/index.ts
+var BUILTIN_ACTIONS = [
   ["core.noop", coreNoop],
   ["core.stop", coreStop],
   ["core.fail", coreFail],
@@ -468,7 +481,8 @@ var createActionsRegistry = () => /* @__PURE__ */ new Map([
   ["core.emit", coreEmit],
   ["core.patch", corePatch],
   ["core.delay", coreDelay]
-]);
+];
+var BUILTIN_ACTION_NAMES = new Set(BUILTIN_ACTIONS.map(([name]) => name));
 
 // src/helpers/conditions/changedCondition.ts
 var changedCondition = (_args, current, previous) => !Object.is(current, previous);
@@ -562,8 +576,8 @@ var typeIsCondition = (_args, value, expected) => {
   return expected === "string" || expected === "number" || expected === "boolean" ? typeof value === expected : false;
 };
 
-// src/registry/conditions.ts
-var createConditionsRegistry = () => /* @__PURE__ */ new Map([
+// src/helpers/conditions/index.ts
+var BUILTIN_CONDITIONS = [
   ["eq", eqCondition],
   ["neq", neqCondition],
   ["gt", gtCondition],
@@ -580,7 +594,8 @@ var createConditionsRegistry = () => /* @__PURE__ */ new Map([
   ["typeIs", typeIsCondition],
   ["changed", changedCondition],
   ["cooldownReady", cooldownReadyCondition]
-]);
+];
+var BUILTIN_CONDITION_NAMES = new Set(BUILTIN_CONDITIONS.map(([name]) => name));
 
 // src/helpers/runner/applyResult.ts
 var applyResult = (result, state, mergeData) => {
@@ -594,6 +609,9 @@ var applyResult = (result, state, mergeData) => {
   state.events.push(...result.events);
 };
 
+// src/helpers/errors/slapError.ts
+var slapError = (code, message, extras = {}) => ({ code, message, ...extras });
+
 // src/helpers/path/resolveValue.ts
 var import_objwalk3 = require("objwalk");
 
@@ -1032,7 +1050,7 @@ var executeNext = (item, depth, state, environment) => {
   const id = typeof item === "string" ? item : item.strategy;
   if (typeof item !== "string" && item.when) {
     const runtime = createRuntime(state);
-    const condition = evaluateCondition(item.when, environment.conditionsRegistry, { ...state, runtime, strategy: id });
+    const condition = evaluateCondition(item.when, environment.registry.conditions, { ...state, runtime, strategy: id });
     if (!condition.ok) {
       return { status: "failed", error: condition.error, patches: [], events: [] };
     }
@@ -1284,6 +1302,9 @@ var normalizeActionResult = (raw) => {
   };
 };
 
+// src/helpers/trace/cloneData.ts
+var cloneData = (data) => ({ ...data });
+
 // src/helpers/runner/pushTrace.ts
 var pushTrace = (state, step, depth, strategyId, strategy, status, props, dataBefore, startedAt, reason) => {
   state.traceSink?.push({
@@ -1466,7 +1487,7 @@ var executeStrategy = (id, extraProps, depth, state, environment) => {
       events: []
     };
   }
-  const action = environment.actionsRegistry.get(strategy.fn);
+  const action = environment.registry.actions.get(strategy.fn);
   if (!action) {
     return {
       status: "failed",
@@ -1521,7 +1542,7 @@ var executeStrategy = (id, extraProps, depth, state, environment) => {
   const dataBefore = cloneData(state.data);
   const traceStep = state.stepCounter.current + 1;
   const startedAt = Date.now();
-  const condition = evaluateCondition(strategy.when, environment.conditionsRegistry, {
+  const condition = evaluateCondition(strategy.when, environment.registry.conditions, {
     ...state,
     runtime,
     strategy: id
@@ -1833,6 +1854,17 @@ var validateCondition = (expression, strategy, path, conditionsRegistry, errors)
     return;
   }
   const [operator, ...args] = expression;
+  if (operator === "guard") {
+    if (args.length !== 1 || typeof args[0] !== "string") {
+      errors.push({
+        code: "CONDITION_INVALID",
+        message: "Guard reference must be a single string name",
+        strategy,
+        path
+      });
+    }
+    return;
+  }
   if (operator === "and" || operator === "or") {
     args.forEach((arg, index) => validateCondition(arg, strategy, `${path}.${index + 1}`, conditionsRegistry, errors));
     return;
@@ -1878,6 +1910,82 @@ var validateNextList = (config, list, path, strategy, conditionsRegistry, errors
   });
 };
 
+// src/helpers/validation/resolveGuards.ts
+var isGuardRef = (expression) => Array.isArray(expression) && expression.length === 2 && expression[0] === "guard" && typeof expression[1] === "string";
+var resolveRef = (config, name, visiting, path) => {
+  if (visiting.includes(name)) {
+    return {
+      issue: { code: "GUARD_CYCLE", message: `Guard "${name}" is part of a reference cycle`, guard: name, path }
+    };
+  }
+  const guard = config.guards?.[name];
+  if (guard === void 0) {
+    return { issue: { code: "GUARD_NOT_FOUND", message: `Guard "${name}" is not defined`, guard: name, path } };
+  }
+  return resolveExpression(config, guard, [...visiting, name], path);
+};
+var resolveExpression = (config, expression, visiting, path) => {
+  if (isGuardRef(expression)) {
+    return resolveRef(config, expression[1], visiting, path);
+  }
+  if (!Array.isArray(expression) || typeof expression[0] !== "string") {
+    return { expression };
+  }
+  const [operator, ...args] = expression;
+  if (operator === "and" || operator === "or") {
+    const resolved = [];
+    for (let index = 0; index < args.length; index += 1) {
+      const result = resolveExpression(config, args[index], visiting, `${path}.${index + 1}`);
+      if (result.issue) {
+        return result;
+      }
+      resolved.push(result.expression);
+    }
+    return { expression: [operator, ...resolved] };
+  }
+  if (operator === "not") {
+    const result = resolveExpression(config, args[0], visiting, `${path}.1`);
+    if (result.issue) {
+      return result;
+    }
+    return { expression: ["not", result.expression] };
+  }
+  return { expression };
+};
+var resolveGuards = (config) => {
+  const issues = [];
+  const resolveWhen = (when, path) => {
+    if (when === void 0) {
+      return void 0;
+    }
+    const result = resolveExpression(config, when, [], path);
+    if (result.issue) {
+      issues.push(result.issue);
+      return when;
+    }
+    return result.expression;
+  };
+  const resolveNext = (next, prefix) => next.map((item, index) => {
+    if (typeof item === "string" || !item || typeof item !== "object" || item.when === void 0) {
+      return item;
+    }
+    const target = item;
+    const when = resolveWhen(target.when, `${prefix}.${index}.when`);
+    return when === void 0 ? item : { ...target, when };
+  });
+  const strategies = {};
+  for (const [id, strategy] of Object.entries(config.strategies)) {
+    const when = strategy.when === void 0 ? void 0 : resolveWhen(strategy.when, `${id}.when`);
+    strategies[id] = {
+      ...strategy,
+      ...when !== void 0 ? { when } : {},
+      ...strategy.then ? { then: resolveNext(strategy.then, `${id}.then`) } : {},
+      ...strategy.catch ? { catch: resolveNext(strategy.catch, `${id}.catch`) } : {}
+    };
+  }
+  return { config: { ...config, strategies }, issues };
+};
+
 // src/helpers/validation/validateConfig.ts
 var validateConfig = (config, actionsRegistry, conditionsRegistry) => {
   const errors = [];
@@ -1896,6 +2004,22 @@ var validateConfig = (config, actionsRegistry, conditionsRegistry) => {
       warnings
     };
   }
+  if (config.guards !== void 0) {
+    if (typeof config.guards !== "object" || Array.isArray(config.guards)) {
+      errors.push({ code: "GUARD_INVALID", message: "Config guards must be an object", path: "guards" });
+    } else {
+      for (const [name, expression] of Object.entries(config.guards)) {
+        validateCondition(expression, name, `guards.${name}`, conditionsRegistry, errors);
+      }
+    }
+  }
+  for (const issue of resolveGuards(config).issues) {
+    errors.push({
+      code: issue.code,
+      message: issue.message,
+      ...issue.path ? { path: issue.path } : {}
+    });
+  }
   for (const [id, strategy] of Object.entries(config.strategies ?? {})) {
     if (!strategy || typeof strategy !== "object") {
       errors.push({ code: "STRATEGY_INVALID", message: "Strategy must be an object", strategy: id });
@@ -2015,10 +2139,10 @@ var createRunCancellation = (source) => {
   };
 };
 
-// src/helpers/runner/createRunner.ts
+// src/createRunner.ts
 var createRunner = (options = {}) => {
-  const actionsRegistry = createActionsRegistry();
-  const conditionsRegistry = createConditionsRegistry();
+  const actionsRegistry = new Map(BUILTIN_ACTIONS);
+  const conditionsRegistry = new Map(BUILTIN_CONDITIONS);
   const configRef = {};
   const timeout = options.timeout ?? options.timeoutMs;
   const runnerOptions = timeout === void 0 ? options : { ...options, timeout };
@@ -2028,19 +2152,24 @@ var createRunner = (options = {}) => {
     console.warn("timeoutMs is deprecated; use timeout. It will be removed in a future major release.");
   }
   const environment = {
-    actionsRegistry,
-    conditionsRegistry,
+    registry: { actions: actionsRegistry, conditions: conditionsRegistry },
     configRef,
     options: runnerOptions,
     mergeData
   };
   const registerAction = (name, action) => {
+    if (BUILTIN_ACTION_NAMES.has(name)) {
+      throw new Error(`Cannot override built-in action "${name}"`);
+    }
     actionsRegistry.set(name, action);
   };
   const registerActions = (items) => {
     Object.entries(items).forEach(([name, action]) => registerAction(name, action));
   };
   const registerCondition = (name, condition) => {
+    if (BUILTIN_CONDITION_NAMES.has(name)) {
+      throw new Error(`Cannot override built-in condition "${name}"`);
+    }
     conditionsRegistry.set(name, condition);
   };
   const registerConditions = (items) => {
@@ -2051,7 +2180,7 @@ var createRunner = (options = {}) => {
     return { ...result, warnings: [...result.warnings, ...runnerLimitWarnings(runnerOptions)] };
   };
   const loadConfig = (nextConfig) => {
-    configRef.current = nextConfig;
+    configRef.current = resolveGuards(nextConfig).config;
     return validateConfig2(nextConfig);
   };
   const runInternal = (entrypoint, context, input, sync, runOptions) => {
@@ -2137,7 +2266,7 @@ var parseDomBinding = (binding, prefix) => {
   return separator <= 0 || separator === source.length - 1 ? void 0 : { selector: source.slice(0, separator), eventType: source.slice(separator + 1) };
 };
 
-// src/flow.ts
+// src/createFlow.ts
 var busBindingPrefix = "[bus] ";
 var domBindingPrefix = "[dom] ";
 var defaultMaxQueueSize = 50;
@@ -2378,10 +2507,11 @@ var createFlow = (definition, options) => {
   return { runner, start, stop };
 };
 
-// src/ws.ts
+// src/createWS.ts
 var openState = 1;
 var maxSeenEvents = 1e3;
 var createWS = (options) => {
+  console.warn("[slapflow] createWS is deprecated and will be removed soon. Use createWebSocket instead.");
   const inboundTopics = new Set(options.inboundTopics ?? []);
   const outboundTopics = new Set(options.outboundTopics ?? []);
   const seenEventIds = /* @__PURE__ */ new Set();
@@ -2393,6 +2523,14 @@ var createWS = (options) => {
   let started = false;
   let currentStatus = "idle";
   const diagnosticsBus = options.bus;
+  const isInboundTopic = (topic) => {
+    for (const pattern of inboundTopics) {
+      if (matchesTopic(topic, pattern)) {
+        return true;
+      }
+    }
+    return false;
+  };
   const emitDiagnostic = (topic, payload) => {
     diagnosticsBus.emit(topic, payload, {
       ...options.origin ? { origin: options.origin } : {}
@@ -2470,7 +2608,7 @@ var createWS = (options) => {
           if (typeof data === "string") {
             try {
               const busEvent = JSON.parse(data);
-              if (busEvent.topic && inboundTopics.has(busEvent.topic)) {
+              if (busEvent.topic && isInboundTopic(busEvent.topic)) {
                 if (busEvent.id) {
                   rememberEvent(busEvent.id);
                 }
@@ -2537,7 +2675,117 @@ var createWS = (options) => {
   return { start, stop, reconnect, status: () => currentStatus };
 };
 
-// src/catchError.ts
+// src/createWebSocket.ts
+var createWebSocket = (options) => {
+  let socket;
+  let retryTimer;
+  let retryAttempt = 0;
+  let started = false;
+  let currentStatus = "idle";
+  const emitSocketEvent = (topic, payload) => {
+    options.bus.dispatch({
+      id: createId(),
+      topic,
+      occurredAt: Date.now(),
+      ...options.origin ? { origin: options.origin } : {},
+      parsed: payload,
+      serialized: JSON.stringify(payload)
+    });
+  };
+  const scheduleRetry = () => {
+    const delay = getRetryDelay(retryAttempt, options.reconnect ?? {});
+    const attempt = retryAttempt + 1;
+    currentStatus = "reconnecting";
+    retryAttempt = attempt;
+    retryTimer = setTimeout(() => {
+      retryTimer = void 0;
+      connect();
+    }, delay);
+  };
+  const connect = () => {
+    if (!started || socket) {
+      return;
+    }
+    currentStatus = "connecting";
+    try {
+      const current = new WebSocket(options.url, options.protocols ?? []);
+      socket = current;
+      current.addEventListener("open", () => {
+        if (socket === current) {
+          retryAttempt = 0;
+          currentStatus = "connected";
+          emitSocketEvent("open", { url: options.url });
+        }
+      });
+      current.addEventListener("message", (event) => {
+        if (socket !== current) {
+          return;
+        }
+        let parsed = event.data;
+        if (typeof parsed === "string") {
+          try {
+            parsed = JSON.parse(parsed);
+          } catch {
+            parsed = event.data;
+          }
+        }
+        emitSocketEvent("message", parsed);
+      });
+      current.addEventListener("close", (event) => {
+        if (socket !== current) {
+          return;
+        }
+        socket = void 0;
+        emitSocketEvent("close", { code: event.code, reason: event.reason });
+        if (started) {
+          scheduleRetry();
+        }
+      });
+      current.addEventListener("error", (event) => {
+        emitSocketEvent("error", { error: event });
+      });
+    } catch (error) {
+      socket = void 0;
+      emitSocketEvent("error", { error });
+      if (started) {
+        scheduleRetry();
+      }
+    }
+  };
+  const start = () => {
+    if (!started) {
+      started = true;
+      connect();
+    }
+  };
+  const stop = () => {
+    started = false;
+    if (retryTimer) {
+      clearTimeout(retryTimer);
+    }
+    retryTimer = void 0;
+    const current = socket;
+    socket = void 0;
+    current?.close();
+    currentStatus = "stopped";
+  };
+  const reconnect = () => {
+    if (!started) {
+      return;
+    }
+    if (retryTimer) {
+      clearTimeout(retryTimer);
+      retryTimer = void 0;
+    }
+    const current = socket;
+    socket = void 0;
+    current?.close();
+    connect();
+  };
+  return { start, stop, reconnect, status: () => currentStatus };
+};
+
+// src/helpers/catchError.ts
 var catchError = (callback) => new Promise((resolve, reject) => {
   try {
     resolve(callback());
@@ -2547,14 +2795,17 @@ var catchError = (callback) => new Promise((resolve, reject) => {
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BUILTIN_ACTIONS,
+  BUILTIN_ACTION_NAMES,
+  BUILTIN_CONDITIONS,
+  BUILTIN_CONDITION_NAMES,
   PubSub,
   catchError,
-  createActionsRegistry,
-  createConditionsRegistry,
   createFlow,
   createMemoryTraceSink,
   createPubSub,
   createWS,
+  createWebSocket,
   defineConfig,
   defineErrorReporter
 });