kolmafia-types

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:

• Install kolmafia-types using a kolmafia alias
• 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',
  ],
};