Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,75 @@
|
||||
# `options` — constructor option schema and defaults
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
This module owns the Zod schema and defaults for the scalar slice of
|
||||
`createStdoutAuditSink({...})`'s input. Validation happens at the
|
||||
boundary — a typo on `maxQueueMs` raises
|
||||
`AUDIT_STDOUT.INVALID_OPTIONS` rather than silently being ignored.
|
||||
The schema is `.strict()` so unknown keys are rejected (same rationale
|
||||
as the `AuditRecord` schema).
|
||||
|
||||
The non-scalar slots — writer, clock, timers, logger, instruments,
|
||||
hmacKey — bypass Zod and are checked structurally by the sink itself
|
||||
at construction. Mixing the two validation styles keeps the typed
|
||||
surface narrow while still rejecting obvious typos.
|
||||
|
||||
## Features
|
||||
|
||||
- Strict Zod schema for scalar option keys.
|
||||
- Defaults: `maxQueueMs = 100`, `warnThrottleMs = 60_000`,
|
||||
`sinkLabel = "stdout"`.
|
||||
- Resolver wraps any `ZodError` as `AUDIT_STDOUT.INVALID_OPTIONS`.
|
||||
- Constants exported so callers can reference them when computing
|
||||
test throughput budgets.
|
||||
|
||||
## Usage: Basic
|
||||
|
||||
```ts
|
||||
import { resolveStdoutAuditScalarOptions } from "@suaveplan/api-audit-stdout/options";
|
||||
|
||||
const resolved = resolveStdoutAuditScalarOptions({ maxQueueMs: 250 });
|
||||
// resolved.warnThrottleMs === 60_000 (default)
|
||||
```
|
||||
|
||||
## Usage: Advanced
|
||||
|
||||
```ts
|
||||
import {
|
||||
DEFAULT_MAX_QUEUE_MS,
|
||||
resolveStdoutAuditScalarOptions,
|
||||
type StdoutAuditScalarOptions,
|
||||
} from "@suaveplan/api-audit-stdout/options";
|
||||
|
||||
function tightenedForTests(): StdoutAuditScalarOptions {
|
||||
return {
|
||||
maxQueueMs: Math.max(1, DEFAULT_MAX_QUEUE_MS / 10),
|
||||
warnThrottleMs: 1_000,
|
||||
};
|
||||
}
|
||||
|
||||
const resolved = resolveStdoutAuditScalarOptions(tightenedForTests());
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `stdoutAuditScalarOptionsSchema` — strict Zod object.
|
||||
- `StdoutAuditScalarOptions` — inferred type.
|
||||
- `ResolvedStdoutAuditScalarOptions` — defaults-applied shape.
|
||||
- `resolveStdoutAuditScalarOptions(raw)` — boundary parser.
|
||||
- `DEFAULT_MAX_QUEUE_MS`, `DEFAULT_WARN_THROTTLE_MS` — constants.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
`maxQueueMs` is bounded to positive integers because a value of 0
|
||||
would mean "never queue" — that's a different semantics (synchronous
|
||||
backpressure) and would need its own option. `warnThrottleMs`
|
||||
governs the once-per-window log; tests use a `FakeClock` plus a
|
||||
short throttle to exercise the throttle without sleeping. The
|
||||
`sinkLabel` exists so a future spinoff (e.g. journald) can reuse
|
||||
this module while still attaching a distinct `sink="…"` label to its
|
||||
counters.
|
||||
Reference in New Issue
Block a user