@uuxxx/fsm 1.2.1 → 1.2.3

package/README.md

@@ -1 +1,313 @@
-# Finite state machine
+# @uuxxx/fsm
+
+[![npm version](https://badge.fury.io/js/@uuxxx%2Ffsm.svg)](https://badge.fury.io/js/@uuxxx%2Ffsm)
+
+A lightweight, type-safe finite state machine library for JavaScript/TypeScript with plugin support and lifecycle hooks.
+
+## Installation
+
+```bash
+npm install @uuxxx/fsm
+# or
+pnpm add @uuxxx/fsm
+# or
+yarn add @uuxxx/fsm
+```
+
+## Quick Start
+
+```typescript
+import { makeFsm } from '@uuxxx/fsm';
+
+type 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
+    }
+  },
+});
+
+// Check current state
+console.log(fsm.state()); // 'idle'
+
+// Perform transitions
+fsm.start();
+console.log(fsm.state()); // 'loading'
+
+fsm.succeed();
+console.log(fsm.state()); // 'success'
+
+fsm.reset()
+console.log(fsm.state()) // 'idle'
+
+fsm.goto('error')
+console.log(fsm.state()) // 'error'
+```
+
+## API Reference
+
+### `makeFsm(config)`
+
+Creates a new finite state machine instance.
+
+#### Parameters
+
+- `config`: Configuration object with the following properties:
+  - `init`: Initial state
+  - `states`: Array of all possible states
+  - `transitions`: Object defining state transitions
+  - `methods?`: Optional lifecycle methods
+  - `plugins?`: Optional array of plugins
+
+#### Returns
+
+An FSM instance with transition methods, state methods, and plugin APIs.
+
+### State Methods
+
+#### `fsm.state()`
+
+Returns the current state.
+
+```typescript
+const currentState = fsm.state();
+```
+
+#### `fsm.allStates()`
+
+Returns an array of all possible states.
+
+```typescript
+const allStates = fsm.allStates();
+```
+
+### Transitions
+
+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`: The state(s) this transition can occur from
+  - Single state: `'idle'`
+  - Multiple states: `['loading', 'error']`
+  - Any state: `'*'`
+- `to`: The target state or a function returning the target state
+  - Static: `'loading'`
+  - 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';
+    },
+  },
+};
+```
+
+### Lifecycle Methods
+
+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);
+    },
+  },
+};
+```
+
+#### `onBeforeTransition(event)`
+
+Called before a transition occurs. Return `false` to cancel the transition.
+
+**Parameters:**
+- `event`: Object with `transition`, `from`, `to`, and optional `args`
+
+#### `onAfterTransition(event)`
+
+Called after a successful transition.
+
+**Parameters:**
+- `event`: Object with `transition`, `from`, `to`, and optional `args`
+
+## Plugins
+
+Plugins extend the FSM with additional functionality. Each plugin receives an API object and returns a plugin definition.
+
+### Plugin API
+
+Plugins have access to:
+
+- `api.state()`: Get current state
+- `api.allStates()`: Get all states
+- `api.init(callback)`: Register initialization callback
+- `api.onBeforeTransition(callback)`: Register before transition callback
+- `api.onAfterTransition(callback)`: Register after transition callback
+
+### 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();
+      },
+    },
+  };
+};
+```
+
+### Using Plugins
+
+```typescript
+const config = {
+  // ... other config
+  plugins: [myPlugin({ someOption: true })],
+};
+
+const fsm = makeFsm(config);
+
+// Access plugin API
+const currentState = fsm['my-plugin'].doSomething();
+```
+
+## Built-in Plugins
+
+### History Plugin
+
+Tracks state history and provides navigation methods.
+
+```typescript
+import { makeFsm, historyPlugin } from '@uuxxx/fsm';
+
+const config = {
+  // ... config
+  plugins: [historyPlugin()],
+};
+
+const fsm = makeFsm(config);
+
+// Navigate
+fsm.goto('state1');
+fsm.goto('state2');
+
+// History API
+console.log(fsm.history.get()); // ['initial', 'state1', 'state2']
+
+fsm.history.back(1); // Go back 1 step
+fsm.history.forward(1); // Go forward 1 step
+```
+
+#### 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
+}
+```
+
+## TypeScript Support
+
+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' },
+  },
+});
+// fsm is fully typed - autocomplete works for transitions and states
+```

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

@@ -1,10 +1,11 @@
-type AnyFn = (...args: any[]) => any;
-type Noop = () => void;
-type Rec<T = unknown> = Record<string, T>;
-type Key = string | number | symbol;
-type Vdx<T> = T | void;
-type KeyOf<T extends Rec> = keyof T;
-type Entries<T extends Rec> = { [K in KeyOf<T>]: [K, T[K]] }[KeyOf<T>];
+type AnyFn = (...args: any[]) => any; //#endregion
+type Rec<T = unknown> = Record<string, T>; //#endregion
+type KeyOf<T extends Rec> = keyof T; //#endregion
+type Noop = () => void; //#endregion
+type Key = string | number | symbol; //#endregion
+type Vdx<T> = T | void; //#endregion
+type EmptyArray = []; //#endregion
+type Entries<T extends Rec> = { [K in KeyOf<T>]: [K, T[K]] }[KeyOf<T>]; //#endregion
 type Label = string;
 type Transition<TState extends Label> = {
   from: '*' | TState | TState[];
@@ -34,4 +35,4 @@ type PluginApi = {
   api: Rec<AnyFn>;
 };
 type Plugin<TState extends Label = Label, TTransitions extends Rec<Transition<TState>> = Rec<Transition<TState>>> = (api: ApiForPlugin<TState, TTransitions>) => PluginApi;
-export { Transition as a, Rec as c, LifecycleMethods as i, Plugin as n, Label as o, StateMethods as r, KeyOf as s, ApiForPlugin as t };
+export { Transition as a, KeyOf as c, LifecycleMethods as i, Rec as l, Plugin as n, Label as o, StateMethods as r, EmptyArray as s, ApiForPlugin as t };

package/dist/history-plugin.d.ts

@@ -1,10 +1,10 @@
-import { a as Transition, c as Rec, o as Label, t as ApiForPlugin } from "./Plugin-C8fnOXt5.js";
+import { a as Transition, l as Rec, o as Label, t as ApiForPlugin } from "./Plugin-DGULTFg-.js";
 declare const historyPlugin: <TState extends Label, TTransitions extends Rec<Transition<TState>>>() => (api: ApiForPlugin<TState, TTransitions>) => {
   name: "history";
   api: {
-    get(): Label[];
-    back(steps: number): Label;
-    forward(steps: number): Label;
+    get(): TState[];
+    back(steps: number): TState;
+    forward(steps: number): TState;
   };
 };
 export { historyPlugin as fsmHistoryPlugin };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { a as Transition, c as Rec, i as LifecycleMethods, n as Plugin, o as Label, r as StateMethods, s as KeyOf } from "./Plugin-C8fnOXt5.js";
-type EmptyArray = [];
+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";
 type Config<TState extends Label, TTransitions extends Rec<Transition<TState>>, TPlugins extends Array<Plugin<TState, TTransitions>> = EmptyArray> = {
   init: TState;
   states: TState[];

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,p,y,g=e.init,v=(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])=>{v.listen(t,e)}),v.listen("onAfterTransition",({to:t})=>{g=t}),v.listen("error",t=>{throw Error(`[FSM]: ${t}`)});let O={state:()=>g,allStates:()=>[...e.states]},d=(i=e.transitions,o=O.state,u={},c=f={register(e,r){let n=r=>{r.to===r.from?v.emit("warn",`
-						Transition: "${e}" is canceled because it's circular.
+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",`
+						Transition: "${s}" is canceled because it's circular.
 						Current state is ${r.from}. Transition target state is ${r.to}
-					`):v.emit("onBeforeTransition",r).filter(t.boolean).every(t.true)&&v.emit("onAfterTransition",r)};return u[e]=(...i)=>{if(t.array(r.from)?!r.from.includes(o()):"*"!==r.from&&r.from!==o())return v.emit("error",`Transition: "${e}" is forbidden`),o();if(a)return v.emit("error",`Transition: "${e}" can't be made. Has pending transtion: "${a}"`),o();if(!t.function(r.to))return n({transition:e,from:o(),to:r.to}),o();let l=r.to(...i);return t.promise(l)?(a=e,l.then(t=>(a=void 0,n({transition:e,from:o(),to:t,args:i}),o()))):(n({transition:e,from:o(),to:l,args:i}),o())},f},make:()=>u},Object.entries(i).forEach(([t,e])=>c.register(t,e)),c.make()),h=(l=e.plugins,m={},b=n({init(t){v.listen("init",t)},onBeforeTransition:t=>v.listen("onBeforeTransition",t),onAfterTransition:t=>v.listen("onAfterTransition",t)},O),y=p={register(t){let{name:e,api:r}=t(b);return e in m&&v.emit("error",`There are at least two plugins with the same name: ${e}`),m[e]=r,p},make:()=>m},(null!=l?l:[]).forEach(y.register),y.make());return v.emit("init",g),n(n(n({},O),h),d)};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})(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};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuxxx/fsm",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "author": "Artem Tryapichnikov <golysheeet@gmail.com>",
   "license": "MIT",
   "description": "Javascript library for creating finite state machine",
@@ -18,10 +18,8 @@
     "fsm"
   ],
   "engines": {
-    "node": " >= 20",
-    "pnpm": ">= 10",
-    "npm": "Please use pnpm instead of yarn to install dependencies",
-    "yarn": "Please use pnpm instead of yarn to install dependencies"
+    "node": ">= 20",
+    "pnpm": ">= 10"
   },
   "files": [
     "dist",
@@ -44,26 +42,25 @@
     "@babel/preset-typescript": "^7.27.1",
     "@changesets/cli": "^2.29.7",
     "@swc/core": "^1.13.5",
-    "@types/jest": "^30.0.0",
-    "babel-jest": "^30.2.0",
     "eslint": "^9.37.0",
     "eslint-config-xo-typescript": "^9.0.0",
-    "jest": "^30.2.0",
-    "jiti": "^2.6.1",
     "lefthook": "^2.0.2",
     "rolldown": "^1.0.0-beta.41",
     "rolldown-plugin-dts": "^0.22.1",
     "rollup-plugin-swc3": "^0.12.1",
-    "ts-jest": "^29.4.4",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@uuxxx/utils": "^0.0.3"
   },
   "scripts": {
     "build": "rolldown -c rolldown.config.ts",
     "changeset:version": "changeset version && git add --all && git commit -m 'chore: bump'",
     "changeset:publish": "changeset publish",
-    "test": "jest",
+    "test": "vitest run",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "check:types": "tsc --noEmit"