diff --git a/.github/workflows/npm-test.yml b/.github/workflows/npm-test.yml index 4fbc0d2..9110419 100644 --- a/.github/workflows/npm-test.yml +++ b/.github/workflows/npm-test.yml @@ -21,7 +21,7 @@ jobs: strategy: matrix: os: [ubuntu-latest, windows-latest, macos-latest] - version: [16] + version: [lts/*] steps: - name: Checkout repository diff --git a/.github/workflows/publish-code-coverage.yml b/.github/workflows/publish-code-coverage.yml index 7b53e8e..0e5d1f7 100644 --- a/.github/workflows/publish-code-coverage.yml +++ b/.github/workflows/publish-code-coverage.yml @@ -18,10 +18,10 @@ jobs: - name: Checkout repository uses: actions/checkout@v3 - - name: Setup node.js @ 16 + - name: Setup node.js @ lts uses: actions/setup-node@v3 with: - node-version: 16 + node-version: lts/* - name: Get npm cache directory id: npm-cache diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 5b4b2b8..2a6a91d 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -25,10 +25,10 @@ jobs: - name: Clean up gh-pages run: rm -rf gh-pages - - name: Setup node.js @ 16 + - name: Setup node.js @ lts uses: actions/setup-node@v3 with: - node-version: 16 + node-version: lts/* - name: Get npm cache directory id: npm-cache diff --git a/.github/workflows/publish-package.yml b/.github/workflows/publish-package.yml index 13189a9..108f583 100644 --- a/.github/workflows/publish-package.yml +++ b/.github/workflows/publish-package.yml @@ -12,10 +12,10 @@ jobs: - name: Checkout repository uses: actions/checkout@v3 - - name: Setup node.js @ 16 + - name: Setup node.js @ lts uses: actions/setup-node@v3 with: - node-version: 16 + node-version: lts/* - name: Get npm cache directory id: npm-cache diff --git a/package-lock.json b/package-lock.json index 4b8dc04..43be900 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@procedure-rpc/procedure.js", - "version": "0.12.3", + "version": "0.12.4", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@procedure-rpc/procedure.js", - "version": "0.12.3", + "version": "0.12.4", "funding": [ "https://github.com/procedure-rpc/procedure.js?sponsor=1", { @@ -43,8 +43,9 @@ "prettier": "2.7.1", "ts-jest": "^28.0.8", "typed-emitter": "^2.1.0", - "typedoc": "^0.23.14", - "typedoc-plugin-versions": "^0.2.0", + "typedoc": "^0.23.15", + "typedoc-plugin-versions": "^0.2.1", + "typedoc-plugin-versions-cli": "^0.1.5", "typescript": "^4.8.0" }, "engines": { @@ -1745,6 +1746,12 @@ "node": ">=8" } }, + "node_modules/async": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/async/-/async-3.2.4.tgz", + "integrity": "sha512-iAB+JbDEGXhyIUavoDl9WP/Jj106Kz9DEn1DPgYw5ruDn0e3Wgi3sKFm55sASdGBNOQB8F59d9qQ7deqrHA8wQ==", + "dev": true + }, "node_modules/babel-jest": { "version": "28.1.3", "resolved": "https://registry.npmjs.org/babel-jest/-/babel-jest-28.1.3.tgz", @@ -1998,6 +2005,99 @@ "integrity": "sha512-cOU9usZw8/dXIXKtwa8pM0OTJQuJkxMN6w30csNRUerHfeQ5R6U3kkU/FtJeIf3M202OHfY2U8ccInBG7/xogA==", "dev": true }, + "node_modules/cli-diff": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/cli-diff/-/cli-diff-1.0.0.tgz", + "integrity": "sha512-XOVrll4VMhxBv26WqV6OH9cWqRxBXthh3uZ3dtg+CLqB8m0R6QJiSoDIXQNXDAeo/FAkQ+kF9Ph8NhQskU3LpQ==", + "dev": true, + "dependencies": { + "chalk": "^2.4.1", + "diff": "^3.5.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/cli-diff/node_modules/ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dev": true, + "dependencies": { + "color-convert": "^1.9.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/cli-diff/node_modules/chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "dev": true, + "dependencies": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/cli-diff/node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dev": true, + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/cli-diff/node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "dev": true + }, + "node_modules/cli-diff/node_modules/diff": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-3.5.0.tgz", + "integrity": "sha512-A46qtFgd+g7pDZinpnwiRJtxbC1hpgf0uzP3iG89scHk0AUC7A1TGxf5OiiOUv/JMZR8GOt8hL900hV0bOy5xA==", + "dev": true, + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/cli-diff/node_modules/escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "dev": true, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/cli-diff/node_modules/has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "dev": true, + "engines": { + "node": ">=4" + } + }, + "node_modules/cli-diff/node_modules/supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "dev": true, + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/cliui": { "version": "7.0.4", "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", @@ -4879,9 +4979,9 @@ } }, "node_modules/typedoc-plugin-versions": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/typedoc-plugin-versions/-/typedoc-plugin-versions-0.2.0.tgz", - "integrity": "sha512-riDfd2+meM1+idHk60pwKgxZnXZhwqSRtY0bYIOSGmTv4paBOuZL0H75Jd/EA099KtEVdvs3sJNl6MizLCUnKQ==", + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/typedoc-plugin-versions/-/typedoc-plugin-versions-0.2.1.tgz", + "integrity": "sha512-JWNziM5ATtXa9jSnul1a8mlEfoAZX5NGekCz1rVJ/2RyAAfeHYM7LVQmTzmHPdXMfoJH56oJMgINLJ2Ri2SARQ==", "dev": true, "dependencies": { "fs-extra": "^10.1.0", @@ -4895,6 +4995,47 @@ "typedoc": "^0.23" } }, + "node_modules/typedoc-plugin-versions-cli": { + "version": "0.1.5", + "resolved": "https://registry.npmjs.org/typedoc-plugin-versions-cli/-/typedoc-plugin-versions-cli-0.1.5.tgz", + "integrity": "sha512-vKmqxljKX4FRICO2Ana1j+gSC9Y+LyVeE0ThMP3j1wtSXnZhP5t53OA65n+nL0JXDdiImZfU0EbL1pTM3a+/uQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/toebeann" + }, + { + "type": "individual", + "url": "https://paypal.me/tobeyblaber" + } + ], + "os": [ + "win32", + "linux", + "darwin" + ], + "dependencies": { + "async": "^3.2.4", + "cli-diff": "^1.0.0", + "prompts": "^2.4.2", + "semver": "^7.3.7", + "yargs": "^17.5.1" + }, + "bin": { + "tpv": "dist/cli.js", + "typedoc-plugin-versions": "dist/cli.js", + "typedoc-plugin-versions-cli": "dist/cli.js", + "typedoc-versions": "dist/cli.js" + }, + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "typedoc": "^0.23", + "typedoc-plugin-versions": "^0.2" + } + }, "node_modules/typedoc/node_modules/brace-expansion": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", @@ -6431,6 +6572,12 @@ "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==", "dev": true }, + "async": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/async/-/async-3.2.4.tgz", + "integrity": "sha512-iAB+JbDEGXhyIUavoDl9WP/Jj106Kz9DEn1DPgYw5ruDn0e3Wgi3sKFm55sASdGBNOQB8F59d9qQ7deqrHA8wQ==", + "dev": true + }, "babel-jest": { "version": "28.1.3", "resolved": "https://registry.npmjs.org/babel-jest/-/babel-jest-28.1.3.tgz", @@ -6616,6 +6763,80 @@ "integrity": "sha512-cOU9usZw8/dXIXKtwa8pM0OTJQuJkxMN6w30csNRUerHfeQ5R6U3kkU/FtJeIf3M202OHfY2U8ccInBG7/xogA==", "dev": true }, + "cli-diff": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/cli-diff/-/cli-diff-1.0.0.tgz", + "integrity": "sha512-XOVrll4VMhxBv26WqV6OH9cWqRxBXthh3uZ3dtg+CLqB8m0R6QJiSoDIXQNXDAeo/FAkQ+kF9Ph8NhQskU3LpQ==", + "dev": true, + "requires": { + "chalk": "^2.4.1", + "diff": "^3.5.0" + }, + "dependencies": { + "ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dev": true, + "requires": { + "color-convert": "^1.9.0" + } + }, + "chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "dev": true, + "requires": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + } + }, + "color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dev": true, + "requires": { + "color-name": "1.1.3" + } + }, + "color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "dev": true + }, + "diff": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-3.5.0.tgz", + "integrity": "sha512-A46qtFgd+g7pDZinpnwiRJtxbC1hpgf0uzP3iG89scHk0AUC7A1TGxf5OiiOUv/JMZR8GOt8hL900hV0bOy5xA==", + "dev": true + }, + "escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "dev": true + }, + "has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "dev": true + }, + "supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "dev": true, + "requires": { + "has-flag": "^3.0.0" + } + } + } + }, "cliui": { "version": "7.0.4", "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", @@ -8760,15 +8981,28 @@ } }, "typedoc-plugin-versions": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/typedoc-plugin-versions/-/typedoc-plugin-versions-0.2.0.tgz", - "integrity": "sha512-riDfd2+meM1+idHk60pwKgxZnXZhwqSRtY0bYIOSGmTv4paBOuZL0H75Jd/EA099KtEVdvs3sJNl6MizLCUnKQ==", + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/typedoc-plugin-versions/-/typedoc-plugin-versions-0.2.1.tgz", + "integrity": "sha512-JWNziM5ATtXa9jSnul1a8mlEfoAZX5NGekCz1rVJ/2RyAAfeHYM7LVQmTzmHPdXMfoJH56oJMgINLJ2Ri2SARQ==", "dev": true, "requires": { "fs-extra": "^10.1.0", "semver": "^7.3.7" } }, + "typedoc-plugin-versions-cli": { + "version": "0.1.5", + "resolved": "https://registry.npmjs.org/typedoc-plugin-versions-cli/-/typedoc-plugin-versions-cli-0.1.5.tgz", + "integrity": "sha512-vKmqxljKX4FRICO2Ana1j+gSC9Y+LyVeE0ThMP3j1wtSXnZhP5t53OA65n+nL0JXDdiImZfU0EbL1pTM3a+/uQ==", + "dev": true, + "requires": { + "async": "^3.2.4", + "cli-diff": "^1.0.0", + "prompts": "^2.4.2", + "semver": "^7.3.7", + "yargs": "^17.5.1" + } + }, "typescript": { "version": "4.8.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.8.3.tgz", diff --git a/package.json b/package.json index 0aa24af..214bb97 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@procedure-rpc/procedure.js", - "version": "0.12.3", + "version": "0.12.4", "title": "procedure.js", "description": "The simple RPC framework for Node.js.", "main": "./dist/index.js", @@ -28,14 +28,17 @@ "license": "MIT", "sideEffects": false, "scripts": { - "build": "tsc", - "prebuild": "npm run format", - "format": "prettier -w . --ignore-path .gitignore", - "format:check": "prettier -c . --ignore-path .gitignore", "test": "jest", "posttest": "npm run format:check", + "format": "prettier -w . --ignore-path .gitignore", + "format:check": "prettier -c . --ignore-path .gitignore", + "build": "tsc", + "prebuild": "npm run format", "docs": "typedoc", - "predocs": "npm run format" + "postdocs": "npm run docs:purge", + "docs:purge": "tpv purge -y --patch 3", + "postdocs:purge": "npm run docs:sync", + "docs:sync": "tpv sync -y --symlinks" }, "dependencies": { "@msgpack/msgpack": "^2.7.2", @@ -56,8 +59,9 @@ "prettier": "2.7.1", "ts-jest": "^28.0.8", "typed-emitter": "^2.1.0", - "typedoc": "^0.23.14", - "typedoc-plugin-versions": "^0.2.0", + "typedoc": "^0.23.15", + "typedoc-plugin-versions": "^0.2.1", + "typedoc-plugin-versions-cli": "^0.1.5", "typescript": "^4.8.0" }, "files": [ diff --git a/src/errors.ts b/src/errors.ts index c88bdd3..5aecbdb 100644 --- a/src/errors.ts +++ b/src/errors.ts @@ -189,11 +189,9 @@ export class ProcedureExecutionError extends ProcedureError { } /** - * Type guard for determining whether a given object conforms to the - * [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) interface. + * Type guard for determining whether a given object conforms to the {@link !Error Error} interface. * @param {unknown} object The object. - * @returns {object is Error} `true` if the object conforms to the - * [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) interface, otherwise `false`. + * @returns {object is Error} `true` if the object conforms to the {@link !Error Error} interface, otherwise `false`. * @internal * @remarks Intended for internal use; may not be exported in future. */ diff --git a/src/index.ts b/src/index.ts index cfd2372..b31a72b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,3 +1,5 @@ +import { Buffer } from 'node:buffer'; +import { env } from 'node:process'; import { isProcedureError, isError, @@ -21,16 +23,16 @@ import { once, EventEmitter } from 'events'; import TypedEmitter from 'typed-emitter'; import { v5 as uuidv5 } from 'uuid'; -// eslint-disable-next-line @typescript-eslint/no-var-requires -const homepage: string = require('../package.json').homepage; +const homepage = + env.npm_package_homepage ?? 'https://procedure-rpc.github.io/procedure.js'; const uuidNamespace = uuidv5(homepage, uuidv5.URL); /** * A simple abstraction of a procedure (the P in RPC). * Allows you to turn a function or callback into a procedure, which can be called via the transport specified. - * @template Input Type of input parameter the procedure accepts. Defaults to `undefined`. - * @template Output Type of output value the procedure returns. Defaults to `undefined`. - * @see {@link https://github.com/andywer/typed-emitter#readme TypedEmitter} + * @typeParam Input Type of input parameter the procedure accepts. Defaults to {@link !undefined `undefined`}. + * @typeParam Output Type of output value the procedure returns. Defaults to {@link !undefined `undefined`}. + * @see {@link typed-emitter!TypedEventEmitter TypedEmitter} */ export class Procedure extends (EventEmitter as { @@ -127,8 +129,8 @@ export class Procedure * Initializes a new {@link Procedure}. * @param {(input: Input) => Output} callback The underlying callback function powering the procedure itself. The callback may be asynchronous. * @param {Partial} [options] Options for a {@link Procedure}. Defaults to `{}`. - * @template Input Type of input parameter the procedure accepts. Defaults to `undefined`. - * @template Output Type of output value the procedure returns. Defaults to `undefined`. + * @template Input Type of input parameter the procedure accepts. Defaults to {@link !undefined `undefined`}. + * @template Output Type of output value the procedure returns. Defaults to {@link !undefined `undefined`}. */ constructor( protected callback: (input: Input) => Output, @@ -192,9 +194,10 @@ export class Procedure } /** - * Attempts to decode the given {@link https://nodejs.org/api/buffer.html#buffer Buffer}. - * @param {Buffer} buffer The {@link https://nodejs.org/api/buffer.html#buffer Buffer} to decode. - * @returns {{ input: Input, error?: never } | { input?: never, error: unknown }} If successful, an object of shape `{ input: Input | Ping }`, otherwise `{ error: unknown }`. + * Attempts to decode the given {@link node!Buffer Buffer}. + * @param {Buffer} buffer The {@link node!Buffer Buffer} to decode. + * @returns {{ input: Input, error?: never } | { input?: never, error: unknown }} If successful, an object of shape `{ input: Input | Ping }`, + * otherwise `{ error: unknown }`. */ #tryDecodeInput( buffer: Buffer @@ -219,9 +222,7 @@ export class Procedure /** * Attempts to asynchronously call the {@link Procedure.callback Procedure's callback} and return a response containing its output value. * @param {Input} input An input parameter to pass to the {@link Procedure.callback callback}. - * @returns {Promise>} A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise} - * which when resolved passes the response to the - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then then} handler(s). + * @returns {Promise>} A {@link !Promise Promise} which when resolved passes the response to the {@link !Promise.then then} handler(s). */ async #tryGetCallbackResponse(input: Input): Promise> { try { @@ -254,7 +255,7 @@ export class Procedure /** * Attempts to encode the given response for transmission back to the {@link Procedure Procedure's} caller. * @param {Response} response The response to encode. - * @returns {Buffer} A {@link https://nodejs.org/api/buffer.html#buffer Buffer} containing the encoded response. + * @returns {Buffer} A {@link node!Buffer Buffer} containing the encoded response. */ #tryEncodeResponse(response: Response): Buffer { try { @@ -284,9 +285,9 @@ export class Procedure /** * Attempts to send the encoded buffer back to the {@link Procedure Procedure's} caller. - * @param {Buffer} buffer A {@link https://nodejs.org/api/buffer.html#buffer Buffer} containing the encoded response. + * @param {Buffer} buffer A {@link node!Buffer Buffer} containing the encoded response. * @param {Socket} socket The socket through which to send the response. - * @returns {boolean} `true` when the encoded {@link https://nodejs.org/api/buffer.html#buffer Buffer} was successfully sent, otherwise `false`. + * @returns {boolean} `true` when the encoded {@link node!Buffer Buffer} was successfully sent, otherwise `false`. */ #trySendBuffer(buffer: Buffer, socket: Socket): boolean { try { @@ -303,7 +304,7 @@ export class Procedure /** * Asynchrously handles the socket's data event, representing requests to call the {@link Procedure}. - * @param {Buffer} data The encoded input {@link https://nodejs.org/api/buffer.html#buffer Buffer}. + * @param {Buffer} data The encoded input {@link node!Buffer Buffer}. * @param {Socket} socket The socket the data was received on. */ async #onRepSocketData(data: Buffer, socket: Socket): Promise { @@ -469,17 +470,17 @@ export type Response = export interface ProcedureOptions { /** * Whether or not to enable optional parameter support. Defaults to `true`. - * When `true` on a {@link Procedure}, a `null` input parameter will be coerced to `undefined`. - * When `true` for a {@link call}, a `null` return value will be coerced to `undefined`. + * When `true` on a {@link Procedure}, a {@link !null `null`} input parameter will be coerced to {@link !undefined `undefined`}. + * When `true` for a {@link call}, a {@link !null `null`} return value will be coerced to {@link !undefined `undefined`}. * * @remarks * The {@link https://procedure-rpc.github.io/procedure.js procedure.js} library uses the {@link https://github.com/msgpack/msgpack-javascript msgpack} * serialization format for encoding JavaScript objects and values for transmission to and from remote {@link Procedure procedures}. - * The JavaScript implementation of msgpack {@link https://github.com/msgpack/msgpack-javascript#messagepack-mapping-table maps undefined to null}. + * The JavaScript implementation of msgpack {@link https://github.com/msgpack/msgpack-javascript#messagepack-mapping-table maps `undefined` to `null`}. * For procedures which accept optional parameters, this is problematic. - * It could also be an issue if you depend on the return value of a procedure to conditionally be `undefined`, + * It could also be an issue if you depend on the return value of a procedure to conditionally be {@link !undefined `undefined`}, * for the convenience of passing the return value into an optional parameter of another function call. - * {@link optionalParameterSupport} aims to alleviate these issues by mapping `null` to `undefined` + * {@link optionalParameterSupport} aims to alleviate these issues by mapping {@link !null `null`} to {@link !undefined `undefined`} * for the input and output of your {@link Procedure} calls. * * @see {@link ignoreUndefinedProperties} @@ -487,18 +488,18 @@ export interface ProcedureOptions { */ optionalParameterSupport: boolean; /** - * Whether or not to ignore `undefined` properties of objects passed to or from a {@link Procedure}. Defaults to `true`. + * Whether or not to ignore {@link !undefined `undefined`} properties of objects passed to or from a {@link Procedure}. Defaults to `true`. * When `true` on a {@link Procedure}, only affects properties of input parameters. * When `true` on a {@link call}, only affects properties of the return value. * * @remarks * The {@link https://procedure-rpc.github.io/procedure.js procedure.js} library uses the {@link https://github.com/msgpack/msgpack-javascript msgpack} * serialization format for encoding JavaScript objects and values for transmission to and from remote {@link Procedure procedures}. - * The JavaScript implementation of msgpack {@link https://github.com/msgpack/msgpack-javascript#messagepack-mapping-table maps undefined to null}. - * This means that when passing objects in or out of a {@link Procedure} (i.e. as a parameter or return value), any properties defined as `undefined` - * will evaluate to `null` on receipt. + * The JavaScript implementation of msgpack {@link https://github.com/msgpack/msgpack-javascript#messagepack-mapping-table maps `undefined` to `null`}. + * This means that when passing objects in or out of a {@link Procedure} (i.e. as a parameter or return value), any properties defined as + * {@link !undefined `undefined`} will evaluate to {@link !null `null`} on receipt. * {@link ignoreUndefinedProperties} aims to alleviate this by signalling msgpack to ignore undefined properties from objects before they are encoded, - * allowing `undefined` to be evaluated as `undefined` and `null` to be evaluated as `null`. + * allowing {@link !undefined `undefined`} to be evaluated as {@link !undefined `undefined`} and {@link !null `null`} to be evaluated as {@link !null `null`}. * This operation incurs some overhead, and means that code relying on the presence of a property to infer meaning * may not operate as expected. * @@ -513,13 +514,12 @@ export interface ProcedureOptions { export interface ProcedureDefinitionOptions extends ProcedureOptions { /** * The number of workers to spin up for the {@link Procedure}. Useful for procedures which may take a long time to complete. - * Will be clamped between `1` and - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER Number.MAX_SAFE_INTEGER} inclusive. + * Will be clamped between `1` and {@link !Number.MAX_SAFE_INTEGER `Number.MAX_SAFE_INTEGER`} inclusive. * Defaults to `1`. */ workers: number; /** Whether or not to output errors and events to the console. Defaults to `false`. */ verbose: boolean; - /** An optional msgpack {@link https://github.com/msgpack/msgpack-javascript#extension-types ExtensionCodec} to use for encoding and decoding messages. */ + /** An optional msgpack {@link @msgpack/msgpack!ExtensionCodec ExtensionCodec} to use for encoding and decoding messages. */ extensionCodec?: ExtensionCodec | undefined; } @@ -529,29 +529,24 @@ export interface ProcedureDefinitionOptions extends ProcedureOptions { export interface ProcedureCallOptions extends ProcedureOptions { /** * The number of milliseconds after which the {@link call} will automatically be aborted. - * Set to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity Infinity} - * or {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN} to never timeout. - * Non-{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN}, finite values will be clamped between - * `0` and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER Number.MAX_SAFE_INTEGER} inclusive. + * Set to {@link !Infinity `Infinity`} or {@link !NaN `NaN`} to never timeout. + * Non-{@link !NaN `NaN`}, finite values will be clamped between `0` and {@link !Number.MAX_SAFE_INTEGER `Number.MAX_SAFE_INTEGER`} inclusive. * Defaults to `1000`. */ timeout: number; /** * The number of milliseconds to wait for a ping-pong from the endpoint before calling the remote procedure. * When set, if a ping-pong is not received in the given time, the {@link call} will be aborted. - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN} or - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity infinite} numbers will result in the ping - * never timing out if no response is received, unless {@link signal} is a valid - * {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal AbortSignal} and gets aborted. - * Non-{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN}, finite values will be clamped between - * `0` and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER Number.MAX_SAFE_INTEGER} inclusive. + * {@link !NaN `NaN`} or {@link !Infinity infinite} numbers will result in the ping never timing out if no response is received, + * unless {@link signal} is a valid {@link !AbortSignal AbortSignal} and gets aborted. + * Non-{@link !NaN `NaN`}, finite values will be clamped between `0` and {@link !Number.MAX_SAFE_INTEGER `Number.MAX_SAFE_INTEGER`} inclusive. * Defaults to `1000`. */ ping?: number | undefined; pingCacheLength?: number | undefined; - /** An optional msgpack {@link https://github.com/msgpack/msgpack-javascript#extension-types ExtensionCodec} to use for encoding and decoding messages. */ + /** An optional msgpack {@link @msgpack/msgpack!ExtensionCodec ExtensionCodec} to use for encoding and decoding messages. */ extensionCodec?: ExtensionCodec | undefined; - /** An optional {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal AbortSignal} which will be used to abort the Procedure call. */ + /** An optional {@link !AbortSignal AbortSignal} which will be used to abort the Procedure call. */ signal?: AbortSignal | undefined; /** Whether the endpoint requires ipv6 support. Defaults to `false`. */ ipv6: boolean; @@ -560,7 +555,7 @@ export interface ProcedureCallOptions extends ProcedureOptions { /** * A map of the names of events emitted by {@link Procedure Procedures} and their function signatures. * @template Input The type of input parameter passed to the data event. - * @see {@link https://github.com/andywer/typed-emitter#readme TypedEmitter} + * @see {@link typed-emitter!TypedEventEmitter TypedEmitter} */ export type ProcedureEvents = { /** @@ -605,11 +600,9 @@ export function isPing(object: unknown): object is Ping { /** * Asynchronously calls a {@link Procedure} at a given endpoint with a given input. * @param {string} endpoint The endpoint at which the {@link Procedure} is {@link Procedure.bind bound}. - * @param {unknown} [input] An input parameter to pass to the {@link Procedure}. Defaults to `undefined`. + * @param {unknown} [input] An input parameter to pass to the {@link Procedure}. Defaults to {@link !undefined `undefined`}. * @param {Partial} [options] Options for calling a {@link Procedure}. Defaults to `{}`. - * @returns {Promise} A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise} - * which when resolved passes the output value to the - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then then} handler(s). + * @returns {Promise} A {@link !Promise Promise} which when resolved passes the output value to the {@link !Promise.then then} handler(s). * @template Output The type of output value expected to be returned from the {@link Procedure}. Defaults to `unknown`. * @see {@link Procedure.endpoint} * @see {@link ping} @@ -677,19 +670,14 @@ export async function call( * Asynchonously pings a {@link Procedure} at a given endpoint to check that it is available and ready to be {@link call called}. * @param {string} endpoint The {@link Procedure.endpoint endpoint} to ping at which a {@link Procedure} is expected to be {@link Procedure.bind bound}. * @param {number} [timeout] How long to wait for a response before timing out. - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN} or - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity infinite} values will result in the ping - * never timing out if no response is received, unless signal is a valid - * {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal AbortSignal} and gets aborted. - * Non-{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN}, finite values will be clamped between - * `0` and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER Number.MAX_SAFE_INTEGER} inclusive. + * {@link !NaN `NaN`} or {@link !Infinity infinite} values will result in the ping never timing out if no response is received, + * unless signal is a valid {@link !AbortSignal AbortSignal} and gets aborted. + * Non-{@link !NaN `NaN`}, finite values will be clamped between `0` and {@link !Number.MAX_SAFE_INTEGER `Number.MAX_SAFE_INTEGER`} inclusive. * Defaults to `1000`. * @param {boolean} [ipv6=false] Whether the endpoint requires ipv6 support. Defaults to `false`. - * @param {AbortSignal} [signal] An optional {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal AbortSignal} which, - * when passed, will be used to abort awaiting the ping. - * Defaults to `undefined`. - * @returns {Promise} A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise} - * which when resolved indicates that the endpoint is available and ready to handle {@link call calls}. + * @param {AbortSignal} [signal] An optional {@link !AbortSignal AbortSignal} which, when passed, will be used to abort awaiting the ping. + * Defaults to {@link !undefined `undefined`}. + * @returns {Promise} A {@link !Promise Promise} which when resolved indicates that the endpoint is available and ready to handle {@link call calls}. */ export async function ping( endpoint: string, @@ -727,11 +715,9 @@ export async function ping( * @param {number} timeout How long to wait for a response before timing out. * @param {number} cacheLength The length of the cache in milliseconds. * @param {boolean} ipv6 Whether the endpoint requires ipv6 support. - * @param {AbortSignal} [signal] An optional {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal AbortSignal} which, - * when passed, will be used to abort awaiting the ping. - * Defaults to `undefined`. - * @returns {Promise} A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise} which, - * when resolved, indicates that the endpoint is available and ready to handle {@link call calls}. + * @param {AbortSignal} [signal] An optional {@link !AbortSignal AbortSignal} which, when passed, will be used to abort awaiting the ping. + * Defaults to {@link !undefined `undefined`}. + * @returns {Promise} A {@link !Promise Promise} which, when resolved, indicates that the endpoint is available and ready to handle {@link call calls}. */ async function cachedPing( endpoint: string, @@ -772,19 +758,14 @@ async function cachedPing( * If any errors are thrown, absorbs them and returns `false`. * @param {string} endpoint The {@link Procedure.endpoint endpoint} to ping at which a {@link Procedure} is expected to be {@link Procedure.bind bound}. * @param {number} [timeout=1000] How long to wait for a response before timing out. - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN} or - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity infinite} values will result in the ping - * never timing out if no response is received, unless signal is a valid - * {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal AbortSignal} and gets aborted. - * Non-{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN NaN}, finite values will be clamped between - * `0` and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER Number.MAX_SAFE_INTEGER} inclusive. + * {@link !NaN `NaN`} or {@link !Infinity infinite} values will result in the ping never timing out if no response is received, + * unless signal is a valid {@link !AbortSignal AbortSignal} and gets aborted. + * Non-{@link !NaN `NaN`}, finite values will be clamped between `0` and {@link !Number.MAX_SAFE_INTEGER `Number.MAX_SAFE_INTEGER`} inclusive. * Defaults to `1000`. * @param {boolean} [ipv6=false] Whether the endpoint requires ipv6 support. Defaults to `false`. - * @param {AbortSignal} [signal] An optional {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal AbortSignal} which, - * when passed, will be used to abort awaiting the ping. - * Defaults to `undefined`. - * @returns {Promise} A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise} - * which when resolved indicated whether the endpoint is available and ready to handle {@link call calls}. + * @param {AbortSignal} [signal] An optional {@link !AbortSignal AbortSignal} which, when passed, will be used to abort awaiting the ping. + * Defaults to {@link !undefined `undefined`}. + * @returns {Promise} A {@link !Promise Promise} which when resolved indicated whether the endpoint is available and ready to handle {@link call calls}. * If errors were thrown, resolves to `false` instead of rejecting. */ export async function tryPing( @@ -806,9 +787,8 @@ export async function tryPing( * @param {string} endpoint The endpoint at which the {@link Procedure} is {@link Procedure.bind bound}. * @param {unknown} input An input parameter to pass to the {@link Procedure}. * @param {ProcedureCallOptions} options Options for calling a {@link Procedure}. - * @returns {Promise>} A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise} - * which when resolved passes the {@link Response response} to the - * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then then} handler(s). + * @returns {Promise>} A {@link !Promise Promise} which when resolved passes the {@link Response response} to the + * {@link !Promise.then then} handler(s). * @template Output The type of output value expected to be returned from the {@link Procedure}. Defaults to `unknown`. */ async function getResponse( @@ -865,9 +845,9 @@ async function getResponse( /** * Encodes a given value for transmission. * @param {unknown} value The value to be encoded. - * @param {boolean} ignoreUndefinedProperties Whether to strip `undefined` properties from objects or not. - * @param {ExtensionCodec} [extensionCodec] The {@link https://github.com/msgpack/msgpack-javascript#extension-types ExtensionCodec} to use for encoding. - * @returns {Buffer} A {@link https://nodejs.org/api/buffer.html#buffer Buffer} containing the encoded value. + * @param {boolean} ignoreUndefinedProperties Whether to strip {@link !undefined `undefined`} properties from objects or not. + * @param {ExtensionCodec} [extensionCodec] The {@link @msgpack/msgpack!ExtensionCodec ExtensionCodec} to use for encoding. + * @returns {Buffer} A {@link node!Buffer Buffer} containing the encoded value. */ function encode( value: unknown, @@ -882,9 +862,9 @@ function encode( } /** - * Decodes a given {@link https://nodejs.org/api/buffer.html#buffer Buffer} and casts it as {@link T}. - * @param {Buffer} buffer The {@link https://nodejs.org/api/buffer.html#buffer Buffer} to be decoded. - * @param {ExtensionCodec} [extensionCodec] The {@link https://github.com/msgpack/msgpack-javascript#extension-types ExtensionCodec} to use for decoding. + * Decodes a given {@link node!Buffer Buffer} and casts it as {@link T}. + * @param {Buffer} buffer The {@link node!Buffer Buffer} to be decoded. + * @param {ExtensionCodec} [extensionCodec] The {@link @msgpack/msgpack!ExtensionCodec ExtensionCodec} to use for decoding. * @returns {T} The buffer, decoded and cast to type {@link T}. * @template T The type the decoded value should be cast to. */ diff --git a/typedoc.json b/typedoc.json index 53e4b1e..017c31d 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,5 +1,38 @@ { - "entryPoints": "src", + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["src"], "entryPointStrategy": "expand", - "includeVersion": true + "includeVersion": true, + "externalSymbolLinkMappings": { + "global": { + "undefined": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined", + "Infinity": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity", + "NaN": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN", + "null": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null", + "Error": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error", + "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise", + "Promise.then": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then", + "Number.MAX_SAFE_INTEGER": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER", + "AbortSignal": "https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal" + }, + "typescript": { + "Error": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error", + "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise", + "Partial": "https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype", + "Record": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type" + }, + "node": { + "Buffer": "https://nodejs.org/api/buffer.html#buffer" + }, + "@types/node": { + "AbortSignal": "https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal", + "Buffer": "https://nodejs.org/api/buffer.html#buffer" + }, + "@msgpack/msgpack": { + "ExtensionCodec": "https://github.com/msgpack/msgpack-javascript#extension-types" + }, + "typed-emitter": { + "TypedEventEmitter": "https://github.com/andywer/typed-emitter#readme" + } + } }