@awsmbiz/inbis-db 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @awsmbiz/inbis-db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+D1 + Drizzle helpers. Peer dependency: `drizzle-orm` ^0.45.4. No tenant columns and no
+generic repository: write queries with Drizzle in your own repository layer.
+
+## Database
+
+```ts
+import { createDatabase } from "@awsmbiz/inbis-db";
+import * as schema from "./schema";
+
+const db = createDatabase(env.DB, { schema }); // Drizzle D1 instance; db.query.* enabled by schema
+```
+
+Create it per request from the binding you were given. The options (`CreateDatabaseOptions`)
+take the Drizzle `schema`.
+
+## Columns
+
+```ts
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { idColumn, timestampColumns } from "@awsmbiz/inbis-db";
+
+export const widgets = sqliteTable("widgets", {
+  id: idColumn(),                 // TEXT PRIMARY KEY, UUIDv7 generated on insert
+  name: text("name").notNull(),
+  ...timestampColumns(),          // created_at / updated_at, epoch ms, as Date
+});
+```
+
+## Batch (atomic writes)
+
+D1 has no interactive transactions. `batch(db, [stmt, ...])` runs the statements
+all-or-nothing in one round trip and returns their typed results in order. An empty
+list returns `[]`. A unique-constraint violation becomes a `409 CONFLICT` `AppError`;
+other errors are rethrown unchanged.
+
+## Keyset pagination
+
+```ts
+import { gt } from "drizzle-orm";
+import { parsePageRequest, toPage } from "@awsmbiz/inbis-db";
+
+const page = parsePageRequest({ limit: query.limit, cursor: query.cursor }, { defaultLimit: 20, maxLimit: 100 });
+const rows = await db.select().from(widgets)
+  .where(page.after === undefined ? undefined : gt(widgets.id, page.after))
+  .orderBy(widgets.id)
+  .limit(page.fetchLimit);
+return toPage(rows, page, (w) => w.id); // { items, nextCursor: string | null }
+```
+
+Cursors are opaque. An invalid cursor gives `400 INVALID_CURSOR`, and an invalid limit
+(not a positive integer) gives `422 VALIDATION_FAILED`. Limits above `maxLimit` are clamped.
+
+## Migrations: the `inbis-db` CLI
+
+Platform packages that own tables ship their migrations. Each migration source is a D1
+binding to the app's one database, with its own `migrations_dir` and `migrations_table`
+(ADR-4, `docs/adr/0004-package-owned-migrations.md`). `inbis-db` is a Node bin that drives
+the app's `wrangler`. It keeps no history of its own.
+
+```sh
+inbis-db migrate [--local|--remote] [--env <env>] [--config <path>] [--persist-to <dir>]
+inbis-db status  [same options]
+inbis-db lock <dir>
+inbis-db check-lock <dir> [--base <git-ref>]
+```
+
+- **`migrate`** runs `wrangler d1 migrations apply <BINDING>` for each source of each
+  database, in `wrangler.jsonc` declaration order (platform bindings first, then the app). It
+  stops at the first failure, then prints the status table. It refuses to start if a file
+  locked in a source's `migrations.lock.json` has changed (checksum drift).
+- **`status`** prints, per source, every migration as `applied` or `pending`, plus any applied
+  migration whose file is missing:
+
+  ```
+  Migration status for D1 database "identity-playground-dev" (local):
+  binding  table                   migration              status
+  AUTH_DB  _inbis_auth_migrations  0001_auth_initial.sql  applied
+  DB       d1_migrations           0001_app_profile.sql   pending
+  1 applied, 1 pending
+  ```
+
+- **Timeout:** each wrangler run may take 5 minutes (`INBIS_DB_WRANGLER_TIMEOUT_MS` to
+  change it); a run past it is stopped and reported with its output so far (exit code 124),
+  so a hung wrangler cannot hang CI. Reading the status is one `wrangler d1 execute`
+  (two when a migrations table does not exist yet).
+- **Layout checks** (both commands): a binding may not be named like its database; bindings of
+  one `database_name` must resolve to the same database (share `database_id`); sources may not
+  share a migrations table or directory; `migrations_pattern` is not supported (use flat `*.sql`).
+- **`lock`** adds sha256 checksums for new `*.sql` files to `<dir>/migrations.lock.json` and
+  refuses if a locked file changed. **`check-lock`** fails on drift, deleted or unlocked files.
+  With `--base`, it also fails if any entry locked at that git ref (the released migrations)
+  changed, even when the lock was edited too.
+
+Requires `wrangler` (optional peer dependency, ^4.156.0) in the app.

package/dist/cli.mjs

@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { createHash } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+// cli/src/errors.ts
+/** An expected failure: printed without a stack trace, exit code 1. */
+var CliError = class extends Error {
+	name = "CliError";
+};
+// cli/src/sources.ts
+const DEFAULT_MIGRATIONS_TABLE = "d1_migrations";
+/** The database a binding resolves to, mirroring wrangler (local: preview id, then id, then binding). */
+function databaseKey(entry, target) {
+	return target === "local" ? entry.preview_database_id ?? entry.database_id ?? entry.binding : entry.database_id ?? entry.binding;
+}
+/**
+* Groups the config's D1 bindings by physical database, keeping declaration
+* order (declare platform bindings before the app's). Rejects layouts where
+* histories would collide or bindings silently miss each other (ADR-4).
+*/
+function databaseSources(config, target) {
+	const base = dirname(config.configPath ?? ".");
+	const groups = /* @__PURE__ */ new Map();
+	const keyByName = /* @__PURE__ */ new Map();
+	for (const entry of config.d1_databases) {
+		const name = entry.database_name ?? entry.binding;
+		if (entry.binding === entry.database_name) throw new CliError(`D1 binding "${entry.binding}" has the same name as its database. Rename the binding: commands target bindings, and a database name always selects the first binding.`);
+		if (entry.migrations_pattern !== void 0) throw new CliError(`D1 binding "${entry.binding}" sets migrations_pattern, which inbis-db does not support. Use flat *.sql files in migrations_dir.`);
+		const key = databaseKey(entry, target);
+		const knownKey = keyByName.get(name);
+		if (knownKey !== void 0 && knownKey !== key) throw new CliError(`D1 bindings for database "${name}" resolve to different ${target} databases. Give every binding of one database the same database_id.`);
+		keyByName.set(name, key);
+		const group = groups.get(key) ?? {
+			database: name,
+			sources: []
+		};
+		groups.set(key, group);
+		const source = {
+			binding: entry.binding,
+			table: entry.migrations_table ?? DEFAULT_MIGRATIONS_TABLE,
+			dir: resolve(base, entry.migrations_dir ?? "migrations")
+		};
+		for (const other of group.sources) {
+			if (other.table === source.table) throw new CliError(`D1 bindings "${other.binding}" and "${source.binding}" share the migrations table "${source.table}". Each migration source needs its own migrations_table.`);
+			if (other.dir === source.dir) throw new CliError(`D1 bindings "${other.binding}" and "${source.binding}" share the migrations directory ${source.dir}.`);
+		}
+		group.sources.push(source);
+	}
+	return [...groups.values()];
+}
+/** Migration file names in a source, in apply order (the files wrangler applies). */
+function migrationFiles(source) {
+	if (!existsSync(source.dir)) return [];
+	return readdirSync(source.dir, { withFileTypes: true }).filter((entry) => entry.isFile() && !entry.name.startsWith(".") && entry.name.endsWith(".sql")).map((entry) => entry.name).sort();
+}
+// cli/src/lock.ts
+const LOCK_FILE = "migrations.lock.json";
+/** sha256 of a migration file; line endings are normalised so checkouts on any OS agree. */
+function checksum(contents) {
+	return `sha256:${createHash("sha256").update(contents.replaceAll("\r\n", "\n")).digest("hex")}`;
+}
+function readLock(dir) {
+	const path = join(dir, LOCK_FILE);
+	return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : void 0;
+}
+/** Problems with locked files: changed (drift) or deleted. */
+function lockDrift(dir, lock) {
+	return Object.entries(lock).flatMap(([name, expected]) => {
+		const path = join(dir, name);
+		if (!existsSync(path)) return [`${name} is locked but missing`];
+		return checksum(readFileSync(path, "utf8")) === expected ? [] : [`${name} changed after it was locked (checksum drift)`];
+	});
+}
+/** Every problem `check-lock` reports: drift, deleted files and files missing from the lock. */
+function lockProblems(dir, lock) {
+	const unlocked = migrationFiles({
+		binding: "",
+		table: "",
+		dir
+	}).filter((name) => !(name in lock)).map((name) => `${name} is not in ${LOCK_FILE}; run inbis-db lock`);
+	return [...lockDrift(dir, lock), ...unlocked];
+}
+/** Adds checksums for new migration files. Refuses if a locked file has changed. */
+function updateLock(dir) {
+	const lock = readLock(dir) ?? {};
+	const drift = lockDrift(dir, lock);
+	if (drift.length > 0) throw new CliError(`Cannot update ${LOCK_FILE}:\n  ${drift.join("\n  ")}`);
+	const added = migrationFiles({
+		binding: "",
+		table: "",
+		dir
+	}).filter((name) => !(name in lock));
+	for (const name of added) lock[name] = checksum(readFileSync(join(dir, name), "utf8"));
+	const sorted = Object.fromEntries(Object.entries(lock).sort(([a], [b]) => a.localeCompare(b)));
+	writeFileSync(join(dir, LOCK_FILE), `${JSON.stringify(sorted, null, 2)}\n`);
+	return { added };
+}
+function git(dir, args) {
+	return execFileSync("git", args, {
+		cwd: dir,
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+}
+/**
+* Released-migration guard: every entry in the lock at `baseRef` (e.g. the
+* default branch) must still be present and unchanged, so editing a released
+* file together with its lock entry is still caught.
+*/
+function releasedChanges(dir, lock, baseRef) {
+	try {
+		git(dir, [
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`${baseRef}^{commit}`
+		]);
+	} catch {
+		throw new CliError(`Base ref "${baseRef}" not found. Fetch it first (git fetch origin <branch>).`);
+	}
+	let released;
+	try {
+		released = JSON.parse(git(dir, ["show", `${baseRef}:./${LOCK_FILE}`]));
+	} catch {
+		return [];
+	}
+	return Object.entries(released).flatMap(([name, expected]) => lock[name] === expected ? [] : [`${name} was released at ${baseRef} and must not change (add a new migration instead)`]);
+}
+// cli/src/status.ts
+function quoteIdentifier(name) {
+	return `"${name.replaceAll("\"", "\"\"")}"`;
+}
+function quoteLiteral(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+async function execute(wrangler, binding, sql, target) {
+	return wrangler.exec([
+		"d1",
+		"execute",
+		binding,
+		"--json",
+		"--command",
+		sql,
+		...target
+	]);
+}
+function rowsOf(stdout) {
+	return JSON.parse(stdout).flatMap((statement) => statement.results);
+}
+async function query(wrangler, binding, sql, target) {
+	const result = await execute(wrangler, binding, sql, target);
+	if (result.code !== 0) throw new CliError(`wrangler d1 execute ${binding} failed:
+${result.stdout}${result.stderr}`);
+	return rowsOf(result.stdout);
+}
+const appliedSql = (sources) => sources.map((source) => `SELECT ${quoteLiteral(source.binding)} AS binding, name FROM ${quoteIdentifier(source.table)}`).join(" UNION ALL ");
+/**
+* The applied migrations of every source. Usually one wrangler run (each run
+* is a cold start): every tracking table is read at once. Only when one does
+* not exist yet (never migrated) are the existing tables looked up first.
+*/
+async function readApplied(wrangler, database, binding, target) {
+	const all = await execute(wrangler, binding, appliedSql(database.sources), target);
+	if (all.code === 0) return rowsOf(all.stdout);
+	if (!/no such table/i.test(`${all.stdout}${all.stderr}`)) throw new CliError(`wrangler d1 execute ${binding} failed:
+${all.stdout}${all.stderr}`);
+	const tables = new Set((await query(wrangler, binding, "SELECT name FROM sqlite_master WHERE type = 'table'", target)).map((row) => row.name));
+	const tracked = database.sources.filter((source) => tables.has(source.table));
+	return tracked.length === 0 ? [] : query(wrangler, binding, appliedSql(tracked), target);
+}
+/** Applied and pending migrations of every source of one database, read through wrangler. */
+async function readStatus(wrangler, database, target) {
+	const [first] = database.sources;
+	if (first === void 0) return [];
+	const applied = await readApplied(wrangler, database, first.binding, target);
+	return database.sources.flatMap((source) => {
+		const appliedHere = new Set(applied.filter((row) => row.binding === source.binding).map((row) => row.name));
+		const files = migrationFiles(source);
+		const rows = files.map((migration) => ({
+			binding: source.binding,
+			table: source.table,
+			migration,
+			status: appliedHere.has(migration) ? "applied" : "pending"
+		}));
+		for (const migration of appliedHere) if (!files.includes(migration)) rows.push({
+			binding: source.binding,
+			table: source.table,
+			migration,
+			status: "applied, file missing"
+		});
+		return rows;
+	});
+}
+/** Renders the status as an aligned plain-text table (stable for CI logs and tests). */
+function formatStatus(database, target, rows) {
+	const header = [
+		"binding",
+		"table",
+		"migration",
+		"status"
+	];
+	const cells = [header, ...rows.map((row) => [
+		row.binding,
+		row.table,
+		row.migration,
+		row.status
+	])];
+	const widths = header.map((_, column) => Math.max(...cells.map((line) => line[column]?.length ?? 0)));
+	const lines = cells.map((line) => line.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd());
+	const pending = rows.filter((row) => row.status === "pending").length;
+	return [
+		`Migration status for D1 database "${database}" (${target}):`,
+		...lines,
+		`${rows.length - pending} applied, ${pending} pending`,
+		""
+	].join("\n");
+}
+// cli/src/wrangler.ts
+/**
+* Locates the application's wrangler: the one installed next to its config,
+* falling back to the one installed with this package.
+*/
+function resolveWrangler(fromDir) {
+	for (const base of [join(fromDir, "noop.js"), import.meta.url]) try {
+		const require = createRequire(base);
+		return {
+			root: dirname(require.resolve("wrangler/package.json")),
+			main: require.resolve("wrangler")
+		};
+	} catch {}
+	throw new Error("wrangler is not installed. Add it to your app: pnpm add -D wrangler");
+}
+/**
+* How long one wrangler run may take (default 5 min, room for a slow remote
+* `migrations apply`). Override with `INBIS_DB_WRANGLER_TIMEOUT_MS`.
+*/
+const DEFAULT_WRANGLER_TIMEOUT_MS = 3e5;
+function timeoutFromEnv() {
+	const value = Number(process.env["INBIS_DB_WRANGLER_TIMEOUT_MS"]);
+	return Number.isInteger(value) && value > 0 ? value : DEFAULT_WRANGLER_TIMEOUT_MS;
+}
+var Wrangler = class {
+	#root;
+	#main;
+	#cwd;
+	#timeoutMs;
+	constructor(cwd, { timeoutMs = timeoutFromEnv() } = {}) {
+		this.#cwd = cwd;
+		this.#timeoutMs = timeoutMs;
+		({root: this.#root, main: this.#main} = resolveWrangler(cwd));
+	}
+	async readConfig(configPath, env) {
+		return (await import(pathToFileURL(this.#main).href)).unstable_readConfig(env === void 0 ? { config: configPath } : {
+			config: configPath,
+			env
+		}, { hideWarnings: true });
+	}
+	/**
+	* Runs `wrangler <args>`; resolves with its exit code and combined output. A
+	* run that exceeds the timeout is stopped (SIGTERM, then SIGKILL) and resolves
+	* with code {@link TIMED_OUT_CODE}, its output so far and a note in `stderr`.
+	*/
+	exec(args) {
+		return new Promise((resolve, reject) => {
+			const child = spawn(process.execPath, [join(this.#root, "bin", "wrangler.js"), ...args], {
+				cwd: this.#cwd,
+				env: {
+					...process.env,
+					WRANGLER_SEND_METRICS: "false",
+					FORCE_COLOR: "0"
+				},
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+			let stdout = "";
+			let stderr = "";
+			let timedOut = false;
+			let kill;
+			const timer = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGTERM");
+				kill = setTimeout(() => child.kill("SIGKILL"), 5e3);
+			}, this.#timeoutMs);
+			child.stdout.on("data", (chunk) => {
+				stdout += chunk.toString();
+			});
+			child.stderr.on("data", (chunk) => {
+				stderr += chunk.toString();
+			});
+			child.on("error", (error) => {
+				clearTimeout(timer);
+				clearTimeout(kill);
+				reject(error);
+			});
+			child.on("close", (code) => {
+				clearTimeout(timer);
+				clearTimeout(kill);
+				if (!timedOut) {
+					resolve({
+						code: code ?? 1,
+						stdout,
+						stderr
+					});
+					return;
+				}
+				const note = `wrangler ${args.join(" ")} did not finish within ${this.#timeoutMs / 1e3} s and was stopped.`;
+				resolve({
+					code: 124,
+					stdout,
+					stderr: `${stderr}${stderr === "" || stderr.endsWith("\n") ? "" : "\n"}${note}\n`
+				});
+			});
+		});
+	}
+};
+// cli/src/run.ts
+const USAGE = `Usage: inbis-db <command> [options]
+
+Commands:
+  migrate      Apply every migration source of each D1 database in declaration
+               order (platform bindings first, then the app), then print the status.
+  status       Print applied and pending migrations per source.
+  lock <dir>   Add checksums of new migration files to <dir>/migrations.lock.json.
+  check-lock <dir> [--base <git-ref>]
+               Fail if a locked migration changed or was deleted, a file is not
+               locked, or (with --base) a migration locked at <git-ref> changed.
+
+  migrate refuses to run if a locked migration file has changed.
+
+Options:
+  --local | --remote     Target local (default) or remote D1.
+  --env <name>           Wrangler environment.
+  --config <path>        Wrangler config (default: wrangler.jsonc/.json/.toml in cwd).
+  --persist-to <dir>     Local D1 state directory (wrangler --persist-to).
+`;
+const options = {
+	local: { type: "boolean" },
+	remote: { type: "boolean" },
+	env: { type: "string" },
+	config: { type: "string" },
+	"persist-to": { type: "string" },
+	base: { type: "string" },
+	help: {
+		type: "boolean",
+		short: "h"
+	}
+};
+function findConfig(cwd, explicit) {
+	if (explicit !== void 0) return resolve(cwd, explicit);
+	for (const name of [
+		"wrangler.jsonc",
+		"wrangler.json",
+		"wrangler.toml"
+	]) if (existsSync(join(cwd, name))) return join(cwd, name);
+	throw new CliError(`No wrangler config found in ${cwd}. Pass --config <path>.`);
+}
+async function context(values, io) {
+	if (values.local === true && values.remote === true) throw new CliError("Pass either --local or --remote, not both.");
+	const target = values.remote === true ? "remote" : "local";
+	const configPath = findConfig(io.cwd, values.config);
+	const wrangler = new Wrangler(io.cwd);
+	const config = await wrangler.readConfig(configPath, values.env);
+	const targetArgs = [
+		`--${target}`,
+		"--config",
+		configPath
+	];
+	if (values.env !== void 0) targetArgs.push("--env", values.env);
+	if (values["persist-to"] !== void 0) targetArgs.push("--persist-to", resolve(io.cwd, values["persist-to"]));
+	return {
+		io,
+		wrangler,
+		target,
+		databases: databaseSources(config, target),
+		targetArgs
+	};
+}
+async function printStatus(ctx, database) {
+	const rows = await readStatus(ctx.wrangler, database, ctx.targetArgs);
+	ctx.io.stdout(formatStatus(database.database, ctx.target, rows));
+	return rows;
+}
+async function migrate(ctx) {
+	let failed = false;
+	for (const database of ctx.databases) {
+		const drift = database.sources.flatMap((source) => {
+			const lock = readLock(source.dir);
+			return lock === void 0 ? [] : lockDrift(source.dir, lock).map((problem) => `${source.binding}: ${problem}`);
+		});
+		if (drift.length > 0) {
+			ctx.io.stderr(`Refusing to migrate "${database.database}"; locked migrations differ from ${LOCK_FILE}:\n  ${drift.join("\n  ")}\n`);
+			failed = true;
+		}
+		for (const source of database.sources) {
+			if (failed) break;
+			if (migrationFiles(source).length === 0) continue;
+			ctx.io.stdout(`Applying ${source.binding} migrations (${source.table})...\n`);
+			const result = await ctx.wrangler.exec([
+				"d1",
+				"migrations",
+				"apply",
+				source.binding,
+				...ctx.targetArgs
+			]);
+			if (result.code !== 0) {
+				ctx.io.stderr(`${result.stdout}${result.stderr}\nApplying ${source.binding} migrations failed; later sources were not applied.\n`);
+				failed = true;
+			}
+		}
+		await printStatus(ctx, database);
+	}
+	return failed ? 1 : 0;
+}
+function lockDir(positionals, io) {
+	const dir = positionals[1];
+	if (dir === void 0) throw new CliError("Pass the migrations directory.");
+	return resolve(io.cwd, dir);
+}
+function lock(positionals, io) {
+	const { added } = updateLock(lockDir(positionals, io));
+	io.stdout(added.length === 0 ? "Lock is up to date.\n" : `Locked ${added.join(", ")}.\n`);
+	return 0;
+}
+function checkLock(positionals, values, io) {
+	const dir = lockDir(positionals, io);
+	const current = readLock(dir);
+	if (current === void 0) throw new CliError(`${join(dir, LOCK_FILE)} not found; run inbis-db lock.`);
+	const problems = [...lockProblems(dir, current), ...values.base === void 0 ? [] : releasedChanges(dir, current, values.base)];
+	if (problems.length > 0) {
+		io.stderr(`Migration lock check failed for ${dir}:\n  ${problems.join("\n  ")}\n`);
+		return 1;
+	}
+	io.stdout(`${Object.keys(current).length} locked migrations unchanged in ${dir}.\n`);
+	return 0;
+}
+async function status(ctx) {
+	for (const database of ctx.databases) await printStatus(ctx, database);
+	return 0;
+}
+/** Runs the inbis-db CLI with `argv` (without node and script); resolves with the exit code. */
+async function run(argv, io) {
+	try {
+		const { values, positionals } = parseArgs({
+			args: argv,
+			options,
+			allowPositionals: true
+		});
+		const [command] = positionals;
+		if (values.help === true || command === void 0) {
+			io.stdout(USAGE);
+			return command === void 0 && values.help !== true ? 1 : 0;
+		}
+		switch (command) {
+			case "migrate": return await migrate(await context(values, io));
+			case "status": return await status(await context(values, io));
+			case "lock": return lock(positionals, io);
+			case "check-lock": return checkLock(positionals, values, io);
+			default: throw new CliError(`Unknown command "${command}".\n\n${USAGE}`);
+		}
+	} catch (error) {
+		if (error instanceof CliError || error instanceof TypeError && "code" in error) {
+			io.stderr(`inbis-db: ${error.message}\n`);
+			return 1;
+		}
+		throw error;
+	}
+}
+// cli/src/main.ts
+process.exitCode = await run(process.argv.slice(2), {
+	cwd: process.cwd(),
+	stdout: (text) => process.stdout.write(text),
+	stderr: (text) => process.stderr.write(text)
+});
+export {};

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { DrizzleD1Database } from "drizzle-orm/d1";
+import { BatchItem, BatchResponse } from "drizzle-orm/batch";
+type Database<TSchema extends Record<string, unknown> = Record<string, never>> = DrizzleD1Database<TSchema>;
+interface CreateDatabaseOptions<TSchema extends Record<string, unknown>> {
+  /** Drizzle tables (and relations) to enable the `db.query.*` API for. */
+  schema?: TSchema;
+}
+/**
+ * Wraps a D1 binding in a Drizzle instance. Create one per request from the
+ * binding you were given; never read bindings from globals.
+ */
+export declare function createDatabase<TSchema extends Record<string, unknown> = Record<string, never>>(d1: D1Database, options?: CreateDatabaseOptions<TSchema>): Database<TSchema>;
+/**
+ * Runs statements atomically in one D1 round trip. D1 has no interactive
+ * transactions, so this is the way to make several writes all-or-nothing.
+ *
+ * Unique-constraint violations become a 409 `CONFLICT` {@link AppError};
+ * other database errors are rethrown unchanged.
+ */
+export declare function batch<TSchema extends Record<string, unknown>, const T extends readonly BatchItem<"sqlite">[]>(db: Database<TSchema>, statements: T): Promise<BatchResponse<T>>;
+/** Text primary key filled with a time-ordered UUIDv7 (see `createId` in `@awsmbiz/inbis-core`). */
+export declare function idColumn(name?: string): import("drizzle-orm").HasRuntimeDefault<import("drizzle-orm").HasDefault<import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<string, [string, ...string[]], number | undefined>>>>>;
+/**
+ * `createdAt` / `updatedAt` columns (`created_at` / `updated_at`, epoch
+ * milliseconds). Both are set on insert; `updatedAt` is refreshed on update.
+ */
+export declare function timestampColumns(): {
+  createdAt: import("drizzle-orm").HasRuntimeDefault<import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTimestampBuilderInitial<"created_at">>>>;
+  updatedAt: import("drizzle-orm").HasDefault<import("drizzle-orm").HasRuntimeDefault<import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTimestampBuilderInitial<"updated_at">>>>>;
+};
+/** Raw paging input, typically straight from the query string. */
+interface PageInput {
+  limit?: string | number | undefined;
+  cursor?: string | undefined;
+}
+interface PageOptions {
+  /** Items per page when no limit is given. Default 20. */
+  defaultLimit?: number;
+  /** Larger limits are clamped to this. Default 100. */
+  maxLimit?: number;
+}
+interface PageRequest {
+  /** Items to return. */
+  limit: number;
+  /** Rows to fetch: `limit + 1`, so {@link toPage} can tell whether more exist. */
+  fetchLimit: number;
+  /** Sort key of the last item on the previous page; fetch rows strictly after it. */
+  after: string | undefined;
+}
+interface Page<T> {
+  items: T[];
+  /** Opaque cursor for the next page, or `null` on the last page. */
+  nextCursor: string | null;
+}
+/**
+ * Validates paging input for keyset pagination over a unique, ordered key
+ * (e.g. a UUIDv7 `id`). Query `WHERE key > after ORDER BY key LIMIT fetchLimit`,
+ * then pass the rows to {@link toPage}.
+ */
+export declare function parsePageRequest(input: PageInput, options?: PageOptions): PageRequest;
+/** Trims the extra fetched row and derives the next cursor from the last item's key. */
+export declare function toPage<T>(rows: T[], request: PageRequest, keyOf: (row: T) => string): Page<T>;
+export type { CreateDatabaseOptions, Database, Page, PageInput, PageOptions, PageRequest };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,105 @@
+import { AppError, createId, validationFailed } from "@awsmbiz/inbis-core";
+import { integer, text } from "drizzle-orm/sqlite-core";
+import { drizzle } from "drizzle-orm/d1";
+// src/batch.ts
+/**
+* Runs statements atomically in one D1 round trip. D1 has no interactive
+* transactions, so this is the way to make several writes all-or-nothing.
+*
+* Unique-constraint violations become a 409 `CONFLICT` {@link AppError};
+* other database errors are rethrown unchanged.
+*/
+async function batch(db, statements) {
+	if (statements.length === 0) return [];
+	try {
+		return await db.batch.bind(db)(statements);
+	} catch (error) {
+		throw toAppError(error);
+	}
+}
+function toAppError(error) {
+	for (let current = error; current instanceof Error; current = current.cause) if (current.message.includes("UNIQUE constraint failed")) return new AppError({
+		code: "CONFLICT",
+		status: 409,
+		message: "The resource already exists.",
+		cause: error
+	});
+	return error;
+}
+// src/columns.ts
+/** Text primary key filled with a time-ordered UUIDv7 (see `createId` in `@awsmbiz/inbis-core`). */
+function idColumn(name = "id") {
+	return text(name).primaryKey().$defaultFn(() => createId());
+}
+/**
+* `createdAt` / `updatedAt` columns (`created_at` / `updated_at`, epoch
+* milliseconds). Both are set on insert; `updatedAt` is refreshed on update.
+*/
+function timestampColumns() {
+	return {
+		createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull().$defaultFn(() => /* @__PURE__ */ new Date()),
+		updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull().$defaultFn(() => /* @__PURE__ */ new Date()).$onUpdateFn(() => /* @__PURE__ */ new Date())
+	};
+}
+// src/database.ts
+/**
+* Wraps a D1 binding in a Drizzle instance. Create one per request from the
+* binding you were given; never read bindings from globals.
+*/
+function createDatabase(d1, options = {}) {
+	return options.schema === void 0 ? drizzle(d1) : drizzle(d1, { schema: options.schema });
+}
+// src/pagination.ts
+/**
+* Validates paging input for keyset pagination over a unique, ordered key
+* (e.g. a UUIDv7 `id`). Query `WHERE key > after ORDER BY key LIMIT fetchLimit`,
+* then pass the rows to {@link toPage}.
+*/
+function parsePageRequest(input, options = {}) {
+	const maxLimit = options.maxLimit ?? 100;
+	const limit = Math.min(parseLimit(input.limit, options.defaultLimit ?? 20), maxLimit);
+	const after = input.cursor === void 0 || input.cursor === "" ? void 0 : decodeCursor(input.cursor);
+	return {
+		limit,
+		fetchLimit: limit + 1,
+		after
+	};
+}
+/** Trims the extra fetched row and derives the next cursor from the last item's key. */
+function toPage(rows, request, keyOf) {
+	const items = rows.slice(0, request.limit);
+	const last = items.at(-1);
+	return {
+		items,
+		nextCursor: rows.length > request.limit && last !== void 0 ? encodeCursor(keyOf(last)) : null
+	};
+}
+function parseLimit(raw, fallback) {
+	if (raw === void 0 || raw === "") return fallback;
+	const value = typeof raw === "number" ? raw : Number(raw);
+	if (!Number.isInteger(value) || value < 1) throw validationFailed([{
+		path: ["limit"],
+		message: "Must be a positive integer."
+	}]);
+	return value;
+}
+function encodeCursor(key) {
+	const bytes = new TextEncoder().encode(JSON.stringify({ k: key }));
+	return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeCursor(cursor) {
+	try {
+		const binary = atob(cursor.replaceAll("-", "+").replaceAll("_", "/"));
+		const json = new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)));
+		const parsed = JSON.parse(json);
+		if (typeof parsed === "object" && parsed !== null && "k" in parsed && typeof parsed.k === "string") return parsed.k;
+	} catch {}
+	throw new AppError({
+		code: "INVALID_CURSOR",
+		status: 400,
+		message: "The page cursor is invalid."
+	});
+}
+export { batch, createDatabase, idColumn, parsePageRequest, timestampColumns, toPage };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/batch.ts","../src/columns.ts","../src/database.ts","../src/pagination.ts"],"sourcesContent":["import { AppError } from \"@awsmbiz/inbis-core\";\nimport type { BatchItem, BatchResponse } from \"drizzle-orm/batch\";\nimport type { Database } from \"./database.js\";\n\n/**\n * Runs statements atomically in one D1 round trip. D1 has no interactive\n * transactions, so this is the way to make several writes all-or-nothing.\n *\n * Unique-constraint violations become a 409 `CONFLICT` {@link AppError};\n * other database errors are rethrown unchanged.\n */\nexport async function batch<\n  TSchema extends Record<string, unknown>,\n  const T extends readonly BatchItem<\"sqlite\">[],\n>(db: Database<TSchema>, statements: T): Promise<BatchResponse<T>> {\n  if (statements.length === 0) return [] as BatchResponse<T>;\n  try {\n    const run = db.batch.bind(db) as unknown as (items: T) => Promise<BatchResponse<T>>;\n    return await run(statements);\n  } catch (error) {\n    throw toAppError(error);\n  }\n}\n\nfunction toAppError(error: unknown): unknown {\n  for (let current: unknown = error; current instanceof Error; current = current.cause) {\n    if (current.message.includes(\"UNIQUE constraint failed\")) {\n      return new AppError({\n        code: \"CONFLICT\",\n        status: 409,\n        message: \"The resource already exists.\",\n        cause: error,\n      });\n    }\n  }\n  return error;\n}\n","import { createId } from \"@awsmbiz/inbis-core\";\nimport { integer, text } from \"drizzle-orm/sqlite-core\";\n\n/** Text primary key filled with a time-ordered UUIDv7 (see `createId` in `@awsmbiz/inbis-core`). */\nexport function idColumn(name = \"id\") {\n  return text(name)\n    .primaryKey()\n    .$defaultFn(() => createId());\n}\n\n/**\n * `createdAt` / `updatedAt` columns (`created_at` / `updated_at`, epoch\n * milliseconds). Both are set on insert; `updatedAt` is refreshed on update.\n */\nexport function timestampColumns() {\n  return {\n    createdAt: integer(\"created_at\", { mode: \"timestamp_ms\" })\n      .notNull()\n      .$defaultFn(() => new Date()),\n    updatedAt: integer(\"updated_at\", { mode: \"timestamp_ms\" })\n      .notNull()\n      .$defaultFn(() => new Date())\n      .$onUpdateFn(() => new Date()),\n  };\n}\n","import { drizzle, type DrizzleD1Database } from \"drizzle-orm/d1\";\n\nexport type Database<TSchema extends Record<string, unknown> = Record<string, never>> =\n  DrizzleD1Database<TSchema>;\n\nexport interface CreateDatabaseOptions<TSchema extends Record<string, unknown>> {\n  /** Drizzle tables (and relations) to enable the `db.query.*` API for. */\n  schema?: TSchema;\n}\n\n/**\n * Wraps a D1 binding in a Drizzle instance. Create one per request from the\n * binding you were given; never read bindings from globals.\n */\nexport function createDatabase<TSchema extends Record<string, unknown> = Record<string, never>>(\n  d1: D1Database,\n  options: CreateDatabaseOptions<TSchema> = {},\n): Database<TSchema> {\n  return options.schema === undefined\n    ? (drizzle(d1))\n    : drizzle(d1, { schema: options.schema });\n}\n","import { AppError, validationFailed } from \"@awsmbiz/inbis-core\";\n\n/** Raw paging input, typically straight from the query string. */\nexport interface PageInput {\n  limit?: string | number | undefined;\n  cursor?: string | undefined;\n}\n\nexport interface PageOptions {\n  /** Items per page when no limit is given. Default 20. */\n  defaultLimit?: number;\n  /** Larger limits are clamped to this. Default 100. */\n  maxLimit?: number;\n}\n\nexport interface PageRequest {\n  /** Items to return. */\n  limit: number;\n  /** Rows to fetch: `limit + 1`, so {@link toPage} can tell whether more exist. */\n  fetchLimit: number;\n  /** Sort key of the last item on the previous page; fetch rows strictly after it. */\n  after: string | undefined;\n}\n\nexport interface Page<T> {\n  items: T[];\n  /** Opaque cursor for the next page, or `null` on the last page. */\n  nextCursor: string | null;\n}\n\n/**\n * Validates paging input for keyset pagination over a unique, ordered key\n * (e.g. a UUIDv7 `id`). Query `WHERE key > after ORDER BY key LIMIT fetchLimit`,\n * then pass the rows to {@link toPage}.\n */\nexport function parsePageRequest(input: PageInput, options: PageOptions = {}): PageRequest {\n  const maxLimit = options.maxLimit ?? 100;\n  const limit = Math.min(parseLimit(input.limit, options.defaultLimit ?? 20), maxLimit);\n  const after = input.cursor === undefined || input.cursor === \"\" ? undefined : decodeCursor(input.cursor);\n  return { limit, fetchLimit: limit + 1, after };\n}\n\n/** Trims the extra fetched row and derives the next cursor from the last item's key. */\nexport function toPage<T>(rows: T[], request: PageRequest, keyOf: (row: T) => string): Page<T> {\n  const items = rows.slice(0, request.limit);\n  const last = items.at(-1);\n  const hasMore = rows.length > request.limit && last !== undefined;\n  return { items, nextCursor: hasMore ? encodeCursor(keyOf(last)) : null };\n}\n\nfunction parseLimit(raw: string | number | undefined, fallback: number): number {\n  if (raw === undefined || raw === \"\") return fallback;\n  const value = typeof raw === \"number\" ? raw : Number(raw);\n  if (!Number.isInteger(value) || value < 1) {\n    throw validationFailed([{ path: [\"limit\"], message: \"Must be a positive integer.\" }]);\n  }\n  return value;\n}\n\nfunction encodeCursor(key: string): string {\n  const bytes = new TextEncoder().encode(JSON.stringify({ k: key }));\n  return btoa(String.fromCharCode(...bytes))\n    .replaceAll(\"+\", \"-\")\n    .replaceAll(\"/\", \"_\")\n    .replace(/=+$/, \"\");\n}\n\nfunction decodeCursor(cursor: string): string {\n  try {\n    const binary = atob(cursor.replaceAll(\"-\", \"+\").replaceAll(\"_\", \"/\"));\n    const json = new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)));\n    const parsed: unknown = JSON.parse(json);\n    if (typeof parsed === \"object\" && parsed !== null && \"k\" in parsed && typeof parsed.k === \"string\") {\n      return parsed.k;\n    }\n  } catch {\n    // fall through to the typed error below\n  }\n  throw new AppError({ code: \"INVALID_CURSOR\", status: 400, message: \"The page cursor is invalid.\" });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@awsmbiz/inbis-db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "D1 + Drizzle helpers for Inbis packages: database factory, column and pagination helpers, batch wrapper, and the inbis-db migration CLI.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awsmbiz/inbis-platform.git",
+    "directory": "packages/db"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@awsmbiz/inbis-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.4",
+    "wrangler": "^4.156.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@cloudflare/vitest-plugin": "1.4.11",
+    "@cloudflare/workers-types": "5.20261030.1",
+    "@awsmbiz/inbis-eslint-config": "0.1.0",
+    "@awsmbiz/inbis-tsconfig": "0.1.0",
+    "@types/node": "24.19.2",
+    "drizzle-orm": "0.45.4",
+    "eslint": "10.14.0",
+    "publint": "0.3.25",
+    "tsdown": "0.23.4",
+    "typescript": "6.0.3",
+    "vitest": "5.0.5",
+    "wrangler": "4.156.0"
+  },
+  "bin": {
+    "inbis-db": "./dist/cli.mjs"
+  },
+  "peerDependenciesMeta": {
+    "wrangler": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc && tsc -p cli",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run && vitest run --config cli/vitest.config.ts",
+    "check:exports": "publint --strict && attw --pack . --profile esm-only"
+  }
 }