Initial Commit

packages/api-stack/api/api-events-in-memory/src/options/options.md

@@ -0,0 +1,80 @@
+# `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.