@bakit/service 3.2.1 → 4.0.1

package/dist/index.d.cts

@@ -0,0 +1,323 @@
+import EventEmitter from 'node:events';
+import * as _bakit_utils from '@bakit/utils';
+import { Awaitable, Collection, FunctionLike, Promisify } from '@bakit/utils';
+import { Socket } from 'node:net';
+
+type Serializable =
+	| string
+	| number
+	| boolean
+	| null
+	| undefined
+	| Serializable[]
+	| { [key: string]: Serializable };
+
+interface RPCResponseError {
+	message: string;
+	name: string;
+	constructorName: string;
+	stack?: string;
+	cause?: RPCResponseError;
+	errors?: RPCResponseError[]; // For AggregateError
+	[key: string]: unknown;
+}
+
+declare const SUPPORTED_LENGTH_BYTES: readonly [1, 2, 4, 8];
+interface FrameCodecOptions {
+    maxBufferSize?: number;
+    maxFrameSize?: number;
+    lengthBytes?: (typeof SUPPORTED_LENGTH_BYTES)[number];
+    endian?: "big" | "little";
+    lengthIncludesHeader?: boolean;
+}
+declare class FrameCodec {
+    private buffer;
+    readonly options: Required<FrameCodecOptions>;
+    stats: {
+        bytesReceived: number;
+        bytesDecoded: number;
+        framesDecoded: number;
+        bufferCopies: number;
+    };
+    constructor(options?: FrameCodecOptions);
+    push(chunk: Buffer): Buffer[];
+    get bufferedBytes(): number;
+    reset(): void;
+    private readLength;
+    encode(payload: Buffer): Buffer<ArrayBufferLike>;
+    static encode(payload: Buffer, options?: FrameCodecOptions): Buffer;
+    static serialize(obj: Serializable): Buffer;
+    static deserialize(buf: Buffer): Serializable;
+}
+
+type EventMap<T> = Record<keyof T, any[]> | DefaultEventMap;
+type DefaultEventMap = [never];
+interface BaseClientDriverEvents {
+    message: [message: Serializable];
+    connect: [];
+    disconnect: [];
+    error: [error: Error];
+}
+interface BaseServerDriverEvents<Connection = unknown> {
+    listen: [];
+    close: [];
+    error: [error: Error];
+    message: [connection: Connection, message: Serializable];
+    connectionAdd: [connection: Connection];
+    connectionRemove: [connection: Connection];
+    connectionError: [connection: Connection, error: Error];
+}
+declare abstract class BaseDriver<Options extends object, Events extends EventMap<Events>> extends EventEmitter<Events> {
+    options: Options;
+    constructor(options: Options);
+}
+declare abstract class BaseClientDriver<Options extends object = object, Events extends EventMap<Events> & BaseClientDriverEvents = BaseClientDriverEvents> extends BaseDriver<Options, Events> {
+    constructor(options: Options);
+    abstract readonly ready: boolean;
+    abstract send(message: Serializable): Awaitable<void>;
+    abstract connect(): Awaitable<void>;
+    abstract disconnect(): Awaitable<void>;
+}
+declare abstract class BaseServerDriver<Options extends object = object, Connection = unknown, Events extends EventMap<Events> & BaseServerDriverEvents<Connection> = BaseServerDriverEvents<Connection>> extends BaseDriver<Options, Events> {
+    constructor(options: Options);
+    readonly _connectionType: Connection;
+    abstract readonly connections: Set<Connection> | Map<unknown, Connection> | Connection[];
+    abstract listen(): Awaitable<void>;
+    abstract close(): Awaitable<void>;
+    abstract send(connection: Connection, message: Serializable): Awaitable<void>;
+    abstract broadcast(message: Serializable): Awaitable<unknown>;
+}
+
+interface IPCClientOptions {
+    id: string;
+    codec?: FrameCodecOptions;
+    reconnect?: IPCClientReconnectOptions;
+}
+interface IPCClientReconnectOptions {
+    /** Enable auto-reconnect (default: true) */
+    enabled?: boolean;
+    /** Max retry attempts (default: 5) */
+    maxRetries?: number;
+    /** Initial delay in ms (default: 1000) */
+    initialDelay?: number;
+    /** Backoff multiplier (default: 1.5) */
+    backoff?: number;
+    /** Max delay in ms (default: 30000) */
+    maxDelay?: number;
+}
+interface IPCClientEvents extends BaseClientDriverEvents {
+    reconnect: [];
+    reconnecting: [attempt: number, delay: number];
+}
+declare enum IPCClientState {
+    Idle = 0,
+    Connecting = 1,
+    Connected = 2,
+    Disconnected = 3
+}
+declare const DEFAULT_IPC_CLIENT_RECONNECT_OPTIONS: Required<IPCClientReconnectOptions>;
+declare class IPCClient extends BaseClientDriver<IPCClientOptions, IPCClientEvents> {
+    private socket?;
+    private codec;
+    state: IPCClientState;
+    private _ready;
+    private reconnectTimer?;
+    private reconnectOptions;
+    private reconnectAttempt;
+    private isIntentionalClose;
+    private queue;
+    constructor(options: IPCClientOptions);
+    get path(): string;
+    get ready(): boolean;
+    connect(): Promise<void>;
+    send(message: Serializable): Promise<void>;
+    disconnect(): Promise<void>;
+    private init;
+    private cleanup;
+    private onSocketConnect;
+    private onSocketClose;
+    private onSocketError;
+    private onSocketData;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private makeMessage;
+    private serialize;
+    private deserialize;
+}
+declare function createIPCClient(options: IPCClientOptions): IPCClient;
+
+interface IPCConnectionEvents {
+    message: [message: Serializable];
+    close: [];
+    error: [error: Error];
+}
+declare class IPCConnection extends EventEmitter<IPCConnectionEvents> {
+    server: IPCServer;
+    socket: Socket;
+    private codec;
+    constructor(server: IPCServer, socket: Socket);
+    send(message: Serializable): Promise<void>;
+    destroy(): void;
+    private setupListeners;
+    private handleData;
+}
+
+interface IPCServerOptions {
+    id: string;
+    codec?: FrameCodecOptions;
+}
+type IPCServerEvents = BaseServerDriverEvents<IPCConnection>;
+declare class IPCServer extends BaseServerDriver<IPCServerOptions, IPCConnection, IPCServerEvents> {
+    private server?;
+    private codecOptions;
+    connections: Collection<Socket, IPCConnection>;
+    codec: FrameCodec;
+    constructor(options: IPCServerOptions);
+    get path(): string;
+    listen(): Promise<void>;
+    private handleConnection;
+    send(connection: IPCConnection, message: Serializable): Awaitable<void>;
+    /**
+     * Send message to a specific client
+     */
+    sendSocket(socket: Socket, message: Serializable): Promise<void>;
+    /**
+     * Broadcast to all connected clients
+     * Returns count of successful sends (fire-and-forget, errors emitted via 'clientError')
+     */
+    broadcast(message: Serializable): Promise<void>;
+    /**
+     * Close server and disconnect all clients
+     */
+    close(): Promise<void>;
+    private sendSocketFrame;
+}
+declare function createIPCServer(options: IPCServerOptions): IPCServer;
+
+interface TransportClientEvents {
+    connect: [];
+    disconnect: [];
+    error: [error: Error];
+    message: [message: Serializable];
+}
+declare class TransportClient<D extends BaseClientDriver> extends EventEmitter<TransportClientEvents> {
+    readonly driver: D;
+    private pending;
+    constructor(driver: D);
+    connect(): _bakit_utils.Awaitable<void>;
+    disconnect(): _bakit_utils.Awaitable<void>;
+    request<Result extends Serializable>(method: string, ...args: Serializable[]): Promise<Result>;
+    send(message: Serializable): _bakit_utils.Awaitable<void>;
+    private setupDriverListeners;
+    private handleMessage;
+    private hydrateError;
+    private captureCallStack;
+    private isResponseMessage;
+}
+declare function createTransportClient<D extends BaseClientDriver<object, any>>(driver: D): TransportClient<D>;
+
+type RPCHandler = (...args: Serializable[]) => Promise<Serializable | Error>;
+interface TransportServerEvents<D extends BaseServerDriver> {
+    listen: [];
+    close: [];
+    error: [error: Error];
+    connectionAdd: [connection: D["_connectionType"]];
+    connectionRemove: [connection: D["_connectionType"]];
+    connectionError: [connection: D["_connectionType"], error: Error];
+    message: [connection: D["_connectionType"], message: Serializable];
+}
+declare class TransportServer<D extends BaseServerDriver> extends EventEmitter<TransportServerEvents<D>> {
+    readonly driver: D;
+    private handlers;
+    constructor(driver: D);
+    get connections(): D["connections"];
+    handle(method: string, handler: RPCHandler): void;
+    listen(): ReturnType<D["listen"]>;
+    close(): ReturnType<D["close"]>;
+    broadcast(message: Serializable): ReturnType<D["broadcast"]>;
+    private setupDriverListeners;
+    private handleMessage;
+    private isRequestMessage;
+}
+declare function createTransportServer<D extends BaseServerDriver<object, any>>(driver: D): TransportServer<D>;
+
+declare enum ServiceDriver {
+    IPC = "ipc"
+}
+interface DriverOptionsMap {
+    [ServiceDriver.IPC]: {
+        id: string;
+        server?: Omit<IPCServerOptions, "id">;
+        client?: Omit<IPCClientOptions, "id">;
+    };
+}
+type ServiceOptions = {
+    [D in keyof DriverOptionsMap]: {
+        driver: D;
+    } & DriverOptionsMap[D];
+}[keyof DriverOptionsMap];
+interface ServiceClientRuntime {
+    role: "client";
+    transport: TransportClient<BaseClientDriver>;
+}
+interface ServiceServerRuntime {
+    role: "server";
+    transport: TransportServer<BaseServerDriver>;
+}
+declare class Service {
+    readonly options: ServiceOptions;
+    private runtime?;
+    private handlers;
+    private binding?;
+    constructor(options: ServiceOptions);
+    get role(): "client" | "server";
+    define<F extends FunctionLike>(method: string, handler: F): Promisify<F>;
+    protected ensureServerBound(): Promise<void> | undefined;
+    protected ensureClientBound(): Promise<void> | undefined;
+}
+declare function createService(options: ServiceOptions): Service;
+declare function getServices(entryDir?: string, cwd?: string): Promise<string[]>;
+declare function getServiceName(servicePath: string, cwd?: string): string;
+
+interface ServiceProcessEvents {
+    stdout: [chunk: Buffer];
+    stderr: [chunk: Buffer];
+    spawn: [];
+    error: [err: Error];
+    exit: [code: number | null, signal: NodeJS.Signals | null];
+}
+declare enum ServiceState {
+    Idle = 0,
+    Starting = 1,
+    Running = 2,
+    Restarting = 3,
+    Stopping = 4,
+    Stopped = 5
+}
+declare class ServiceProcess extends EventEmitter<ServiceProcessEvents> {
+    readonly path: string;
+    private child?;
+    private spawnTimestamp;
+    private _state;
+    constructor(path: string);
+    get name(): string;
+    get state(): ServiceState;
+    get ready(): boolean;
+    get uptime(): number;
+    start(): void;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    private init;
+    private cleanup;
+    private onChildSpawn;
+    private onChildExit;
+}
+
+declare function getIPCPath(id: string, platform?: NodeJS.Platform): string;
+declare function isServerRunning(path: string): Promise<boolean>;
+
+declare function serializeRPCError(err: Error): RPCResponseError;
+declare function createDynamicRPCError(data: RPCResponseError): Error;
+declare function isSerializedError(value: unknown): value is RPCResponseError;
+
+export { BaseClientDriver, type BaseClientDriverEvents, BaseServerDriver, type BaseServerDriverEvents, DEFAULT_IPC_CLIENT_RECONNECT_OPTIONS, FrameCodec, type FrameCodecOptions, IPCClient, type IPCClientEvents, type IPCClientOptions, type IPCClientReconnectOptions, IPCClientState, IPCServer, type IPCServerEvents, type IPCServerOptions, type RPCHandler, Service, type ServiceClientRuntime, ServiceDriver, type ServiceOptions, ServiceProcess, type ServiceProcessEvents, type ServiceServerRuntime, ServiceState, TransportClient, type TransportClientEvents, TransportServer, type TransportServerEvents, createDynamicRPCError, createIPCClient, createIPCServer, createService, createTransportClient, createTransportServer, getIPCPath, getServiceName, getServices, isSerializedError, isServerRunning, serializeRPCError };