@relaybus/core 0.2.0 → 0.3.1

package/dist/internal/index.d.ts

@@ -0,0 +1,438 @@
+import { b as EventHeaders, E as EventEnvelope, h as Clock, L as LeaseReference, d as ErrorInfo, j as ClaimRequest, C as ClaimedDelivery, T as Transport, U as TransportMessageHandler, V as TransportSubscriptionHooks, p as CloseOptions, D as Duration } from '../transport-BlfzIBZD.js';
+
+/** Returns `value` when it is an integer of at least 1, else throws a {@link ConfigurationError} naming the option. */
+declare function assertPositiveInteger(value: number, name: string): number;
+
+/**
+ * Reads one header of an incoming message, for the `type`, `id`, `key` or
+ * `source` option of {@link plainJsonDecoder}. Header names are compared
+ * exactly (Kafka and AMQP header names are case-sensitive). Returns undefined when the
+ * header is absent, so the decoder falls back to its default.
+ *
+ * ```ts
+ * plainJsonDecoder({ type: fromHeader('event-type'), id: fromHeader('message-id') })
+ * ```
+ */
+declare function fromHeader(name: string): (message: {
+    readonly headers: EventHeaders;
+}) => string | undefined;
+/**
+ * Reads a field of the JSON payload by a dotted path (`'meta.eventType'`), for
+ * the `type`, `id`, `key` or `source` option of {@link plainJsonDecoder}. A
+ * string is returned as is and a safe integer as its decimal text (numeric ids
+ * are common). Anything else returns undefined so the decoder falls back to its
+ * default: a missing field, and also a fraction or an integer beyond 2^53, which
+ * JSON parsing may already have rounded, so two different ids could collide.
+ *
+ * ```ts
+ * plainJsonDecoder({ type: fromPayloadField('eventType'), key: fromPayloadField('order.id') })
+ * ```
+ */
+declare function fromPayloadField(path: string): (message: {
+    readonly payload: unknown;
+}) => string | undefined;
+
+/** The media type of a content type, without parameters and lower-cased; undefined for anything but a string. */
+declare function mediaTypeOf(contentType: unknown): string | undefined;
+declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+/** Readers of structured CloudEvent attributes that fail with the error of the calling transport. */
+interface CloudEventReaders {
+    readonly optionalAttribute: (body: Record<string, unknown>, name: string) => string | undefined;
+    readonly requiredAttribute: (body: Record<string, unknown>, name: string) => string;
+    readonly assertValidType: (type: string, label: string) => void;
+    readonly assertJsonDataContentType: (dataContentType: string | undefined) => void;
+}
+declare function createCloudEventReaders(invalid: (reason: string) => Error): CloudEventReaders;
+/**
+ * The JSON text of a CloudEvents 1.0 structured-mode event: the attributes (the key as `subject`,
+ * correlation and causation ids as extension attributes), then `data`, the already serialized
+ * payload, so the payload is serialized only once.
+ */
+declare function writeStructuredCloudEvent(envelope: EventEnvelope, { time, data }: {
+    readonly time: string;
+    readonly data: string;
+}): string;
+
+/** A task for {@link schedule}: what runs, after how long, whether it repeats and keeps the process alive. */
+type ScheduledTask = Parameters<NonNullable<Clock['schedule']>>[0];
+/** Cancels a scheduled task; harmless once it ran or was cancelled. */
+type CancelTimer = () => void;
+/**
+ * The one place relaybus starts timers: through `clock.schedule` when the clock controls timers,
+ * else with the platform timers.
+ */
+declare function schedule(clock: Clock, task: ScheduledTask): CancelTimer;
+/** Resolves after `milliseconds` on the timers of `clock`. */
+declare function sleep(clock: Clock, milliseconds: number): Promise<void>;
+
+/**
+ * A field of the JSON body, by dotted path: `'eventName'`, `'meta.correlationId'`. A segment that
+ * is a whole number indexes an array: `'messageType.0'` is the first element of `messageType`.
+ */
+type BodyField = {
+    readonly body: string;
+};
+/** A message header (Kafka record header, AMQP message header), by exact name. */
+type HeaderField = {
+    readonly header: string;
+};
+/** Where one envelope value lives on the wire. */
+type WireField = BodyField | HeaderField;
+/** The one event type every message of the route carries: written nowhere, used for every message read. */
+type FixedType = {
+    readonly fixed: string;
+};
+type MappingFields<TField extends WireField, TTransportId extends string> = {
+    /** Where the event type lives, or the one type of the route. Required. */
+    readonly type: TField | FixedType;
+    /**
+     * Where the event id lives, or the transport's own message identity (see the transport's
+     * mapping type). Required, so the inbox dedup key is always a deliberate choice. A message
+     * whose mapped id is missing is malformed.
+     */
+    readonly id: TField | TTransportId;
+    /** Ordering key. Default: the transport's own (the Kafka record key; none on RabbitMQ). */
+    readonly key?: TField;
+    /** Producing service. Default: the transport's own (Kafka topic; RabbitMQ `appId`, else the routing key). */
+    readonly source?: TField;
+    /** RFC 3339 time. Default: the transport's own (Kafka record timestamp; RabbitMQ `timestamp`, seconds). */
+    readonly occurredAt?: TField;
+    readonly correlationId?: TField;
+    readonly causationId?: TField;
+    /** Media type written with the message. Default `application/json`. Not checked on read. */
+    readonly contentType?: string;
+};
+/**
+ * A JSON object that wraps the payload with event metadata, such as
+ * `{ "eventName": ..., "messageId": ..., "data": {...}, "meta": {...} }`.
+ * Each value lives at a body path or in a header.
+ */
+type BodyEnvelopeMapping<TTransportId extends string> = MappingFields<WireField, TTransportId> & {
+    /** Body path of the payload. Required. */
+    readonly payload: BodyField;
+    /**
+     * Event headers: a body path holding an object of strings, or `'message-headers'` (default),
+     * every message header that no other field maps.
+     */
+    readonly headers?: BodyField | 'message-headers';
+};
+/**
+ * The body is the payload itself, as a plain JSON producer writes it; every other value lives in
+ * a header, so body paths are a compile error here.
+ */
+type PayloadOnlyMapping<TTransportId extends string> = MappingFields<HeaderField, TTransportId> & {
+    readonly payload: 'whole-body';
+    /** Event headers: every message header that no other field maps. */
+    readonly headers?: 'message-headers';
+};
+/** Where every envelope value lives in a JSON message. `type`, `id` and `payload` are required. */
+type JsonEnvelopeMapping<TTransportId extends string> = BodyEnvelopeMapping<TTransportId> | PayloadOnlyMapping<TTransportId>;
+/** A JSON message: the parsed body and the text headers. */
+type JsonWireMessage = {
+    readonly body: unknown;
+    readonly headers: EventHeaders;
+};
+/** The values read from a message. An absent optional value is left to the transport's default. */
+type JsonEnvelopeFields = {
+    readonly id?: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly key?: string;
+    readonly source?: string;
+    readonly headers: EventHeaders;
+    readonly correlationId: string | null;
+    readonly causationId: string | null;
+    readonly occurredAt?: Date;
+};
+/** The errors of the calling transport. */
+type JsonEnvelopeFailures = {
+    /** For a message that cannot be read: it goes to the invalid-message path. */
+    readonly invalid: (reason: string) => Error;
+    /** For an event that cannot be written: never retried. */
+    readonly unencodable: (reason: string) => Error;
+};
+/** Writes and reads one mapping. Created once per codec; both methods are pure. */
+interface JsonEnvelopeFormat {
+    /** The mapped headers and the body; the id is left out when the transport supplies it. */
+    write(envelope: EventEnvelope): JsonWireMessage;
+    read(message: JsonWireMessage): JsonEnvelopeFields;
+}
+/**
+ * Compiles `mapping` once. `transportIds` lists the transport's own id strategies.
+ *
+ * @throws ConfigurationError for a mapping that is incomplete, names a header twice, nests one
+ * body path inside another or mixes array indexes and names under one body field.
+ */
+declare function createJsonEnvelopeFormat(mapping: JsonEnvelopeMapping<string>, { transportIds, failures, }: {
+    readonly transportIds: readonly string[];
+    readonly failures: JsonEnvelopeFailures;
+}): JsonEnvelopeFormat;
+
+/** What a ledger remembers of a claim: at least who it was handed to and which delivery. */
+interface HandedOutEntry {
+    readonly owner: string;
+    readonly deliveryId: string;
+}
+/**
+ * The claims a store instance handed out and has not seen settled, keyed by
+ * {@link DeliveryLeaseIdentity} (delivery id and exact lease token). After a failed claim the
+ * store keeps exactly these listed as running and gives the rest back.
+ */
+declare class HandedOutLedger<TEntry extends HandedOutEntry> {
+    #private;
+    register(lease: LeaseReference, entry: TEntry): void;
+    /** Whether the claim with this identity ({@link DeliveryLeaseIdentity.of}) is handed out. */
+    has(identity: string): boolean;
+    forget(lease: LeaseReference): void;
+    /** Forgets every entry `settled` says is settled. */
+    forgetWhere(settled: (entry: TEntry, identity: string) => boolean): void;
+    /** The entries handed out to `owner`. */
+    entriesOf(owner: string): TEntry[];
+}
+
+/** How a claim ends without completing: retried later, given back, or dead-lettered. */
+type SettlementChange = {
+    readonly kind: 'reschedule';
+    readonly availableAt: Date;
+    readonly error: ErrorInfo;
+    readonly now: Date;
+} | {
+    readonly kind: 'release';
+    readonly now: Date;
+} | {
+    readonly kind: 'bury';
+    readonly error: ErrorInfo;
+    readonly now: Date;
+};
+/** A change of the claim a lease names. */
+type LeaseChange = {
+    readonly lease: LeaseReference;
+    readonly change: SettlementChange;
+};
+/** A lease renewal; `now` for a store that records when it happened. */
+type LeaseExtension = {
+    readonly lease: LeaseReference;
+    readonly leaseExpiresAt: Date;
+    readonly now?: Date;
+};
+/**
+ * What a store answers about a lease: at once when it answers from memory, later when it asks a
+ * database. Answering at once keeps the in-memory store as fast (in microtasks) as it always was.
+ */
+type StoreAnswer = boolean | Promise<boolean>;
+/**
+ * The fenced settlement skeleton every event store shares: find the claim a lease names (a lease
+ * this store cannot have issued, or whose claim ended, is not held and changes nothing), apply the
+ * change fenced by the lease, then forget the lease as handed out once the store answered.
+ * A store supplies only how it finds a held claim, how it writes a change and a renewal, and its
+ * bookkeeping of handed-out leases.
+ */
+declare abstract class LeaseSettlement<THeld> {
+    #private;
+    /** Renews the lease when it is still held; false otherwise. */
+    extendLease(extension: LeaseExtension): StoreAnswer;
+    /**
+     * Applies `change` when the lease is still held. Once the store answered (either way) the lease
+     * is forgotten as handed out; when the write throws it stays registered, since the caller may
+     * retry with the same lease.
+     */
+    changeClaim(request: LeaseChange): StoreAnswer;
+    /** The claim `lease` names, when this store issued the lease; undefined otherwise. */
+    protected abstract findHeld(lease: LeaseReference): THeld | undefined;
+    protected abstract writeChange(held: THeld, request: LeaseChange): StoreAnswer;
+    protected abstract writeExtension(held: THeld, extension: LeaseExtension): StoreAnswer;
+    /** Drops `lease` from the store's handed-out bookkeeping; nothing for a store that keeps none. */
+    protected abstract forgetHandedOut(lease: LeaseReference): void;
+}
+
+/**
+ * The claim skeleton of the database stores: a request for no handlers or no deliveries claims
+ * nothing, and the claims of one owner run one after the other. Claims of one owner read the same
+ * held lanes and the same bookkeeping of what was handed out, so they must not overlap (the
+ * dispatcher claims one batch at a time anyway; `runOnce` next to a running dispatcher is what
+ * this guards against). A store supplies only {@link OwnerSerializedClaims.claimInTurn}.
+ */
+declare abstract class OwnerSerializedClaims {
+    #private;
+    claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
+    /** Whether the request cannot claim anything: no handlers, or a limit that is not above 0. */
+    protected claimsNothing(request: ClaimRequest): boolean;
+    /** Claims for `request` once the earlier claims of its owner settled. */
+    protected abstract claimInTurn(request: ClaimRequest): Promise<ClaimedDelivery[]>;
+}
+
+/** The event a transport's decoder extracted from a message; see the transport's `DecodedEvent`. */
+interface DecodedEventFields {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly source?: string;
+    readonly key?: string | null;
+    readonly headers?: EventHeaders;
+    readonly correlationId?: string | null;
+    readonly causationId?: string | null;
+    readonly occurredAt?: Date;
+}
+/** A fixed value, or an extractor that reads it from a plain message. */
+type TextOption<TPlain, TValue extends string | null> = TValue | ((message: TPlain) => TValue | undefined) | undefined;
+/**
+ * Observes the rejection of a promise an async decoder or extractor returned by
+ * mistake: the value is refused as malformed, and an unobserved rejection would
+ * otherwise crash the process.
+ */
+declare function observeRejection(value: unknown): void;
+/**
+ * The inbound plumbing a transport shares with every other: completing what a user decoder
+ * returned and reading the extractor options of a plain JSON decoder. A transport supplies only its
+ * malformed-message error and the defaults its messages carry (source, key, time).
+ */
+declare abstract class DecodedEventReader<TMessage, TPlain> {
+    /**
+     * Fills the fields a decoder left out and guards against a decoder that returned no object,
+     * which would otherwise surface as a retried `TypeError` instead of a malformed message.
+     */
+    complete(decoded: unknown, message: TMessage): EventEnvelope;
+    /** The text an option gives for `plain`; undefined when it gives none or `''`. */
+    text<TValue extends string | null>(option: TextOption<TPlain, TValue>, { plain, name }: {
+        readonly plain: TPlain;
+        readonly name: string;
+    }): string | undefined;
+    /** The error of a malformed message, which the transport dead-letters instead of retrying. */
+    abstract invalid(reason: string): Error;
+    protected abstract defaultSource(message: TMessage): string;
+    protected abstract defaultKey(message: TMessage): string | null;
+    protected abstract defaultTime(message: TMessage): Date;
+}
+
+/** One subscription of a transport: what it consumes and where the messages go. */
+interface TransportSubscription {
+    readonly destinations: readonly string[];
+    readonly onMessage: TransportMessageHandler;
+    readonly hooks: TransportSubscriptionHooks | undefined;
+}
+/**
+ * The skeleton of a broker transport that publishes and subscribes: the {@link Transport} port
+ * with its subscribe signature in one place. A transport supplies how it publishes, opens its one
+ * subscription, reports readiness and closes.
+ */
+declare abstract class SubscribingTransport implements Transport {
+    abstract readonly name: string;
+    abstract readonly system: string;
+    /**
+     * Subscribes to `destinations`. Not async itself: the subscription's own promise is returned
+     * as it is, so its checks reject rather than throw.
+     */
+    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler, hooks?: TransportSubscriptionHooks): Promise<void>;
+    abstract publish(envelope: EventEnvelope, destination: string): Promise<void>;
+    abstract isReady(): boolean;
+    abstract close(options?: CloseOptions): Promise<void>;
+    /** Opens the transport's one subscription; rejects when it cannot. */
+    protected abstract openSubscription(subscription: TransportSubscription): Promise<void>;
+}
+
+/**
+ * Two identifiers joined into one map or set key, such as an event id and a handler id, or a
+ * handler id and an ordering key. The NUL separator keeps `('a:b', 'c')` and `('a', 'b:c')` apart.
+ * Keys are plain strings, so they cost nothing more than the template literal they replace.
+ */
+declare abstract class CompositeKey {
+    static of(first: string, second: string): string;
+    /** The start every key of `first` shares, to find them all by prefix. */
+    static startOf(first: string): string;
+}
+
+/** The range a {@link BoundedInteger} option allows. */
+interface IntegerBounds {
+    readonly name: string;
+    readonly minimum: number;
+    readonly maximum: number;
+}
+/** An integer option with fixed lower and upper bounds. */
+declare abstract class BoundedInteger {
+    /** Returns `value` when it is an integer within the bounds, else throws a {@link ConfigurationError}. */
+    static of(value: number, { name, minimum, maximum }: IntegerBounds): number;
+}
+
+/**
+ * Identifies one claim of a delivery: the delivery id with the exact lease token it was handed out
+ * with. Two claims of the same delivery (an expired one and the current one) have different
+ * identities, so bookkeeping of the older can never replace or remove the newer one's.
+ */
+declare abstract class DeliveryLeaseIdentity {
+    static of(deliveryId: string, leaseToken: string): string;
+    /** The start of the identity of every claim of `deliveryId`. */
+    static prefixOf(deliveryId: string): string;
+}
+
+/**
+ * Delays that double with every attempt, from `initialMs` up to `maxMs`: the first retry waits
+ * `initialMs`, the second twice that, and so on. Without jitter, for in-process retries.
+ */
+declare class ExponentialBackoff {
+    readonly initialMs: number;
+    readonly maxMs: number;
+    constructor({ initialMs, maxMs }: {
+        readonly initialMs: number;
+        readonly maxMs: number;
+    });
+    /** The delay after failed attempt `attempt` (1-based). */
+    delayFor(attempt: number): number;
+}
+
+/** The claim a lane lease token names, as written in the token. */
+interface LaneLeaseTokenParts {
+    readonly lane: number;
+    /** The lane's epoch, as decimal text: PostgreSQL epochs exceed the safe integers. */
+    readonly epoch: string;
+    /** The claim generation of the delivery. */
+    readonly claims: number;
+}
+/** How many digits each part of a token may have, and how many lanes there are. */
+interface LaneLeaseTokenLimits {
+    readonly laneCount: number;
+    readonly epochDigits: number;
+    readonly claimsDigits: number;
+}
+/**
+ * The fencing token of a claim in a lane-leased store: `<lane>:<epoch>:<claims>`. Every state
+ * change checks the lane epoch and the delivery's claim generation it names. A store creates one
+ * format with its own digit limits and parses only the tokens it can have issued.
+ */
+declare class LaneLeaseTokenFormat {
+    #private;
+    constructor(limits: LaneLeaseTokenLimits);
+    format(lane: number, { epoch, claims }: {
+        readonly epoch: string | number;
+        readonly claims: number;
+    }): string;
+    /** The parts of `token`; undefined when the store cannot have issued it. */
+    parse(token: string): LaneLeaseTokenParts | undefined;
+}
+
+/**
+ * A configured length of time, converted once from a {@link Duration} option. Each factory names
+ * the option, so its refusal says which one was wrong.
+ */
+declare abstract class Milliseconds {
+    /** Zero or more milliseconds. */
+    static of(value: Duration, name: string): number;
+    /** More than zero milliseconds: a wait, a timeout or an age that must pass at all. */
+    static positive(value: Duration, name: string): number;
+    /** A duration that drives a timer: more than zero, and no longer than timers can represent. */
+    static forTimer(value: Duration, name: string): number;
+}
+
+/** A text option that must not be empty: a name, an exchange, a queue. */
+declare abstract class NonEmptyText {
+    static of(value: string, name: string): string;
+    /** Like {@link NonEmptyText.of}, for an option that may be left out. */
+    static optional(value: string | undefined, name: string): string | undefined;
+}
+
+/** A count option that must be a whole number of at least 1: a batch size, attempts, a limit. */
+declare abstract class PositiveInteger {
+    /** Returns `value` when it is an integer of at least 1, else throws a {@link ConfigurationError} naming the option. */
+    static of(value: number, name: string): number;
+}
+
+export { type BodyEnvelopeMapping, type BodyField, BoundedInteger, type CancelTimer, type CloudEventReaders, CompositeKey, type DecodedEventFields, DecodedEventReader, DeliveryLeaseIdentity, ExponentialBackoff, type FixedType, type HandedOutEntry, HandedOutLedger, type HeaderField, type IntegerBounds, type JsonEnvelopeFailures, type JsonEnvelopeFields, type JsonEnvelopeFormat, type JsonEnvelopeMapping, type JsonWireMessage, LaneLeaseTokenFormat, type LaneLeaseTokenLimits, type LaneLeaseTokenParts, type LeaseChange, type LeaseExtension, LeaseSettlement, Milliseconds, NonEmptyText, OwnerSerializedClaims, type PayloadOnlyMapping, PositiveInteger, type ScheduledTask, type SettlementChange, SubscribingTransport, type TextOption, type TransportSubscription, type WireField, assertPositiveInteger, createCloudEventReaders, createJsonEnvelopeFormat, fromHeader, fromPayloadField, isJsonObject, mediaTypeOf, observeRejection, schedule, sleep, writeStructuredCloudEvent };