jssm 5.162.5 → 5.162.7

package/dist/deno/jssm_types.d.ts

@@ -883,6 +883,10 @@ type AfterHook<mDT> = {
     from: string;
     handler: HookHandler<mDT>;
 };
+type AfterAnyHook<mDT> = {
+    kind: 'after any';
+    handler: HookHandler<mDT>;
+};
 type PostBasicHookDescription<mDT> = {
     kind: 'post hook';
     from: string;
@@ -956,12 +960,12 @@ type PostEverythingHook<mDT> = {
  *
  *  Pre-transition variants (`'hook'`, `'named'`, `'standard transition'`,
  *  `'main transition'`, `'forced transition'`, `'any transition'`,
- *  `'global action'`, `'any action'`, `'entry'`, `'exit'`, `'after'`)
- *  may return a falsy value to veto a transition.  Post-transition
+ *  `'global action'`, `'any action'`, `'entry'`, `'exit'`, `'after'`,
+ *  `'after any'`) may return a falsy value to veto a transition.  Post-transition
  *  variants (`'post *'`) cannot veto and are invoked only after a
  *  successful transition.
  */
-type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | AfterHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT> | PreEverythingHook<mDT> | EverythingHook<mDT> | PrePostEverythingHook<mDT> | PostEverythingHook<mDT>;
+type HookDescription<mDT> = BasicHookDescription<mDT> | HookDescriptionWithAction<mDT> | GlobalActionHook<mDT> | AnyActionHook<mDT> | StandardTransitionHook<mDT> | MainTransitionHook<mDT> | ForcedTransitionHook<mDT> | AnyTransitionHook<mDT> | EntryHook<mDT> | ExitHook<mDT> | AfterHook<mDT> | AfterAnyHook<mDT> | PostBasicHookDescription<mDT> | PostHookDescriptionWithAction<mDT> | PostGlobalActionHook<mDT> | PostAnyActionHook<mDT> | PostStandardTransitionHook<mDT> | PostMainTransitionHook<mDT> | PostForcedTransitionHook<mDT> | PostAnyTransitionHook<mDT> | PostEntryHook<mDT> | PostExitHook<mDT> | PreEverythingHook<mDT> | EverythingHook<mDT> | PrePostEverythingHook<mDT> | PostEverythingHook<mDT>;
 /**
  *  Whether an observational hook runs in the pre-transition phase (where it
  *  may veto/mutate the transition) or the post-transition phase (a pure
@@ -1235,7 +1239,9 @@ type JssmErrorEventDetail = {
 /**
  *  Detail payload fired with a `data-change` event.  Fires whenever the
  *  machine's data payload is replaced.  `old_data` is the value before the
- *  change; `new_data` is the value after.
+ *  change; `new_data` is the value after.  `cause` names the API family that
+ *  performed the replacement: a data-bearing `transition`, an `override`, or
+ *  a direct `set_data` call.
  */
 type JssmDataChangeEventDetail<mDT> = {
     from?: StateType;
@@ -1243,7 +1249,7 @@ type JssmDataChangeEventDetail<mDT> = {
     action?: StateType;
     old_data: mDT;
     new_data: mDT;
-    cause: 'transition' | 'override';
+    cause: 'transition' | 'override' | 'set_data';
 };
 /**
  *  Detail payload fired with an `override` event.  Distinguishes a forced

package/dist/fence/fence.js

@@ -21912,6 +21912,14 @@ function nth_matching_loc(tree, predicate, n) {
  *
  */
 function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
+    // the explicit quotation syntax lets `""` through the grammar; a nameless
+    // state can never be addressed, so reject at edge assembly (fsl#653)
+    if (from === '') {
+        throw new JssmError(undefined, 'A state name may not be the empty string (transition source)');
+    }
+    if (to === '') {
+        throw new JssmError(undefined, 'A state name may not be the empty string (transition target)');
+    }
     const kind = isRight
         ? arrow_right_kind(this_se.kind)
         : arrow_left_kind(this_se.kind), 
@@ -21951,6 +21959,11 @@ function makeTransition(this_se, from, to, isRight, _wasList, _wasIndex) {
     if (this_se[probability] != null) {
         edge.probability = this_se[probability];
     }
+    // same rejection for `''` action quotation — an action nobody can name
+    // can never be dispatched (fsl#653)
+    if (edge.action === '') {
+        throw new JssmError(undefined, 'An action name may not be the empty string');
+    }
     return edge;
 }
 /*********
@@ -23790,7 +23803,7 @@ function fslSemanticSpans(text) {
  *  Useful for runtime diagnostics and for embedding in serialized machine
  *  snapshots so that deserializers can detect version-skew.
  */
-const version = "5.162.5";
+const version = "5.162.7";
 
 /**
  *  The FSL Markdown fence convention parser — pure, host-agnostic logic that
@@ -23970,6 +23983,7 @@ const hook_required_fields = {
     'entry': ['to'],
     'exit': ['from'],
     'after': ['from'],
+    'after any': [],
     'post hook': ['from', 'to'],
     'post named': ['from', 'to', 'action'],
     'post global action': ['action'],
@@ -24338,6 +24352,7 @@ class Machine {
         this._entry_hooks = new Map();
         this._exit_hooks = new Map();
         this._after_hooks = new Map();
+        this._after_any_hook = undefined;
         this._global_action_hooks = new Map();
         this._any_action_hook = undefined;
         this._standard_transition_hook = undefined;
@@ -24852,6 +24867,53 @@ class Machine {
     data() {
         return structuredClone(this._data);
     }
+    /*********
+     *
+     *  Replace the machine's data in place, without a transition.  This is the
+     *  practical way to assign any value — including `undefined`, `null`, or
+     *  `false` — outside a hook's complex return, closing the gap where an
+     *  `undefined` assignment had no direct API (StoneCypher/fsl#1264).  Fires
+     *  a `data-change` event with cause `'set_data'` when the value actually
+     *  changes; unlike {@link override} it requires no `allows_override`
+     *  config, because it never moves the state.
+     *
+     *  ```typescript
+     *  import * as jssm from 'jssm';
+     *
+     *  const lswitch = jssm.from('on <=> off;', {data: 1});
+     *  console.log( lswitch.data() );              // 1
+     *
+     *  lswitch.set_data(2);
+     *  console.log( lswitch.data() );              // 2
+     *
+     *  lswitch.set_data(undefined);
+     *  console.log( lswitch.data() );              // undefined
+     *  ```
+     *
+     *  @typeParam mDT The type of the machine data member; usually omitted
+     *
+     *  @param newData The value to install as the machine's data.
+     *
+     *  @returns The machine, for chaining.
+     *
+     *  @see Machine.data
+     *  @see override
+     *
+     */
+    set_data(newData) {
+        const oldData = this._data;
+        this._data = newData;
+        if (oldData !== newData) {
+            this._fire('data-change', {
+                from: this._state,
+                to: this._state,
+                old_data: oldData,
+                new_data: newData,
+                cause: 'set_data'
+            });
+        }
+        return this;
+    }
     /**
      *  The machine's current data by REFERENCE — no clone.  The public
      *  {@link Machine.data} contract is a deep clone per call (a mutation
@@ -26551,11 +26613,14 @@ class Machine {
         }
         for (const field of hook_spatial_fields) {
             const needed = required.includes(field);
-            const present = HookDesc[field] !== undefined;
-            if (needed && !present) {
-                throw new JssmError(this, `${HookDesc.kind} hook requires '${field}'`);
-            }
-            if (!needed && present) {
+            const value = HookDesc[field];
+            // a required spatial field must be a usable key: a non-empty string.
+            // presence alone isn't enough — `action: false` or `from: ''` would
+            // register a hook nothing can ever fire (fsl#653, fsl#659)
+            if (needed && ((typeof value !== 'string') || (value === ''))) {
+                throw new JssmError(this, `${HookDesc.kind} hook requires '${field}' to be a non-empty string`);
+            }
+            if (!needed && (value !== undefined)) {
                 throw new JssmError(this, `${HookDesc.kind} hook does not take '${field}'`);
             }
         }
@@ -26629,6 +26694,11 @@ class Machine {
                 this._has_hooks = true;
                 this._has_after_hooks = true;
                 break;
+            case 'after any':
+                this._after_any_hook = HookDesc.handler;
+                this._has_hooks = true;
+                this._has_after_hooks = true;
+                break;
             case 'post hook': {
                 // Numeric pair key; same rationale as 'hook' (#729).
                 this._post_hooks.set(pair_key(this._state_interner.intern(HookDesc.from), this._state_interner.intern(HookDesc.to)), HookDesc.handler);
@@ -26800,6 +26870,12 @@ class Machine {
             case 'after':
                 removed = this._after_hooks.delete(HookDesc.from);
                 break;
+            case 'after any':
+                if (this._after_any_hook !== undefined) {
+                    this._after_any_hook = undefined;
+                    removed = true;
+                }
+                break;
             case 'post hook': {
                 const fid = this._state_interner.id_of(HookDesc.from), tid = this._state_interner.id_of(HookDesc.to);
                 removed = (fid !== undefined) && (tid !== undefined) && this._post_hooks.delete(pair_key(fid, tid));
@@ -27017,6 +27093,36 @@ class Machine {
         this.set_hook({ kind: 'after', from, handler });
         return this;
     }
+    /** Register a hook that fires when ANY state's `after` timer elapses — the
+     *  whole-machine companion to {@link hook_after}, mirroring how
+     *  {@link hook_any_transition} companions {@link hook}.  When the elapsing
+     *  state also has a specific {@link hook_after}, the specific hook fires
+     *  first and this one fires second; a specific after hook firing always
+     *  implies the any-after hook fires too (StoneCypher/fsl#1299).  Like
+     *  `hook_after` it is informational — its outcome cannot reject the timed
+     *  transition — and it does NOT fire on ordinary dispatch.
+     *  @param handler - Callback invoked whenever any `after` timer fires, just
+     *                   before the timed transition is taken.
+     *  @returns `this` for chaining.
+     *
+     *  @example
+     *    const m = sm`a after 1000 -> b; a -> c; c -> a;`;
+     *    let calls = 0;
+     *    m.hook_after_any(() => { calls += 1; });
+     *    m.go('c');
+     *    m.go('a');
+     *    // ordinary dispatch never fires it; only a timer elapsing does:
+     *    calls;  // => 0
+     *    m.clear_state_timeout();
+     *
+     *  @see hook_after
+     *  @see hook_any_transition
+     *  @see set_state_timeout
+     */
+    hook_after_any(handler) {
+        this.set_hook({ kind: 'after any', handler });
+        return this;
+    }
     /** Post-transition hook on a specific edge.  Fires after the transition
      *  from `from` to `to` has completed.  Cannot block the transition.
      *  @param from    - Source state name.
@@ -27243,7 +27349,13 @@ class Machine {
     }
     /*********
      *
-     *  Replace the current state and data with no regard to the graph.
+     *  Replace the current state — and, when a data argument is provided, the
+     *  data — with no regard to the graph.
+     *
+     *  The data argument is arity-detected: omitting it preserves the current
+     *  data, while explicitly passing `undefined` really sets the data to
+     *  `undefined` (StoneCypher/fsl#1264).  Before 5.163 an omitted data
+     *  argument silently cleared the data.
      *
      *  ```typescript
      *  import { sm } from 'jssm';
@@ -27259,22 +27371,37 @@ class Machine {
      *  console.log( machine.state() );    // 'a'
      *  ```
      *
+     *  @param newState The state to teleport to; must exist in the graph.
+     *
+     *  @param newData Replacement data.  Omit to keep the current data; pass
+     *  `undefined` explicitly to clear it.
+     *
+     *  @throws {JssmError} If the machine's config does not set
+     *  `allows_override: true`, or if `newState` does not exist.
+     *
+     *  @see set_data
+     *
      */
     override(newState, newData) {
+        // arity, not undefined-comparison: an omitted argument preserves the
+        // data, an explicit `undefined` clears it (StoneCypher/fsl#1264)
+        const dataProvided = arguments.length >= 2;
         if (this.allows_override) {
             if (this._states.has(newState)) {
                 const fromState = this._state;
                 const oldData = this._data;
                 this._state = newState;
                 this._state_id = this._state_interner.intern(newState);
-                this._data = newData;
+                if (dataProvided) {
+                    this._data = newData;
+                }
                 this._fire('override', {
                     from: fromState,
                     to: newState,
                     old_data: oldData,
-                    new_data: newData
+                    new_data: this._data
                 });
-                if (oldData !== newData) {
+                if (dataProvided && (oldData !== newData)) {
                     this._fire('data-change', {
                         from: fromState,
                         to: newState,
@@ -27482,13 +27609,20 @@ class Machine {
      *  `newStateOrAction` is an action name and the target state is looked up
      *  via the current action edge.
      *
+     *  @param dataProvided `true` when the caller explicitly supplied a data
+     *  argument — even an explicitly-`undefined` one, which commits `undefined`
+     *  as the new data (StoneCypher/fsl#1264).  When `false` the current data
+     *  is preserved.  The public wrappers derive this from call arity; the
+     *  default reproduces the old `!== undefined` inference for any direct
+     *  callers.
+     *
      *  @returns `true` if the transition was valid and every hook passed;
      *  `false` if the transition was invalid or any hook rejected.
      *
      *  @internal
      *
      */
-    transition_impl(newStateOrAction, newData, wasForced, wasAction) {
+    transition_impl(newStateOrAction, newData, wasForced, wasAction, dataProvided = newData !== undefined) {
         let valid = false, trans_type, newState, newStateId = NaN, actionId = NaN, fromAction = undefined;
         if (wasForced) {
             // numeric inline of valid_force_transition: any existing edge
@@ -27753,7 +27887,7 @@ class Machine {
                 if (data_changed) {
                     this._data = hook_args.data;
                 }
-                else if (newData !== undefined) {
+                else if (dataProvided) {
                     this._data = newData;
                 }
                 // success fallthrough to posthooks; intentionally no return here
@@ -27766,9 +27900,9 @@ class Machine {
                 }
                 this._state = newState;
                 this._state_id = newStateId;
-                // TODO known bug: this gives no way to set data to undefined
-                //   see https://github.com/StoneCypher/fsl/issues/1264
-                if (newData !== undefined) {
+                // provision is detected by caller arity, so an explicit `undefined`
+                // commits while an omitted argument preserves (StoneCypher/fsl#1264)
+                if (dataProvided) {
                     this._data = newData;
                 }
                 // success fallthrough to posthooks; intentionally no return here
@@ -28081,7 +28215,9 @@ class Machine {
      *
      */
     action(actionName, newData) {
-        return this.transition_impl(actionName, newData, false, true);
+        // arity, not undefined-comparison: an explicit `undefined` is a real
+        // data assignment (StoneCypher/fsl#1264)
+        return this.transition_impl(actionName, newData, false, true, arguments.length >= 2);
     }
     /********
      *
@@ -28345,6 +28481,7 @@ class Machine {
         push_global(this._main_transition_hook, 'main transition', 'pre');
         push_global(this._forced_transition_hook, 'forced transition', 'pre');
         push_global(this._any_transition_hook, 'any transition', 'pre');
+        push_global(this._after_any_hook, 'after any', 'pre');
         push_global(this._pre_everything_hook, 'pre everything', 'pre');
         push_global(this._everything_hook, 'everything', 'pre');
         // post-phase, edge- and state-keyed tables
@@ -28859,7 +28996,7 @@ class Machine {
      *
      */
     do(actionName, newData) {
-        return this.transition_impl(actionName, newData, false, true);
+        return this.transition_impl(actionName, newData, false, true, arguments.length >= 2);
     }
     /********
      *
@@ -28893,7 +29030,7 @@ class Machine {
      *
      */
     transition(newState, newData) {
-        return this.transition_impl(newState, newData, false, false);
+        return this.transition_impl(newState, newData, false, false, arguments.length >= 2);
     }
     /********
      *
@@ -28917,7 +29054,7 @@ class Machine {
      *
      */
     go(newState, newData) {
-        return this.transition_impl(newState, newData, false, false);
+        return this.transition_impl(newState, newData, false, false, arguments.length >= 2);
     }
     /********
      *
@@ -28945,7 +29082,7 @@ class Machine {
      *
      */
     force_transition(newState, newData) {
-        return this.transition_impl(newState, newData, true, false);
+        return this.transition_impl(newState, newData, true, false, arguments.length >= 2);
     }
     /** Get the edge index for an action from the current state.
      *  Interned dispatch: resolves via the numeric (action, from) index —
@@ -29058,6 +29195,11 @@ class Machine {
                 if (ah !== undefined) {
                     ah({ data: this._data, next_data: this._data });
                 }
+                // a specific after hook firing implies the any-after hook fires too,
+                // afterward; and it also fires alone (StoneCypher/fsl#1299)
+                if (this._after_any_hook !== undefined) {
+                    this._after_any_hook({ data: this._data, next_data: this._data });
+                }
             }
             this._fire('timeout', { from: from_state, to: next_state, after_time });
             this.go(next_state);