pastelmind / kolmafia-types

TypeScript type declarations for KoLmafia. Alternative to kolmafia-js.

kolmafia-types

Type definitions for writing TypeScript/JavaScript code that runs in KoLmafia. This is a drop-in replacement for kolmafia-js.

Once installed, your scripts will be type checked for correctness:

// For JavaScript
const {visitUrl} = require('kolmafia');
// For TypeScript, Babel, or other transpilers/bundlers that support ES modules
import {visitUrl} from 'kolmafia';

visitUrl('main.php'); // OK
visitUrl(123); // Type error

Why another type definition for KoLmafia?

kolmafia-types provides some features missing in kolmafia-js:

• Curated JSDoc comments for KoLmafia functions, including @links to KoL wiki pages, @deprecated warnings, and @version of KoLmafia when the function was introduced. (Note: work in progress)
• Type definitions for popular ASH scripts
• Frequent(-ish) updates

Installation

kolmafia-types requires TypeScript 4.1 or above. If your TypeScript version is lower than this, you may see compiler error messages like "Cannot find module 'kolmafia-types'."

To use kolmafia-types in your project, you can choose one of:

1. Install kolmafia-types using a kolmafia alias
2. Tell TypeScript to use a custom path to resolve kolmafia

Method 1: Install using the kolmafia alias

This is the recommended method.

Install kolmafia-types using a package manager that supports package aliases:

# NPM >= 6.9.0, <= 7 (see notes)
npm install --save-dev kolmafia@npm:kolmafia-types

# Yarn >= 0.17.0
yarn add --dev kolmafia@npm:kolmafia-types

This installs kolmafia-types under the kolmafia alias.

Note: As of writing, NPM v7 has a bug that causes the npm outdated command to fail if you have an aliased package. If you cannot use package aliases, you may stick to NPM v6.x, or use the method below.

Method 2: Use a custom path to resolve kolmafia

To use this method, install kolmafia-types normally:

# NPM
npm install --save-dev kolmafia-types

# Yarn
yarn add --dev kolmafia-types

Then, add the paths field in your tsconfig.json:

{
  "compilerOptions": {
    // ...other options...
    "paths": {
      "kolmafia": ["./node_modules/kolmafia-types"]
    }
  }
}

This tells TypeScript to retrieve type definitions for kolmafia by looking at where kolmafia-types is installed.

Note: The actual path may be different, depending on where your tsconfig.json is, and your compilerOptions.baseUrl setting.

Usage

Type definitions for ASH scripts

kolmafia-types provides type definitions for some popular ASH scripts. See the /contrib directory for a list of available types.

To use them, add an entry for each ASH script in your tsconfig.json:

{
  "compilerOptions": {
    // ...
    "paths": {
      // Note: File names are case sensitive!
      "canadv.ash": ["./node_modules/kolmafia/contrib/canadv.ash"],
      "zlib.ash": ["./node_modules/kolmafia/contrib/zlib.ash"]
    }
  }
}

This allows TypeScript to type check functions imported from these ASH scripts:

// JavaScript
const {canAdv} = require('canadv.ash');
const {getvar, setvar} = require('zlib.ash');
// TypeScript, Babel, or other transpilers/bundlers
import {canAdv} from 'canadv.ash';
import {getvar, setvar} from 'zlib.ash';

setvar('my_var_1', 'some_value');
const value = getvar('my_var_2');
if (canAdv(Location.get('The Haunted Bedroom'), false)) {
  // ...
}

If you use a bundler, you may also need to add the ASH scripts as external modules. (See Using a bundler)

Using a bundler

Bundlers such as Webpack and Rollup can bundle all dependencies into a single file. However, kolmafia is a library that exists only inside KoLmafia's execution environment. Thus, you need to configure your bundler to ignore kolmafia.

Webpack:

// webpack.config.js
module.exports = {
  //...
  externals: {
    kolmafia: 'commonjs kolmafia',
    // Additional ASH scripts used in your code
    'canadv.ash': 'commonjs canadv.ash',
    'zlib.ash': 'commonjs zlib.ash',
  },
};

Rollup:

// rollup.config.js
export default {
  // ...
  external: [
    'kolmafia',
    // Additional ASH scripts used in your code
    'canadv.ash',
    'zlib.ash',
  ],
};

kolmafia-types's Issues

Stop using Node.js v10

Node.js v10 reaches EOL on 2021-04-30.

Things to do:

• Remove v10 from all GitHub workflows (#28)

Remove custom test script (and ts-node) when tsd is updated

In #20, I added a custom test script (run-tests.ts) to work around a limitation in tsd, our testing tool. Because tsd 0.14.0 does not support the typesVersions property in package.json, it cannot find our typings when invoked from the shell. Since it does not provide any mechanism for specifying a custom type source, we need to temporarily supply a types field in package.json.

To work around this, I wrote a tiny Node.js script (run-tests.ts) that monkey-patches package.json with a types field before running tsd, then restore the original afterwards. I also installed ts-node to avoid an extra compile step when running the script.

The main branch of tsd has recently gained support for custom type sources. Another PR adds an accompanying CLI option for this. If the next release of tsd includes these changes, we may be able to replace this script with an invocation of tsd --typings-file src/index.d.ts.

TODO

• Wait for a new release of tsd
• Update tsd
• Replace custom test script and invoke tsd from the command line instead
• Remove ts-node and/or @types/node

Add JSDoc comments to all KoLmafia functions

This is a tracking issue.

There are 690 KoLmafia library functions as of r20673 (overloaded forms are counted separately). Documenting them all is a mountainous task and may take several months.

I'm going to tackle them by dividing them into groups, each starting with an English letter:

Progress

• Functions that start with 'A' (28)
• Functions that start with 'B' (24)
• Functions that start with 'C' (50) (2972038)
• Functions that start with 'D' (19)
• Functions that start with 'E' (35) (#19)
• Functions that start with 'F' (20)
• Functions that start with 'G' (50)
• Functions that start with 'H' (22)
• Functions that start with 'I' (44)
• Functions that start with 'J' (8)
• Functions that start with 'K' (2)
• Functions that start with 'L' (16)
• Functions that start with 'M' (98)
• Functions that start with 'N' (10)
• Functions that start with 'O' (6)
• Functions that start with 'P' (45)
• Functions that start with 'Q' (0)
• Functions that start with 'R' (36)
• Functions that start with 'S' (54)
• Functions that start with 'T' (86)
• Functions that start with 'U' (16)
• Functions that start with 'V' (9)
• Functions that start with 'W' (11)
• Functions that start with 'X' (1)
• Functions that start with 'Y' (0)
• Functions that start with 'Z' (0)