skills/docs/api-stack/api/api-plugin-event-bus/src/schemas/options.md

options.ts — Zod schema for EventBusPluginOptions

Purpose

Boundary Zod schema validated by createEventBusPlugin(options) at the factory entry point. Invalid input produces an EventBusError(EVENT_BUS.INVALID_INPUT) carrying the underlying ZodError as cause — callers always see a typed failure, never an unknown parse error from upstream code paths. Schema is .strict() so unknown keys fail loudly (typos in option names surface immediately rather than producing silent no-ops).

Features

• Single schema (EventBusPluginOptionsSchema) covering the full option surface with sane defaults applied.
• Sub-schemas exported for downstream reuse: BackpressureOptionsSchema, IdempotencyOptionsSchema.
• Schema produces a fully-resolved EventBusPluginOptionsResolved type (defaults applied) suitable for passing as PluginDescriptor.defaults.
• Strict mode prevents typo classes like applySchema: true (the wrong package's option) from silently being ignored.

Usage: Basic

import { EventBusPluginOptionsSchema } from "@suaveplan/api-plugin-event-bus/schemas/options";

const resolved = EventBusPluginOptionsSchema.parse({});
console.log(resolved.routePrefix); // "/event-bus"
console.log(resolved.backpressure.policy); // "drop-oldest"

Usage: Advanced

import {
    EventBusPluginOptionsSchema,
    type EventBusPluginOptionsInput,
} from "@suaveplan/api-plugin-event-bus/schemas/options";

const input: EventBusPluginOptionsInput = {
    backpressure: { capacity: 32, policy: "throw" },
    idempotency: { enabled: true, cacheCapacity: 8192 },
    routePrefix: "/bus",
    mountRoutes: false,
    requireAuthForRoutes: false,
    tenantIsolation: false,
    interceptors: [
        async (env, next) => {
            console.log("emit", env.type);
            return next();
        },
    ],
};

const resolved = EventBusPluginOptionsSchema.parse(input);

API Reference

EventBusPluginOptionsSchema

Strict object schema producing EventBusPluginOptionsResolved. Fields:

• interceptors: Interceptor[] (default []).
• backpressure: { capacity: number; policy: QueuePolicy }.
• idempotency: { enabled: boolean; cacheCapacity: number }.
• routePrefix: string (default "/event-bus").
• mountRoutes: boolean (default true).
• requireAuthForRoutes: boolean (default true).
• tenantIsolation: boolean (default true).
• maxTopicLength: number (default 256).
• logger?: LoggerLike (optional override).

BackpressureOptionsSchema

Stand-alone sub-schema. Exported so consumers building custom plugin factories can reuse the same shape.

IdempotencyOptionsSchema

Stand-alone sub-schema.

type EventBusPluginOptionsInput

z.input of the top-level schema — what callers pass in.

type EventBusPluginOptionsResolved

z.output of the top-level schema — what the descriptor stores as defaults after parsing.

Implementation Notes

• The interceptors array uses z.custom (typeof val === "function") rather than z.function(...) because Zod 4's z.function is builder-style and does not return a ZodType directly compatible with z.array.
• The routePrefix regex matches /auth's rule verbatim — start with /, no trailing / (the literal root / is allowed). Sharing the rule across the plugin family means routes mount predictably.
• The schema is .strict() because the cost of catching typos at the factory boundary far outweighs the convenience of forward-compatible passthrough.