# `InMemoryEventsBusOptions`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

The options module is the single boundary at which user-supplied
configuration enters the in-memory events bus. It owns the Zod schema,
the default for `maxHistoryPerTopic`, and the
`resolveInMemoryEventsBusOptions` helper that turns a partial caller
input into a fully-resolved internal options object. Keeping resolution
out of the factory avoids re-checking defaults on every internal call
and keeps the public Zod-validation surface in one place.

## Features

- Strict schema (`.strict()`) — typos in the options object surface as
  `EVENTS_IN_MEMORY.INVALID_OPTIONS` rather than being silently
  dropped. This is the difference between "the cap I set was ignored"
  and "the cap key was misspelled" — the test author needs to know.
- Default `maxHistoryPerTopic = 1000` matches the design doc's
  "guard against runaway tests" guidance — high enough for realistic
  test suites, low enough that an accidental `while (true) publish(...)`
  fails loudly.
- Public Zod-failures are repackaged as `EventsInMemoryError`. Callers
  catch the package's own error type; `error.cause` still carries the
  raw `z.ZodError` for forensic logs.
- `ResolvedInMemoryEventsBusOptions` exposes a concrete (non-optional)
  shape downstream code can branch on without re-applying defaults.

## Usage: Basic

```ts
import { resolveInMemoryEventsBusOptions } from "@suaveplan/api-events-in-memory/options";

const resolved = resolveInMemoryEventsBusOptions(undefined);
console.log(resolved.maxHistoryPerTopic); // 1000
```

## Usage: Advanced

Combine a parsed JSON config blob with the schema directly when the
caller wants to surface validation issues at file-read time rather than
at bus-construction time:

```ts
import {
    inMemoryEventsBusOptionsSchema,
    resolveInMemoryEventsBusOptions,
} from "@suaveplan/api-events-in-memory/options";

const fromFile: unknown = JSON.parse(readFileSync("./bus.json", "utf8"));
const result = inMemoryEventsBusOptionsSchema.safeParse(fromFile);
if (!result.success) {
    throw new Error(`bus.json failed validation: ${result.error.message}`);
}
const resolved = resolveInMemoryEventsBusOptions(result.data);
```

`maxHistoryPerTopic` must be a positive integer; `0` and negatives are
rejected so callers can't accidentally disable history entirely.

## API Reference

- `DEFAULT_MAX_HISTORY_PER_TOPIC: 1000` — applied when callers omit the field.
- `InMemoryEventsBusOptions` — interface with `maxHistoryPerTopic?: number`.
- `inMemoryEventsBusOptionsSchema` — `z.ZodObject` with `.strict()`.
- `ResolvedInMemoryEventsBusOptions` — internal resolved shape (`maxHistoryPerTopic: number`).
- `resolveInMemoryEventsBusOptions(raw?)` — parses, applies defaults, raises `EventsInMemoryError(INVALID_OPTIONS)` on failure.

## Implementation Notes

The schema rejects extra keys with `.strict()` because the alternative
("permissive, ignore unknown") empirically masks typos for months
before anyone notices. The repackaging-to-`EventsInMemoryError` step is
the boundary at which the package commits to its own error namespace —
once a Zod error has crossed `resolveInMemoryEventsBusOptions`, no
caller should ever see a raw `z.ZodError` again.