@uuxxx/fsm 1.3.0 → 1.4.0

package/README.md

@@ -32,7 +32,7 @@ type State = 'idle' | 'loading' | 'success' | 'error';
 
 const fsm = makeFsm({
 	init: 'idle',
-	states: ['idle', 'loading', 'success', 'error'] as State[],
+	states: ['idle', 'loading', 'success', 'error'],
 	transitions: {
 		start: {
 			from: 'idle',
@@ -285,11 +285,13 @@ Plugin names must be unique — registering two plugins with the same name trigg
 
 ### History Plugin
 
-Tracks state history with pointer-based navigation.
+Read-only state history tracking with pointer-based navigation.
+
+`back()` and `forward()` move an internal pointer and return the state at that position — they do **not** change the FSM state. Use transition methods to actually navigate (e.g. `fsm.goto(fsm.history.back(1))`).
 
 ```typescript
 import { makeFsm } from '@uuxxx/fsm';
-import { fsmHistoryPlugin } from '@uuxxx/fsm/history-plugin';
+import { historyPlugin } from '@uuxxx/fsm-plugins/history';
 
 const fsm = makeFsm({
 	init: 'a',
@@ -297,27 +299,31 @@ const fsm = makeFsm({
 	transitions: {
 		goto: { from: '*', to: (s: 'a' | 'b' | 'c') => s },
 	},
-	plugins: [fsmHistoryPlugin()],
+	plugins: [historyPlugin()],
 });
 
 fsm.goto('b');
 fsm.goto('c');
-fsm.history.get(); // ['a', 'b', 'c']
-
-fsm.history.back(1); // returns 'b'
-fsm.history.back(1); // returns 'a'
-fsm.history.forward(2); // returns 'c'
+fsm.history.get(); // ['a', 'b', 'c'] (returns a copy)
+
+fsm.history.back(1); // returns 'b' (pointer moved, FSM state unchanged)
+fsm.history.current(); // 'b'
+fsm.history.canBack(); // true
+fsm.history.canForward(); // true
+fsm.history.forward(1); // returns 'c'
+fsm.goto(fsm.history.current()); // actually transition to 'c'
 ```
 
 #### History API
 
-| Method                       | Returns    | Description                                                                        |
-| ---------------------------- | ---------- | ---------------------------------------------------------------------------------- |
-| `fsm.history.get()`          | `TState[]` | Full history array                                                                 |
-| `fsm.history.back(steps)`    | `TState`   | Move pointer back by `steps`, returns the state at that position. Clamps to start  |
-| `fsm.history.forward(steps)` | `TState`   | Move pointer forward by `steps`, returns the state at that position. Clamps to end |
-
-> **Note:** `back()` and `forward()` move the internal history pointer and return the state at that position. They do **not** trigger a state transition on the FSM — use transition methods if you need to change the actual FSM state.
+| Method                       | Returns    | Description                                                                                                     |
+| ---------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
+| `fsm.history.get()`          | `TState[]` | Returns a copy of the full history array                                                                        |
+| `fsm.history.current()`      | `TState`   | Returns the state at the current pointer position                                                               |
+| `fsm.history.back(steps)`    | `TState`   | Move pointer back by `steps`, returns the state at that position. Clamps to start. Ignores non-positive values  |
+| `fsm.history.forward(steps)` | `TState`   | Move pointer forward by `steps`, returns the state at that position. Clamps to end. Ignores non-positive values |
+| `fsm.history.canBack()`      | `boolean`  | Whether the pointer can move back (pointer > 0)                                                                 |
+| `fsm.history.canForward()`   | `boolean`  | Whether the pointer can move forward (pointer < end)                                                            |
 
 When a transition occurs, any forward history after the current pointer is discarded (like browser navigation).
 

package/dist/index.d.ts

@@ -29,6 +29,8 @@ type CancelableLifecycleMethod<TState extends Label, TTransitions extends Rec<Tr
 type LifecycleMethods<TState extends Label, TTransitions extends Rec<Transition<TState>>> = {
   onBeforeTransition?: CancelableLifecycleMethod<TState, TTransitions>;
   onAfterTransition?: LifecycleMethod<TState, TTransitions>;
+  onError?: (msg: string, lifecycle?: Lifecycle<TState, Entries<TTransitions>>) => void;
+  onWarn?: (msg: string, lifecycle: Lifecycle<TState, Entries<TTransitions>>) => void;
 };
 type StateMethods<TState extends Label> = {
   state: () => TState;
@@ -37,8 +39,9 @@ type StateMethods<TState extends Label> = {
 /** API object passed to each plugin during registration. Provides state access, lifecycle hooks, and error listeners. */
 type ApiForPlugin<TState extends Label, TTransitions extends Rec<Transition<TState>>> = {
   init: (listener: (state: TState) => void) => void;
-  onError: (listener: (msg: string) => void) => Noop;
-} & StateMethods<TState> & { [K in KeyOf<LifecycleMethods<TState, TTransitions>>]-?: (listener: LifecycleMethods<TState, TTransitions>[K]) => Noop };
+  onError: (listener: (msg: string, lifecycle?: Lifecycle<TState, Entries<TTransitions>>) => void) => Noop;
+  onWarn: (listener: (msg: string, lifecycle: Lifecycle<TState, Entries<TTransitions>>) => void) => Noop;
+} & StateMethods<TState> & { [K in Exclude<KeyOf<LifecycleMethods<TState, TTransitions>>, 'onError' | 'onWarn'>]-?: (listener: LifecycleMethods<TState, TTransitions>[K]) => Noop };
 type PluginApi = {
   name: string;
   api: Rec<AnyFn>;
@@ -53,10 +56,9 @@ type Plugin<TState extends Label = Label, TTransitions extends Rec<Transition<TS
 type Config<TState extends Label, TTransitions extends Rec<Transition<TState>>, TPlugins extends Array<Plugin<TState, TTransitions>> = EmptyArray> = {
   /** Initial state of the FSM. */init: TState; /** All valid states. The FSM will reject transitions to states not in this list. */
   states: TState[]; /** Transition definitions. Each key becomes a method on the FSM instance. */
-  transitions: TTransitions; /** Optional lifecycle hooks (`onBeforeTransition`, `onAfterTransition`). */
+  transitions: TTransitions; /** Optional lifecycle hooks (`onBeforeTransition`, `onAfterTransition`, `onError`). */
   methods?: LifecycleMethods<TState, TTransitions>; /** Optional plugins to extend the FSM with additional APIs. */
-  plugins?: TPlugins; /** Custom error handler. By default, errors throw with a `[FSM]:` prefix. */
-  onError?: (msg: string) => void;
+  plugins?: TPlugins;
 };
 type TransitionMethods<TTransitions extends Rec<Transition<Label>>> = { [K in KeyOf<TTransitions>]: TTransitions[K]['to'] extends Label ? () => TTransitions[K]['to'] : TTransitions[K]['to'] };
 type PluginsMethods<TState extends Label, TTransitions extends Rec<Transition<TState>>, TPlugins extends Array<Plugin<TState, TTransitions>>> = { [K in ReturnType<TPlugins[number]>['name']]: Extract<ReturnType<TPlugins[number]>, {

package/dist/index.js

@@ -1,4 +1,4 @@
-let t={nlx:t=>null===t,ulx:t=>void 0===t,nil:e=>t.nlx(e)||t.ulx(e),not:{nlx:t=>null!==t,ulx:t=>void 0!==t,nil:e=>t.not.nlx(e)&&t.not.ulx(e)},array:t=>Array.isArray(t),string:t=>"string"==typeof t,function:t=>"function"==typeof t,promise:t=>t instanceof Promise,boolean:t=>"boolean"==typeof t,false:t=>!1===t,true:t=>!0===t};function e(t){return(e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t})(t)}function r(t,e){var r=Object.keys(t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(t);e&&(n=n.filter(function(e){return Object.getOwnPropertyDescriptor(t,e).enumerable})),r.push.apply(r,n)}return r}function n(t){for(var n=1;n<arguments.length;n++){var i=null!=arguments[n]?arguments[n]:{};n%2?r(Object(i),!0).forEach(function(r){!function(t,r,n){var i;(i=function(t,r){if("object"!=e(t)||!t)return t;var n=t[Symbol.toPrimitive];if(void 0!==n){var i=n.call(t,r||"default");if("object"!=e(i))return i;throw TypeError("@@toPrimitive must return a primitive value.")}return("string"===r?String:Number)(t)}(r,"string"),(r="symbol"==e(i)?i:i+"")in t)?Object.defineProperty(t,r,{value:n,enumerable:!0,configurable:!0,writable:!0}):t[r]=n}(t,r,i[r])}):Object.getOwnPropertyDescriptors?Object.defineProperties(t,Object.getOwnPropertyDescriptors(i)):r(Object(i)).forEach(function(e){Object.defineProperty(t,e,Object.getOwnPropertyDescriptor(i,e))})}return t}let i=e=>{var r,i,o,l;let s,a,u,f,c,m,b=e.init,p=e.states.includes(e.init)?[...e.states]:[...e.states,e.init],y=(s=new Map,{listen(t,e){var r;return s.has(t)||s.set(t,[]),null==(r=s.get(t))||r.push(e),()=>{this.unlisten(t,e)}},unlisten(t,e){let r=s.get(t);if(!r)return;let n=r.filter(t=>t!==e);n.length?s.set(t,n):s.delete(t)},emit(e,...r){var n,i;return null!=(n=null==(i=s.get(e))?void 0:i.map(t=>t(...r)).filter(t.not.ulx))?n:[]},unlistenAll(t){s.delete(t)}});Object.entries(null!=(r=e.methods)?r:{}).forEach(([t,e])=>{y.listen(t,e)}),y.listen("onAfterTransition",({to:t})=>{b=t}),y.listen("error",null!=(i=e.onError)?i:t=>{throw Error(`[FSM]: ${t}`)});let g={state:()=>b,allStates:()=>p},d=(o=e.transitions,a=((e,{state:r,allStates:n})=>{let i,o={},l={register(s,a){let u=r=>{n().includes(r.to)?r.to===r.from?e.emit("warn",`
+let t={nlx:t=>null===t,ulx:t=>void 0===t,nil:e=>t.nlx(e)||t.ulx(e),not:{nlx:t=>null!==t,ulx:t=>void 0!==t,nil:e=>t.not.nlx(e)&&t.not.ulx(e)},array:t=>Array.isArray(t),string:t=>"string"==typeof t,function:t=>"function"==typeof t,promise:t=>t instanceof Promise,boolean:t=>"boolean"==typeof t,false:t=>!1===t,true:t=>!0===t};function e(t){return(e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t})(t)}function r(t,e){var r=Object.keys(t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(t);e&&(n=n.filter(function(e){return Object.getOwnPropertyDescriptor(t,e).enumerable})),r.push.apply(r,n)}return r}function n(t){for(var n=1;n<arguments.length;n++){var i=null!=arguments[n]?arguments[n]:{};n%2?r(Object(i),!0).forEach(function(r){!function(t,r,n){var i;(i=function(t,r){if("object"!=e(t)||!t)return t;var n=t[Symbol.toPrimitive];if(void 0!==n){var i=n.call(t,r||"default");if("object"!=e(i))return i;throw TypeError("@@toPrimitive must return a primitive value.")}return("string"===r?String:Number)(t)}(r,"string"),(r="symbol"==e(i)?i:i+"")in t)?Object.defineProperty(t,r,{value:n,enumerable:!0,configurable:!0,writable:!0}):t[r]=n}(t,r,i[r])}):Object.getOwnPropertyDescriptors?Object.defineProperties(t,Object.getOwnPropertyDescriptors(i)):r(Object(i)).forEach(function(e){Object.defineProperty(t,e,Object.getOwnPropertyDescriptor(i,e))})}return t}let i=["onError","onWarn"],o=e=>{var r,o,l;let s,a,u,f,c,m,b=e.init,p=e.states.includes(e.init)?[...e.states]:[...e.states,e.init],y=(s=new Map,{listen(t,e){var r;return s.has(t)||s.set(t,[]),null==(r=s.get(t))||r.push(e),()=>{this.unlisten(t,e)}},unlisten(t,e){let r=s.get(t);if(!r)return;let n=r.filter(t=>t!==e);n.length?s.set(t,n):s.delete(t)},emit(e,...r){var n,i;return null!=(n=null==(i=s.get(e))?void 0:i.map(t=>t(...r)).filter(t.not.ulx))?n:[]},unlistenAll(t){s.delete(t)}}),g=null!=(r=e.methods)?r:{},{onError:v,onWarn:O}=g;Object.entries(function(t,e){if(null==t)return{};var r,n,i=function(t,e){if(null==t)return{};var r={};for(var n in t)if(({}).hasOwnProperty.call(t,n)){if(e.includes(n))continue;r[n]=t[n]}return r}(t,e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(t);for(n=0;n<o.length;n++)r=o[n],e.includes(r)||({}).propertyIsEnumerable.call(t,r)&&(i[r]=t[r])}return i}(g,i)).forEach(([t,e])=>{y.listen(t,e)}),y.listen("onAfterTransition",({to:t})=>{b=t}),y.listen("error",null!=v?v:t=>{throw Error(`[FSM]: ${t}`)}),O&&y.listen("warn",O);let d={state:()=>b,allStates:()=>p},h=(o=e.transitions,a=((e,{state:r,allStates:n})=>{let i,o={},l={register(s,a){let u=r=>{n().includes(r.to)?r.to===r.from?e.emit("warn",`
 						Transition: "${s}" is canceled because it's circular.
 						Current state is ${r.from}. Transition target state is ${r.to}
-					`):e.emit("onBeforeTransition",r).filter(t.boolean).every(t.true)&&e.emit("onAfterTransition",r):e.emit("error",`Transition: "${s}" can't be executed. It has invalid "to": "${r.to}"`)};return o[s]=(...n)=>{if(t.array(a.from)?!a.from.includes(r()):"*"!==a.from&&a.from!==r())return e.emit("error",`Transition: "${s}" is forbidden`),r();if(i)return e.emit("error",`Transition: "${s}" can't be made. Has pending transtion: "${i}"`),r();if(!t.function(a.to))return u({transition:s,from:r(),to:a.to}),r();let o=a.to(...n);return t.promise(o)?(i=s,o.then(t=>(i=void 0,u({transition:s,from:r(),to:t,args:n}),r()))):(u({transition:s,from:r(),to:o,args:n}),r())},l},make:()=>o};return l})(y,g),Object.entries(o).forEach(([t,e])=>a.register(t,e)),a.make()),v=(l=e.plugins,u={},f=n({init(t){y.listen("init",t)},onError:t=>y.listen("error",t),onBeforeTransition:t=>y.listen("onBeforeTransition",t),onAfterTransition:t=>y.listen("onAfterTransition",t)},g),m=c={register(t){let{name:e,api:r}=t(f);return e in u&&y.emit("error",`There are at least two plugins with the same name: "${e}"`),u[e]=r,c},make:()=>u},(null!=l?l:[]).forEach(m.register),m.make());return y.emit("init",b),n(n(n({},g),v),d)};export{i as makeFsm};
+					`,r):e.emit("onBeforeTransition",r).filter(t.boolean).every(t.true)&&e.emit("onAfterTransition",r):e.emit("error",`Transition: "${s}" can't be executed. It has invalid "to": "${r.to}"`,r)};return o[s]=(...n)=>{if(t.array(a.from)?!a.from.includes(r()):"*"!==a.from&&a.from!==r())return e.emit("error",`Transition: "${s}" is forbidden`),r();if(i)return e.emit("error",`Transition: "${s}" can't be made. Has pending transtion: "${i}"`),r();if(!t.function(a.to))return u({transition:s,from:r(),to:a.to}),r();let o=a.to(...n);return t.promise(o)?(i=s,o.then(t=>(i=void 0,u({transition:s,from:r(),to:t,args:n}),r()))):(u({transition:s,from:r(),to:o,args:n}),r())},l},make:()=>o};return l})(y,d),Object.entries(o).forEach(([t,e])=>a.register(t,e)),a.make()),j=(l=e.plugins,u={},f=n({init(t){y.listen("init",t)},onError:t=>y.listen("error",t),onWarn:t=>y.listen("warn",t),onBeforeTransition:t=>y.listen("onBeforeTransition",t),onAfterTransition:t=>y.listen("onAfterTransition",t)},d),m=c={register(t){let{name:e,api:r}=t(f);return e in u&&y.emit("error",`There are at least two plugins with the same name: "${e}"`),u[e]=r,c},make:()=>u},(null!=l?l:[]).forEach(m.register),m.make());return y.emit("init",b),n(n(n({},d),j),h)};export{o as makeFsm};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuxxx/fsm",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Lightweight, type-safe finite state machine for TypeScript with plugin support and lifecycle hooks",
   "keywords": [
     "finite state machine",