Événements

@bext-stack/framework/events est un bus d'événements de domaine typé - l'équivalent pour les développeurs d'applications des événements + écouteurs de Laravel. Vous déclarez une carte d'événements (nom → type de charge utile), enregistrez les écouteurs et emit ; un événement se diffuse à chaque auditeur. Il dissocie le code que fait à du code auquel réagit, et il s'agit d'un TypeScript pur et entièrement typé.

Quand l'utiliser#

Une seule action a plusieurs effets secondaires indépendants (e-mail de bienvenue + espace de travail provisionnement + analyses lors de l'inscription) qui ne devraient pas être câblés ensemble.
Vous souhaitez ajouter une réaction à un flux existant sans toucher au flux.
Distribution à la demande et en cours de processus : synchrone ou asynchrone.

Déclaration et expédition#

import { createEventBus } from "@bext-stack/framework/events";

type AppEvents = {
  "user.registered": { id: string; email: string };
  "order.paid": { orderId: string; amount: number };
};

const bus = createEventBus<AppEvents>();

bus.on("user.registered", (u) => sendWelcome(u.email));    // payload is typed
bus.on("user.registered", (u) => provisionWorkspace(u.id));

await bus.emit("user.registered", { id: "u1", email: "a@b.co" }); // fans out, awaits async

emit attend chaque auditeur (y compris les auditeurs asynchrones). Si les auditeurs lancent, ils exécutent toujours et les erreurs font surface par la suite (une seule erreur est renvoyée ; plusieurs deviennent un AggregateError ) — un mauvais auditeur n'avale jamais silencieusement le reste. emitSync est la variante « feu et oubli ».

Membre	Fait
`on(event, fn)`	enregistrer un auditeur ; renvoie un fn de désabonnement
`once(event, fn)`	écouteur unique (supprimé automatiquement après la première émission)
`off(event, fn)`	supprimer un auditeur
`emit(event, payload)`	diffusion asynchrone, attend tous les auditeurs
`emitSync(event, payload)`	tirer et oublier
`listenerCount(event)` / `removeAll(event?)`	introspection / démontage

Enregistrez-en plusieurs à la fois (carte $listen de Laravel) avec subscribe :

import { subscribe } from "@bext-stack/framework/events";

const off = subscribe(bus, {
  "user.registered": [(u) => sendWelcome(u.email), (u) => provisionWorkspace(u.id)],
  "order.paid": (o) => fulfil(o.orderId),
});

Conseil

Un bus est en mémoire et propre à chaque isolat V8. Enregistrez les écouteurs au niveau du module, exécuté une fois par isolat afin que chaque isolat dispose du même ensemble, puis émettez au cours de la même requête ou du même rendu : c’est le cas courant et déterministe. Pour une diffusion durable, entre requêtes ou entre processus, utilisez plutôt la file du SDK pour les tâches en arrière-plan ou la diffusion en temps réel. Ce mécanisme est un répartiteur synchrone interne à l’application, pas un bus durable.

Essayez-le#

La démonstration des événements en ligne distribue un unique événement user.registered à trois écouteurs indépendants. Code source dans sites/demo/src/app/examples/events/page.tsx.

Voir aussi#

Tâches en arrière-plan / Flux durables — pour des réactions durables entre processus.
Notifications — une cible courante pour les écouteurs : e-mail, SMS, Slack ou notifications dans l’application.
Boîte à outils de candidature — le reste de la couche d'application TypeScript.