@praxisjs/fsm 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @praxisjs/fsm
+
+## 0.1.0
+
+### Minor Changes
+
+- aaf7dab: Initial beta release
+
+### Patch Changes
+
+- Updated dependencies [aaf7dab]
+  - @praxisjs/core@0.1.0
+  - @praxisjs/shared@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Mateus Martins
+
+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/dist/decorators.d.ts

@@ -0,0 +1,6 @@
+import { type MachineDefinition } from "./machine";
+export declare function Transition(machineProp: string, event: string): (_target: object, methodKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function StateMachine<S extends string, E extends string>(definition: MachineDefinition<S, E>, propertyKey?: string): (target: {
+    prototype: object;
+}) => void;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEhF,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,IAEzD,SAAS,MAAM,EACf,WAAW,MAAM,EACjB,YAAY,kBAAkB,KAC7B,kBAAkB,CA2BtB;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAC7D,UAAU,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EACnC,WAAW,SAAY,IAEN,QAAQ;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,IAAI,CAWtD"}

package/dist/decorators.js

@@ -0,0 +1,42 @@
+import { createMachine } from "./machine";
+export function Transition(machineProp, event) {
+    return function (_target, methodKey, descriptor) {
+        const original = descriptor.value;
+        return {
+            configurable: true,
+            enumerable: false,
+            get() {
+                const bound = (...args) => {
+                    const machine = this[machineProp];
+                    if (!machine) {
+                        console.warn(`[Transition] "${machineProp}" is not a state machine.`);
+                        return;
+                    }
+                    if (machine.send(event))
+                        return original.apply(this, args);
+                };
+                Object.defineProperty(this, methodKey, {
+                    value: bound,
+                    configurable: true,
+                    writable: true,
+                });
+                return bound;
+            },
+        };
+    };
+}
+export function StateMachine(definition, propertyKey = "machine") {
+    return function (target) {
+        const machines = new WeakMap();
+        Object.defineProperty(target.prototype, propertyKey, {
+            get() {
+                if (!machines.has(this))
+                    machines.set(this, createMachine(definition));
+                return machines.get(this);
+            },
+            enumerable: true,
+            configurable: true,
+        });
+    };
+}
+//# sourceMappingURL=decorators.js.map

package/dist/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAwC,MAAM,WAAW,CAAC;AAEhF,MAAM,UAAU,UAAU,CAAC,WAAmB,EAAE,KAAa;IAC3D,OAAO,UACL,OAAe,EACf,SAAiB,EACjB,UAA8B;QAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAwC,CAAC;QACrE,OAAO;YACL,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,KAAK;YACjB,GAAG;gBACD,MAAM,KAAK,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE;oBACnC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAEnB,CAAC;oBACd,IAAI,CAAC,OAAO,EAAE,CAAC;wBACb,OAAO,CAAC,IAAI,CACV,iBAAiB,WAAW,2BAA2B,CACxD,CAAC;wBACF,OAAO;oBACT,CAAC;oBACD,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;wBAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC7D,CAAC,CAAC;gBACF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE;oBACrC,KAAK,EAAE,KAAK;oBACZ,YAAY,EAAE,IAAI;oBAClB,QAAQ,EAAE,IAAI;iBACf,CAAC,CAAC;gBACH,OAAO,KAAK,CAAC;YACf,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,UAAmC,EACnC,WAAW,GAAG,SAAS;IAEvB,OAAO,UAAU,MAA6B;QAC5C,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAyB,CAAC;QACtD,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE;YACnD,GAAG;gBACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;gBACvE,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAkB,CAAC;YAC7C,CAAC;YACD,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createMachine } from "./machine";
+export type { Machine, MachineDefinition, StateMap } from "./machine";
+export { Transition, StateMachine } from "./decorators";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createMachine } from "./machine";
+export { Transition, StateMachine } from "./decorators";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/machine.d.ts

@@ -0,0 +1,25 @@
+import type { Computed } from "@praxisjs/shared";
+export type StateMap<S extends string, E extends string> = Record<S, {
+    on?: Partial<Record<E, S>>;
+    onEnter?: () => void;
+    onExit?: () => void;
+}>;
+export interface MachineDefinition<S extends string, E extends string> {
+    initial: S;
+    states: StateMap<S, E>;
+    onTransition?: (from: S, event: E, to: S) => void;
+}
+export interface Machine<S extends string, E extends string> {
+    state: Computed<S>;
+    history: Computed<Array<{
+        from: S;
+        event: E;
+        to: S;
+    }>>;
+    send(event: E): boolean;
+    can(event: E): boolean;
+    is(state: S): boolean;
+    reset(): void;
+}
+export declare function createMachine<S extends string, E extends string>(definition: MachineDefinition<S, E>): Machine<S, E>;
+//# sourceMappingURL=machine.d.ts.map

package/dist/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,MAAM,CAAC,CAAC,EAAE;IACjE,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC,CAAC;AAEL,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM;IACnE,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM;IACzD,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACnB,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC;QAAC,EAAE,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC,CAAC;IACvD,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;IACxB,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;IACvB,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;IACtB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAC9D,UAAU,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CA8Bf"}

package/dist/machine.js

@@ -0,0 +1,31 @@
+import { signal, computed } from "@praxisjs/core";
+export function createMachine(definition) {
+    const _state = signal(definition.initial);
+    const _history = signal([]);
+    function send(event) {
+        const current = _state();
+        const nextState = definition.states[current].on?.[event];
+        if (!nextState)
+            return false;
+        definition.states[current].onExit?.();
+        _state.set(nextState);
+        _history.update((h) => [...h, { from: current, event, to: nextState }]);
+        definition.onTransition?.(current, event, nextState);
+        definition.states[nextState].onEnter?.();
+        return true;
+    }
+    return {
+        state: computed(() => _state()),
+        history: computed(() => _history()),
+        send,
+        can: (event) => !!definition.states[_state()].on?.[event],
+        is: (state) => _state() === state,
+        reset: () => {
+            definition.states[_state()].onExit?.();
+            _state.set(definition.initial);
+            _history.set([]);
+            definition.states[definition.initial].onEnter?.();
+        },
+    };
+}
+//# sourceMappingURL=machine.js.map

package/dist/machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.js","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAwBlD,MAAM,UAAU,aAAa,CAC3B,UAAmC;IAEnC,MAAM,MAAM,GAAG,MAAM,CAAI,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAM,CAAsC,EAAE,CAAC,CAAC;IAEjE,SAAS,IAAI,CAAC,KAAQ;QACpB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QACzD,IAAI,CAAC,SAAS;YAAE,OAAO,KAAK,CAAC;QAE7B,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtB,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QACxE,UAAU,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QACrD,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;QAC/B,OAAO,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;QACnC,IAAI;QACJ,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC;QACzD,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK;QACjC,KAAK,EAAE,GAAG,EAAE;YACV,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjB,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@praxisjs/fsm",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@praxisjs/core": "0.1.0",
+    "@praxisjs/shared": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}

package/src/decorators.ts

@@ -0,0 +1,52 @@
+import { createMachine, type Machine, type MachineDefinition } from "./machine";
+
+export function Transition(machineProp: string, event: string) {
+  return function (
+    _target: object,
+    methodKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor {
+    const original = descriptor.value as (...args: unknown[]) => unknown;
+    return {
+      configurable: true,
+      enumerable: false,
+      get(this: Record<string, unknown>) {
+        const bound = (...args: unknown[]) => {
+          const machine = this[machineProp] as
+            | Machine<string, string>
+            | undefined;
+          if (!machine) {
+            console.warn(
+              `[Transition] "${machineProp}" is not a state machine.`,
+            );
+            return;
+          }
+          if (machine.send(event)) return original.apply(this, args);
+        };
+        Object.defineProperty(this, methodKey, {
+          value: bound,
+          configurable: true,
+          writable: true,
+        });
+        return bound;
+      },
+    };
+  };
+}
+
+export function StateMachine<S extends string, E extends string>(
+  definition: MachineDefinition<S, E>,
+  propertyKey = "machine",
+) {
+  return function (target: { prototype: object }): void {
+    const machines = new WeakMap<object, Machine<S, E>>();
+    Object.defineProperty(target.prototype, propertyKey, {
+      get(this: object): Machine<S, E> {
+        if (!machines.has(this)) machines.set(this, createMachine(definition));
+        return machines.get(this) as Machine<S, E>;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createMachine } from "./machine";
+export type { Machine, MachineDefinition, StateMap } from "./machine";
+export { Transition, StateMachine } from "./decorators";

package/src/machine.ts

@@ -0,0 +1,57 @@
+import { signal, computed } from "@praxisjs/core";
+import type { Computed } from "@praxisjs/shared";
+
+export type StateMap<S extends string, E extends string> = Record<S, {
+    on?: Partial<Record<E, S>>;
+    onEnter?: () => void;
+    onExit?: () => void;
+  }>;
+
+export interface MachineDefinition<S extends string, E extends string> {
+  initial: S;
+  states: StateMap<S, E>;
+  onTransition?: (from: S, event: E, to: S) => void;
+}
+
+export interface Machine<S extends string, E extends string> {
+  state: Computed<S>;
+  history: Computed<Array<{ from: S; event: E; to: S }>>;
+  send(event: E): boolean;
+  can(event: E): boolean;
+  is(state: S): boolean;
+  reset(): void;
+}
+
+export function createMachine<S extends string, E extends string>(
+  definition: MachineDefinition<S, E>,
+): Machine<S, E> {
+  const _state = signal<S>(definition.initial);
+  const _history = signal<Array<{ from: S; event: E; to: S }>>([]);
+
+  function send(event: E): boolean {
+    const current = _state();
+    const nextState = definition.states[current].on?.[event];
+    if (!nextState) return false;
+
+    definition.states[current].onExit?.();
+    _state.set(nextState);
+    _history.update((h) => [...h, { from: current, event, to: nextState }]);
+    definition.onTransition?.(current, event, nextState);
+    definition.states[nextState].onEnter?.();
+    return true;
+  }
+
+  return {
+    state: computed(() => _state()),
+    history: computed(() => _history()),
+    send,
+    can: (event) => !!definition.states[_state()].on?.[event],
+    is: (state) => _state() === state,
+    reset: () => {
+      definition.states[_state()].onExit?.();
+      _state.set(definition.initial);
+      _history.set([]);
+      definition.states[definition.initial].onEnter?.();
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}