jssm 5.143.10 → 5.143.12

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.143.10 at 6/12/2026, 8:06:22 AM
+* Generated for version 5.143.12 at 6/12/2026, 8:38:46 AM
 
 -->
-# jssm 5.143.10
+# jssm 5.143.12
 
 [**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,902 tests at 100.0% line coverage
+  library.**  6,952 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,902 tests***, run 75,608 times.
+***6,952 tests***, run 78,925 times.
 
-- 6,208 specs with 100.0% coverage
-- 694 fuzz tests with 63.5% coverage
-- 5,805 TypeScript lines - 1.2 tests per line, 13.0 generated tests per line
+- 6,225 specs with 100.0% coverage
+- 727 fuzz tests with 73.1% coverage
+- 5,871 TypeScript lines - 1.2 tests per line, 13.4 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/instance.js

@@ -22560,6 +22560,119 @@ theme_mapping.set('ocean', ocean_theme);
 theme_mapping.set('plain', plain_theme);
 theme_mapping.set('bold', bold_theme);
 
+/**
+ * String interning support for the jssm machine internals.
+ *
+ * State and action names are interned to dense integer ids at machine
+ * construction so that per-transition dispatch can use numeric map keys
+ * (integer hashing) instead of repeated string-keyed lookups.  Internal
+ * machinery only — deliberately not re-exported from the `jssm` public
+ * surface, so the public API is unchanged.
+ *
+ * @internal
+ */
+/**
+ * A string↔integer bimap.  Assigns dense ids (0, 1, 2, …) in first-seen
+ * order; lookups are O(1) both directions.  Grows monotonically — there is
+ * no removal, matching machine semantics (states and actions are fixed
+ * after construction; late interning only happens for never-matching
+ * lookups such as hook registrations naming unknown states).
+ *
+ * @example
+ *   const i = new Interner();
+ *   i.intern('red');     // 0
+ *   i.intern('green');   // 1
+ *   i.intern('red');     // 0  (idempotent)
+ *   i.id_of('green');    // 1
+ *   i.name_of(0);        // 'red'
+ *
+ * @see pair_key
+ */
+class Interner {
+    constructor() {
+        this.ids = new Map();
+        this.names = [];
+    }
+    /**
+     * Return the id for `name`, assigning the next dense id if the name has
+     * not been seen before.
+     *
+     * @param name - The string to intern.
+     * @returns The (possibly newly assigned) integer id.
+     *
+     * @example
+     *   interner.intern('red');  // 0 on first call, 0 on every later call
+     */
+    intern(name) {
+        const existing = this.ids.get(name);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const id = this.names.length;
+        this.ids.set(name, id);
+        this.names.push(name);
+        return id;
+    }
+    /**
+     * Return the id for `name` without interning, or `undefined` when the
+     * name has never been interned.  This is the hot-path probe for
+     * user-supplied names.
+     *
+     * @param name - The string to look up.
+     *
+     * @example
+     *   interner.id_of('mauve');  // undefined — never interned
+     */
+    id_of(name) {
+        return this.ids.get(name);
+    }
+    /**
+     * Return the name for `id`, or `undefined` for an id never assigned.
+     *
+     * @param id - The integer id to invert.
+     *
+     * @example
+     *   interner.name_of(0);  // 'red'
+     */
+    name_of(id) {
+        return this.names[id];
+    }
+    /** The count of distinct interned names. */
+    get size() {
+        return this.names.length;
+    }
+}
+/**
+ * Szudzik pairing: packs two non-negative integers into one unique number,
+ * order-sensitively, with no dependence on a fixed table size — so interners
+ * may keep growing without invalidating existing keys.  Values stay exact
+ * for ids below 2^26 (the result is bounded by roughly max(a,b)^2), far
+ * beyond any real machine's state count.
+ *
+ * NaN deliberately propagates: probing with an unknown name's id
+ * (`id_of(...) ?? NaN`) yields a NaN key, which can never match a stored
+ * key, so the lookup misses — exactly the behavior of the string-keyed maps
+ * it replaces.  Do NOT use a negative sentinel instead: Szudzik is only
+ * injective over the naturals, and a negative input can collide with a real
+ * stored key (e.g. szudzik(-1, 2) === szudzik(1, 1) === 3), which would make
+ * lookups from an unknown state falsely succeed.
+ *
+ * @param a - First non-negative integer (or NaN as a deliberate miss).
+ * @param b - Second non-negative integer (or NaN as a deliberate miss).
+ * @returns A number unique to the ordered pair `(a, b)` over the naturals.
+ *
+ * @example
+ *   pair_key(2, 5);  // 27
+ *   pair_key(5, 2);  // 32 — order-sensitive
+ *
+ * @see Interner
+ */
+function pair_key(a, b) {
+    return (a >= b)
+        ? (a * a) + a + b
+        : (b * b) + a;
+}
+
 /*******
  *
  *  Convenience aliases for common mathematical and numeric constants from
@@ -22675,7 +22788,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.143.10";
+const version = "5.143.12";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -22927,6 +23040,12 @@ class Machine {
         this._actions = new Map();
         this._reverse_actions = new Map();
         this._reverse_action_targets = new Map(); // todo
+        this._state_interner = new Interner();
+        this._action_interner = new Interner();
+        this._state_id = NaN;
+        this._edge_id_by_pair = new Map();
+        this._edge_id_by_action_pair = new Map();
+        this._edge_to_ids = [];
         this._start_states = new Set(start_states);
         this._end_states = new Set(end_states); // todo consider what to do about incorporating complete too
         this._failed_outputs = new Set(failed_outputs);
@@ -23113,6 +23232,13 @@ class Machine {
             }
             //    const to_mapping = from_mapping.get(tr.to);
             from_mapping.set(tr.to, thisEdgeId); // already checked that this mapping doesn't exist, above
+            // numeric mirror of the (from, to) endpoint mapping.  intern() rather
+            // than id_of(): idempotent, and returns number (not number|undefined)
+            // since both endpoints were just created above if missing.
+            const from_id = this._state_interner.intern(tr.from);
+            const to_id = this._state_interner.intern(tr.to);
+            this._edge_id_by_pair.set(pair_key(from_id, to_id), thisEdgeId);
+            this._edge_to_ids[thisEdgeId] = to_id;
             // outbound adjacency: every edge originating at tr.from, regardless of action/target.
             // _edge_map above keys a single edge per (from, to) and overwrites on collision, which
             // is fine for lookup_transition_for but loses information for edges_between when several
@@ -23147,6 +23273,9 @@ class Machine {
                 // no need to test for reverse mapping pre-presence;
                 // forward mapping already covers collisions
                 rActionMap.set(tr.action, thisEdgeId);
+                // numeric mirror of the (action, from) dispatch mapping
+                const action_id = this._action_interner.intern(tr.action);
+                this._edge_id_by_action_pair.set(pair_key(action_id, from_id), thisEdgeId);
                 // reverse mapping first by state target name
                 if (!(this._reverse_action_targets.has(tr.to))) {
                     this._reverse_action_targets.set(tr.to, new Map());
@@ -23191,9 +23320,11 @@ class Machine {
                 throw new JssmError(this, `requested start state ${initial_state} is not in start state list; add {start_states_no_enforce:true} to constructor options if desired`);
             }
             this._state = initial_state;
+            this._state_id = this._state_interner.intern(this._state);
         }
         else {
             this._state = start_states[0];
+            this._state_id = this._state_interner.intern(this._state);
         }
         // done building, do checks
         // assert all props are valid
@@ -23281,6 +23412,7 @@ class Machine {
             throw new JssmError(this, `state ${JSON.stringify(state_config.name)} already exists`);
         }
         this._states.set(state_config.name, state_config);
+        this._state_interner.intern(state_config.name);
         return state_config.name;
     }
     /*********
@@ -25321,6 +25453,7 @@ class Machine {
                 const fromState = this._state;
                 const oldData = this._data;
                 this._state = newState;
+                this._state_id = this._state_interner.intern(newState);
                 this._data = newData;
                 this._fire('override', {
                     from: fromState,
@@ -25428,30 +25561,45 @@ class Machine {
      *
      */
     transition_impl(newStateOrAction, newData, wasForced, wasAction) {
-        let valid = false, trans_type, newState, fromAction = undefined;
+        let valid = false, trans_type, newState, newStateId = NaN, fromAction = undefined;
         if (wasForced) {
-            if (this.valid_force_transition(newStateOrAction, newData)) {
+            // numeric inline of valid_force_transition: any existing edge
+            // qualifies, forced or not.  one string probe (the user's target name)
+            // plus one numeric probe, replacing two string probes.
+            const to_id = this._state_interner.id_of(newStateOrAction);
+            const edgeId = (to_id === undefined) ? undefined : this._edge_id_by_pair.get(pair_key(this._state_id, to_id));
+            if (edgeId !== undefined) {
                 valid = true;
                 trans_type = 'forced';
                 newState = newStateOrAction;
+                newStateId = to_id;
             }
         }
         else if (wasAction) {
-            if (this.valid_action(newStateOrAction, newData)) {
-                const edge = this.current_action_edge_for(newStateOrAction);
+            // single numeric resolution: the old path looked the action up twice,
+            // once inside valid_action and again inside current_action_edge_for
+            const edgeId = this.current_action_for(newStateOrAction);
+            if ((edgeId !== undefined) && (edgeId !== null)) {
+                const edge = this._edges[edgeId];
                 valid = true;
                 trans_type = edge.kind;
                 newState = edge.to;
+                newStateId = this._edge_to_ids[edgeId];
                 fromAction = newStateOrAction;
             }
         }
         else {
-            if (this.valid_transition(newStateOrAction, newData)) {
+            // numeric inline of valid_transition: the edge must exist and must not
+            // be forced_only (truthiness, matching the old refusal exactly)
+            const to_id = this._state_interner.id_of(newStateOrAction);
+            const edgeId = (to_id === undefined) ? undefined : this._edge_id_by_pair.get(pair_key(this._state_id, to_id));
+            if ((edgeId !== undefined) && (!(this._edges[edgeId].forced_only))) {
                 if (this._has_transition_hooks || this._has_post_transition_hooks) {
                     trans_type = this.edges_between(this._state, newStateOrAction)[0].kind; // TODO this won't do the right thing if various edges have different types
                 }
                 valid = true;
                 newState = newStateOrAction;
+                newStateId = to_id;
             }
         }
         // hook_args is read only inside the `_has_hooks` / `_has_post_hooks`
@@ -25657,6 +25805,7 @@ class Machine {
                     this._history.shove([this._state, this._data]);
                 }
                 this._state = newState;
+                this._state_id = newStateId;
                 if (data_changed) {
                     this._data = hook_args.data;
                 }
@@ -25672,6 +25821,7 @@ class Machine {
                     this._history.shove([this._state, this._data]);
                 }
                 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) {
@@ -26356,14 +26506,16 @@ class Machine {
         return this.transition_impl(newState, newData, true, false);
     }
     /** Get the edge index for an action from the current state.
+     *  Interned dispatch: resolves via the numeric (action, from) index —
+     *  unknown action names miss without throwing.
      *  @param action - The action name.
      *  @returns The edge index, or `undefined` if the action is not available.
      */
     current_action_for(action) {
-        const action_base = this._actions.get(action);
-        return action_base
-            ? action_base.get(this.state())
-            : undefined;
+        const action_id = this._action_interner.id_of(action);
+        return (action_id === undefined)
+            ? undefined
+            : this._edge_id_by_action_pair.get(pair_key(action_id, this._state_id));
     }
     /** Get the full transition object for an action from the current state.
      *  @param action - The action name.

package/dist/cdn/viz.js

@@ -22585,6 +22585,119 @@ theme_mapping.set('ocean', ocean_theme);
 theme_mapping.set('plain', plain_theme);
 theme_mapping.set('bold', bold_theme);
 
+/**
+ * String interning support for the jssm machine internals.
+ *
+ * State and action names are interned to dense integer ids at machine
+ * construction so that per-transition dispatch can use numeric map keys
+ * (integer hashing) instead of repeated string-keyed lookups.  Internal
+ * machinery only — deliberately not re-exported from the `jssm` public
+ * surface, so the public API is unchanged.
+ *
+ * @internal
+ */
+/**
+ * A string↔integer bimap.  Assigns dense ids (0, 1, 2, …) in first-seen
+ * order; lookups are O(1) both directions.  Grows monotonically — there is
+ * no removal, matching machine semantics (states and actions are fixed
+ * after construction; late interning only happens for never-matching
+ * lookups such as hook registrations naming unknown states).
+ *
+ * @example
+ *   const i = new Interner();
+ *   i.intern('red');     // 0
+ *   i.intern('green');   // 1
+ *   i.intern('red');     // 0  (idempotent)
+ *   i.id_of('green');    // 1
+ *   i.name_of(0);        // 'red'
+ *
+ * @see pair_key
+ */
+class Interner {
+    constructor() {
+        this.ids = new Map();
+        this.names = [];
+    }
+    /**
+     * Return the id for `name`, assigning the next dense id if the name has
+     * not been seen before.
+     *
+     * @param name - The string to intern.
+     * @returns The (possibly newly assigned) integer id.
+     *
+     * @example
+     *   interner.intern('red');  // 0 on first call, 0 on every later call
+     */
+    intern(name) {
+        const existing = this.ids.get(name);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const id = this.names.length;
+        this.ids.set(name, id);
+        this.names.push(name);
+        return id;
+    }
+    /**
+     * Return the id for `name` without interning, or `undefined` when the
+     * name has never been interned.  This is the hot-path probe for
+     * user-supplied names.
+     *
+     * @param name - The string to look up.
+     *
+     * @example
+     *   interner.id_of('mauve');  // undefined — never interned
+     */
+    id_of(name) {
+        return this.ids.get(name);
+    }
+    /**
+     * Return the name for `id`, or `undefined` for an id never assigned.
+     *
+     * @param id - The integer id to invert.
+     *
+     * @example
+     *   interner.name_of(0);  // 'red'
+     */
+    name_of(id) {
+        return this.names[id];
+    }
+    /** The count of distinct interned names. */
+    get size() {
+        return this.names.length;
+    }
+}
+/**
+ * Szudzik pairing: packs two non-negative integers into one unique number,
+ * order-sensitively, with no dependence on a fixed table size — so interners
+ * may keep growing without invalidating existing keys.  Values stay exact
+ * for ids below 2^26 (the result is bounded by roughly max(a,b)^2), far
+ * beyond any real machine's state count.
+ *
+ * NaN deliberately propagates: probing with an unknown name's id
+ * (`id_of(...) ?? NaN`) yields a NaN key, which can never match a stored
+ * key, so the lookup misses — exactly the behavior of the string-keyed maps
+ * it replaces.  Do NOT use a negative sentinel instead: Szudzik is only
+ * injective over the naturals, and a negative input can collide with a real
+ * stored key (e.g. szudzik(-1, 2) === szudzik(1, 1) === 3), which would make
+ * lookups from an unknown state falsely succeed.
+ *
+ * @param a - First non-negative integer (or NaN as a deliberate miss).
+ * @param b - Second non-negative integer (or NaN as a deliberate miss).
+ * @returns A number unique to the ordered pair `(a, b)` over the naturals.
+ *
+ * @example
+ *   pair_key(2, 5);  // 27
+ *   pair_key(5, 2);  // 32 — order-sensitive
+ *
+ * @see Interner
+ */
+function pair_key(a, b) {
+    return (a >= b)
+        ? (a * a) + a + b
+        : (b * b) + a;
+}
+
 /*******
  *
  *  Convenience aliases for common mathematical and numeric constants from
@@ -22700,7 +22813,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.143.10";
+const version = "5.143.12";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -22952,6 +23065,12 @@ class Machine {
         this._actions = new Map();
         this._reverse_actions = new Map();
         this._reverse_action_targets = new Map(); // todo
+        this._state_interner = new Interner();
+        this._action_interner = new Interner();
+        this._state_id = NaN;
+        this._edge_id_by_pair = new Map();
+        this._edge_id_by_action_pair = new Map();
+        this._edge_to_ids = [];
         this._start_states = new Set(start_states);
         this._end_states = new Set(end_states); // todo consider what to do about incorporating complete too
         this._failed_outputs = new Set(failed_outputs);
@@ -23138,6 +23257,13 @@ class Machine {
             }
             //    const to_mapping = from_mapping.get(tr.to);
             from_mapping.set(tr.to, thisEdgeId); // already checked that this mapping doesn't exist, above
+            // numeric mirror of the (from, to) endpoint mapping.  intern() rather
+            // than id_of(): idempotent, and returns number (not number|undefined)
+            // since both endpoints were just created above if missing.
+            const from_id = this._state_interner.intern(tr.from);
+            const to_id = this._state_interner.intern(tr.to);
+            this._edge_id_by_pair.set(pair_key(from_id, to_id), thisEdgeId);
+            this._edge_to_ids[thisEdgeId] = to_id;
             // outbound adjacency: every edge originating at tr.from, regardless of action/target.
             // _edge_map above keys a single edge per (from, to) and overwrites on collision, which
             // is fine for lookup_transition_for but loses information for edges_between when several
@@ -23172,6 +23298,9 @@ class Machine {
                 // no need to test for reverse mapping pre-presence;
                 // forward mapping already covers collisions
                 rActionMap.set(tr.action, thisEdgeId);
+                // numeric mirror of the (action, from) dispatch mapping
+                const action_id = this._action_interner.intern(tr.action);
+                this._edge_id_by_action_pair.set(pair_key(action_id, from_id), thisEdgeId);
                 // reverse mapping first by state target name
                 if (!(this._reverse_action_targets.has(tr.to))) {
                     this._reverse_action_targets.set(tr.to, new Map());
@@ -23216,9 +23345,11 @@ class Machine {
                 throw new JssmError(this, `requested start state ${initial_state} is not in start state list; add {start_states_no_enforce:true} to constructor options if desired`);
             }
             this._state = initial_state;
+            this._state_id = this._state_interner.intern(this._state);
         }
         else {
             this._state = start_states[0];
+            this._state_id = this._state_interner.intern(this._state);
         }
         // done building, do checks
         // assert all props are valid
@@ -23306,6 +23437,7 @@ class Machine {
             throw new JssmError(this, `state ${JSON.stringify(state_config.name)} already exists`);
         }
         this._states.set(state_config.name, state_config);
+        this._state_interner.intern(state_config.name);
         return state_config.name;
     }
     /*********
@@ -25346,6 +25478,7 @@ class Machine {
                 const fromState = this._state;
                 const oldData = this._data;
                 this._state = newState;
+                this._state_id = this._state_interner.intern(newState);
                 this._data = newData;
                 this._fire('override', {
                     from: fromState,
@@ -25453,30 +25586,45 @@ class Machine {
      *
      */
     transition_impl(newStateOrAction, newData, wasForced, wasAction) {
-        let valid = false, trans_type, newState, fromAction = undefined;
+        let valid = false, trans_type, newState, newStateId = NaN, fromAction = undefined;
         if (wasForced) {
-            if (this.valid_force_transition(newStateOrAction, newData)) {
+            // numeric inline of valid_force_transition: any existing edge
+            // qualifies, forced or not.  one string probe (the user's target name)
+            // plus one numeric probe, replacing two string probes.
+            const to_id = this._state_interner.id_of(newStateOrAction);
+            const edgeId = (to_id === undefined) ? undefined : this._edge_id_by_pair.get(pair_key(this._state_id, to_id));
+            if (edgeId !== undefined) {
                 valid = true;
                 trans_type = 'forced';
                 newState = newStateOrAction;
+                newStateId = to_id;
             }
         }
         else if (wasAction) {
-            if (this.valid_action(newStateOrAction, newData)) {
-                const edge = this.current_action_edge_for(newStateOrAction);
+            // single numeric resolution: the old path looked the action up twice,
+            // once inside valid_action and again inside current_action_edge_for
+            const edgeId = this.current_action_for(newStateOrAction);
+            if ((edgeId !== undefined) && (edgeId !== null)) {
+                const edge = this._edges[edgeId];
                 valid = true;
                 trans_type = edge.kind;
                 newState = edge.to;
+                newStateId = this._edge_to_ids[edgeId];
                 fromAction = newStateOrAction;
             }
         }
         else {
-            if (this.valid_transition(newStateOrAction, newData)) {
+            // numeric inline of valid_transition: the edge must exist and must not
+            // be forced_only (truthiness, matching the old refusal exactly)
+            const to_id = this._state_interner.id_of(newStateOrAction);
+            const edgeId = (to_id === undefined) ? undefined : this._edge_id_by_pair.get(pair_key(this._state_id, to_id));
+            if ((edgeId !== undefined) && (!(this._edges[edgeId].forced_only))) {
                 if (this._has_transition_hooks || this._has_post_transition_hooks) {
                     trans_type = this.edges_between(this._state, newStateOrAction)[0].kind; // TODO this won't do the right thing if various edges have different types
                 }
                 valid = true;
                 newState = newStateOrAction;
+                newStateId = to_id;
             }
         }
         // hook_args is read only inside the `_has_hooks` / `_has_post_hooks`
@@ -25682,6 +25830,7 @@ class Machine {
                     this._history.shove([this._state, this._data]);
                 }
                 this._state = newState;
+                this._state_id = newStateId;
                 if (data_changed) {
                     this._data = hook_args.data;
                 }
@@ -25697,6 +25846,7 @@ class Machine {
                     this._history.shove([this._state, this._data]);
                 }
                 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) {
@@ -26381,14 +26531,16 @@ class Machine {
         return this.transition_impl(newState, newData, true, false);
     }
     /** Get the edge index for an action from the current state.
+     *  Interned dispatch: resolves via the numeric (action, from) index —
+     *  unknown action names miss without throwing.
      *  @param action - The action name.
      *  @returns The edge index, or `undefined` if the action is not available.
      */
     current_action_for(action) {
-        const action_base = this._actions.get(action);
-        return action_base
-            ? action_base.get(this.state())
-            : undefined;
+        const action_id = this._action_interner.id_of(action);
+        return (action_id === undefined)
+            ? undefined
+            : this._edge_id_by_action_pair.get(pair_key(action_id, this._state_id));
     }
     /** Get the full transition object for an action from the current state.
      *  @param action - The action name.