tome-kolmafia

Tome

Tome is a library written to support relay scripts for KoLmafia written in TypeScript with React.

It works as a drop-in replacement for the kolmafia typescript bindings, and allows use of libram. Any kolmafia function call will return a placeholder value on the first call, and then silently fetch the correct value in the background, triggering a UI refresh in React when that value arrives. Essentially, tome goes for eventual UI consistency.

Install

To get started, simply run yarn add tome-kolmafia. Afterwards, you'll need to do some hackery with your build system to get tome-kolmafia treated as kolmafia. Afterwards you'll be able to import functions as if from kolmafia, and even use libram in the browser!

The tome developers recommend using TypeScript and vite for your build system.

Usage

After that, there's a little more work to be done before you can fully benefit. You'll need to wrap your App on some level (above wherever you want to run libram/kolmafia functions) with a RefreshContextProvider. Then the rest of your app should be in a subcomponent of that context provider. A top-level component in your app needs to then call useContext(RefreshContext). By default, your app will refresh its data any time the main pane is navigated orwhenever key pieces of character state change.

How to get your build system to treat tome-kolmafia as kolmafia

TypeScript

If you are using TypeScript, you will need the following in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "kolmafia": ["./node_modules/tome-kolmafia/dist/kolmafia"]
    }
  }
}

vite

Add the following snippet to defineConfig in vite.config.ts:

defineConfig({
  // ...
  resolve: {
    alias: {
      kolmafia: path.resolve(
        __dirname,
        "node_modules/tome-kolmafia/dist/kolmafia/index.js",
      ),
    },
  },
  optimizeDeps: {
    include: ["kolmafia > dataloader", "tome-kolmafia > dataloader"],
    exclude: ["kolmafia", "tome-kolmafia"],
  },
  // ...
});

esbuild

Inside of your build call in your build script, make sure the value of alias contains kolmafia with the correct path. Example below.

build({
  alias: {
    kolmafia: path.resolve(
      __dirname,
      "node_modules/tome-kolmafia/dist/kolmafia/index.js",
    ),
  },
  ...remainingconfig,
});

Webpack

Hopefully someone who knows will fill this section in soon!

eslint-plugin-import

To configure eslint-plugin-import, install eslint-import-resolver-alias and include the following snippet in eslint.config.js:

settings: {
  "import/resolver": {
    alias: {
      map: [["kolmafia", "tome-kolmafia/dist/kolmafia"]],
    },
  },
},

Advanced Usage

The RefreshContextProvider that you wrap your app in can have its default refresh conditions overwritten via characterStateOverride. This should be provided with a callback that returns a Promise<Record<string, unknown>>. Any time the values in the record change, data will be refreshed. The default behavior if no characterStateOverride is provided is to refresh when your turn count, meat, hp, mp, equipment, familiar, or adventure count change.

Developer Setup

For testing actual development of tome itself, run yarn link /path/to/tome in the project that depends on tome.