aoc-kit v1.1.6

aoc-kit

aoc-kit is a Node library / CLI built for Advent of Code. It takes care of downloading your specific program input for each task and enables automatic submission of your answers.

Installation

To install aoc-kit into your project, use your preferred package manger. In case of npm, run the following command:

npm install aoc-kit

This will allow you to import the defineSolution() method from within your code. However, you still need a way to run the CLI itself. You can do this by also installing the aoc-kit package globally after which you'll be able to execute commands by running:

aoc-kit [command] [args]

Alternatively, you can execute these commands without installing the package globally by prefixing them with npx and running them inside your project directory (e.g. npx aoc-kit run index.js).

Configuration

While there are multiple features of this tool that are able to function anonymously, the actual download of your custom input and submission of your answers will require authentication of your Advent of Code account.

In order to do that, you'll first need to obtain your session token. Start by visiting the official AoC website in your browser and logging into your account. Once logged in, inspect the website's cookies in your browser's developer tools. There, you should be able to see a cookie named session. Its value is the session token you're looking for.

Session token example in Chrome DevTools

Once you have the token, authenticate your account in the CLI by running:

aoc-kit login [token]

Analogically, you can also run aoc-kit logout to remove your account's authentication from the CLI.

Usage

When writing a solution, start by creating a .js (or .mjs) file with the following contents:

import { defineSolution } from 'aoc-kit';

export default defineSolution((input, solve, config) => {}, {});

Let's start off by focusing on the second argument of our defineSolution() method. This argument is a configuration object for how the CLI is supposed to behave while executing our code and is entirely optional as well as any of its properties. The supported properties are:

Most of these properties can also be set in the form of a CLI argument, instead of making them part of the JS code (more in the CLI Options section). If the same property is set in both places, the CLI argument serves as an override.

Now let's take a look at the first argument of the defineSolution() method. This one is a function whose body will contain our actual solution to the given task and it takes different 3 arguments. The first one named input contains the input data for the task and is either of type string or string[], depending on the lines property of our configuration object as described above.

The second argument is a function called solve(). This is a function we'll most likely be calling at the very end of our solution's code and its argument is the value we desire to submit as our final answer. The argument can either be of type string or number. This function must be called exactly once during the execution of our solution.

The last argument is an object named config. This object contains the entire configuration of the CLI during this execution. It combines values from the configuration object passed into the defineSolution() method as well as any overrides cause by additional CLI arguments. Its properties are mostly the same as in the case of the configuration object with the exception of a new input property of type string | null which contains the value passed with the --input flag of the CLI (more in the CLI Options section).

CLI Options

CLI flags for the aoc-kit run and aoc-kit submit comnmands:

Example

main.js:

import { defineSolution } from 'aoc-kit';

// Sums up all numbers in the input
export default defineSolution((input, solve) => {
  const nums = input.map(x => Number(x));
  const sum = nums.reduce((acc, x) => x + acc, 0);
  solve(sum);
}, { mode: 'lines' });

Terminal:

License

MIT