@uuxxx/fsm 1.2.3 → 1.2.4

package/README.md

@@ -21,33 +21,33 @@ import { makeFsm } from '@uuxxx/fsm';
 
 type State = 'idle' | 'loading' | 'success' | 'error';
 
-const STATES: State[] = ['idle', 'loading', 'success', 'error']
+const STATES: State[] = ['idle', 'loading', 'success', 'error'];
 
 const fsm = makeFsm({
-  init: 'idle',
-  states: STATES,
-  transitions: {
-    start: {
-      from: 'idle',
-      to: 'loading',
-    },
-    succeed: {
-      from: 'loading',
-      to: 'success',
-    },
-    fail: {
-      from: 'loading',
-      to: 'error',
-    },
-    reset: {
-      from: ['success', 'error'],
-      to: 'idle',
-    },
-    goto: {
-      from: '*',
-      to: (state: State) => state
-    }
-  },
+	init: 'idle',
+	states: STATES,
+	transitions: {
+		start: {
+			from: 'idle',
+			to: 'loading',
+		},
+		succeed: {
+			from: 'loading',
+			to: 'success',
+		},
+		fail: {
+			from: 'loading',
+			to: 'error',
+		},
+		reset: {
+			from: ['success', 'error'],
+			to: 'idle',
+		},
+		goto: {
+			from: '*',
+			to: (state: State) => state,
+		},
+	},
 });
 
 // Check current state
@@ -60,11 +60,11 @@ console.log(fsm.state()); // 'loading'
 fsm.succeed();
 console.log(fsm.state()); // 'success'
 
-fsm.reset()
-console.log(fsm.state()) // 'idle'
+fsm.reset();
+console.log(fsm.state()); // 'idle'
 
-fsm.goto('error')
-console.log(fsm.state()) // 'error'
+fsm.goto('error');
+console.log(fsm.state()); // 'error'
 ```
 
 ## API Reference
@@ -110,8 +110,8 @@ Transitions are defined as objects with `from` and `to` properties:
 
 ```typescript
 type Transition<TState> = {
-  from: '*' | TState | TState[];
-  to: TState | ((...args: any[]) => TState | Promise<TState>);
+	from: '*' | TState | TState[];
+	to: TState | ((...args: any[]) => TState | Promise<TState>);
 };
 ```
 
@@ -121,39 +121,39 @@ type Transition<TState> = {
   - Any state: `'*'`
 - `to`: The target state or a function returning the target state
   - Static: `'loading'`
-  - Dynamic: `(userId: string) => \`user_\${userId}\``
+  - Dynamic: `(userId: string) => \`user\_\${userId}\``
   - Async: `async (data) => await apiCall(data)`
 
 #### Examples
 
 ```typescript
 const transitions = {
-  // Simple transition
-  'idle -> loading': {
-    from: 'idle',
-    to: 'loading',
-  },
-
-  // Multiple source states
-  reset: {
-    from: ['success', 'error'],
-    to: 'idle',
-  },
-
-  // Wildcard (from any state)
-  goto: {
-    from: '*',
-    to: (targetState: State) => targetState,
-  },
-
-  // Async transition
-  'async fetch': {
-    from: 'idle',
-    to: async () => {
-      const result = await fetchData();
-      return result.success ? 'success' : 'error';
-    },
-  },
+	// Simple transition
+	'idle -> loading': {
+		from: 'idle',
+		to: 'loading',
+	},
+
+	// Multiple source states
+	reset: {
+		from: ['success', 'error'],
+		to: 'idle',
+	},
+
+	// Wildcard (from any state)
+	goto: {
+		from: '*',
+		to: (targetState: State) => targetState,
+	},
+
+	// Async transition
+	'async fetch': {
+		from: 'idle',
+		to: async () => {
+			const result = await fetchData();
+			return result.success ? 'success' : 'error';
+		},
+	},
 };
 ```
 
@@ -163,17 +163,17 @@ Lifecycle methods can be attached to the FSM configuration:
 
 ```typescript
 const config = {
-  // ... other config
-  methods: {
-    onBeforeTransition: (event) => {
-      console.log('About to transition:', event);
-      // Return false to cancel the transition
-      return true;
-    },
-    onAfterTransition: (event) => {
-      console.log('Transition completed:', event);
-    },
-  },
+	// ... other config
+	methods: {
+		onBeforeTransition: (event) => {
+			console.log('About to transition:', event);
+			// Return false to cancel the transition
+			return true;
+		},
+		onAfterTransition: (event) => {
+			console.log('Transition completed:', event);
+		},
+	},
 };
 ```
 
@@ -182,6 +182,7 @@ const config = {
 Called before a transition occurs. Return `false` to cancel the transition.
 
 **Parameters:**
+
 - `event`: Object with `transition`, `from`, `to`, and optional `args`
 
 #### `onAfterTransition(event)`
@@ -189,6 +190,7 @@ Called before a transition occurs. Return `false` to cancel the transition.
 Called after a successful transition.
 
 **Parameters:**
+
 - `event`: Object with `transition`, `from`, `to`, and optional `args`
 
 ## Plugins
@@ -208,42 +210,34 @@ Plugins have access to:
 ### Creating a Plugin
 
 ```typescript
-const myPlugin = (options) => (api) => {
-  // Plugin initialization
-  api.init((initialState) => {
-    console.log('FSM initialized with state:', initialState);
-  });
-
-  // Listen to transitions
-  api.onBeforeTransition((event) => {
-    console.log('Transition starting:', event);
-  });
-
-  // Return plugin definition
-  return {
-    name: 'my-plugin',
-    api: {
-      // Custom methods exposed on fsm['my-plugin']
-      doSomething: () => {
-        return api.state();
-      },
-    },
-  };
-};
+import type { FsmLabel, FsmPlugin, FsmTransition } from '@uuxxx/fsm';
+
+export const somePlugin = <TState extends FsmLabel, TTransitions extends Record<string, FsmTransition<TState>>>() =>
+	((api) => {
+		// ... plugin code
+
+		return {
+			// replace with your plugin name
+			name: 'plugin-name' as const,
+			api: {
+				// ... plugin methods
+			},
+		};
+	}) satisfies FsmPlugin<TState, TTransitions>;
 ```
 
 ### Using Plugins
 
 ```typescript
 const config = {
-  // ... other config
-  plugins: [myPlugin({ someOption: true })],
+	// ... other config
+	plugins: [somePlugin({ someOption: true })],
 };
 
 const fsm = makeFsm(config);
 
 // Access plugin API
-const currentState = fsm['my-plugin'].doSomething();
+const currentState = fsm['plugin-name'].doSomething();
 ```
 
 ## Built-in Plugins
@@ -253,11 +247,12 @@ const currentState = fsm['my-plugin'].doSomething();
 Tracks state history and provides navigation methods.
 
 ```typescript
-import { makeFsm, historyPlugin } from '@uuxxx/fsm';
+import { makeFsm } from '@uuxxx/fsm';
+import { fsmHistoryPlugin } from '@uuxxx/fsm/history-plugin';
 
 const config = {
-  // ... config
-  plugins: [historyPlugin()],
+	// ... config
+	plugins: [fsmHistoryPlugin()],
 };
 
 const fsm = makeFsm(config);
@@ -267,34 +262,17 @@ fsm.goto('state1');
 fsm.goto('state2');
 
 // History API
-console.log(fsm.history.get()); // ['initial', 'state1', 'state2']
+console.log(fsm.history.get()); // Get all history
 
-fsm.history.back(1); // Go back 1 step
-fsm.history.forward(1); // Go forward 1 step
+fsm.history.back(1); // Get 1 step back
+fsm.history.forward(1); // Get 1 step forward
 ```
 
 #### History API Methods
 
 - `fsm.history.get()`: Get the full history array
-- `fsm.history.back(steps?)`: Go back N steps (default: 1)
-- `fsm.history.forward(steps?)`: Go forward N steps (default: 1)
-
-## Error Handling
-
-The FSM throws errors in the following cases:
-
-- Invalid transition (current state doesn't match `from`)
-- Pending async transition when starting a new sync transition
-- Invalid target state
-- Duplicate plugin names
-
-```typescript
-try {
-  fsm.invalidTransition();
-} catch (error) {
-  console.error(error.message); // [FSM]: Transition: "invalidTransition" is forbidden
-}
-```
+- `fsm.history.back(steps?)`: Get N step back (default: 1)
+- `fsm.history.forward(steps?)`: Get N step forward (default: 1)
 
 ## TypeScript Support
 
@@ -302,12 +280,12 @@ The library is fully typed. Type inference works automatically:
 
 ```typescript
 const fsm = makeFsm({
-  init: 'idle',
-  states: ['idle', 'running', 'stopped'],
-  transitions: {
-    start: { from: 'idle', to: 'running' },
-    stop: { from: 'running', to: 'stopped' },
-  },
+	init: 'idle',
+	states: ['idle', 'running', 'stopped'],
+	transitions: {
+		start: { from: 'idle', to: 'running' },
+		stop: { from: 'running', to: 'stopped' },
+	},
 });
 // fsm is fully typed - autocomplete works for transitions and states
 ```

package/dist/{Plugin-DGULTFg-.d.ts → Plugin-Dx6AAZEC.d.ts}

@@ -29,6 +29,7 @@ type StateMethods<TState extends Label> = {
 };
 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 };
 type PluginApi = {
   name: string;

package/dist/history-plugin.d.ts

@@ -1,4 +1,4 @@
-import { a as Transition, l as Rec, o as Label, t as ApiForPlugin } from "./Plugin-DGULTFg-.js";
+import { a as Transition, l as Rec, o as Label, t as ApiForPlugin } from "./Plugin-Dx6AAZEC.js";
 declare const historyPlugin: <TState extends Label, TTransitions extends Rec<Transition<TState>>>() => (api: ApiForPlugin<TState, TTransitions>) => {
   name: "history";
   api: {

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-import { a as Transition, c as KeyOf, i as LifecycleMethods, l as Rec, n as Plugin, o as Label, r as StateMethods, s as EmptyArray } from "./Plugin-DGULTFg-.js";
+import { a as Transition, c as KeyOf, i as LifecycleMethods, l as Rec, n as Plugin, o as Label, r as StateMethods, s as EmptyArray } from "./Plugin-Dx6AAZEC.js";
 type Config<TState extends Label, TTransitions extends Rec<Transition<TState>>, TPlugins extends Array<Plugin<TState, TTransitions>> = EmptyArray> = {
   init: TState;
   states: TState[];
   transitions: TTransitions;
   methods?: LifecycleMethods<TState, TTransitions>;
   plugins?: TPlugins;
+  onError?: (msg: string) => void;
 };
 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;let l,s,a,u,f,c,m=e.init,b=e.states.includes(e.init)?[...e.states]:[...e.states,e.init],p=(l=new Map,{listen(t,e){var r;return l.has(t)||l.set(t,[]),null==(r=l.get(t))||r.push(e),()=>{this.unlisten(t,e)}},unlisten(t,e){let r=l.get(t);if(!r)return;let n=r.filter(t=>t!==e);n.length?l.set(t,n):l.delete(t)},emit(e,...r){var n,i;return null!=(n=null==(i=l.get(e))?void 0:i.map(t=>t(...r)).filter(t.not.ulx))?n:[]},unlistenAll(t){l.delete(t)}});Object.entries(null!=(r=e.methods)?r:{}).forEach(([t,e])=>{p.listen(t,e)}),p.listen("onAfterTransition",({to:t})=>{m=t}),p.listen("error",t=>{throw Error(`[FSM]: ${t}`)});let y={state:()=>m,allStates:()=>b},g=(i=e.transitions,s=((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=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",`
 						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})(p,y),Object.entries(i).forEach(([t,e])=>s.register(t,e)),s.make()),d=(o=e.plugins,a={},u=n({init(t){p.listen("init",t)},onBeforeTransition:t=>p.listen("onBeforeTransition",t),onAfterTransition:t=>p.listen("onAfterTransition",t)},y),c=f={register(t){let{name:e,api:r}=t(u);return e in a&&p.emit("error",`There are at least two plugins with the same name: "${e}"`),a[e]=r,f},make:()=>a},(null!=o?o:[]).forEach(c.register),c.make());return p.emit("init",m),n(n(n({},y),d),g)};export{i as makeFsm};
+					`):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};

package/package.json

@@ -1,31 +1,24 @@
 {
   "name": "@uuxxx/fsm",
-  "version": "1.2.3",
-  "author": "Artem Tryapichnikov <golysheeet@gmail.com>",
-  "license": "MIT",
+  "version": "1.2.4",
   "description": "Javascript library for creating finite state machine",
-  "homepage": "https://github.com/uuxxx/fsm/blob/main/README.md",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/uuxxx/fsm.git"
-  },
   "keywords": [
     "finite state machine",
     "fsm"
   ],
-  "engines": {
-    "node": ">= 20",
-    "pnpm": ">= 10"
+  "homepage": "https://github.com/uuxxx/fsm/blob/main/README.md",
+  "license": "MIT",
+  "author": "Artem Tryapichnikov <golysheeet@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uuxxx/fsm.git"
   },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -36,15 +29,22 @@
       "default": "./dist/history-plugin.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@uuxxx/utils": "^0.0.3"
+  },
   "devDependencies": {
     "@babel/core": "^7.28.4",
     "@babel/preset-env": "^7.28.3",
     "@babel/preset-typescript": "^7.27.1",
     "@changesets/cli": "^2.29.7",
     "@swc/core": "^1.13.5",
-    "eslint": "^9.37.0",
-    "eslint-config-xo-typescript": "^9.0.0",
     "lefthook": "^2.0.2",
+    "oxfmt": "^0.41.0",
+    "oxlint": "^1.0.0",
+    "oxlint-tsgolint": "^0.17.0",
     "rolldown": "^1.0.0-beta.41",
     "rolldown-plugin-dts": "^0.22.1",
     "rollup-plugin-swc3": "^0.12.1",
@@ -53,16 +53,19 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "dependencies": {
-    "@uuxxx/utils": "^0.0.3"
+  "engines": {
+    "node": ">= 20",
+    "pnpm": ">= 10"
   },
   "scripts": {
     "build": "rolldown -c rolldown.config.ts",
     "changeset:version": "changeset version && git add --all && git commit -m 'chore: bump'",
     "changeset:publish": "changeset publish",
     "test": "vitest run",
-    "lint": "eslint",
-    "lint:fix": "eslint --fix",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt --write .",
+    "fmt:check": "oxfmt --check .",
     "check:types": "tsc --noEmit"
   }
 }