@beignet/provider-event-bus-memory 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-event-bus-memory
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,227 @@
+# @beignet/provider-event-bus-memory
+
+In-memory `EventBusPort` adapter for Beignet applications.
+
+Use it for tests, local development, and single-process apps. Distributed
+systems should adapt a queue, stream, outbox, or message broker behind the same
+`EventBusPort` interface.
+
+## Install
+
+```bash
+bun add @beignet/provider-event-bus-memory
+```
+
+## Direct setup
+
+```typescript
+import { defineEvent } from "@beignet/core/events";
+import { createInMemoryEventBus } from "@beignet/provider-event-bus-memory";
+import { z } from "zod";
+
+// Define your domain events
+const UserRegistered = defineEvent("user.registered", {
+  payload: z.object({
+    userId: z.string(),
+    email: z.string().email(),
+  }),
+});
+
+// Create the event bus
+const eventBus = createInMemoryEventBus();
+
+// Subscribe to events
+const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+  console.log(`User registered: ${payload.email}`);
+  // Send welcome email, update analytics, etc.
+});
+
+// Publish events
+await eventBus.publish(UserRegistered, {
+  userId: "123",
+  email: "user@example.com",
+});
+
+// Unsubscribe when done
+unsubscribe();
+```
+
+## Framework setup
+
+```typescript
+import { createNextServer } from "@beignet/next";
+import { createInMemoryEventBusProvider } from "@beignet/provider-event-bus-memory";
+import { appPorts } from "@/infra/app-ports";
+import { routes } from "@/server/routes";
+
+export const server = await createNextServer({
+  ports: appPorts,
+  providers: [createInMemoryEventBusProvider()],
+  createContext: ({ ports }) => ({
+    ports,
+  }),
+  routes,
+});
+```
+
+Use `createInMemoryEventBus()` directly when you want to manually assign an
+event bus under `ports`.
+
+## Instrumentation
+
+Pass a provider instrumentation target when creating the direct event bus to
+record published events under the `eventBus` watcher:
+
+```typescript
+const eventBus = createInMemoryEventBus({
+  instrumentation: ports,
+});
+```
+
+## Using in use cases
+
+```typescript
+import { defineEvent } from "@beignet/core/events";
+import { z } from "zod";
+
+const OrderPlaced = defineEvent("order.placed", {
+  payload: z.object({
+    orderId: z.string(),
+    total: z.number(),
+  }),
+});
+
+// Subscribe to events in your application setup
+ctx.ports.eventBus.subscribe(OrderPlaced, async (payload) => {
+  // Send order confirmation email
+  await ctx.ports.mailer.send({
+    to: customer.email,
+    subject: "Order Confirmation",
+    text: `Your order ${payload.orderId} has been placed!`,
+  });
+});
+
+const placeOrder = useCase
+  .command("orders.place")
+  .input(PlaceOrderInput)
+  .output(OrderOutput)
+  .emits([OrderPlaced])
+  .run(async ({ ctx, input, events }) => {
+    return ctx.ports.uow.transaction(async (tx) => {
+      const order = await tx.orders.create(input);
+
+      await events.record(tx.events, OrderPlaced, {
+        orderId: order.id,
+        total: order.total,
+      });
+
+      return order;
+    });
+  });
+```
+
+## EventBus port API
+
+### `publish<E>(event: E, payload: InferEventPayload<E>): Promise<void> | void`
+
+Publish a domain event with a typed payload.
+
+```typescript
+await eventBus.publish(UserRegistered, {
+  userId: "123",
+  email: "user@example.com",
+});
+```
+
+By default, the in-memory bus awaits handlers so local development and tests are
+deterministic. Handler errors are rethrown unless `onHandlerError` is provided.
+Use `delivery: "fire-and-forget"` when you intentionally want detached
+in-process delivery.
+
+### `subscribe<E>(event: E, handler: (payload) => void | Promise<void>): () => void`
+
+Subscribe to a domain event. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+  console.log(`New user: ${payload.email}`);
+});
+
+// Later, when you want to stop listening:
+unsubscribe();
+```
+
+## TypeScript support
+
+The event bus provides full type safety:
+
+```typescript
+import type { EventBusPort } from "@beignet/core/ports";
+import { definePorts } from "@beignet/core/ports";
+
+// Type-safe ports definition
+const appPorts = definePorts({
+  eventBus: createInMemoryEventBus() as EventBusPort,
+  // ... other ports
+});
+
+type AppPorts = typeof appPorts;
+```
+
+## Testing
+
+The in-memory event bus is perfect for testing:
+
+```typescript
+import { describe, expect, it, mock } from "bun:test";
+
+describe("User Registration", () => {
+  it("should publish UserRegistered event", async () => {
+    const eventBus = createInMemoryEventBus();
+    const handler = mock(() => {});
+    
+    eventBus.subscribe(UserRegistered, handler);
+    
+    // Perform registration
+    await registerUser(ctx, { email: "test@example.com" });
+    
+    expect(handler).toHaveBeenCalledWith({
+      userId: expect.any(String),
+      email: "test@example.com",
+    });
+  });
+});
+```
+
+## Behavior
+
+- **Awaited by default**: `publish(...)` waits for subscribed handlers unless
+  `delivery: "fire-and-forget"` is configured
+- **In-process**: Events are only delivered within the same process
+- **Memory-only**: No persistence - events are lost if the process crashes
+- **Order**: Handlers are called in the order they were subscribed
+- **Multiple handlers**: Multiple handlers can subscribe to the same event
+- **Error handling**: Handler errors reject `publish(...)` unless
+  `onHandlerError` is configured
+
+## When to use
+
+Good for:
+
+- Single-process applications
+- Development and testing
+- Simple event-driven workflows
+- Decoupling application components
+
+Not suitable for:
+
+- Distributed systems
+- Event persistence requirements
+- Guaranteed delivery needs
+- Cross-service communication
+
+For production distributed systems, implement `EventBusPort` with a proper message broker.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @beignet/provider-event-bus-memory
+ *
+ * In-memory event bus provider that implements EventBusPort.
+ * Suitable for single-process applications or testing.
+ *
+ * For distributed systems, consider implementing EventBusPort with
+ * a message broker like RabbitMQ, Kafka, or Redis Pub/Sub.
+ *
+ * @example
+ * ```ts
+ * import { createInMemoryEventBus } from "@beignet/provider-event-bus-memory";
+ *
+ * const eventBus = createInMemoryEventBus();
+ *
+ * // Subscribe to an event
+ * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+ *   console.log(`User registered: ${payload.email}`);
+ * });
+ *
+ * // Publish an event
+ * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
+ *
+ * // Unsubscribe when done
+ * unsubscribe();
+ * ```
+ */
+import type { EventBusPort } from "@beignet/core/ports";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+/**
+ * Options for the in-memory event bus.
+ */
+export type InMemoryEventBusDelivery = "await-handlers" | "fire-and-forget";
+export interface InMemoryEventBusOptions {
+    /**
+     * Optional instrumentation target. Providers pass existing app ports here
+     * automatically; direct factory users can pass an instrumentation port.
+     */
+    instrumentation?: ProviderInstrumentationTarget;
+    /**
+     * How publish calls deliver events to subscribed handlers.
+     *
+     * Defaults to "await-handlers" so local development and tests observe handler
+     * work deterministically. Use "fire-and-forget" for detached in-process
+     * delivery when the caller should not wait for listeners.
+     */
+    delivery?: InMemoryEventBusDelivery;
+    /**
+     * Called when an async event handler throws an error.
+     *
+     * In "await-handlers" mode, handler errors are rethrown when this callback is
+     * not provided. In "fire-and-forget" mode, handler errors are swallowed when
+     * this callback is not provided so detached handlers do not create unhandled
+     * rejections.
+     *
+     * @param error  The error thrown by the handler
+     * @param eventName  The name of the event being handled
+     * @param payload  The event payload that was passed to the handler
+     */
+    onHandlerError?: (error: unknown, eventName: string, payload: unknown) => void;
+}
+export interface InMemoryEventBusProviderOptions extends Omit<InMemoryEventBusOptions, "instrumentation"> {
+    /**
+     * Provider name. Defaults to "event-bus-memory".
+     */
+    name?: string;
+}
+export interface InMemoryEventBusProviderPorts {
+    eventBus: EventBusPort;
+}
+/**
+ * Create an in-memory event bus implementation.
+ *
+ * This is suitable for single-process applications or testing.
+ * For distributed systems, you would implement EventBusPort with
+ * a message broker like RabbitMQ, Kafka, or Redis Pub/Sub.
+ *
+ * @example
+ * ```ts
+ * const eventBus = createInMemoryEventBus();
+ *
+ * eventBus.subscribe(UserRegistered, (payload) => {
+ *   console.log(`User registered: ${payload.email}`);
+ * });
+ *
+ * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With error handling
+ * const eventBus = createInMemoryEventBus({
+ *   onHandlerError: (error, eventName, payload) => {
+ *     logger.error(`Event handler failed for ${eventName}`, { error, payload });
+ *   },
+ * });
+ * ```
+ */
+export declare function createInMemoryEventBus(options?: InMemoryEventBusOptions): EventBusPort;
+export declare function createInMemoryEventBusProvider(options?: InMemoryEventBusProviderOptions): import("@beignet/core/providers").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
+    eventBus: EventBusPort;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AAEjC;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAE5E,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,eAAe,CAAC,EAAE,6BAA6B,CAAC;IAEhD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IAEpC;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,CACf,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,KACb,IAAI,CAAC;CACX;AAED,MAAM,WAAW,+BACf,SAAQ,IAAI,CAAC,uBAAuB,EAAE,iBAAiB,CAAC;IACxD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,YAAY,CAoFd;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,+BAAoC;;GAiB9C"}

package/dist/index.js

@@ -0,0 +1,142 @@
+/**
+ * @beignet/provider-event-bus-memory
+ *
+ * In-memory event bus provider that implements EventBusPort.
+ * Suitable for single-process applications or testing.
+ *
+ * For distributed systems, consider implementing EventBusPort with
+ * a message broker like RabbitMQ, Kafka, or Redis Pub/Sub.
+ *
+ * @example
+ * ```ts
+ * import { createInMemoryEventBus } from "@beignet/provider-event-bus-memory";
+ *
+ * const eventBus = createInMemoryEventBus();
+ *
+ * // Subscribe to an event
+ * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+ *   console.log(`User registered: ${payload.email}`);
+ * });
+ *
+ * // Publish an event
+ * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
+ *
+ * // Unsubscribe when done
+ * unsubscribe();
+ * ```
+ */
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+/**
+ * Create an in-memory event bus implementation.
+ *
+ * This is suitable for single-process applications or testing.
+ * For distributed systems, you would implement EventBusPort with
+ * a message broker like RabbitMQ, Kafka, or Redis Pub/Sub.
+ *
+ * @example
+ * ```ts
+ * const eventBus = createInMemoryEventBus();
+ *
+ * eventBus.subscribe(UserRegistered, (payload) => {
+ *   console.log(`User registered: ${payload.email}`);
+ * });
+ *
+ * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With error handling
+ * const eventBus = createInMemoryEventBus({
+ *   onHandlerError: (error, eventName, payload) => {
+ *     logger.error(`Event handler failed for ${eventName}`, { error, payload });
+ *   },
+ * });
+ * ```
+ */
+export function createInMemoryEventBus(options = {}) {
+    const onHandlerError = options?.onHandlerError;
+    const delivery = options.delivery ?? "await-handlers";
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "event-bus-memory",
+        watcher: "eventBus",
+    });
+    const handlers = new Map();
+    const reportHandlerError = (error, eventName, payload) => {
+        try {
+            onHandlerError?.(error, eventName, payload);
+        }
+        catch {
+            // Handler error callbacks should not make publish throw or create unhandled rejections.
+        }
+    };
+    return {
+        publish(event, payload) {
+            instrumentation.record({
+                type: "eventBus",
+                eventName: event.name,
+            });
+            const subs = handlers.get(event.name);
+            if (!subs || subs.size === 0)
+                return;
+            const subscribers = [...subs];
+            if (delivery === "fire-and-forget") {
+                for (const handler of subscribers) {
+                    try {
+                        const result = handler(payload);
+                        Promise.resolve(result).catch((error) => {
+                            reportHandlerError(error, event.name, payload);
+                        });
+                    }
+                    catch (error) {
+                        reportHandlerError(error, event.name, payload);
+                    }
+                }
+                return;
+            }
+            return (async () => {
+                for (const handler of subscribers) {
+                    try {
+                        await handler(payload);
+                    }
+                    catch (error) {
+                        reportHandlerError(error, event.name, payload);
+                        if (!onHandlerError)
+                            throw error;
+                    }
+                }
+            })();
+        },
+        subscribe(event, handler) {
+            let subs = handlers.get(event.name);
+            if (!subs) {
+                subs = new Set();
+                handlers.set(event.name, subs);
+            }
+            subs.add(handler);
+            return () => {
+                subs.delete(handler);
+                if (subs.size === 0) {
+                    handlers.delete(event.name);
+                }
+            };
+        },
+    };
+}
+export function createInMemoryEventBusProvider(options = {}) {
+    const { name = "event-bus-memory", ...eventBusOptions } = options;
+    return createProvider({
+        name,
+        setup({ ports }) {
+            return {
+                ports: {
+                    eventBus: createInMemoryEventBus({
+                        ...eventBusOptions,
+                        instrumentation: ports,
+                    }),
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@beignet/provider-event-bus-memory",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "In-memory event bus provider for Beignet - implements EventBusPort for single-process applications",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "event-bus",
+    "provider",
+    "in-memory",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-event-bus-memory"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,222 @@
+/**
+ * @beignet/provider-event-bus-memory
+ *
+ * In-memory event bus provider that implements EventBusPort.
+ * Suitable for single-process applications or testing.
+ *
+ * For distributed systems, consider implementing EventBusPort with
+ * a message broker like RabbitMQ, Kafka, or Redis Pub/Sub.
+ *
+ * @example
+ * ```ts
+ * import { createInMemoryEventBus } from "@beignet/provider-event-bus-memory";
+ *
+ * const eventBus = createInMemoryEventBus();
+ *
+ * // Subscribe to an event
+ * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+ *   console.log(`User registered: ${payload.email}`);
+ * });
+ *
+ * // Publish an event
+ * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
+ *
+ * // Unsubscribe when done
+ * unsubscribe();
+ * ```
+ */
+
+import type { EventBusPort } from "@beignet/core/ports";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+
+/**
+ * Options for the in-memory event bus.
+ */
+export type InMemoryEventBusDelivery = "await-handlers" | "fire-and-forget";
+
+export interface InMemoryEventBusOptions {
+  /**
+   * Optional instrumentation target. Providers pass existing app ports here
+   * automatically; direct factory users can pass an instrumentation port.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+
+  /**
+   * How publish calls deliver events to subscribed handlers.
+   *
+   * Defaults to "await-handlers" so local development and tests observe handler
+   * work deterministically. Use "fire-and-forget" for detached in-process
+   * delivery when the caller should not wait for listeners.
+   */
+  delivery?: InMemoryEventBusDelivery;
+
+  /**
+   * Called when an async event handler throws an error.
+   *
+   * In "await-handlers" mode, handler errors are rethrown when this callback is
+   * not provided. In "fire-and-forget" mode, handler errors are swallowed when
+   * this callback is not provided so detached handlers do not create unhandled
+   * rejections.
+   *
+   * @param error  The error thrown by the handler
+   * @param eventName  The name of the event being handled
+   * @param payload  The event payload that was passed to the handler
+   */
+  onHandlerError?: (
+    error: unknown,
+    eventName: string,
+    payload: unknown,
+  ) => void;
+}
+
+export interface InMemoryEventBusProviderOptions
+  extends Omit<InMemoryEventBusOptions, "instrumentation"> {
+  /**
+   * Provider name. Defaults to "event-bus-memory".
+   */
+  name?: string;
+}
+
+export interface InMemoryEventBusProviderPorts {
+  eventBus: EventBusPort;
+}
+
+/**
+ * Create an in-memory event bus implementation.
+ *
+ * This is suitable for single-process applications or testing.
+ * For distributed systems, you would implement EventBusPort with
+ * a message broker like RabbitMQ, Kafka, or Redis Pub/Sub.
+ *
+ * @example
+ * ```ts
+ * const eventBus = createInMemoryEventBus();
+ *
+ * eventBus.subscribe(UserRegistered, (payload) => {
+ *   console.log(`User registered: ${payload.email}`);
+ * });
+ *
+ * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With error handling
+ * const eventBus = createInMemoryEventBus({
+ *   onHandlerError: (error, eventName, payload) => {
+ *     logger.error(`Event handler failed for ${eventName}`, { error, payload });
+ *   },
+ * });
+ * ```
+ */
+export function createInMemoryEventBus(
+  options: InMemoryEventBusOptions = {},
+): EventBusPort {
+  const onHandlerError = options?.onHandlerError;
+  const delivery = options.delivery ?? "await-handlers";
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "event-bus-memory",
+      watcher: "eventBus",
+    },
+  );
+
+  const handlers = new Map<
+    string,
+    Set<(payload: unknown) => void | Promise<void>>
+  >();
+
+  const reportHandlerError = (
+    error: unknown,
+    eventName: string,
+    payload: unknown,
+  ) => {
+    try {
+      onHandlerError?.(error, eventName, payload);
+    } catch {
+      // Handler error callbacks should not make publish throw or create unhandled rejections.
+    }
+  };
+
+  return {
+    publish(event, payload) {
+      instrumentation.record({
+        type: "eventBus",
+        eventName: event.name,
+      });
+
+      const subs = handlers.get(event.name);
+      if (!subs || subs.size === 0) return;
+
+      const subscribers = [...subs];
+
+      if (delivery === "fire-and-forget") {
+        for (const handler of subscribers) {
+          try {
+            const result = handler(payload);
+            Promise.resolve(result).catch((error: unknown) => {
+              reportHandlerError(error, event.name, payload);
+            });
+          } catch (error) {
+            reportHandlerError(error, event.name, payload);
+          }
+        }
+
+        return;
+      }
+
+      return (async () => {
+        for (const handler of subscribers) {
+          try {
+            await handler(payload);
+          } catch (error) {
+            reportHandlerError(error, event.name, payload);
+            if (!onHandlerError) throw error;
+          }
+        }
+      })();
+    },
+
+    subscribe(event, handler) {
+      let subs = handlers.get(event.name);
+      if (!subs) {
+        subs = new Set();
+        handlers.set(event.name, subs);
+      }
+
+      subs.add(handler as (payload: unknown) => void | Promise<void>);
+
+      return () => {
+        subs.delete(handler as (payload: unknown) => void | Promise<void>);
+        if (subs.size === 0) {
+          handlers.delete(event.name);
+        }
+      };
+    },
+  };
+}
+
+export function createInMemoryEventBusProvider(
+  options: InMemoryEventBusProviderOptions = {},
+) {
+  const { name = "event-bus-memory", ...eventBusOptions } = options;
+
+  return createProvider({
+    name,
+    setup({ ports }) {
+      return {
+        ports: {
+          eventBus: createInMemoryEventBus({
+            ...eventBusOptions,
+            instrumentation: ports,
+          }),
+        } satisfies InMemoryEventBusProviderPorts,
+      };
+    },
+  });
+}