@stolbivi/pirojok/lib/chrome/Messages.d.ts

Some minimalistic library used to build chrome extensions, covers some popular Chrome Extension API

/**
 * Type definitions and utilities for Chrome extension messaging system.
 * Provides a type-safe way to handle request-response style communication between different parts of a Chrome extension.
 */
/// <reference types="chrome" />
import Port = chrome.runtime.Port;
import MessageSender = chrome.runtime.MessageSender;
/**
 * Type definition for a message handler function
 * @template Payload - Type of the incoming message payload
 * @template Response - Type of the response to be sent back
 */
export type Handler<Payload, Response> = (payload: Payload, sender?: MessageSender) => Promise<Response>;
/**
 * Type definition for a request creator function
 * @template Payload - Type of the request payload
 * @template Response - Type of the expected response
 */
export type RequestCreator<Payload, Response> = {
    (payload?: Payload): Request<Payload, Response>;
    type: string;
};
/**
 * Type definition for an action creator function
 * @template Payload - Type of the action payload
 * @template Response - Type of the response to be sent back
 */
export type ActionCreator<Payload, Response> = {
    (payload?: Payload): Action<Payload, Response>;
    type: string;
};
/**
 * Interface representing a request message
 * @template Payload - Type of the request payload
 * @template Response - Type of the expected response
 */
export interface Request<Payload, Response> {
    type: string;
    payload?: Payload;
    toAction: () => Action<Payload, Response>;
}
/**
 * Interface representing an action that can handle a request
 * @template Payload - Type of the action payload
 * @template Response - Type of the response to be sent back
 */
export interface Action<Payload, Response> {
    type: string;
    payload?: Payload;
    handler: Handler<Payload, Response>;
}
/**
 * Type representing an error response
 */
export type Error = {
    error: string;
};
/**
 * Creates a request creator function for a specific message type
 * @template Payload - Type of the request payload
 * @template Response - Type of the expected response
 * @param type - Unique identifier for the request type
 * @returns A function that creates requests of the specified type
 */
export declare function createRequest<Payload, Response>(type: string): RequestCreator<Payload, Response>;
/**
 * Creates an action creator function for handling specific message types
 * @template Payload - Type of the action payload
 * @template Response - Type of the response to be sent back
 * @param type - Unique identifier for the action type
 * @param handler - Function that will handle the incoming message
 * @returns A function that creates actions of the specified type
 */
export declare function createAction<Payload, Response>(type: string, handler: Handler<Payload, Response>): ActionCreator<Payload, Response>;
/**
 * Creates an action creator from an existing request creator
 * @template Payload - Type of the payload
 * @template Response - Type of the response
 * @param requestCreator - The request creator to base the action on
 * @param handler - Function that will handle the incoming message
 * @returns A function that creates actions matching the request type
 */
export declare function createFromRequest<Payload, Response>(requestCreator: RequestCreator<Payload, Response>, handler: Handler<Payload, Response>): ActionCreator<Payload, Response>;
/**
 * Type definition for a connection listener function
 */
export type OnConnectListener = (port: Port) => void;
/**
 * Enhanced messaging API wrapper for Chrome extensions.
 * Provides a type-safe way to handle request-response communication between different parts of the extension.
 * Automatically cleans up listeners after receiving a response or on failure.
 */
export declare class Messages {
    private readonly _verbose;
    /**
     * Creates a new Messages instance
     * @param verbose - Whether to enable verbose logging
     */
    constructor(verbose?: boolean);
    /**
     * Sends a request to the extension runtime
     * @template Payload - Type of the request payload
     * @template Response - Type of the expected response
     * @param request - The request to send
     * @returns Promise that resolves with the response or rejects with an error
     */
    request<Payload, Response>(request: Request<Payload, Response>): Promise<Response & Error>;
    /**
     * Sends a request to a specific tab
     * @template Payload - Type of the request payload
     * @template Response - Type of the expected response
     * @param tabId - ID of the target tab
     * @param request - The request to send
     * @returns Promise that resolves with the response or rejects with an error
     */
    requestTab<Payload, Response>(tabId: number, request: Request<Payload, Response>): Promise<Response & Error>;
    /**
     * Handles the request-response cycle for a given port
     * @template Payload - Type of the request payload
     * @template Response - Type of the expected response
     * @param request - The request to send
     * @param port - The port to communicate through
     * @returns Promise that resolves with the response or rejects with an error
     */
    private handleRequest;
    /**
     * Sets up a listener for incoming connections of a specific type
     * @template Payload - Type of the incoming message payload
     * @template Response - Type of the response to be sent back
     * @param actionCreator - Function that creates actions for handling messages
     * @returns The connection listener function that was added
     */
    listen<Payload, Response>(actionCreator: ActionCreator<Payload, Response>): OnConnectListener;
    /**
     * Removes a previously added connection listener
     * @param onConnect - The listener function to remove
     */
    removeListener(onConnect: OnConnectListener): void;
}