better-convex 0.7.2 → 0.8.0

package/dist/orm/index.js

@@ -1,5 +1,10 @@
-import { A as entityKind, C as text, D as custom, E as id, O as json, S as vectorIndex, T as integer, _ as aggregateIndex, a as deletion, b as searchIndex, c as EnableRLS, d as OrmSchemaOptions, f as RlsPolicies, g as rlsPolicy, h as RlsPolicy, i as convexTable, k as ConvexColumnBuilder, l as OrmContext, m as TableName, o as Brand, p as TableDeleteConfig, s as Columns, t as DirectAggregate, u as OrmSchemaDefinition, v as index, w as createSystemFields, x as uniqueIndex, y as rankIndex } from "../runtime-B9xQFY8W.js";
-import { A as ne, C as inArray, D as like, E as isNull, F as notLike, I as or, L as startsWith, M as notBetween, N as notIlike, O as lt, P as notInArray, S as ilike, T as isNotNull, _ as endsWith, a as mergedStream, b as gt, c as isUnsetToken, d as arrayContained, f as arrayContains, g as contains, h as column, i as getIndexFields, j as not, k as lte, l as unsetToken, m as between, n as EmptyStream, o as stream, p as arrayOverlaps, r as QueryStream, s as streamIndexRange, t as getByIdWithOrmQueryFallback, u as and, v as eq, w as isFieldReference, x as gte, y as fieldRef } from "../query-context-BDSis9rT.js";
+import { t as DirectAggregate } from "../runtime-C0WcYGY0.js";
+import { C as integer, S as createSystemFields, T as entityKind, _ as rankIndex, a as EnableRLS, b as vectorIndex, c as OrmSchemaOptions, d as TableDeleteConfig, f as TableName, g as index, h as aggregateIndex, i as Columns, l as OrmSchemaPluginTables, m as rlsPolicy, n as deletion, o as OrmContext, p as RlsPolicy, r as Brand, s as OrmSchemaDefinition, t as convexTable, u as RlsPolicies, v as searchIndex, w as ConvexColumnBuilder, x as text, y as uniqueIndex } from "../table-B7yzBihE.js";
+import { a as AGGREGATE_EXTREMA_TABLE, c as aggregatePlugin, i as AGGREGATE_BUCKET_TABLE, l as boolean, n as MIGRATION_STATE_TABLE, o as AGGREGATE_MEMBER_TABLE, r as migrationPlugin, s as AGGREGATE_STATE_TABLE, t as MIGRATION_RUN_TABLE } from "../schema-Bx6j2doh.js";
+import { a as pretendRequired, i as pretend, n as deprecated } from "../validators-D_i3BK7v.js";
+import { a as objectOf, i as json, n as arrayOf, r as custom, t as id } from "../id-BcBb900m.js";
+import { t as textEnum } from "../text-enum-CFdcLUuw.js";
+import { A as ne, C as inArray, D as like, E as isNull, F as notLike, I as or, L as startsWith, M as notBetween, N as notIlike, O as lt, P as notInArray, S as ilike, T as isNotNull, _ as endsWith, a as mergedStream, b as gt, c as isUnsetToken, d as arrayContained, f as arrayContains, g as contains, h as column, i as getIndexFields, j as not, k as lte, l as unsetToken, m as between, n as EmptyStream, o as stream, p as arrayOverlaps, r as QueryStream, s as streamIndexRange, t as getByIdWithOrmQueryFallback, u as and, v as eq, w as isFieldReference, x as gte, y as fieldRef } from "../query-context-DEUFBhXS.js";
 import { v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric } from "convex/server";
 
@@ -33,37 +38,6 @@ function bigint(name) {
 	return new ConvexBigIntBuilder(name ?? "");
 }
 
-//#endregion
-//#region src/orm/builders/boolean.ts
-/**
-* Boolean column builder class
-* Compiles to v.boolean() or v.optional(v.boolean())
-*/
-var ConvexBooleanBuilder = class extends ConvexColumnBuilder {
-	static [entityKind] = "ConvexBooleanBuilder";
-	constructor(name) {
-		super(name, "boolean", "ConvexBoolean");
-	}
-	/**
-	* Expose Convex validator for schema integration
-	*/
-	get convexValidator() {
-		if (this.config.notNull) return v.boolean();
-		return v.optional(v.union(v.null(), v.boolean()));
-	}
-	/**
-	* Compile to Convex validator
-	* .notNull() → v.boolean()
-	* nullable → v.optional(v.boolean())
-	*/
-	build() {
-		return this.convexValidator;
-	}
-};
-function boolean(name) {
-	return new ConvexBooleanBuilder(name ?? "");
-}
-
 //#endregion
 //#region src/orm/builders/bytes.ts
 var ConvexBytesBuilder = class extends ConvexColumnBuilder {
@@ -115,32 +89,6 @@ function date(nameOrConfig, maybeConfig) {
 	return new ConvexDateBuilder(name, mode);
 }
 
-//#endregion
-//#region src/orm/builders/text-enum.ts
-var ConvexTextEnumBuilder = class extends ConvexColumnBuilder {
-	static [entityKind] = "ConvexTextEnumBuilder";
-	constructor(name, values) {
-		super(name, "string", "ConvexText");
-		this.config.values = [...values];
-	}
-	_enumValidator() {
-		const literals = this.config.values.map((value) => v.literal(value));
-		if (literals.length === 1) return literals[0];
-		return v.union(...literals);
-	}
-	get convexValidator() {
-		const base = this._enumValidator();
-		if (this.config.notNull) return base;
-		return v.optional(v.union(v.null(), base));
-	}
-	build() {
-		return this.convexValidator;
-	}
-};
-function textEnum(values) {
-	return new ConvexTextEnumBuilder("", values);
-}
-
 //#endregion
 //#region src/orm/builders/timestamp.ts
 var ConvexTimestampBuilder = class extends ConvexColumnBuilder {
@@ -289,105 +237,6 @@ function check(name, expression) {
 	return new ConvexCheckBuilder(name, expression);
 }
 
-//#endregion
-//#region src/orm/aggregate-index/schema.ts
-const AGGREGATE_BUCKET_TABLE = "aggregate_bucket";
-const AGGREGATE_MEMBER_TABLE = "aggregate_member";
-const AGGREGATE_EXTREMA_TABLE = "aggregate_extrema";
-const AGGREGATE_RANK_TREE_TABLE = "aggregate_rank_tree";
-const AGGREGATE_RANK_NODE_TABLE = "aggregate_rank_node";
-const AGGREGATE_STATE_TABLE = "aggregate_state";
-const countBucketTable = convexTable(AGGREGATE_BUCKET_TABLE, {
-	tableKey: text().notNull(),
-	indexName: text().notNull(),
-	keyHash: text().notNull(),
-	keyParts: custom(v.array(v.any())).notNull(),
-	count: integer().notNull(),
-	sumValues: custom(v.record(v.string(), v.number())).notNull(),
-	nonNullCountValues: custom(v.record(v.string(), v.number())).notNull(),
-	updatedAt: integer().notNull()
-}, (t) => [index("by_table_index_hash").on(t.tableKey, t.indexName, t.keyHash), index("by_table_index").on(t.tableKey, t.indexName)]);
-const countMemberTable = convexTable(AGGREGATE_MEMBER_TABLE, {
-	kind: text().notNull(),
-	tableKey: text().notNull(),
-	indexName: text().notNull(),
-	docId: text().notNull(),
-	keyHash: text().notNull(),
-	keyParts: custom(v.array(v.any())).notNull(),
-	sumValues: custom(v.record(v.string(), v.number())).notNull(),
-	nonNullCountValues: custom(v.record(v.string(), v.number())).notNull(),
-	extremaValues: custom(v.record(v.string(), v.any())).notNull(),
-	rankNamespace: custom(v.any()),
-	rankKey: custom(v.any()),
-	rankSumValue: integer(),
-	updatedAt: integer().notNull()
-}, (t) => [index("by_kind_table_index_doc").on(t.kind, t.tableKey, t.indexName, t.docId), index("by_kind_table_index").on(t.kind, t.tableKey, t.indexName)]);
-const countExtremaTable = convexTable(AGGREGATE_EXTREMA_TABLE, {
-	tableKey: text().notNull(),
-	indexName: text().notNull(),
-	keyHash: text().notNull(),
-	fieldName: text().notNull(),
-	valueHash: text().notNull(),
-	value: custom(v.any()).notNull(),
-	sortKey: text().notNull(),
-	count: integer().notNull(),
-	updatedAt: integer().notNull()
-}, (t) => [
-	index("by_table_index").on(t.tableKey, t.indexName),
-	index("by_table_index_hash_field_value").on(t.tableKey, t.indexName, t.keyHash, t.fieldName, t.valueHash),
-	index("by_table_index_hash_field_sort").on(t.tableKey, t.indexName, t.keyHash, t.fieldName, t.sortKey)
-]);
-const countStateTable = convexTable(AGGREGATE_STATE_TABLE, {
-	kind: text().notNull(),
-	tableKey: text().notNull(),
-	indexName: text().notNull(),
-	keyDefinitionHash: text().notNull(),
-	metricDefinitionHash: text().notNull(),
-	status: text().notNull(),
-	cursor: text(),
-	processed: integer().notNull(),
-	startedAt: integer().notNull(),
-	updatedAt: integer().notNull(),
-	completedAt: integer(),
-	lastError: text()
-}, (t) => [index("by_kind_table_index").on(t.kind, t.tableKey, t.indexName), index("by_kind_status").on(t.kind, t.status)]);
-const aggregateCounterValidator = v.object({
-	count: v.number(),
-	sum: v.number()
-});
-const aggregateItemValidator = v.object({
-	k: v.any(),
-	v: v.any(),
-	s: v.number()
-});
-const rankTreeTable = convexTable(AGGREGATE_RANK_TREE_TABLE, {
-	aggregateName: text().notNull(),
-	maxNodeSize: integer().notNull(),
-	namespace: custom(v.any()),
-	root: id(AGGREGATE_RANK_NODE_TABLE).notNull()
-}, (tree) => [index("by_namespace").on(tree.namespace), index("by_aggregate_name").on(tree.aggregateName)]);
-const rankNodeTable = convexTable(AGGREGATE_RANK_NODE_TABLE, {
-	aggregate: custom(aggregateCounterValidator),
-	items: custom(v.array(aggregateItemValidator)).notNull(),
-	subtrees: custom(v.array(v.string())).notNull()
-});
-const aggregateStorageTables = {
-	[AGGREGATE_BUCKET_TABLE]: countBucketTable,
-	[AGGREGATE_MEMBER_TABLE]: countMemberTable,
-	[AGGREGATE_EXTREMA_TABLE]: countExtremaTable,
-	[AGGREGATE_RANK_TREE_TABLE]: rankTreeTable,
-	[AGGREGATE_RANK_NODE_TABLE]: rankNodeTable,
-	[AGGREGATE_STATE_TABLE]: countStateTable
-};
-function injectAggregateStorageTables(schema) {
-	const merged = { ...schema };
-	for (const [tableName, tableDef] of Object.entries(aggregateStorageTables)) {
-		if (tableName in schema && schema[tableName] !== tableDef) throw new Error(`defineSchema cannot inject internal table '${tableName}' because the name is already in use.`);
-		merged[tableName] = tableDef;
-	}
-	return merged;
-}
-
 //#endregion
 //#region src/orm/aggregate-index/runtime.ts
 const UNDEFINED_SENTINEL = "__betterConvexUndefined";
@@ -8924,6 +8773,624 @@ function isOne(relation) {
 	return relation.relationType === "one";
 }
 
+//#endregion
+//#region src/orm/migrations/definitions.ts
+const MIGRATION_ID_RE = /^[a-zA-Z0-9_:-]+$/;
+const FUNCTION_SOURCE_WHITESPACE_RE = /\s+/g;
+const FUNCTION_SOURCE_PUNCTUATION_SPACE_RE = /\s*([{}();,:])\s*/g;
+function defineMigration(migration) {
+	validateMigrationId(migration.id);
+	validateMigrationStep("up", migration.up);
+	if (migration.down) validateMigrationStep("down", migration.down);
+	return migration;
+}
+function defineMigrationSet(migrations) {
+	const normalized = [...migrations].map((migration) => {
+		const defined = defineMigration(migration);
+		return {
+			...defined,
+			checksum: defined.checksum ?? computeMigrationChecksum(defined)
+		};
+	});
+	normalized.sort((a, b) => a.id.localeCompare(b.id));
+	const byId = {};
+	for (const migration of normalized) {
+		if (byId[migration.id]) throw new Error(`defineMigrationSet received duplicate migration id '${migration.id}'.`);
+		byId[migration.id] = migration;
+	}
+	return {
+		migrations: normalized,
+		ids: normalized.map((migration) => migration.id),
+		byId
+	};
+}
+function detectMigrationDrift(params) {
+	const { migrationSet, appliedState } = params;
+	const issues = [];
+	for (const [migrationId, state] of Object.entries(appliedState)) {
+		if (!state.applied) continue;
+		const migration = migrationSet.byId[migrationId];
+		if (!migration) {
+			issues.push({
+				kind: "missing_from_manifest",
+				migrationId,
+				message: `Applied migration '${migrationId}' is missing from the current migration manifest.`
+			});
+			continue;
+		}
+		if (state.checksum && state.checksum !== migration.checksum) issues.push({
+			kind: "checksum_mismatch",
+			migrationId,
+			expectedChecksum: migration.checksum,
+			actualChecksum: state.checksum,
+			message: `Applied migration '${migrationId}' checksum drift detected.`
+		});
+	}
+	return issues;
+}
+function buildMigrationPlan(params) {
+	const { direction, migrationSet, appliedState, steps, to } = params;
+	if (direction === "up") return {
+		direction,
+		migrations: migrationSet.migrations.filter((migration) => !appliedState[migration.id]?.applied)
+	};
+	if (steps !== void 0 && to !== void 0) throw new Error("Use either down steps or down to, not both.");
+	const appliedInOrder = migrationSet.migrations.filter((migration) => appliedState[migration.id]?.applied);
+	const ensureDownSteps = (selected) => {
+		const missingDown = selected.find((migration) => !migration.down);
+		if (missingDown) throw new Error(`Cannot execute down migration for '${missingDown.id}': missing down migration handler.`);
+		return selected;
+	};
+	if (to) {
+		const targetIndex = migrationSet.ids.indexOf(to);
+		if (targetIndex === -1) throw new Error(`Unknown migration id '${to}' for down --to.`);
+		return {
+			direction,
+			migrations: ensureDownSteps(appliedInOrder.filter((migration) => {
+				return migrationSet.ids.indexOf(migration.id) > targetIndex;
+			})).reverse()
+		};
+	}
+	const resolvedSteps = steps ?? 1;
+	if (!Number.isInteger(resolvedSteps) || resolvedSteps < 1) throw new Error("Down steps must be a positive integer.");
+	return {
+		direction,
+		migrations: ensureDownSteps(appliedInOrder.slice(-resolvedSteps).reverse())
+	};
+}
+function validateMigrationId(id) {
+	if (!id || typeof id !== "string") throw new Error("Migration id must be a non-empty string.");
+	if (!MIGRATION_ID_RE.test(id)) throw new Error(`Migration id '${id}' is invalid. Use alphanumeric characters, '_' ':' or '-'.`);
+}
+function validateMigrationStep(direction, step) {
+	if (!step || typeof step !== "object") throw new Error(`Migration ${direction} step must be an object.`);
+	if (!step.table || typeof step.table !== "string") throw new Error(`Migration ${direction} step.table must be a string.`);
+	if (typeof step.migrateOne !== "function") throw new Error(`Migration ${direction} step.migrateOne must be a function.`);
+	if (step.batchSize !== void 0 && (!Number.isInteger(step.batchSize) || step.batchSize < 1)) throw new Error(`Migration ${direction} step.batchSize must be a positive integer.`);
+	if (step.writeMode !== void 0 && step.writeMode !== "safe_bypass" && step.writeMode !== "normal") throw new Error(`Migration ${direction} step.writeMode must be 'safe_bypass' or 'normal'.`);
+}
+function computeMigrationChecksum(migration) {
+	return simpleStableHash(JSON.stringify({
+		id: migration.id,
+		name: migration.name ?? null,
+		description: migration.description ?? null,
+		up: serializeStep(migration.up),
+		down: migration.down ? serializeStep(migration.down) : null
+	}));
+}
+function serializeStep(step) {
+	return {
+		table: step.table,
+		batchSize: step.batchSize ?? null,
+		writeMode: step.writeMode ?? "safe_bypass",
+		source: normalizeFunctionSource(step.migrateOne)
+	};
+}
+function normalizeFunctionSource(fn) {
+	return fn.toString().replace(FUNCTION_SOURCE_WHITESPACE_RE, " ").replace(FUNCTION_SOURCE_PUNCTUATION_SPACE_RE, "$1").trim();
+}
+function simpleStableHash(value) {
+	let hashA = 2166136261;
+	let hashB = 16777619;
+	for (let i = 0; i < value.length; i += 1) {
+		const code = value.charCodeAt(i);
+		hashA ^= code;
+		hashA = Math.imul(hashA, 16777619);
+		hashB ^= code + i;
+		hashB = Math.imul(hashB, 2246822507);
+	}
+	return `m_${(hashA >>> 0).toString(16).padStart(8, "0")}${(hashB >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+//#endregion
+//#region src/orm/migrations/runtime.ts
+const DEFAULT_BATCH_SIZE = 128;
+function createMigrationHandlers(params) {
+	const { schema, migrations, getOrm, getChunkRef } = params;
+	const knownTables = new Set(Object.values(schema).map((tableConfig) => tableConfig.name));
+	const run = async (ctx, args = {}) => {
+		if (!migrations || migrations.migrations.length === 0) return {
+			status: "noop",
+			reason: "no_migrations_registered"
+		};
+		const direction = parseDirection(args.direction);
+		const dryRun = args.dryRun === true;
+		const allowDrift = args.allowDrift === true;
+		const restart = args.restart === true;
+		const batchSize = parseOptionalPositiveInteger(args.batchSize, "batchSize");
+		const steps = parseOptionalPositiveInteger(args.steps, "steps");
+		const to = parseOptionalString(args.to, "to");
+		const stateRows = await getAllStateRows(ctx.db);
+		const appliedState = toAppliedStateMap(stateRows);
+		const drift = detectMigrationDrift({
+			migrationSet: migrations,
+			appliedState
+		});
+		if (drift.length > 0 && !allowDrift) return {
+			status: "drift_blocked",
+			direction,
+			drift
+		};
+		const plan = buildMigrationPlan({
+			direction,
+			migrationSet: migrations,
+			appliedState,
+			steps,
+			to
+		});
+		if (plan.migrations.length === 0) return {
+			status: "noop",
+			direction,
+			drift,
+			plan: []
+		};
+		for (const migration of plan.migrations) {
+			const step = getStepForDirection(migration, direction);
+			if (!knownTables.has(step.table)) throw new Error(`Migration '${migration.id}' references unknown table '${step.table}'.`);
+		}
+		if (dryRun) return {
+			status: "dry_run",
+			direction,
+			drift,
+			plan: plan.migrations.map((migration) => migration.id)
+		};
+		const activeRun = await getActiveRun(ctx.db);
+		if (activeRun) return {
+			status: "running",
+			runId: activeRun.runId
+		};
+		const now = Date.now();
+		const runId = createRunId(now);
+		await ctx.db.insert(MIGRATION_RUN_TABLE, {
+			runId,
+			direction,
+			status: "running",
+			dryRun: false,
+			allowDrift,
+			migrationIds: plan.migrations.map((migration) => migration.id),
+			currentIndex: 0,
+			startedAt: now,
+			updatedAt: now,
+			cancelRequested: false
+		});
+		const stateById = new Map(stateRows.map((row) => [row.migrationId, row]));
+		for (const migration of plan.migrations) {
+			const writeMode = getStepForDirection(migration, direction).writeMode ?? "safe_bypass";
+			const existing = stateById.get(migration.id);
+			const resetProgress = restart || existing?.direction !== direction;
+			if (existing) await ctx.db.patch(existing._id, cleanUndefined({
+				checksum: migration.checksum,
+				status: "pending",
+				direction,
+				runId,
+				cursor: resetProgress ? null : existing.cursor ?? null,
+				processed: resetProgress ? 0 : existing.processed ?? 0,
+				startedAt: now,
+				updatedAt: now,
+				completedAt: null,
+				lastError: null,
+				writeMode
+			}));
+			else await ctx.db.insert(MIGRATION_STATE_TABLE, {
+				migrationId: migration.id,
+				checksum: migration.checksum,
+				applied: direction === "down",
+				status: "pending",
+				direction,
+				runId,
+				cursor: null,
+				processed: 0,
+				startedAt: now,
+				updatedAt: now,
+				completedAt: null,
+				lastError: null,
+				writeMode
+			});
+		}
+		if (ctx.scheduler) {
+			const chunkRef = getChunkRef();
+			if (chunkRef) {
+				const chunkArgs = { runId };
+				if (batchSize !== void 0) chunkArgs.batchSize = batchSize;
+				await ctx.scheduler.runAfter(0, chunkRef, chunkArgs);
+				return {
+					status: "running",
+					direction,
+					runId,
+					plan: plan.migrations.map((migration) => migration.id)
+				};
+			}
+		}
+		const inlineResult = await chunk(ctx, {
+			runId,
+			batchSize
+		});
+		return {
+			status: "running",
+			direction,
+			runId,
+			plan: plan.migrations.map((migration) => migration.id),
+			inlineResult
+		};
+	};
+	const chunk = async (ctx, args) => {
+		const runId = parseRequiredString(args.runId, "runId");
+		const batchSize = parseOptionalPositiveInteger(args.batchSize, "batchSize");
+		const runRow = await getRunById(ctx.db, runId);
+		if (!runRow) return {
+			status: "missing",
+			runId
+		};
+		if (runRow.status !== "running") return {
+			status: runRow.status,
+			runId
+		};
+		if (runRow.cancelRequested) {
+			await markRunCanceled(ctx.db, runRow);
+			return {
+				status: "canceled",
+				runId
+			};
+		}
+		const migrationId = runRow.migrationIds[runRow.currentIndex];
+		if (!migrationId) {
+			await markRunCompleted(ctx.db, runRow);
+			return {
+				status: "completed",
+				runId
+			};
+		}
+		const migration = migrations?.byId[migrationId];
+		if (!migration) {
+			await markRunFailed(ctx.db, runRow, `Migration '${migrationId}' is missing from registry.`);
+			return {
+				status: "failed",
+				runId
+			};
+		}
+		const direction = parseDirection(runRow.direction);
+		const step = getStepForDirection(migration, direction);
+		const resolvedBatchSize = batchSize ?? step.batchSize ?? DEFAULT_BATCH_SIZE;
+		const stateRow = await getOrCreateStateRow(ctx.db, migration, direction, step);
+		const cursor = stateRow.cursor ?? null;
+		try {
+			const page = await ctx.db.query(step.table).paginate({
+				cursor,
+				numItems: resolvedBatchSize
+			});
+			const docs = Array.isArray(page?.page) ? page.page : [];
+			const orm = getOrm(ctx);
+			const writeMode = step.writeMode ?? "safe_bypass";
+			let processedInBatch = 0;
+			for (const doc of docs) {
+				const migrationCtxBase = {
+					db: ctx.db,
+					migrationId,
+					runId,
+					direction,
+					dryRun: false,
+					writeMode
+				};
+				const result = await runWithWriteMode(orm, writeMode, (resolvedOrm) => step.migrateOne({
+					...migrationCtxBase,
+					orm: resolvedOrm
+				}, doc));
+				if (isPatchPayload(result) && hasDocId(doc)) await ctx.db.patch(doc._id, result);
+				processedInBatch += 1;
+			}
+			const now = Date.now();
+			const isDone = Boolean(page?.isDone);
+			const nextCursor = isDone ? null : page?.continueCursor ?? null;
+			const nextProcessed = (stateRow.processed ?? 0) + processedInBatch;
+			if (isDone) {
+				await ctx.db.patch(stateRow._id, cleanUndefined({
+					status: "completed",
+					applied: direction === "up",
+					cursor: null,
+					processed: nextProcessed,
+					completedAt: now,
+					updatedAt: now,
+					lastError: null,
+					runId,
+					direction,
+					writeMode
+				}));
+				const nextIndex = runRow.currentIndex + 1;
+				const done = nextIndex >= runRow.migrationIds.length;
+				await ctx.db.patch(runRow._id, cleanUndefined({
+					currentIndex: nextIndex,
+					status: done ? "completed" : "running",
+					updatedAt: now,
+					completedAt: done ? now : null,
+					lastError: null
+				}));
+				if (!done && ctx.scheduler) {
+					const chunkRef = getChunkRef();
+					if (chunkRef) await ctx.scheduler.runAfter(0, chunkRef, {
+						runId,
+						batchSize: resolvedBatchSize
+					});
+				}
+				return {
+					status: done ? "completed" : "running",
+					runId,
+					migrationId,
+					processedInBatch,
+					processed: nextProcessed,
+					currentIndex: nextIndex,
+					total: runRow.migrationIds.length
+				};
+			}
+			await ctx.db.patch(stateRow._id, cleanUndefined({
+				status: "running",
+				cursor: nextCursor,
+				processed: nextProcessed,
+				updatedAt: now,
+				runId,
+				direction,
+				writeMode
+			}));
+			await ctx.db.patch(runRow._id, cleanUndefined({
+				status: "running",
+				updatedAt: now
+			}));
+			if (ctx.scheduler) {
+				const chunkRef = getChunkRef();
+				if (chunkRef) await ctx.scheduler.runAfter(0, chunkRef, {
+					runId,
+					batchSize: resolvedBatchSize
+				});
+			}
+			return {
+				status: "running",
+				runId,
+				migrationId,
+				processedInBatch,
+				processed: nextProcessed,
+				cursor: nextCursor
+			};
+		} catch (error) {
+			const message = error.message || String(error);
+			await ctx.db.patch(stateRow._id, cleanUndefined({
+				status: "failed",
+				lastError: message,
+				updatedAt: Date.now()
+			}));
+			await markRunFailed(ctx.db, runRow, message);
+			return {
+				status: "failed",
+				runId,
+				migrationId,
+				error: message
+			};
+		}
+	};
+	const status = async (ctx, args = {}) => {
+		if (!migrations) return {
+			status: "noop",
+			reason: "no_migrations_registered"
+		};
+		const limit = parseOptionalPositiveInteger(args.limit, "limit") ?? 25;
+		const runId = parseOptionalString(args.runId, "runId");
+		const stateRows = await getAllStateRows(ctx.db);
+		const sortedRuns = [...await getAllRunRows(ctx.db)].sort((left, right) => right.startedAt - left.startedAt);
+		const selectedRuns = runId ? sortedRuns.filter((entry) => entry.runId === runId).slice(0, 1) : sortedRuns.slice(0, limit);
+		const activeRun = sortedRuns.find((entry) => entry.status === "running") ?? null;
+		const appliedState = toAppliedStateMap(stateRows);
+		const drift = detectMigrationDrift({
+			migrationSet: migrations,
+			appliedState
+		});
+		const pendingUp = buildMigrationPlan({
+			direction: "up",
+			migrationSet: migrations,
+			appliedState
+		});
+		return {
+			status: activeRun ? "running" : "idle",
+			activeRun,
+			runs: selectedRuns,
+			migrations: stateRows.map((row) => ({
+				migrationId: row.migrationId,
+				checksum: row.checksum,
+				applied: row.applied,
+				status: row.status,
+				direction: row.direction ?? null,
+				runId: row.runId ?? null,
+				cursor: row.cursor ?? null,
+				processed: row.processed,
+				updatedAt: row.updatedAt,
+				startedAt: row.startedAt ?? null,
+				completedAt: row.completedAt ?? null,
+				lastError: row.lastError ?? null,
+				writeMode: row.writeMode
+			})),
+			pending: pendingUp.migrations.map((migration) => migration.id),
+			drift
+		};
+	};
+	const cancel = async (ctx, args = {}) => {
+		if (!migrations) return {
+			status: "noop",
+			reason: "no_migrations_registered"
+		};
+		const runId = parseOptionalString(args.runId, "runId");
+		const runRow = runId ? await getRunById(ctx.db, runId) : await getActiveRun(ctx.db);
+		if (!runRow) return {
+			status: "noop",
+			reason: "no_active_run"
+		};
+		if (runRow.status !== "running") return {
+			status: "noop",
+			reason: "run_not_running",
+			runId: runRow.runId,
+			runStatus: runRow.status
+		};
+		const now = Date.now();
+		await ctx.db.patch(runRow._id, cleanUndefined({
+			cancelRequested: true,
+			updatedAt: now
+		}));
+		if (!(ctx.scheduler ? getChunkRef() : void 0)) {
+			await markRunCanceled(ctx.db, runRow);
+			return {
+				status: "canceled",
+				runId: runRow.runId
+			};
+		}
+		return {
+			status: "cancel_requested",
+			runId: runRow.runId
+		};
+	};
+	return {
+		run,
+		chunk,
+		status,
+		cancel
+	};
+}
+function getStepForDirection(migration, direction) {
+	if (direction === "up") return migration.up;
+	if (!migration.down) throw new Error(`Migration '${migration.id}' is missing down migration.`);
+	return migration.down;
+}
+function createRunId(now) {
+	return `mr_${now}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function parseDirection(value) {
+	if (value === void 0 || value === null) return "up";
+	if (value === "up" || value === "down") return value;
+	throw new Error("Migration direction must be either 'up' or 'down'.");
+}
+function parseOptionalPositiveInteger(value, fieldName) {
+	if (value === void 0 || value === null) return;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throw new Error(`Migration ${fieldName} must be a positive integer.`);
+	return value;
+}
+function parseOptionalString(value, fieldName) {
+	if (value === void 0 || value === null) return;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`Migration ${fieldName} must be a non-empty string.`);
+	return value;
+}
+function parseRequiredString(value, fieldName) {
+	const parsed = parseOptionalString(value, fieldName);
+	if (!parsed) throw new Error(`Migration ${fieldName} is required.`);
+	return parsed;
+}
+function toAppliedStateMap(stateRows) {
+	const entries = {};
+	for (const row of stateRows) entries[row.migrationId] = {
+		applied: row.applied,
+		checksum: row.checksum,
+		cursor: row.cursor ?? null,
+		processed: row.processed
+	};
+	return entries;
+}
+async function getAllStateRows(db) {
+	return await db.query(MIGRATION_STATE_TABLE).collect();
+}
+async function getAllRunRows(db) {
+	return await db.query(MIGRATION_RUN_TABLE).collect();
+}
+async function getRunById(db, runId) {
+	return await db.query(MIGRATION_RUN_TABLE).withIndex("by_run_id", (query) => query.eq("runId", runId)).first() ?? null;
+}
+async function getActiveRun(db) {
+	return await db.query(MIGRATION_RUN_TABLE).withIndex("by_status", (query) => query.eq("status", "running")).first() ?? null;
+}
+async function getOrCreateStateRow(db, migration, direction, step) {
+	const existing = await db.query(MIGRATION_STATE_TABLE).withIndex("by_migration_id", (query) => query.eq("migrationId", migration.id)).first();
+	if (existing) return existing;
+	const now = Date.now();
+	const stateId = await db.insert(MIGRATION_STATE_TABLE, {
+		migrationId: migration.id,
+		checksum: migration.checksum,
+		applied: direction === "down",
+		status: "pending",
+		direction,
+		runId: null,
+		cursor: null,
+		processed: 0,
+		startedAt: now,
+		updatedAt: now,
+		completedAt: null,
+		lastError: null,
+		writeMode: step.writeMode ?? "safe_bypass"
+	});
+	const created = await db.get(stateId);
+	if (!created) throw new Error(`Failed to create migration state row for '${migration.id}'.`);
+	return created;
+}
+async function markRunCompleted(db, runRow) {
+	const now = Date.now();
+	await db.patch(runRow._id, cleanUndefined({
+		status: "completed",
+		updatedAt: now,
+		completedAt: now,
+		cancelRequested: false,
+		lastError: null
+	}));
+}
+async function markRunCanceled(db, runRow) {
+	const now = Date.now();
+	await db.patch(runRow._id, cleanUndefined({
+		status: "canceled",
+		updatedAt: now,
+		completedAt: now,
+		cancelRequested: true
+	}));
+	for (const stateRow of await getAllStateRows(db)) if (stateRow.runId === runRow.runId && (stateRow.status === "running" || stateRow.status === "pending")) await db.patch(stateRow._id, cleanUndefined({
+		status: "canceled",
+		updatedAt: now
+	}));
+}
+async function markRunFailed(db, runRow, message) {
+	const now = Date.now();
+	await db.patch(runRow._id, cleanUndefined({
+		status: "failed",
+		updatedAt: now,
+		completedAt: now,
+		lastError: message
+	}));
+}
+async function runWithWriteMode(orm, writeMode, callback) {
+	if (writeMode === "normal") return await callback(orm);
+	return await orm.skipRules.withoutTriggers(async (noTriggersOrm) => {
+		return await callback(noTriggersOrm);
+	});
+}
+function isPatchPayload(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function hasDocId(doc) {
+	return "_id" in doc && doc._id !== void 0 && doc._id !== null;
+}
+function cleanUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, candidate]) => candidate !== void 0));
+}
+
 //#endregion
 //#region src/orm/scheduled-delete.ts
 function scheduledDeleteFactory(schema, edgeMetadata, scheduledMutationBatch) {
@@ -9093,6 +9560,10 @@ function scheduledMutationBatchFactory(schema, edgeMetadata, scheduledMutationBa
 
 //#endregion
 //#region src/orm/create-orm.ts
+function getResetTableNames(schema) {
+	const pluginTables = schema[OrmSchemaPluginTables];
+	return [...new Set([...Object.values(schema).map((tableConfig) => tableConfig.name), ...pluginTables ?? []])];
+}
 function isOrmCtx(source) {
 	return !!source && typeof source === "object" && "db" in source;
 }
@@ -9143,13 +9614,25 @@ function createOrm(config) {
 		with: withContext,
 		api: () => {
 			let aggregateBackfillChunkRef = config.ormFunctions.aggregateBackfillChunk;
+			let migrationRunChunkRef = config.ormFunctions.migrationRunChunk;
 			let resetChunkRef = config.ormFunctions.resetChunk;
 			const countBackfillHandlers = createCountBackfillHandlers(config.schema, () => aggregateBackfillChunkRef);
+			const migrationHandlers = createMigrationHandlers({
+				schema: config.schema,
+				migrations: config.migrations,
+				getOrm: (ctx) => db(ctx),
+				getChunkRef: () => migrationRunChunkRef
+			});
 			const aggregateBackfillChunk = mutationBuilder({
 				args: v.any(),
 				handler: countBackfillHandlers.chunk
 			});
 			if (!aggregateBackfillChunkRef) aggregateBackfillChunkRef = aggregateBackfillChunk;
+			const migrationRunChunk = mutationBuilder({
+				args: v.any(),
+				handler: migrationHandlers.chunk
+			});
+			if (!migrationRunChunkRef) migrationRunChunkRef = migrationRunChunk;
 			const resetChunk = mutationBuilder({
 				args: v.object({
 					tableName: v.string(),
@@ -9193,11 +9676,24 @@ function createOrm(config) {
 					args: v.any(),
 					handler: countBackfillHandlers.status
 				}),
+				migrationRun: mutationBuilder({
+					args: v.any(),
+					handler: migrationHandlers.run
+				}),
+				migrationRunChunk,
+				migrationStatus: mutationBuilder({
+					args: v.any(),
+					handler: migrationHandlers.status
+				}),
+				migrationCancel: mutationBuilder({
+					args: v.any(),
+					handler: migrationHandlers.cancel
+				}),
 				resetChunk,
 				reset: internalActionGeneric({
 					args: v.any(),
 					handler: async (ctx) => {
-						const tableNames = [...new Set(Object.values(config.schema).map((tableConfig) => tableConfig.name))];
+						const tableNames = getResetTableNames(config.schema);
 						let deleted = 0;
 						for (const tableName of tableNames) {
 							let cursor = null;
@@ -9440,6 +9936,7 @@ function defineRelations(schema, relations) {
 	const strict = schemaOptions?.strict ?? true;
 	const defaults = schemaOptions?.defaults;
 	const schemaDefinition = schema[OrmSchemaDefinition];
+	const pluginTableNames = schema[OrmSchemaPluginTables];
 	const tablesConfig = buildRelations(tables, relations ? relations(createRelationsHelper(tables)) : {}, strict, defaults);
 	Object.defineProperty(tablesConfig, OrmSchemaOptions, {
 		value: {
@@ -9452,6 +9949,10 @@ function defineRelations(schema, relations) {
 		value: schemaDefinition,
 		enumerable: false
 	});
+	if (pluginTableNames) Object.defineProperty(tablesConfig, OrmSchemaPluginTables, {
+		value: pluginTableNames,
+		enumerable: false
+	});
 	return tablesConfig;
 }
 function defineRelationsPart(schema, relations) {
@@ -9460,6 +9961,7 @@ function defineRelationsPart(schema, relations) {
 	const strict = schemaOptions?.strict ?? true;
 	const defaults = schemaOptions?.defaults;
 	const schemaDefinition = schema[OrmSchemaDefinition];
+	const pluginTableNames = schema[OrmSchemaPluginTables];
 	const tablesConfig = buildRelationsParts(tables, relations ? relations(createRelationsHelper(tables)) : Object.fromEntries(Object.keys(tables).map((k) => [k, {}])), strict, defaults);
 	Object.defineProperty(tablesConfig, OrmSchemaOptions, {
 		value: {
@@ -9472,6 +9974,10 @@ function defineRelationsPart(schema, relations) {
 		value: schemaDefinition,
 		enumerable: false
 	});
+	if (pluginTableNames) Object.defineProperty(tablesConfig, OrmSchemaPluginTables, {
+		value: pluginTableNames,
+		enumerable: false
+	});
 	return tablesConfig;
 }
 function processRelations(tablesConfig, tables) {
@@ -9559,6 +10065,7 @@ const DEFAULTS_NUMERIC_FIELDS = [
 	"mutationScheduleCallCap"
 ];
 const MUTATION_EXECUTION_MODES = ["sync", "async"];
+const BUILTIN_SCHEMA_PLUGINS = [aggregatePlugin(), migrationPlugin()];
 const normalizeDefaults = (defaults) => {
 	if (!defaults) return;
 	const normalized = {};
@@ -9579,6 +10086,27 @@ const normalizeDefaults = (defaults) => {
 	}
 	return normalized;
 };
+function resolveSchemaPlugins(plugins) {
+	const resolved = [...BUILTIN_SCHEMA_PLUGINS, ...plugins ?? []];
+	const seen = /* @__PURE__ */ new Set();
+	for (const plugin of resolved) {
+		if (seen.has(plugin.key)) throw new Error(`defineSchema received duplicate plugin '${plugin.key}'. Remove duplicate plugin registrations.`);
+		seen.add(plugin.key);
+	}
+	return resolved;
+}
+function applySchemaPlugins(schema, plugins) {
+	let current = schema;
+	const pluginTableNames = [];
+	for (const plugin of plugins) {
+		current = plugin.inject(current);
+		for (const tableName of plugin.tableNames) if (!pluginTableNames.includes(tableName)) pluginTableNames.push(tableName);
+	}
+	return {
+		schema: current,
+		pluginTableNames
+	};
+}
 /**
 * Better Convex schema definition
 *
@@ -9589,7 +10117,8 @@ const normalizeDefaults = (defaults) => {
 function defineSchema(schema, options) {
 	const strict = options?.strict ?? true;
 	const defaults = normalizeDefaults(options?.defaults);
-	const schemaWithInternals = injectAggregateStorageTables(schema);
+	const { schema: schemaWithPlugins, pluginTableNames } = applySchemaPlugins(schema, resolveSchemaPlugins(options?.plugins));
+	const frozenPluginTableNames = Object.freeze([...pluginTableNames]);
 	Object.defineProperty(schema, OrmSchemaOptions, {
 		value: {
 			strict,
@@ -9597,15 +10126,23 @@ function defineSchema(schema, options) {
 		},
 		enumerable: false
 	});
-	Object.defineProperty(schemaWithInternals, OrmSchemaOptions, {
+	Object.defineProperty(schemaWithPlugins, OrmSchemaOptions, {
 		value: {
 			strict,
 			defaults
 		},
 		enumerable: false
 	});
-	const { strict: _strict, defaults: _defaults, ...convexOptions } = options ?? {};
-	const convexSchema = defineSchema$1(schemaWithInternals, convexOptions);
+	Object.defineProperty(schema, OrmSchemaPluginTables, {
+		value: frozenPluginTableNames,
+		enumerable: false
+	});
+	Object.defineProperty(schemaWithPlugins, OrmSchemaPluginTables, {
+		value: frozenPluginTableNames,
+		enumerable: false
+	});
+	const { strict: _strict, defaults: _defaults, plugins: _plugins, ...convexOptions } = options ?? {};
+	const convexSchema = defineSchema$1(schemaWithPlugins, convexOptions);
 	Object.defineProperty(convexSchema, OrmSchemaOptions, {
 		value: {
 			strict,
@@ -9613,11 +10150,15 @@ function defineSchema(schema, options) {
 		},
 		enumerable: false
 	});
+	Object.defineProperty(convexSchema, OrmSchemaPluginTables, {
+		value: frozenPluginTableNames,
+		enumerable: false
+	});
 	Object.defineProperty(schema, OrmSchemaDefinition, {
 		value: convexSchema,
 		enumerable: false
 	});
-	Object.defineProperty(schemaWithInternals, OrmSchemaDefinition, {
+	Object.defineProperty(schemaWithPlugins, OrmSchemaDefinition, {
 		value: convexSchema,
 		enumerable: false
 	});
@@ -9629,4 +10170,4 @@ function defineSchema(schema, options) {
 }
 
 //#endregion
-export { Brand, Columns, OrmNotFoundError, RlsPolicy, RlsRole, TableName, aggregateIndex, and, asc, between, bigint, boolean, bytes, check, contains, convexTable, createOrm, custom, date, defineRelations, defineRelationsPart, defineSchema, defineTriggers, deletion, desc, endsWith, eq, extractRelationsConfig, fieldRef, foreignKey, getByIdWithOrmQueryFallback, getTableColumns, getTableConfig, gt, gte, id, ilike, inArray, index, integer, isFieldReference, isNotNull, isNull, json, like, lt, lte, ne, not, notBetween, notInArray, or, rankIndex, rlsPolicy, rlsRole, scheduledDeleteFactory, scheduledMutationBatchFactory, searchIndex, startsWith, text, textEnum, timestamp, unique, uniqueIndex, unsetToken, vector, vectorIndex };
+export { Brand, Columns, OrmNotFoundError, OrmSchemaPluginTables, RlsPolicy, RlsRole, TableName, aggregateIndex, and, arrayOf, asc, between, bigint, boolean, buildMigrationPlan, bytes, check, contains, convexTable, createOrm, custom, date, defineMigration, defineMigrationSet, defineRelations, defineRelationsPart, defineSchema, defineTriggers, deletion, deprecated, desc, detectMigrationDrift, endsWith, eq, extractRelationsConfig, fieldRef, foreignKey, getByIdWithOrmQueryFallback, getTableColumns, getTableConfig, gt, gte, id, ilike, inArray, index, integer, isFieldReference, isNotNull, isNull, json, like, lt, lte, ne, not, notBetween, notInArray, objectOf, or, pretend, pretendRequired, rankIndex, rlsPolicy, rlsRole, scheduledDeleteFactory, scheduledMutationBatchFactory, searchIndex, startsWith, text, textEnum, timestamp, unique, uniqueIndex, unsetToken, vector, vectorIndex };