@fluojs/event-bus 1.0.0-beta.1

package/dist/transports/redis-transport.d.ts

@@ -0,0 +1,57 @@
+import type { Redis } from 'ioredis';
+import type { EventBusTransport } from '../types.js';
+/** Clients used by {@link RedisEventBusTransport} for publish and subscribe responsibilities. */
+export interface RedisEventBusTransportOptions {
+    publishClient: Redis;
+    subscribeClient: Redis;
+}
+/**
+ * Redis Pub/Sub transport adapter for cross-process event fan-out.
+ *
+ * @example
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { RedisEventBusTransport } from '@fluojs/event-bus/redis';
+ *
+ * const publishClient = new Redis();
+ * const subscribeClient = new Redis();
+ *
+ * const transport = new RedisEventBusTransport({ publishClient, subscribeClient });
+ * ```
+ */
+export declare class RedisEventBusTransport implements EventBusTransport {
+    private readonly publishClient;
+    private readonly subscribeClient;
+    private readonly handlersByChannel;
+    private messageListenerAttached;
+    /**
+     * Creates a Redis-backed event-bus transport.
+     *
+     * @param options Redis clients dedicated to publish and subscribe operations.
+     */
+    constructor(options: RedisEventBusTransportOptions);
+    private readonly onMessage;
+    /**
+     * Publishes one event payload to a Redis Pub/Sub channel.
+     *
+     * @param channel Channel name derived from the event type.
+     * @param payload Serializable event payload.
+     * @returns A promise that resolves once Redis accepts the publication.
+     */
+    publish(channel: string, payload: unknown): Promise<void>;
+    /**
+     * Subscribes one local handler to a Redis Pub/Sub channel.
+     *
+     * @param channel Channel name to subscribe to.
+     * @param handler Async handler invoked with JSON-decoded payloads.
+     * @returns A promise that resolves once Redis confirms the subscription.
+     */
+    subscribe(channel: string, handler: (payload: unknown) => Promise<void>): Promise<void>;
+    /**
+     * Unsubscribes all tracked channels and detaches the Redis message listener.
+     *
+     * @returns A promise that resolves once the transport cleanup finishes.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=redis-transport.d.ts.map

package/dist/transports/redis-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-transport.d.ts","sourceRoot":"","sources":["../../src/transports/redis-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,iGAAiG;AACjG,MAAM,WAAW,6BAA6B;IAC5C,aAAa,EAAE,KAAK,CAAC;IACrB,eAAe,EAAE,KAAK,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0D;IAC5F,OAAO,CAAC,uBAAuB,CAAS;IAExC;;;;OAIG;gBACS,OAAO,EAAE,6BAA6B;IAKlD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAgBxB;IAEF;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/D;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7F;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAsB7B"}

package/dist/transports/redis-transport.js

@@ -0,0 +1,98 @@
+/** Clients used by {@link RedisEventBusTransport} for publish and subscribe responsibilities. */
+
+/**
+ * Redis Pub/Sub transport adapter for cross-process event fan-out.
+ *
+ * @example
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { RedisEventBusTransport } from '@fluojs/event-bus/redis';
+ *
+ * const publishClient = new Redis();
+ * const subscribeClient = new Redis();
+ *
+ * const transport = new RedisEventBusTransport({ publishClient, subscribeClient });
+ * ```
+ */
+export class RedisEventBusTransport {
+  publishClient;
+  subscribeClient;
+  handlersByChannel = new Map();
+  messageListenerAttached = false;
+
+  /**
+   * Creates a Redis-backed event-bus transport.
+   *
+   * @param options Redis clients dedicated to publish and subscribe operations.
+   */
+  constructor(options) {
+    this.publishClient = options.publishClient;
+    this.subscribeClient = options.subscribeClient;
+  }
+  onMessage = (receivedChannel, message) => {
+    const handler = this.handlersByChannel.get(receivedChannel);
+    if (!handler) {
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(message);
+    } catch {
+      return;
+    }
+    void handler(payload);
+  };
+
+  /**
+   * Publishes one event payload to a Redis Pub/Sub channel.
+   *
+   * @param channel Channel name derived from the event type.
+   * @param payload Serializable event payload.
+   * @returns A promise that resolves once Redis accepts the publication.
+   */
+  async publish(channel, payload) {
+    await this.publishClient.publish(channel, JSON.stringify(payload));
+  }
+
+  /**
+   * Subscribes one local handler to a Redis Pub/Sub channel.
+   *
+   * @param channel Channel name to subscribe to.
+   * @param handler Async handler invoked with JSON-decoded payloads.
+   * @returns A promise that resolves once Redis confirms the subscription.
+   */
+  async subscribe(channel, handler) {
+    this.handlersByChannel.set(channel, handler);
+    await this.subscribeClient.subscribe(channel);
+    if (!this.messageListenerAttached) {
+      this.subscribeClient.on('message', this.onMessage);
+      this.messageListenerAttached = true;
+    }
+  }
+
+  /**
+   * Unsubscribes all tracked channels and detaches the Redis message listener.
+   *
+   * @returns A promise that resolves once the transport cleanup finishes.
+   */
+  async close() {
+    let closeError;
+    const channels = [...this.handlersByChannel.keys()];
+    try {
+      if (channels.length > 0) {
+        await this.subscribeClient.unsubscribe(...channels);
+      }
+    } catch (error) {
+      closeError = error;
+    } finally {
+      this.handlersByChannel.clear();
+      if (this.messageListenerAttached) {
+        this.subscribeClient.off('message', this.onMessage);
+        this.messageListenerAttached = false;
+      }
+    }
+    if (closeError) {
+      throw closeError;
+    }
+  }
+}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+import type { MetadataPropertyKey, Token } from '@fluojs/core';
+/** Constructor type used to identify one published event shape and optional stable transport key. */
+export interface EventType<TEvent extends object = object> {
+    new (...args: never[]): TEvent;
+    readonly eventKey?: string;
+}
+/** Metadata stored by {@link OnEvent}. */
+export interface EventHandlerMetadata {
+    eventType: EventType;
+}
+/** Runtime descriptor for one discovered event handler method. */
+export interface EventHandlerDescriptor {
+    eventType: EventType;
+    methodKey: MetadataPropertyKey;
+    methodName: string;
+    moduleName: string;
+    targetName: string;
+    token: Token;
+}
+/** Options that control how one `publish()` call waits for local handlers. */
+export interface EventPublishOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    waitForHandlers?: boolean;
+}
+/** Transport adapter contract for cross-process event fan-out and inbound subscription wiring. */
+export interface EventBusTransport {
+    /**
+     * Publish an event payload to the external transport under the given channel name.
+     * Called by the event bus on every local `publish()` invocation when a transport is configured.
+     */
+    publish(channel: string, payload: unknown): Promise<void>;
+    /**
+     * Subscribe to incoming messages on the given channel from the external transport.
+     * The event bus calls this once per discovered local handler during bootstrap.
+     * Received messages are deserialized and dispatched to matching local handlers.
+     */
+    subscribe(channel: string, handler: (payload: unknown) => Promise<void>): Promise<void>;
+    /**
+     * Tear down any open connections. Called during application shutdown.
+     */
+    close(): Promise<void>;
+}
+/** Module options for local event dispatch defaults and optional external fan-out. */
+export interface EventBusModuleOptions {
+    publish?: {
+        timeoutMs?: number;
+        waitForHandlers?: boolean;
+    };
+    /**
+     * Optional external transport adapter (e.g. Redis Pub/Sub).
+     * When provided, `publish()` fans out to the transport in addition to local handlers,
+     * and incoming transport messages are dispatched to local handlers on bootstrap.
+     */
+    transport?: EventBusTransport;
+}
+/** Event publishing facade exposed by the event-bus module. */
+export interface EventBus {
+    /**
+     * Publishes one event to matching local handlers and the optional external transport.
+     *
+     * @param event Event instance to publish.
+     * @param options Optional timeout, abort signal, and wait-for-handler controls.
+     * @returns A promise that resolves once the configured publish workflow completes.
+     */
+    publish(event: object, options?: EventPublishOptions): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE/D,qGAAqG;AACrG,MAAM,WAAW,SAAS,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IACvD,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExF;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,CAAC;IACF;;;;OAIG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@fluojs/event-bus",
+  "description": "In-process event publishing and handler discovery for Fluo applications.",
+  "keywords": [
+    "fluo",
+    "event-bus",
+    "events",
+    "pubsub",
+    "in-process"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/event-bus"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./redis": {
+      "types": "./dist/transports/redis-transport.d.ts",
+      "import": "./dist/transports/redis-transport.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}