first commit

docs/api-stack/api/api-ws-broker-in-memory/src/options/options.md

@@ -0,0 +1,74 @@
+# `options` — `createInMemoryWsBroker` option surface
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module owns the Zod-validated option shape consumed by
+`createInMemoryWsBroker`. Keeping it in a dedicated feature folder lets
+the constructor stay focused on lifecycle wiring and lets the option
+defaulting logic be tested in isolation without standing up a broker
+instance.
+
+The option set is deliberately small: an in-memory broker has no
+network knobs, no retry tuning, and no persistence story. The two
+levers that matter — delivery semantics and a defensive subscriber cap
+— are exposed here.
+
+## Features
+
+- `InMemoryWsBrokerOptions` — the public, all-optional input shape.
+- `InMemoryWsBrokerDeliveryMode` — `"fire-and-forget"` (default) or
+  `"await-all"`.
+- `inMemoryWsBrokerOptionsSchema` — strict Zod schema; unknown keys
+  are rejected so option typos fail at the constructor boundary.
+- `resolveInMemoryWsBrokerOptions(opts)` — applies defaults and yields
+  the `ResolvedInMemoryWsBrokerOptions` shape used internally.
+- `ResolvedInMemoryWsBrokerOptions` — every field required.
+
+## Usage: Basic
+
+```ts
+import { inMemoryWsBrokerOptionsSchema } from "@suaveplan/api-ws-broker-in-memory/options";
+
+const parsed = inMemoryWsBrokerOptionsSchema.parse({
+    deliveryMode: "await-all",
+});
+// parsed.deliveryMode === "await-all"
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    inMemoryWsBrokerOptionsSchema,
+    resolveInMemoryWsBrokerOptions,
+} from "@suaveplan/api-ws-broker-in-memory/options";
+
+const raw = { deliveryMode: "await-all" as const };
+const safe = inMemoryWsBrokerOptionsSchema.parse(raw);
+const resolved = resolveInMemoryWsBrokerOptions(safe);
+// resolved === { deliveryMode: "await-all" }
+```
+
+## API Reference
+
+- `interface InMemoryWsBrokerOptions { deliveryMode?; }`
+- `type InMemoryWsBrokerDeliveryMode = "fire-and-forget" | "await-all"`
+- `inMemoryWsBrokerOptionsSchema: z.ZodType<InMemoryWsBrokerOptions>`
+- `function resolveInMemoryWsBrokerOptions(opts): ResolvedInMemoryWsBrokerOptions`
+- `interface ResolvedInMemoryWsBrokerOptions { deliveryMode; }`
+
+## Implementation Notes
+
+- The schema is `.strict()` because typos in option keys are a common
+  ops failure mode and silently ignoring them is worse than throwing.
+- The split between public `Options` (all optional) and internal
+  `ResolvedOptions` (all required) lets the broker implementation skip
+  per-call defaulting work and keeps every field statically narrowed
+  inside the hot path.
+- Future broker tuning knobs (e.g. publish concurrency, slow-handler
+  detection thresholds) should land here as additional optional
+  fields, never as global module state.