@hot-updater/server 1.0.0-rc.17 → 1.0.0-rc.18

package/dist/database/index.mjs

@@ -1,15 +1,16 @@
-import { DatabaseAmbiguousCommitError, DatabaseConflictError, DatabaseConstraintError, DatabaseTransactionError } from "./errors.mjs";
 import { DatabaseCursorError } from "./cursor.mjs";
+import { DatabaseAmbiguousCommitError, DatabaseConflictError, DatabaseConstraintError, DatabaseTransactionError } from "./errors.mjs";
+import { defineAggregate, defineTable } from "./schema.mjs";
+import { aggregateBatchingModule } from "./aggregateBatching.mjs";
 import { MAX_SHARDS, SHARD_COLUMN, resolveSchema, validateSchema } from "./resolveSchema.mjs";
 import { DatabaseQueryError } from "./engineReads.mjs";
 import { createEngine } from "./engine.mjs";
 import { createDatabaseEngine } from "./database.mjs";
-import { defineAggregate, defineTable } from "./schema.mjs";
 import { ENGINE_SCHEMA_KEY, ENGINE_SCHEMA_VERSION, SETTINGS_TABLE, checkSchemaFence, isMissingSchemaError, withSchemaFence } from "./fence.mjs";
 import { migrateSchema, writeSchemaSettings } from "../db/schemaSettings.mjs";
 import { createTableStatements, isMultiIndex } from "./sql/sqlSchema.mjs";
-import { builtInSchema, builtInSettings, builtInTarget, createEngineDatabase, migrateBuiltInSchema } from "../db/builtInDatabase.mjs";
+import { coreSchema, coreSettings, coreTarget, createEngineDatabase, migrateCoreSchema, toolingTargetOf } from "../db/coreDatabase.mjs";
 import { WRITE_GUARD_TABLE, classifySqlError, createSqlAdapter } from "./sql/sqlAdapter.mjs";
 import { createKvAdapter, encodeKvKey } from "./kv/kvAdapter.mjs";
-import { DATABASE_MAX_MULTI_VALUES, DATABASE_MAX_QUERY_LIMIT, DATABASE_VERSION_COLUMN, DatabaseAdapterContractError, DatabaseSchemaError, DatabaseValueError, compareTuples, compareUtf8, createMemoryAdapter, indexOrderColumns, normalizeStoredRow, normalizeStoredValue, verifyAdapter } from "@hot-updater/plugin-core/internal";
-export { DATABASE_MAX_MULTI_VALUES, DATABASE_MAX_QUERY_LIMIT, DATABASE_VERSION_COLUMN, DatabaseAdapterContractError, DatabaseAmbiguousCommitError, DatabaseConflictError, DatabaseConstraintError, DatabaseCursorError, DatabaseQueryError, DatabaseSchemaError, DatabaseTransactionError, DatabaseValueError, ENGINE_SCHEMA_KEY, ENGINE_SCHEMA_VERSION, MAX_SHARDS, SETTINGS_TABLE, SHARD_COLUMN, WRITE_GUARD_TABLE, builtInSchema, builtInSettings, builtInTarget, checkSchemaFence, classifySqlError, compareTuples, compareUtf8, createDatabaseEngine, createEngine, createEngineDatabase, createKvAdapter, createMemoryAdapter, createSqlAdapter, createTableStatements, defineAggregate, defineTable, encodeKvKey, indexOrderColumns, isMissingSchemaError, isMultiIndex, migrateBuiltInSchema, migrateSchema, normalizeStoredRow, normalizeStoredValue, resolveSchema, validateSchema, verifyAdapter, withSchemaFence, writeSchemaSettings };
+import { DATABASE_MAX_MULTI_VALUES, DATABASE_MAX_QUERY_LIMIT, DATABASE_VERSION_COLUMN, DatabaseAdapterContractError, DatabaseSchemaError, DatabaseValueError, compareTuples, compareUtf8, createMemoryAdapter, expiresAt, indexOrderColumns, normalizeStoredRow, normalizeStoredValue, verifyAdapter } from "@hot-updater/plugin-core/internal";
+export { DATABASE_MAX_MULTI_VALUES, DATABASE_MAX_QUERY_LIMIT, DATABASE_VERSION_COLUMN, DatabaseAdapterContractError, DatabaseAmbiguousCommitError, DatabaseConflictError, DatabaseConstraintError, DatabaseCursorError, DatabaseQueryError, DatabaseSchemaError, DatabaseTransactionError, DatabaseValueError, ENGINE_SCHEMA_KEY, ENGINE_SCHEMA_VERSION, MAX_SHARDS, SETTINGS_TABLE, SHARD_COLUMN, WRITE_GUARD_TABLE, aggregateBatchingModule, checkSchemaFence, classifySqlError, compareTuples, compareUtf8, coreSchema, coreSettings, coreTarget, createDatabaseEngine, createEngine, createEngineDatabase, createKvAdapter, createMemoryAdapter, createSqlAdapter, createTableStatements, defineAggregate, defineTable, encodeKvKey, expiresAt, indexOrderColumns, isMissingSchemaError, isMultiIndex, migrateCoreSchema, migrateSchema, normalizeStoredRow, normalizeStoredValue, resolveSchema, toolingTargetOf, validateSchema, verifyAdapter, withSchemaFence, writeSchemaSettings };

package/dist/database/kv/kvAdapter.cjs

@@ -54,6 +54,11 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 	});
 	const partition = (layout, index, eq) => `${layout.rows}#${index.name}#${encodeKvKey(eq)}`;
 	const copyOf = (layout, row) => Object.fromEntries(layout.copied.map((name) => [name, row[name] ?? null]));
+	/** The expiry every item of `row` carries, for a table with retention. */
+	const stamp = (table, row) => {
+		const at = row && (0, _hot_updater_plugin_core_internal.expiresAt)(table, row);
+		return at === void 0 ? {} : { expiresAt: at };
+	};
 	/** Every index and unique item a row has, by address. */
 	const itemsOf = (layout, row) => {
 		const items = /* @__PURE__ */ new Map();
@@ -87,7 +92,8 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 				type: "put",
 				key: item.key,
 				value: copy,
-				condition: taken ? { exists: false } : void 0
+				condition: taken ? { exists: false } : void 0,
+				...stamp(layout.table, after)
 			});
 		}
 		return ops;
@@ -114,7 +120,8 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 						[_hot_updater_plugin_core_internal.DATABASE_VERSION_COLUMN]: 1
 					},
 					init: op.init,
-					condition: condition ?? (op.init ? void 0 : { exists: true })
+					condition: condition ?? (op.init ? void 0 : { exists: true }),
+					...stamp(op.table, op.init)
 				}];
 			case "delete": return [{
 				type: "delete",
@@ -132,7 +139,8 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 					type: "put",
 					key,
 					value: row,
-					condition
+					condition,
+					...stamp(op.table, row)
 				}, ...indexOps(layout, before, row)];
 			}
 		}
@@ -264,6 +272,10 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 				failedOp: items[result.failedOp].origin
 			} : result;
 		},
+		...store.deleteConsumed === void 0 ? {} : { deleteConsumed: (table, rows) => {
+			const layout = layoutOf(table);
+			return store.deleteConsumed(rows.flatMap((row) => [rowItem(layout, (0, _hot_updater_plugin_core_internal.rowKey)(table, row)), ...[...itemsOf(layout, row).values()].map(({ key }) => key)]));
+		} },
 		migrations: { apply: async () => store.migrations?.apply() },
 		...store.dispose === void 0 ? {} : { dispose: () => store.dispose() }
 	};

package/dist/database/kv/kvAdapter.d.cts

@@ -14,6 +14,12 @@ type KvCondition = {
 type KvOp = {
   readonly key: KvKey;
   readonly condition?: KvCondition;
+  /**
+   * When a put's or a created item expires, in epoch milliseconds, which
+   * the store maps to its native TTL. Every item of a row of a table with
+   * retention carries it, index copies included.
+   */
+  readonly expiresAt?: number;
 } & ({
   readonly type: "put";
   readonly value: StoredRow;
@@ -76,6 +82,8 @@ interface KeyValueStore {
   }>;
   /** Applies every op or none; `failedOp` names an op whose condition failed. */
   write(ops: readonly KvOp[]): Promise<WriteResult>;
+  /** Deletes items with no condition and not atomically, a batch at a time. */
+  deleteConsumed?(keys: readonly KvKey[]): Promise<void>;
   /** Prepares the store, such as its one table, for `db migrate`. */
   readonly migrations?: {
     apply(): Promise<void>;

package/dist/database/kv/kvAdapter.d.mts

@@ -14,6 +14,12 @@ type KvCondition = {
 type KvOp = {
   readonly key: KvKey;
   readonly condition?: KvCondition;
+  /**
+   * When a put's or a created item expires, in epoch milliseconds, which
+   * the store maps to its native TTL. Every item of a row of a table with
+   * retention carries it, index copies included.
+   */
+  readonly expiresAt?: number;
 } & ({
   readonly type: "put";
   readonly value: StoredRow;
@@ -76,6 +82,8 @@ interface KeyValueStore {
   }>;
   /** Applies every op or none; `failedOp` names an op whose condition failed. */
   write(ops: readonly KvOp[]): Promise<WriteResult>;
+  /** Deletes items with no condition and not atomically, a batch at a time. */
+  deleteConsumed?(keys: readonly KvKey[]): Promise<void>;
   /** Prepares the store, such as its one table, for `db migrate`. */
   readonly migrations?: {
     apply(): Promise<void>;

package/dist/database/kv/kvAdapter.mjs

@@ -1,4 +1,4 @@
-import { DATABASE_VERSION_COLUMN, DatabaseAdapterContractError, canonicalJson, compareUtf8, findPhysicalIndex, indexEntries, indexOrderColumns, indexOrderTuple, matchesQuery, rowKey } from "@hot-updater/plugin-core/internal";
+import { DATABASE_VERSION_COLUMN, DatabaseAdapterContractError, canonicalJson, compareUtf8, expiresAt, findPhysicalIndex, indexEntries, indexOrderColumns, indexOrderTuple, matchesQuery, rowKey } from "@hot-updater/plugin-core/internal";
 //#region src/database/kv/kvAdapter.ts
 const SEPARATOR = "
";
 /** Order-preserving text for key values; each value ends in the lowest code point any encoding uses. */
@@ -54,6 +54,11 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 	});
 	const partition = (layout, index, eq) => `${layout.rows}#${index.name}#${encodeKvKey(eq)}`;
 	const copyOf = (layout, row) => Object.fromEntries(layout.copied.map((name) => [name, row[name] ?? null]));
+	/** The expiry every item of `row` carries, for a table with retention. */
+	const stamp = (table, row) => {
+		const at = row && expiresAt(table, row);
+		return at === void 0 ? {} : { expiresAt: at };
+	};
 	/** Every index and unique item a row has, by address. */
 	const itemsOf = (layout, row) => {
 		const items = /* @__PURE__ */ new Map();
@@ -87,7 +92,8 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 				type: "put",
 				key: item.key,
 				value: copy,
-				condition: taken ? { exists: false } : void 0
+				condition: taken ? { exists: false } : void 0,
+				...stamp(layout.table, after)
 			});
 		}
 		return ops;
@@ -114,7 +120,8 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 						[DATABASE_VERSION_COLUMN]: 1
 					},
 					init: op.init,
-					condition: condition ?? (op.init ? void 0 : { exists: true })
+					condition: condition ?? (op.init ? void 0 : { exists: true }),
+					...stamp(op.table, op.init)
 				}];
 			case "delete": return [{
 				type: "delete",
@@ -132,7 +139,8 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 					type: "put",
 					key,
 					value: row,
-					condition
+					condition,
+					...stamp(op.table, row)
 				}, ...indexOps(layout, before, row)];
 			}
 		}
@@ -264,6 +272,10 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 				failedOp: items[result.failedOp].origin
 			} : result;
 		},
+		...store.deleteConsumed === void 0 ? {} : { deleteConsumed: (table, rows) => {
+			const layout = layoutOf(table);
+			return store.deleteConsumed(rows.flatMap((row) => [rowItem(layout, rowKey(table, row)), ...[...itemsOf(layout, row).values()].map(({ key }) => key)]));
+		} },
 		migrations: { apply: async () => store.migrations?.apply() },
 		...store.dispose === void 0 ? {} : { dispose: () => store.dispose() }
 	};

package/dist/database/resolveSchema.cjs

@@ -1,3 +1,4 @@
+const require_retention = require("./retention.cjs");
 let _hot_updater_plugin_core_internal = require("@hot-updater/plugin-core/internal");
 //#region src/database/resolveSchema.ts
 const SHARD_COLUMN = "_shard";
@@ -98,6 +99,7 @@ const problemsOf = (module, model, definition) => {
 	}
 	if (definition.kind === "table") tableProblems(definition, add, table);
 	else aggregateProblems(definition, add);
+	for (const problem of require_retention.retentionProblems(module.schema, model)) add(problem);
 	return problems;
 };
 /** Rejects invalid module schemas at startup, listing every problem. */
@@ -177,7 +179,8 @@ const resolveSchema = (modules) => {
 				name,
 				columns,
 				key: definition.kind === "aggregate" ? [...definition.key, SHARD_COLUMN] : [...definition.key],
-				indexes: indexesOf(definition)
+				indexes: indexesOf(definition),
+				...require_retention.physicalRetention(definition)
 			},
 			references: references.filter(({ table }) => table === name),
 			referencedBy,

package/dist/database/resolveSchema.d.cts

@@ -6,7 +6,7 @@ declare const MAX_SHARDS = 64;
 interface SchemaModule {
   readonly id: string;
   readonly schema: SchemaShape;
-  /** Prefixes this module's table names; third-party plugins use their id. */
+  /** Prefixes this module's table names; a plugin uses its id unless it sets `namespace: false`. */
   readonly namespace?: string;
 }
 interface ResolvedReference {

package/dist/database/resolveSchema.d.mts

@@ -6,7 +6,7 @@ declare const MAX_SHARDS = 64;
 interface SchemaModule {
   readonly id: string;
   readonly schema: SchemaShape;
-  /** Prefixes this module's table names; third-party plugins use their id. */
+  /** Prefixes this module's table names; a plugin uses its id unless it sets `namespace: false`. */
   readonly namespace?: string;
 }
 interface ResolvedReference {

package/dist/database/resolveSchema.mjs

@@ -1,3 +1,4 @@
+import { physicalRetention, retentionProblems } from "./retention.mjs";
 import { DATABASE_VERSION_COLUMN, DatabaseSchemaError } from "@hot-updater/plugin-core/internal";
 //#region src/database/resolveSchema.ts
 const SHARD_COLUMN = "_shard";
@@ -98,6 +99,7 @@ const problemsOf = (module, model, definition) => {
 	}
 	if (definition.kind === "table") tableProblems(definition, add, table);
 	else aggregateProblems(definition, add);
+	for (const problem of retentionProblems(module.schema, model)) add(problem);
 	return problems;
 };
 /** Rejects invalid module schemas at startup, listing every problem. */
@@ -177,7 +179,8 @@ const resolveSchema = (modules) => {
 				name,
 				columns,
 				key: definition.kind === "aggregate" ? [...definition.key, SHARD_COLUMN] : [...definition.key],
-				indexes: indexesOf(definition)
+				indexes: indexesOf(definition),
+				...physicalRetention(definition)
 			},
 			references: references.filter(({ table }) => table === name),
 			referencedBy,

package/dist/database/retention.cjs

@@ -0,0 +1,92 @@
+//#region src/database/retention.ts
+const MINUTE_MS = 6e4;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+/** A model's retention as its physical table carries it, which each adapter maps natively. */
+const physicalRetention = ({ retention }) => retention === void 0 ? {} : { retention: {
+	column: retention.field,
+	ms: retention.days * DAY_MS
+} };
+/** Models in a reference or a rooted index, which an expired row's delete would break. */
+const linkedModels = (schema) => Object.entries(schema).flatMap(([name, { fields, indexes }]) => [...Object.values(fields).map(({ references }) => references), ...Object.values(indexes).map(({ root }) => root)].flatMap((link) => link ? [name, link.model] : []));
+/**
+* What is wrong with a model's retention: it counts from an integer field,
+* over whole days, and expired rows are deleted without cascades, counter
+* moves, or root bumps, so the model is in no reference or rooted index.
+*/
+const retentionProblems = (schema, model) => {
+	const definition = schema[model];
+	if (definition.retention === void 0) return [];
+	const { field, days } = definition.retention;
+	const declared = definition.fields[field] ?? (definition.kind === "table" ? definition.derived[field] : void 0);
+	return [
+		...declared?.type !== "integer" || "multi" in declared && declared.multi === true ? [`retention field "${field}" is not an integer field`] : [],
+		...Number.isSafeInteger(days) && days >= 1 ? [] : ["retention days must be a whole number of at least 1"],
+		...linkedModels(schema).includes(model) ? ["a model with retention is in no reference or rooted index"] : []
+	];
+};
+/**
+* Rows a pass deletes from each table: one statement or two a table, so a
+* pass stays well inside D1's 50 queries an invocation.
+*/
+const PASS_LIMIT = 500;
+/** The lease row: when the next pass is due, in epoch ms. */
+const LEASE_KEY = "retention.nextPassAt";
+/**
+* The adapter, pruning during its writes with no scheduler: once the lease
+* row in `leaseTable` is due, the write that takes it first runs one bounded
+* pass over the tables with retention, and other writers skip. The next pass is due in an hour, or in a minute while a pass still
+* found a full batch of expired rows in some table. A backend that expires
+* rows natively, or a schema without retention, gets its adapter back.
+*/
+const pruneDuringWrites = (adapter, tables, { leaseTable: table, now }) => {
+	const expiring = tables.filter(({ retention }) => retention !== void 0);
+	if (adapter.prune === void 0 || expiring.length === 0) return adapter;
+	const key = [LEASE_KEY];
+	let checkAt = 0;
+	const lease = async (row, due) => {
+		const value = String(due);
+		const guard = { v: row === null ? -1 : Number(row._v) };
+		const next = {
+			key: LEASE_KEY,
+			value,
+			_v: guard.v + 1
+		};
+		const op = row === null ? {
+			type: "insert",
+			table,
+			row: next
+		} : {
+			type: "patch",
+			table,
+			key,
+			set: { value },
+			guard,
+			previous: row
+		};
+		return (await adapter.write([op])).ok ? next : null;
+	};
+	const pass = async () => {
+		const at = now();
+		if (at < checkAt) return;
+		checkAt = at + MINUTE_MS;
+		const [row = null] = await adapter.get(table, [key]);
+		checkAt = row === null ? at : Number(row.value);
+		if (checkAt > at) return;
+		const held = await lease(row, at + HOUR_MS);
+		if (held === null) return;
+		checkAt = at + HOUR_MS;
+		const deleted = [];
+		for (const t of expiring) deleted.push(await adapter.prune(t, at - t.retention.ms, PASS_LIMIT));
+		if (deleted.includes(PASS_LIMIT) && await lease(held, at + MINUTE_MS) !== null) checkAt = at + MINUTE_MS;
+	};
+	const warn = (error) => console.warn("[hot-updater] Pruning expired rows failed.", error);
+	return Object.assign(Object.create(adapter), { async write(ops) {
+		await pass().catch(warn);
+		return adapter.write(ops);
+	} });
+};
+//#endregion
+exports.physicalRetention = physicalRetention;
+exports.pruneDuringWrites = pruneDuringWrites;
+exports.retentionProblems = retentionProblems;

package/dist/database/retention.mjs

@@ -0,0 +1,90 @@
+//#region src/database/retention.ts
+const MINUTE_MS = 6e4;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+/** A model's retention as its physical table carries it, which each adapter maps natively. */
+const physicalRetention = ({ retention }) => retention === void 0 ? {} : { retention: {
+	column: retention.field,
+	ms: retention.days * DAY_MS
+} };
+/** Models in a reference or a rooted index, which an expired row's delete would break. */
+const linkedModels = (schema) => Object.entries(schema).flatMap(([name, { fields, indexes }]) => [...Object.values(fields).map(({ references }) => references), ...Object.values(indexes).map(({ root }) => root)].flatMap((link) => link ? [name, link.model] : []));
+/**
+* What is wrong with a model's retention: it counts from an integer field,
+* over whole days, and expired rows are deleted without cascades, counter
+* moves, or root bumps, so the model is in no reference or rooted index.
+*/
+const retentionProblems = (schema, model) => {
+	const definition = schema[model];
+	if (definition.retention === void 0) return [];
+	const { field, days } = definition.retention;
+	const declared = definition.fields[field] ?? (definition.kind === "table" ? definition.derived[field] : void 0);
+	return [
+		...declared?.type !== "integer" || "multi" in declared && declared.multi === true ? [`retention field "${field}" is not an integer field`] : [],
+		...Number.isSafeInteger(days) && days >= 1 ? [] : ["retention days must be a whole number of at least 1"],
+		...linkedModels(schema).includes(model) ? ["a model with retention is in no reference or rooted index"] : []
+	];
+};
+/**
+* Rows a pass deletes from each table: one statement or two a table, so a
+* pass stays well inside D1's 50 queries an invocation.
+*/
+const PASS_LIMIT = 500;
+/** The lease row: when the next pass is due, in epoch ms. */
+const LEASE_KEY = "retention.nextPassAt";
+/**
+* The adapter, pruning during its writes with no scheduler: once the lease
+* row in `leaseTable` is due, the write that takes it first runs one bounded
+* pass over the tables with retention, and other writers skip. The next pass is due in an hour, or in a minute while a pass still
+* found a full batch of expired rows in some table. A backend that expires
+* rows natively, or a schema without retention, gets its adapter back.
+*/
+const pruneDuringWrites = (adapter, tables, { leaseTable: table, now }) => {
+	const expiring = tables.filter(({ retention }) => retention !== void 0);
+	if (adapter.prune === void 0 || expiring.length === 0) return adapter;
+	const key = [LEASE_KEY];
+	let checkAt = 0;
+	const lease = async (row, due) => {
+		const value = String(due);
+		const guard = { v: row === null ? -1 : Number(row._v) };
+		const next = {
+			key: LEASE_KEY,
+			value,
+			_v: guard.v + 1
+		};
+		const op = row === null ? {
+			type: "insert",
+			table,
+			row: next
+		} : {
+			type: "patch",
+			table,
+			key,
+			set: { value },
+			guard,
+			previous: row
+		};
+		return (await adapter.write([op])).ok ? next : null;
+	};
+	const pass = async () => {
+		const at = now();
+		if (at < checkAt) return;
+		checkAt = at + MINUTE_MS;
+		const [row = null] = await adapter.get(table, [key]);
+		checkAt = row === null ? at : Number(row.value);
+		if (checkAt > at) return;
+		const held = await lease(row, at + HOUR_MS);
+		if (held === null) return;
+		checkAt = at + HOUR_MS;
+		const deleted = [];
+		for (const t of expiring) deleted.push(await adapter.prune(t, at - t.retention.ms, PASS_LIMIT));
+		if (deleted.includes(PASS_LIMIT) && await lease(held, at + MINUTE_MS) !== null) checkAt = at + MINUTE_MS;
+	};
+	const warn = (error) => console.warn("[hot-updater] Pruning expired rows failed.", error);
+	return Object.assign(Object.create(adapter), { async write(ops) {
+		await pass().catch(warn);
+		return adapter.write(ops);
+	} });
+};
+//#endregion
+export { physicalRetention, pruneDuringWrites, retentionProblems };

package/dist/database/schema.cjs

@@ -4,7 +4,8 @@ const defineTable = (fields, options) => ({
 	fields,
 	key: options.key,
 	derived: options.derived ?? {},
-	indexes: options.indexes ?? {}
+	indexes: options.indexes ?? {},
+	...options.retention === void 0 ? {} : { retention: options.retention }
 });
 const defineAggregate = (fields, options) => ({
 	kind: "aggregate",
@@ -14,7 +15,9 @@ const defineAggregate = (fields, options) => ({
 	gauges: options.gauges ?? [],
 	distinct: options.distinct ?? [],
 	shards: options.shards ?? 1,
-	indexes: options.indexes ?? {}
+	indexes: options.indexes ?? {},
+	...options.batched ? { batched: true } : {},
+	...options.retention === void 0 ? {} : { retention: options.retention }
 });
 //#endregion
 exports.defineAggregate = defineAggregate;

package/dist/database/schema.d.cts

@@ -1,6 +1,16 @@
 import { AggregateShape, FieldDefinition, FieldReference, FieldType, IndexDefinition, ReferenceAction, TableShape } from "./definitions.cjs";
 import { DatabaseJson } from "@hot-updater/plugin-core/internal";
 //#region src/database/schema.d.ts
+/**
+ * How long a model keeps its rows: `days` past the epoch milliseconds in
+ * `field`, an integer field (a table's derived one too, where null keeps
+ * the row). Expired rows are deleted without cascades, so a model with
+ * retention is in no reference and no rooted index.
+ */
+interface RetentionDefinition<TField extends string = string> {
+  readonly field: TField;
+  readonly days: number;
+}
 type FieldValue<TType extends FieldType> = TType extends "string" ? string : TType extends "integer" | "number" ? number : TType extends "boolean" ? boolean : DatabaseJson;
 type Fields = Readonly<Record<string, FieldDefinition>>;
 type RowOf<TFields extends Fields> = { -readonly [K in keyof TFields]: TFields[K] extends FieldDefinition<infer TType> ? TFields[K] extends {
@@ -18,6 +28,10 @@ type DerivedTypes = Readonly<Record<string, FieldType>>;
 /** Derived fields over a table's row, by name. */
 type DerivedFields<TFields extends Fields, TDerived extends DerivedTypes> = { readonly [K in keyof TDerived]: DerivedDefinition<RowOf<TFields>, TDerived[K]>; };
 type Indexes = Readonly<Record<string, IndexDefinition>>;
+/** The integer fields, declared or derived, that retention can count from. */
+type IntegerFields<TFields extends Fields, TDerived extends DerivedTypes> = { [K in keyof TFields]: TFields[K] extends {
+  readonly type: "integer";
+} ? K : never; }[keyof TFields] | { [K in keyof TDerived]: TDerived[K] extends "integer" ? K : never; }[keyof TDerived];
 type MissingFields<TIndex, TNames extends string> = TIndex extends {
   readonly eq: readonly (infer TEq)[];
   readonly sort: readonly (infer TSort)[];
@@ -36,6 +50,8 @@ declare const defineTable: <const TFields extends Fields, const TKey extends rea
   readonly key: TKey;
   readonly derived?: DerivedFields<TFields, TDerived>;
   readonly indexes?: TIndexes & CheckIndexes<TIndexes, (keyof TFields | keyof TDerived) & string>;
+  /** Rows expire `days` after the epoch milliseconds in `field`. */
+  readonly retention?: RetentionDefinition<IntegerFields<TFields, TDerived> & string>;
 }) => TableDefinition<TFields, TDerived, TIndexes, TKey>;
 interface AggregateDefinition<TFields extends Fields = Fields, TMetric extends string = string, TIndexes extends Indexes = Indexes, TSketch extends string = string, TKey extends readonly (keyof TFields & string)[] = readonly (keyof TFields & string)[]> extends AggregateShape {
   readonly kind: "aggregate";
@@ -45,6 +61,12 @@ interface AggregateDefinition<TFields extends Fields = Fields, TMetric extends s
   readonly gauges: readonly TMetric[];
   readonly distinct: readonly TSketch[];
   readonly indexes: TIndexes;
+  /**
+   * On a database that batches aggregates, changes apply after their
+   * transaction commits, in one write per row with other transactions'
+   * changes, so reads may lag them. Elsewhere they commit with it.
+   */
+  readonly batched?: true;
 }
 declare const defineAggregate: <const TFields extends Fields, const TKey extends readonly (keyof TFields & string)[], const TMetric extends string = never, const TIndexes extends Indexes = {}, const TSketch extends string = never>(fields: TFields, options: {
   readonly key: TKey;
@@ -53,9 +75,16 @@ declare const defineAggregate: <const TFields extends Fields, const TKey extends
   readonly distinct?: readonly TSketch[];
   readonly shards?: number;
   readonly indexes?: TIndexes & CheckIndexes<TIndexes, keyof TFields & string>;
+  readonly batched?: true;
+  /**
+   * Rows expire `days` after the epoch milliseconds in `field`, an
+   * identity field such as a bucket's start; a change to a row already
+   * past it is dropped, so a late gauge decrement never goes below zero.
+   */
+  readonly retention?: RetentionDefinition<IntegerFields<TFields, {}> & string>;
 }) => AggregateDefinition<TFields, TMetric, TIndexes, TSketch, TKey>;
 type ModelDefinition = TableDefinition | AggregateDefinition;
 /** A module's models by name: core, or one plugin. */
 type ModuleSchema = Readonly<Record<string, ModelDefinition>>;
 //#endregion
-export { AggregateDefinition, CheckIndex, DerivedDefinition, DerivedFields, type FieldDefinition, type FieldReference, type FieldType, FieldValue, type IndexDefinition, ModelDefinition, ModuleSchema, type ReferenceAction, RowOf, TableDefinition, defineAggregate, defineTable };
+export { AggregateDefinition, CheckIndex, DerivedDefinition, DerivedFields, type FieldDefinition, type FieldReference, type FieldType, FieldValue, type IndexDefinition, ModelDefinition, ModuleSchema, type ReferenceAction, RetentionDefinition, RowOf, TableDefinition, defineAggregate, defineTable };

package/dist/database/schema.d.mts

@@ -1,6 +1,16 @@
 import { AggregateShape, FieldDefinition, FieldReference, FieldType, IndexDefinition, ReferenceAction, TableShape } from "./definitions.mjs";
 import { DatabaseJson } from "@hot-updater/plugin-core/internal";
 //#region src/database/schema.d.ts
+/**
+ * How long a model keeps its rows: `days` past the epoch milliseconds in
+ * `field`, an integer field (a table's derived one too, where null keeps
+ * the row). Expired rows are deleted without cascades, so a model with
+ * retention is in no reference and no rooted index.
+ */
+interface RetentionDefinition<TField extends string = string> {
+  readonly field: TField;
+  readonly days: number;
+}
 type FieldValue<TType extends FieldType> = TType extends "string" ? string : TType extends "integer" | "number" ? number : TType extends "boolean" ? boolean : DatabaseJson;
 type Fields = Readonly<Record<string, FieldDefinition>>;
 type RowOf<TFields extends Fields> = { -readonly [K in keyof TFields]: TFields[K] extends FieldDefinition<infer TType> ? TFields[K] extends {
@@ -18,6 +28,10 @@ type DerivedTypes = Readonly<Record<string, FieldType>>;
 /** Derived fields over a table's row, by name. */
 type DerivedFields<TFields extends Fields, TDerived extends DerivedTypes> = { readonly [K in keyof TDerived]: DerivedDefinition<RowOf<TFields>, TDerived[K]>; };
 type Indexes = Readonly<Record<string, IndexDefinition>>;
+/** The integer fields, declared or derived, that retention can count from. */
+type IntegerFields<TFields extends Fields, TDerived extends DerivedTypes> = { [K in keyof TFields]: TFields[K] extends {
+  readonly type: "integer";
+} ? K : never; }[keyof TFields] | { [K in keyof TDerived]: TDerived[K] extends "integer" ? K : never; }[keyof TDerived];
 type MissingFields<TIndex, TNames extends string> = TIndex extends {
   readonly eq: readonly (infer TEq)[];
   readonly sort: readonly (infer TSort)[];
@@ -36,6 +50,8 @@ declare const defineTable: <const TFields extends Fields, const TKey extends rea
   readonly key: TKey;
   readonly derived?: DerivedFields<TFields, TDerived>;
   readonly indexes?: TIndexes & CheckIndexes<TIndexes, (keyof TFields | keyof TDerived) & string>;
+  /** Rows expire `days` after the epoch milliseconds in `field`. */
+  readonly retention?: RetentionDefinition<IntegerFields<TFields, TDerived> & string>;
 }) => TableDefinition<TFields, TDerived, TIndexes, TKey>;
 interface AggregateDefinition<TFields extends Fields = Fields, TMetric extends string = string, TIndexes extends Indexes = Indexes, TSketch extends string = string, TKey extends readonly (keyof TFields & string)[] = readonly (keyof TFields & string)[]> extends AggregateShape {
   readonly kind: "aggregate";
@@ -45,6 +61,12 @@ interface AggregateDefinition<TFields extends Fields = Fields, TMetric extends s
   readonly gauges: readonly TMetric[];
   readonly distinct: readonly TSketch[];
   readonly indexes: TIndexes;
+  /**
+   * On a database that batches aggregates, changes apply after their
+   * transaction commits, in one write per row with other transactions'
+   * changes, so reads may lag them. Elsewhere they commit with it.
+   */
+  readonly batched?: true;
 }
 declare const defineAggregate: <const TFields extends Fields, const TKey extends readonly (keyof TFields & string)[], const TMetric extends string = never, const TIndexes extends Indexes = {}, const TSketch extends string = never>(fields: TFields, options: {
   readonly key: TKey;
@@ -53,9 +75,16 @@ declare const defineAggregate: <const TFields extends Fields, const TKey extends
   readonly distinct?: readonly TSketch[];
   readonly shards?: number;
   readonly indexes?: TIndexes & CheckIndexes<TIndexes, keyof TFields & string>;
+  readonly batched?: true;
+  /**
+   * Rows expire `days` after the epoch milliseconds in `field`, an
+   * identity field such as a bucket's start; a change to a row already
+   * past it is dropped, so a late gauge decrement never goes below zero.
+   */
+  readonly retention?: RetentionDefinition<IntegerFields<TFields, {}> & string>;
 }) => AggregateDefinition<TFields, TMetric, TIndexes, TSketch, TKey>;
 type ModelDefinition = TableDefinition | AggregateDefinition;
 /** A module's models by name: core, or one plugin. */
 type ModuleSchema = Readonly<Record<string, ModelDefinition>>;
 //#endregion
-export { AggregateDefinition, CheckIndex, DerivedDefinition, DerivedFields, type FieldDefinition, type FieldReference, type FieldType, FieldValue, type IndexDefinition, ModelDefinition, ModuleSchema, type ReferenceAction, RowOf, TableDefinition, defineAggregate, defineTable };
+export { AggregateDefinition, CheckIndex, DerivedDefinition, DerivedFields, type FieldDefinition, type FieldReference, type FieldType, FieldValue, type IndexDefinition, ModelDefinition, ModuleSchema, type ReferenceAction, RetentionDefinition, RowOf, TableDefinition, defineAggregate, defineTable };

package/dist/database/schema.mjs

@@ -4,7 +4,8 @@ const defineTable = (fields, options) => ({
 	fields,
 	key: options.key,
 	derived: options.derived ?? {},
-	indexes: options.indexes ?? {}
+	indexes: options.indexes ?? {},
+	...options.retention === void 0 ? {} : { retention: options.retention }
 });
 const defineAggregate = (fields, options) => ({
 	kind: "aggregate",
@@ -14,7 +15,9 @@ const defineAggregate = (fields, options) => ({
 	gauges: options.gauges ?? [],
 	distinct: options.distinct ?? [],
 	shards: options.shards ?? 1,
-	indexes: options.indexes ?? {}
+	indexes: options.indexes ?? {},
+	...options.batched ? { batched: true } : {},
+	...options.retention === void 0 ? {} : { retention: options.retention }
 });
 //#endregion
 export { defineAggregate, defineTable };

package/dist/database/sql/sqlAdapter.cjs

@@ -265,6 +265,14 @@ const createSqlAdapter = ({ executor, tablePrefix = "", maxOps = 1e3, maxParams
 				throw error;
 			}
 		},
+		async prune(table, before, limit) {
+			const statements = require_sqlSchema.pruneStatements(dialect, table, tablePrefix, limit).map((render) => sql((bind) => render(() => bind(before))));
+			return (executor.batch ? await executor.batch(statements) : await executor.transaction(async (connection) => {
+				const done = [];
+				for (const statement of statements) done.push(await connection.execute(statement));
+				return done;
+			})).at(-1)?.changes ?? 0;
+		},
 		migrations: { async apply(tables) {
 			const created = executor.batch && !tables.includes(WRITE_GUARD_TABLE) ? [...tables, WRITE_GUARD_TABLE] : tables;
 			const statements = require_sqlSchema.createTableStatements(dialect, created, tablePrefix);

package/dist/database/sql/sqlAdapter.mjs

@@ -1,4 +1,4 @@
-import { createTableStatements, isMultiIndex, quoteSql } from "./sqlSchema.mjs";
+import { createTableStatements, isMultiIndex, pruneStatements, quoteSql } from "./sqlSchema.mjs";
 import { DATABASE_VERSION_COLUMN, findPhysicalColumn, findPhysicalIndex, indexEntries, indexOrderColumns, indexOrderTuple, normalizeStoredRow, rowKey } from "@hot-updater/plugin-core/internal";
 //#region src/database/sql/sqlAdapter.ts
 /** Where a batch write records its first failed op, before any change applies. */
@@ -265,6 +265,14 @@ const createSqlAdapter = ({ executor, tablePrefix = "", maxOps = 1e3, maxParams
 				throw error;
 			}
 		},
+		async prune(table, before, limit) {
+			const statements = pruneStatements(dialect, table, tablePrefix, limit).map((render) => sql((bind) => render(() => bind(before))));
+			return (executor.batch ? await executor.batch(statements) : await executor.transaction(async (connection) => {
+				const done = [];
+				for (const statement of statements) done.push(await connection.execute(statement));
+				return done;
+			})).at(-1)?.changes ?? 0;
+		},
 		migrations: { async apply(tables) {
 			const created = executor.batch && !tables.includes(WRITE_GUARD_TABLE) ? [...tables, WRITE_GUARD_TABLE] : tables;
 			const statements = createTableStatements(dialect, created, tablePrefix);