jssm 5.133.0 → 5.134.0

package/README.md

@@ -18,10 +18,10 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.133.0 at 5/27/2026, 9:02:28 PM
+* Generated for version 5.134.0 at 5/27/2026, 10:16:05 PM
 
 -->
-# jssm 5.133.0
+# jssm 5.134.0
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -281,7 +281,7 @@ That decision shows up everywhere downstream:
   or run `npm run benny` against your own machine.
 
 - **More thoroughly tested than any other JavaScript state-machine
-  library.**  6,157 tests at 100.0% line coverage
+  library.**  6,220 tests at 100.0% line coverage
   ([report](https://coveralls.io/github/StoneCypher/jssm)), plus
   fuzz testing via `fast-check`, with parser test data across ten natural
   languages and Emoji.
@@ -414,11 +414,11 @@ If your contribution is missing here, please open an issue.
 
 <br/>
 
-***6,157 tests***, run 56,944 times.
+***6,220 tests***, run 57,007 times.
 
-- 5,644 specs with 100.0% coverage
-- 513 fuzz tests with 4.3% coverage
-- 4,415 TypeScript lines - 1.4 tests per line, 12.9 generated tests per line
+- 5,707 specs with 100.0% coverage
+- 513 fuzz tests with 4.0% coverage
+- 4,856 TypeScript lines - 1.3 tests per line, 11.7 generated tests per line
 
 [![Actions Status](https://github.com/StoneCypher/jssm/workflows/Node%20CI/badge.svg)](https://github.com/StoneCypher/jssm/actions)
 [![NPM version](https://img.shields.io/npm/v/jssm.svg)](https://www.npmjs.com/package/jssm)

package/dist/cdn/viz.js

@@ -21352,7 +21352,7 @@ var constants = /*#__PURE__*/Object.freeze({
  *  Useful for runtime diagnostics and for embedding in serialized machine
  *  snapshots so that deserializers can detect version-skew.
  */
-const version = "5.133.0";
+const version = "5.134.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -21646,6 +21646,8 @@ class Machine {
         this._timeout_target = undefined;
         this._timeout_target_time = undefined;
         this._after_mapping = new Map();
+        this._event_handlers = new Map();
+        this._firing_error = false;
         // consolidate the state declarations
         if (state_declaration) {
             state_declaration.map((state_decl) => {
@@ -22971,6 +22973,141 @@ class Machine {
     has_completes() {
         return this.states().some((x) => this.state_is_complete(x));
     }
+    on(name, filterOrFn, maybeFn) {
+        return this._subscribe(name, filterOrFn, maybeFn, false);
+    }
+    once(name, filterOrFn, maybeFn) {
+        return this._subscribe(name, filterOrFn, maybeFn, true);
+    }
+    /**
+     *  Remove a previously-registered event handler.  Match is by reference —
+     *  the same function value passed to {@link Machine.on} or
+     *  {@link Machine.once}.  Returns `true` if a subscription was found and
+     *  removed, `false` otherwise.
+     *
+     *  ```typescript
+     *  const fn = (e: any) => console.log(e);
+     *  m.on('transition', fn);
+     *  m.off('transition', fn);  // true
+     *  m.off('transition', fn);  // false
+     *  ```
+     *
+     *  @param name    The event name.
+     *  @param handler The handler reference to remove.
+     *  @returns `true` if removed, `false` if no match was registered.
+     */
+    off(name, handler) {
+        const set = this._event_handlers.get(name);
+        if (set === undefined) {
+            return false;
+        }
+        for (const entry of set) {
+            if (entry.handler === handler) {
+                set.delete(entry);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     *  Shared registration core used by {@link Machine.on} and
+     *  {@link Machine.once}.  Normalizes the optional filter argument and
+     *  installs the entry into the per-event subscription set.
+     *
+     *  @internal
+     */
+    _subscribe(name, filterOrFn, maybeFn, once) {
+        let filter;
+        let handler;
+        if (typeof filterOrFn === 'function') {
+            filter = undefined;
+            handler = filterOrFn;
+        }
+        else {
+            filter = filterOrFn;
+            handler = maybeFn;
+        }
+        if (typeof handler !== 'function') {
+            throw new JssmError(this, `event handler for "${name}" must be a function`);
+        }
+        let set = this._event_handlers.get(name);
+        if (set === undefined) {
+            set = new Set();
+            this._event_handlers.set(name, set);
+        }
+        const entry = { handler, filter, once };
+        set.add(entry);
+        return () => { set.delete(entry); };
+    }
+    /**
+     *  Dispatch an event to every registered subscriber in registration
+     *  order.  Filters are checked first; non-matching handlers are skipped
+     *  without invoking the handler.  Exceptions thrown by a handler are
+     *  caught and re-emitted as an `error` event so subsequent handlers
+     *  still run.
+     *
+     *  Re-entry into the `error` event itself is guarded — if an `error`
+     *  handler throws, the new exception is swallowed rather than rebroadcast
+     *  to avoid an infinite loop.
+     *
+     *  @internal
+     */
+    _fire(name, detail) {
+        const set = this._event_handlers.get(name);
+        if (set === undefined || set.size === 0) {
+            return;
+        }
+        // Snapshot so handlers can `off()` mid-loop without disturbing iteration.
+        const entries = Array.from(set);
+        for (const entry of entries) {
+            // filter check
+            if (entry.filter !== undefined) {
+                let matched = true;
+                for (const k of Object.keys(entry.filter)) {
+                    if (entry.filter[k] !== detail[k]) {
+                        matched = false;
+                        break;
+                    }
+                }
+                if (!matched) {
+                    continue;
+                }
+            }
+            // once removal happens BEFORE invocation so a throwing handler still
+            // gets removed and so re-entrant `on` calls during the handler see
+            // the post-removal state.
+            if (entry.once) {
+                set.delete(entry);
+            }
+            try {
+                entry.handler(detail);
+            }
+            catch (err) {
+                if (name === 'error' || this._firing_error) {
+                    // surface to stderr as a last resort but never recurse;
+                    // `console` is in the JS standard library and present in every
+                    // supported runtime, so guarding it would just add an untestable
+                    // branch.  See #638.
+                    // eslint-disable-next-line no-console
+                    console.error(err);
+                }
+                else {
+                    this._firing_error = true;
+                    try {
+                        this._fire('error', {
+                            error: err,
+                            source_event: name,
+                            source_detail: detail,
+                            handler: entry.handler
+                        });
+                    }
+                    finally {
+                        this._firing_error = false;
+                    }
+                }
+            }
+        }
+    }
     /** Low-level hook registration.  Installs a handler described by a
      *  {@link HookDescription} into the appropriate internal map.  Prefer the
      *  convenience wrappers ({@link hook}, {@link hook_entry}, etc.) over
@@ -23137,6 +23274,179 @@ class Machine {
             default:
                 throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
         }
+        // fire the registration event for inspector tools (#638)
+        this._fire('hook-registration', { description: HookDesc });
+    }
+    /**
+     *  Remove a previously-registered hook described by a
+     *  {@link HookDescription}.  Match is by `kind` + identifying keys
+     *  (`from`/`to`/`action`/etc.), not by handler reference — there is one
+     *  hook per slot in the registry, so the description uniquely identifies
+     *  which one to clear.  Fires a `hook-removal` event for inspector tools.
+     *
+     *  This is the symmetric counterpart of {@link Machine.set_hook} for the
+     *  event-bridging use case (#638).  Reasoning about hooks via observation
+     *  events requires being able to observe their disappearance too.
+     *
+     *  ```typescript
+     *  const m = sm`a -> b;`;
+     *  const fn = () => true;
+     *  m.set_hook({ kind: 'hook', from: 'a', to: 'b', handler: fn });
+     *  m.remove_hook({ kind: 'hook', from: 'a', to: 'b', handler: fn });
+     *  ```
+     *
+     *  @param HookDesc - A hook descriptor identifying the hook to remove.
+     *  @returns `true` if a hook was removed, `false` otherwise.
+     */
+    remove_hook(HookDesc) {
+        let removed = false;
+        switch (HookDesc.kind) {
+            case 'hook': {
+                const inner = this._hooks.get(HookDesc.from);
+                if (inner !== undefined && inner.has(HookDesc.to)) {
+                    inner.delete(HookDesc.to);
+                    removed = true;
+                }
+                break;
+            }
+            case 'named': {
+                const inner = this._named_hooks.get(HookDesc.from);
+                const inner2 = inner === undefined ? undefined : inner.get(HookDesc.to);
+                if (inner2 !== undefined && inner2.has(HookDesc.action)) {
+                    inner2.delete(HookDesc.action);
+                    removed = true;
+                }
+                break;
+            }
+            case 'global action':
+                removed = this._global_action_hooks.delete(HookDesc.action);
+                break;
+            case 'any action':
+                if (this._any_action_hook !== undefined) {
+                    this._any_action_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'standard transition':
+                if (this._standard_transition_hook !== undefined) {
+                    this._standard_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'main transition':
+                if (this._main_transition_hook !== undefined) {
+                    this._main_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'forced transition':
+                if (this._forced_transition_hook !== undefined) {
+                    this._forced_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'any transition':
+                if (this._any_transition_hook !== undefined) {
+                    this._any_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'entry':
+                removed = this._entry_hooks.delete(HookDesc.to);
+                break;
+            case 'exit':
+                removed = this._exit_hooks.delete(HookDesc.from);
+                break;
+            case 'after':
+                removed = this._after_hooks.delete(HookDesc.from);
+                break;
+            case 'post hook': {
+                const inner = this._post_hooks.get(HookDesc.from);
+                if (inner !== undefined && inner.has(HookDesc.to)) {
+                    inner.delete(HookDesc.to);
+                    removed = true;
+                }
+                break;
+            }
+            case 'post named': {
+                const inner = this._post_named_hooks.get(HookDesc.from);
+                const inner2 = inner === undefined ? undefined : inner.get(HookDesc.to);
+                if (inner2 !== undefined && inner2.has(HookDesc.action)) {
+                    inner2.delete(HookDesc.action);
+                    removed = true;
+                }
+                break;
+            }
+            case 'post global action':
+                removed = this._post_global_action_hooks.delete(HookDesc.action);
+                break;
+            case 'post any action':
+                if (this._post_any_action_hook !== undefined) {
+                    this._post_any_action_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'post standard transition':
+                if (this._post_standard_transition_hook !== undefined) {
+                    this._post_standard_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'post main transition':
+                if (this._post_main_transition_hook !== undefined) {
+                    this._post_main_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'post forced transition':
+                if (this._post_forced_transition_hook !== undefined) {
+                    this._post_forced_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'post any transition':
+                if (this._post_any_transition_hook !== undefined) {
+                    this._post_any_transition_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'post entry':
+                removed = this._post_entry_hooks.delete(HookDesc.to);
+                break;
+            case 'post exit':
+                removed = this._post_exit_hooks.delete(HookDesc.from);
+                break;
+            case 'pre everything':
+                if (this._pre_everything_hook !== undefined) {
+                    this._pre_everything_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'everything':
+                if (this._everything_hook !== undefined) {
+                    this._everything_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'pre post everything':
+                if (this._pre_post_everything_hook !== undefined) {
+                    this._pre_post_everything_hook = undefined;
+                    removed = true;
+                }
+                break;
+            case 'post everything':
+                if (this._post_everything_hook !== undefined) {
+                    this._post_everything_hook = undefined;
+                    removed = true;
+                }
+                break;
+            default:
+                throw new JssmError(this, `Unknown hook type ${HookDesc.kind}, should be impossible`);
+        }
+        if (removed) {
+            this._fire('hook-removal', { description: HookDesc });
+        }
+        return removed;
     }
     /** Register a pre-transition hook on a specific edge.  Fires before
      *  transitioning from `from` to `to`.  If the handler returns `false`, the
@@ -23478,8 +23788,25 @@ class Machine {
     override(newState, newData) {
         if (this.allows_override) {
             if (this._states.has(newState)) {
+                const fromState = this._state;
+                const oldData = this._data;
                 this._state = newState;
                 this._data = newData;
+                this._fire('override', {
+                    from: fromState,
+                    to: newState,
+                    old_data: oldData,
+                    new_data: newData
+                });
+                if (oldData !== newData) {
+                    this._fire('data-change', {
+                        from: fromState,
+                        to: newState,
+                        old_data: oldData,
+                        new_data: newData,
+                        cause: 'override'
+                    });
+                }
             }
             else {
                 throw new JssmError(this, `Cannot override state to "${newState}", a state that does not exist`);
@@ -23568,6 +23895,21 @@ class Machine {
             forced: wasForced,
             trans_type
         };
+        // 'action' event fires when an action is attempted, regardless of whether
+        // it ultimately succeeds — matches the issue spec for observation events.
+        if (wasAction) {
+            this._fire('action', {
+                action: newStateOrAction,
+                from: this._state,
+                to: newState,
+                data: this._data,
+                next_data: newData
+            });
+        }
+        // Captured pre-transition source state so 'data-change' detail and similar
+        // events can name where we came from.
+        const fromState = this._state;
+        const oldData = this._data;
         if (valid) {
             if (this._has_hooks) {
                 // once validity is known, clear old 'after' timeout clause
@@ -23580,10 +23922,23 @@ class Machine {
                     }
                 }
                 let data_changed = false;
+                const fire_rejection = (hook_name) => {
+                    this._fire('rejection', {
+                        from: fromState,
+                        to: newState,
+                        action: fromAction,
+                        data: oldData,
+                        next_data: newData,
+                        reason: 'hook',
+                        hook_name,
+                        forced: wasForced
+                    });
+                };
                 // 0. pre everything hook (fires before all other pre-hooks)
                 if (this._pre_everything_hook !== undefined) {
                     const outcome = abstract_everything_hook_step(this._pre_everything_hook, Object.assign(Object.assign({}, hook_args), { hook_name: 'pre everything' }));
                     if (outcome.pass === false) {
+                        fire_rejection('pre everything');
                         return false;
                     }
                     update_fields(outcome);
@@ -23592,12 +23947,14 @@ class Machine {
                     // 1a. any action hook
                     const outcome = abstract_hook_step(this._any_action_hook, hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('any action');
                         return false;
                     }
                     update_fields(outcome);
                     // 1b. global specific action hook
                     const outcome2 = abstract_hook_step(this._global_action_hooks.get(newStateOrAction), hook_args);
                     if (outcome2.pass === false) {
+                        fire_rejection('global action');
                         return false;
                     }
                     update_fields(outcome2);
@@ -23613,6 +23970,7 @@ class Machine {
                 if (this._any_transition_hook !== undefined) {
                     const outcome = abstract_hook_step(this._any_transition_hook, hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('any transition');
                         return false;
                     }
                     update_fields(outcome);
@@ -23621,6 +23979,7 @@ class Machine {
                 if (this._has_exit_hooks) {
                     const outcome = abstract_hook_step(this._exit_hooks.get(this._state), hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('exit');
                         return false;
                     }
                     update_fields(outcome);
@@ -23635,6 +23994,7 @@ class Machine {
                         const nh = byAct === undefined ? undefined : byAct.get(newStateOrAction);
                         const outcome = abstract_hook_step(nh, hook_args);
                         if (outcome.pass === false) {
+                            fire_rejection('named');
                             return false;
                         }
                         update_fields(outcome);
@@ -23647,6 +24007,7 @@ class Machine {
                     const h = byTo === undefined ? undefined : byTo.get(newState);
                     const outcome = abstract_hook_step(h, hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('hook');
                         return false;
                     }
                     update_fields(outcome);
@@ -23656,6 +24017,7 @@ class Machine {
                 if (trans_type === 'legal') {
                     const outcome = abstract_hook_step(this._standard_transition_hook, hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('standard transition');
                         return false;
                     }
                     update_fields(outcome);
@@ -23664,6 +24026,7 @@ class Machine {
                 if (trans_type === 'main') {
                     const outcome = abstract_hook_step(this._main_transition_hook, hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('main transition');
                         return false;
                     }
                     update_fields(outcome);
@@ -23672,6 +24035,7 @@ class Machine {
                 if (trans_type === 'forced') {
                     const outcome = abstract_hook_step(this._forced_transition_hook, hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('forced transition');
                         return false;
                     }
                     update_fields(outcome);
@@ -23680,6 +24044,7 @@ class Machine {
                 if (this._has_entry_hooks) {
                     const outcome = abstract_hook_step(this._entry_hooks.get(newState), hook_args);
                     if (outcome.pass === false) {
+                        fire_rejection('entry');
                         return false;
                     }
                     update_fields(outcome);
@@ -23688,6 +24053,7 @@ class Machine {
                 if (this._everything_hook !== undefined) {
                     const outcome = abstract_everything_hook_step(this._everything_hook, Object.assign(Object.assign({}, hook_args), { hook_name: 'everything' }));
                     if (outcome.pass === false) {
+                        fire_rejection('everything');
                         return false;
                     }
                     update_fields(outcome);
@@ -23723,6 +24089,15 @@ class Machine {
             // not valid
         }
         else {
+            this._fire('rejection', {
+                from: fromState,
+                to: newStateOrAction,
+                action: fromAction,
+                data: oldData,
+                next_data: newData,
+                reason: 'invalid',
+                forced: wasForced
+            });
             return false;
         }
         // posthooks begin here
@@ -23805,6 +24180,47 @@ class Machine {
                 this._post_everything_hook(Object.assign(Object.assign({}, hook_args), { hook_name: 'post everything' }));
             }
         }
+        // observation events: fire after the state has been committed and all
+        // hooks (pre and post) have completed, matching the semantics that
+        // events observe rather than intercept (#638).
+        const newData_after = this._data;
+        this._fire('exit', {
+            state: fromState,
+            to: newState,
+            action: fromAction,
+            data: newData_after
+        });
+        this._fire('transition', {
+            from: fromState,
+            to: newState,
+            action: fromAction,
+            data: newData_after,
+            next_data: newData,
+            trans_type,
+            forced: wasForced
+        });
+        this._fire('entry', {
+            state: newState,
+            from: fromState,
+            action: fromAction,
+            data: newData_after
+        });
+        if (oldData !== newData_after) {
+            this._fire('data-change', {
+                from: fromState,
+                to: newState,
+                action: fromAction,
+                old_data: oldData,
+                new_data: newData_after,
+                cause: 'transition'
+            });
+        }
+        if (this.state_is_terminal(newState)) {
+            this._fire('terminal', { state: newState, data: newData_after });
+        }
+        if (this.state_is_complete(newState)) {
+            this._fire('complete', { state: newState, data: newData_after });
+        }
         // possibly re-establish new 'after' clause
         this.auto_set_state_timeout();
         return true;
@@ -24433,14 +24849,17 @@ class Machine {
         // this is enforced by the "after mapping runs normally with very short time" tests in after_mapping.spec
         // we'll mark it no-check so that our coverage numbers aren't wrecked
         /* istanbul ignore next */
+        /* v8 ignore next 10 */
         () => {
+            const from_state = this.state();
             this.clear_state_timeout();
             if (this._has_after_hooks) {
-                const ah = this._after_hooks.get(this.state());
+                const ah = this._after_hooks.get(from_state);
                 if (ah !== undefined) {
                     ah({ data: this._data, next_data: this._data });
                 }
             }
+            this._fire('timeout', { from: from_state, to: next_state, after_time });
             this.go(next_state);
         }, after_time);
         this._timeout_target = next_state;