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

package/database/build.mjs

@@ -0,0 +1,579 @@
+import { i as indexFields, n as defineSchema, o as v, r as defineTable } from "../schema-BF-Y1EVu.mjs";
+import { parse } from "acorn";
+//#region src/database/build.ts
+/**
+* A Project's `db/` folder, built: its TypeScript stripped of types, checked as the Database checks
+* it, and its generated files written. `midsummer db dev` builds with it on every save, so a refusal
+* shows where it was written long before a deploy; the Database checks a deploy again, the same way.
+*
+*   const built = buildDatabase({ "schema.ts": schema, "messages.ts": messages }, strip)
+*   built.files      // { "schema.mjs": js, "messages.mjs": js }: what the Stand-in runs
+*   built.functions  // [{ name: "messages.send", kind: "mutation", internal: false, ... }]
+*   built.generated  // the files of db/_generated/: api.mjs and the types
+*
+* `strip` takes TypeScript to JavaScript, keeping every position, so a refusal points at the author's
+* line: `transformSync(ts, { mode: "strip-only" }).code` of `amaro`. Only types are taken out; an
+* enum or a namespace is code, and is refused. Nothing here runs the Project's code.
+*
+* What is admitted: imports of `@midsummer-ai/sdk/server`, `./_generated/server` and
+* `./_generated/api` by name (no renaming), and of the folder's own modules; functions as top-level
+* exports (`export const send = mutation({ ... })`); actions in files of their own; the schema as
+* literals (`export default defineSchema({ ... })` in `schema.ts`). Never `eval`, a dynamic
+* `import()`, `import.meta` or import attributes.
+*/
+/** A file the Database would refuse; the message gives the file, and the line when there is one. */
+var Refused = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "Refused";
+	}
+};
+const SOURCES = [
+	".ts",
+	".mts",
+	".mjs",
+	".js"
+];
+const extensionOf = (name) => /\.[^.]*$/u.exec(name)?.[0] ?? "";
+/** Whether a file directly in `db/` is a source: types (`.d.ts`) and dotfiles are none. */
+const isSource = (name) => SOURCES.includes(extensionOf(name)) && !name.endsWith(".d.ts") && !name.startsWith(".") && !name.includes("/");
+const SDK = "@midsummer-ai/sdk/server";
+const DEFINERS = [
+	"query",
+	"mutation",
+	"internalQuery",
+	"internalMutation",
+	"action",
+	"internalAction"
+];
+const ACTIONS = /* @__PURE__ */ new Set(["action", "internalAction"]);
+const ADMITTED = /* @__PURE__ */ new Set([
+	...DEFINERS,
+	"v",
+	"increment",
+	"take",
+	"give",
+	"InsufficientError",
+	"NotFoundError",
+	"defineSchema",
+	"defineTable"
+]);
+const API_NAMES = /* @__PURE__ */ new Set(["api", "internal"]);
+const SURFACES = new Map([[SDK, ADMITTED], ...[
+	"",
+	".js",
+	".mjs"
+].flatMap((x) => [[`./_generated/server${x}`, ADMITTED], [`./_generated/api${x}`, API_NAMES]])]);
+const SCHEMA_FILE = "schema.mjs";
+const FUNCTION_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/u;
+const FORBIDDEN = /* @__PURE__ */ new Set([
+	"eval",
+	"__realm",
+	"__step"
+]);
+function* nodes(node) {
+	yield node;
+	for (const value of Object.values(node)) if (Array.isArray(value)) {
+		for (const child of value) if (typeof child?.type === "string") yield* nodes(child);
+	} else if (typeof value?.type === "string") yield* nodes(value);
+}
+/** Strips each source and points its siblings at their built files. Throws `Refused` with the author's file. */
+function stripSources(sources, strip) {
+	const entries = Object.keys(sources).filter(isSource);
+	const names = /* @__PURE__ */ new Map();
+	for (const file of entries) {
+		const name = file.slice(0, -extensionOf(file).length);
+		const first = names.get(name);
+		if (first !== void 0) throw new Refused(`${first} and ${file} compile to ${name}.mjs. Rename one file.`);
+		names.set(name, file);
+	}
+	const files = {}, from = {};
+	for (const [name, file] of names) {
+		let js;
+		try {
+			js = /\.m?ts$/u.test(file) ? strip(sources[file]) : sources[file];
+		} catch (error) {
+			const { startLine: line, code } = error ?? {};
+			const why = `${file}${Number.isInteger(line) ? `:${line}` : ""}: ${String(error?.message ?? error).split("\n")[0]}`;
+			throw new Refused(code === "UnsupportedSyntax" ? `${why}. Write it as JavaScript instead: an object of constants for an enum, plain exports for a namespace.` : why);
+		}
+		files[`${name}.mjs`] = siblingsNamed(file, js, names);
+		from[`${name}.mjs`] = file;
+	}
+	return {
+		files,
+		from
+	};
+}
+/** `js` with each import of the folder (`./helper`, `./helper.ts`, `./helper.js`) naming its built file. */
+function siblingsNamed(file, js, names) {
+	let tree;
+	try {
+		tree = parse(js, {
+			ecmaVersion: "latest",
+			sourceType: "module"
+		});
+	} catch (error) {
+		throw new Refused(`${file}: does not parse as a module: ${error.message}`);
+	}
+	const edits = [];
+	for (const node of tree.body) {
+		if (!node.source || !/^(Import|ExportNamed|ExportAll)Declaration$/u.test(node.type)) continue;
+		const match = /^\.\/([A-Za-z0-9_-]+)(?:\.(?:ts|mts|js|mjs))?$/u.exec(node.source.value);
+		if (match && names.has(match[1])) edits.push({
+			at: node.source.start,
+			end: node.source.end,
+			text: JSON.stringify(`./${match[1]}.mjs`)
+		});
+	}
+	let out = js;
+	for (const edit of edits.sort((a, b) => b.at - a.at)) out = `${out.slice(0, edit.at)}${edit.text}${out.slice(edit.end)}`;
+	return out;
+}
+/** Parses one built module and checks every rule of admission. Throws `Refused` naming the author's file and line. */
+function inspect(file, text, siblings) {
+	const refuse = (why, node) => {
+		throw new Refused(`${file}${node?.loc ? `:${node.loc.start.line}` : ""}: ${why}`);
+	};
+	let tree;
+	try {
+		tree = parse(text, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			locations: true
+		});
+	} catch (error) {
+		return refuse(`does not parse as a module: ${error.message}`);
+	}
+	for (const node of nodes(tree)) {
+		if (node.type === "ImportExpression") refuse("a dynamic import() (a function loads nothing at runtime)", node);
+		if (node.type === "MetaProperty" && node.meta.name === "import") refuse("import.meta", node);
+		if ((node.type === "Identifier" || node.type === "PrivateIdentifier") && FORBIDDEN.has(node.name)) refuse(`the name ${node.name}`, node);
+		if (!node.source || !/^(Import|ExportNamed|ExportAll)Declaration$/u.test(node.type)) continue;
+		if (node.attributes?.length) refuse("import attributes", node);
+		const spec = node.source.value;
+		const allowed = SURFACES.get(spec);
+		if (allowed) {
+			const names = (node.specifiers ?? []).map((s) => s.type === "ImportSpecifier" && s.imported.type === "Identifier" && s.imported.name === s.local.name ? s.local.name : null);
+			if (names.includes("defineFunction")) refuse("defineFunction: define with query, mutation or action", node);
+			if (node.type !== "ImportDeclaration" || !names.length || !names.every((name) => name !== null && allowed.has(name))) refuse(`only \`import { ${[...allowed].join(", ")} } from "${spec}"\` (no renaming)`, node);
+			continue;
+		}
+		const sibling = /^\.\/([A-Za-z0-9_-]+\.mjs)$/u.exec(spec)?.[1];
+		if (!sibling || !siblings.has(sibling)) refuse(`import of "${spec}" (only "${SDK}", "./_generated/server", "./_generated/api" and modules of this folder are admitted)`, node);
+	}
+	return tree;
+}
+/** A file's functions, as top-level exports, and the count of definer calls anywhere (each must be one of them). */
+function definersOf(tree, base) {
+	const isDefiner = (n) => n?.type === "CallExpression" && n.callee.type === "Identifier" && DEFINERS.includes(n.callee.name);
+	const literal = (n) => n?.type === "Literal" && typeof n.value === "string" ? n.value : null;
+	const calls = [...nodes(tree)].filter(isDefiner).length;
+	const defs = [];
+	for (const top of tree.body) {
+		if (top.type === "ExportDefaultDeclaration" && isDefiner(top.declaration)) {
+			const first = top.declaration.arguments[0];
+			defs.push({
+				kind: top.declaration.callee.name,
+				name: literal(first) ?? (first?.type === "ObjectExpression" ? `${base}.default` : null),
+				export: "default",
+				call: top.declaration
+			});
+		}
+		if (top.type !== "ExportNamedDeclaration" || top.declaration?.type !== "VariableDeclaration") continue;
+		for (const one of top.declaration.declarations) {
+			if (!isDefiner(one.init) || one.id.type !== "Identifier") continue;
+			defs.push({
+				kind: one.init.callee.name,
+				name: `${base}.${one.id.name}`,
+				export: one.id.name,
+				named: one.init.arguments[0]?.type !== "ObjectExpression",
+				call: one.init
+			});
+		}
+	}
+	return {
+		defs,
+		calls
+	};
+}
+/**
+* A reader of literal values in a module's parse (the schema's, and a function's `args`): literals,
+* arrays, objects, `v.<shape>(...)`, `defineTable(...).index(...)` and the module's top-level
+* `const`s of these. Anything else calls `refuse`.
+*/
+function literalReader(tree, refuse, lenient = false) {
+	const consts = /* @__PURE__ */ new Map();
+	const vShapes = v;
+	const value = (node) => {
+		if (!node) return refuse(null);
+		if (node.type === "Identifier" && consts.has(node.name)) return consts.get(node.name);
+		if (node.type === "Literal" && !node.regex && typeof node.value !== "bigint") return node.value;
+		if (node.type === "UnaryExpression" && node.operator === "-" && node.argument.type === "Literal" && typeof node.argument.value === "number") return -node.argument.value;
+		if (node.type === "ArrayExpression" && node.elements.every((e) => e && e.type !== "SpreadElement")) return node.elements.map(value);
+		if (node.type === "ObjectExpression") {
+			const out = {};
+			for (const p of node.properties) {
+				if (p.type !== "Property" || p.computed || p.kind !== "init" || p.method) refuse(p);
+				out[p.key.type === "Identifier" ? p.key.name : String(p.key.value)] = value(p.value);
+			}
+			return out;
+		}
+		if (node.type === "CallExpression" && !node.optional && node.arguments.every((a) => a.type !== "SpreadElement")) {
+			const callee = node.callee;
+			const args = () => node.arguments.map(value);
+			if (callee.type === "Identifier" && callee.name === "defineTable") return defineTable(args()[0]);
+			if (callee.type === "MemberExpression" && !callee.computed && !callee.optional && callee.object.type === "Identifier" && callee.object.name === "v" && Object.hasOwn(v, callee.property.name)) return vShapes[callee.property.name](...args());
+			if (callee.type === "MemberExpression" && !callee.computed && !callee.optional && [
+				"index",
+				"searchIndex",
+				"vectorIndex"
+			].includes(callee.property.name)) {
+				const table = value(callee.object);
+				if (typeof table?.[callee.property.name] === "function") return table[callee.property.name](...args());
+			}
+		}
+		return refuse(node);
+	};
+	for (const top of tree.body) {
+		const declaration = top.type === "ExportNamedDeclaration" ? top.declaration : top;
+		if (declaration?.type !== "VariableDeclaration" || declaration.kind !== "const") continue;
+		for (const one of declaration.declarations) {
+			if (one.id.type !== "Identifier" || !one.init) continue;
+			if (!lenient) {
+				consts.set(one.id.name, value(one.init));
+				continue;
+			}
+			try {
+				consts.set(one.id.name, value(one.init));
+			} catch {}
+		}
+	}
+	return { value };
+}
+/** A function's `args` fields and `returns` shape as written, for its types; null where they are not literals. */
+function signatureOf(tree, call) {
+	const UNKNOWN = Symbol("unknown");
+	let value;
+	try {
+		({value} = literalReader(tree, () => {
+			throw UNKNOWN;
+		}, true));
+	} catch {
+		return {
+			args: null,
+			returns: null
+		};
+	}
+	const spec = (call?.arguments)?.find((a) => a.type === "ObjectExpression");
+	const prop = (name) => (spec?.properties)?.find((p) => p.type === "Property" && !p.computed && (p.key.name ?? p.key.value) === name)?.value;
+	const read = (node) => {
+		if (!node) return null;
+		try {
+			return value(node);
+		} catch {
+			return null;
+		}
+	};
+	const args = prop("args");
+	const fields = args?.type === "ObjectExpression" ? Object.fromEntries(args.properties.filter((p) => p.type === "Property" && !p.computed).map((p) => [p.key.name ?? String(p.key.value), read(p.value)])) : read(args);
+	return {
+		args: fields && typeof fields === "object" && !("object" in fields) ? fields : fields?.object ?? null,
+		returns: read(prop("returns"))
+	};
+}
+function schemaOf(file, tree) {
+	const refuse = (why, node) => {
+		throw new Refused(`${file}${node?.loc ? `:${node.loc.start.line}` : ""}: ${why}`);
+	};
+	const literal = "the schema is written as literals: defineSchema({ <table>: defineTable({ <field>: v.<shape>(...) }) })";
+	let value;
+	try {
+		({value} = literalReader(tree, (node) => refuse(literal, node)));
+	} catch (error) {
+		if (error instanceof Refused) throw error;
+		return refuse(error.message, null);
+	}
+	const declaration = tree.body.find((n) => n.type === "ExportDefaultDeclaration")?.declaration;
+	if (declaration?.type !== "CallExpression" || declaration.callee.type !== "Identifier" || declaration.callee.name !== "defineSchema" || declaration.arguments.length !== 1) refuse("the schema is `export default defineSchema({ ... })`", declaration);
+	try {
+		const built = defineSchema(value(declaration.arguments[0]));
+		return {
+			tables: built.tables,
+			indexes: built.indexes
+		};
+	} catch (error) {
+		if (error instanceof Refused) throw error;
+		return refuse(error.message, declaration);
+	}
+}
+/** Builds a `db/` folder's sources: `{ <file>: text }`, its top level. Throws `Refused`. */
+function buildDatabase(sources, strip) {
+	const { files, from } = stripSources(sources, strip);
+	const names = Object.keys(files).sort();
+	const siblings = new Set(names);
+	const functions = [];
+	const defined = /* @__PURE__ */ new Map();
+	let tables = null, indexes = null;
+	for (const file of names) {
+		const author = from[file];
+		const tree = inspect(author, files[file], siblings);
+		const { defs, calls } = definersOf(tree, file.replace(/\.mjs$/u, ""));
+		if (calls !== defs.length) throw new Refused(`${author}: a function defined outside a top-level export (\`export const send = mutation({ ... })\`)`);
+		for (const def of defs) {
+			if (def.named) throw new Refused(`${author}: export const ${def.export} = ${def.kind}({ ... }): its name is the export's (${def.name}), so the definer takes none`);
+			if (!def.name || !def.name.split(".").every((part) => FUNCTION_NAME.test(part))) throw new Refused(`${author}: a function's name: [A-Za-z][A-Za-z0-9_]{0,63}, or <file>.<export> with both so (${JSON.stringify(def.name)})`);
+			if (defined.has(def.name)) throw new Refused(`${author}: the name "${def.name}" is also defined by ${defined.get(def.name)}`);
+			defined.set(def.name, author);
+		}
+		const acting = defs.filter((def) => ACTIONS.has(def.kind)).length;
+		if (acting && acting !== defs.length) throw new Refused(`${author}: actions and queries or mutations in one file (an action waits on the network, the others run as one step): put the actions in a file of their own`);
+		if (file === SCHEMA_FILE) ({tables, indexes} = schemaOf(author, tree));
+		for (const def of defs) functions.push({
+			name: def.name,
+			kind: def.kind,
+			file,
+			export: def.export,
+			...signatureOf(tree, def.call)
+		});
+	}
+	return {
+		files,
+		from,
+		functions,
+		tables,
+		indexes,
+		generated: generatedOf(functions, tables, indexes)
+	};
+}
+const HEAD = "// Generated by `midsummer db dev` from this folder. Do not edit.";
+const kindOf = (kind) => kind.replace(/^internal/u, "").toLowerCase();
+/** The function references, nested by file: `api.messages.send`; `internal` has the internal functions alike. */
+function referencesOf(functions) {
+	const tree = (list) => {
+		const top = /* @__PURE__ */ new Map();
+		for (const fn of list) {
+			const [a, b] = fn.name.split(".");
+			const ref = {
+				name: fn.name,
+				kind: kindOf(fn.kind)
+			};
+			const had = top.get(a);
+			if (b === void 0 ? had : had?.ref) throw new Refused(`${fn.file}: "${a}" names both a function and a file of functions`);
+			if (b === void 0) top.set(a, { ref });
+			else top.set(a, { group: new Map([...had?.group ?? [], [b, ref]]) });
+		}
+		return top;
+	};
+	tree(functions);
+	const js = (top) => `Object.freeze({ ${[...top].map(([key, x]) => `${key}: ${x.ref ? `Object.freeze(${JSON.stringify(x.ref)})` : `Object.freeze({ ${[...x.group].map(([b, r]) => `${b}: Object.freeze(${JSON.stringify(r)})`).join(", ")} })`}`).join(", ")} })`;
+	return [`export const api = ${js(tree(functions.filter((fn) => !fn.kind.startsWith("internal"))))};`, `export const internal = ${js(tree(functions.filter((fn) => fn.kind.startsWith("internal"))))};`];
+}
+/** A shape as a TypeScript type. */
+function typeOf(shape) {
+	if (shape === void 0 || shape === null) return "unknown";
+	if (typeof shape === "string") return {
+		string: "string",
+		number: "number",
+		boolean: "boolean",
+		document: "unknown",
+		int64: "number | string",
+		bytes: "string",
+		timestamp: "number",
+		decimal: "string"
+	}[shape] ?? "unknown";
+	if ("optional" in shape) return `${typeOf(shape.optional)} | null | undefined`;
+	if ("array" in shape) return `Array<${typeOf(shape.array)}>`;
+	if ("object" in shape) return `{ ${Object.entries(shape.object).map(([key, inner]) => `${JSON.stringify(key)}${inner && typeof inner === "object" && "optional" in inner ? "?" : ""}: ${typeOf(inner)}`).join("; ")} }`;
+	if ("literal" in shape) return JSON.stringify(shape.literal);
+	if ("union" in shape) return shape.union.map(typeOf).join(" | ") || "never";
+	if ("record" in shape) return `Record<string, ${typeOf(shape.record)}>`;
+	if ("id" in shape) return `Id<${JSON.stringify(shape.id)}>`;
+	return "unknown";
+}
+const fieldsType = (fields) => typeOf({ object: fields ?? {} });
+function dataModelOf(tables, indexes) {
+	const names = Object.keys(tables ?? {});
+	if (!names.length) return [
+		HEAD,
+		"export type TableNames = string;",
+		"export type Id<T extends TableNames = TableNames> = string & { readonly __table?: T };",
+		"export interface DataModel { [table: string]: { document: { _id: Id; _version: number; [field: string]: any }; indexes: Record<string, string[]> } }",
+		"export type Doc<T extends TableNames> = DataModel[T][\"document\"];",
+		""
+	].join("\n");
+	return [
+		HEAD,
+		`export type TableNames = ${names.map((name) => JSON.stringify(name)).join(" | ")};`,
+		"/** A document's id: a string that identifies its table. */",
+		"export type Id<T extends TableNames> = string & { readonly __table: T };",
+		"export interface DataModel {",
+		...names.map((name) => `  ${JSON.stringify(name)}: { document: { _id: Id<${JSON.stringify(name)}>; _version: number } & ${typeOf({ object: tables[name] })}; indexes: { ${Object.entries(indexes?.[name] ?? {}).map(([index, fields]) => `${JSON.stringify(index)}: ${JSON.stringify(indexFields(fields))}`).join("; ")} } };`),
+		"}",
+		"/** A document of a table, as a read returns it. */",
+		"export type Doc<T extends TableNames> = DataModel[T][\"document\"];",
+		""
+	].join("\n");
+}
+function apiTypesOf(functions) {
+	const tree = (list) => {
+		const top = /* @__PURE__ */ new Map();
+		for (const fn of list) {
+			const [a, b] = fn.name.split(".");
+			const ref = `FunctionReference<${JSON.stringify(kindOf(fn.kind))}, ${fn.args ? fieldsType(fn.args) : "any"}, ${fn.returns ? typeOf(fn.returns) : "any"}>`;
+			if (b === void 0) top.set(a, ref);
+			else top.set(a, new Map([...top.get(a) ?? [], [b, ref]]));
+		}
+		return `{ ${[...top].map(([key, x]) => `readonly ${key}: ${typeof x === "string" ? x : `{ ${[...x].map(([b, r]) => `readonly ${b}: ${r};`).join(" ")} }`};`).join(" ")} }`;
+	};
+	return [
+		HEAD,
+		"import type { FunctionReference } from \"./server\";",
+		"export type { FunctionReference } from \"./server\";",
+		`export declare const api: ${tree(functions.filter((fn) => !fn.kind.startsWith("internal")))};`,
+		`export declare const internal: ${tree(functions.filter((fn) => fn.kind.startsWith("internal")))};`,
+		""
+	].join("\n");
+}
+function generatedOf(functions, tables, indexes) {
+	return {
+		"api.mjs": [
+			`${HEAD} A function's reference for the client: \`db.mutation(api.messages.send, args)\`.`,
+			...referencesOf(functions),
+			""
+		].join("\n"),
+		"api.d.ts": apiTypesOf(functions),
+		"dataModel.d.ts": dataModelOf(tables, indexes),
+		"server.d.ts": SERVER_TYPES
+	};
+}
+/** `@midsummer-ai/sdk/server`, typed by this Project's schema (`./dataModel`). */
+const SERVER_TYPES = `${HEAD} What "@midsummer-ai/sdk/server" gives, typed by this
+// Database's schema: its tables, documents and function references.
+import type { DataModel, Doc, Id, TableNames } from "./dataModel";
+export type { DataModel, Doc, Id, TableNames } from "./dataModel";
+
+/** A field type. \`T\` is the value's type; \`O\` whether the field may be left out. */
+export interface Validator<T, O extends boolean = false> {
+  readonly type?: string;
+  readonly optional?: O;
+  /** For the types only: never present at run time. */
+  readonly __value?: T;
+}
+type Required<T> = Validator<T, false>;
+export type Infer<V> = V extends Validator<infer T, boolean> ? T : never;
+export type Fields = Record<string, Validator<any, boolean>>;
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+type OptionalKeys<F extends Fields> = { [K in keyof F]: F[K] extends Validator<any, true> ? K : never }[keyof F];
+type RequiredKeys<F extends Fields> = Exclude<keyof F, OptionalKeys<F>>;
+/** The document a table's fields describe. */
+export type DocOf<F extends Fields> = Simplify<{ [K in RequiredKeys<F>]: Infer<F[K]> } & { [K in OptionalKeys<F>]?: Infer<F[K]> }>;
+export declare const v: {
+  string(): Required<string>;
+  number(): Required<number>;
+  boolean(): Required<boolean>;
+  /** Any JSON value, at any depth. */
+  document(): Required<unknown>;
+  id<T extends TableNames>(table: T): Required<Id<T>>;
+  array<V extends Validator<any, boolean>>(of: V): Required<Infer<V>[]>;
+  object<F extends Fields>(fields: F): Required<DocOf<F>>;
+  /** May be left out or null. */
+  optional<V extends Validator<any, boolean>>(inner: V): Validator<Infer<V> | null, true>;
+  int64(): Validator<number | string>;
+  bytes(): Validator<string>;
+  timestamp(): Validator<number>;
+  decimal(): Validator<string>;
+  literal<L extends string | number | boolean>(value: L): Validator<L>;
+  union<V extends Validator<any, boolean>[]>(...of: V): Validator<Infer<V[number]>>;
+  record<V extends Validator<any, boolean>>(of: V): Validator<Record<string, Infer<V>>>;
+};
+
+// ---- Operators: a patch's values ----
+
+export interface Operator { readonly __operator?: "increment" | "take" | "give"; readonly n: number }
+/** The field goes up by \`n\` (default 1). */
+export declare function increment(n?: number): Operator;
+/** Takes \`n\` from a field; below zero the whole mutation fails with InsufficientError and writes nothing. */
+export declare function take(n?: number): Operator;
+/** Gives \`n\` back: the inverse of \`take\`. */
+export declare function give(n?: number): Operator;
+export type Patch<D> = { [K in keyof D]?: D[K] | (D[K] extends number ? Operator : never) };
+
+// ---- The tables a function reads and writes: \`ctx.db.<table>\` ----
+
+type Value<T extends TableNames> = Omit<Doc<T>, "_id" | "_version">;
+/** A range's bounds on the index's first field (\`eq\`), or on it (\`gte\`, \`gt\`, \`lte\`, \`lt\`); \`order\`; at most \`limit\`. */
+export interface RangeOptions { eq?: unknown; gte?: unknown; gt?: unknown; lte?: unknown; lt?: unknown; order?: "asc" | "desc"; limit?: number }
+export interface Reader<T extends TableNames> {
+  get(id: Id<T>): Doc<T> | null;
+  /** The rows of an index (\`""\`: by id) within the bounds, in its order. */
+  range(index: keyof DataModel[T]["indexes"] | "", field: string, options?: RangeOptions): { ok: true; rows: Doc<T>[] };
+}
+export interface Writer<T extends TableNames> extends Reader<T> {
+  /** Its id at once, usable anywhere in the same mutation. */
+  insert(doc: Value<T>): Id<T>;
+  patch(id: Id<T>, fields: Patch<Value<T>>): void;
+  replace(id: Id<T>, doc: Value<T>): void;
+  delete(id: Id<T>): void;
+}
+type Tables<R> = { readonly [T in TableNames]: R extends "write" ? Writer<T> : Reader<T> } & { table<T extends TableNames>(name: T): R extends "write" ? Writer<T> : Reader<T> };
+type AsyncReader<T extends TableNames> = { get(id: Id<T>): Promise<Doc<T> | null>; range(index: keyof DataModel[T]["indexes"] | "", field: string, options?: RangeOptions): Promise<{ ok: true; rows: Doc<T>[] }> };
+
+// ---- Functions ----
+
+/** A function's reference (\`api.messages.send\`): its name, kind, arguments and answer. */
+export interface FunctionReference<Kind extends "query" | "mutation" | "action", Args = any, Returns = any> { readonly name: string; readonly kind: Kind; readonly __args?: Args; readonly __returns?: Returns }
+type ArgsOf<F> = F extends FunctionReference<any, infer A, any> ? A : never;
+export interface Identity { readonly user: string | null; readonly server: boolean }
+/** The caller as the Project's sign-in identifies it (its \`sub\`), and the issuer when the Database trusts one; null: no user. */
+export type Auth = { readonly subject: string; readonly issuer: string | null } | null;
+export interface Scheduler {
+  runAfter<F extends FunctionReference<"mutation" | "action">>(ms: number, fn: F, args: ArgsOf<F>): string;
+  runAt<F extends FunctionReference<"mutation" | "action">>(at: number, fn: F, args: ArgsOf<F>): string;
+  status(id: string): { name: string; args: unknown; at: number; state: string; error?: string } | null;
+  cancel(id: string): boolean;
+}
+/** Reads only; run again when anything it read changes. */
+export interface QueryCtx { readonly db: Tables<"read">; readonly identity: Identity; readonly auth: Auth; readonly now: number }
+/** One serializable transaction; run again when a row it read changed. */
+export interface MutationCtx { readonly db: Tables<"write">; readonly identity: Identity; readonly auth: Auth; readonly now: number; readonly scheduler: Scheduler }
+/** May wait on the network; its writes are the mutations it runs. */
+export interface ActionCtx {
+  readonly db: { readonly [T in TableNames]: AsyncReader<T> };
+  readonly identity: Identity;
+  readonly auth: Auth;
+  fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+  now(): number; random(bytes?: number): Uint8Array;
+  run<F extends FunctionReference<any>>(fn: F, args: ArgsOf<F>): Promise<F extends FunctionReference<any, any, infer R> ? R : never>;
+  readonly scheduler: { runAfter<F extends FunctionReference<"mutation" | "action">>(ms: number, fn: F, args: ArgsOf<F>): Promise<string>; runAt<F extends FunctionReference<"mutation" | "action">>(at: number, fn: F, args: ArgsOf<F>): Promise<string>; status(id: string): Promise<unknown>; cancel(id: string): Promise<boolean> };
+}
+type ArgsFrom<A> = A extends Fields ? DocOf<A> : Record<string, never>;
+interface Definition<Ctx, A, R> { args?: A; returns?: Validator<R, boolean>; handler: (ctx: Ctx, args: ArgsFrom<A>) => R | Promise<R> }
+/** A mutation or an action may run on a schedule: \`cron: "0 6 * * *"\` (minute hour day month weekday, UTC). */
+interface Scheduled { cron?: string }
+export interface RegisteredFunction<Kind extends string, Args, Returns> { readonly __kind?: Kind; readonly __args?: Args; readonly __returns?: Returns }
+export declare function query<A extends Fields = {}, R = any>(definition: Definition<QueryCtx, A, R>): RegisteredFunction<"query", ArgsFrom<A>, R>;
+export declare function internalQuery<A extends Fields = {}, R = any>(definition: Definition<QueryCtx, A, R>): RegisteredFunction<"query", ArgsFrom<A>, R>;
+export declare function mutation<A extends Fields = {}, R = any>(definition: Definition<MutationCtx, A, R> & Scheduled): RegisteredFunction<"mutation", ArgsFrom<A>, R>;
+export declare function internalMutation<A extends Fields = {}, R = any>(definition: Definition<MutationCtx, A, R> & Scheduled): RegisteredFunction<"mutation", ArgsFrom<A>, R>;
+export declare function action<A extends Fields = {}, R = any>(definition: Definition<ActionCtx, A, R> & Scheduled): RegisteredFunction<"action", ArgsFrom<A>, R>;
+export declare function internalAction<A extends Fields = {}, R = any>(definition: Definition<ActionCtx, A, R> & Scheduled): RegisteredFunction<"action", ArgsFrom<A>, R>;
+
+// ---- Errors ----
+
+/** A \`take\` asked for more than the field holds: the mutation wrote nothing. */
+export declare class InsufficientError extends Error { readonly detail: { table: string; field: string; has: number; asked: number } }
+/** A mutation patched or replaced a row that is not there. */
+export declare class NotFoundError extends Error { readonly detail: { table: string; id: string } }
+
+// ---- The schema ----
+
+export interface TableDefinition<F extends Fields> {
+  /** One field, or a list for a compound index; \`{ unique: true }\`: no two rows may share its key. */
+  index(name: string, field: (keyof F & string) | ReadonlyArray<keyof F & string>, options?: { unique?: boolean }): TableDefinition<F>;
+}
+export declare function defineTable<F extends Fields>(fields: F): TableDefinition<F>;
+export declare function defineSchema<T extends Record<string, TableDefinition<any>>>(tables: T): { tables: T };
+`;
+//#endregion
+export { Refused, buildDatabase, isSource, typeOf };

package/database/client.d.mts

@@ -0,0 +1,60 @@
+import { DatabaseError, DatabaseErrorCode } from "./errors.mjs";
+//#region src/database/client.d.ts
+/** A function's reference, as `api.<file>.<export>` holds it, typed by its arguments and its answer. */
+interface Reference<Kind extends "query" | "mutation" | "action", Args = any, Returns = any> {
+  readonly name: string;
+  readonly kind: Kind;
+  readonly __args?: Args;
+  readonly __returns?: Returns;
+}
+type ArgsOf<F> = F extends Reference<any, infer A, any> ? A : never;
+type ReturnsOf<F> = F extends Reference<any, any, infer R> ? R : never;
+interface Database {
+  query<F extends Reference<"query">>(fn: F, args: ArgsOf<F>): Promise<ReturnsOf<F>>;
+  /**
+   * `tag` identifies this mutation for retries: sent again under it, it applies once while the Database
+   * still keeps the tag, which is for the client's last 64 writes until it has been idle 24 hours. A
+   * tag is made when not given. Give each mutation a tag of its own, and never rely on one past that.
+   */
+  mutation<F extends Reference<"mutation">>(fn: F, args: ArgsOf<F>, options?: {
+    readonly tag?: string;
+  }): Promise<ReturnsOf<F>>;
+  action<F extends Reference<"action">>(fn: F, args: ArgsOf<F>): Promise<ReturnsOf<F>>;
+  /** Gives `onValue` the query's value now and after every change; returns a stop. */
+  watch<F extends Reference<"query">>(fn: F, args: ArgsOf<F>, onValue: (value: ReturnsOf<F>) => void): () => void;
+  close(): void;
+}
+type ConnectOptions = {
+  /** Where the Database serves, as `midsummer db show` gives it, or the development server's address. */
+  readonly url: string;
+  /** A token for this Database. */
+  readonly token?: string;
+  /** A new token, asked for before the one held runs out and when it is refused. */
+  readonly refresh?: () => Promise<string> | string;
+} | {
+  /** A Database Key, `mdbk_…`: exchanged for a token and the Database's address. */
+  readonly key: string;
+  /** The platform's API, where a key is exchanged. */
+  readonly api?: string;
+} | {
+  /** The name the run's Environment binds the Database under: in CI, an Agent's run or `midsummer dev`. */
+  readonly binding: string;
+  /** The platform's API; the one the run's Workload token came from when left out. */
+  readonly api?: string;
+} | {
+  /** `context.database`, the Databases a Deployment's Environment binds. */
+  readonly database: BoundDatabases;
+  /** The name the Environment binds the Database under, such as `main`. */
+  readonly binding: string;
+};
+/** What Midsummer hands a Deployment as `context.database`: a token and address for a Database its Environment binds. */
+interface BoundDatabases {
+  token(binding: string): Promise<{
+    readonly token: string;
+    readonly url: string;
+    readonly expiresAt: number;
+  }>;
+}
+declare function connect(options: ConnectOptions): Promise<Database>;
+//#endregion
+export { BoundDatabases, ConnectOptions, Database, DatabaseError, type DatabaseErrorCode, Reference, connect };