npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

kolmafia-util

v0.3.0

Published

Utility library for KoLmafia

Downloads

12

Readme

kolmafia-util

Test & Lint status npm

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.