@alius/rpc/index.d.ts

JSON-RPC 2.0 implementation configured with OpenRPC

/**
 * JSON-RPC 2.0 provider.
 * OpenRPC is used to provide API configuration.
 */
export class RPC {
  /**
   * Creates new RPC provider instance with specified config and handlers.
   * <b>{@link RPC#init await init()} has to be executed to finish asynchronous initalization
   * of this object.</b>
   * <p>Every method specified in config must have corresponding handler.</p>
   *
   * @param {OpenRPC} [config="./empty.openrpc.json"] - API config
   * @param {Object<string, Function>} [handlers={}] - handlers for methods
   * @param {RPCOptionsType} [options={}] - additional options
   */
  constructor(config?: OpenRPC, handlers?: {
    [x: string]: Function;
  }, options?: RPCOptionsType);
  /**
   * true when object initialization is complete.
   *
   * @type {boolean}
   * @readonly
   */
  get initialized(): boolean;
  /**
   * JSON validator.
   *
   * @type {Ajv}
   * @readonly
   */
  get ajv(): Ajv;
  /**
   * JSON request object being processed.
   * <strong>Accessing this property must be done in current task of JS event loop.</strong>
   *
   * @type {JSONRPCRequest}
   * @readonly
   */
  get json(): JSONRPCRequest
  /**
   * Initialized asynchronous part of this object.
   */
  init(): Promise<RPC>;
  /**
   * Configures this RPC provider with new configuration.
   *
   * @param {OpenRPC} config - API config
   * @param {Object<string, Function>} [handlers={}] - handlers for methods
   * @param {RPCOptionsType} [options={}] - additional options
   */
  configure(config: OpenRPC, handlers?: {
    [x: string]: Function;
  }, options?: RPCOptionsType): Promise<void>;
  /**
   * Handler for 'rpc.discover' method.
   *
   * @returns {OpenRPC} current API configuration
   */
  serviceDiscover(): OpenRPC
  /**
   * Adds new method to API.
   * If method with such name already exists - replaces it with provided config and handler.
   *
   * @param {OpenRPCMethod} config - method configuration
   * @param {function} handler - method handler
   */
  putMethod(config: OpenRPCMethod, handler: Function): Promise<void>;
  /**
   * Removes named method from API.
   * If there is no method with provided name - silently returns.
   *
   * @param {string} name - method name to remove
   */
  removeMethod(name: string): void;
  /**
   * Returns method config.
   * Returns <code>undefined</code> if method with such name is not found.
   *
   * @param {string} name - method name
   * @returns {OpenRPCMethod|undefined} method config
   */
  getMethodConfig(name: string): OpenRPCMethod | undefined;
  /**
   * Executes single JSON-RPC request or batch of requests.
   * Execution order:<ul>
   * <li>parses request if string passed</li>
   * <li>if single request is passed - executes it with {@link RPC#executeSingle executeSingle} and returns response</li>
   * <li>if empty batch is passed - returns invalid request error (-32600)</li>
   * <li>executes all requests with {@link RPC#executeSingle executeSingle()} and collects responses</li>
   * <li>if there are no responses (batch contains notifications only) - returns</li>
   * <li>returns responses</li>
   * </ul>
   *
   * @param {(Array<JSONRPCRequest>|JSONRPCRequest|string)} json - JSON-RPC request as object or encoded in JSON string
   * @param {object} [options] - processing options
   * @param {Array<PreProcessorFunction>} [options.preProcessors] - list of additional pre-processor functions
   *      will be executed before configured pre-processors
   * @param {boolean} [options.skipPreProcessors=false] - skips configured pre-processors if true
   * @param {Array<PostProcessorFunction>} [options.postProcessors] - list of additional post-processor functions
   *      will be executed after configured post-processors
   * @param {boolean} [options.skipPostProcessors=false] - skips configured post-processors if true
   * @returns {Promise<JSONRPCResult|JSONRPCError|Array<JSONRPCResult|JSONRPCError>|undefined>} response object or undefined (for notifications)
   */
  execute(json: (Array<JSONRPCRequest> | JSONRPCRequest | string), options?: {
    preProcessors?: Array<PreProcessorFunction>;
    skipPreProcessors?: boolean;
    postProcessors?: Array<PostProcessorFunction>;
    skipPostProcessors?: boolean;
  }): Promise<JSONRPCResult | JSONRPCError | Array<JSONRPCResult | JSONRPCError> | undefined>;
  /**
   * Executes single JSON-RPC request.
   * Execution order:<ul>
   * <li>parses request if string passed</li>
   * <li>validates request</li>
   * <li>tests if API has handler for requested method</li>
   * <li>executes additional pre-processors</li>
   * <li>executes configured pre-processors</li>
   * <li>matches params by name if passed as object - excesive parameters are discarded</li>
   * <li>validates params - excesive parameters are discarded</li>
   * <li>tests if values are provided for all params marked required</li>
   * <li>executes handler with provided parameters</li>
   * <li>validates response (on validation failure - changes response to error (-32030)
   * with original response saved in 'data' property)</li>
   * <li>executes configured post-processors</li>
   * <li>executes additional post-processors</li>
   * <li>on successful execution<ul>
   * <li>returns if request was notification</li>
   * <li>tries to stringify result to JSON to make sure that valid JSON can be produced
   * (on failure to stringify - returns stringify error (-32000) with stringify error
   * saved in 'data' property)</li>
   * <li>returns result response</li>
   * </ul></li>
   * <li>on execution failure<ul>
   * <li>if error code id thrown - tries to find error object among defined errors by code;
   * returns error object if found</li>
   * <li>if error object thrown - tries to find error object among defined errors by err.code;
   * if found - replaces 'message' and 'data' default property values with provided (if provided)
   * and returns resulting error object</li>
   * <li>if predefined error can not be found - returns method execution error (-32020) object
   * with original error serialized in 'data' property.</li>
   * </ul></li>
   * </ul>
   * <p>If parameter <code>json</code> value is object (not string) - it can be modified
   * by pre/post-processors. General rule - do not reuse request objects.
   * If you decide to reuse request object - take necessary precautions to prevent unpredictable results.</p>
   *
   * @param {(JSONRPCRequest|string)} json - JSON-RPC request as object or encoded in JSON string
   * @param {object} [options] - processing options
   * @param {Array<PreProcessorFunction>} [options.preProcessors] - list of additional pre-processor functions
   *      will be executed before configured pre-processors
   * @param {boolean} [options.skipPreProcessors=false] - skips configured pre-processors if true
   * @param {Array<PostProcessorFunction>} [options.postProcessors] - list of additional post-processor functions
   *      will be executed after configured post-processors
   * @param {boolean} [options.skipPostProcessors=false] - skips configured post-processors if true
   * @returns {Promise<JSONRPCResult|JSONRPCError|undefined>} response object or undefined (for notifications)
   */
  executeSingle(json: (JSONRPCRequest | string), options?: {
    preProcessors?: Array<PreProcessorFunction>;
    skipPreProcessors?: boolean;
    postProcessors?: Array<PostProcessorFunction>;
    skipPostProcessors?: boolean;
  }): Promise<JSONRPCResult | JSONRPCError | undefined>;
  /**
   * Creates JSON-RPC request object.
   *
   * @param {(null|string|number)} id - request id
   * @param {string} method - method name to execute
   * @param {(Object<string, *>|Array<*>)} [params] - list of parameter values to pass to method
   * @returns {JSONRPCRequest} created JSON-RPC request object
   */
  static request(id: (null | string | number), method: string, params?: ({
    [x: string]: any;
  } | Array<any>)): JSONRPCRequest;
  /**
   * Creates JSON-RPC notification object.
   *
   * @param {string} method - method name to execute
   * @param {(Object<string, *>|Array<*>)} [params] - list of parameter values to pass to method
   * @returns {JSONRPCRequest} created JSON-RPC notification object
   */
  static notification(method: string, params?: ({
    [x: string]: any;
  } | Array<any>)): JSONRPCRequest;
  /**
   * Creates JSON-RPC error response object.
   * Passing <code>id</code> value <code>undefined</code> results in returning <code>undefined</code> value.
   * According to specification if <code>id</code> is undefined - server MUST NOT respond.
   *
   * @param {JSONRPCErrorObject} error - execution error to report
   * @param {(null|string|number)} [id] - response id
   * @returns {(JSONRPCError|undefined)} JSON-RPC error response object or
   *      undefined if id parameter value is undefined
   */
  static errorResponse(error: JSONRPCErrorObject, id?: (null | string | number)): (JSONRPCError | undefined);
  /**
   * Throws TypeError if provided test is false.
   *
   * @param {boolean} test - test value
   * @param {string} [message] - error message
   * @throws {TypeError} when test is false
   */
  static assert(test: boolean, message?: string): void;
  /**
   * JSON-RPC version.
   *
   * @type {string}
   * @readonly
   */
  static get VERSION(): string;
  /**
   * Member name for specifying JSON-RPC version.
   * Used in request and response objects.
   *
   * @type {string}
   * @readonly
   */
  static get JSONRPC(): string;
  /**
   * Member name for specifying identifier established by client.
   * Used in request and response objects.
   *
   * @type {string}
   * @readonly
   */
  static get ID(): string;
  /**
   * Member name for specifying method name to be invoked.
   * Used in request objects.
   *
   * @type {string}
   * @readonly
   */
  static get METHOD(): string;
  /**
   * Member name for specifying parameter values to be used during the invocation of the method.
   * Used in request objects.
   *
   * @type {string}
   * @readonly
   */
  static get PARAMS(): string;
  /**
   * Member name for specifying result of the successful method invocation.
   * Used in response objects.
   *
   * @type {string}
   * @readonly
   */
  static get RESULT(): string;
  /**
   * Member name for specifying error of the method invocation.
   * Used in response objects.
   *
   * @type {string}
   * @readonly
   */
  static get ERROR(): string;
  /**
   * Member name for specifying error code in error object.
   * Used in response error objects.
   *
   * @type {string}
   * @readonly
   */
  static get ERROR_CODE(): string;
  /**
   * Member name for specifying error message in error object.
   * Used in response error objects.
   *
   * @type {string}
   * @readonly
   */
  static get ERROR_MESSAGE(): string;
  /**
   * Member name for specifying error additional data in error object.
   * Used in response error objects.
   *
   * @type {string}
   * @readonly
   */
  static get ERROR_DATA(): string;
  /**
   * Finds corresponding JSONRPCErrorObject among implementation defined and
   * among additional errors (if provided).
   * If 'err' is number - tests err against JSONRPCErrorObject.code.
   * If 'err' is object - tests err.code against JSONRPCErrorObject.code.
   * If error is found and 'err' is object - resulting error object is updated
   * with 'err.message' and 'err.data' values (if exists).
   * If error is not found and default is provided - returns default error
   * with 'data' property containing serialized original error.
   * If error is not found and there is no default provided - returns undefined.
   *
   * @param {number|object|Error} err - error to look for
   * @param {JSONRPCErrorObject|OpenRPCError} [defaultError] - error response to return if not found
   * @param {Array<JSONRPCErrorObject|OpenRPCError>} [errors] - additional list of errors to look
   * @returns {JSONRPCErrorObject|undefined} error response object or undefined if not found
   */
  static findError(err: number | object | Error, defaultError?: JSONRPCErrorObject | OpenRPCError, errors?: Array<JSONRPCErrorObject | OpenRPCError>): JSONRPCErrorObject | undefined;
  /**
   * JSON stringify error.
   * Reported when response can not be stringified to JSON
   * (usualy due circular references).
   * Non-standard.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32000(): JSONRPCErrorObject;
  /**
   * Pre-processor execution error.
   * Reported when pre-processor throws unknown error.
   * Non-standard.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32010(): JSONRPCErrorObject;
  /**
   * Method execution error.
   * Reported when method execution throws error.
   * Non-standard.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32020(): JSONRPCErrorObject;
  /**
   * Invalid result error.
   * Reported when method produces invalid result.
   * Non-standard.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32030(): JSONRPCErrorObject;
  /**
   * General security error.
   * Non-standard.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32040(): JSONRPCErrorObject;
  /**
   * Credentials expired error.
   * Non-standard.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32041(): JSONRPCErrorObject;
  /**
   * Post-processor execution error.
   * Reported when post-processor throws unknown error.
   * Non-standard.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32050(): JSONRPCErrorObject;
  /**
   * Invalid request error.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32600(): JSONRPCErrorObject;
  /**
   * Method not found error.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32601(): JSONRPCErrorObject;
  /**
   * Invalid params error.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32602(): JSONRPCErrorObject;
  /**
   * Internal error.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32603(): JSONRPCErrorObject;
  /**
   * JSON parse error.
   *
   * @type {JSONRPCErrorObject}
   * @readonly
   */
  static get ERROR_32700(): JSONRPCErrorObject;
  /**
   * List of error objects defined in specs.
   *
   * @type {Array<JSONRPCErrorObject>}
   * @readonly
   */
  static get SPEC_ERRORS(): JSONRPCErrorObject[];
  /**
   * List of all error objects defined in this implementation
   * (including spec errors).
   *
   * @type {Array<JSONRPCErrorObject>}
   * @readonly
   */
  static get IMPL_ERRORS(): JSONRPCErrorObject[];
  /**
   * Service discovery method name as specified in OpenRPC.
   *
   * @type {string}
   * @readonly
   */
  static get RPC_DISCOVER(): string;
  /**
   * Service discovery method schema as specified in OpenRPC.
   *
   * @type {OpenRPC}
   * @readonly
   */
  static get RPC_DISCOVER_SCHEMA(): OpenRPC;
}
export type RPCOptionsType = {
  /**
   * list of functions executed before handler execution
   */
  preProcessors?: Array<PreProcessorFunction>;
  /**
   * list of functions executed before handler execution
   */
  postProcessors?: Array<PostProcessorFunction>;
};
/**
 * Pre-processor funtion definition.
 *
 * @typedef PreProcessorFunction
 * @type {function}
 * @param {JSONRPCRequest} request
 * @param {RPC} rpc - reference to RPC handler
 * @throws {number|object|Error} stops request processing and
 *      returns error response.
 */
export type PreProcessorFunction = (request: JSONRPCRequest, rpc: RPC) => any;
/**
 * Post-processor funtion definition.
 *
 * @typedef PostProcessorFunction
 * @type {function}
 * @param {JSONRPCRequest} request
 * @param {JSONRPCResult} result
 * @param {RPC} rpc - reference to RPC handler
 * @throws {number|object|Error} returns specified error response instead.
 */
export type PostProcessorFunction = (request: JSONRPCRequest, result: JSONRPCResult, rpc: RPC) => any;
/**
 * JSON-RPC request object structure.
 *
 * @typedef JSONRPCRequest
 * @type {object}
 * @property {"2.0"} jsonrpc - JSON-RPC version always exact string "2.0"
 * @property {null|string|number} [id] - request id
 * @property {string} method - method to execute
 * @property {(Object<string, *>|Array)} params - parameters for method
 */
export type JSONRPCRequest = {
  /**
   * JSON-RPC version always exact string "2.0"
   */
  jsonrpc: "2.0";
  /**
   * request id
   */
  id?: null | string | number;
  /**
   * method to execute
   */
  method: string;
  /**
   * parameters for method
   */
  params?: ({
    [x: string]: any;
  } | any[]);
};
/**
 * JSON-RPC error object structure.
 *
 * @typedef JSONRPCErrorObject
 * @type {object}
 * @property {number} code - error code
 * @property {string} message - error message
 * @property {*} [data] - additional error data
 */
export type JSONRPCErrorObject = {
  /**
   * error code
   */
  code: number;
  /**
   * error message
   */
  message: string;
  /**
   * additional error data
   */
  data?: any;
};
/**
 * JSON-RPC error response object structure.
 *
 * @typedef JSONRPCError
 * @type {object}
 * @property {"2.0"} jsonrpc - JSON-RPC version always exact string "2.0"
 * @property {null|string|number} id - request id
 * @property {JSONRPCErrorObject} error - error object
 */
export type JSONRPCError = {
  /**
   * JSON-RPC version always exact string "2.0"
   */
  jsonrpc: "2.0";
  /**
   * request id
   */
  id: null | string | number;
  /**
   * error object
   */
  error: JSONRPCErrorObject;
};
/**
* JSON-RPC result object response structure.
*
* @typedef JSONRPCResult
* @type {object}
* @property {"2.0"} jsonrpc - JSON-RPC version always exact string "2.0"
* @property {null|string|number} id - request id
* @property {*} result - result object
*/
export type JSONRPCResult = {
  /**
   * JSON-RPC version always exact string "2.0"
   */
  jsonrpc: "2.0";
  /**
   * request id
   */
  id: null | string | number;
  /**
   * result object
   */
  result: any;
};
/**
 * OpenRPC object structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPC
 * @type {object}
 * @property {string} openrpc - OpenRPC semantic version number
 * @property {OpenRPCInfo} info - API metadata
 * @property {Array<OpenRPCServer>} [servers] - array of object providing information on connectivity to target server
 * @property {Array<(OpenRPCMethod|OpenRPCReference)>} methods - list of methods available in API
 * @property {Array<OpenRPCComponents>} [components] - holds various schemas for specification
 * @property {OpenRPCExternalDoc} [externalDocs] - additional external documentation
 */
export type OpenRPC = {
  /**
   * OpenRPC semantic version number
   */
  openrpc: string;
  /**
   * API metadata
   */
  info: OpenRPCInfo;
  /**
   * array of object providing information on connectivity to target server
   */
  servers?: Array<OpenRPCServer>;
  /**
   * list of methods available in API
   */
  methods: Array<(OpenRPCMethod | OpenRPCReference)>;
  /**
   * holds various schemas for specification
   */
  components?: Array<OpenRPCComponents>;
  /**
   * additional external documentation
   */
  externalDocs?: OpenRPCExternalDoc;
};
/**
 * OpenRPC Info structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCInfo
 * @type {object}
 * @property {string} title - application title
 * @property {string} [description] - verbose application description
 * @property {string} [termsOfService] - URL to terms of service for API
 * @property {OpenRPCContact} [contact] - contact information for exposed API
 * @property {OpenRPCLicense} [license] - license information for exposed API
 * @property {string} version - API version
 */
export type OpenRPCInfo = {
  /**
   * application title
   */
  title: string;
  /**
   * verbose application description
   */
  description?: string;
  /**
   * URL to terms of service for API
   */
  termsOfService?: string;
  /**
   * contact information for exposed API
   */
  contact?: OpenRPCContact;
  /**
   * license information for exposed API
   */
  license?: OpenRPCLicense;
  /**
   * API version
   */
  version: string;
};
/**
 * OpenRPC Contact structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCContact
 * @type {object}
 * @property {string} [name] - name of contact person/organization
 * @property {string} [url] - URL to contact information
 * @property {string} [email] - email of contact person/organization
 */
export type OpenRPCContact = {
  /**
   * name of contact person/organization
   */
  name?: string;
  /**
   * URL to contact information
   */
  url?: string;
  /**
   * email of contact person/organization
   */
  email?: string;
};
/**
 * OpenRPC License structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCLicense
 * @type {object}
 * @property {string} name - license name used for API
 * @property {string} [url] - URL to license
 */
export type OpenRPCLicense = {
  /**
   * license name used for API
   */
  name: string;
  /**
   * URL to license
   */
  url?: string;
};
/**
 * OpenRPC Server structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCServer
 * @type {object}
 * @property {string} name - cannonical name for the server
 * @property {string} url - URL to the target host
 * @property {string} [summary] - short summary for what server is
 * @property {string} [description] - description of host designated by url
 * @property {Object<string, OpenRPCServerVariable>} [variables] - map of variables
 */
export type OpenRPCServer = {
  /**
   * cannonical name for the server
   */
  name: string;
  /**
   * URL to the target host
   */
  url: string;
  /**
   * short summary for what server is
   */
  summary?: string;
  /**
   * description of host designated by url
   */
  description?: string;
  /**
   * map of variables
   */
  variables?: {
    [x: string]: OpenRPCServerVariable;
  };
};
/**
 * OpenRPC Server variable structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCServerVariable
 * @type {object}
 * @property {Array<string>} [enum] - enumeration of string values to be used if the substitution options are from a limited set
 * @property {string} default - default value to use for substitution, which SHALL be sent if an alternate value is not supplied
 * @property {string} [description] - Description of server variable
 */
export type OpenRPCServerVariable = {
  /**
   * enumeration of string values to be used if the substitution options are from a limited set
   */
  enum?: Array<string>;
  /**
   * default value to use for substitution, which SHALL be sent if an alternate value is not supplied
   */
  default: string;
  /**
   * Description of server variable
   */
  description?: string;
};
/**
 * OpenRPC Method structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCMethod
 * @type {object}
 * @property {string} name - method name
 * @property {Array<OpenRPCTag|OpenRPCReference>} [tags] - list of tags
 * @property {string} [summary] - short summary for what method does
 * @property {string} [description] - verbose explanation of the method behavior
 * @property {OpenRPCExternalDoc} [externalDocs] - additional external documentation
 * @property {Array<(OpenRPCContentDescriptor|OpenRPCReference)>} params - list of parameters for method
 * @property {(OpenRPCContentDescriptor|OpenRPCReference)} result - result returned by method
 * @property {boolean} [deprecated] - declares this method deprecated
 * @property {Array<OpenRPCServer>} [servers] - alternative servers to service this method
 * @property {Array<(OpenRPCError|OpenRPCReference)>} [errors] - list of custom application defined errors
 * @property {Array<(OpenRPCLink|OpenRPCReference)>} [links] - list of possible links from this method call
 * @property {("by-name"|"by-position"|"either")} [paramStructure] - expected format of paramters. Defaults to "by-position".
 * @property {Array<OpenRPCExamplePairing>} [examples] - list of examples
 */
export type OpenRPCMethod = {
  /**
   * method name
   */
  name: string;
  /**
   * list of tags
   */
  tags?: Array<OpenRPCTag | OpenRPCReference>;
  /**
   * short summary for what method does
   */
  summary?: string;
  /**
   * verbose explanation of the method behavior
   */
  description?: string;
  /**
   * additional external documentation
   */
  externalDocs?: OpenRPCExternalDoc;
  /**
   * list of parameters for method
   */
  params: Array<(OpenRPCContentDescriptor | OpenRPCReference)>;
  /**
   * result returned by method
   */
  result: (OpenRPCContentDescriptor | OpenRPCReference);
  /**
   * declares this method deprecated
   */
  deprecated?: boolean;
  /**
   * alternative servers to service this method
   */
  servers?: Array<OpenRPCServer>;
  /**
   * list of custom application defined errors
   */
  errors?: Array<(OpenRPCError | OpenRPCReference)>;
  /**
   * list of possible links from this method call
   */
  links?: Array<(OpenRPCLink | OpenRPCReference)>;
  /**
   * expected format of paramters. Defaults to "by-position".
   */
  paramStructure?: ("by-name" | "by-position" | "either");
  /**
   * list of examples
   */
  examples?: Array<OpenRPCExamplePairing>;
};
/**
 * OpenRPC Content Descriptor structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCContentDescriptor
 * @type {object}
 * @property {string} name - name of content being described
 * @property {string} [summary] - short summary of content being described
 * @property {string} [description] - verbose explanation of content descriptor behavior
 * @property {boolean} [required] - determines if content is required field. Defaults to false
 * @property {object} schema - schema that describes content
 * @property {boolean} [deprecated] - specifies that content is deprecated. Defaults to false
 */
export type OpenRPCContentDescriptor = {
  /**
   * name of content being described
   */
  name: string;
  /**
   * short summary of content being described
   */
  summary?: string;
  /**
   * verbose explanation of content descriptor behavior
   */
  description?: string;
  /**
   * determines if content is required field. Defaults to false
   */
  required?: boolean;
  /**
   * schema that describes content
   */
  schema: object;
  /**
   * specifies that content is deprecated. Defaults to false
   */
  deprecated?: boolean;
};
/**
 * OpenRPC Example Pairing structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCExamplePairing
 * @type {object}
 * @property {string} [name] - name for example pairing
 * @property {string} [summary] - short description for example pairing
 * @property {string} [description] - verbose explanation of example pairing
 * @property {Array<(OpenRPCExample|OpenRPCReference)>} [params] - example parameters
 * @property {(OpenRPCExample|OpenRPCReference)} [result] - example result
 */
export type OpenRPCExamplePairing = {
  /**
   * name for example pairing
   */
  name?: string;
  /**
   * short description for example pairing
   */
  summary?: string;
  /**
   * verbose explanation of example pairing
   */
  description?: string;
  /**
   * example parameters
   */
  params?: Array<(OpenRPCExample | OpenRPCReference)>;
  /**
   * example result
   */
  result?: (OpenRPCExample | OpenRPCReference);
};
/**
 * OpenRPC Example structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCExample
 * @type {object}
 * @property {string} [name] - canonical example name
 * @property {string} [summary] - short description for example
 * @property {string} [description] - verbose explanation of example
 * @property {*} [value] - embeded literal example
 * @property {string} [externalValue] - URL to literal example which can not easily be included in JSON
 */
export type OpenRPCExample = {
  /**
   * canonical example name
   */
  name?: string;
  /**
   * short description for example
   */
  summary?: string;
  /**
   * verbose explanation of example
   */
  description?: string;
  /**
   * embeded literal example
   */
  value?: any;
  /**
   * URL to literal example which can not easily be included in JSON
   */
  externalValue?: string;
};
/**
 * OpenRPC Link structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCLink
 * @type {object}
 * @property {string} name - canonical link name
 * @property {string} [summary] - short description for link
 * @property {string} [description] - full description for link
 * @property {string} [method] - name of existing, resolvable OpenRPC method
 * @property {Object<string, *>} [params] - params to pass to method
 * @property {OpenRPCServer} [server] - server to be used by target method
 */
export type OpenRPCLink = {
  /**
   * canonical link name
   */
  name: string;
  /**
   * short description for link
   */
  summary?: string;
  /**
   * full description for link
   */
  description?: string;
  /**
   * name of existing, resolvable OpenRPC method
   */
  method?: string;
  /**
   * params to pass to method
   */
  params?: {
    [x: string]: any;
  };
  /**
   * server to be used by target method
   */
  server?: OpenRPCServer;
};
/**
 * OpenRPC Error structure.
 *
 * @typedef OpenRPCError
 * @type {object}
 * @property {number} code - error code
 * @property {string} message - short error description
 * @property {*} [data] - additional information about error
 */
export type OpenRPCError = {
  /**
   * error code
   */
  code: number;
  /**
   * short error description
   */
  message: string;
  /**
   * additional information about error
   */
  data?: any;
};
/**
 * OpenRPC Components structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCComponents
 * @type {object}
 * @property {Object<string, OpenRPCContentDescriptor>} [contentDescriptors] - reusable content descriptors
 * @property {Object<string, object>} [schemas] - reusable schemas
 * @property {Object<string, OpenRPCExample>} [examples] - reusable examples
 * @property {Object<string, OpenRPCLink>} [links] - reusable links
 * @property {Object<string, OpenRPCError>} [errors] - reusable errors
 * @property {Object<string, OpenRPCExamplePairing>} [examplePairingObjects] - reusable example pairings
 * @property {Object<string, OpenRPCTag>} [tags] - reusable tags
 */
export type OpenRPCComponents = {
  /**
   * reusable content descriptors
   */
  contentDescriptors?: {
    [x: string]: OpenRPCContentDescriptor;
  };
  /**
   * reusable schemas
   */
  schemas?: {
    [x: string]: object;
  };
  /**
   * reusable examples
   */
  examples?: {
    [x: string]: OpenRPCExample;
  };
  /**
   * reusable links
   */
  links?: {
    [x: string]: OpenRPCLink;
  };
  /**
   * reusable errors
   */
  errors?: {
    [x: string]: OpenRPCError;
  };
  /**
   * reusable example pairings
   */
  examplePairingObjects?: {
    [x: string]: OpenRPCExamplePairing;
  };
  /**
   * reusable tags
   */
  tags?: {
    [x: string]: OpenRPCTag;
  };
};
/**
 * OpenRPC Tag structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCTag
 * @type {object}
 * @property {string} name - tag name
 * @property {string} [summary] - short summary for tag
 * @property {string} [description] - verbose tag explanation
 * @property {OpenRPCExternalDoc} [externalDocs] - additional external documentation
 */
export type OpenRPCTag = {
  /**
   * tag name
   */
  name: string;
  /**
   * short summary for tag
   */
  summary?: string;
  /**
   * verbose tag explanation
   */
  description?: string;
  /**
   * additional external documentation
   */
  externalDocs?: OpenRPCExternalDoc;
};

/**
 * OpenRPC External Document structure.
 * This object MAY be extended with Specification Extensions.
 *
 * @typedef OpenRPCExternalDoc
 * @type {object}
 * @property {string} [description] - document description
 * @property {string} url - target document url
 */
export type OpenRPCExternalDoc = {
  /**
   * document description
   */
  description?: string;
  /**
   * target document url
   */
  url: string;
};

/**
 * OpenRPC Reference structure.
 *
 * @typedef OpenRPCReference
 * @type {object}
 * @property {string} $ref - reference string
 */
export type OpenRPCReference = {
  /**
   * reference string
   */
  $ref: string;
};
/**
 * OpenRPC Specification Extensions structure.
 * The extensions properties are implemented as patterned fields
 * that are always prefixed by "x-".
 */
export type OpenRPCSpecificationExtensions = {};
/**
 * RPC Exception.
 * Class contains additional properties: code and data
 *
 * @extends Exception
 */
export class RPCException extends Exception {
  /**
   * Creates new RPC Exception instance with code, message and possible cause and data.
   * If provided code is not number then code -32603 (Internal error) is assigned.
   *
   * @param {number} [code=-32603] - error code
   * @param {string} [message="RPCError"] - message decribing exception
   * @param {Error|*} [cause=null] - initial cause for this error
   * @param {*} [data=null] - additional error data
   */
  constructor(code?: number, message?: string, cause?: Error | any, data?: any);
  /**
   * Returns error code.
   *
   * @type {number}
   * @readonly
   */
  get code(): number;
  /**
   * Returns additional error data.
   *
   * @type {*}
   * @readonly
   */
  get data(): any;
  /**
   * Returns object with serialized exception fields for JSON serialization
   * according to RPC specification.
   * Will have following properties:<ul>
   * <li>code - error code</li>
   * <li>message - error message</li>
   * <li>data - either data passed to constructor or
   * serialized this error without code and message properties</li>
   * </ul>
   *
   * @returns {JSONRPCErrorObject}
   */
  toJSON(): JSONRPCErrorObject;
}
/**
 * Invalid request (code: -32600).
 *
 * @extends RPCException
 */
export class InvalidRequestException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Method not found (code: -32601).
 *
 * @extends RPCException
 */
export class MethodNotFoundException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Invalid params (code: -32602).
 *
 * @extends RPCException
 */
export class InvalidParamsException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Internal error (code: -32603).
 *
 * @extends RPCException
 */
export class InternalException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Parse error (code: -32700).
 *
 * @extends RPCException
 */
export class ParseException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Stringify error (code: -32000).
 *
 * @extends RPCException
 */
export class StringifyException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Pre-processor execution error (code: -32010).
 *
 * @extends RPCException
 */
export class PreProcessorExecutionException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Method execution error (code: -32020).
 *
 * @extends RPCException
 */
export class MethodExecutionException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Invalid result (code: -32030).
 *
 * @extends RPCException
 */
export class InvalidResultException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Security error (code: -32040).
 *
 * @extends RPCException
 */
export class SecurityException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Credentials expired (code: -32041).
 *
 * @extends RPCException
 */
export class CredentialsExpiredException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}
/**
 * Post-processor execution error (code: -32050).
 *
 * @extends RPCException
 */
export class PostProcessorExecutionException extends RPCException {
  constructor(message?: string, cause?: Error | any, data?: any);
  static get CODE(): number;
  static get MESSAGE(): string;
}

import Ajv from "ajv";
import { Exception } from "@alius/exception";