@relaybus/testing 0.4.0 → 0.5.0

package/dist/codec-contract.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"codec-contract.cjs"}

package/dist/codec-contract.d.cts

@@ -0,0 +1,178 @@
+import { RelayBusError, EventEnvelope } from '@relaybus/core';
+
+/** How message bodies are compared: byte for byte, or as JSON regardless of key order and spacing. */
+type BodyComparison = 'bytes' | 'json';
+/** Bytes as text or bytes, as captured or encoded. */
+type WireBytes = string | Uint8Array;
+
+/** The two functions of a test framework the codec contract registers its tests with. */
+interface TestFramework {
+    readonly describe: (name: string, body: () => void) => void;
+    readonly it: (name: string, body: () => Promise<void>) => void;
+}
+/** Thrown by a codec contract assertion: one line per mismatch between the codec and the case. */
+declare class CodecContractError extends RelayBusError {
+    name: string;
+    readonly code: string;
+    readonly mismatches: readonly string[];
+    constructor(message: string, mismatches?: readonly string[]);
+}
+
+/** A record as captured from a topic: what an existing producer wrote. */
+interface KafkaCapturedRecord {
+    readonly topic: string;
+    /** Default 0. */
+    readonly partition?: number;
+    /** Default `'0'`. */
+    readonly offset?: string;
+    readonly key: WireBytes | null;
+    readonly value: WireBytes | null;
+    /** Default none. */
+    readonly headers?: Readonly<Record<string, WireBytes>>;
+    /** Epoch milliseconds in a string; compared only when the codec sets a timestamp. */
+    readonly timestamp?: string;
+}
+/** What a codec's `encode` returns: a `KafkaCodec` record. */
+interface KafkaWrittenRecord {
+    readonly key: WireBytes | null;
+    readonly value: WireBytes | null;
+    readonly headers: Readonly<Record<string, WireBytes | readonly WireBytes[]>>;
+    readonly timestamp?: string;
+}
+/** A record as a consumer hands it over: bytes for the key, the value and every header. */
+interface KafkaDeliveredRecord {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: string;
+    readonly key: Buffer | null;
+    readonly value: Buffer | null;
+    readonly headers: Readonly<Record<string, Buffer>>;
+    readonly timestamp?: string;
+}
+/** One message of the format: the event and the record that carries it. */
+interface KafkaCodecCase {
+    readonly name: string;
+    readonly envelope: EventEnvelope;
+    readonly record: KafkaCapturedRecord;
+    /**
+     * The event decoding the record gives, when the wire does not carry all of `envelope` (for
+     * example a record written without a key). Default `envelope`.
+     */
+    readonly decoded?: EventEnvelope;
+    /**
+     * Checks one direction only: `'decode'` for a message only other producers write (for
+     * example one without an id, which relaybus would add), `'encode'` for one only other
+     * consumers read. Default both.
+     */
+    readonly only?: 'encode' | 'decode';
+}
+interface KafkaCodecContractOptions {
+    /** Writes an event: a codec's `encode`, or a transport's publish captured by an injected producer. */
+    readonly encode: (envelope: EventEnvelope) => KafkaWrittenRecord | Promise<KafkaWrittenRecord>;
+    /** Reads a record the way the transport does: `(record) => decodeKafkaRecord(codec, record)`. */
+    readonly decode: (record: KafkaDeliveredRecord) => EventEnvelope | Promise<EventEnvelope>;
+    readonly cases: readonly KafkaCodecCase[];
+    /** How values are compared. Default `'bytes'`. */
+    readonly compare?: BodyComparison;
+    /** Headers left out of the comparison, such as ones relaybus adds and other consumers ignore. */
+    readonly ignoreHeaders?: readonly string[];
+}
+/**
+ * What differs between `testCase` and what the codec writes and reads, one line each: the key,
+ * the value, the headers (a repeated header by its last value) and the timestamp of
+ * `encode(envelope)`, and `decode(record)` against the expected event. Empty when they agree.
+ */
+declare function kafkaCodecMismatches(options: KafkaCodecContractOptions, testCase: KafkaCodecCase): Promise<string[]>;
+/**
+ * Throws a {@link CodecContractError} listing what {@link kafkaCodecMismatches} finds, so any test framework
+ * (or a plain script) can check one case.
+ */
+declare function assertKafkaCodecCase(options: KafkaCodecContractOptions, testCase: KafkaCodecCase): Promise<void>;
+/**
+ * Registers one test per case through `framework` (the `describe` and `it` of Jest, Vitest,
+ * Mocha or `node:test`), each asserting {@link assertKafkaCodecCase}: a format of existing
+ * producers and consumers is adopted only once relaybus writes and reads it exactly.
+ */
+declare function registerKafkaCodecContract(framework: TestFramework, { name, options }: {
+    readonly name: string;
+    readonly options: KafkaCodecContractOptions;
+}): void;
+
+/** A message as captured from a queue: what an existing publisher wrote. */
+interface RabbitMqCapturedMessage {
+    readonly routingKey: string;
+    /**
+     * The message properties as publish options name them (`persistent`, `messageId`,
+     * `contentType`, `timestamp`, ...), without `headers`. Default none.
+     */
+    readonly properties?: Readonly<Record<string, unknown>>;
+    /** Default none. */
+    readonly headers?: Readonly<Record<string, unknown>>;
+    readonly body: WireBytes;
+}
+/** What a codec's `encode` returns: a `RabbitMqCodec` message. */
+interface RabbitMqWrittenMessage {
+    readonly content: Uint8Array;
+    /** The publish options: properties, and the headers under `headers`. */
+    readonly options: object;
+}
+/** A message as a consumer receives it. */
+interface RabbitMqDeliveredMessage {
+    readonly content: Buffer;
+    readonly fields: {
+        readonly routingKey: string;
+    };
+    readonly properties: Readonly<Record<string, unknown>> & {
+        readonly headers: Readonly<Record<string, unknown>>;
+    };
+}
+/** One message of the format: the event and the message that carries it. */
+interface RabbitMqCodecCase {
+    readonly name: string;
+    readonly envelope: EventEnvelope;
+    readonly message: RabbitMqCapturedMessage;
+    /** The event decoding the message gives, when the wire does not carry all of `envelope`. */
+    readonly decoded?: EventEnvelope;
+    /**
+     * Checks one direction only: `'decode'` for a message only other producers write (for
+     * example one without an id, which relaybus would add), `'encode'` for one only other
+     * consumers read. Default both.
+     */
+    readonly only?: 'encode' | 'decode';
+}
+interface RabbitMqCodecContractOptions {
+    /** Writes an event: a codec's `encode`. The routing key is the route's destination, not the codec's. */
+    readonly encode: (envelope: EventEnvelope) => RabbitMqWrittenMessage | Promise<RabbitMqWrittenMessage>;
+    /** Reads a message the way the transport does: `(message) => decodeRabbitMqMessage(codec, message)`. */
+    readonly decode: (message: RabbitMqDeliveredMessage) => EventEnvelope | Promise<EventEnvelope>;
+    readonly cases: readonly RabbitMqCodecCase[];
+    /** How bodies are compared. Default `'bytes'`. */
+    readonly compare?: BodyComparison;
+    /** Properties left out of the comparison, such as a `timestamp` that differs per send. */
+    readonly ignoreProperties?: readonly string[];
+    /** Headers left out of the comparison. */
+    readonly ignoreHeaders?: readonly string[];
+}
+/**
+ * What differs between `testCase` and what the codec writes and reads, one line each: the
+ * properties, headers and body of `encode(envelope)`, and `decode(message)` against the expected
+ * event. Empty when they agree.
+ */
+declare function rabbitMqCodecMismatches(options: RabbitMqCodecContractOptions, testCase: RabbitMqCodecCase): Promise<string[]>;
+/**
+ * Throws a {@link CodecContractError} listing what {@link rabbitMqCodecMismatches} finds, so any test framework
+ * (or a plain script) can check one case.
+ */
+declare function assertRabbitMqCodecCase(options: RabbitMqCodecContractOptions, testCase: RabbitMqCodecCase): Promise<void>;
+/**
+ * Registers one test per case through `framework` (the `describe` and `it` of Jest, Vitest,
+ * Mocha or `node:test`), each asserting {@link assertRabbitMqCodecCase}: a format of existing
+ * producers and consumers is adopted only once relaybus writes and reads it exactly.
+ */
+declare function registerRabbitMqCodecContract(framework: TestFramework, { name, options }: {
+    readonly name: string;
+    readonly options: RabbitMqCodecContractOptions;
+}): void;
+
+export { CodecContractError, assertKafkaCodecCase, assertRabbitMqCodecCase, kafkaCodecMismatches, rabbitMqCodecMismatches, registerKafkaCodecContract, registerRabbitMqCodecContract };
+export type { BodyComparison, KafkaCapturedRecord, KafkaCodecCase, KafkaCodecContractOptions, KafkaDeliveredRecord, KafkaWrittenRecord, RabbitMqCapturedMessage, RabbitMqCodecCase, RabbitMqCodecContractOptions, RabbitMqDeliveredMessage, RabbitMqWrittenMessage, TestFramework, WireBytes };

package/dist/codec-contract.d.ts

@@ -0,0 +1,178 @@
+import { RelayBusError, EventEnvelope } from '@relaybus/core';
+
+/** How message bodies are compared: byte for byte, or as JSON regardless of key order and spacing. */
+type BodyComparison = 'bytes' | 'json';
+/** Bytes as text or bytes, as captured or encoded. */
+type WireBytes = string | Uint8Array;
+
+/** The two functions of a test framework the codec contract registers its tests with. */
+interface TestFramework {
+    readonly describe: (name: string, body: () => void) => void;
+    readonly it: (name: string, body: () => Promise<void>) => void;
+}
+/** Thrown by a codec contract assertion: one line per mismatch between the codec and the case. */
+declare class CodecContractError extends RelayBusError {
+    name: string;
+    readonly code: string;
+    readonly mismatches: readonly string[];
+    constructor(message: string, mismatches?: readonly string[]);
+}
+
+/** A record as captured from a topic: what an existing producer wrote. */
+interface KafkaCapturedRecord {
+    readonly topic: string;
+    /** Default 0. */
+    readonly partition?: number;
+    /** Default `'0'`. */
+    readonly offset?: string;
+    readonly key: WireBytes | null;
+    readonly value: WireBytes | null;
+    /** Default none. */
+    readonly headers?: Readonly<Record<string, WireBytes>>;
+    /** Epoch milliseconds in a string; compared only when the codec sets a timestamp. */
+    readonly timestamp?: string;
+}
+/** What a codec's `encode` returns: a `KafkaCodec` record. */
+interface KafkaWrittenRecord {
+    readonly key: WireBytes | null;
+    readonly value: WireBytes | null;
+    readonly headers: Readonly<Record<string, WireBytes | readonly WireBytes[]>>;
+    readonly timestamp?: string;
+}
+/** A record as a consumer hands it over: bytes for the key, the value and every header. */
+interface KafkaDeliveredRecord {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: string;
+    readonly key: Buffer | null;
+    readonly value: Buffer | null;
+    readonly headers: Readonly<Record<string, Buffer>>;
+    readonly timestamp?: string;
+}
+/** One message of the format: the event and the record that carries it. */
+interface KafkaCodecCase {
+    readonly name: string;
+    readonly envelope: EventEnvelope;
+    readonly record: KafkaCapturedRecord;
+    /**
+     * The event decoding the record gives, when the wire does not carry all of `envelope` (for
+     * example a record written without a key). Default `envelope`.
+     */
+    readonly decoded?: EventEnvelope;
+    /**
+     * Checks one direction only: `'decode'` for a message only other producers write (for
+     * example one without an id, which relaybus would add), `'encode'` for one only other
+     * consumers read. Default both.
+     */
+    readonly only?: 'encode' | 'decode';
+}
+interface KafkaCodecContractOptions {
+    /** Writes an event: a codec's `encode`, or a transport's publish captured by an injected producer. */
+    readonly encode: (envelope: EventEnvelope) => KafkaWrittenRecord | Promise<KafkaWrittenRecord>;
+    /** Reads a record the way the transport does: `(record) => decodeKafkaRecord(codec, record)`. */
+    readonly decode: (record: KafkaDeliveredRecord) => EventEnvelope | Promise<EventEnvelope>;
+    readonly cases: readonly KafkaCodecCase[];
+    /** How values are compared. Default `'bytes'`. */
+    readonly compare?: BodyComparison;
+    /** Headers left out of the comparison, such as ones relaybus adds and other consumers ignore. */
+    readonly ignoreHeaders?: readonly string[];
+}
+/**
+ * What differs between `testCase` and what the codec writes and reads, one line each: the key,
+ * the value, the headers (a repeated header by its last value) and the timestamp of
+ * `encode(envelope)`, and `decode(record)` against the expected event. Empty when they agree.
+ */
+declare function kafkaCodecMismatches(options: KafkaCodecContractOptions, testCase: KafkaCodecCase): Promise<string[]>;
+/**
+ * Throws a {@link CodecContractError} listing what {@link kafkaCodecMismatches} finds, so any test framework
+ * (or a plain script) can check one case.
+ */
+declare function assertKafkaCodecCase(options: KafkaCodecContractOptions, testCase: KafkaCodecCase): Promise<void>;
+/**
+ * Registers one test per case through `framework` (the `describe` and `it` of Jest, Vitest,
+ * Mocha or `node:test`), each asserting {@link assertKafkaCodecCase}: a format of existing
+ * producers and consumers is adopted only once relaybus writes and reads it exactly.
+ */
+declare function registerKafkaCodecContract(framework: TestFramework, { name, options }: {
+    readonly name: string;
+    readonly options: KafkaCodecContractOptions;
+}): void;
+
+/** A message as captured from a queue: what an existing publisher wrote. */
+interface RabbitMqCapturedMessage {
+    readonly routingKey: string;
+    /**
+     * The message properties as publish options name them (`persistent`, `messageId`,
+     * `contentType`, `timestamp`, ...), without `headers`. Default none.
+     */
+    readonly properties?: Readonly<Record<string, unknown>>;
+    /** Default none. */
+    readonly headers?: Readonly<Record<string, unknown>>;
+    readonly body: WireBytes;
+}
+/** What a codec's `encode` returns: a `RabbitMqCodec` message. */
+interface RabbitMqWrittenMessage {
+    readonly content: Uint8Array;
+    /** The publish options: properties, and the headers under `headers`. */
+    readonly options: object;
+}
+/** A message as a consumer receives it. */
+interface RabbitMqDeliveredMessage {
+    readonly content: Buffer;
+    readonly fields: {
+        readonly routingKey: string;
+    };
+    readonly properties: Readonly<Record<string, unknown>> & {
+        readonly headers: Readonly<Record<string, unknown>>;
+    };
+}
+/** One message of the format: the event and the message that carries it. */
+interface RabbitMqCodecCase {
+    readonly name: string;
+    readonly envelope: EventEnvelope;
+    readonly message: RabbitMqCapturedMessage;
+    /** The event decoding the message gives, when the wire does not carry all of `envelope`. */
+    readonly decoded?: EventEnvelope;
+    /**
+     * Checks one direction only: `'decode'` for a message only other producers write (for
+     * example one without an id, which relaybus would add), `'encode'` for one only other
+     * consumers read. Default both.
+     */
+    readonly only?: 'encode' | 'decode';
+}
+interface RabbitMqCodecContractOptions {
+    /** Writes an event: a codec's `encode`. The routing key is the route's destination, not the codec's. */
+    readonly encode: (envelope: EventEnvelope) => RabbitMqWrittenMessage | Promise<RabbitMqWrittenMessage>;
+    /** Reads a message the way the transport does: `(message) => decodeRabbitMqMessage(codec, message)`. */
+    readonly decode: (message: RabbitMqDeliveredMessage) => EventEnvelope | Promise<EventEnvelope>;
+    readonly cases: readonly RabbitMqCodecCase[];
+    /** How bodies are compared. Default `'bytes'`. */
+    readonly compare?: BodyComparison;
+    /** Properties left out of the comparison, such as a `timestamp` that differs per send. */
+    readonly ignoreProperties?: readonly string[];
+    /** Headers left out of the comparison. */
+    readonly ignoreHeaders?: readonly string[];
+}
+/**
+ * What differs between `testCase` and what the codec writes and reads, one line each: the
+ * properties, headers and body of `encode(envelope)`, and `decode(message)` against the expected
+ * event. Empty when they agree.
+ */
+declare function rabbitMqCodecMismatches(options: RabbitMqCodecContractOptions, testCase: RabbitMqCodecCase): Promise<string[]>;
+/**
+ * Throws a {@link CodecContractError} listing what {@link rabbitMqCodecMismatches} finds, so any test framework
+ * (or a plain script) can check one case.
+ */
+declare function assertRabbitMqCodecCase(options: RabbitMqCodecContractOptions, testCase: RabbitMqCodecCase): Promise<void>;
+/**
+ * Registers one test per case through `framework` (the `describe` and `it` of Jest, Vitest,
+ * Mocha or `node:test`), each asserting {@link assertRabbitMqCodecCase}: a format of existing
+ * producers and consumers is adopted only once relaybus writes and reads it exactly.
+ */
+declare function registerRabbitMqCodecContract(framework: TestFramework, { name, options }: {
+    readonly name: string;
+    readonly options: RabbitMqCodecContractOptions;
+}): void;
+
+export { CodecContractError, assertKafkaCodecCase, assertRabbitMqCodecCase, kafkaCodecMismatches, rabbitMqCodecMismatches, registerKafkaCodecContract, registerRabbitMqCodecContract };
+export type { BodyComparison, KafkaCapturedRecord, KafkaCodecCase, KafkaCodecContractOptions, KafkaDeliveredRecord, KafkaWrittenRecord, RabbitMqCapturedMessage, RabbitMqCodecCase, RabbitMqCodecContractOptions, RabbitMqDeliveredMessage, RabbitMqWrittenMessage, TestFramework, WireBytes };

package/dist/codec-contract.js

@@ -0,0 +1,3 @@
+export { CodecContractError, assertKafkaCodecCase, assertRabbitMqCodecCase, kafkaCodecMismatches, rabbitMqCodecMismatches, registerKafkaCodecContract, registerRabbitMqCodecContract } from './chunk-ZZZXYZJ3.js';
+//# sourceMappingURL=codec-contract.js.map
+//# sourceMappingURL=codec-contract.js.map

package/dist/codec-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"codec-contract.js"}