kolmafia-util

kolmafia-util

KoLmafia-util is a utility library for writing JavaScript/TypeScript programs that run inside KoLmafia.

It provides some useful features for writing JavaScript-based KoLmafia projects.

Installing

If your JavaScript project uses a bundler (Webpack, Rollup, etc.), use:

npm install kolmafia-util

Support for dependencies.txt is coming soon.

Usage

If you are using a bundler, you can import and use kolmafia-util like this:

import {sinceKolmafiaVersion} from 'kolmafia-util';

sinceKolmafiaVersion(20, 7);

API

The following is a list of functions and classes exported by kolmafia-util.

notifyProjectMaintainer()

function notifyProjectMaintainer(projectName: string, username: string): void;

This function combines the functionality of the script <name> and notify <player> statements in ASH. When executed, it sends a Kmail to the author (username) to notify them that you are using the project (projectName).

This function must be called inside the main() function:

// Bad
notifyProjectMaintainer('MyProject', 'SomePlayer123');

// OK
exports.main = function main() {
  notifyProjectMaintainer('MyProject', 'SomePlayer123');
};

sinceKolmafiaRevision()

function sinceKolmafiaRevision(revision: number): void;

This function checks KoLmafia's revision number against revision. If the current revision is smaller, it throws a KolmafiaVersionError containing a helpful error message. Otherwise, it does nothing.

This function is similar to the since statement in ASH. Specifically, it behaves like the since rXXX; statement.

Example:

import {sinceKolmafiaRevsion} from 'kolmafia-util';

// Ensure that KoLmafia's revision is at least r20505
sinceKolmafiaRevsion(20505);

sinceKolmafiaVersion()

function sinceKolmafiaVersion(majorVersion: number, minorVersion: number): void;

This function checks KoLmafia's version against majorVersion and minorVersion. If the current version is lesser, it throws a KolmafiaVersionError containing a helpful error message. Otherwise, it does nothing.

This function is similar to the since statement in ASH. Specifically, it behaves like the since XX.YY; statement.

Example:

import {sinceKolmafiaVersion} from 'kolmafia-util';

// Ensure that KoLmafia's version is at least v20.7
sinceKolmafiaVersion(20, 7);

KolmafiaVersionError

A custom error class used by sinceKolmafiaRevision() and sinceKolmafiaVersion(). You can use it with instanceof to manually handle version errors:

import {KolmafiaVersionError, sinceKolmafiaVersion} from 'kolmafia-util';

try {
  sinceKolmafiaVersion(20, 7);
} catch (err) {
  if (err instanceof KolmafiaVersionError) {
    // Your own code
  }
}

withDisabledFunctions()

Temporarily disable one or more ASH functions while executing a callback.

// Disables the userConfirm() function while executing the callback
const someValue = withDisabledFunctions('user_confirm', () => {
  /* ... */
  return someValue;
});

withFamiliar()

Temporarily changes the current familiar while executing a callback.

const someValue = withFamiliar(Familiar.get('Slimeling'), () => {
  /* ... */
  return someValue;
});

withFamiliarIfOwned()

Temporarily changes the current familiar only if you own it while executing a callback.

const someValue = withFamiliarIfOwned(Familiar.get('Slimeling'), () => {
  /* ... */
  return someValue;
});

withOutfitCheckpoint()

Saves your current outfit using the checkpoint gCLI command, executes a callback, then restores the saved outfit.

const someValue = withOutfitCheckpoint(() => {
  /* ... */
  return someValue;
});

Sending messages, items, and meat to other players

kmail(options)

Sends a Kmail to another player. The options object supports the following fields:

• recipent: Target player ID or username
• message: (optional) Message text
• meat: (optional) Amount of meat to send
• items: (optional) A Map which maps Items to send to their quantities. If more than 11 items are given, this function will attempt to send multiple Kmail messages.

This throws a KmailError upon failure.

kmail({
  recipent: 'sellbot',
  items: new Map([
    [Item.get('pail'), 5],
    [Item.get('seal tooth'), 1],
  ]),
});

sendGift(options)

Sends a gift message to another player. The options object supports the following fields:

• recipent: Target player ID or username
• message: (optional) Message text
• meat: (optional) Amount of meat to send, not including the cost of gift boxes themselves
• items: (optional) A Map which maps Items to send to their quantities. Multiple items will be sent in separate packages.
• insideNote: (optional) Message to put inside the gift box
• useStorage: (optional) If truthy, will send meat and items from Hagnk's instead of your inventory

This will always use the plain brown wrapper or the less-than-three-shaped-box to minimize the cost of packaging. Take care not to hit the daily limit of 100 gift boxes.

This throws a GiftError upon failure.

sendGift({
  recipent: 'sellbot',
  message: 'Hi there!',
  insideNote: 'With <3',
  meat: 100000,
  useStorage: true,
});

sendToPlayer(options)

Sends Kmail messages and gifts to another player. This combines kmail() and sendGift() into a single function call, intelligently deciding how to send each item.

The options object supports the following fields:

• recipent: Target player ID or username
• message: (optional) Message text
• meat: (optional) Amount of meat to send, not including the cost of gift boxes themselves
• items: (optional) A Map which maps Items to send to their quantities.
• insideNote: (optional) Message to put inside the gift box
• useStorage: (optional) If truthy, will send meat and items from Hagnk's instead of your inventory

This cannot send meat and items in Hagnk's. To do so, use sendGift() instead.

KmailError

A custom error class thrown when sending a Kmail fails.

GiftError

A custom error class thrown when sending a Kmail fails.

Assertion Library

kolmafia-util provides basic assertion functions for debugging your code. To use them, import the assert namespace object:

import {assert} from 'kolmafia-util';

assert.ok(someValue());

These assertion functions do not rely on KoLmafia's library functions. This makes them runnable in almost any JavaScript environment.

Note: These assertion functions are not fully fledged assertion libraries like Chai.

assert.ok(cond, [message])

Asserts that a condition is truthy. This also acts as a TypeScript type assertion, and can participate in type narrowing.

const a: string | null = getSomething();
assert.ok(a, 'a is falsy');
// This works because assert.ok() narrows the type of a to a string.
const b = a.toLowerCase();

assert.fail([message])

Throws an error, optionally with the given message.

assert.fail('This should be unreachable');

assert.equal(actual, expected, [message])

Asserts that actual is strictly equal (===) to expected.

assert.equal(someValue(), 'FOO');

assert.notEqual(actual, expected, [message])

Asserts that actual is strictly inequal (!==) to expected.

assert.notEqual(someValue(), null);

assert.isAtLeast(actual, expected, [message])

Asserts that actual is greater than or equal (>=) to expected.

assert.isAtLeast(someValue(), 50);

assert.isAtMost(actual, expected, [message])

Asserts that actual is less than or equal (>=) to expected.

assert.isAtMost(someValue(), 50);

assert.isAbove(actual, expected, [message])

Asserts that actual is greater than (>) expected.

assert.isAbove(someValue(), 50);

assert.isBelow(actual, expected, [message])

Asserts that actual is less than (<) expected.

assert.isBelow(someValue(), 50);

assert.AssertionError

An error class that is thrown by the assertion functions.