npc-vortex-api 🛠️

A utility package for npc for Vortex.

Description

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.

Table of contents

• 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

Installation

pnpm

pnpm add @toebean/npc-vortex-api

yarn

yarn add @toebean/npc-vortex-api

npm

npm i @toebean/npc-vortex-api

Usage

Registering npc procedures in a Vortex extension

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.

Calling external npc procedures from a Vortex extension

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 for more information about the call function.
• See https://zod.dev for more information on Zod.

Registering npc procedures in a separate Node.js application

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 for more information about the create function.
• See https://zod.dev for more information on Zod.

Calling Vortex npc procedures from a separate Node.js application

Registered by extensions

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 for more information about the call function.
• See https://zod.dev for more information on Zod.

npc for Vortex built-ins

npc-vortex-api exposes helper methods to call the built-in npc procedures of npc for Vortex:

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 to validate the output of each function, so you do not need to do this yourself.

Complete listing of all helper methods:

• Nexus
• Vortex

Calling npc for Vortex built-ins from a Vortex extension

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:

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 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
• Vortex

License

npc-vortex-api is licensed under MIT © 2023 Tobey Blaber.