|
1 | | -## [PureMVC](http://puremvc.github.com/) [Typescript](https://github.com/PureMVC/puremvc-typescript-multicore-framework/wiki) Utility: State Machine |
2 | | -This utility provides a simple yet effective Finite State Machine implementation, which allows the definition of discrete states, and the valid transitions to other states available from any given state, and the actions which trigger the transitions. A mechanism is provided for defining the entire state machine in JSON and having a fully populated StateMachine injected into the PureMVC app. |
| 1 | +## [PureMVC](http://puremvc.github.com/) [Typescript](https://github.com/PureMVC/puremvc-typescript-multicore-framework/wiki) Utility: Async Command |
| 2 | +The Async Command utility offers a solution to the problem of executing a series of commands each of which may need to complete one or more asynchronous operations before the next command is executed. |
| 3 | + |
| 4 | +The problem can be handled without this utility, by having a `SimpleCommand` send a notification when a promise resolves, thereby triggering the next command. |
| 5 | + |
| 6 | +But that leads to a tight coupling of one command to the next, if the first must know the notification to send in order to trigger the second. |
| 7 | + |
| 8 | +With the `AsyncCommand` and `AsyncMacroCommand` you could dynamically create a pipeline of commands to be executed sequentially, each of which may have multiple async tasks to complete. None need know anything about the others. |
3 | 9 |
|
4 | 10 | ## Status |
5 | | -Production - [Version 1.0.0](https://github.com/PureMVC/puremvc-typescript-util-statemachine/blob/master/VERSION) |
| 11 | +Production - [Version 1.0.0](https://github.com/PureMVC/puremvc-typescript-util-async-command/blob/master/VERSION) |
6 | 12 |
|
7 | 13 | ## Platforms / Technologies |
8 | 14 | * [Typescript](http://en.wikipedia.org/wiki/Typescript) |
| 15 | +* [NPM Package](https://www.npmjs.com/package/@puremvc/puremvc-js-util-async-command) |
9 | 16 |
|
10 | | -## State Representation |
11 | | -* The States held and navigated by the StateMachine are instances of a State class, which carries several critical pieces of information about that State. Each State has optional associated Notifications to be sent on entry into the State and exit from the State. |
12 | | -* The exiting notification carries a reference in the body to the State that we are transitioning to. This helps actors respond properly by anticipating the destination state. |
13 | | -* The entering notification for a State carries a reference in the body to the state we are entering as well, in case you've sub-classed State to pass data. |
14 | | -* It is up to the programmer to define and register commands or mediators with interest in these entering and exiting notifications, the state machine simply sends them at the appropriate times. |
15 | | -* The State class also exposes methods for defining and removing transitions. A transition simply maps an action name to a target State name. |
16 | | - |
17 | | -## State Transitions |
18 | | -* The transition from one state to the next is triggered by any actor sending a StateMachine.ACTION Notification. Include the name of the action in the Notification's type parameter. |
19 | | -* Actions are what trigger the StateMachine to initiate the transition from the one State to the next. There is no formal Action class at this time, it is merely a name that will trigger a State transition. |
20 | | -* It is up to the application to ensure any special conditions for making the transition are met before sending the StateMachine.ACTION Notification, which will initiate the transition immediately if one is defined for the input action given the current State. |
21 | | -* Any actor responding to the Notification sent when exiting a state may send a StateMachine.CANCEL notification, which will cause the StateMachine not to enter the next State. The programmer must insure that no other responses to the current State's exit notification need to be rolled back. This is best done by checking any items that could lead to a StateMachine.CANCEL being sent before initiating any exit activity such as visual transitions or form clearing/population, thus avoiding the need to rollback to restore the application to the state being exited. |
22 | | -* Finally, when a transition is complete, the StateMachine sends a StateMachine.CHANGED Notification, with a reference to the new State. This is sent once any exiting notification for the previous state, as well as any entering notification for the new state have both been executed, and the current state of the StateMachine has been updated to the new state. |
23 | | - |
24 | | -## FSM Injector |
25 | | - * Also included in this release is useful class that allows you to define your FSM in an JSON format, and pass it to the FSMInjector where it will be parsed, and a fully populated StateMachine instance will be created and registered via your Facade. |
26 | | -* The FSMInjector extends Notifier to give it a reference to the Facade for injecting the completed StateMachine. |
27 | | -* The JSON format for the FSM Injector is simple. For instance here is the FSM for a door: |
28 | | - |
29 | | -> { |
30 | | -> initial: "CLOSED" |
31 | | -> states: [ |
32 | | -> { |
33 | | -> name: "OPENED" |
34 | | -> entering: "openingNote" |
35 | | -> transitions: [ |
36 | | -> { |
37 | | -> action: "CLOSE" |
38 | | -> target: "CLOSED" |
39 | | -> }, |
40 | | -> ] |
41 | | -> }, |
42 | | -> { |
43 | | -> name: "CLOSED" |
44 | | -> entering: "closingNote" |
45 | | -> transitions: [ |
46 | | -> { |
47 | | -> action: "OPEN" |
48 | | -> target: "CLOSED" |
49 | | -> }, |
50 | | -> { |
51 | | -> action: "LOCK" |
52 | | -> target: "LOCKED" |
53 | | -> }, |
54 | | -> ] |
55 | | -> }, |
56 | | -> { |
57 | | -> name: "LOCKED" |
58 | | -> entering: "lockingNote" |
59 | | -> exiting: "unlockingNote" |
60 | | -> transitions: [ |
61 | | -> { |
62 | | -> action: "UNLOCK" |
63 | | -> target: "CLOSED" |
64 | | -> }, |
65 | | -> ] |
66 | | -> } |
67 | | -> } |
| 17 | +## Ported Utility |
| 18 | +* This is a direct port of the original [AS3 AsyncCommand utility](https://github.com/PureMVC/puremvc-as3-util-asynccommand) |
| 19 | +* [Historical Discussion](http://forums.puremvc.org/index.php?topic=831.0) |
68 | 20 |
|
69 | | -* The above FSM defines three discrete states OPENED, CLOSED and LOCKED. |
70 | | -* The actions OPEN, CLOSE and LOCK are used to trigger state transitions. |
71 | | -* It is only possible to LOCK the door when it is CLOSED, because only the CLOSED state defines a transition targeting the LOCKED state. |
72 | | -* It is not possible to OPEN the door from the LOCKED state because no transition is defined targeting the OPEN state. |
73 | | -* And when you UNLOCK the door, it returns to the CLOSED state, where it is once again possible to OPEN or LOCK. |
74 | | -* An exiting notification is defined only for exiting the OPEN state to illustrate that entering and exiting notifications are optional. |
75 | 21 |
|
76 | 22 | ## License |
77 | | -* PureMVC Typescript Utility - State Machine - Copyright © 2007-2025 Neil Manuell, Cliff Hall |
| 23 | +* PureMVC Utility for JS - AsyncCommand - Ported by Cliff Hall (no relation) |
| 24 | +* From PureMVC Utility for AS3 - AsyncCommand - Copyright © 2008 Duncan Hall |
78 | 25 | * PureMVC - Copyright © 2007-2025 Futurescale, Inc. |
79 | 26 | * All rights reserved. |
80 | 27 |
|
|
0 commit comments