@toebean/npc-vortex-api
Version:
A utility package for npc for Vortex.
279 lines (214 loc) • 12.2 kB
Markdown
<center>
A utility package for npc for Vortex.
[](https://npmjs.org/package/@toebean/npc-vortex-api "View npc-vortex-api on npm") [](https://npmjs.org/package/@toebean/npc-vortex-api "View npc-vortex-api on npm") [](https://toebeann.github.io/npc-vortex-api/ "Read the documentation on Github Pages") [](https://github.com/toebeann/npc-vortex-api/blob/main/LICENSE "View the license on GitHub")
[](https://github.com/toebeann/npc-vortex-api/actions/workflows/pnpm-test.yml "View pnpm test on GitHub Actions") [](https://github.com/toebeann/npc-vortex-api/actions/workflows/publish-package.yml "View publish package on GitHub Actions") [](https://github.com/toebeann/npc-vortex-api/actions/workflows/publish-docs.yml "View publish docs on GitHub Actions")
[](https://github.com/toebeann/npc-vortex-api "View npc-vortex-api on GitHub") [](https://twitter.com/toebean__ "Follow @toebean__ on Twitter") [](https://github.com/sponsors/toebeann "Sponsor npc-vortex-api on GitHub") [](https://paypal.me/tobeyblaber "Donate to npc-vortex-api with PayPal")
</center>
This package exposes a number of utility functions for calling the built-in procedures of npc for Vortex, as well as type information for working with the extension in TypeScript.
- [npc-vortex-api 🛠️](
- [Description](
- [Table of contents](
- [Installation](
- [pnpm](
- [yarn](
- [npm](
- [Usage](
- [Registering npc procedures in a Vortex extension](
- [Calling external npc procedures from a Vortex extension](
- [Registering npc procedures in a separate Node.js application](
- [Calling Vortex npc procedures from a separate Node.js application](
- [Registered by extensions](
- [npc for Vortex built-ins](
- [Calling npc for Vortex built-ins from a Vortex extension](
- [License](
```shell
pnpm add @toebean/npc-vortex-api
```
```shell
yarn add @toebean/npc-vortex-api
```
```shell
npm i @toebean/npc-vortex-api
```
```ts
import { join } from "path";
import { RegisterNpcApi } from "@toebean/npc-vortex-api";
import { types } from "vortex-api";
import { z } from "zod";
export default main(context: types.IExtensionContext) {
// always call registerNpcApi from within context.once
context.once(async () => {
// apply type information to the registerNpcApi function
const registerNpcApi: RegisterNpcApi = context.api.ext.registerNpcApi;
// this is the function which we will expose as an npc procedure
const callback = Math.sqrt;
// the path at which we will expose the procedure
// it is recommended to always namespace your procedures
// by the name of your extension
const path = join("myExtensionName", "getSquareRoot");
// it is recommended to validate the input arguments being
// sent to your procedure with middleware - in this case
// we are using Zod to validate the input argument is a number
const middleware = z.number().parse;
// now register the npc procedure
const endpoint = await registerNpcApi?.(path, callback, middleware);
// endpoint = "vortex\\myExtensionName\\getSquareRoot"
// the npc procedure will now be callable via npc
// at the endpoint: vortex\myExtensionName\getSquareRoot
if (!endpoint) {
// if endpoint is undefined, this is likely because the user
// does not have npc for Vortex installed
}
});
}
```
- See https://zod.dev for more information on Zod.
```ts
import { join } from "path";
import { call } from "@toebean/npc";
import { types } from "vortex-api";
import { z } from "zod";
async function getSquareRoot(n: number) {
const result = await call(join("myNodeApp", "getSquareRoot"), n);
// we should validate the result matches our expectations,
// for this purpose we recommend using Zod
return z.number().parse(result);
}
const getSquareRoot = async (n: number) => {
}z.number().parse(await call(join("myNodeApp", "getSquareRoot"), n));
export default async function main(context: types.IExtensionContext) {
try {
const root = await getSquareRoot(64);
// if the endpoint was available, the input value 64 was
// acceptable by the procedure at the endpoint,
// and the output value meets our own validation,
// then root will now be the result of the externally defined
// function `myNodeApp\getSquareRoot`: 8
} catch (error) {
// if the npc endpoint `myNodeApp\getSquareRoot` is not available,
// or if our input arguments/output did not pass validation,
// an error will be thrown, so we should handle that error here
}
}
```
- See [npc](https://toebeann.github.io/npc) for more information about the [call](https://toebeann.github.io/npc/stable/?page=Function.call) function.
- See https://zod.dev for more information on Zod.
```ts
import { join } from "path";
import { create } from "@toebean/npc";
import { z } from "zod";
// create an npc procedure which calculates the square root of a
// numeric input value, with middleware which will validate the
// input value is a number using Zod
const npc = create(Math.sqrt, z.number().parse);
await npc.listen(join("myNodeApp", "getSquareRoot"));
// the npc procedure is now available to be called at the endpoint:
// myNodeApp\getSquareRoot
```
- See [npc](https://toebeann.github.io/npc) for more information about the [create](https://toebeann.github.io/npc/stable/?page=Function.create) function.
- See https://zod.dev for more information on Zod.
```ts
import { join } from "path";
import { call } from "@toebean/npc";
import { z } from "zod";
async function getSquareRoot(n: number) {
const result = await call({
endpoint: join("vortex", "myExtensionName", "getSquareRoot"),
input: n,
});
// we should validate the result matches our expectations,
// for this purpose we recommend using Zod
return z.number().parse(result);
}
(async () => {
try {
const root = await getSquareRoot(64);
// if the endpoint was available, the input value 64 was
// acceptable by the procedure at the endpoint,
// and the output value meets our own validation,
// then root will now be the result of the externally defined
// function `myNodeApp\getSquareRoot`: 8
} catch (error) {
// if the npc endpoint `myNodeApp\getSquareRoot` is not available,
// or if our input arguments/output did not pass validation,
// an error will be thrown, so we should handle that error here
}
})();
```
- See [npc](https://toebeann.github.io/npc) for more information about the [call](https://toebeann.github.io/npc/stable/?page=Function.call) function.
- See https://zod.dev for more information on Zod.
npc-vortex-api exposes helper methods to call the built-in npc procedures of npc for Vortex:
```ts
import { inspect } from "util";
import { getLatestUpdated } from "@toebean/npc-vortex-api/nexus";
import { getCurrentGame } from "@toebean/npc-vortex-api/vortex";
(async () => {
try {
const currentGame = await getCurrentGame();
if (currentGame.id !== "__placeholder") {
const latest = await getLatestUpdated({
input: { gameId: currentGame.id },
});
console.log(inspect(latest, false, null, true));
// prints a list of the latest updated mods on Nexus Mods
// for the game which the user is currently managing in Vortex
}
} catch (error) {
// handle any errors
}
})();
```
All of the helper methods use [Zod](https://zod.dev) to validate the output of each function, so you do not need to do this yourself.
Complete listing of all helper methods:
- [Nexus](https://toebeann.github.io/npc-vortex-api/stable/?page=Module.nexus)
- [Vortex](https://toebeann.github.io/npc-vortex-api/stable/?page=Module.vortex)
It is not necessary to use npc to call the npc for Vortex built-ins from a Vortex extension, as they are exposed via the Vortex extension API in the same manner as registerNpcApi:
```ts
import { NexusApi, VortexApi } from "@toebean/npc-vortex-api";
import { types } from "vortex-api";
export default main(context: types.IExtensionContext) {
// always call Vortex extension API functions from within context.once
context.once(async () => {
const nexusApi: NexusApi = context.api.ext.createNexusApi?.();
const vortexApi: VortexApi = context.api.ext.createVortexApi?.();
// if vortexApi or nexusApi are undefined,
// the npc for Vortex extension is likely not installed
if (vortexApi && nexusApi) {
try {
const currentGame = await vortexApi.getCurrentGame();
if (currentGame.id !== '__placeholder') {
const latest = await nexus.getLatestUpdated({
input: { gameId: currentGame.id },
});
// latest now contains a list of the latest updated
// mods from Nexus Mods for the game which the user
// is currently managing in Vortex
}
} catch (error) {
// handle any errors here
}
}
});
}
```
All of the built-ins use [Zod](https://zod.dev) to validate the output of each function, so you do not need to do this yourself.
Complete listing of npc for Vortex built-ins:
- [Nexus](https://toebeann.github.io/npc-vortex-api/stable/?page=index.Interface.NexusApi)
- [Vortex](https://toebeann.github.io/npc-vortex-api/stable/?page=index.Interface.VortexApi)
npc-vortex-api is licensed under [MIT](https://github.com/toebeann/npc-vortex-api/blob/main/LICENSE) © 2023 Tobey Blaber.