Hook notation

[StoneCypher]

It's time. We've thought it over enough.

Hooks and state are the same thing. State is an object. The language is blind to state, as is the machine; state exists solely for hooks.

Hooks and input output queues are the same thing. The input and output queues are arrays. We won't bother reversing them for efficiency. It's not clear if the input queue is opaque or not, yet. The language and machine are blind to input and output state; they exist for hooks as well.

Hooks have an in-language presence notation which is implicitly universal and unneeded; hooks also can be "closed," meaning that in that choice, you must explicitly name what's hookable. (Possibly a short notation? Return to this in #619.)

Hooks need to return a posterior: the new data, the new state, the new status (that is, running, halted, etc.) That means we need to more clearly enumerate and clean up status, in turn.

A hook also needs to be able to reject a transition, which is why they need to be transactional (see #452.) This probably means that we should just stash state prior to the hook lifecycle (see #487) and apply it afterwards. This will have a non-trivial performance impact even when state isn't in use 😢 so we should probably get benchmarking #593 in place first.

The basic notation, which will probably be rarely used due to the short notation, is:

machine_name: "Store door sign";
open <-> closed;
entry_hook open;
entry_hook closed;

This should also take lists:

machine_name: "Store door sign";
open <-> closed;
entry_hook [open closed];

There is also a shorthand in #619:

machine_name: "Store door sign";
^open <-> ^closed;

Attaching hooks happens outside the machine (typically in the fluent call afterwards.) So, by example:

import { sm } from 'jssm';

const door_sign = sm` ^open <-> ^closed; `
  .on_enter('open', () => console.log('do on-open stuff here'))
  .on_enter('closed', () => console.log('do on-closed stuff here'));

The hook accepts an object called prior and another called parameters. The prior object should be cloned as output unless you have a specific plan otherwise. The parameters object contains things that don't get cloned.

The prior object contains:

1. data - the finite state machine's user-governed dataset.
2. status - running, stopped, terminal, error, et cetera
3. state - the state it's coming from (because this is prior)

The parameter object contains:

1. edge - object - The edge being followed
2. action - string or undefined - The action being used, if any
3. probability - number or undefined - the value returned from a probabilistic edge firing

This also, in turn, means that the machine needs a concept of stoppage that is distinct from the state #621, which is probably just an internal flag, but also needs to be considered for reset #449 and so on