@ue-too/being 0.14.1 → 0.16.0

package/README.md

@@ -14,11 +14,13 @@ Let's say we want to build a state machine for a vending machine.
 To make it simple, the vending machine only accepts dollar bills and sells 3 types of items at $1, $2, and $3.
 
 The items are:
+
 - Coke (1 dollar)
 - Red Bull (2 dollars)
 - Water (3 dollars)
 
 There are only 3 kinds of actions that the user can take:
+
 - insert coins
 - select an item (we can break it into multiple events; each event representing a different item)
 - cancel the transaction
@@ -26,15 +28,18 @@ There are only 3 kinds of actions that the user can take:
 With the above information, we can create a state machine for the vending machine.
 
 For the `@ue-too/being` library, there are 3 main things that we need to define and be clear on in order to create a state machine:
+
 - All possible states of the state machine.
 - All possible events that can happen in the state machine.
 - The context of the state machine.
 - The rules for the state transitions.
 
 Let's start with the all possible states of the state machine.
+
 > There are many ways to represent the vending machine in a state machine. My way is only one possible way but you can probably come up with a better way or at least what makes sense to you.
 
 I'm defining the states as follows:
+
 - IDLE
 - 1 Dollar Inserted
 - 2 Dollars Inserted
@@ -43,12 +48,19 @@ I'm defining the states as follows:
 To create a type that is a string literal union of the states, we can use the utilty type `CreateStateType`.
 
 ```ts
-import { CreateStateType } from "@ue-too/being";
-
-const VENDING_MACHINE_STATES = ["IDLE", "ONE_DOLLAR_INSERTED", "TWO_DOLLARS_INSERTED", "THREE_DOLLARS_INSERTED"] as const;
-export type VendingMachineStates = CreateStateType<typeof VENDING_MACHINE_STATES>;
-
+import { CreateStateType } from '@ue-too/being';
+
+const VENDING_MACHINE_STATES = [
+    'IDLE',
+    'ONE_DOLLAR_INSERTED',
+    'TWO_DOLLARS_INSERTED',
+    'THREE_DOLLARS_INSERTED',
+] as const;
+export type VendingMachineStates = CreateStateType<
+    typeof VENDING_MACHINE_STATES
+>;
 ```
+
 Next, we should define all the possible events and their payload.
 
 ```ts
@@ -58,7 +70,7 @@ type VendingMachineEvents = {
     selectRedBull: {};
     selectWater: {};
     cancelTransaction: {};
-}
+};
 ```
 
 Sometimes we need variables to keep track of certain attributes that can persists across different states; that's where the context comes along.
@@ -89,10 +101,19 @@ There's only one thing required to override in the abstract class which is the `
 It's an object with the key being the event name and the value being the reaction and the default target state to transition to after the reaction.
 
 The `EventReactions` looks like this:
+
 ```ts
-export type EventReactions<EventPayloadMapping, Context extends BaseContext, States extends string> = {
+export type EventReactions<
+    EventPayloadMapping,
+    Context extends BaseContext,
+    States extends string,
+> = {
     [K in keyof Partial<EventPayloadMapping>]: {
-        action: (context: Context, event: EventPayloadMapping[K], stateMachine: StateMachine<EventPayloadMapping, Context, States>) => void;
+        action: (
+            context: Context,
+            event: EventPayloadMapping[K],
+            stateMachine: StateMachine<EventPayloadMapping, Context, States>
+        ) => void;
         defaultTargetState?: States;
     };
 };
@@ -105,138 +126,171 @@ Now let's implement the `IdleState`.
 In the idle state, we only care about the `insertBills` event.
 
 ```ts
-import { TemplateState, EventReactions } from "@ue-too/being";
-
-class IdleState extends TemplateState<VendingMachineEvents, BaseContext, VendingMachineStates> {
-
-    public eventReactions: EventReactions<VendingMachineEvents, BaseContext, VendingMachineStates> = {
-        "insertBills": {
+import { EventReactions, TemplateState } from '@ue-too/being';
+
+class IdleState extends TemplateState<
+    VendingMachineEvents,
+    BaseContext,
+    VendingMachineStates
+> {
+    public eventReactions: EventReactions<
+        VendingMachineEvents,
+        BaseContext,
+        VendingMachineStates
+    > = {
+        insertBills: {
             action: (context, event, stateMachine) => {
-                console.log("inserted bills");
+                console.log('inserted bills');
             },
-            defaultTargetState: "ONE_DOLLAR_INSERTED"
+            defaultTargetState: 'ONE_DOLLAR_INSERTED',
         },
-    }
+    };
 }
 ```
 
 After that we can implement the `OneDollarInsertedState`.
 
 ```ts
-import { TemplateState, EventReactions } from "@ue-too/being";
-
-class OneDollarInsertedState extends TemplateState<VendingMachineEvents, BaseContext, VendingMachineStates> {
-    public eventReactions: EventReactions<VendingMachineEvents, BaseContext, VendingMachineStates> = {
-        "insertBills": {
+import { EventReactions, TemplateState } from '@ue-too/being';
+
+class OneDollarInsertedState extends TemplateState<
+    VendingMachineEvents,
+    BaseContext,
+    VendingMachineStates
+> {
+    public eventReactions: EventReactions<
+        VendingMachineEvents,
+        BaseContext,
+        VendingMachineStates
+    > = {
+        insertBills: {
             action: (context, event, stateMachine) => {
-                console.log("inserted bills");
+                console.log('inserted bills');
             },
-            defaultTargetState: "TWO_DOLLARS_INSERTED"
+            defaultTargetState: 'TWO_DOLLARS_INSERTED',
         },
-        "selectCoke": {
+        selectCoke: {
             action: (context, event, stateMachine) => {
-                console.log("selected coke");
+                console.log('selected coke');
             },
-            defaultTargetState: "IDLE"
+            defaultTargetState: 'IDLE',
         },
-        "selectRedBull": {
+        selectRedBull: {
             action: (context, event, stateMachine) => {
                 console.log('not enough money, 1 dollar short');
             },
         },
-        "selectWater": {
+        selectWater: {
             action: (context, event, stateMachine) => {
                 console.log('not enough money, 2 dollars short');
             },
         },
-        "cancelTransaction": {
+        cancelTransaction: {
             action: (context, event, stateMachine) => {
                 console.log('cancelled transaction');
                 console.log('refunding 1 dollar');
             },
-            defaultTargetState: "IDLE"
-        }
-    }
+            defaultTargetState: 'IDLE',
+        },
+    };
 }
 ```
+
 For the implementation of the `TwoDollarsInsertedState` and `ThreeDollarsInsertedState`, it's very similar to the `OneDollarInsertedState`.
 
 ```ts
-import { TemplateState, EventReactions } from "@ue-too/being";
-
-class TwoDollarsInsertedState extends TemplateState<VendingMachineEvents, BaseContext, VendingMachineStates> {
-    public eventReactions: EventReactions<VendingMachineEvents, BaseContext, VendingMachineStates> = {
-        "insertBills": {
+import { EventReactions, TemplateState } from '@ue-too/being';
+
+class TwoDollarsInsertedState extends TemplateState<
+    VendingMachineEvents,
+    BaseContext,
+    VendingMachineStates
+> {
+    public eventReactions: EventReactions<
+        VendingMachineEvents,
+        BaseContext,
+        VendingMachineStates
+    > = {
+        insertBills: {
             action: (context, event, stateMachine) => {
-                console.log("inserted bills");
+                console.log('inserted bills');
             },
-            defaultTargetState: "THREE_DOLLARS_INSERTED"
+            defaultTargetState: 'THREE_DOLLARS_INSERTED',
         },
-        "selectCoke": {
+        selectCoke: {
             action: (context, event, stateMachine) => {
-                console.log("selected coke");
+                console.log('selected coke');
             },
-            defaultTargetState: "IDLE"
+            defaultTargetState: 'IDLE',
         },
-        "selectRedBull": {
+        selectRedBull: {
             action: (context, event, stateMachine) => {
                 console.log('selected red bull');
             },
-            defaultTargetState: "IDLE"
+            defaultTargetState: 'IDLE',
         },
-        "selectWater": {
+        selectWater: {
             action: (context, event, stateMachine) => {
                 console.log('not enough money, 1 dollars short');
             },
         },
-        "cancelTransaction": {
+        cancelTransaction: {
             action: (context, event, stateMachine) => {
                 console.log('cancelled transaction');
                 console.log('refunding 2 dollars');
             },
-            defaultTargetState: "IDLE"
-        }
-    }
+            defaultTargetState: 'IDLE',
+        },
+    };
 }
 
-class ThreeDollarsInsertedState extends TemplateState<VendingMachineEvents, BaseContext, VendingMachineStates> {
-    public eventReactions: EventReactions<VendingMachineEvents, BaseContext, VendingMachineStates> = {
-        "insertBills": {
+class ThreeDollarsInsertedState extends TemplateState<
+    VendingMachineEvents,
+    BaseContext,
+    VendingMachineStates
+> {
+    public eventReactions: EventReactions<
+        VendingMachineEvents,
+        BaseContext,
+        VendingMachineStates
+    > = {
+        insertBills: {
             action: (context, event, stateMachine) => {
                 console.log('not taking more bills');
                 console.log('returning the inserted bills');
             },
         },
-        "selectCoke": {
+        selectCoke: {
             action: (context, event, stateMachine) => {
-                console.log("selected coke");
+                console.log('selected coke');
                 console.log('no change');
             },
-            defaultTargetState: "IDLE"
+            defaultTargetState: 'IDLE',
         },
-        "selectRedBull": {
+        selectRedBull: {
             action: (context, event, stateMachine) => {
                 console.log('selected red bull');
                 console.log('change: 1 dollar');
             },
-            defaultTargetState: "IDLE"
+            defaultTargetState: 'IDLE',
         },
-        "selectWater": {
+        selectWater: {
             action: (context, event, stateMachine) => {
                 console.log('selected water');
                 console.log('no change');
             },
         },
-        "cancelTransaction": {
+        cancelTransaction: {
             action: (context, event, stateMachine) => {
                 console.log('cancelled transaction');
                 console.log('refunding 3 dollars');
             },
-            defaultTargetState: "IDLE"
-        }
-    }
+            defaultTargetState: 'IDLE',
+        },
+    };
 }
 ```
+
 With all the states implemented, we can now create the state machine.
 
 ```ts
@@ -261,4 +315,3 @@ vendingMachine.happens("selectCoke");
 ```
 
 For the full complete example code, please refer to the `src/vending-machine-example.ts` file.
-

package/hierarchical-example.d.ts

@@ -1,13 +1 @@
-/**
- * Example: Hierarchical State Machine POC
- *
- * @remarks
- * This example demonstrates how to use hierarchical state machines with
- * composite states that contain child state machines.
- *
- * Scenario: A media player with hierarchical states
- * - Top level: IDLE, PLAYING, PAUSED
- * - PLAYING contains: BUFFERING, STREAMING, ERROR
- * - Events can be handled at child or parent level
- */
 export declare function runHierarchicalStateMachineExample(): void;

package/hierarchical.d.ts

@@ -16,7 +16,7 @@
  *
  * @category Hierarchical State Machines
  */
-import { BaseContext, StateMachine, TemplateStateMachine, TemplateState, EventResult, DefaultOutputMapping, EventArgs } from "./interface";
+import { BaseContext, DefaultOutputMapping, EventArgs, EventResult, StateMachine, TemplateState, TemplateStateMachine } from './interface';
 /**
  * Represents a hierarchical state path using dot notation.
  * Example: "PARENT.CHILD" means we're in CHILD state within PARENT state.
@@ -93,8 +93,8 @@ export declare abstract class CompositeState<EventPayloadMapping = any, Context
      * Gets the full hierarchical path of the current state.
      */
     getStatePath(parentState: ParentStates): HierarchicalStatePath<ParentStates, ChildStates>;
-    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, ParentStates, EventOutputMapping>, from: ParentStates | "INITIAL"): void;
-    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, ParentStates, EventOutputMapping>, to: ParentStates | "TERMINAL"): void;
+    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, ParentStates, EventOutputMapping>, from: ParentStates | 'INITIAL'): void;
+    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, ParentStates, EventOutputMapping>, to: ParentStates | 'TERMINAL'): void;
     handles<K extends keyof EventPayloadMapping | string>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, ParentStates, EventOutputMapping>): EventResult<ParentStates, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;
 }
 /**

package/index.d.ts

@@ -108,6 +108,6 @@
  * @see {@link TemplateStateMachine} for the main state machine class
  * @see {@link TemplateState} for creating state implementations
  */
-export * from "./interface";
-export * from "./schema-factory";
-export * from "./hierarchical";
+export * from './interface';
+export * from './schema-factory';
+export * from './hierarchical';