@dixxanta08/stategate 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+import { TransitionParams } from "./types";
+export declare class AbortTransition extends Error {
+    details: TransitionParams;
+    constructor(params?: TransitionParams);
+}
+export declare class InvalidTransition extends Error {
+    details: TransitionParams;
+    constructor(params?: TransitionParams);
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidTransition = exports.AbortTransition = void 0;
+class AbortTransition extends Error {
+    constructor(params = {}) {
+        var _a;
+        super(params.message || "Aborting transition");
+        this.name = "AbortTransition";
+        this.details = {
+            timestamp: (_a = params.timestamp) !== null && _a !== void 0 ? _a : new Date(),
+            ...params,
+        };
+    }
+}
+exports.AbortTransition = AbortTransition;
+class InvalidTransition extends Error {
+    constructor(params = {}) {
+        var _a;
+        super(params.message || "Invalid transition");
+        this.name = "InvalidTransition";
+        this.details = {
+            timestamp: (_a = params.timestamp) !== null && _a !== void 0 ? _a : new Date(),
+            ...params,
+        };
+    }
+}
+exports.InvalidTransition = InvalidTransition;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { EventHandler, PreTransitionParams, PostTransitionParams, MachineConfig } from "./types";
+export declare class StateMachine {
+    private handlers;
+    private readonly config;
+    constructor(config: MachineConfig);
+    preTransition(params: PreTransitionParams): Promise<void>;
+    transition(entity: any, nextState: string, context?: {
+        actor: string;
+        meta?: any;
+    }): Promise<void>;
+    postTransition(params: PostTransitionParams): Promise<void>;
+    on(event: string, callback: EventHandler): void;
+    emit(event: string): void;
+}

package/dist/index.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateMachine = void 0;
+const errors_1 = require("./errors");
+class StateMachine {
+    constructor(config) {
+        var _a;
+        this.handlers = {};
+        const transitionKeys = Object.keys(config.transitions);
+        transitionKeys.forEach((tK) => {
+            const nextStates = Object.keys(config.transitions[tK]);
+            nextStates.forEach((nS) => {
+                if (config.transitions[tK][nS].isAbortable &&
+                    !config.transitions[tK][nS].onAbort) {
+                    config.transitions[tK][nS].onAbort = () => {
+                        console.log(`Aborting transition from ${tK} to ${nS}`);
+                    };
+                }
+            });
+        });
+        this.config = {
+            ...config,
+            stateKey: (_a = config.stateKey) !== null && _a !== void 0 ? _a : "status",
+        };
+    }
+    async preTransition(params) {
+        var _a;
+        const { currentState, nextState, nextTransition, allowedNextStates, entity, context, } = params;
+        if (!(nextState in allowedNextStates)) {
+            throw new errors_1.InvalidTransition({
+                message: "Invalid Transaction",
+                from: currentState,
+                to: nextState,
+                meta: context,
+            });
+        }
+        nextTransition.onBefore && (await nextTransition.onBefore(entity));
+        const beforeTransitionHooks = (_a = this.config.globalHooks) === null || _a === void 0 ? void 0 : _a.beforeTransition;
+        const payload = {
+            from: currentState,
+            to: nextState,
+            actor: context === null || context === void 0 ? void 0 : context.actor,
+            meta: context === null || context === void 0 ? void 0 : context.meta,
+            timestamp: new Date(),
+        };
+        const hooks = beforeTransitionHooks !== null && beforeTransitionHooks !== void 0 ? beforeTransitionHooks : [];
+        await Promise.all(hooks.map((fn) => fn(payload)));
+    }
+    async transition(entity, nextState, context) {
+        var _a, _b, _c, _d, _e, _f;
+        const stateKey = this.config.stateKey;
+        const currentState = entity[stateKey];
+        const allowedNextStates = this.config.transitions[currentState];
+        const nextTransition = allowedNextStates[nextState];
+        const entitySnapshot = structuredClone(entity);
+        try {
+            await this.preTransition({
+                currentState,
+                allowedNextStates,
+                nextState,
+                nextTransition,
+                entity,
+                context,
+            });
+            entity[stateKey] = nextState;
+            await this.postTransition({
+                currentState,
+                nextState,
+                entity,
+                nextTransition,
+                stateKey,
+                context,
+            });
+        }
+        catch (e) {
+            const error = e;
+            if (e instanceof errors_1.InvalidTransition) {
+                const invalidTransitionErrorPayload = {
+                    from: currentState,
+                    to: nextState,
+                    message: (error === null || error === void 0 ? void 0 : error.message) ? error.message : "Invalid transition.",
+                    timestamp: new Date(),
+                    meta: context,
+                };
+                (_b = (_a = this.config.globalHooks) === null || _a === void 0 ? void 0 : _a.onInvalidTransition) === null || _b === void 0 ? void 0 : _b.call(_a, invalidTransitionErrorPayload);
+            }
+            if ((nextTransition === null || nextTransition === void 0 ? void 0 : nextTransition.isAbortable) && e instanceof errors_1.AbortTransition) {
+                entity = structuredClone(entitySnapshot);
+                const abortTransitionErrorPayload = {
+                    from: currentState,
+                    to: nextState,
+                    message: (error === null || error === void 0 ? void 0 : error.message) ? error.message : "Aborting transition.",
+                    timestamp: new Date(),
+                    meta: context,
+                };
+                (_c = nextTransition.onAbort) === null || _c === void 0 ? void 0 : _c.call(nextTransition, abortTransitionErrorPayload);
+            }
+            else {
+                console.log("Abort Transition triggered but skipped over transition {isAbortable:false} ", error);
+            }
+            if ((_d = this.config.globalHooks) === null || _d === void 0 ? void 0 : _d.onError) {
+                const errorPaylaod = {
+                    from: currentState,
+                    to: nextState,
+                    message: (error === null || error === void 0 ? void 0 : error.message) ? error.message : "Aborting transition.",
+                    timestamp: new Date(),
+                    meta: context,
+                };
+                (_f = (_e = this.config.globalHooks) === null || _e === void 0 ? void 0 : _e.onError) === null || _f === void 0 ? void 0 : _f.call(_e, error, errorPaylaod);
+            }
+        }
+    }
+    async postTransition(params) {
+        var _a;
+        const { currentState, nextState, nextTransition, stateKey, entity, context, } = params;
+        if (entity[stateKey] !== nextState) {
+            throw new Error("Transition failed or had incongurencies");
+        }
+        nextTransition.onAfter && (await nextTransition.onAfter(entity));
+        const afterTransitionHooks = (_a = this.config.globalHooks) === null || _a === void 0 ? void 0 : _a.afterTransition;
+        const payload = {
+            from: currentState,
+            to: nextState,
+            actor: context === null || context === void 0 ? void 0 : context.actor,
+            meta: context === null || context === void 0 ? void 0 : context.meta,
+            timestamp: new Date(),
+        };
+        const hooks = afterTransitionHooks !== null && afterTransitionHooks !== void 0 ? afterTransitionHooks : [];
+        await Promise.all(hooks.map((fn) => fn(payload)));
+    }
+    on(event, callback) {
+        if (!this.handlers[event]) {
+            this.handlers[event] = [];
+        }
+        this.handlers[event].push(callback);
+    }
+    emit(event) {
+        this.handlers[event].forEach((fn) => fn());
+    }
+}
+exports.StateMachine = StateMachine;

package/dist/machine.js

@@ -0,0 +1 @@
+"use strict";

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+export type TransitionParams = {
+    from?: string;
+    to?: string;
+    message?: string;
+    timestamp?: Date;
+    meta?: any;
+};
+export type TransitionPayload = {
+    from: string;
+    to: string;
+    actor?: string;
+    meta?: any;
+    timestamp: Date;
+};
+export type EventHandler = (entity?: any) => Promise<void>;
+export type AbortHandler = (errorPaylaod?: AbortTransitionErrorPayload) => void;
+export type TransitionHandler = (payload: TransitionPayload) => Promise<void>;
+export type InvalidTransitionHandler = (payload: TransitionPayload) => void;
+export type ErrorTransitionHandler = (error: Error, payload: TransitionPayload) => void;
+export type TransitionConfig = {
+    isAbortable?: boolean;
+    onBefore?: EventHandler;
+    onAbort?: AbortHandler;
+    onAfter?: EventHandler;
+    details?: {
+        label: string;
+        description: string;
+        allowedActors: string;
+    };
+};
+export type PreTransitionParams = {
+    currentState: string;
+    allowedNextStates: Record<string, TransitionConfig>;
+    nextState: string;
+    nextTransition: TransitionConfig;
+    entity: any;
+    context?: {
+        actor?: string;
+        meta?: any;
+    };
+};
+export type PostTransitionParams = {
+    currentState: string;
+    nextState: string;
+    nextTransition: TransitionConfig;
+    entity: any;
+    stateKey: string;
+    context?: {
+        actor?: string;
+        meta?: any;
+    };
+};
+export type MachineConfig = {
+    initialState: string;
+    stateKey?: string;
+    transitions: Record<string, Record<string, TransitionConfig>>;
+    globalHooks?: {
+        beforeTransition?: TransitionHandler[];
+        afterTransition?: TransitionHandler[];
+        onInvalidTransition?: InvalidTransitionHandler;
+        onError?: ErrorTransitionHandler;
+    };
+};
+export type NormalizedMachineconfig = Omit<MachineConfig, "stateKey"> & {
+    stateKey: string;
+};
+export type BaseErrorPayload<TMeta = any> = {
+    message: string;
+    timestamp: Date;
+    meta?: TMeta;
+};
+export type AbortTransitionErrorPayload<TMeta = any> = BaseErrorPayload<TMeta> & {
+    from: string;
+    to: string;
+};
+export type GlobalErrorPayload<TMeta = any> = BaseErrorPayload<TMeta> & {
+    error: Error;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.js

@@ -0,0 +1 @@
+"use strict";

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dixxanta08/stategate",
+  "version": "0.1.0",
+  "description": "Deterministic state machine for backend workflows",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dixxanta08/stategate.git"
+  },
+  "homepage": "https://github.com/dixxanta08/stategate",
+  "bugs": {
+    "url": "https://github.com/dixxanta08/stategate/issues"
+  },
+  "keywords": [
+    "state-machine",
+    "orders",
+    "backend",
+    "ecommerce",
+    "fsm"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.1.2"
+  }
+}