cspell-lib 9.6.0 → 9.6.2

package/dist/rpc/assert.js

@@ -0,0 +1,21 @@
+/**
+ * Note: This code is here to avoid a dependency on Node's 'assert' module.
+ */
+/**
+ * Asserts that a condition is true.
+ * @param condition - The condition to assert.
+ * @param msg - optional message for the assertion error.
+ * @throws {AssertionError} If the condition is false.
+ */
+export function assert(condition, msg) {
+    if (!condition) {
+        throw new AssertionError(msg);
+    }
+}
+export class AssertionError extends Error {
+    constructor(message) {
+        super(message || 'Assertion failed');
+        this.name = 'AssertionError';
+    }
+}
+//# sourceMappingURL=assert.js.map

package/dist/rpc/client.d.ts

@@ -0,0 +1,186 @@
+import type { MessagePortLike } from './messagePort.js';
+import type { RCPBaseRequest, RequestID, RPCPendingClientRequest, RPCResponse } from './models.js';
+import type { RPCProtocol, RPCProtocolMethodNames } from './protocol.js';
+interface PendingRequest {
+    readonly id: RequestID;
+    readonly request: RCPBaseRequest;
+    readonly response: Promise<RPCResponse>;
+    readonly isResolved: boolean;
+    readonly isCanceled: boolean;
+    /** calling abort will cancel the request if it has not already been resolved. */
+    abort: AbortController['abort'];
+    handleResponse: (res: RPCResponse) => void;
+    /**
+     * Cancels the request by telling the server to cancel the request and waiting on the response.
+     */
+    cancel: () => Promise<boolean>;
+}
+export interface RPCClientOptions {
+    /**
+     * A function to generate random UUIDs.
+     * @default undefined
+     */
+    randomUUID?: () => string;
+    /**
+     * If true, the client will close the port when disposed.
+     * @default false
+     */
+    closePortOnDispose?: boolean;
+    /**
+     * Set the default timeout in milliseconds for requests.
+     */
+    timeoutMs?: number;
+}
+export interface RPCClientConfiguration extends RPCClientOptions {
+    /**
+     * The message port to use for communication.
+     */
+    port: MessagePortLike;
+}
+export interface RequestOptions {
+    /**
+     * An AbortSignal to abort the request.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Timeout in milliseconds to wait before aborting the request.
+     */
+    timeoutMs?: number | undefined;
+}
+/**
+ * The RPC Client.
+ */
+declare class RPCClientImpl<T, P extends RPCProtocol<T> = RPCProtocol<T>, MethodNames extends RPCProtocolMethodNames<P> = RPCProtocolMethodNames<P>> {
+    #private;
+    /**
+     * Create an RPC Client.
+     * @param config - The client configuration.
+     */
+    constructor(config: RPCClientConfiguration);
+    /**
+     * Make a request to the RPC server.
+     *
+     * It is unlikely you need to use this method directly. Consider using `call` or `getApi` instead.
+     *
+     * @param method - The method name.
+     * @param params - The method parameters.
+     * @param options - Request options including abort signal and timeout.
+     * @returns The pending client request.
+     */
+    request<M extends MethodNames>(method: M, params: Parameters<P[M]>, options?: RequestOptions): RPCPendingClientRequest<M, ReturnType<P[M]>>;
+    /**
+     * Check the health of the RPC server.
+     * @param options - used to set timeout and abort signal.
+     * @returns resolves to true if the server is OK, false on timeout.
+     */
+    isOK(options?: RequestOptions): Promise<boolean>;
+    /**
+     * The current known ready state of the RPC server.
+     * - `true` - The server is ready.
+     * - `false` - The server is not ready.
+     */
+    get isReady(): boolean;
+    /**
+     * Check if the RPC server is ready. If already ready, returns true immediately.
+     * If not ready, sends a 'ready' request to the server.
+     * @param options - used to set timeout and abort signal.
+     * @returns resolves to true when the server is ready, rejects if the request times out or fails.
+     */
+    ready(options?: RequestOptions): Promise<boolean>;
+    /**
+     * Call a method on the RPC server.
+     * @param method - The method name.
+     * @param params - The method parameters.
+     * @param options - Call options including abort signal.
+     * @returns A Promise with the method result.
+     */
+    call<M extends MethodNames>(method: M, params: Parameters<P[M]>, options?: RequestOptions): ReturnType<P[M]>;
+    /**
+     * Get the API for the given method names.
+     *
+     * This is useful passing the API to other parts of the code that do not need to know about the RPCClient.
+     *
+     * @param methods - The method names to include in the API.
+     * @returns A partial API with the requested methods.
+     */
+    getApi<M extends MethodNames>(methods: M[]): Pick<P, M>;
+    /**
+     * Get info about a pending request by its RequestID.
+     * @param id - The RequestID of the pending request.
+     * @returns The found pending request or undefined if not found.
+     */
+    getPendingRequestById(id: RequestID): PendingRequest | undefined;
+    /**
+     * Get info about a pending request by the promise returned using `call` or an api method.
+     * @param id - The RequestID of the pending request.
+     * @returns The found pending request or undefined if not found.
+     */
+    getPendingRequestByPromise(promise: Promise<unknown>): PendingRequest | undefined;
+    /**
+     * Get the number of pending requests.
+     */
+    get length(): number;
+    /**
+     * Abort a pending request by its promise.
+     *
+     * Note: the request promise will be rejected with an AbortRequestError.
+     * @param promise - The promise returned by the request.
+     * @param reason - The reason for aborting the request.
+     * @returns True if the request was found and aborted, false otherwise.
+     */
+    abortPromise(promise: Promise<unknown>, reason: unknown): boolean;
+    /**
+     * Abort a pending request by its RequestId.
+     *
+     * Note: the request promise will be rejected with an AbortRequestError.
+     * @param requestId - The RequestID of the request to abort.
+     * @param reason - The reason for aborting the request.
+     * @returns True if the request was found and aborted, false otherwise.
+     */
+    abortRequest(requestId: RequestID, reason?: unknown): boolean;
+    /**
+     * Abort all pending requests.
+     *
+     * Note: each request promise will be rejected with an AbortRequestError.
+     *
+     * @param reason - The reason for aborting the request.
+     */
+    abortAllRequests(reason?: unknown): void;
+    /**
+     * Cancel a pending request by its RequestID.
+     *
+     * Tries to cancel the request by sending a cancel request to the server and waiting for the response.
+     * @param id - The RequestID of the request to cancel.
+     * @returns resolves to true if the request was found and canceled, false otherwise.
+     */
+    cancelRequest(id: RequestID): Promise<boolean>;
+    /**
+     * Cancel a pending request by its Promise.
+     *
+     * Tries to cancel the request by sending a cancel request to the server and waiting for the response.
+     * @param id - The RequestID of the request to cancel.
+     * @returns resolves to true if the request was found and canceled, false otherwise.
+     */
+    cancelPromise(promise: Promise<unknown>): Promise<boolean>;
+    /**
+     * Set the default timeout for requests. Requests can override this value.
+     * @param timeoutMs - the timeout in milliseconds
+     */
+    setTimeout(timeoutMs: number | undefined): void;
+    /**
+     * Dispose of the RPC client, aborting all pending requests and closing the port if specified in options.
+     */
+    [Symbol.dispose](): void;
+}
+/**
+ * The RPC Client.
+ */
+export declare class RPCClient<T> extends RPCClientImpl<T> {
+    /**
+     * Create an RPC Client.
+     * @param config - The client configuration.
+     */
+    constructor(config: RPCClientConfiguration);
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/rpc/client.js

@@ -0,0 +1,364 @@
+import { AbortRPCRequestError, CanceledRPCRequestError, TimeoutRPCRequestError } from './errors.js';
+import { Future } from './Future.js';
+import { MessagePortNotifyEvents } from './MessagePortEvents.js';
+import { createRPCCancelRequest, createRPCMethodRequest, createRPCOkRequest, createRPCReadyRequest, isBaseResponse, isRPCCanceledResponse, isRPCErrorResponse, isRPCReadyResponse, isRPCResponse, } from './modelsHelpers.js';
+const DefaultOkOptions = {
+    timeoutMs: 200,
+};
+/**
+ * The RPC Client.
+ */
+class RPCClientImpl {
+    #port;
+    #count = 0;
+    #options;
+    #pendingRequests = new Map();
+    #pendingRequestsByPromise = new WeakMap();
+    #defaultTimeoutMs;
+    #isReady;
+    #ready;
+    /**
+     * Create an RPC Client.
+     * @param config - The client configuration.
+     */
+    constructor(config) {
+        this.#port = new MessagePortNotifyEvents(config.port);
+        this.#options = config;
+        this.#defaultTimeoutMs = config.timeoutMs;
+        this.#isReady = false;
+        this.#ready = new Future();
+        this.#port.onMessage((msg) => this.#processMessageFromServer(msg));
+        this.#port.start();
+    }
+    /**
+     * Make a request to the RPC server.
+     *
+     * It is unlikely you need to use this method directly. Consider using `call` or `getApi` instead.
+     *
+     * @param method - The method name.
+     * @param params - The method parameters.
+     * @param options - Request options including abort signal and timeout.
+     * @returns The pending client request.
+     */
+    request(method, params, options) {
+        // Register the request.
+        const id = this.#calcId(method);
+        const request = createRPCMethodRequest(id, method, params);
+        const pendingRequest = this.#sendRequest(request, options);
+        const response = pendingRequest.response.then(handleResponse);
+        // Record the promise to request ID mapping.
+        this.#pendingRequestsByPromise.set(response, id);
+        const clientRequest = {
+            id,
+            method,
+            response,
+            abort: pendingRequest.abort,
+            cancel: pendingRequest.cancel,
+            get isResolved() {
+                return pendingRequest.isResolved;
+            },
+            get isCanceled() {
+                return pendingRequest.isCanceled;
+            },
+        };
+        return clientRequest;
+        function handleResponse(res) {
+            if (isRPCErrorResponse(res)) {
+                throw res.error;
+            }
+            if (isRPCCanceledResponse(res)) {
+                throw new CanceledRPCRequestError(`Request ${id} was canceled`);
+            }
+            if (isRPCResponse(res)) {
+                return res.result;
+            }
+            throw new Error(`Malformed response for request ${id}`); // Should not happen.
+        }
+    }
+    #sendRequest(request, options = {}) {
+        // Register the request.
+        const id = request.id;
+        const requestType = request.type;
+        let isResolved = false;
+        let isCanceled = false;
+        const timeoutMs = options.timeoutMs ?? this.#defaultTimeoutMs;
+        const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
+        const future = new Future();
+        options.signal?.addEventListener('abort', abort);
+        timeoutSignal?.addEventListener('abort', timeoutHandler);
+        const response = future.promise;
+        const cancelRequest = () => this.#port.postMessage(createRPCCancelRequest(id));
+        const cancel = async () => {
+            if (isResolved || isCanceled)
+                return isCanceled;
+            cancelRequest();
+            await response.catch(() => { });
+            return isCanceled;
+        };
+        const pendingRequest = {
+            id,
+            request,
+            response,
+            handleResponse,
+            abort,
+            cancel,
+            get isResolved() {
+                return isResolved;
+            },
+            get isCanceled() {
+                return isCanceled;
+            },
+        };
+        this.#pendingRequests.set(id, pendingRequest);
+        this.#pendingRequestsByPromise.set(response, id);
+        const cleanup = () => {
+            options.signal?.removeEventListener('abort', abort);
+            timeoutSignal?.removeEventListener('abort', timeoutHandler);
+            this.#cleanupPendingRequest(pendingRequest);
+        };
+        this.#port.postMessage(request);
+        return pendingRequest;
+        function timeoutHandler() {
+            abort(new TimeoutRPCRequestError(`Request ${requestType} ${id} timed out after ${timeoutMs} ms`));
+        }
+        function abort(reason) {
+            if (isResolved || isCanceled)
+                return;
+            isCanceled = true;
+            cancelRequest();
+            reason = reason instanceof Event ? undefined : reason;
+            reason ??= `Request ${id} aborted`;
+            reason = typeof reason === 'string' ? new AbortRPCRequestError(reason) : reason;
+            cleanup();
+            future.reject(reason);
+        }
+        function handleResponse(res) {
+            // Do not process anything if already resolved or canceled.
+            if (isResolved || isCanceled)
+                return;
+            isResolved = true;
+            if (isRPCCanceledResponse(res)) {
+                isCanceled = true;
+            }
+            cleanup();
+            future.resolve(res);
+        }
+    }
+    /**
+     * Check the health of the RPC server.
+     * @param options - used to set timeout and abort signal.
+     * @returns resolves to true if the server is OK, false on timeout.
+     */
+    async isOK(options = DefaultOkOptions) {
+        try {
+            const req = this.#sendRequest(createRPCOkRequest(this.#calcId('isOK')), options);
+            const res = await req.response;
+            return isBaseResponse(res) && res.type === 'ok' && res.code === 200;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * The current known ready state of the RPC server.
+     * - `true` - The server is ready.
+     * - `false` - The server is not ready.
+     */
+    get isReady() {
+        return this.#isReady;
+    }
+    /**
+     * Check if the RPC server is ready. If already ready, returns true immediately.
+     * If not ready, sends a 'ready' request to the server.
+     * @param options - used to set timeout and abort signal.
+     * @returns resolves to true when the server is ready, rejects if the request times out or fails.
+     */
+    async ready(options) {
+        if (this.#isReady)
+            return true;
+        // We send the request, but we do not care about the result other than it succeeded.
+        await this.#sendRequest(createRPCReadyRequest(this.#calcId('ready')), options).response;
+        return this.#isReady; // We are returning the current state.
+    }
+    /**
+     * Call a method on the RPC server.
+     * @param method - The method name.
+     * @param params - The method parameters.
+     * @param options - Call options including abort signal.
+     * @returns A Promise with the method result.
+     */
+    call(method, params, options) {
+        const req = this.request(method, params, options);
+        return req.response;
+    }
+    /**
+     * Get the API for the given method names.
+     *
+     * This is useful passing the API to other parts of the code that do not need to know about the RPCClient.
+     *
+     * @param methods - The method names to include in the API.
+     * @returns A partial API with the requested methods.
+     */
+    getApi(methods) {
+        const apiEntries = methods.map((method) => [method, ((...params) => this.call(method, params))]);
+        return Object.fromEntries(apiEntries);
+    }
+    /**
+     * Get info about a pending request by its RequestID.
+     * @param id - The RequestID of the pending request.
+     * @returns The found pending request or undefined if not found.
+     */
+    getPendingRequestById(id) {
+        return this.#pendingRequests.get(id);
+    }
+    /**
+     * Get info about a pending request by the promise returned using `call` or an api method.
+     * @param id - The RequestID of the pending request.
+     * @returns The found pending request or undefined if not found.
+     */
+    getPendingRequestByPromise(promise) {
+        const requestId = this.#pendingRequestsByPromise.get(promise);
+        if (!requestId)
+            return undefined;
+        return this.getPendingRequestById(requestId);
+    }
+    /**
+     * Get the number of pending requests.
+     */
+    get length() {
+        return this.#pendingRequests.size;
+    }
+    #calcId(method) {
+        const suffix = this.#options.randomUUID ? this.#options.randomUUID() : `${performance.now()}`;
+        return `${method}-${++this.#count}-${suffix}`;
+    }
+    #cleanupPendingRequest(request) {
+        this.#pendingRequests.delete(request.id);
+        this.#pendingRequestsByPromise.delete(request.response);
+    }
+    #processMessageFromServer(msg) {
+        // Ignore messages that are not RPC messages
+        if (!isBaseResponse(msg))
+            return;
+        this.#handleReadyResponse(msg);
+        const pendingRequest = this.#pendingRequests.get(msg.id);
+        if (!pendingRequest)
+            return;
+        pendingRequest.handleResponse(msg);
+    }
+    /**
+     * Handle possible ready response messages.
+     * @param msg - The message to handle.
+     */
+    #handleReadyResponse(msg) {
+        if (!isRPCReadyResponse(msg))
+            return;
+        if (this.#ready.isResolved)
+            return;
+        this.#isReady = msg.code === 200;
+        this.#ready.resolve(this.#isReady);
+    }
+    /**
+     * Abort a pending request by its promise.
+     *
+     * Note: the request promise will be rejected with an AbortRequestError.
+     * @param promise - The promise returned by the request.
+     * @param reason - The reason for aborting the request.
+     * @returns True if the request was found and aborted, false otherwise.
+     */
+    abortPromise(promise, reason) {
+        const pendingRequest = this.getPendingRequestByPromise(promise);
+        if (!pendingRequest)
+            return false;
+        return this.abortRequest(pendingRequest.id, reason);
+    }
+    /**
+     * Abort a pending request by its RequestId.
+     *
+     * Note: the request promise will be rejected with an AbortRequestError.
+     * @param requestId - The RequestID of the request to abort.
+     * @param reason - The reason for aborting the request.
+     * @returns True if the request was found and aborted, false otherwise.
+     */
+    abortRequest(requestId, reason) {
+        const pendingRequest = this.getPendingRequestById(requestId);
+        if (!pendingRequest)
+            return false;
+        pendingRequest.abort(reason);
+        return true;
+    }
+    /**
+     * Abort all pending requests.
+     *
+     * Note: each request promise will be rejected with an AbortRequestError.
+     *
+     * @param reason - The reason for aborting the request.
+     */
+    abortAllRequests(reason) {
+        for (const pendingRequest of this.#pendingRequests.values()) {
+            try {
+                pendingRequest.abort(reason);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    /**
+     * Cancel a pending request by its RequestID.
+     *
+     * Tries to cancel the request by sending a cancel request to the server and waiting for the response.
+     * @param id - The RequestID of the request to cancel.
+     * @returns resolves to true if the request was found and canceled, false otherwise.
+     */
+    async cancelRequest(id) {
+        const pendingRequest = this.getPendingRequestById(id);
+        if (!pendingRequest)
+            return false;
+        return await pendingRequest.cancel();
+    }
+    /**
+     * Cancel a pending request by its Promise.
+     *
+     * Tries to cancel the request by sending a cancel request to the server and waiting for the response.
+     * @param id - The RequestID of the request to cancel.
+     * @returns resolves to true if the request was found and canceled, false otherwise.
+     */
+    async cancelPromise(promise) {
+        const request = this.getPendingRequestByPromise(promise);
+        if (!request)
+            return false;
+        return this.cancelRequest(request.id);
+    }
+    /**
+     * Set the default timeout for requests. Requests can override this value.
+     * @param timeoutMs - the timeout in milliseconds
+     */
+    setTimeout(timeoutMs) {
+        this.#defaultTimeoutMs = timeoutMs;
+    }
+    /**
+     * Dispose of the RPC client, aborting all pending requests and closing the port if specified in options.
+     */
+    [Symbol.dispose]() {
+        this.abortAllRequests(new Error('RPC Client disposed'));
+        this.#pendingRequests.clear();
+        if (this.#options.closePortOnDispose) {
+            this.#port.close();
+        }
+        this.#port[Symbol.dispose]();
+    }
+}
+/**
+ * The RPC Client.
+ */
+export class RPCClient extends RPCClientImpl {
+    /**
+     * Create an RPC Client.
+     * @param config - The client configuration.
+     */
+    constructor(config) {
+        super(config);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/rpc/errors.d.ts

@@ -0,0 +1,24 @@
+export declare class RPCRequestError extends Error {
+    constructor(message: string);
+}
+export declare class AbortRPCRequestError extends RPCRequestError {
+    constructor(message: string);
+}
+export declare class TimeoutRPCRequestError extends RPCRequestError {
+    constructor(message: string);
+}
+export declare class UnknownMethodRPCRequestError extends RPCRequestError {
+    method: string;
+    constructor(method: string, message?: string);
+}
+export declare class MalformedRPCRequestError extends RPCRequestError {
+    request?: unknown;
+    constructor(message: string, request?: unknown);
+}
+export declare class CanceledRPCRequestError extends RPCRequestError {
+    constructor(message?: string);
+}
+export declare class AlreadyDisposedError extends Error {
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/rpc/errors.js

@@ -0,0 +1,47 @@
+export class RPCRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RPCRequestError';
+    }
+}
+export class AbortRPCRequestError extends RPCRequestError {
+    constructor(message) {
+        super(message);
+        this.name = 'AbortRPCRequestError';
+    }
+}
+export class TimeoutRPCRequestError extends RPCRequestError {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutRPCRequestError';
+    }
+}
+export class UnknownMethodRPCRequestError extends RPCRequestError {
+    method;
+    constructor(method, message) {
+        super(message || `Unknown method: ${method}`);
+        this.name = 'UnknownMethodRPCRequestError';
+        this.method = method;
+    }
+}
+export class MalformedRPCRequestError extends RPCRequestError {
+    request;
+    constructor(message, request) {
+        super(message);
+        this.name = 'MalformedRPCRequestError';
+        this.request = request;
+    }
+}
+export class CanceledRPCRequestError extends RPCRequestError {
+    constructor(message) {
+        super(message ?? 'The RPC request was canceled');
+        this.name = 'CanceledRPCRequestError';
+    }
+}
+export class AlreadyDisposedError extends Error {
+    constructor() {
+        super('NotifyEmitter has been disposed.');
+        this.name = 'AlreadyDisposedError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/rpc/index.d.ts

@@ -0,0 +1,11 @@
+export type { RPCClientConfiguration, RPCClientOptions } from './client.js';
+export { RPCClient } from './client.js';
+export { AbortRPCRequestError, CanceledRPCRequestError, RPCRequestError, TimeoutRPCRequestError, UnknownMethodRPCRequestError, } from './errors.js';
+export type { MessagePortLike } from './messagePort.js';
+export type { NotifyEvent, NotifyHandler, NotifyOnceEvent } from './notify.js';
+export { NotifyEmitter, notifyEventOnce, notifyEventToPromise } from './notify.js';
+export type { RPCProtocol, RPCProtocolMethods } from './protocol.js';
+export { protocolDefinition, protocolMethods } from './protocol.js';
+export type { RPCServerConfiguration, RPCServerOptions } from './server.js';
+export { RPCServer } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/rpc/index.js

@@ -0,0 +1,6 @@
+export { RPCClient } from './client.js';
+export { AbortRPCRequestError, CanceledRPCRequestError, RPCRequestError, TimeoutRPCRequestError, UnknownMethodRPCRequestError, } from './errors.js';
+export { NotifyEmitter, notifyEventOnce, notifyEventToPromise } from './notify.js';
+export { protocolDefinition, protocolMethods } from './protocol.js';
+export { RPCServer } from './server.js';
+//# sourceMappingURL=index.js.map