diff --git a/src/message/http/index.ts b/src/message/http/index.ts index f162660..7852dce 100644 --- a/src/message/http/index.ts +++ b/src/message/http/index.ts @@ -12,7 +12,14 @@ import { import { isStringOrObjectOrThrow, ValidationError } from "../../event/validation"; import { JSONParser, MappedParser, Parser, parserByContentType } from "../../parsers"; -// implements Serializer +/** + * Serialize a CloudEvent for HTTP transport in binary mode + * @implements {Serializer} + * @see https://github.com/cloudevents/spec/blob/v1.0.1/http-protocol-binding.md#31-binary-content-mode + * + * @param {CloudEvent} event The event to serialize + * @returns {Message} a Message object with headers and body + */ export function binary(event: CloudEvent): Message { const contentType: Headers = { [CONSTANTS.HEADER_CONTENT_TYPE]: CONSTANTS.DEFAULT_CONTENT_TYPE }; const headers: Headers = { ...contentType, ...headersFor(event) }; @@ -27,7 +34,14 @@ export function binary(event: CloudEvent): Message { }; } -// implements Serializer +/** + * Serialize a CloudEvent for HTTP transport in structured mode + * @implements {Serializer} + * @see https://github.com/cloudevents/spec/blob/v1.0.1/http-protocol-binding.md#32-structured-content-mode + * + * @param {CloudEvent} event the CloudEvent to be serialized + * @returns {Message} a Message object with headers and body + */ export function structured(event: CloudEvent): Message { if (event.data_base64) { // The event's data is binary - delete it @@ -41,9 +55,15 @@ export function structured(event: CloudEvent): Message { }; } -// implements Detector -// TODO: this could probably be optimized +/** + * Determine if a Message is a CloudEvent + * @implements {Detector} + * + * @param {Message} message an incoming Message object + * @returns {boolean} true if this Message is a CloudEvent + */ export function isEvent(message: Message): boolean { + // TODO: this could probably be optimized try { deserialize(message); return true; @@ -54,6 +74,7 @@ export function isEvent(message: Message): boolean { /** * Converts a Message to a CloudEvent + * @implements {Deserializer} * * @param {Message} message the incoming message * @return {CloudEvent} A new {CloudEvent} instance diff --git a/src/message/index.ts b/src/message/index.ts index 2d05f48..67f0d8f 100644 --- a/src/message/index.ts +++ b/src/message/index.ts @@ -6,6 +6,12 @@ import { binary, deserialize, structured, isEvent } from "./http"; * Binding is an interface for transport protocols to implement, * which provides functions for sending CloudEvent Messages over * the wire. + * @interface + * + * @property {@link Serializer} `binary` - converts a CloudEvent into a Message in binary mode + * @property {@link Serializer} `structured` - converts a CloudEvent into a Message in structured mode + * @property {@link Deserializer} `toEvent` - converts a Message into a CloudEvent + * @property {@link Detector} `isEvent` - determines if a Message can be converted to a CloudEvent */ export interface Binding { binary: Serializer; @@ -17,6 +23,7 @@ export interface Binding { /** * Headers is an interface representing transport-agnostic headers as * key/value string pairs + * @interface */ export interface Headers extends IncomingHttpHeaders { [key: string]: string | string[] | undefined; @@ -25,6 +32,9 @@ export interface Headers extends IncomingHttpHeaders { /** * Message is an interface representing a CloudEvent as a * transport-agnostic message + * @interface + * @property {@linkcode Headers} `headers` - the headers for the event Message + * @property string `body` - the body of the event Message */ export interface Message { headers: Headers; @@ -33,6 +43,7 @@ export interface Message { /** * An enum representing the two transport modes, binary and structured + * @interface */ export enum Mode { BINARY = "binary", @@ -42,6 +53,7 @@ export enum Mode { /** * Serializer is an interface for functions that can convert a * CloudEvent into a Message. + * @interface */ export interface Serializer { (event: CloudEvent): Message; @@ -50,6 +62,7 @@ export interface Serializer { /** * Deserializer is a function interface that converts a * Message to a CloudEvent + * @interface */ export interface Deserializer { (message: Message): CloudEvent; @@ -58,12 +71,16 @@ export interface Deserializer { /** * Detector is a function interface that detects whether * a message contains a valid CloudEvent + * @interface */ export interface Detector { (message: Message): boolean; } -// HTTP Message capabilities +/** + * Bindings for HTTP transport support + * @implements {@linkcode Binding} + */ export const HTTP: Binding = { binary: binary as Serializer, structured: structured as Serializer, diff --git a/src/transport/emitter.ts b/src/transport/emitter.ts index 2dc132e..d75f477 100644 --- a/src/transport/emitter.ts +++ b/src/transport/emitter.ts @@ -5,15 +5,17 @@ import { EventEmitter } from "events"; /** * Options is an additional, optional dictionary of options that may * be passed to an EmitterFunction and TransportFunction + * @interface */ export interface Options { [key: string]: string | Record | unknown; } /** - * EmitterFunction is an invokable interface returned by the emitterFactory - * function. Invoke an EmitterFunction with a CloudEvent and optional transport + * EmitterFunction is an invokable interface returned by {@linkcode emitterFor}. + * Invoke an EmitterFunction with a CloudEvent and optional transport * options to send the event as a Message across supported transports. + * @interface */ export interface EmitterFunction { (event: CloudEvent, options?: Options): Promise; @@ -23,6 +25,7 @@ export interface EmitterFunction { * TransportFunction is an invokable interface provided to the emitterFactory. * A TransportFunction's responsiblity is to send a JSON encoded event Message * across the wire. + * @interface */ export interface TransportFunction { (message: Message, options?: Options): Promise; @@ -30,11 +33,12 @@ export interface TransportFunction { const emitterDefaults = { binding: HTTP, mode: Mode.BINARY }; /** - * emitterFactory creates and returns an EmitterFunction using the supplied - * TransportFunction. The returned EmitterFunction will invoke the Binding's - * `binary` or `structured` function to convert a CloudEvent into a JSON - * Message based on the Mode provided, and invoke the TransportFunction with - * the Message and any supplied options. + * Creates and returns an {@linkcode EmitterFunction} using the supplied + * {@linkcode TransportFunction}. The returned {@linkcode EmitterFunction} + * will invoke the {@linkcode Binding}'s `binary` or `structured` function + * to convert a {@linkcode CloudEvent} into a JSON + * {@linkcode Message} based on the {@linkcode Mode} provided, and invoke the + * TransportFunction with the Message and any supplied options. * * @param {TransportFunction} fn a TransportFunction that can accept an event Message * @param { {Binding, Mode} } options network binding and message serialization options @@ -62,7 +66,7 @@ export function emitterFor(fn: TransportFunction, options = emitterDefaults): Em } /** - * A static class to emit CloudEvents within an application + * A helper class to emit CloudEvents within an application */ export class Emitter { /** @@ -97,7 +101,7 @@ export class Emitter { * Emit an event inside this application * * @param {CloudEvent} event to emit - * @param {boolean} ensureDelivery fail the promise if one listener fail + * @param {boolean} ensureDelivery fail the promise if one listener fails * @return {void} */ static async emitEvent(event: CloudEvent, ensureDelivery = true): Promise {