@relaybus/core 0.2.0 → 0.3.0

package/dist/internal/index.d.cts

@@ -0,0 +1,171 @@
+import { a as EventHeaders, E as EventEnvelope, C as Clock } from '../event-DCRTuYKI.cjs';
+
+/** 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;
+
+export { type BodyEnvelopeMapping, type BodyField, type CancelTimer, type CloudEventReaders, type FixedType, type HeaderField, type JsonEnvelopeFailures, type JsonEnvelopeFields, type JsonEnvelopeFormat, type JsonEnvelopeMapping, type JsonWireMessage, type PayloadOnlyMapping, type ScheduledTask, type WireField, assertPositiveInteger, createCloudEventReaders, createJsonEnvelopeFormat, fromHeader, fromPayloadField, isJsonObject, mediaTypeOf, schedule, sleep, writeStructuredCloudEvent };

package/dist/internal/index.d.ts

@@ -0,0 +1,171 @@
+import { a as EventHeaders, E as EventEnvelope, C as Clock } from '../event-DCRTuYKI.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;
+
+export { type BodyEnvelopeMapping, type BodyField, type CancelTimer, type CloudEventReaders, type FixedType, type HeaderField, type JsonEnvelopeFailures, type JsonEnvelopeFields, type JsonEnvelopeFormat, type JsonEnvelopeMapping, type JsonWireMessage, type PayloadOnlyMapping, type ScheduledTask, type WireField, assertPositiveInteger, createCloudEventReaders, createJsonEnvelopeFormat, fromHeader, fromPayloadField, isJsonObject, mediaTypeOf, schedule, sleep, writeStructuredCloudEvent };