@nzelajs/blueprint

English below · Version francaise plus bas.

The blueprint schema of the Nzela engine: the process graph (nodes and transitions) that the engine executes, the studio authors, and the validator guards. Vendor-free (pure types and functions), the single source of truth shared across the whole toolchain.

English

Install

npm add @nzelajs/blueprint

What it provides

• Graph model: BlueprintGraph, BlueprintNode, Transition, NodeType (state | auto | approval | subprocess | wait), plus ApproverSpec, SlaSpec, TimerSpec, SubprocessSpec, WaitSpec.
• Generic instance: WorkflowInstance { id, tenantId, status, version, data }, with an optional approval extension (requesterId, beneficiaryId) read only by the approval node handler.
• Helpers: findNode, findTransition, findAutoTransition(s), initialNode, submitTransition.
• Validator: parseBlueprint(input, { palette?, validateExpression? }), fail-closed. Shape checks always run; when a Palette is given, node types, named guards and effects must be declared.
• Injected expression check (vendor-free): pass validateExpression: (expr) => void and every inline cel: guard is compile-checked at publish time (its throw becomes a BlueprintSemanticError). The core imports NO expression engine: an app wires this callback to an adapter, e.g. @nzelajs/adapter-expr-cel's validateCelExpression. Omit it and behavior is unchanged (broken expressions then surface fail-closed at runtime instead of at publish).

Example

import { parseBlueprint, type BlueprintGraph } from "@nzelajs/blueprint";

const graph: BlueprintGraph = {
  entityType: "leave-request",
  nodes: [
    { id: "DRAFT", type: "state" },
    { id: "N1", type: "approval", approver: { kind: "ORG_CHAIN", level: 1 } },
    { id: "APPROVED", type: "state", terminal: true },
  ],
  transitions: [
    { from: "DRAFT", action: "submit", to: "N1" },
    { from: "N1", action: "approve", to: "APPROVED" },
    { from: "N1", action: "return", to: "DRAFT" },
  ],
};

parseBlueprint(graph); // throws BlueprintShapeError / BlueprintSemanticError on any violation

Security note: a blueprint may be authored by a non-technical client through the studio. Always run parseBlueprint (ideally with a Palette) before persisting. Validation is deny-by-default.

Francais

Installation

npm add @nzelajs/blueprint

Ce que ca fournit

• Modele de graphe : BlueprintGraph, BlueprintNode, Transition, NodeType (state | auto | approval | subprocess | wait), plus ApproverSpec, SlaSpec, TimerSpec, SubprocessSpec, WaitSpec.
• Instance generique : WorkflowInstance { id, tenantId, status, version, data }, avec une extension d'approbation optionnelle (requesterId, beneficiaryId) lue par le seul handler d'approbation.
• Helpers : findNode, findTransition, findAutoTransition(s), initialNode, submitTransition.
• Validator : parseBlueprint(input, { palette?, validateExpression? }), fail-closed. Les controles de forme sont toujours appliques ; avec une Palette, les types de noeud, gardes nommees et effets doivent etre declares.
• Controle d'expression injecte (sans vendor) : fournissez validateExpression: (expr) => void et chaque garde cel: est compilee/verifiee a la publication (son exception devient une BlueprintSemanticError). Le coeur n'importe AUCUN moteur d'expression : l'app branche ce callback sur un adapter, ex. validateCelExpression de @nzelajs/adapter-expr-cel. Sans lui, comportement inchange (une expression invalide echoue alors fail-closed au runtime au lieu de la publication).

Note de securite : un blueprint peut etre edite par un client non technique via le studio. Toujours executer parseBlueprint (idealement avec une Palette) avant de persister. Validation deny-by-default.

License

Apache-2.0.