@alwatr/fsm 0.30.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.30.0](https://github.com/AliMD/alwatr/compare/v0.29.0...v0.30.0) (2023-03-06)
+
+### Bug Fixes
+
+- **fsm:** every signal mather ([0dc504d](https://github.com/AliMD/alwatr/commit/0dc504dacbb1ec68f154244619d644ff8e43cc04))
+- **fsm:** remove additional import ([231337b](https://github.com/AliMD/alwatr/commit/231337b95ee7b046fe35429f50931ddf85be291f))
+- **fsm:** update context in transition bug ([28a21d0](https://github.com/AliMD/alwatr/commit/28a21d00d903b6189d814303c72ba6e784852f33))
+
+### Features
+
+- Alwatr Finite State Machines ([d5900b4](https://github.com/AliMD/alwatr/commit/d5900b4ee8685b120188888871405853f5a69417))
+- **fsm:** $all and $self state ([69adf41](https://github.com/AliMD/alwatr/commit/69adf41064ca0f55497484c50e298ebc26c42dcc))
+- **fsm:** enhance types ([3b13046](https://github.com/AliMD/alwatr/commit/3b130463a102f59c38603b0de470be5c87ee88c9))
+- **fsm:** make simple state machine ([ff9ae1c](https://github.com/AliMD/alwatr/commit/ff9ae1ca04156e8b811899ff0f62480e1c37af72))
+- **fsm:** new state context type with {to, from, by} ([11423e6](https://github.com/AliMD/alwatr/commit/11423e6a89159b92e82cfd1e774ad37983581090))
+- **fsm:** rewrite with signal power ([01a1651](https://github.com/AliMD/alwatr/commit/01a1651e231a817d5eebb54cf84d51d620bfd6e8))
+- **fsm:** share state events ([de42522](https://github.com/AliMD/alwatr/commit/de42522a97fdf6be8bee73d91a35820e2a5e6efb))
+- **fsm:** transition with partial context set ([823377e](https://github.com/AliMD/alwatr/commit/823377e65028ea3e713f060ae678776c609c1661))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 S. Ali Mihandoost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Alwatr Finite State Machines - `@alwatr/fsm`
+
+Managing invocations finite-state machines as actors written in tiny TypeScript module.

package/core.d.ts

@@ -0,0 +1,54 @@
+import type { Stringifyable, StringifyableRecord } from '@alwatr/type';
+export interface MachineConfig<TState extends string, TEventId extends string, TContext extends Stringifyable> extends StringifyableRecord {
+    /**
+     * Machine ID (It is used in the state change signal identifier, so it must be unique).
+     */
+    id: string;
+    /**
+     * Initial state.
+     */
+    initial: TState;
+    /**
+     * Initial context.
+     */
+    context: TContext;
+    /**
+     * States list
+     */
+    states: {
+        [S in TState | '$all']: {
+            /**
+             * An object mapping eventId (keys) to state.
+             */
+            on: {
+                [E in TEventId]?: TState | '$self';
+            };
+        };
+    };
+}
+export interface StateContext<TState extends string, TEventId extends string> {
+    [T: string]: string;
+    to: TState;
+    from: TState | 'init';
+    by: TEventId | 'INIT';
+}
+export declare class FiniteStateMachine<TState extends string = string, TEventId extends string = string, TContext extends StringifyableRecord = StringifyableRecord> {
+    readonly config: Readonly<MachineConfig<TState, TEventId, TContext>>;
+    state: StateContext<TState, TEventId>;
+    context: TContext;
+    signal: {
+        readonly id: string;
+        readonly getValue: () => StateContext<TState, TEventId> | undefined;
+        readonly untilChange: () => Promise<StateContext<TState, TEventId>>;
+        readonly subscribe: (listenerCallback: import("@alwatr/signal/type.js").ListenerFunction<StateContext<TState, TEventId>>, options?: Partial<import("@alwatr/signal/type.js").SubscribeOptions> | undefined) => import("@alwatr/signal").ListenerSpec;
+        readonly unsubscribe: (listener: import("@alwatr/signal").ListenerSpec) => void;
+    };
+    protected _logger: import("@alwatr/logger").AlwatrLogger;
+    protected setState(to: TState, by: TEventId | 'INIT'): void;
+    constructor(config: Readonly<MachineConfig<TState, TEventId, TContext>>);
+    /**
+     * Machine transition.
+     */
+    transition(event: TEventId, context?: Partial<TContext>): TState | null;
+}
+//# sourceMappingURL=core.d.ts.map

package/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["src/core.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,aAAa,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAOrE,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM,EAAE,QAAQ,SAAS,aAAa,CAC3G,SAAQ,mBAAmB;IAC3B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,EAAE,QAAQ,CAAC;IAElB;;OAEG;IACH,MAAM,EAAE;SACL,CAAC,IAAI,MAAM,GAAG,MAAM,GAAG;YACtB;;eAEG;YACH,EAAE,EAAE;iBACD,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;aACnC,CAAC;SACH;KACF,CAAC;CACH;AAED,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,MAAM,EAAE,QAAQ,SAAS,MAAM;IAC1E,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,EAAE,EAAE,QAAQ,GAAG,MAAM,CAAC;CACvB;AAED,qBAAa,kBAAkB,CAC7B,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,QAAQ,SAAS,MAAM,GAAG,MAAM,EAChC,QAAQ,SAAS,mBAAmB,GAAG,mBAAmB;aAqB9B,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAnBvF,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAInC;IACF,OAAO,WAAuB;IAC9B,MAAM;;;;;;MAAkG;IAExG,SAAS,CAAC,OAAO,wCAAgD;IAEjE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI;gBAS/B,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAQvF;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,GAAG,IAAI;CAoCxE"}

package/core.js

@@ -0,0 +1,63 @@
+import { createLogger, globalAlwatr } from '@alwatr/logger';
+import { contextConsumer } from '@alwatr/signal';
+import { dispatch } from '@alwatr/signal/core.js';
+globalAlwatr.registeredList.push({
+    name: '@alwatr/fsm',
+    version: _ALWATR_VERSION_,
+});
+export class FiniteStateMachine {
+    setState(to, by) {
+        var _a, _b;
+        this.state = {
+            to,
+            from: (_b = (_a = this.signal.getValue()) === null || _a === void 0 ? void 0 : _a.to) !== null && _b !== void 0 ? _b : 'init',
+            by,
+        };
+        dispatch(this.signal.id, this.state, { debounce: 'NextCycle' });
+    }
+    constructor(config) {
+        this.config = config;
+        this.state = {
+            to: this.config.initial,
+            from: 'init',
+            by: 'INIT',
+        };
+        this.context = this.config.context;
+        this.signal = contextConsumer.bind('finite-state-machine-' + this.config.id);
+        this._logger = createLogger(`alwatr/fsm:${this.config.id}`);
+        this._logger.logMethodArgs('constructor', config);
+        dispatch(this.signal.id, this.state, { debounce: 'NextCycle' });
+        if (!config.states[config.initial]) {
+            this._logger.error('constructor', 'invalid_initial_state', config);
+        }
+    }
+    /**
+     * Machine transition.
+     */
+    transition(event, context) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const fromState = this.state.to;
+        let toState = (_c = (_b = (_a = this.config.states[fromState]) === null || _a === void 0 ? void 0 : _a.on) === null || _b === void 0 ? void 0 : _b[event]) !== null && _c !== void 0 ? _c : (_e = (_d = this.config.states.$all) === null || _d === void 0 ? void 0 : _d.on) === null || _e === void 0 ? void 0 : _e[event];
+        if (toState === '$self') {
+            toState = fromState;
+        }
+        this._logger.logMethodFull('transition', { fromState, event, context }, toState);
+        if (context !== undefined) {
+            this.context = {
+                ...this.context,
+                ...context,
+            };
+        }
+        if (toState == null) {
+            this._logger.incident('transition', 'invalid_target_state', 'Defined target state for this event not found in state config', {
+                fromState,
+                event,
+                events: { ...(_f = this.config.states.$all) === null || _f === void 0 ? void 0 : _f.on, ...(_g = this.config.states[fromState]) === null || _g === void 0 ? void 0 : _g.on },
+            });
+            return null;
+        }
+        this.setState(toState, event);
+        return toState;
+    }
+}
+//# sourceMappingURL=core.js.map

package/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["src/core.ts"],"names":[],"mappings":"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","sourcesContent":["import {createLogger, globalAlwatr} from '@alwatr/logger';\nimport {contextConsumer} from '@alwatr/signal';\nimport {dispatch} from '@alwatr/signal/core.js';\n\nimport type {Stringifyable, StringifyableRecord} from '@alwatr/type';\n\nglobalAlwatr.registeredList.push({\n  name: '@alwatr/fsm',\n  version: _ALWATR_VERSION_,\n});\n\nexport interface MachineConfig<TState extends string, TEventId extends string, TContext extends Stringifyable>\n  extends StringifyableRecord {\n  /**\n   * Machine ID (It is used in the state change signal identifier, so it must be unique).\n   */\n  id: string;\n\n  /**\n   * Initial state.\n   */\n  initial: TState;\n\n  /**\n   * Initial context.\n   */\n  context: TContext;\n\n  /**\n   * States list\n   */\n  states: {\n    [S in TState | '$all']: {\n      /**\n       * An object mapping eventId (keys) to state.\n       */\n      on: {\n        [E in TEventId]?: TState | '$self';\n      };\n    };\n  };\n}\n\nexport interface StateContext<TState extends string, TEventId extends string> {\n  [T: string]: string;\n  to: TState;\n  from: TState | 'init';\n  by: TEventId | 'INIT';\n}\n\nexport class FiniteStateMachine<\n  TState extends string = string,\n  TEventId extends string = string,\n  TContext extends StringifyableRecord = StringifyableRecord\n> {\n  state: StateContext<TState, TEventId> = {\n    to: this.config.initial,\n    from: 'init',\n    by: 'INIT',\n  };\n  context = this.config.context;\n  signal = contextConsumer.bind<StateContext<TState, TEventId>>('finite-state-machine-' + this.config.id);\n\n  protected _logger = createLogger(`alwatr/fsm:${this.config.id}`);\n\n  protected setState(to: TState, by: TEventId | 'INIT'): void {\n    this.state = {\n      to,\n      from: this.signal.getValue()?.to ?? 'init',\n      by,\n    };\n    dispatch<StateContext<TState, TEventId>>(this.signal.id, this.state, {debounce: 'NextCycle'});\n  }\n\n  constructor(public readonly config: Readonly<MachineConfig<TState, TEventId, TContext>>) {\n    this._logger.logMethodArgs('constructor', config);\n    dispatch<StateContext<TState, TEventId>>(this.signal.id, this.state, {debounce: 'NextCycle'});\n    if (!config.states[config.initial]) {\n      this._logger.error('constructor', 'invalid_initial_state', config);\n    }\n  }\n\n  /**\n   * Machine transition.\n   */\n  transition(event: TEventId, context?: Partial<TContext>): TState | null {\n    const fromState = this.state.to;\n\n    let toState: TState | '$self' | undefined =\n      this.config.states[fromState]?.on?.[event] ?? this.config.states.$all?.on?.[event];\n\n    if (toState === '$self') {\n      toState = fromState;\n    }\n\n    this._logger.logMethodFull('transition', {fromState, event, context}, toState);\n\n    if (context !== undefined) {\n      this.context = {\n        ...this.context,\n        ...context,\n      };\n    }\n\n    if (toState == null) {\n      this._logger.incident(\n          'transition',\n          'invalid_target_state',\n          'Defined target state for this event not found in state config',\n          {\n            fromState,\n            event,\n            events: {...this.config.states.$all?.on, ...this.config.states[fromState]?.on},\n          },\n      );\n      return null;\n    }\n\n    this.setState(toState, event);\n    return toState;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@alwatr/fsm",
+  "version": "0.30.0",
+  "description": "Managing invocations finite-state machines as actors written in tiny TypeScript module.",
+  "keywords": [
+    "state",
+    "finite",
+    "machine",
+    "typescript",
+    "esm",
+    "alwatr"
+  ],
+  "main": "core.js",
+  "type": "module",
+  "types": "core.d.ts",
+  "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com>",
+  "license": "MIT",
+  "files": [
+    "**/*.{d.ts.map,d.ts,js.map,js,html,md}"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AliMD/alwatr",
+    "directory": "core/fsm"
+  },
+  "homepage": "https://github.com/AliMD/alwatr/tree/main/core/fsm#readme",
+  "bugs": {
+    "url": "https://github.com/AliMD/alwatr/issues"
+  },
+  "dependencies": {
+    "@alwatr/logger": "^0.30.0",
+    "@alwatr/signal": "^0.30.0",
+    "@alwatr/type": "^0.30.0",
+    "tslib": "^2.5.0"
+  },
+  "gitHead": "36f55780ccdcb1acc07400b0cdb3fe7b0df56cca"
+}