@nzelajs/core

English below · Version francaise plus bas.

The Nzela engine core: the transition loop (guards, optimistic locking, event log, signed outbox, dependency joins) with node-entry behavior fully delegated to a NodeHandler registry. Vendor-free: its only dependencies are @nzelajs/blueprint and @nzelajs/ports.

English

Install

npm add @nzelajs/core @nzelajs/blueprint @nzelajs/ports

What it provides

• NzelaEngine implements the WorkflowEngine port: dispatch (actor action, idempotent, optionally authorized deny-by-default), advanceCase (system clock tick over time-guarded auto transitions), resumeFromExternal / expireExternalWait (wait-node wake-up), and decideTask which delegates to the registered approval handler when it is an ApprovalCapableHandler.
• No switch (node.type): on entering a node the core consults the NodeHandlerRegistry and delegates. A type with no registered handler is a resting node (safe default: nothing runs).
• Transition sequence (ported from the source engine): assert guards, cancel source-node timers, cancel open source-node approval tasks, optimistic-locked status write, TRANSITION event, transition effects, signed case.transitioned outbox event, dependency joins (DAG wake-up of blocked instances), then enter the target node via its handler.
• Helpers: InMemoryNodeHandlerRegistry, buildGuardContext / buildExpressionContext, parseIsoDuration, canonicalize / outboxEventMaterial (pure canonical signing material), requiredPermissionFor.

Wiring example

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

const handlers = new InMemoryNodeHandlerRegistry();
registerGenericHandlers(handlers); // state + auto; approval/subprocess/wait are opt-in packages

const engine = new NzelaEngine({
  uow, // UnitOfWork adapter (tenant-scoped transactions)
  blueprints, // BlueprintProvider adapter
  guards, // GuardRunner adapter
  effects, // EffectRunner adapter
  clock, // systemClock or fixedClock(...)
  outboxSigner, // HMAC signer
  handlers,
  // authorizer, resolverFactory, tenantContext: optional
});

Security note: authorization is opt-in but deny-by-default once an Authorizer is wired; the engine asks for transition.permission when declared, else the conventional submit/withdraw/dispatch mapping. Guards fail closed. The outbox payload is signed with a canonical, tenant-bound material.

Francais

Installation

npm add @nzelajs/core @nzelajs/blueprint @nzelajs/ports

Ce que ca fournit

• NzelaEngine implemente le port WorkflowEngine : dispatch (action d'un acteur, idempotente, autorisation deny-by-default optionnelle), advanceCase (tick d'horloge sur les transitions auto gardees par le temps), resumeFromExternal / expireExternalWait (reveil des noeuds d'attente), et decideTask qui delegue au handler approval enregistre quand il est un ApprovalCapableHandler.
• Aucun switch (node.type) : a l'entree d'un noeud, le coeur consulte le NodeHandlerRegistry et delegue. Un type sans handler = noeud au repos (defaut sur : rien ne s'execute).
• Sequence de transition (portee du moteur source) : gardes, annulation des timers du noeud source, annulation des taches ouvertes du noeud source, ecriture du statut sous verrou optimiste, evenement TRANSITION, effets de transition, evenement outbox signe case.transitioned, jointures de dependances (reveil DAG), puis entree dans le noeud cible via son handler.
• Helpers : InMemoryNodeHandlerRegistry, buildGuardContext / buildExpressionContext, parseIsoDuration, canonicalize / outboxEventMaterial, requiredPermissionFor.

Note de securite : l'autorisation est opt-in mais deny-by-default des qu'un Authorizer est branche ; les gardes echouent fermees ; l'outbox est signee sur un materiel canonique lie au tenant.

License

Apache-2.0