Merge branch 'main' into new-docs

Author: Matthew Phillips

.changeset/config.json

@@ -7,5 +7,8 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  },
   "ignore": []
 }

.changeset/odd-fans-cough.md

@@ -0,0 +1,11 @@
+---
+"robot3": minor
+---
+
+'/logging' is now exported, so you can import it in your dev environment to log state changes.
+
+```ts
+import 'robot3/logging';
+
+import {...} from 'robot3';
+```

.github/workflows/nodejs.yml

@@ -5,7 +5,7 @@ on: [push]
 jobs:
   build:
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
 
     strategy:
       matrix:

.github/workflows/site.yml

@@ -6,6 +6,7 @@ on:
     - main
     paths:
     - 'docs/**'
+    - '.github/workflows/site.yml'
 
 jobs:
   deploy:
@@ -18,22 +19,18 @@ jobs:
       with:
         node-version: 22
 
+    - name: Setup Rclone
+      uses: AnimMouse/setup-rclone@v1
+      with:
+        rclone_config: ${{ secrets.RCLONE_CONFIG }}
+
     - name: Install dependencies
       run: npm ci
 
     - name: Build Site
       run: npm run --workspace=docs build
 
-    - name: Sync Bucket
-      uses: jakejarvis/s3-sync-action@master
-      with:
-        args: --delete
-      env:
-        AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
-        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-        DEST_DIR: '/'
-        SOURCE_DIR: 'docs/_site'      # optional: defaults to entire repository
+    - run: rclone sync docs/_site remote:thisrobot.life
 
     - name: Invalidate CDN
       uses: chetan/invalidate-cloudfront-action@master

docs/api/invoke.md

@@ -196,3 +196,34 @@ const machine = createMachine({
   error: state()
 })
 ```
+
+## Cancellation
+
+JavaScript does not support cancellation of promises: the action which will
+resolve the promise will run to completion or until it encounters an error.
+
+There are situations where the result of the promise no longer matters. The
+machine should proceed to a different action, or simply stop changing state
+entirely. To achieve this with the `invoke` state, an extra event can be
+added to the state like the `cancel` event in the example below.
+
+```js
+import { createMachine, invoke, reduce, state, transition } from 'robot3';
+
+const loadTodos = () => Promise.reject("Sorry but you can't do that");
+
+const machine = createMachine({
+  start: invoke(loadTodos,
+    transition('cancel', 'cancelled'),
+    transition('done', 'loaded',
+      reduce((ctx, ev) => ({ ...ctx, todo: ev.data }))
+    )
+  ),
+  cancelled: state(),
+  loaded: state()
+})
+```
+
+By moving out of `start` state before the promise returned by `loadTodos`
+resolves, the function result will be discarded: the machine finds that it
+is no longer in the state from which is was invoked and discards the event.

docs/guides.md

@@ -9,4 +9,5 @@ These guides are meant to help you along your journey learning Finite State Mach
 
 * __[Composition](./guides/composition.html)__: How to use functional composition when building state machines, to maximize code reuse where possible.
 * __[Nested States](./guides/nested-states.html)__: Create machines with nested states by [invoking](./api/invoke.html) other machines.
-* __[Comparison with XState](./guides/comparison-with-xstate.html)__: Differences and tradeoffs between Robot and [XState](https://xstate.js.org).
+* __[Awaiting asynchronous completion](./guides/awaiting-asynchronous-execution.html)__: How to await a machine to enter a `final` state.
+* __[Comparison with XState](./guides/comparison-with-xstate.html)__: Differences and tradeoffs between Robot and [XState](https://xstate.js.org).

docs/guides/awaiting-asynchronous-execution.md

@@ -0,0 +1,30 @@
+---
+layout: page.njk
+title: Awaiting asynchronous execution
+tags: guide
+permalink: guides/awaiting-asynchronous-execution.html
+---
+
+In a scenario where it's necessary to `await` the machine to enter a `final`
+state (a state which has no transitions), the `onChange` callback (the second argument to `interpret`) can be used
+to resolve a promise. The promise can be externally awaited.
+
+```js
+let resolve;
+let promise = new Promise(_resolve => {
+  resolve = _resolve;
+})
+
+service = interpret(machine, () => {
+  if(machine.state.value.final) {
+    resolve();
+  }
+});
+
+await promise;
+// All done!
+```
+
+This is particularly useful for state machines which consist entirely
+of `immediate` and `invoke` states: these model execution flows which do
+not depend on external events for their execution and state transition.

docs/guides/nested-states.md

@@ -72,7 +72,8 @@ Here we create a `nested` function that defines a submachine.
 
 ```js
 // A helper function for more easily building nested state machines.
-const nested = (to, states) => createMachine(states,
+const nested = (to, states) => invoke(
+  createMachine(states),
   transition('done', to)
 );
 
@@ -90,4 +91,4 @@ const stoplight = createMachine({
     dontWalk: final()
   })
 });
-```
+```