@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.419

package/database/client.mjs

@@ -0,0 +1,126 @@
+import { DatabaseError } from "./errors.mjs";
+import { t as Connection } from "../connection-CDk7H1FL.mjs";
+//#region src/database/client.ts
+/**
+* `@midsummer-ai/sdk/database`: a Project's Database, from its app or its server.
+*
+*   import { connect } from "@midsummer-ai/sdk/database"
+*   import { api } from "../db/_generated/api"
+*
+*   const db = await connect({ url, token, refresh })
+*   const id = await db.mutation(api.messages.send, { channel: "general", body: "hi" })
+*   const stop = db.watch(api.messages.list, { channel: "general" }, (messages) => render(messages))
+*
+* In your Deployment's server, Midsummer hands in the Databases the Environment binds as
+* `context.database`: name one by its binding name, and no key is kept anywhere.
+*
+*   const db = await connect({ database: context.database, binding: "main" })
+*
+* In a CI run or an Agent's run, the run's Environment binds it the same way, and the run's own
+* Workload token is what proves it: no key there either. Under `midsummer dev`, every binding
+* reaches the Database's Stand-in.
+*
+*   const db = await connect({ binding: "main" })
+*
+* From code outside Midsummer, a Database Key is enough: it is exchanged for a token, and again
+* before that token runs out.
+*
+*   const db = await connect({ key: process.env.DATABASE_KEY! })
+*
+* One connection carries every call. A mutation is tagged, so one sent again after a lost
+* connection applies once; a watch is given its value now and again after every change. Every
+* refusal is a `DatabaseError` whose `code`, a `DatabaseErrorCode`, tells you why.
+*/
+const API = "https://api.midsummer.new";
+/** A token and the Database's address, from the platform, for a key or for a run's binding. */
+async function exchange(api, proof) {
+	const response = await fetch(`${api}/v1/db/tokens`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(typeof proof === "string" ? { key: proof } : proof)
+	});
+	const answer = await response.json().catch(() => ({}));
+	if (!response.ok || !answer.token || !answer.url) throw new DatabaseError("denied", answer.error ?? `The Database Key was refused (${response.status}).`);
+	return {
+		token: answer.token,
+		url: answer.url
+	};
+}
+const refusal = (answer) => new DatabaseError(answer?.why ?? answer?.err ?? "refused", answer?.error ?? answer?.why ?? "refused");
+const caught = (error) => ({
+	ok: false,
+	why: error?.code ?? "refused",
+	error: error?.message
+});
+async function connect(options) {
+	let url, token, refresh;
+	if ("database" in options) {
+		const first = await options.database.token(options.binding);
+		url = first.url;
+		token = first.token;
+		refresh = async () => (await options.database.token(options.binding)).token;
+	} else if ("binding" in options) {
+		const env = globalThis.process?.env ?? {};
+		if (env.MIDSUMMER_DATABASE_URL) {
+			url = env.MIDSUMMER_DATABASE_URL;
+			token = env.MIDSUMMER_DATABASE_TOKEN;
+		} else {
+			const workload = env.MIDSUMMER_IDENTITY_REQUEST_TOKEN, tokenUrl = env.MIDSUMMER_IDENTITY_TOKEN_URL;
+			if (!workload || !tokenUrl) throw new DatabaseError("denied", "This code runs outside Midsummer, so no Environment binds a Database for it. Connect with a Database Key: connect({ key }).");
+			const api = options.api ?? new URL(tokenUrl).origin;
+			const proof = {
+				binding: options.binding,
+				workload
+			};
+			const first = await exchange(api, proof);
+			url = first.url;
+			token = first.token;
+			refresh = async () => (await exchange(api, proof)).token;
+		}
+	} else if ("key" in options) {
+		const api = options.api ?? API;
+		const first = await exchange(api, options.key);
+		url = first.url;
+		token = first.token;
+		refresh = async () => (await exchange(api, options.key)).token;
+	} else {
+		url = options.url;
+		token = options.token;
+		refresh = options.refresh;
+	}
+	const connection = await Connection.connect(url, {
+		...token !== void 0 ? { token } : {},
+		...refresh ? { refresh } : {}
+	});
+	const call = (fn) => ({
+		name: fn.name,
+		kind: fn.kind
+	});
+	return {
+		async query(fn, args) {
+			const value = await connection.query(call(fn), args).catch(caught);
+			if (value && typeof value === "object" && !Array.isArray(value) && value.ok === false) throw refusal(value);
+			return value;
+		},
+		async mutation(fn, args, { tag } = {}) {
+			const answer = await connection.mutation(call(fn), args, tag ? { tag } : {}).catch(caught);
+			if (!answer?.ok) throw refusal(answer);
+			return answer.value ?? null;
+		},
+		async action(fn, args) {
+			const answer = await connection.mutation(call(fn), args, {}).catch(caught);
+			if (!answer?.ok) throw refusal(answer);
+			return answer.value ?? null;
+		},
+		watch(fn, args, onValue) {
+			return connection.watchQuery(call(fn), args, {}, (value) => {
+				if (value !== void 0) onValue(value);
+			});
+		},
+		close() {
+			connection.close();
+		}
+	};
+}
+//#endregion
+export { DatabaseError, connect };

package/database/contract.d.mts

@@ -0,0 +1,11 @@
+import { DatabaseClient } from "./stand-in.mjs";
+//#region src/database/contract.d.ts
+/** The fixture's folder: `schema.ts`, `notes.ts` and `accounts.ts`, served by every Database the cases run against. */
+declare const contractFolder: URL;
+interface ContractCase {
+  readonly name: string;
+  run(db: DatabaseClient): Promise<void>;
+}
+declare const databaseContract: ReadonlyArray<ContractCase>;
+//#endregion
+export { ContractCase, contractFolder, databaseContract };

package/database/contract.mjs

@@ -0,0 +1,164 @@
+import { DatabaseError } from "./errors.mjs";
+//#region src/database/contract.ts
+/**
+* What every Database promises its client, as cases any test runner can run. The Database runs them
+* through its own client and wire, and the Stand-in passes the same cases; a behaviour that is not a
+* case here is not promised.
+*
+* Each case is given a client of a Database serving the fixture in `./contract-db` (its functions
+* and schema). Expected values are written out, never computed with a Database's own code, and each
+* case makes its own caller, so cases never see each other's rows.
+*
+*   for (const item of databaseContract) test(item.name, () => item.run(client))
+*/
+/** The fixture's folder: `schema.ts`, `notes.ts` and `accounts.ts`, served by every Database the cases run against. */
+const contractFolder = new URL("./contract-db/", import.meta.url);
+function eq(got, want, what) {
+	if (JSON.stringify(got) !== JSON.stringify(want)) throw new Error(`${what}: got ${JSON.stringify(got)}, want ${JSON.stringify(want)}`);
+}
+async function refusedWith(call, code, what) {
+	try {
+		await call();
+	} catch (error) {
+		if (error instanceof DatabaseError && error.code === code) return;
+		throw new Error(`${what}: refused ${error?.code ?? error?.message}, want ${code}`);
+	}
+	throw new Error(`${what}: answered, want refused ${code}`);
+}
+function caller(db) {
+	const subject = `c${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+	return {
+		subject,
+		me: db.as(subject)
+	};
+}
+async function until(test, ms, what) {
+	for (const started = Date.now(); Date.now() - started < ms; await new Promise((resolve) => setTimeout(resolve, 50))) if (test()) return;
+	throw new Error(`${what}: not within ${ms} ms`);
+}
+const databaseContract = [
+	{
+		name: "a mutation's row reads back with what it wrote, owned by its caller",
+		async run(db) {
+			const { subject, me } = caller(db);
+			const id = await me.mutation("notes.add", { text: "hello" });
+			eq(await me.query("notes.get", { id }), {
+				owner: subject,
+				text: "hello",
+				n: 0
+			}, "the row");
+		}
+	},
+	{
+		name: "a mutation that throws writes nothing; one that returns writes all of it",
+		async run(db) {
+			const { me } = caller(db);
+			await refusedWith(() => me.mutation("notes.addTwo", {
+				text: "t",
+				fail: true
+			}), "refused", "the throw");
+			eq(await me.query("notes.mine", {}), [], "after the throw");
+			eq(await me.mutation("notes.addTwo", {
+				text: "t",
+				fail: false
+			}), 2, "its answer");
+			eq(await me.query("notes.mine", {}), ["t 1", "t 2"], "after the return");
+		}
+	},
+	{
+		name: "a take of more than a field holds is refused short, and nothing moves",
+		async run(db) {
+			const { me } = caller(db);
+			const a = await me.mutation("accounts.open", { coins: 5 }), b = await me.mutation("accounts.open", { coins: 0 });
+			await refusedWith(() => me.mutation("accounts.move", {
+				from: a,
+				to: b,
+				coins: 7
+			}), "short", "the move");
+			eq([await me.query("accounts.coins", { id: a }), await me.query("accounts.coins", { id: b })], [5, 0], "the coins");
+			await me.mutation("accounts.move", {
+				from: a,
+				to: b,
+				coins: 3
+			});
+			eq([await me.query("accounts.coins", { id: a }), await me.query("accounts.coins", { id: b })], [2, 3], "the coins after a move");
+		}
+	},
+	{
+		name: "increments made at once add up exactly",
+		async run(db) {
+			const { me } = caller(db);
+			const id = await me.mutation("notes.add", { text: "count" });
+			await Promise.all(Array.from({ length: 20 }, () => me.mutation("notes.bump", { id })));
+			eq((await me.query("notes.get", { id })).n, 20, "the count");
+		}
+	},
+	{
+		name: "a mutation sent twice as the same call applies once",
+		async run(db) {
+			const { me } = caller(db);
+			const tag = await me.tag();
+			await me.mutation("notes.add", { text: "once" }, { tag });
+			try {
+				await me.mutation("notes.add", { text: "once" }, { tag });
+			} catch (error) {
+				if (!(error instanceof DatabaseError)) throw error;
+			}
+			eq(await me.query("notes.mine", {}), ["once"], "the rows");
+		}
+	},
+	{
+		name: "arguments that do not fit the function are refused invalid",
+		async run(db) {
+			const { me } = caller(db);
+			await refusedWith(() => me.mutation("notes.add", { text: 5 }), "invalid", "a number for text");
+			await refusedWith(() => me.mutation("notes.addTwo", { text: "x" }), "invalid", "a missing argument");
+		}
+	},
+	{
+		name: "a write that does not fit the schema is refused invalid, and nothing is written",
+		async run(db) {
+			const { me } = caller(db);
+			await refusedWith(() => me.mutation("notes.addRaw", { text: 42 }), "invalid", "a number in a text field");
+			eq(await me.query("notes.mine", {}), [], "the rows");
+		}
+	},
+	{
+		name: "an internal function is refused to a client",
+		async run(db) {
+			await refusedWith(() => caller(db).me.query("notes.secret", {}), "internal", "the internal query");
+		}
+	},
+	{
+		name: "a function that is not there is refused",
+		async run(db) {
+			await refusedWith(() => caller(db).me.query("notes.nothing", {}), "no function", "the call");
+		}
+	},
+	{
+		name: "a function's caller is the signed-in subject",
+		async run(db) {
+			const { subject, me } = caller(db);
+			eq(await me.query("notes.whoami", {}), subject, "the subject");
+		}
+	},
+	{
+		name: "a watched query is given its value again after a mutation changes it",
+		async run(db) {
+			const { me } = caller(db);
+			let seen = null;
+			const stop = me.watch("notes.mine", {}, (value) => {
+				seen = value;
+			});
+			try {
+				await until(() => Array.isArray(seen), 5e3, "its first value");
+				await me.mutation("notes.add", { text: "pushed" });
+				await until(() => JSON.stringify(seen) === JSON.stringify(["pushed"]), 5e3, "the new value");
+			} finally {
+				stop();
+			}
+		}
+	}
+];
+//#endregion
+export { contractFolder, databaseContract };

package/database/errors.d.mts

@@ -0,0 +1,23 @@
+//#region src/database/errors.d.ts
+/**
+ * Why a Database refused a call, as the client throws it: the same codes from the Stand-in and the
+ * Database.
+ *
+ * - `refused`: the function threw; nothing it wrote was kept.
+ * - `short`: a `take` asked for more than a field holds; nothing moved.
+ * - `notfound`: a patch or replace named a row that is not there.
+ * - `invalid`: the arguments, the answer or a write did not fit their shapes.
+ * - `internal`: an internal function, which no client may call.
+ * - `no function`: no function of that name.
+ * - `busy`, `quota`, `paused`: a limit the Project's plan or budget sets; `busy` may be sent again.
+ * - `denied`: the caller may not do this: a Database Key or token was refused, or a token that only reads asked to write.
+ * - `unavailable`: the Database could not be reached, or could not finish the call.
+ */
+type DatabaseErrorCode = "refused" | "short" | "notfound" | "invalid" | "internal" | "no function" | "busy" | "quota" | "paused" | "denied" | "unavailable";
+declare class DatabaseError extends Error {
+  readonly code: DatabaseErrorCode | (string & {});
+  readonly detail?: unknown;
+  constructor(code: DatabaseErrorCode | (string & {}), message?: string, detail?: unknown);
+}
+//#endregion
+export { DatabaseError, DatabaseErrorCode };

package/database/errors.mjs

@@ -0,0 +1,13 @@
+//#region src/database/errors.ts
+var DatabaseError = class extends Error {
+	code;
+	detail;
+	constructor(code, message = code, detail) {
+		super(message);
+		this.code = code;
+		this.detail = detail;
+		this.name = "DatabaseError";
+	}
+};
+//#endregion
+export { DatabaseError };

package/database/server.d.mts

@@ -0,0 +1,3 @@
+import { a as defineSchema, c as shapeError, i as Table, l as v, n as Schema, o as defineTable, r as Shape, s as indexFields, t as IndexDeclaration } from "../schema-f7E9uzUn.mjs";
+import { C as take, S as query, _ as internalAction, a as InsufficientError, b as isFunction, c as RangeOptions, d as Row, f as Rows, g as increment, h as give, i as FunctionReference, l as Refusal, m as action, n as Document, o as NotFoundError, p as ScheduledRun, r as FunctionKind, s as Operator, t as Capabilities, u as RegisteredFunction, v as internalMutation, x as mutation, y as internalQuery } from "../server-C7O7CICU.mjs";
+export { Capabilities, Document, FunctionKind, FunctionReference, type IndexDeclaration, InsufficientError, NotFoundError, Operator, RangeOptions, Refusal, RegisteredFunction, Row, Rows, ScheduledRun, type Schema, type Shape, type Table, action, defineSchema, defineTable, give, increment, indexFields, internalAction, internalMutation, internalQuery, isFunction, mutation, query, shapeError, take, v };

package/database/server.mjs

@@ -0,0 +1,320 @@
+import { a as shapeError, i as indexFields, n as defineSchema, o as v, r as defineTable, t as TABLE } from "../schema-BF-Y1EVu.mjs";
+//#region src/database/server.ts
+/**
+* `@midsummer-ai/sdk/server`: what a Project's `db/` functions are written with. Each file of `db/` is
+* a module of functions, each export a function named `<file>.<export>`, referred to by the client
+* as `api.<file>.<export>`:
+*
+*   import { mutation, query, v } from "./_generated/server"
+*
+*   export const send = mutation({
+*     args: { channel: v.string(), body: v.string() },
+*     handler: async (ctx, { channel, body }) => ctx.db.messages.insert({ channel, body }),
+*   })
+*   export const list = query({
+*     args: { channel: v.string() },
+*     handler: async (ctx, { channel }) => ctx.db.messages.range("by_channel", "channel", { eq: channel }).rows,
+*   })
+*
+* `./_generated/server` is this module typed by the Project's schema; `db/schema.ts` is
+* `export default defineSchema({ ... })`.
+*
+* You write what you mean, and the Database does the concurrency. A query reads rows and never writes them;
+* watched, it is run again when anything it read changes. A mutation is one serializable step: its
+* reads see the rows as they are, its writes are saved together or not at all, and it is run again when
+* a row it read changed, so there is no conflict to handle and no retry loop. A mutation sent again
+* under the same call tag applies once. Neither sees a clock, the network or randomness: `ctx.now`
+* is the call's own time, and its body may run more than once. An action may wait on the network
+* (`ctx.fetch`, https only); its writes are the mutations it runs with `ctx.run`.
+*
+*   ctx.db.<table>: get(id), range(index, field, { eq, gte, gt, lte, lt, order, limit }), where
+*     index "" is the table's own order by id; in a mutation also insert(doc) (its id at once),
+*     patch(id, fields) (a field's value may be `increment(n)`, `take(n)` or `give(n)`),
+*     replace(id, doc) and delete(id). A document is `{ _id, _version, ...fields }`.
+*   ctx.auth: the signed-in caller, `{ subject, issuer }`, or null.
+*   ctx.scheduler: runAfter(ms, fn, args), runAt(time, fn, args), status(id), cancel(id).
+*   cron: "minute hour day month weekday" (UTC) on a mutation or an action runs it on a schedule.
+*/
+const FUNCTION = /^[A-Za-z][A-Za-z0-9_]{0,63}(?:\.[A-Za-z][A-Za-z0-9_]{0,63})?$/u;
+function defineFunction(name, handler, options) {
+	if (name !== null && (typeof name !== "string" || !FUNCTION.test(name))) throw new TypeError("a function's name: [A-Za-z][A-Za-z0-9_]{0,63}");
+	const { kind, args = null, returns = null, internal = false, cron = null } = options;
+	if (args !== null && (typeof args !== "object" || Array.isArray(args))) throw new TypeError(`${name}: args is an object of shapes (v.string(), ...)`);
+	if (cron !== null && (kind === "query" || typeof cron !== "string" || cron.trim().split(/\s+/u).length !== 5 || !/^[0-9*/,\- ]{9,100}$/u.test(cron.trim()))) throw new TypeError(`${name}: cron is "minute hour day month weekday" (a mutation or an action)`);
+	return Object.freeze({
+		name,
+		handler,
+		options: Object.freeze({
+			kind,
+			args: args && Object.freeze({ object: args }),
+			returns,
+			internal: internal === true,
+			cron: cron && cron.trim()
+		})
+	});
+}
+const OPERATOR = Symbol("operator");
+function operator(kind, n) {
+	if (!Number.isFinite(n) || n < 0) throw new TypeError(`${kind}(n): n is a number of at least 0`);
+	return Object.freeze({
+		[OPERATOR]: kind,
+		n
+	});
+}
+/** A field's value plus `n` (a field not yet there counts as 0). */
+const increment = (n = 1) => operator("increment", n);
+/** A field's value minus `n`; below zero the whole mutation fails with `InsufficientError` and writes nothing. */
+const take = (n = 1) => operator("take", n);
+/** A field's value plus `n`: the inverse of `take`. */
+const give = (n = 1) => operator("give", n);
+/** A `take` asked for more than the field holds: the mutation wrote nothing. */
+var InsufficientError = class extends Error {
+	detail;
+	constructor(detail) {
+		super(`not enough ${detail.table}.${detail.field}: has ${detail.has}, asked ${detail.asked}`);
+		this.detail = detail;
+		this.name = "InsufficientError";
+	}
+};
+/** A mutation patched or replaced a row that is not there. */
+var NotFoundError = class extends Error {
+	detail;
+	constructor(detail) {
+		super(`no ${detail.table} row ${detail.id}`);
+		this.detail = detail;
+		this.name = "NotFoundError";
+	}
+};
+/** A call the Database refused: `why` is its reason, as the client's `DatabaseError` carries it. */
+var Refusal = class extends Error {
+	why;
+	detail;
+	constructor(why, message, detail) {
+		super(message);
+		this.why = why;
+		this.detail = detail;
+		this.name = "Refusal";
+	}
+};
+const documentOf = (id, row) => {
+	if (row === null || row === void 0) return null;
+	const fields = Object.fromEntries(Object.entries(row).filter(([key]) => !key.startsWith("_")));
+	return Object.freeze({
+		...fields,
+		_id: id,
+		_version: Number(row._version ?? 0)
+	});
+};
+const fieldsOf = (doc) => Object.fromEntries(Object.entries(doc ?? {}).filter(([key]) => !key.startsWith("_")));
+function applied(current, value, where) {
+	if (value === null || typeof value !== "object" || !(OPERATOR in value)) return value;
+	const op = value;
+	const has = current === void 0 || current === null ? 0 : Number(current);
+	if (!Number.isFinite(has)) throw new TypeError(`${where.table}.${where.field} is not a number: ${op[OPERATOR]}() needs one`);
+	if (op[OPERATOR] === "take") {
+		if (has - op.n < 0) throw new InsufficientError({
+			...where,
+			has,
+			asked: op.n
+		});
+		return has - op.n;
+	}
+	return has + op.n;
+}
+function tablesOf(make) {
+	const cache = /* @__PURE__ */ new Map();
+	const table = (name) => {
+		if (typeof name !== "string" || !TABLE.test(name)) throw new TypeError(`a table name: ${JSON.stringify(name)}`);
+		if (!cache.has(name)) cache.set(name, make(name));
+		return cache.get(name);
+	};
+	return new Proxy(Object.freeze({ table }), { get: (target, key) => key in target || typeof key !== "string" ? target[key] : table(key) });
+}
+const boundsOf = (options = {}) => ({
+	...options.eq === void 0 ? {} : { eq: [options.eq] },
+	gte: options.gte,
+	gt: options.gt,
+	lte: options.lte,
+	lt: options.lt,
+	...options.order ? { order: options.order } : {},
+	limit: options.limit ?? 1e3
+});
+const rangeOf = (rows, name, index, _field, options) => ({
+	ok: true,
+	rows: rows.range(name, index || "_id", boundsOf(options)).map((row) => documentOf(row._id, row))
+});
+const readDb = (rows) => tablesOf((name) => Object.freeze({
+	get: (id) => documentOf(String(id), rows.get(name, String(id))),
+	range: (index, field, options) => rangeOf(rows, name, index, field, options)
+}));
+/** A short, stable text of a string (FNV-1a, base 36): the ids a call inserts. */
+function fnv(text) {
+	let hash = 2166136261;
+	for (let i = 0; i < text.length; i += 1) hash = Math.imul(hash ^ text.charCodeAt(i), 16777619) >>> 0;
+	return hash.toString(36);
+}
+/** A write's document checked against its table in the schema; a table the schema does not declare takes no writes. */
+function fits(schema, name, doc) {
+	if (!schema) return;
+	const fields = schema[name];
+	if (!fields) throw new Refusal("invalid", `${name}: no such table in the schema`, { table: name });
+	const why = shapeError({ object: fields }, doc, name);
+	if (why) throw new Refusal("invalid", why, { table: name });
+}
+function writeDb(rows) {
+	let inserts = 0;
+	return tablesOf((name) => Object.freeze({
+		get: (id) => documentOf(String(id), rows.get(name, String(id))),
+		range: (index, field, options) => rangeOf(rows, name, index, field, options),
+		insert: (doc) => {
+			const id = `${fnv(`${rows.call}:${name}`)}${(inserts++).toString(36).padStart(2, "0")}`;
+			const fields = fieldsOf(doc);
+			fits(rows.schema, name, fields);
+			rows.set(name, id, fields);
+			return id;
+		},
+		patch: (id, change) => {
+			const row = rows.get(name, String(id));
+			if (row === null || row === void 0) throw new NotFoundError({
+				table: name,
+				id
+			});
+			const current = fieldsOf(row);
+			const next = { ...current };
+			for (const [field, value] of Object.entries(change ?? {})) if (value === void 0) delete next[field];
+			else next[field] = applied(current[field], value, {
+				table: name,
+				id,
+				field
+			});
+			fits(rows.schema, name, next);
+			rows.set(name, String(id), next);
+		},
+		replace: (id, doc) => {
+			if (rows.get(name, String(id)) === null) throw new NotFoundError({
+				table: name,
+				id
+			});
+			const fields = fieldsOf(doc);
+			fits(rows.schema, name, fields);
+			rows.set(name, String(id), fields);
+		},
+		delete: (id) => {
+			rows.delete(name, String(id));
+		}
+	}));
+}
+function spec(kind, name, given) {
+	if (given === null || typeof given !== "object" || typeof given.handler !== "function") throw new TypeError(`${kind}(${name ? `"${name}", ` : ""}{ args, returns, cron, handler })`);
+	return given;
+}
+/** A definer's arguments: `({ ... })`, named by its export, or `("name", { ... })`. */
+const named = (name, given) => given === void 0 && name !== null && typeof name === "object" ? [null, name] : [name, given];
+const fnName = (fn) => fn !== null && typeof fn === "object" && typeof fn.name === "string" ? fn.name : String(fn);
+function schedulerOf(rows) {
+	return Object.freeze({
+		runAfter: (ms, fn, args) => rows.runAfter(Math.max(0, Number(ms) || 0), fnName(fn), args ?? null),
+		runAt: (at, fn, args) => rows.runAfter(Math.max(0, (Number(at) || 0) - rows.now), fnName(fn), args ?? null),
+		status: (id) => {
+			const row = rows.scheduledRow(String(id));
+			return row ? Object.freeze({
+				name: row.name,
+				args: row.args ?? null,
+				at: row.due,
+				state: row.state,
+				...row.error ? { error: row.error } : {}
+			}) : null;
+		},
+		cancel: (id) => rows.cancelScheduled(String(id))
+	});
+}
+const authOf = (user, issuer) => user ? Object.freeze({
+	subject: user,
+	issuer: issuer ?? null
+}) : null;
+const contextOf = (rows, tables, scheduler) => Object.freeze({
+	db: tables,
+	identity: Object.freeze({
+		user: rows.user ?? null,
+		server: !!rows.server
+	}),
+	auth: authOf(rows.server ? null : rows.user, rows.issuer),
+	now: rows.now,
+	...scheduler ? { scheduler } : {}
+});
+/** A function that reads rows and never writes them: `export const list = query({ args, returns, handler: (ctx, args) => ... })`. */
+function query(name, given, extra = {}) {
+	const [own, definition] = named(name, given);
+	const { handler, args = null, returns = null } = spec("query", own, definition);
+	return defineFunction(own, (rows, a) => handler(contextOf(rows, readDb(rows)), a ?? {}), {
+		kind: "query",
+		args,
+		returns,
+		...extra
+	});
+}
+/** One serializable transaction: `export const send = mutation({ args, returns, handler: (ctx, args) => ... })`. */
+function mutation(name, given, extra = {}) {
+	const [own, definition] = named(name, given);
+	const { handler, args = null, returns = null, cron = null } = spec("mutation", own, definition);
+	return defineFunction(own, (rows, a) => handler(contextOf(rows, writeDb(rows), schedulerOf(rows)), a ?? {}), {
+		kind: "mutation",
+		args,
+		returns,
+		cron,
+		...extra
+	});
+}
+/** May wait on the network: `export const charge = action({ args, returns, handler: async (ctx, args) => ... })`. */
+function action(name, given, extra = {}) {
+	const [own, definition] = named(name, given);
+	const { handler, args = null, returns = null, cron = null } = spec("action", own, definition);
+	return defineFunction(own, (cap, a) => {
+		const tables = tablesOf((table) => Object.freeze({
+			get: async (id) => documentOf(String(id), await cap.get(table, String(id))),
+			range: async (index, _field, options) => ({
+				ok: true,
+				rows: (await cap.range(table, index || "_id", boundsOf(options))).map((row) => documentOf(row._id, row))
+			})
+		}));
+		const ctx = Object.freeze({
+			db: tables,
+			identity: Object.freeze({
+				user: cap.user ?? null,
+				server: !!cap.server
+			}),
+			auth: authOf(cap.server ? null : cap.user, cap.issuer),
+			fetch: async (url, init) => {
+				const target = new URL(String(url));
+				if (target.protocol !== "https:") throw new TypeError("ctx.fetch: an https URL");
+				return cap.fetch(target, init);
+			},
+			now: () => cap.now(),
+			random: (n = 16) => cap.random(n),
+			run: (fn, args) => cap.run(fnName(fn), args ?? null),
+			scheduler: Object.freeze({
+				runAfter: (ms, fn, args) => cap.schedule(Math.max(0, Number(ms) || 0), fnName(fn), args ?? null),
+				runAt: (at, fn, args) => cap.schedule(Math.max(0, (Number(at) || 0) - cap.now()), fnName(fn), args ?? null),
+				status: (id) => cap.scheduled(String(id)),
+				cancel: (id) => cap.cancel(String(id))
+			})
+		});
+		return handler(ctx, a ?? {});
+	}, {
+		kind: "action",
+		args,
+		returns,
+		cron,
+		...extra
+	});
+}
+/** As `query`, callable only by another function, never a client. */
+const internalQuery = (name, given) => query(name, given, { internal: true });
+/** As `mutation`, callable only by another function, never a client. */
+const internalMutation = (name, given) => mutation(name, given, { internal: true });
+/** As `action`, callable only by another function, never a client. */
+const internalAction = (name, given) => action(name, given, { internal: true });
+/** Whether a value is a function defined here, as a module of `db/` exports it. */
+const isFunction = (value) => value !== null && typeof value === "object" && typeof value.handler === "function" && typeof value.options?.kind === "string";
+//#endregion
+export { InsufficientError, NotFoundError, Refusal, action, defineSchema, defineTable, give, increment, indexFields, internalAction, internalMutation, internalQuery, isFunction, mutation, query, shapeError, take, v };