cursedbelt-server 4.15.0 → 4.16.0

package/dist/server/d1/http.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A D1 database reached over Cloudflare's REST API — for a process that is NOT a Worker.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────────────
+ * An app that moves onto a Worker keeps some work on the Mac: a job that drives the owner's
+ * own Chrome, a bulk importer reading a local folder, a backfill, a backup. Before the move
+ * those wrote the Mac's `bun:sqlite` file; after it, that file is a frozen copy nothing reads,
+ * and a script writing into it reports success while the library it meant to change never
+ * hears about it. Measured on `music`'s cutover plan, 2026-09-22: four Mac-side writers, and
+ * the only other door into D1 was a per-app bearer route on the Worker for each one.
+ *
+ * So the Mac gets the same {@link D1LikeDatabase} a Worker holds, pointed at the same
+ * database, and the app's own catalogue code runs unchanged against production — ONE writer
+ * of the rows, one schema, one set of statements.
+ *
+ * ── How ──────────────────────────────────────────────────────────────────────────────────
+ * It is a {@link D1BindingLike} over `POST /accounts/:account/d1/database/:db/query` (and
+ * `/raw`), handed to {@link createRemoteD1} — so every value normalisation, limit check and
+ * `success: false` guard is the binding driver's own, not a second copy that could drift.
+ * `batch()` sends `{ batch: [...] }`, which D1 runs as one unit exactly as a binding's batch
+ * does: measured 2026-09-23 on a throwaway database, a batch whose second statement violated
+ * a UNIQUE constraint left the first one's row absent.
+ *
+ * 🔴 **Not for a Worker.** A Worker has the binding, which is faster, free of an API token,
+ * and not subject to the REST API's rate limit. This is for a Mac process, with the account
+ * token read from the generation's secrets — never shipped to a browser or a Worker.
+ *
+ * 🔴 **Every number arrives as a REAL.** The REST API's parameters are JSON, and measured
+ * 2026-09-23 it binds a JSON `5` as the REAL `5.0` (`typeof(?)` answers `real`). Everywhere a
+ * number is compared, added, used as a `LIMIT`, or stored in an INTEGER column, that is
+ * indistinguishable from an integer — SQLite compares `5.0 = 5` true and INTEGER affinity
+ * stores `5`. The one place it differs: a number stored into a TEXT column is `'5.0'`, where
+ * the binding stores `'5'`. Bind a string into a TEXT column. (Sending integers as strings
+ * instead was measured too, and is worse: it breaks every comparison that has no column
+ * affinity, such as `CASE WHEN ? = 1`.)
+ *
+ * 🔴 **A BLOB parameter is refused.** The REST API's parameters are JSON; there is no
+ * lossless spelling of bytes in it that D1 documents, and guessing one would store the
+ * wrong thing silently. Encode bytes yourself (hex, base64) if a table genuinely needs them.
+ */
+import { type D1BindingLike } from './remote.js';
+import { type D1LikeDatabase } from './types.js';
+export interface HttpD1Options {
+    accountId: string;
+    databaseId: string;
+    /** An API token with D1 Edit on the account. */
+    apiToken: string;
+    /** Each request's ceiling, in ms. Default 30 s — a hung socket must not hang a job. */
+    timeoutMs?: number;
+    /** Injected for tests. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Defaults to `https://api.cloudflare.com/client/v4`. */
+    apiBase?: string;
+}
+/** Thrown when the REST API itself refuses — auth, a missing database, a rate limit. */
+export declare class D1HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * The {@link D1BindingLike} half — exported for a caller that wants to wrap it itself
+ * (a test, or `perInvocation`). Most callers want {@link createHttpD1}.
+ */
+export declare function httpD1Binding(options: HttpD1Options): D1BindingLike;
+/** A {@link D1LikeDatabase} over the D1 REST API. See the header for when, and when not. */
+export declare function createHttpD1(options: HttpD1Options): D1LikeDatabase;

package/dist/server/d1/http.js

@@ -0,0 +1,143 @@
+/**
+ * A D1 database reached over Cloudflare's REST API — for a process that is NOT a Worker.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────────────
+ * An app that moves onto a Worker keeps some work on the Mac: a job that drives the owner's
+ * own Chrome, a bulk importer reading a local folder, a backfill, a backup. Before the move
+ * those wrote the Mac's `bun:sqlite` file; after it, that file is a frozen copy nothing reads,
+ * and a script writing into it reports success while the library it meant to change never
+ * hears about it. Measured on `music`'s cutover plan, 2026-09-22: four Mac-side writers, and
+ * the only other door into D1 was a per-app bearer route on the Worker for each one.
+ *
+ * So the Mac gets the same {@link D1LikeDatabase} a Worker holds, pointed at the same
+ * database, and the app's own catalogue code runs unchanged against production — ONE writer
+ * of the rows, one schema, one set of statements.
+ *
+ * ── How ──────────────────────────────────────────────────────────────────────────────────
+ * It is a {@link D1BindingLike} over `POST /accounts/:account/d1/database/:db/query` (and
+ * `/raw`), handed to {@link createRemoteD1} — so every value normalisation, limit check and
+ * `success: false` guard is the binding driver's own, not a second copy that could drift.
+ * `batch()` sends `{ batch: [...] }`, which D1 runs as one unit exactly as a binding's batch
+ * does: measured 2026-09-23 on a throwaway database, a batch whose second statement violated
+ * a UNIQUE constraint left the first one's row absent.
+ *
+ * 🔴 **Not for a Worker.** A Worker has the binding, which is faster, free of an API token,
+ * and not subject to the REST API's rate limit. This is for a Mac process, with the account
+ * token read from the generation's secrets — never shipped to a browser or a Worker.
+ *
+ * 🔴 **Every number arrives as a REAL.** The REST API's parameters are JSON, and measured
+ * 2026-09-23 it binds a JSON `5` as the REAL `5.0` (`typeof(?)` answers `real`). Everywhere a
+ * number is compared, added, used as a `LIMIT`, or stored in an INTEGER column, that is
+ * indistinguishable from an integer — SQLite compares `5.0 = 5` true and INTEGER affinity
+ * stores `5`. The one place it differs: a number stored into a TEXT column is `'5.0'`, where
+ * the binding stores `'5'`. Bind a string into a TEXT column. (Sending integers as strings
+ * instead was measured too, and is worse: it breaks every comparison that has no column
+ * affinity, such as `CASE WHEN ? = 1`.)
+ *
+ * 🔴 **A BLOB parameter is refused.** The REST API's parameters are JSON; there is no
+ * lossless spelling of bytes in it that D1 documents, and guessing one would store the
+ * wrong thing silently. Encode bytes yourself (hex, base64) if a table genuinely needs them.
+ */
+import { createRemoteD1 } from './remote.js';
+import { D1UnsupportedError } from './types.js';
+/** Thrown when the REST API itself refuses — auth, a missing database, a rate limit. */
+export class D1HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(`D1 over HTTP refused the request (${status}): ${message}`);
+        this.name = 'D1HttpError';
+        this.status = status;
+    }
+}
+function toWire(values) {
+    return values.map((value, index) => {
+        if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+            throw new D1UnsupportedError(`a BLOB parameter (parameter ${index + 1}) over the D1 REST API`, 'encode the bytes as text (hex or base64) — the REST API has no documented lossless BLOB spelling');
+        }
+        return value;
+    });
+}
+/**
+ * The {@link D1BindingLike} half — exported for a caller that wants to wrap it itself
+ * (a test, or `perInvocation`). Most callers want {@link createHttpD1}.
+ */
+export function httpD1Binding(options) {
+    const doFetch = options.fetch ?? fetch;
+    const base = `${options.apiBase ?? 'https://api.cloudflare.com/client/v4'}/accounts/${options.accountId}/d1/database/${options.databaseId}`;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const post = async (path, body) => {
+        const response = await doFetch(`${base}${path}`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${options.apiToken}`, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const envelope = (await response.json().catch(() => null));
+        if (!response.ok || !envelope || envelope.success === false) {
+            const message = envelope?.errors
+                ?.map((e) => e.message)
+                .filter(Boolean)
+                .join('; ') || response.statusText || 'no body';
+            throw new D1HttpError(response.status, message);
+        }
+        return envelope.result ?? [];
+    };
+    const asResult = (wire) => ({
+        results: Array.isArray(wire?.results) ? wire?.results : [],
+        success: wire?.success !== false,
+        ...(wire?.meta ? { meta: wire.meta } : {}),
+    });
+    class HttpStatement {
+        sql;
+        params;
+        constructor(sql, params = []) {
+            this.sql = sql;
+            this.params = params;
+        }
+        bind(...values) {
+            return new HttpStatement(this.sql, toWire(values));
+        }
+        async all() {
+            return asResult((await post('/query', { sql: this.sql, params: this.params }))[0]);
+        }
+        run() {
+            return this.all();
+        }
+        async first(column) {
+            const row = ((await this.all()).results?.[0] ?? null);
+            if (row === null)
+                return null;
+            return column === undefined ? row : (row[column] ?? null);
+        }
+        async raw() {
+            const wire = (await post('/raw', { sql: this.sql, params: this.params }))[0];
+            const results = wire?.results;
+            return results?.rows ?? [];
+        }
+    }
+    return {
+        prepare: (sql) => new HttpStatement(sql),
+        async batch(statements) {
+            const batch = statements.map((s) => {
+                if (!(s instanceof HttpStatement)) {
+                    throw new TypeError('batch() accepts only statements from this same HTTP D1 handle.');
+                }
+                return { sql: s.sql, params: s.params };
+            });
+            if (batch.length === 0)
+                return [];
+            return (await post('/query', { batch })).map(asResult);
+        },
+        async exec(sql) {
+            const results = await post('/query', { sql });
+            return {
+                count: results.length,
+                duration: results.reduce((sum, r) => sum + (r.meta?.duration ?? 0), 0),
+            };
+        },
+    };
+}
+/** A {@link D1LikeDatabase} over the D1 REST API. See the header for when, and when not. */
+export function createHttpD1(options) {
+    return createRemoteD1(httpD1Binding(options));
+}

package/dist/server/d1/index.d.ts

@@ -16,6 +16,7 @@
  */
 export { type BackupPoint, createTimeTravelBackup, type DatabaseBackup, type TimeTravelOpts, } from './backup.js';
 export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation.js';
+export { createHttpD1, D1HttpError, type HttpD1Options } from './http.js';
 export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export { createRemoteD1, type D1BindingLike, type D1BindingMeta, type D1BindingResult, type D1BindingStatement, } from './remote.js';

package/dist/server/d1/index.js

@@ -34,6 +34,7 @@ export { createTimeTravelBackup, } from './backup.js';
 // of them, since business tables stay on raw statements. Measured 2026-09-18 against the
 // published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { createPendingWrites, perInvocation } from './invocation.js';
+export { createHttpD1, D1HttpError } from './http.js';
 export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export { createRemoteD1, } from './remote.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.15.0",
+	"version": "4.16.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/server/d1/http.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test';
+import { createHttpD1, D1HttpError } from './http.js';
+import { D1UnsupportedError } from './types.js';
+
+/**
+ * The HTTP driver against a fake of the D1 REST API's WIRE shapes — the envelopes below are
+ * copied from real responses measured 2026-09-23 on a throwaway database (see `http.ts`).
+ */
+interface Sent {
+	url: string;
+	body: Record<string, unknown>;
+	auth: string | null;
+}
+
+function fakeApi(reply: (path: string, body: Record<string, unknown>) => { status?: number; envelope: unknown }) {
+	const sent: Sent[] = [];
+	const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+		const url = String(input);
+		const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+		sent.push({ url, body, auth: new Headers(init?.headers).get('authorization') });
+		const path = url.endsWith('/raw') ? '/raw' : '/query';
+		const { status = 200, envelope } = reply(path, body);
+		return new Response(JSON.stringify(envelope), { status });
+	}) as typeof fetch;
+	const db = createHttpD1({ accountId: 'acct', databaseId: 'db1', apiToken: 'tok', fetch: fetchImpl });
+	return { db, sent };
+}
+
+const ok = (result: unknown[]) => ({ envelope: { success: true, errors: [], result } });
+const meta = { duration: 0.4, changes: 1, last_row_id: 7, rows_read: 1, rows_written: 1 };
+
+describe('createHttpD1', () => {
+	test('a statement is one POST to /query with its sql, params and the bearer', async () => {
+		const { db, sent } = fakeApi(() => ok([{ results: [{ id: 1, v: 'a' }], success: true, meta }]));
+		const rows = await db.prepare('SELECT * FROM t WHERE id = ? AND v = ?').bind(1, 'a').all();
+		expect(rows.results).toEqual([{ id: 1, v: 'a' }]);
+		expect(sent).toEqual([
+			{
+				url: 'https://api.cloudflare.com/client/v4/accounts/acct/d1/database/db1/query',
+				body: { sql: 'SELECT * FROM t WHERE id = ? AND v = ?', params: [1, 'a'] },
+				auth: 'Bearer tok',
+			},
+		]);
+	});
+
+	test('run reports changes and last_row_id; first reads a row and a column', async () => {
+		const { db } = fakeApi(() => ok([{ results: [{ n: 3 }], success: true, meta }]));
+		const res = await db.prepare('INSERT INTO t (v) VALUES (?)').bind('x').run();
+		expect(res.meta.changes).toBe(1);
+		expect(res.meta.last_row_id).toBe(7);
+		expect(await db.prepare('SELECT COUNT(*) n FROM t').first()).toEqual({ n: 3 });
+		expect(await db.prepare('SELECT COUNT(*) n FROM t').first('n')).toBe(3);
+	});
+
+	test('batch is ONE request carrying every statement, and answers one result each', async () => {
+		const { db, sent } = fakeApi(() =>
+			ok([
+				{ results: [], success: true, meta },
+				{ results: [{ id: 1 }], success: true, meta: { ...meta, changes: 0 } },
+			]),
+		);
+		const results = await db.batch([
+			db.prepare('INSERT INTO t (v) VALUES (?)').bind('a'),
+			db.prepare('SELECT id FROM t'),
+		]);
+		expect(sent).toHaveLength(1);
+		expect(sent[0]?.body).toEqual({
+			batch: [
+				{ sql: 'INSERT INTO t (v) VALUES (?)', params: ['a'] },
+				{ sql: 'SELECT id FROM t', params: [] },
+			],
+		});
+		expect(results.map((r) => r.results)).toEqual([[], [{ id: 1 }]]);
+	});
+
+	test('raw reads the /raw endpoint, so duplicate column names survive', async () => {
+		const { db, sent } = fakeApi(() =>
+			ok([{ results: { columns: ['id', 'v', 'v'], rows: [[1, 'a', 'a']] }, success: true, meta }]),
+		);
+		expect(await db.prepare('SELECT id, v, v AS v FROM t').raw()).toEqual([[1, 'a', 'a']]);
+		expect(sent[0]?.url.endsWith('/raw')).toBe(true);
+	});
+
+	test('a refused statement throws with D1 own message — never a silent empty result', async () => {
+		const { db } = fakeApi(() => ({
+			status: 400,
+			envelope: {
+				success: false,
+				result: [],
+				errors: [{ code: 7500, message: 'UNIQUE constraint failed: t.v: SQLITE_CONSTRAINT' }],
+			},
+		}));
+		const attempt = db.prepare('INSERT INTO t (v) VALUES (?)').bind('one').run();
+		await expect(attempt).rejects.toBeInstanceOf(D1HttpError);
+		await expect(db.prepare('INSERT INTO t (v) VALUES (?)').bind('one').run()).rejects.toThrow(
+			/400\): UNIQUE constraint failed/,
+		);
+	});
+
+	test('a body that is not JSON (a proxy page, an outage) still throws with the status', async () => {
+		const fetchImpl = (async () => new Response('<html>bad gateway</html>', { status: 502 })) as unknown as typeof fetch;
+		const db = createHttpD1({ accountId: 'a', databaseId: 'd', apiToken: 't', fetch: fetchImpl });
+		await expect(db.prepare('SELECT 1').all()).rejects.toThrow(/\(502\)/);
+	});
+
+	test('a BLOB parameter is refused rather than sent in a spelling D1 does not document', () => {
+		const { db } = fakeApi(() => ok([]));
+		expect(() => db.prepare('INSERT INTO t (b) VALUES (?)').bind(new Uint8Array([1, 2]))).toThrow(D1UnsupportedError);
+	});
+
+	test('the parameter cap is the binding driver own — asserted before anything is sent', () => {
+		const { db, sent } = fakeApi(() => ok([]));
+		const holes = Array.from({ length: 101 }, () => '?').join(', ');
+		expect(() => db.prepare(`SELECT ${holes}`).bind(...Array.from({ length: 101 }, (_, i) => i))).toThrow();
+		expect(sent).toHaveLength(0);
+	});
+
+	test('exec sends the whole script and counts the statements D1 ran', async () => {
+		const { db, sent } = fakeApi(() => ok([{ meta }, { meta }, { meta }]));
+		expect(await db.exec('CREATE TABLE u (x); INSERT INTO u VALUES (1); INSERT INTO u VALUES (2)')).toEqual({
+			count: 3,
+			duration: 1.2000000000000002,
+		});
+		expect(sent[0]?.body).toEqual({ sql: 'CREATE TABLE u (x); INSERT INTO u VALUES (1); INSERT INTO u VALUES (2)' });
+	});
+});

package/src/server/d1/http.ts

@@ -0,0 +1,182 @@
+/**
+ * A D1 database reached over Cloudflare's REST API — for a process that is NOT a Worker.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────────────────
+ * An app that moves onto a Worker keeps some work on the Mac: a job that drives the owner's
+ * own Chrome, a bulk importer reading a local folder, a backfill, a backup. Before the move
+ * those wrote the Mac's `bun:sqlite` file; after it, that file is a frozen copy nothing reads,
+ * and a script writing into it reports success while the library it meant to change never
+ * hears about it. Measured on `music`'s cutover plan, 2026-09-22: four Mac-side writers, and
+ * the only other door into D1 was a per-app bearer route on the Worker for each one.
+ *
+ * So the Mac gets the same {@link D1LikeDatabase} a Worker holds, pointed at the same
+ * database, and the app's own catalogue code runs unchanged against production — ONE writer
+ * of the rows, one schema, one set of statements.
+ *
+ * ── How ──────────────────────────────────────────────────────────────────────────────────
+ * It is a {@link D1BindingLike} over `POST /accounts/:account/d1/database/:db/query` (and
+ * `/raw`), handed to {@link createRemoteD1} — so every value normalisation, limit check and
+ * `success: false` guard is the binding driver's own, not a second copy that could drift.
+ * `batch()` sends `{ batch: [...] }`, which D1 runs as one unit exactly as a binding's batch
+ * does: measured 2026-09-23 on a throwaway database, a batch whose second statement violated
+ * a UNIQUE constraint left the first one's row absent.
+ *
+ * 🔴 **Not for a Worker.** A Worker has the binding, which is faster, free of an API token,
+ * and not subject to the REST API's rate limit. This is for a Mac process, with the account
+ * token read from the generation's secrets — never shipped to a browser or a Worker.
+ *
+ * 🔴 **Every number arrives as a REAL.** The REST API's parameters are JSON, and measured
+ * 2026-09-23 it binds a JSON `5` as the REAL `5.0` (`typeof(?)` answers `real`). Everywhere a
+ * number is compared, added, used as a `LIMIT`, or stored in an INTEGER column, that is
+ * indistinguishable from an integer — SQLite compares `5.0 = 5` true and INTEGER affinity
+ * stores `5`. The one place it differs: a number stored into a TEXT column is `'5.0'`, where
+ * the binding stores `'5'`. Bind a string into a TEXT column. (Sending integers as strings
+ * instead was measured too, and is worse: it breaks every comparison that has no column
+ * affinity, such as `CASE WHEN ? = 1`.)
+ *
+ * 🔴 **A BLOB parameter is refused.** The REST API's parameters are JSON; there is no
+ * lossless spelling of bytes in it that D1 documents, and guessing one would store the
+ * wrong thing silently. Encode bytes yourself (hex, base64) if a table genuinely needs them.
+ */
+
+import { createRemoteD1, type D1BindingLike, type D1BindingResult, type D1BindingStatement } from './remote.js';
+import { D1UnsupportedError, type D1LikeDatabase } from './types.js';
+
+export interface HttpD1Options {
+	accountId: string;
+	databaseId: string;
+	/** An API token with D1 Edit on the account. */
+	apiToken: string;
+	/** Each request's ceiling, in ms. Default 30 s — a hung socket must not hang a job. */
+	timeoutMs?: number;
+	/** Injected for tests. Defaults to the global `fetch`. */
+	fetch?: typeof fetch;
+	/** Defaults to `https://api.cloudflare.com/client/v4`. */
+	apiBase?: string;
+}
+
+interface WireResult {
+	results?: unknown;
+	success?: boolean;
+	meta?: D1BindingResult['meta'];
+}
+
+interface Envelope {
+	success?: boolean;
+	errors?: { code?: number; message?: string }[];
+	result?: WireResult[];
+}
+
+/** Thrown when the REST API itself refuses — auth, a missing database, a rate limit. */
+export class D1HttpError extends Error {
+	readonly status: number;
+	constructor(status: number, message: string) {
+		super(`D1 over HTTP refused the request (${status}): ${message}`);
+		this.name = 'D1HttpError';
+		this.status = status;
+	}
+}
+
+function toWire(values: readonly unknown[]): unknown[] {
+	return values.map((value, index) => {
+		if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+			throw new D1UnsupportedError(
+				`a BLOB parameter (parameter ${index + 1}) over the D1 REST API`,
+				'encode the bytes as text (hex or base64) — the REST API has no documented lossless BLOB spelling',
+			);
+		}
+		return value;
+	});
+}
+
+/**
+ * The {@link D1BindingLike} half — exported for a caller that wants to wrap it itself
+ * (a test, or `perInvocation`). Most callers want {@link createHttpD1}.
+ */
+export function httpD1Binding(options: HttpD1Options): D1BindingLike {
+	const doFetch = options.fetch ?? fetch;
+	const base = `${options.apiBase ?? 'https://api.cloudflare.com/client/v4'}/accounts/${options.accountId}/d1/database/${options.databaseId}`;
+	const timeoutMs = options.timeoutMs ?? 30_000;
+
+	const post = async (path: '/query' | '/raw', body: unknown): Promise<WireResult[]> => {
+		const response = await doFetch(`${base}${path}`, {
+			method: 'POST',
+			headers: { authorization: `Bearer ${options.apiToken}`, 'content-type': 'application/json' },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		const envelope = (await response.json().catch(() => null)) as Envelope | null;
+		if (!response.ok || !envelope || envelope.success === false) {
+			const message =
+				envelope?.errors
+					?.map((e) => e.message)
+					.filter(Boolean)
+					.join('; ') || response.statusText || 'no body';
+			throw new D1HttpError(response.status, message);
+		}
+		return envelope.result ?? [];
+	};
+
+	const asResult = (wire: WireResult | undefined): D1BindingResult => ({
+		results: Array.isArray(wire?.results) ? (wire?.results as unknown[]) : [],
+		success: wire?.success !== false,
+		...(wire?.meta ? { meta: wire.meta } : {}),
+	});
+
+	class HttpStatement implements D1BindingStatement {
+		constructor(
+			readonly sql: string,
+			readonly params: unknown[] = [],
+		) {}
+
+		bind(...values: unknown[]): D1BindingStatement {
+			return new HttpStatement(this.sql, toWire(values));
+		}
+
+		async all(): Promise<D1BindingResult> {
+			return asResult((await post('/query', { sql: this.sql, params: this.params }))[0]);
+		}
+
+		run(): Promise<D1BindingResult> {
+			return this.all();
+		}
+
+		async first(column?: string): Promise<unknown> {
+			const row = ((await this.all()).results?.[0] ?? null) as Record<string, unknown> | null;
+			if (row === null) return null;
+			return column === undefined ? row : (row[column] ?? null);
+		}
+
+		async raw(): Promise<unknown[][]> {
+			const wire = (await post('/raw', { sql: this.sql, params: this.params }))[0];
+			const results = wire?.results as { rows?: unknown[][] } | undefined;
+			return results?.rows ?? [];
+		}
+	}
+
+	return {
+		prepare: (sql) => new HttpStatement(sql),
+		async batch(statements) {
+			const batch = statements.map((s) => {
+				if (!(s instanceof HttpStatement)) {
+					throw new TypeError('batch() accepts only statements from this same HTTP D1 handle.');
+				}
+				return { sql: s.sql, params: s.params };
+			});
+			if (batch.length === 0) return [];
+			return (await post('/query', { batch })).map(asResult);
+		},
+		async exec(sql) {
+			const results = await post('/query', { sql });
+			return {
+				count: results.length,
+				duration: results.reduce((sum, r) => sum + (r.meta?.duration ?? 0), 0),
+			};
+		},
+	};
+}
+
+/** A {@link D1LikeDatabase} over the D1 REST API. See the header for when, and when not. */
+export function createHttpD1(options: HttpD1Options): D1LikeDatabase {
+	return createRemoteD1(httpD1Binding(options));
+}

package/src/server/d1/index.ts

@@ -40,6 +40,7 @@ export {
 // of them, since business tables stay on raw statements. Measured 2026-09-18 against the
 // published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation.js';
+export { createHttpD1, D1HttpError, type HttpD1Options } from './http.js';
 export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export {