@nzelajs/node-advanced

English below · Version francaise plus bas.

The advanced node handlers of the Nzela engine: subprocess (spawn child instances and join on their completion) and wait (park until a signed external event or a timeout). Opt-in: a generic app never loads them. Vendor-free.

English

Install

npm add @nzelajs/node-advanced @nzelajs/core

What it provides

• subprocessNodeHandler({ outboxSigner }): the fan-out/join node.
  • On entry: runs the node's effects, then reads node.subprocess (join defaults to all; resumeAction defaults to the node's first outgoing transition, else it throws). Behavior:
    • No spec, no children, or join: "none": crosses the resume transition immediately. A none join still spawns its children fire-and-forget (per-spec autoSubmit), WITHOUT a blocking dependency.
    • all / any with children: creates every child and its join dependency FIRST (so a child that completes synchronously on submit already sees every sibling dependency), then submits the children (unless autoSubmit is explicitly false). The parent stays parked on the node; the core wakes it via its dependency joins when the join is met (all = every child done, any = the first). Each child inherits the parent's requester and beneficiary; formMap copies parent form fields into the child (child key -> parent key). Waking the parent may in turn wake ITS parent (DAG recursion).
  • Emits a signed case.subcase.spawned outbox event per child.
• waitNodeHandler({ outboxSigner }): the external-parking node.
  • On entry: runs the node's effects, registers an external wait (a fresh token), schedules the timeout timer when wait.timeout is declared, emits a signed case.external.waiting event, then rests on the node. The instance is resumed by the engine's resumeFromExternal (webhook: wait.onResolve, else the first outgoing transition) or expireExternalWait (timeout: wait.onTimeout; a no-op when no onTimeout is declared). This handler only parks; it never resumes.
• registerAdvancedHandlers(registry, { outboxSigner }): register both handlers at once.
• Building block: resumeActionFor.

Example

import { InMemoryNodeHandlerRegistry, NzelaEngine } from "@nzelajs/core";
import { registerAdvancedHandlers } from "@nzelajs/node-advanced";
import { registerGenericHandlers } from "@nzelajs/node-auto";

const handlers = new InMemoryNodeHandlerRegistry();
registerGenericHandlers(handlers); // state + auto, for the states around the advanced nodes
registerAdvancedHandlers(handlers, { outboxSigner });
const engine = new NzelaEngine({
  uow,
  blueprints,
  guards,
  effects,
  clock,
  outboxSigner,
  handlers,
});

Security note: everything fails closed. A subprocess node without a resume transition throws; the handler requires the core engine context (spawnChild / submitChild) and throws outside it. An unknown or already-closed external wait throws (never double-applied).

Francais

Installation

npm add @nzelajs/node-advanced @nzelajs/core

Ce que ca fournit

• subprocessNodeHandler({ outboxSigner }) : le noeud d'essaimage/jointure.
  • A l'entree : execute les effets du noeud, puis lit node.subprocess (join vaut all par defaut ; resumeAction vaut par defaut la 1re transition sortante du noeud, sinon leve). Comportement :
    • Pas de spec, aucun enfant, ou join: "none" : franchit la reprise immediatement. Une jointure none engendre quand meme ses enfants (fire-and-forget, autoSubmit de la spec), SANS dependance bloquante.
    • all / any avec enfants : cree TOUS les enfants et leur dependance de jointure d'abord (un enfant qui se termine de facon synchrone a la soumission voit deja toutes les dependances soeurs), puis soumet les enfants (sauf si autoSubmit vaut explicitement false). Le parent reste gare sur le noeud ; le coeur le reveille via ses jointures de dependance quand la jointure est atteinte (all = tous les enfants finis, any = le premier). Chaque enfant herite du demandeur et du beneficiaire du parent ; formMap recopie des champs du parent vers l'enfant (cle enfant -> cle parent). Reveiller le parent peut a son tour reveiller SON parent (recursion du DAG).
  • Emet un evenement outbox signe case.subcase.spawned par enfant.
• waitNodeHandler({ outboxSigner }) : le noeud d'attente externe.
  • A l'entree : execute les effets du noeud, enregistre une attente externe (jeton neuf), planifie le timer de timeout si wait.timeout est declare, emet un evenement signe case.external.waiting, puis se gare sur le noeud. Le dossier est repris par le moteur via resumeFromExternal (webhook : wait.onResolve, sinon la 1re transition sortante) ou expireExternalWait (timeout : wait.onTimeout ; no-op sans onTimeout). Ce handler ne fait que garer ; il ne reprend jamais.
• registerAdvancedHandlers(registry, { outboxSigner }) : enregistre les deux handlers.
• Brique : resumeActionFor.

Note de securite : tout echoue ferme. Un noeud subprocess sans transition de reprise leve ; le handler exige le contexte du moteur (spawnChild / submitChild) et leve en dehors. Une attente externe inconnue ou deja close leve (jamais appliquee deux fois).

License

Apache-2.0.