@x-oasis/async-call-rpc 0.1.38

package/src/types/messageChannel.ts

@@ -0,0 +1,133 @@
+import { IpcRenderer, UtilityProcess, WebContents } from 'electron';
+import { AbstractChannelProtocolProps as BaseAbstractChannelProtocolProps } from './channel';
+
+export interface ChannelPort {
+  on(event: 'message', listener: (messageEvent: MessageEvent) => void): this;
+  removeListener(
+    event: 'message',
+    listener: (messageEvent: MessageEvent) => void
+  ): this;
+  postMessage(message: any, transfer?: MainPort[]): void;
+}
+
+export type UtilityMessageChannelPortStoreProps = {
+  name: string;
+  port: ParentPort;
+  masterProcessName: string;
+  clientMiddlewares?: ClientMiddleware[];
+  senderMiddlewares?: SenderMiddleware[];
+};
+
+export type OnMessageEntry = {
+  data: any;
+  ports: any;
+};
+export type SenderEntry = any;
+
+export type ClientMiddleware = (
+  channel?: MessageChannelProtocol
+) => (v: OnMessageEntry) => OnMessageEntry;
+
+export type SenderMiddleware = (
+  channel?: MessageChannelProtocol
+) => (data: SenderEntry) => SenderEntry;
+
+/**
+ * Extended AbstractChannelProtocolProps for message channel protocols
+ * Includes additional middleware configuration options
+ */
+export type AbstractChannelProtocolProps = BaseAbstractChannelProtocolProps & {
+  clientMiddlewares?: ClientMiddleware[];
+  senderMiddlewares?: SenderMiddleware[];
+};
+
+export type DeferredMessageChannelProtocolProps =
+  AbstractChannelProtocolProps & {
+    port?: MainPort;
+  };
+
+export type MessageChannelProtocolProps = AbstractChannelProtocolProps & {
+  port?: MainPort;
+};
+
+export type ProcessChannelProtocolProps = {
+  process: UtilityProcess;
+} & AbstractChannelProtocolProps;
+
+export type IPCMainGlobalChannelProtocolProps = AbstractChannelProtocolProps & {
+  channelName: string;
+};
+
+export type IPCMainChannelProtocolProps = {
+  channelName: string;
+  webContents: WebContents;
+} & AbstractChannelProtocolProps;
+
+export type IPCRendererChannelProtocolProps = {
+  channelName: string;
+  ipcRenderer: IpcRenderer;
+  projectName: string;
+} & AbstractChannelProtocolProps;
+
+export interface ParentPort extends NodeJS.EventEmitter {
+  on(event: 'message', listener: (messageEvent: MessageEvent) => void): this;
+  once(event: 'message', listener: (messageEvent: MessageEvent) => void): this;
+  addListener(
+    event: 'message',
+    listener: (messageEvent: MessageEvent) => void
+  ): this;
+  removeListener(
+    event: 'message',
+    listener: (messageEvent: MessageEvent) => void
+  ): this;
+  postMessage(message: any): void;
+}
+
+export type UtilityNodeJSProcess = NodeJS.Process;
+
+export interface MainPort extends NodeJS.EventEmitter {
+  // Docs: https://electronjs.org/docs/api/message-port-main
+
+  /**
+   * Emitted when the remote end of a MessagePortMain object becomes disconnected.
+   */
+  /**
+   * Emitted when a MessagePortMain object receives a message.
+   */
+  on(event: 'close', listener: Function): this;
+  on(event: 'message', listener: (messageEvent: MessageEvent) => void): this;
+  off(event: 'close', listener: Function): this;
+  off(event: 'message', listener: (messageEvent: MessageEvent) => void): this;
+  once(event: 'close', listener: Function): this;
+  once(event: 'message', listener: (messageEvent: MessageEvent) => void): this;
+  addListener(event: 'close', listener: Function): this;
+  addListener(
+    event: 'message',
+    listener: (messageEvent: MessageEvent) => void
+  ): this;
+  removeListener(event: 'close', listener: Function): this;
+  removeListener(
+    event: 'message',
+    listener: (messageEvent: MessageEvent) => void
+  ): this;
+  /**
+   * Disconnects the port, so it is no longer active.
+   */
+  close(): void;
+  /**
+   * Sends a message from the port, and optionally, transfers ownership of objects to
+   * other browsing contexts.
+   */
+  postMessage(message: any, transfer?: MainPort[]): void;
+  /**
+   * Starts the sending of messages queued on the port. Messages will be queued until
+   * this method is called.
+   */
+  start(): void;
+}
+
+export function isUtilityProcess(
+  process: NodeJS.Process
+): process is UtilityNodeJSProcess {
+  return !!(process as UtilityNodeJSProcess).parentPort;
+}

package/src/types/middleware.ts

@@ -0,0 +1,54 @@
+import { Deferred } from '@x-oasis/deferred';
+
+import { HostRequestEntry, RequestEntry } from './rpc';
+
+export type MiddlewareFunction = {
+  (...args: any[]): any;
+  displayName?: string;
+  lifecycle?: SendMiddlewareLifecycle;
+};
+
+export type MessageOutput = {
+  event: any;
+  ports: any;
+};
+
+export type NormalizedRawMessageOutput = MessageOutput & {
+  data: string;
+};
+
+export type DeserializedMessageOutput = MessageOutput & {
+  data: HostRequestEntry | RequestEntry;
+};
+
+export type SenderMiddlewareOutput = {
+  data: any;
+  transfer: any;
+  seqId: number;
+  returnValue: Deferred;
+  isOptionsRequest: boolean;
+  middlewareContext: MiddlewareContext;
+};
+
+export type PendingSendEntry = SenderMiddlewareOutput & {
+  // fnName: string;
+  methodName: string;
+  lifecycle: SendMiddlewareLifecycle;
+  middlewareContext: MiddlewareContext;
+};
+
+export type MiddlewareContext = {
+  isResumed?: boolean;
+  startLifecycle: SendMiddlewareLifecycle;
+  minLifecycle: SendMiddlewareLifecycle;
+  reserved: PendingSendEntry;
+};
+
+export enum SendMiddlewareLifecycle {
+  Initial = 0,
+  Prepare = 10,
+  Transform = 20,
+  DataOperation = 30,
+  Send = 40,
+  Aborted = 100,
+}

package/src/types/proxyChannel.ts

@@ -0,0 +1,3 @@
+export type ProxyChannelProps = {
+  name: string;
+};

package/src/types/proxyService.ts

@@ -0,0 +1,18 @@
+import AbstractChannelProtocol from '../protocol/AbstractChannelProtocol';
+
+// export type IService = {
+//   [key: string]: Function
+// }
+export type IService = any;
+
+export type ServiceHandlerPath = string;
+export type ProxyRPCClientChannel =
+  | AbstractChannelProtocol
+  | { (): AbstractChannelProtocol };
+
+export type ProxyRPCClientProps = {
+  requestPath: string;
+  channel: ProxyRPCClientChannel;
+};
+
+export type ServiceHandlers = Record<string, (...args: any[]) => any>;

package/src/types/rpc.ts

@@ -0,0 +1,61 @@
+export enum RequestType {
+  /**
+   * for normal request, wait for return value
+   */
+  PromiseRequest = 'pr',
+  PromiseAbort = 'pa',
+
+  /**
+   * send a command
+   */
+  SignalRequest = 'sr',
+  SignalAbort = 'sa',
+}
+
+export type RequestRawSequenceId = number;
+
+export type RequestSequenceId = string;
+export type RequestServicePath = string;
+export type RequestFnName = string;
+
+export type RequestEntryHeader = [
+  RequestType,
+  RequestSequenceId,
+  RequestServicePath,
+  RequestFnName
+];
+export type RequestEntryBody = any;
+export type RequestEntry = [RequestEntryHeader, RequestEntryBody];
+
+export enum ResponseType {
+  ReturnSuccess = 'rs',
+  ReturnFail = 'rf',
+
+  PortSuccess = 'ps',
+  PortFail = 'pf',
+}
+export type ResponseEntryHeader = [ResponseType, RequestSequenceId];
+export type ResponseEntryBody = any;
+
+export type HostName = string;
+
+/**
+ * 0 RequestType: PromiseRequest, PromiseAbort, SignalRequest, SignalAbort
+ * 1 RequestSequenceId: string
+ */
+export type HostRequestEntryHeader = [
+  RequestType,
+  RequestSequenceId,
+  RequestServicePath,
+  RequestFnName,
+  HostName
+];
+export type HostRequestEntryBody = any;
+export type HostRequestEntry = [HostRequestEntryHeader, HostRequestEntryBody];
+
+// export type SendingProps = {
+//   requestPath?: string;
+//   fnName?: string;
+//   args?: any;
+//   isOptionsRequest?: boolean;
+// };

package/src/types/rpcProtocol.ts

@@ -0,0 +1,24 @@
+export type IRPCProtocolServer = {
+  source: any;
+  encoder: null;
+  decoder: null;
+  onRequest: () => {};
+  handleRequest: () => {};
+  sendReply: () => {};
+};
+
+export type IRPCProtocolClient = {
+  source: any;
+  encode: () => {};
+  decode: () => {};
+  sendRequest: () => {};
+  onReply: () => {};
+  handleReply: () => {};
+};
+
+export type IRPCProtocol = {
+  encode: Function;
+  decode: Function;
+  onMessage: Function;
+  send: Function;
+};

package/src/utils/constants.ts

@@ -0,0 +1,17 @@
+/**
+ * Constants used for JSONRPC implementation
+ */
+
+export const ERROR = 'Error';
+
+export const isArray = Array.isArray;
+
+export const isObject = (val: unknown): val is object => {
+  return val !== null && typeof val === 'object' && !isArray(val);
+};
+
+export const isFunction = (val: unknown): val is Function => {
+  return typeof val === 'function';
+};
+
+export const UNDEFINED = void 0;

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+/**
+ * JSONRPC utilities and types
+ */
+export * from './jsonrpc';
+export * from './constants';

package/src/utils/jsonrpc.ts

@@ -0,0 +1,242 @@
+import { ID, ErrorResponse } from '../error';
+import { ERROR, isArray, isFunction, isObject, UNDEFINED } from './constants';
+
+/**
+ * JSONRPC version constant
+ */
+export const jsonrpc = '2.0' as const;
+
+/**
+ * JSONRPC Request interface
+ */
+export interface Request {
+  readonly jsonrpc: typeof jsonrpc;
+  readonly id?: ID;
+  readonly method: string;
+  readonly params: readonly unknown[] | object;
+  readonly remoteStack?: string;
+}
+
+/**
+ * JSONRPC Success Response interface
+ */
+export interface SuccessResponse {
+  readonly jsonrpc: typeof jsonrpc;
+  readonly id?: ID;
+  readonly result: unknown;
+  readonly undef?: boolean; // Non-standard extension for undefined values
+}
+
+/**
+ * JSONRPC Response type (success or error)
+ */
+export type Response = SuccessResponse | ErrorResponse<unknown>;
+
+/**
+ * Error map function type for custom error mapping
+ */
+export type ErrorMapFunction<T = unknown> = (
+  error: unknown,
+  request: Request
+) => {
+  code: number;
+  message: string;
+  data?: T;
+};
+
+/**
+ * AsyncCall error detail structure
+ */
+export interface AsyncCallErrorDetail {
+  readonly stack?: string;
+  readonly type?: string;
+}
+
+/**
+ * Create a JSONRPC request object
+ */
+export const makeRequest = (
+  id: ID,
+  method: string,
+  params: readonly unknown[] | object,
+  remoteStack?: string
+): Request => {
+  const x: Request = { jsonrpc, id, method, params, remoteStack };
+  deleteUndefined(x, 'id');
+  deleteFalsy(x, 'remoteStack');
+  return x;
+};
+
+/**
+ * Create a JSONRPC success response object
+ */
+export const makeSuccessResponse = (
+  id: ID,
+  result: unknown
+): SuccessResponse => {
+  const x: SuccessResponse = { jsonrpc, id, result };
+  deleteUndefined(x, 'id');
+  return x;
+};
+
+/**
+ * Create a JSONRPC error response object
+ * Pre-defined errors from JSONRPC 2.0 specification section 5.1
+ */
+export const makeErrorResponse = <T>(
+  id: ID,
+  code: number,
+  message: string,
+  data?: T
+): ErrorResponse<T> => {
+  if (id === UNDEFINED) id = null;
+  code = Math.floor(code);
+  if (Number.isNaN(code)) code = -1;
+  const x: ErrorResponse<T> = {
+    jsonrpc,
+    id,
+    error: { code, message, data },
+  };
+  deleteUndefined(x.error, 'data');
+  return x;
+};
+
+/**
+ * Parse error response (-32700)
+ * Pre-defined error in JSONRPC 2.0 specification section 5.1
+ */
+export const ErrorResponseParseError = <T>(
+  e: unknown,
+  mapper: ErrorMapFunction<T>
+): ErrorResponse<T> => {
+  const obj = ErrorResponseMapped({} as any, e, mapper);
+  const o = obj.error as Mutable<ErrorResponse['error']>;
+  o.code = -32700;
+  o.message = 'Parse error';
+  return obj;
+};
+
+/**
+ * Invalid Request error response (-32600)
+ * Pre-defined error in JSONRPC 2.0 specification section 5.1
+ */
+export const ErrorResponseInvalidRequest = (id: ID): ErrorResponse => {
+  return makeErrorResponse(id, -32600, 'Invalid Request');
+};
+
+/**
+ * Method not found error response (-32601)
+ * Pre-defined error in JSONRPC 2.0 specification section 5.1
+ */
+export const ErrorResponseMethodNotFound = (id: ID): ErrorResponse => {
+  return makeErrorResponse(id, -32601, 'Method not found');
+};
+
+/**
+ * Invalid params error response (-32602)
+ * Pre-defined error in JSONRPC 2.0 specification section 5.1
+ */
+export const ErrorResponseInvalidParams = (id: ID): ErrorResponse => {
+  return makeErrorResponse(id, -32602, 'Invalid params');
+};
+
+/**
+ * Internal error response (-32603)
+ * Pre-defined error in JSONRPC 2.0 specification section 5.1
+ */
+export const ErrorResponseInternalError = (id: ID): ErrorResponse => {
+  return makeErrorResponse(id, -32603, 'Internal error');
+};
+
+/**
+ * Map an error to a JSONRPC error response using a custom mapper
+ */
+export const ErrorResponseMapped = <T>(
+  request: Request,
+  e: unknown,
+  mapper: ErrorMapFunction<T>
+): ErrorResponse<T> => {
+  const { id } = request;
+  const { code, message, data } = mapper(e, request);
+  return makeErrorResponse(id, code, message, data);
+};
+
+/**
+ * Default error mapper that extracts error information
+ */
+export const defaultErrorMapper =
+  (stack = '', code = -1): ErrorMapFunction<AsyncCallErrorDetail> =>
+  (e) => {
+    let message = toString('', () => (e as any).message);
+    let type = toString(
+      ERROR,
+      (ctor = (e as any).constructor) => isFunction(ctor) && ctor.name
+    );
+
+    // Check for DOMException
+    const E = globalThis.DOMException;
+    if (E && e instanceof E) {
+      type = `DOMException:${e.name}`;
+    }
+
+    const eType = typeof e;
+    if (
+      eType === 'string' ||
+      eType === 'number' ||
+      eType === 'boolean' ||
+      eType === 'bigint'
+    ) {
+      type = ERROR;
+      message = String(e);
+    }
+
+    const data: AsyncCallErrorDetail = stack ? { stack, type } : { type };
+    return { code, message, data };
+  };
+
+/**
+ * Check if an object is a valid JSONRPC request or response
+ */
+export const isJSONRPCObject = (data: any): data is Response | Request => {
+  if (!isObject(data)) return false;
+  if (!('jsonrpc' in data)) return false;
+  const obj = data as { jsonrpc?: string; params?: unknown };
+  if (obj.jsonrpc !== jsonrpc) return false;
+  if ('params' in obj) {
+    const params = obj.params;
+    if (!isArray(params) && !isObject(params)) return false;
+  }
+  return true;
+};
+
+/**
+ * Helper function to safely convert value to string
+ */
+const toString = (_default: string, val: () => any): string => {
+  try {
+    const v = val();
+    if (v === UNDEFINED) return _default;
+    return String(v);
+  } catch {
+    return _default;
+  }
+};
+
+/**
+ * Delete undefined property from object
+ */
+const deleteUndefined = <O>(x: O, key: keyof O): void => {
+  if (x[key] === UNDEFINED) delete x[key];
+};
+
+/**
+ * Delete falsy property from object
+ */
+const deleteFalsy = <T>(x: T, key: keyof T): void => {
+  if (!x[key]) delete x[key];
+};
+
+/**
+ * Make a type mutable
+ */
+type Mutable<T> = { -readonly [key in keyof T]: T[key] };