kolmafia-util
v0.3.0
Published
Utility library for KoLmafia
Downloads
12
Readme
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 usernamemessage
: (optional) Message textmeat
: (optional) Amount of meat to senditems
: (optional) A Map which mapsItem
s 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 usernamemessage
: (optional) Message textmeat
: (optional) Amount of meat to send, not including the cost of gift boxes themselvesitems
: (optional) A Map which mapsItem
s to send to their quantities. Multiple items will be sent in separate packages.insideNote
: (optional) Message to put inside the gift boxuseStorage
: (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 usernamemessage
: (optional) Message textmeat
: (optional) Amount of meat to send, not including the cost of gift boxes themselvesitems
: (optional) A Map which mapsItem
s to send to their quantities.insideNote
: (optional) Message to put inside the gift boxuseStorage
: (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.