@nzelajs/ports

English below · Version francaise plus bas.

The hexagonal port contracts of the Nzela engine: persistence, tenant isolation, clock, outbox, guard/effect runners, approver resolution, authorization, identity, and the NodeHandler seam. No vendor here (the port is a sas, not a hiding place). The authorization seam is agnostic: it carries an attempt, never a permission grammar.

English

Install

npm add @nzelajs/ports

What it provides

• Tenancy (security first): TenantContextPort, UnitOfWork.withTenant (tenant-scoped transaction, Postgres RLS enforced) so a query can never cross tenants.
• Persistence: RepositoryRegistry (instances, events, timers, external waits, dependencies, blueprints, outbox; optional approvalTasks/authz), all ORM-agnostic. BlueprintInstallStore is versioned + immutable + pinned (editing never breaks a running instance).
• Runners: GuardRunner (deny-by-default predicates), EffectRunner (named side-effects).
• Authorization: Authorizer and AuthorizationAttempt (an agnostic seam: the engine describes WHAT an actor attempts - actor, instance, action, transition/task level - and invents NO permission string; an adapter maps the attempt to its own model, be it permissions, roles or a policy engine). RelationResolver, Grant and OrgRelation are reused from @kengela/contracts for adapters that need them (not redeclared).
• NodeHandler: the extensibility seam that lets the core dispatch node behavior without a hardcoded switch. Generic apps register state/auto; approval apps add approval/wait/subprocess.
• Engine surface: WorkflowEngine (dispatch, advanceCase, decideTask, resumeFromExternal).
• Org-chart companions (optional): DeskRuleStore (desk queue auto-assignment rules, wildcard "*" type, decreasing-specificity lookup), TenantSettingsStore (per-step returnRouting override of the N-1 return rule), OrgStore (deprovisioning + unit lookups) and DirectoryStore (display names for the chain preview). All four are OPTIONAL members of RepositoryRegistry (deskRules, tenantSettings, org, directory): a generic app never provides them.

Francais

Installation

npm add @nzelajs/ports

Ce que ca fournit

• Multi-tenant (securite d'abord) : TenantContextPort, UnitOfWork.withTenant (transaction scopee tenant, RLS Postgres) - une requete ne peut jamais franchir un tenant.
• Persistance : RepositoryRegistry (instances, evenements, timers, attentes externes, dependances, blueprints, outbox ; approvalTasks/authz optionnels), agnostique de l'ORM. BlueprintInstallStore versionne + immuable + epingle (l'edition ne casse pas un dossier en cours).
• Runners : GuardRunner (predicats deny-by-default), EffectRunner (side-effects nommes).
• Autorisation : Authorizer et AuthorizationAttempt (une couture agnostique : le moteur decrit CE QUE tente un acteur - acteur, instance, action, niveau transition/tache - et n'invente AUCUNE chaine de permission ; un adapter mappe la tentative vers son propre modele, permissions, roles ou moteur de politique). RelationResolver, Grant et OrgRelation sont reutilises depuis @kengela/contracts pour les adapters qui en ont besoin (non redeclares).
• NodeHandler : la couture d'extensibilite qui laisse le coeur dispatcher le comportement d'un noeud sans switch code en dur. Apps generiques : state/auto ; apps d'approbation : + approval.
• Surface moteur : WorkflowEngine (dispatch, advanceCase, decideTask, resumeFromExternal).
• Compagnons organigramme (optionnels) : DeskRuleStore (regles d'auto-affectation des files de bureau, joker "*", resolution par specificite decroissante), TenantSettingsStore (override returnRouting par etape de la regle de renvoi N-1), OrgStore (deprovisionnement + unites) et DirectoryStore (noms affiches pour l'apercu du parcours). Les quatre sont des membres OPTIONNELS de RepositoryRegistry (deskRules, tenantSettings, org, directory) : une app generique ne les fournit jamais.

License

Apache-2.0.