@toebean/npc-vortex-api
TypeScript icon, indicating that this package has built-in type declarations

0.2.1 • Public • Published

npc-vortex-api 🛠️

A utility package for npc for Vortex.

npm package version npm package downloads typedocs license

pnpm test publish package publish docs

github twitter GitHub Sponsors donation button PayPal donation button

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

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
    }
  });
}

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
  }
}

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

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
  }
})();

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:

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:

License

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

Package Sidebar

Install

npm i @toebean/npc-vortex-api

Weekly Downloads

1

Version

0.2.1

License

MIT

Unpacked Size

343 kB

Total Files

27

Last publish

Collaborators

  • toebean