@mfeflow/event-bus 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @mfeflow/event-bus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed event bus for micro-frontends on one page. Remotes publish and subscribe by event name; they never import each other. Event names are versioned (`cart.item-added.v1`), payload types come from a map each contract adds to, and late subscribers can be given the last payload.
+
+## Install
+
+```sh
+pnpm add @mfeflow/event-bus
+```
+
+`react` (19) is an optional peer dependency, needed only for `@mfeflow/event-bus/react`. In a project made with mfeflow, `mfeflow add event-bus` does all of this and creates the contracts package.
+
+## Usage
+
+```ts
+// packages/contracts: the types, shared by every remote
+export interface Events {
+  'cart.item-added.v1': { sku: string; qty: number };
+  'cart.cleared.v1': undefined;
+}
+```
+
+```ts
+// each app, once
+import type { Events } from '@acme/contracts/events';
+
+declare module '@mfeflow/event-bus' {
+  interface EventMap extends Events {}
+}
+```
+
+```ts
+// catalog
+import { publish } from '@mfeflow/event-bus';
+publish('cart.item-added.v1', { sku: 'A1', qty: 1 });
+
+// cart
+import { useEvent } from '@mfeflow/event-bus/react';
+useEvent('cart.item-added.v1', ({ sku, qty }) => addLine(sku, qty));
+```
+
+A wrong name, a wrong payload or a missing payload fails typecheck. A handler that throws is logged and does not stop the others.
+
+### Replay for late subscribers
+
+```ts
+import { configureEvent } from '@mfeflow/event-bus';
+configureEvent('session.changed.v1', { replay: true });
+```
+
+A remote that mounts after the event was published gets the last payload when it subscribes. Off by default: most events are things that happened, not state. Under React StrictMode a replayed event reaches the handler once per mount, so keep that handler idempotent.
+
+### Validating payloads
+
+Nothing validates in the core bundle. Pass any function that returns the payload or throws:
+
+```ts
+import { fromStandardSchema } from '@mfeflow/event-bus/standard-schema';
+configureEvent('cart.item-added.v1', { validate: fromStandardSchema(itemAddedSchema) });
+```
+
+`fromStandardSchema` takes a Zod 3.24+, Valibot 1+ or ArkType 2+ schema (the [Standard Schema](https://standardschema.dev) interface, copied in, so it is not a dependency). A rejected payload reaches nobody, `publish` returns `false`, and the log names the event and the schema's message, never the payload.
+
+## Module Federation sharing
+
+Bucket: **singleton**. Share `@mfeflow/event-bus` and `@mfeflow/event-bus/react` (`@mfeflow/rsbuild` does). The registry also lives on `globalThis`, so a second copy of the same version still reaches the same subscribers (and warns in development that two copies are loaded). A copy that finds a registry from an incompatible version keeps its own, warns in development, and talks to other copies through `window` events.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/bus.d.ts

@@ -0,0 +1,34 @@
+import type { EventMap } from './index.js';
+/** The names an event can be published under. */
+export type EventName = Extract<keyof EventMap, string>;
+export type Handler<K extends EventName> = (payload: EventMap[K]) => void;
+/** `[]` for an event whose payload is `undefined`, `[payload]` for the rest. */
+export type PayloadArgs<K extends EventName> = [EventMap[K]] extends [undefined] ? [payload?: undefined] : [payload: EventMap[K]];
+export interface EventConfig<T> {
+    /** Give each new subscriber the last payload right away. Off by default: most events are things that happened, not state. */
+    replay?: boolean;
+    /**
+     * Runs on every publish. Return the payload (parsed, if you like) or throw to reject it: a
+     * rejected payload reaches nobody. No validator ships here; `@mfeflow/event-bus/standard-schema`
+     * turns a Zod, Valibot or ArkType schema into one.
+     */
+    validate?: (payload: unknown) => T;
+}
+export interface SubscribeOptions {
+    /** Skip the replayed payload of an event that replays. Default true. */
+    replay?: boolean | undefined;
+}
+export declare function isEventName(name: string): boolean;
+/**
+ * Tells every subscriber, in every remote on the page. Returns false when the event's validator
+ * rejected the payload (nothing was sent, and the reason is logged without the payload).
+ */
+export declare function publish<K extends EventName>(name: K, ...args: PayloadArgs<K>): boolean;
+/** Calls `handler` for every `name` published from now on. Returns the function that stops it. */
+export declare function subscribe<K extends EventName>(name: K, handler: Handler<K>, options?: SubscribeOptions): () => void;
+/** Sets how an event behaves. Safe to call from every remote that cares; later calls change only what they name. */
+export declare function configureEvent<K extends EventName>(name: K, config: EventConfig<EventMap[K]>): void;
+/** How many handlers are subscribed to `name`; for tests and the dev overlay. */
+export declare function listenerCount(name: string): number;
+/** Only for tests: forgets every subscriber, replayed payload and setting. */
+export declare function resetEventBusForTests(): void;

package/dist/bus.js

@@ -0,0 +1,118 @@
+import { broadcast, listen, stopListening } from "./channel.js";
+import { registry, resetRegistry } from "./registry.js";
+import { resetWarningsForTests, warnOnce } from "./warn.js";
+const NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+\.v[1-9][0-9]*$/;
+function isEventName(name) {
+    return NAME.test(name);
+}
+function checkName(name) {
+    if (!NAME.test(name)) warnOnce(`"${name}" is not a versioned event name; use <domain>.<event>.v<major>, like cart.item-added.v1`);
+}
+function reportHandlerError(name, error) {
+    console.error(`[mfeflow/event-bus] a handler for "${name}" threw`, error);
+}
+function call(name, handler, payload) {
+    try {
+        handler(payload);
+    } catch (error) {
+        reportHandlerError(name, error);
+    }
+}
+function deliver(r, name, payload) {
+    const set = r.listeners.get(name);
+    if (!set) return;
+    for (const subscription of Array.from(set))if (set.has(subscription)) call(name, subscription.handler, payload);
+}
+function remember(r, name, payload) {
+    if (r.config.get(name)?.replay) r.last.set(name, payload);
+}
+const DELIVERED_KEPT = 64;
+const origin = Math.random().toString(36).slice(2);
+let sent = 0;
+function alreadyDelivered(r, id) {
+    if (r.delivered.has(id)) return true;
+    r.delivered.add(id);
+    if (r.delivered.size > DELIVERED_KEPT) {
+        const oldest = r.delivered.values().next();
+        if (!oldest.done) r.delivered.delete(oldest.value);
+    }
+    return false;
+}
+function checked(r, name, payload) {
+    const validate = r.config.get(name)?.validate;
+    if (!validate) return {
+        payload
+    };
+    try {
+        return {
+            payload: validate(payload)
+        };
+    } catch (error) {
+        return {
+            reason: error instanceof Error ? error.message : 'invalid payload'
+        };
+    }
+}
+function receive(id, name, payload) {
+    const r = registry();
+    if (alreadyDelivered(r, id)) return;
+    const result = checked(r, name, payload);
+    if ('reason' in result) return void console.error(`[mfeflow/event-bus] "${name}" was not delivered: ${result.reason}`);
+    remember(r, name, result.payload);
+    deliver(r, name, result.payload);
+}
+function publish(name, ...args) {
+    checkName(name);
+    const r = registry();
+    const result = checked(r, name, args[0]);
+    if ('reason' in result) {
+        console.error(`[mfeflow/event-bus] "${name}" was not sent: ${result.reason}`);
+        return false;
+    }
+    const id = `${origin}:${String(sent++)}`;
+    alreadyDelivered(r, id);
+    remember(r, name, result.payload);
+    deliver(r, name, result.payload);
+    listen(receive);
+    broadcast(id, name, result.payload);
+    return true;
+}
+function subscribe(name, handler, options = {}) {
+    checkName(name);
+    const r = registry();
+    listen(receive);
+    const subscription = {
+        handler: handler
+    };
+    const set = r.listeners.get(name) ?? new Set();
+    r.listeners.set(name, set);
+    set.add(subscription);
+    if (false !== options.replay && r.config.get(name)?.replay && r.last.has(name)) call(name, subscription.handler, r.last.get(name));
+    return ()=>{
+        set.delete(subscription);
+        if (0 === set.size && r.listeners.get(name) === set) r.listeners.delete(name);
+    };
+}
+function configureEvent(name, config) {
+    checkName(name);
+    const r = registry();
+    const before = r.config.get(name) ?? {
+        replay: false,
+        validate: void 0
+    };
+    const next = {
+        replay: config.replay ?? before.replay,
+        validate: config.validate ?? before.validate
+    };
+    r.config.set(name, next);
+    if (!next.replay) r.last.delete(name);
+}
+function listenerCount(name) {
+    return registry().listeners.get(name)?.size ?? 0;
+}
+function resetEventBusForTests() {
+    stopListening();
+    resetRegistry();
+    resetWarningsForTests();
+}
+export { configureEvent, isEventName, listenerCount, publish, resetEventBusForTests, subscribe };

package/dist/channel.d.ts

@@ -0,0 +1,10 @@
+export declare const CHANNEL_EVENT = "mfeflow:event-bus";
+/**
+ * Tells the other copies of the bus on this page, which may keep their own registry. Copies that
+ * share a registry get it twice and drop the second by `id`. Does nothing without a window.
+ */
+export declare function broadcast(id: string, name: string, payload: unknown): void;
+/** Hands each message to `deliver`. Listens once; a second call does nothing. */
+export declare function listen(deliver: (id: string, name: string, payload: unknown) => void): void;
+/** Only for tests. */
+export declare function stopListening(): void;

package/dist/channel.js

@@ -0,0 +1,33 @@
+const CHANNEL_EVENT = 'mfeflow:event-bus';
+function isMessage(value) {
+    return 'object' == typeof value && null !== value && 'string' == typeof Reflect.get(value, 'id') && 'string' == typeof Reflect.get(value, 'name');
+}
+let stop;
+function broadcast(id, name, payload) {
+    if ("u" < typeof window) return;
+    const detail = {
+        id,
+        name,
+        payload
+    };
+    window.dispatchEvent(new CustomEvent(CHANNEL_EVENT, {
+        detail
+    }));
+}
+function listen(deliver) {
+    if ("u" < typeof window || stop) return;
+    const on = (event)=>{
+        if (!(event instanceof CustomEvent)) return;
+        const detail = event.detail;
+        if (isMessage(detail)) deliver(detail.id, detail.name, detail.payload);
+    };
+    window.addEventListener(CHANNEL_EVENT, on);
+    stop = ()=>{
+        window.removeEventListener(CHANNEL_EVENT, on);
+    };
+}
+function stopListening() {
+    stop?.();
+    stop = void 0;
+}
+export { CHANNEL_EVENT, broadcast, listen, stopListening };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Every event the platform knows, with its payload. Empty here: contracts add to it by
+ * declaration merging, so `publish('cart.item-added.v1', { sku })` is checked end to end.
+ *
+ *   declare module '@mfeflow/event-bus' {
+ *     interface EventMap {
+ *       'cart.item-added.v1': { sku: string };
+ *       'cart.cleared.v1': undefined;
+ *     }
+ *   }
+ */
+export interface EventMap {
+}
+export { configureEvent, isEventName, listenerCount, publish, resetEventBusForTests, subscribe, type EventConfig, type EventName, type Handler, type PayloadArgs, type SubscribeOptions, } from './bus.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { configureEvent, isEventName, listenerCount, publish, resetEventBusForTests, subscribe } from "./bus.js";

package/dist/react.d.ts

@@ -0,0 +1,7 @@
+import { type EventName, type Handler, type SubscribeOptions } from './bus.js';
+/**
+ * Calls `handler` for each `name` while the component is mounted. The handler may change on every
+ * render without resubscribing. An event that replays calls it once on mount with the last payload,
+ * which under StrictMode happens once per mount, so keep a handler that replays idempotent.
+ */
+export declare function useEvent<K extends EventName>(name: K, handler: Handler<K>, options?: SubscribeOptions): void;

package/dist/react.js

@@ -0,0 +1,18 @@
+import { useEffect, useRef } from "react";
+import { subscribe } from "./bus.js";
+function useEvent(name, handler, options = {}) {
+    const latest = useRef(handler);
+    useEffect(()=>{
+        latest.current = handler;
+    });
+    const { replay } = options;
+    useEffect(()=>subscribe(name, (payload)=>{
+            latest.current(payload);
+        }, {
+            replay
+        }), [
+        name,
+        replay
+    ]);
+}
+export { useEvent };

package/dist/registry.d.ts

@@ -0,0 +1,31 @@
+/** Bumped when the shape of the shared registry changes; copies that disagree stop sharing it. */
+export declare const PROTOCOL = 1;
+export type Listener = (payload: unknown) => void;
+/** One subscription. The set holds these, not the functions, so subscribing a function twice is two subscriptions. */
+export interface Subscription {
+    readonly handler: Listener;
+}
+export interface Config {
+    replay: boolean;
+    validate: ((payload: unknown) => unknown) | undefined;
+}
+export interface Registry {
+    protocol: number;
+    listeners: Map<string, Set<Subscription>>;
+    /** The last payload of each event that replays. */
+    last: Map<string, unknown>;
+    config: Map<string, Config>;
+    /** Ids of the latest events delivered, so an event that arrives twice (directly and over the window) is delivered once. */
+    delivered: Set<string>;
+    /** One entry per copy of this package that has used the registry. */
+    copies: Set<symbol>;
+}
+/**
+ * The registry every copy of this package on the page shares, kept on `globalThis` so a second
+ * copy (a missing singleton share) still reaches the same subscribers. A copy that finds one it
+ * cannot read (another protocol) keeps its own and talks to the other copies through
+ * the window bridge in `./channel` only.
+ */
+export declare function registry(): Registry;
+/** Only for tests: forgets every subscriber, replayed payload and setting, and this copy's isolation. */
+export declare function resetRegistry(): void;

package/dist/registry.js

@@ -0,0 +1,42 @@
+import { warnOnce } from "./warn.js";
+const PROTOCOL = 1;
+const KEY = Symbol.for('mfeflow.event-bus');
+const COPY = Symbol('copy');
+function create() {
+    return {
+        protocol: PROTOCOL,
+        listeners: new Map(),
+        last: new Map(),
+        config: new Map(),
+        delivered: new Set(),
+        copies: new Set()
+    };
+}
+function isRegistry(value) {
+    return 'object' == typeof value && null !== value && Reflect.get(value, 'protocol') === PROTOCOL && Reflect.get(value, 'listeners') instanceof Map && Reflect.get(value, 'last') instanceof Map && Reflect.get(value, 'config') instanceof Map && Reflect.get(value, 'delivered') instanceof Set && Reflect.get(value, 'copies') instanceof Set;
+}
+let own;
+function attach(shared) {
+    if (shared.copies.has(COPY)) return shared;
+    shared.copies.add(COPY);
+    if (shared.copies.size > 1) warnOnce('two copies of @mfeflow/event-bus are loaded on this page. They share their subscribers, so events still arrive, but a remote is bundling its own copy: share @mfeflow/event-bus as a singleton (@mfeflow/rsbuild does) and make sure the shell imports it.');
+    return shared;
+}
+function registry() {
+    if (own) return own;
+    const existing = Reflect.get(globalThis, KEY);
+    if (void 0 === existing) {
+        const fresh = create();
+        Reflect.set(globalThis, KEY, fresh);
+        return attach(fresh);
+    }
+    if (isRegistry(existing)) return attach(existing);
+    warnOnce('another copy of @mfeflow/event-bus on this page speaks a different protocol, so this copy cannot share its subscribers. It falls back to window events; share @mfeflow/event-bus as a singleton so one copy is loaded.');
+    own = create();
+    return own;
+}
+function resetRegistry() {
+    own = void 0;
+    Reflect.deleteProperty(globalThis, KEY);
+}
+export { PROTOCOL, registry, resetRegistry };

package/dist/standard-schema.d.ts

@@ -0,0 +1,28 @@
+/** The Standard Schema interface (https://standardschema.dev), copied here so no validator is a dependency. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly {
+        readonly message: string;
+    }[];
+};
+/**
+ * Turns a Standard Schema (Zod 3.24+, Valibot 1+, ArkType 2+) into an event's `validate`. Failures
+ * list the schema's messages and never the payload, so a rejected event cannot leak what was in it.
+ *
+ *   configureEvent('cart.item-added.v1', { validate: fromStandardSchema(itemAdded) });
+ */
+export declare function fromStandardSchema<Output>(schema: StandardSchemaV1<unknown, Output>): (payload: unknown) => Output;
+export {};

package/dist/standard-schema.js

@@ -0,0 +1,12 @@
+function fromStandardSchema(schema) {
+    return (payload)=>{
+        const result = schema['~standard'].validate(payload);
+        if (result instanceof Promise) {
+            result.catch(()=>void 0);
+            throw new TypeError('the schema validates asynchronously, and events are delivered synchronously');
+        }
+        if (result.issues) throw new TypeError(result.issues.map((issue)=>issue.message).join('; '));
+        return result.value;
+    };
+}
+export { fromStandardSchema };

package/dist/warn.d.ts

@@ -0,0 +1,5 @@
+/** Dev builds warn about mistakes; production builds stay quiet. Bundlers replace `process.env.NODE_ENV`. */
+export declare const isDev: () => boolean;
+export declare function warnOnce(message: string): void;
+/** Only for tests. */
+export declare function resetWarningsForTests(): void;

package/dist/warn.js

@@ -0,0 +1,11 @@
+const seen = new Set();
+const isDev = ()=>'production' !== process.env.NODE_ENV;
+function warnOnce(message) {
+    if (!isDev() || seen.has(message)) return;
+    seen.add(message);
+    console.warn(`[mfeflow/event-bus] ${message}`);
+}
+function resetWarningsForTests() {
+    seen.clear();
+}
+export { isDev, resetWarningsForTests, warnOnce };

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@mfeflow/event-bus",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A typed event bus for micro-frontends on one page: versioned event names, payload types merged by each remote, optional validation, replay for late subscribers, and a React hook.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "event-bus",
+    "pub-sub",
+    "typescript",
+    "react"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/event-bus"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./standard-schema": {
+      "types": "./dist/standard-schema.d.ts",
+      "import": "./dist/standard-schema.js",
+      "default": "./dist/standard-schema.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mfeflow/contracts": "0.2.0",
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "singleton"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }