`options/`

(no submodules)

Purpose

Defines the boundary-validated option shape consumed by createTwoPcCoordinator. Every tunable that affects coordinator behaviour (host instance id, outstanding-prepared cap, default phase-1 timeout) lives here, with Zod validation at the seam and explicit defaults pinned to the design doc §9.2 numbers.

Centralising option resolution in one module keeps the coordinator free of conditional fallback logic — by the time it sees the resolved shape every field is concrete, so subsequent code never has to re-check undefined.

Features

DEFAULT_TIMEOUT_MS = 5000 — phase-1 deadline default per design doc §9.2.
TIMEOUT_CEILING_MS = 30000 — hard ceiling enforced at call time (the coordinator's limits/timeout-ceiling module imports this).
DEFAULT_OUTSTANDING_PREPARED_CAP = 256 — admission-control default per design doc §14.
twoPcCoordinatorOptionsSchema — Zod schema, strict() so typos surface as Zod errors instead of being silently ignored.
resolveTwoPcCoordinatorOptions(raw) — validates and fills in defaults; returns the fully-populated ResolvedTwoPcCoordinatorOptions shape the coordinator consumes.

Usage: Basic

import {
    DEFAULT_TIMEOUT_MS,
    resolveTwoPcCoordinatorOptions,
} from "@suaveplan/api-2pc/options";

const resolved = resolveTwoPcCoordinatorOptions({
    hostInstanceId: "host-01",
});

console.log(resolved.defaultTimeoutMs === DEFAULT_TIMEOUT_MS); // true

Usage: Advanced

Override every default — useful for canary hosts where operators want a tighter admission cap and a longer prepare window:

import { resolveTwoPcCoordinatorOptions } from "@suaveplan/api-2pc/options";

const resolved = resolveTwoPcCoordinatorOptions({
    hostInstanceId: "canary-eu-west-1",
    outstandingPreparedCap: 64,
    defaultTimeoutMs: 15_000,
});

Calls supplying defaultTimeoutMs above TIMEOUT_CEILING_MS raise a Zod error at this boundary — the coordinator's runtime ceiling check in limits/timeout-ceiling.ts then surfaces the misuse on per-call overrides as well.

API Reference

const DEFAULT_TIMEOUT_MS: number — 5000.
const TIMEOUT_CEILING_MS: number — 30000.
const DEFAULT_OUTSTANDING_PREPARED_CAP: number — 256.
interface TwoPcCoordinatorOptions — caller-supplied input shape.
interface ResolvedTwoPcCoordinatorOptions — internal shape after defaults.
const twoPcCoordinatorOptionsSchema: z.ZodType — strict-shape Zod schema.
function resolveTwoPcCoordinatorOptions(raw): ResolvedTwoPcCoordinatorOptions — validates and resolves defaults.

Implementation Notes

The schema uses .strict() so unknown keys fail validation rather than silently being dropped. The default for defaultTimeoutMs is applied post-parse with ?? DEFAULT_TIMEOUT_MS rather than via z.default(...) so the schema continues to reject above-ceiling values regardless of whether the caller supplied the field — Zod's default would short-circuit .max() checks when the field is omitted, which is the wrong shape for a ceiling-enforced option.

The module deliberately does NOT re-throw Zod failures as TwoPcError — that's the responsibility of the coordinator's public entry points. Keeping this module pure of cross-package error mapping makes it reusable from tests that want a raw Zod surface for property-based shape testing.

3.4 KiB Raw Blame History

options/