Version 1.0.0-alpha.5

Squashed commit of the following:

commit ed1efa5
Author: Abdullah Ali <[email protected]>
Date:   Fri Nov 2 10:35:40 2018 +0200

    build: Upgrade to latest Node.js LTS: 10.13.0

commit 188ff9d
Author: Abdullah Ali <[email protected]>
Date:   Fri Nov 2 10:30:13 2018 +0200

    chore: Version bump: 1.0.0-alpha5

commit 4d32b4e
Author: Abdullah Ali <[email protected]>
Date:   Fri Nov 2 10:28:20 2018 +0200

    feat: Action priorities

    A new decorator to specify which actions override others. A higher prioirity means an action gets to
    override all those below it when updating the state.

commit b9110b8
Author: Abdullah Ali <[email protected]>
Date:   Sat Sep 29 10:49:50 2018 +0200

    test: Fix unused variable/parameters in the tests.

commit f77a4a6
Author: Abdullah Ali <[email protected]>
Date:   Sat Sep 29 10:48:45 2018 +0200

    docs(Spec): Fix spec pseudocode examples.

commit e536638
Merge: 452ec70 555f566
Author: Abdullah Ali <[email protected]>
Date:   Wed Sep 26 20:18:51 2018 +0200

    Merge branch 'master' into devel

commit 452ec70

Author: voodooattack

Diff for: .travis.yml

@@ -1,12 +1,16 @@
 language: nodejs
 
-node_js: 8.12.0
+node_js:
+  - "8.12.0"
+  - "10.13.0"
 
 cache:
   directories:
   - node_modules
 
 before_script:
+- nvm install stable
+- nvm use stable
 - npm install
 - npm run build
 

Diff for: README.md

@@ -121,8 +121,6 @@ When both traits are present in a single machine, the NPC will potentially exhib
 
 Here are some abstract syntax examples for a full pseudo-language based on this pattern. In this theoretical language, the program itself is a state machine, variables of the `MachineState` are global variables, and all of the primitives described above are part of the language itself.
 
-You can read about the original idea (slightly outdated) [in this proposal](https://gist.github.com/voodooattack/ccb1d18112720a8de5be660dbb80541c).
-
 This is mostly pseudo-javascript with two extra `when` and `exit` keywords, and using a hypothetical decorator syntax to specify action metadata. 
 
 The decorators are completely optional, and the currently proposed ones are:
@@ -137,7 +135,7 @@ Action decorators may only precede a `when` block, and will only apply to that b
 
 - `@inhibitedBy(action_name)` Prevents this action from triggering if another by `action_name` will execute during this tick. Can be used multiple times with the same action and different inhibitors.
 
-- `@priority(number)` Sets a numeric priority for the action. This will influence the order of evaluation inside the main loop. Actions with higher priority values are evaluated last, meaning that they will take precedence if there's a conflict from multiple actions trying to update the same variable during the same tick.    
+- `@priority(expression)` Sets a priority for the action. (Default is 0) This will influence the order of evaluation inside the main loop. Actions with lower priority values are evaluated last, while actions with higher priority values are evaluated first, meaning that they will take precedence if there's a conflict from multiple actions trying to update the same variable during the same tick. Can be a literal numeric value or an expression that returns a signed numeric value.
 
 ##### Control decorators:
 
@@ -151,8 +149,9 @@ Action decorators may only precede a `when` block, and will only apply to that b
 
 ```typescript
 // maximum number of primes to brute-force before exiting, 
-// note that this variable is a readonly external input
-@input('maxPrimes') 
+// note that this variable is a readonly external input, 
+// and is read only once on startup.
+@input('once') 
 const maxPrimes: number = 10; 
 
 let counter = 2; // starting counting up from 2

Diff for: package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "when-ts",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.5",
   "description": "When: A software design pattern for building event-based recombinant state machines.",
   "main": "dist/lib/src/index.js",
   "types": "dist/types/src/index.d.ts",
@@ -31,7 +31,7 @@
     "tslint": "^5.10.0",
     "tslint-config-prettier": "^1.13.0",
     "tslint-config-standard": "^8.0.1",
-    "typedoc": "^0.12.0",
+    "typedoc": "^0.13.0",
     "typescript": "^3.0.3"
   },
   "peerDependencies": {

Diff for: package.json

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
-import { actionMetadataKey, inputMetadataKey } from './actionMetadataKey';
-import { ActivationCond, InputPolicy, MachineInputSource, MachineState } from './interfaces';
+import { actionMetadataKey, inputMetadataKey, priorityMetadataKey } from './metadataKeys';
+import { ActivationCond, InputPolicy, MachineInputSource, MachineState, PriorityExpression } from './interfaces';
 import { StateMachine } from './stateMachine';
 import { chainWhen, ConditionBuilder, ConstructorOf, InputMapping, WhenDecoratorWithChain } from './util';
 
@@ -111,5 +111,19 @@ export function input<S extends MachineState, I extends MachineInputSource,
   };
 }
 
-export type StateObject<S extends MachineState, I extends MachineInputSource = any> =
-  S & Readonly<I>;
+export function priority<
+  S extends MachineState, I extends MachineInputSource = any,
+  M extends StateMachine<S, I> = any>
+(
+  priority: number| PriorityExpression<S, I>,
+  chainedHistory: ConditionBuilder<S, I>[] = []
+): WhenDecoratorWithChain<S, I> {
+  function definePriority(_: ConstructorOf<M>, __: string | symbol, descriptor: PropertyDescriptor) {
+    Reflect.defineMetadata(priorityMetadataKey, priority, descriptor.value);
+  }
+  return chainWhen<S, I>([definePriority, ...chainedHistory]);
+}
+
+export type StateObject<
+  S extends MachineState,
+  I extends MachineInputSource = any> = S & Readonly<I>;

Diff for: src/index.ts

@@ -43,6 +43,13 @@ export type ActivationAction<State extends MachineState, InputSource extends Mac
   (state: Readonly<State & InputSource>, machine: StateMachine<State, InputSource>)
     => Pick<State, fields> | void;
 
+/**
+ * An activation condition, takes two arguments and must return true for the associated action to fire.
+ */
+export type PriorityExpression<State extends MachineState, InputSource extends MachineInputSource> =
+  (state: Readonly<State & InputSource>, machine: StateMachine<State, InputSource>) => number;
+
+
 
 /**
  * The HistoryManager interface allows for state manipulation and the rewinding of a program.

Diff for: src/interfaces.ts

@@ -2,3 +2,5 @@
 export const actionMetadataKey = Symbol('when-action');
 /** @ignore */
 export const inputMetadataKey = Symbol('when-input');
+/** @ignore */
+export const priorityMetadataKey = Symbol('when-priority');

Diff for: src/actionMetadataKey.ts renamed to src/metadataKeys.ts

@@ -1,4 +1,4 @@
-import { actionMetadataKey, inputMetadataKey } from './actionMetadataKey';
+import { actionMetadataKey, inputMetadataKey, priorityMetadataKey } from './metadataKeys';
 import { HistoryManager } from './historyManager';
 import { ActivationAction, ActivationCond, MachineInputSource, MachineState } from './index';
 import { IHistory } from './interfaces';
@@ -40,12 +40,17 @@ export class StateMachine<S extends MachineState, I extends MachineInputSource =
    */
   protected constructor(initialState: S, inputSource?: I) {
     const properties = getAllMethods(this);
+    const program: [ActivationCond<S, I>, any, number][] = [];
     for (let m of properties) {
       if (Reflect.hasMetadata(actionMetadataKey, m)) {
         const cond = Reflect.getMetadata(actionMetadataKey, m);
-        this._program.set(cond, m as any);
+        const priority = Reflect.getMetadata(priorityMetadataKey, m);
+        program.push([cond, m, typeof priority === 'number' ? priority : 0]);
       }
     }
+    this._program = new Map(
+      program.sort(([,,a], [,,b]) => a - b) as any
+    );
     this._history = new HistoryManager<S, I, this>(this, initialState, inputSource,
       inputSource ? Reflect.getMetadata(inputMetadataKey, inputSource) : []
     );

Diff for: src/stateMachine.ts

@@ -1,5 +1,5 @@
-import { actionMetadataKey, inputMetadataKey } from './actionMetadataKey';
-import { inhibitedBy, InputPolicy, MachineInputSource, StateMachine, unless, when } from './index';
+import { actionMetadataKey, inputMetadataKey } from './metadataKeys';
+import { inhibitedBy, InputPolicy, MachineInputSource, priority, StateMachine, unless, when } from './index';
 import { ActivationCond } from './interfaces';
 
 /** @ignore */
@@ -37,13 +37,14 @@ export function getInheritanceTree<T>(entity: ConstructorOf<T>): Function[] {
 
 /** @ignore */
 export type ConditionBuilder<S, I> = {
-  (T: any, methodName: string | symbol, descriptor: PropertyDescriptor): ActivationCond<S, I>
+  (T: any, methodName: string | symbol, descriptor: PropertyDescriptor): ActivationCond<S, I> | void
 }
 
 export type WhenDecoratorChainResult<S, I> = {
   andWhen(cond: ActivationCond<S, I> | true): WhenDecoratorWithChain<S, I>;
   unless(condition: ActivationCond<S, I>): WhenDecoratorWithChain<S, I>;
   inhibitedBy<M>(inhibitor: keyof M): WhenDecoratorWithChain<S, I>;
+  priority(p: number): WhenDecoratorWithChain<S, I>;
 }
 export type WhenDecoratorWithChain<S, I> = MethodDecorator & WhenDecoratorChainResult<S, I>;
 
@@ -55,22 +56,24 @@ export function chainWhen<S, I>(chainedHistory: ConditionBuilder<S, I>[]): WhenD
     {
       andWhen: (...args: any[]) => (when as any)(...args, chainedHistory),
       unless: (...args: any[]) => (unless as any)(...args, chainedHistory),
-      inhibitedBy: (...args: any[]) => (inhibitedBy as any)(...args, chainedHistory)
+      inhibitedBy: (...args: any[]) => (inhibitedBy as any)(...args, chainedHistory),
+      priority: (...args: any[]) => (priority as any)(...args, chainedHistory),
     }
   );
 }
 
 /**
  * Build a decorator out of a list of conditions.
- * @param {ActivationCond<S>[]} builders
+ * @param {ActivationCond[]} builders
  * @param {boolean} invert
  * @return {(_: any, _methodName: (string | symbol), descriptor: PropertyDescriptor) => void}
  */
 /** @ignore */
 function buildDecorator<S, I>(builders: ConditionBuilder<S, I>[]) {
   return function decorator(Type: any, methodName: string | symbol, descriptor: PropertyDescriptor)
   {
-    const built = builders.map(builder => builder(Type, methodName, descriptor));
+    const built = builders.map(builder => builder(Type, methodName, descriptor))
+      .filter(cond => typeof cond === 'function');
     const cond = built.length > 1 ? function () {
       for (let current of built) {
         // tell TS to ignore the next line because we specifically want a non-contextual `this`

Diff for: src/util.ts

@@ -182,6 +182,7 @@ describe('StateMachine', () => {
     const test = new TestMachine();
     const result = test.run(true);
 
+    expect(result).toEqual({ value: 3 });
     expect(series).toEqual([[0, 1], [1, 2], [2, 3], [3, 4], [1, 2], [2, 3], [3, 4]]);
 
   });
@@ -503,12 +504,12 @@ describe('StateMachine', () => {
       }
 
       @when<BlankState>(true)
-      keepMe(_, m: BlankMachine) {
+      keepMe(_: any, m: BlankMachine) {
         return { tick: m.history.tick };
       }
 
-      @when((_, m) => m.history.tick > 5)
-      exitMachine(_, m: BlankMachine) {
+      @when<BlankState>((_, m) => m.history.tick > 5)
+      exitMachine(_: any, m: BlankMachine) {
         m.exit();
       }
     }
@@ -582,4 +583,51 @@ describe('StateMachine', () => {
     expect(test.history.records).toEqual(expectedHistory);
   });
 
+  it('Can handle priorities', () => {
+
+    type State = {
+      value: number;
+    }
+
+    class TestMachine extends StateMachine<State> {
+      constructor() {
+        super({ value: 0 });
+      }
+
+      @when<State>(state => Math.abs(state.value) >= 5)
+      exitWhenDone(_: State, m: TestMachine) {
+        // this should execute on tick 6
+        expect(m.history.tick).toEqual(6);
+        m.exit();
+      }
+
+
+      // overrides the increment action via priority
+      @when<State>(state => state.value > -5).priority(10)
+      decrementOncePerTick(s: State) {
+        return { value: s.value - 1 };
+      }
+
+      @when<State>(state => state.value < 5)
+      incrementOncePerTick(s: State) {
+        return { value: s.value + 1 };
+      }
+
+      update(tick: number): StateObject<BlankState, IBlankMachineInputs> {
+        let old = this.snapshot(tick);
+        this._fixed = 10;
+        this._increments++;
+        this._random = Math.round(Math.random() * 1000);
+        if (old.tick % 2 !== 0) old.increments = old.increments === 0 ?  0 : old.increments - 1;
+        return { ...old, tick };
+      }
+    }
+
+    const test = new TestMachine();
+    const result = test.run();
+
+    expect(result).toEqual({ value: -5 });
+  });
+
+
 });