node-jet/lib/3_jet/peer/index.d.ts

Jet Realtime Message Bus for the Web. Daemon and Peer implementation.

import type { InfoOptions } from '../daemon/index.js';
import { type PublishMessage, type ValueType } from '../types.js';
import { type JsonRpcConfig } from '../../2_jsonrpc/index.js';
import type Method from './method.js';
import type State from './state.js';
import Fetcher from './fetcher.js';
import { type logger } from '../log.js';
import type { Socket } from '../../1_socket/socket.js';
import { EventEmitter } from '../../1_socket/index.js';
import type { access } from '../daemon/route.js';
export interface JsonParams<T = ValueType> {
    method?: string;
    access?: access;
    path?: string | Record<string, string | string[]>;
    args?: object;
    timeout?: number;
    value?: T;
    user?: string;
    password?: string;
    groups?: string[];
    id?: string;
}
export type publishEvent = 'Add' | 'Remove' | 'Change';
export interface PublishParams<T = ValueType> {
    event?: publishEvent;
    path: string;
    value?: T;
}
export interface PeerConfig extends JsonRpcConfig {
    url?: string;
    ip?: string;
    port?: number;
    name?: string;
    log?: logger;
}
/**
 * Create a Jet Peer instance.
 * @class
 * @classdesc A Peer instance is required for all actions related to Jet.
 * A Peer connected to a Daemon is able to add content (States/Methods)
 * or to consume content (by fetching or by calling set).
 * The peer uses either the Websocket protocol or the TCP trivial protocol (default) as transport.
 * When specifying the url field, the peer uses the Websocket protocol as transport.
 * If no config is provided, the Peer connects to the local ('localhost') Daemon using
 * the trivial protocol.
 * Browsers do only support the Websocket transport and must be provided with a config with url field.
 *
 * @param {PeerConfig} [config] A peer configuration
 * @param {string} [config.url] The Jet Daemon Websocket URL, e.g. `ws://localhost:11123`
 * @param {string} [config.ip=localhost] The Jet Daemon TCP trivial protocol ip
 * @param {number} [config.port=11122] The Jet Daemon TCP trivial protocol port
 * @param {string} [config.user] The user name used for authentication
 * @param {string} [config.password] The user's password used for auhtentication
 * @returns {Peer} The newly created Peer instance.
 *
 * @example
 * var peer = new jet.Peer({url: 'ws://jetbus.io:8080'})
 */
export declare class Peer extends EventEmitter {
    #private;
    cache: Record<string, PublishMessage<ValueType>>;
    constructor(config?: PeerConfig, sock?: Socket);
    isConnected: () => boolean;
    unfetch: (fetcher: Fetcher) => Promise<undefined>;
    fetchFull: () => boolean;
    fetch: (fetcher: Fetcher) => Promise<void>;
    /**
     * Actually connect the peer to the Jet Daemon
     * After the connect Promise has been resolved, the peer provides `peer.daemonInfo` object.
     *
     * ```javascript
     * peer.connect().then(function() {
     *   var daemonInfo = peer.daemonInfo
     *   console.log('name', daemonInfo.name) // string
     *   console.log('version', daemonInfo.version) // string
     *   console.log('protocolVersion', daemonInfo.protocolVersion) // number
     *   console.log('can process JSON-RPC batches', daemonInfo.features.batches) // boolean
     *   console.log('supports authentication', daemonInfo.features.authentication) // boolean
     *   console.log('fetch-mode', daemonInfo.features.fetch); // string: 'full' or 'simple'
     * })
     * ```
     *
     * @returns {external:Promise} A Promise which gets resolved once connected to the Daemon, or gets rejected with either:
     * - [jet.ConnectionClosed](#module:errors~ConnectionClosed)
     *
     * @example
     * var peer = new jet.Peer({url: 'ws://jetbus.io:8012'})
     * peer.connect().then(function() {
     *   console.log('connected')
     * }).catch(function(err) {
     *   console.log('connect failed', err)
     * })
     */
    authenticate: (user: string, password: string) => Promise<ValueType>;
    addUser: (user: string, password: string, groups: string[]) => Promise<ValueType>;
    connect: (controller?: AbortController) => Promise<void>;
    /**
     * Close the connection to the Daemon. All associated States and Methods are automatically
     * removed by the Daemon.
     *
     * @returns {external:Promise}
     *
     */
    close: () => Promise<void>;
    /**
     * Batch operations wrapper. Issue multiple commands to the Daemon
     * in one message batch. Only required for performance critical actions.
     *
     * @param {function} action A function performing multiple peer actions.
     *
     */
    batch: (action: () => void) => void;
    /**
     * Get {State}s and/or {Method}s defined by a Peer.
     *
     * @param {object} expression A Fetch expression to retrieve a snapshot of the currently matching data.
     * @returns {external:Promise}
     */
    get: <T extends ValueType>(expression: JsonParams) => Promise<{
        path: string;
        value: T;
    }[]>;
    /**
     * Adds a state or method to the Daemon.
     *
     * @param {(State|Method)} content The content to be added.
     * @returns {external:Promise} Gets resolved as soon as the content has been added to the Daemon.
     */
    add: <T extends ValueType>(stateOrMethod: Method | State<T>) => Promise<void>;
    /**
     * Remove a state or method from the Daemon.
     *
     * @param {State|Method} content The content to be removed.
     * @returns {external:Promise} Gets resolved as soon as the content has been removed from the Daemon.
     */
    remove: <T extends ValueType>(stateOrMethod: Method | State<T>) => Promise<void>;
    /**
     * Call a {Method} defined by another Peer.
     *
     * @param {string} path The unique path of the {Method}.
     * @param {Array} args The arguments provided to the {Method}.
     * @param {object} [options] Options.
     * @param {number} [options.timeout] A timeout for invoking the {Method} after which a timeout error rejects the promise.
     * @returns {external:Promise}
     */
    call: (path: string, callparams: ValueType[] | Record<string, ValueType>) => Promise<object>;
    /**
     * Info
     * @private
     */
    info: () => Promise<InfoOptions>;
    /**
     * Authenticate
     * @private
     */
    /**
     * Config
     *
     * @private
     */
    configure: (params: JsonParams) => Promise<ValueType>;
    /**
     * Set a {State} to another value.
     *
     * @param {string} path The unique path to the {State}.
     * @param {*} value The desired new value of the {State}.
     * @param {object} [options] Optional settings
     * @param {number} [options.timeout]
     *
     */
    set: (path: string, value: ValueType) => Promise<ValueType>;
}
export default Peer;