cursedbelt-server 4.14.0 → 4.15.0

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

@@ -16,7 +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 { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.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';
 export { classifySchedule, cronFieldCount, jobsForCron, type PortableJob, type PortableJobContext, type ScheduleVerdict, toCronTriggers, toFiveField, type TriggerShape, type WorkersPrimitive, } from './scheduling.js';

package/dist/server/d1/index.js

@@ -34,7 +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 { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export { createRemoteD1, } from './remote.js';
 export { classifySchedule, cronFieldCount, jobsForCron, toCronTriggers, toFiveField, } from './scheduling.js';

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

@@ -54,3 +54,34 @@ export declare function assertBatchSize(count: number): void;
  * ```
  */
 export declare function chunkForBind<T>(items: readonly T[], paramsPerItem: number): T[][];
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export declare function inArray(values: readonly (string | number)[]): {
+    sql: string;
+    param: string;
+};

package/dist/server/d1/limits.js

@@ -94,3 +94,40 @@ export function chunkForBind(items, paramsPerItem) {
         out.push(items.slice(i, i + size));
     return out;
 }
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export function inArray(values) {
+    for (const v of values) {
+        if (typeof v === 'string')
+            continue;
+        if (typeof v === 'number' && Number.isFinite(v))
+            continue;
+        throw new TypeError(`inArray takes strings and finite numbers, got ${typeof v}: ${String(v)}`);
+    }
+    return { sql: 'IN (SELECT value FROM json_each(?))', param: JSON.stringify(values) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.14.0",
+	"version": "4.15.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/index.ts

@@ -40,7 +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 { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export {
 	createRemoteD1,

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

@@ -1,6 +1,6 @@
 import { Database } from 'bun:sqlite';
 import { describe, expect, test } from 'bun:test';
-import { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+import { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 import { createLocalD1 } from './local.js';
 import { D1LimitError } from './types.js';
 
@@ -87,4 +87,69 @@ describe('D1 limits are enforced on the LOCAL driver too', () => {
 			expect(() => chunkForBind([1], 1.5)).toThrow(RangeError);
 		});
 	});
+
+	describe('inArray binds a list of any length as ONE parameter', () => {
+		const seeded = (n: number) => {
+			const db = new Database(':memory:');
+			db.run('CREATE TABLE items (id TEXT PRIMARY KEY, n INTEGER, deleted_at INTEGER)');
+			const insert = db.prepare('INSERT INTO items (id, n) VALUES (?, ?)');
+			for (let i = 0; i < n; i++) insert.run(`itm_${String(i).padStart(4, '0')}`, i);
+			return { raw: db, seam: createLocalD1(db) };
+		};
+		const ids = (n: number) => Array.from({ length: n }, (_, i) => `itm_${String(i).padStart(4, '0')}`);
+
+		test('the shape it replaces is refused at 150 ids — the red this exists for', () => {
+			const { seam } = seeded(150);
+			const holes = ids(150).map(() => '?').join(', ');
+			expect(() => seam.prepare(`SELECT id FROM items WHERE id IN (${holes})`).bind(...ids(150))).toThrow(
+				D1LimitError,
+			);
+		});
+
+		test('a 150-id read under ORDER BY / LIMIT / OFFSET selects exactly those rows', async () => {
+			const { seam } = seeded(400);
+			const set = inArray(ids(150));
+			const page = await seam
+				.prepare(`SELECT id FROM items WHERE id ${set.sql} ORDER BY id LIMIT ? OFFSET ?`)
+				.bind(set.param, 100, 20)
+				.all<{ id: string }>();
+			expect(page.results.map((r) => r.id)).toEqual(ids(150).slice(20, 120));
+			const count = await seam
+				.prepare(`SELECT COUNT(*) AS n FROM items WHERE id ${set.sql}`)
+				.bind(set.param)
+				.first<{ n: number }>();
+			expect(count?.n).toBe(150);
+		});
+
+		test('a 1,000-id UPDATE is one statement and touches only those rows', async () => {
+			const { raw, seam } = seeded(1_200);
+			const set = inArray(ids(1_000));
+			await seam.prepare(`UPDATE items SET deleted_at = ? WHERE id ${set.sql}`).bind(7, set.param).run();
+			expect(raw.query('SELECT COUNT(*) AS n FROM items WHERE deleted_at = 7').get()).toEqual({ n: 1_000 });
+			expect(raw.query('SELECT COUNT(*) AS n FROM items WHERE deleted_at IS NULL').get()).toEqual({ n: 200 });
+		});
+
+		test('numbers compare as numbers, and an empty list is valid SQL that matches nothing', async () => {
+			const { seam } = seeded(10);
+			const nums = inArray([2, 4, 6]);
+			const hit = await seam.prepare(`SELECT id FROM items WHERE n ${nums.sql} ORDER BY n`).bind(nums.param).all<{ id: string }>();
+			expect(hit.results.map((r) => r.id)).toEqual(['itm_0002', 'itm_0004', 'itm_0006']);
+			const none = inArray([]);
+			const empty = await seam.prepare(`SELECT id FROM items WHERE id ${none.sql}`).bind(none.param).all();
+			expect(empty.results).toEqual([]);
+		});
+
+		test('a value it cannot compare honestly is refused, not matched against nothing', () => {
+			expect(() => inArray([null as unknown as string])).toThrow(TypeError);
+			expect(() => inArray([Number.NaN])).toThrow(TypeError);
+			expect(() => inArray([{} as unknown as string])).toThrow(TypeError);
+		});
+
+		test('past 2 MB of JSON the seam refuses it at bind(), naming the byte count', () => {
+			const { seam } = seeded(1);
+			const huge = inArray(Array.from({ length: 90_000 }, (_, i) => `itm_${String(i).padStart(20, '0')}`));
+			expect(() => seam.prepare(`SELECT id FROM items WHERE id ${huge.sql}`).bind(huge.param)).toThrow(/value size/);
+		});
+	});
 });
+

package/src/server/d1/limits.ts

@@ -121,3 +121,39 @@ export function chunkForBind<T>(items: readonly T[], paramsPerItem: number): T[]
 	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size) as T[]);
 	return out;
 }
+
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export function inArray(values: readonly (string | number)[]): { sql: string; param: string } {
+	for (const v of values) {
+		if (typeof v === 'string') continue;
+		if (typeof v === 'number' && Number.isFinite(v)) continue;
+		throw new TypeError(`inArray takes strings and finite numbers, got ${typeof v}: ${String(v)}`);
+	}
+	return { sql: 'IN (SELECT value FROM json_each(?))', param: JSON.stringify(values) };
+}