@mqueue/queue/dist/index.d.ts

A simple queue interface with support for multiple backends

import * as crypto from 'crypto';
import { BinaryToTextEncoding } from 'node:crypto';

interface QueueAdapter {
    /** Queue provider/type identifier */
    type: string;
    /**
     * Healthcheck the connection.
     *
     * @since 1.0.0
     */
    healthcheck(): Promise<void>;
    /**
     * Close the connection.
     *
     * @since 1.0.0
     */
    close(): Promise<void>;
}

type JsonValue = null | boolean | number | string | JsonValue[] | {
    [key: string]: JsonValue;
};

type QueueMessageHeaders = Record<string, string | undefined>;
interface QueueMessageOptions {
    isRedelivered?: boolean;
    headers?: QueueMessageHeaders;
    body: Buffer;
}
type QueueMessageFromJSONOptions = Omit<QueueMessageOptions, "body">;
declare class QueueMessage {
    body: Buffer;
    headers: QueueMessageHeaders;
    isRedelivered?: boolean;
    constructor({ body, headers, isRedelivered }: QueueMessageOptions);
    /** Body Content as JSON */
    json<T = unknown>(): Promise<T>;
    /** Body Content as Text/String */
    text(): Promise<string>;
    static fromJSON(json: JsonValue, options: QueueMessageFromJSONOptions): QueueMessage;
}

type IncomingQueueMessageAdapterListenerInput = {
    /** Ack the received Queue Message */
    accept: () => Promise<void>;
    /** Nack/Reject the received Queue Message */
    reject: (error?: Error) => Promise<void>;
    transport: {
        /** Queue/Topic Name this payload was received on */
        name: string;
    };
    message: QueueMessageOptions;
    /** Additional non-standard fields */
    [key: string]: unknown;
};
type IncomingQueueMessageAdapterListener = (options: IncomingQueueMessageAdapterListenerInput) => Promise<void>;
interface IncomingQueueAdapter extends QueueAdapter {
    /**
     * Listen for messages.
     *
     * @since 1.0.0
     */
    consume(callback: IncomingQueueMessageAdapterListener): Promise<void>;
}

type Hook<T> = (input: T) => Promise<T> | T;
declare class HookSet<T> extends Set<Hook<T>> {
}

type IncomingQueueMessageListenerInput = {
    accept: () => Promise<void>;
    reject: (error?: Error) => Promise<void>;
    transport: {
        /** Queue/Topic Name this payload was received on */
        name: string;
    };
    message: QueueMessage;
    [key: string]: unknown;
};
type IncomingQueueMessageListener = (options: IncomingQueueMessageListenerInput) => Promise<void>;
interface IncomingQueueOptions {
    onReceipt?: Hook<IncomingQueueMessageListenerInput>[];
    onHealthcheck?: Hook<unknown>[];
    onBeforeClose?: Hook<unknown>[];
    onAfterClose?: Hook<unknown>[];
}
declare class IncomingQueue {
    adapter: IncomingQueueAdapter;
    on: {
        receipt: HookSet<IncomingQueueMessageListenerInput>;
        healthcheck: HookSet<unknown>;
        beforeClose: HookSet<unknown>;
        afterClose: HookSet<unknown>;
    };
    constructor(adapter: IncomingQueueAdapter, options?: IncomingQueueOptions);
    /** Check that MQueue is connected under-the-hood */
    isConnected(): Promise<boolean>;
    /** Assert that MQueue is connected under-the-hood */
    healthcheck(): Promise<void>;
    /** Close the queue connection */
    close(): Promise<void>;
    /** Listen and Consume queue messages */
    consume(callback?: IncomingQueueMessageListener): Promise<void>;
}

interface OutgoingQueueAdapter extends QueueAdapter {
    /**
     * Create a message.
     *
     * @since 1.0.0
     */
    sendMessage(message: QueueMessageOptions): Promise<void>;
}

interface OutgoingQueueOptions {
    onSend?: Hook<QueueMessage>[];
    onHealthcheck?: Hook<unknown>[];
    onBeforeClose?: Hook<unknown>[];
    onAfterClose?: Hook<unknown>[];
}
type SendMessageOptions = QueueMessage | ({
    /** Whether the message was redelivered */
    isRedelivered?: boolean;
    /** Message Headers */
    headers?: QueueMessageHeaders;
} & ({
    /** Body Content */
    body: Buffer;
} | {
    json: JsonValue;
}));
declare class OutgoingQueue {
    adapter: OutgoingQueueAdapter;
    on: {
        send: HookSet<QueueMessage>;
        healthcheck: HookSet<unknown>;
        beforeClose: HookSet<unknown>;
        afterClose: HookSet<unknown>;
    };
    constructor(adapter: OutgoingQueueAdapter, options?: OutgoingQueueOptions);
    /** Check that MQueue is connected under-the-hood */
    isConnected(): Promise<boolean>;
    /** Assert that MQueue is connected under-the-hood */
    healthcheck(): Promise<void>;
    /** Close the queue connection */
    close(): Promise<void>;
    /** Send a message to the queue */
    sendMessage(message: SendMessageOptions): Promise<void>;
}

/**
 * MQueue - A simple queue interface with support for multiple backends.
 * @see https://github.com/domwebber/mqueue
 */
declare class MQueue {
    private constructor();
    /** Initialise an Outgoing Queue to send messages */
    static Outgoing: typeof OutgoingQueue;
    /** Initialise an Incoming Queue to receive messages */
    static Incoming: typeof IncomingQueue;
}

interface SignatureHashHookOptions {
    header?: string;
    algorithm?: string;
    encoding?: BinaryToTextEncoding;
}
interface IncomingSignatureHashHookOptions extends SignatureHashHookOptions {
    throwOnMissing?: boolean;
    throwOnInvalid?: boolean;
}
/**
 * Enable Digital Signatures for Queue Messages via Hooks.
 *
 * ```ts
 * const outgoingQueue = new MQueue.Outgoing(
 *   outgoingQueueAdapter,
 *   { onSend: [SignatureHashHook.outgoing()] },
 * );
 *
 * // ...
 *
 * const incomingQueue = new MQueue.Incoming(
 *   incomingQueueAdapter,
 *   { onReceipt: [SignatureHashHook.incoming()] },
 * );
 * ```
 */
declare class SignatureHashHook {
    static DEFAULT_HEADER: "signature";
    static DEFAULT_ALGORITHM: "sha256";
    static DEFAULT_ENCODING: "base64";
    protected static _hash(content: Buffer, algorithm: string): crypto.Hash;
    /**
     * Enable Digital Signatures for Outgoing Queue Messages.
     *
     * ```ts
     * const outgoingQueue = new MQueue.Outgoing(
     *   outgoingQueueAdapter,
     *   { onSend: [SignatureHashHook.outgoing()] },
     * );
     * ```
     */
    static outgoing({ header, algorithm, encoding, }?: SignatureHashHookOptions): Hook<QueueMessage>;
    /**
     * Enable Digital Signatures for Incoming Queue Messages.
     *
     * ```ts
     * const incomingQueue = new MQueue.Incoming(
     *   incomingQueueAdapter,
     *   { onReceipt: [SignatureHashHook.incoming()] },
     * );
     * ```
     */
    static incoming({ header, algorithm, encoding, throwOnMissing, throwOnInvalid, }?: IncomingSignatureHashHookOptions): Hook<IncomingQueueMessageListenerInput>;
}

export { IncomingQueue, type IncomingQueueAdapter, type IncomingQueueMessageAdapterListener, type IncomingQueueMessageAdapterListenerInput, type IncomingQueueMessageListener, type IncomingQueueMessageListenerInput, type IncomingQueueOptions, type JsonValue, OutgoingQueue, type OutgoingQueueAdapter, type OutgoingQueueOptions, type QueueAdapter, QueueMessage, type QueueMessageFromJSONOptions, type QueueMessageHeaders, type QueueMessageOptions, type SendMessageOptions, SignatureHashHook, MQueue as default };