@hitl-sdk/state-sqlite

SQLite-backed State for Hitl, built on Node's built-in node:sqlite. Zero runtime dependencies.

Requires Node.js 22.13.0+.

Install

npm install @hitl-sdk/hitl @hitl-sdk/state-sqlite

Setup

For most apps, no setup step is required. Constructing SqliteState runs migrations automatically (synchronous and idempotent):

import { DatabaseSync } from "node:sqlite";
import { SqliteState } from "@hitl-sdk/state-sqlite";

const state = new SqliteState(new DatabaseSync(".hitl/human_requests.db"));

See examples/hello-world for a lazy singleton pattern.

CLI (optional)

Use the CLI when you want to initialize a database file outside your app — CI, scripts, or infra that runs before the server starts:

npx @hitl-sdk/state-sqlite setup --db .hitl/human_requests.db
npx @hitl-sdk/state-sqlite setup --db .hitl/human_requests.db --table custom_approvals

Export DDL without opening a database:

npx @hitl-sdk/state-sqlite schema
npx @hitl-sdk/state-sqlite schema --table custom_approvals

Programmatically:

import { schemaSql, migrationSql, SCHEMA_VERSION } from "@hitl-sdk/state-sqlite";

schemaSql();
migrationSql("001_initial", "hitl.human_requests");

Usage

import { mkdirSync } from "node:fs";
import { join } from "node:path";
import { DatabaseSync } from "node:sqlite";
import { Hitl } from "@hitl-sdk/hitl";
import { SqliteState } from "@hitl-sdk/state-sqlite";

const dbPath = join(process.cwd(), ".hitl", "human_requests.db");
mkdirSync(join(process.cwd(), ".hitl"), { recursive: true });

const state = new SqliteState(new DatabaseSync(dbPath));

export const hitl = new Hitl({ state, /* resolver, adapters, … */ });

Migrations

Schema changes are versioned inside this package (SCHEMA_VERSION). Opening the database with SqliteState (or re-running setup) applies new migrations idempotently after you upgrade @hitl-sdk/state-sqlite.

Upgrading from the legacy default table hitl.approvals is handled automatically by migration 006_rename_human_requests when you use the new default hitl.human_requests. Custom --table names are not renamed automatically.