ngn

What is ngn?

ngn is a cron scheduler for JavaScript and TypeScript task files. Write tasks as plain files, run one command, and every run — status, logs, timings, key-value state — is recorded into one SQLite file. Each task also gets its own SQLite database, with nothing to configure. Read the history back with ngn sql from the terminal, or in a browser with ngnui.

Installation

One package. Install it globally, or run it without installing:

npm install -g @apisurf/ngn
ngn <command>

# or, without installing
npx @apisurf/ngn <command>

Add it to the project too, for the TaskContext and defineConfig types:

npm i @apisurf/ngn

Commands

ngn init            # ngn.config.ts + tasks/
ngn add scrape.ts   # tasks/scrape.ts, from a template
ngn run             # schedule every task  (Ctrl-C to stop)

Every command takes --root to point at a project other than the working directory. Quote your globs so the shell does not expand them.

run:single ignores ngn.config.ts entirely: no .env is loaded and the run database is :memory:, so nothing is recorded. To schedule one configured task, use ngn run --match.

Writing a task

A task file exports timing and task. task may also be the default export.

import { TaskContext } from "@apisurf/ngn";

export const timing = "*/5 * * * * *";

export const task = async (ctx: TaskContext) => {
  await ctx.log.info("fetching");

  const html = await fetch("https://example.com").then((res) => res.text());
  await ctx.kv.set("last-length", String(html.length));
};

Your file and its relative imports are bundled. Package imports are left alone and resolved from your own node_modules at run time, so the version you installed is the version that runs.

The context

Hooks

Four more optional exports run around task, each with the same context:

// Runs before task. Returning true records the run as skipped; no other hook fires
export const shouldSkip = async (ctx: TaskContext) => {
  return (await ctx.kv.get("paused")) === "1";
};

export const onSuccess = async (ctx: TaskContext) => {
  await ctx.log.info("scrape ok");
};

// The run is already recorded as a failure; the error is rethrown after this
export const onError = async (error: Error, ctx: TaskContext) => {
  await ctx.log.error(error.message);
};

// After success or failure. Not called on a skipped run
export const onComplete = async (ctx: TaskContext) => {};

Configuration

ngn.config.ts (or ngn.config.js), written by ngn init and typed by defineConfig:

import { defineConfig } from "@apisurf/ngn";

export default defineConfig({
  dbPath: "file:./ngn.sqlite",
  port: 4545,
  match: ["tasks/**/*.ts"],
  envFile: ".env",
});

Storing data with ctx.sqlite

Every task gets its own SQLite database. It lives next to the task file — tasks/scrape.ts writes to tasks/scrape.db — and the file is only created once the task actually uses it. This is your data, separate from the run history in dbPath.

export const task = async (ctx: TaskContext) => {
  await ctx.sqlite.execute("CREATE TABLE IF NOT EXISTS pages (url TEXT, seen TEXT)");
  await ctx.sqlite.execute("INSERT INTO pages (url, seen) VALUES (?, ?)", [
    "https://example.com",
    new Date().toISOString(),
  ]);

  const { rows } = await ctx.sqlite.execute("SELECT COUNT(*) AS n FROM pages");
  await ctx.log.info(`${rows[0].n} pages`);
};

A task can only reach databases inside its own folder — absolute paths and paths that climb out with .. are rejected. Connections are held open between runs and closed on shutdown.

Reading what your tasks did

Both readers open the file dbPath points at, so it must be a file: URL. Neither needs the scheduler running.

From the terminal

ngn sql passes any query straight to SQLite and prints a table, or --json / --csv. Rows go to stdout and counts to stderr, so piping into jq works. --db <file> queries a database without a config, and --max-width <n> sets where table cells are cut (default 60, 0 disables).

ngn sql "SELECT status, COUNT(*) FROM task_runs GROUP BY status"
ngn sql "SELECT * FROM logs WHERE status = 'error' ORDER BY id DESC" --json

ngn sql --help lists every column. Times are unix milliseconds. The tables:

In a browser

@apisurf/ngnui is a separate CLI that serves a dashboard over the same file.

npx @apisurf/ngnui --db ./ngn.sqlite --live http://127.0.0.1:4545

Its live task editor runs code through a running ngn run, which --live points at, on the config's port. That endpoint listens on loopback only. ngn run prints the exact line for your project when it starts. ngnui is a paid module; the scheduler itself is open source and never requires it.

Cron patterns

Six fields, seconds first. With five fields, tasks run at second 0.

┌────────────── second (0-59, optional)
│ ┌──────────── minute (0-59)
│ │ ┌────────── hour (0-23)
│ │ │ ┌──────── day of month (1-31)
│ │ │ │ ┌────── month (1-12 or jan-dec)
│ │ │ │ │ ┌──── day of week (0-7 or sun-sat, 0 and 7 are Sunday)
│ │ │ │ │ │
* * * * * *