anbaric 1.64.0 → 1.65.0

package/README.md

@@ -61,8 +61,8 @@ import {Action, Code, PropertyDefinition, State, StateMachine, Transition} from
 
 const sendWelcome = new Action("Send welcome email", new Code("welcome"));
 sendWelcome.run = async (job) => {
-    // Access properties stored against the job
-    const email = job.properties.get("email");
+    // Access properties stored against the job - reading one is asynchronous
+    const email = await job.properties.get("email");
     // Run some code
     console.log(`Sending welcome email to ${email}`);
     // Return new properties to add to the job
@@ -72,7 +72,7 @@ sendWelcome.run = async (job) => {
 };
 
 const onboarding = new StateMachine("onboarding", [
-    new State("new", [sendWelcome], [new Transition("active", (job) => job.properties.get("emailSent") === true)]),
+    new State("new", [sendWelcome], [new Transition("active", async (job) => await job.properties.get("emailSent") === true)]),
     new State("active"),
 ]);
 
@@ -81,6 +81,11 @@ const customer = await onboarding.startJob(new Map([["email", "ada@example.com"]
 
 The job starts in `new`; when it is processed the action runs, sets `emailSent`, and the transition advances it to `active`.
 
+`job.properties` is read on demand: `get`, `has` and `getMany` return promises, so
+a job can hold a great deal while a step that needs one property pays for one.
+That is why an action's `predicate` and a transition's guard may be `async`, as
+above. See [Actions and actors](anbaric/docs/features/actions-and-actors.md#reading-properties-is-asynchronous).
+
 ### Using AI agents to automate states
 
 An **agent** is an actor whose properties are produced by a model rather than by
@@ -104,7 +109,7 @@ const triage = new RemoteLLMAgenticAction(
 );
 
 const support = new StateMachine("support", [
-    new State("open", [triage], [new Transition("prioritised", (job) => job.properties.has("priority"))]),
+    new State("open", [triage], [new Transition("prioritised", async (job) => await job.properties.has("priority"))]),
     new State("prioritised"),
 ]);
 ```
@@ -136,7 +141,7 @@ approve.fields = ["approved"];                                  // the input we
 approve.resolveUrl = (job) => `/approve?job=${job.id}`;         // where the human provides it
 
 const fulfilment = new StateMachine("fulfilment", [
-    new State("review", [approve], [new Transition("approved", (job) => job.properties.get("approved") === true)]),
+    new State("review", [approve], [new Transition("approved", async (job) => await job.properties.get("approved") === true)]),
     new State("approved"),
 ]);
 

package/docs/patterns/testing.md

@@ -25,13 +25,15 @@ test("payOut marks the expense paid", async () => {
 `new Job(id, properties, state)` is all you need to construct a job for a test
 (later constructor arguments have sensible defaults).
 
-Transition predicates and property validations are just as easy:
+Transition predicates and property validations are just as easy. A predicate
+that reads properties is asynchronous, because reading properties is, so `await`
+it:
 
 ```ts
-test("advances once approved", () => {
+test("advances once approved", async () => {
     const job = new Job("job-1", new Map([["approved", true]]), "review");
     const toApproved = machineTransition("approved");
-    expect(toApproved.predicate(job)).toBe(true);
+    expect(await toApproved.predicate(job)).toBe(true);
 });
 
 test("amount must be positive", () => {
@@ -46,10 +48,10 @@ If several actions share a state and choose themselves by `predicate`, assert th
 selection:
 
 ```ts
-test("low-priority tickets auto-triage", () => {
+test("low-priority tickets auto-triage", async () => {
     const job = new Job("t1", new Map([["priority", "low"]]), "open");
-    expect(autoTriage.predicate(job)).toBe(true);
-    expect(escalate.predicate(job)).toBe(false);
+    expect(await autoTriage.predicate(job)).toBe(true);
+    expect(await escalate.predicate(job)).toBe(false);
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.64.0",
+  "version": "1.65.0",
   "description": "Everything needed to write an Anbaric app: state machines, jobs, document and secret stores, local in-memory implementations and the Anbaric Cloud clients",
   "license": "MIT",
   "type": "module",
@@ -24,9 +24,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.64.0",
-    "anbaric-data-store": "^1.64.0",
-    "anbaric-state-machine": "^1.64.0",
-    "anbaric-tsapi": "^1.64.0"
+    "anbaric-impl-cloud": "^1.65.0",
+    "anbaric-data-store": "^1.65.0",
+    "anbaric-state-machine": "^1.65.0",
+    "anbaric-tsapi": "^1.65.0"
   }
 }