kitcn 0.26.1 → 0.26.3

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # kitcn
 
+## 0.26.3
+
+### Patch Changes
+
+- [#394](https://github.com/udecode/kitcn/pull/394) [`1317349`](https://github.com/udecode/kitcn/commit/13173495fa8db3d8a0568642981c1cdef4dcdf2b) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Features
+
+  - Support a per-source `index: { name, range }` on `select().union([...])`, so each source walks its own index range instead of re-walking one shared range and filtering the misses in JS.
+
+  ```ts
+  const page = await db.query.messages
+    .select()
+    .union([
+      {
+        index: {
+          name: "by_from_to",
+          range: (q) => q.eq("from", me).eq("to", them),
+        },
+      },
+      {
+        index: {
+          name: "by_from_to",
+          range: (q) => q.eq("from", them).eq("to", me),
+        },
+      },
+    ])
+    .interleaveBy(["createdAt", "id"])
+    .paginate({ cursor: null, limit: 20 });
+  ```
+
+  - Support union sources anchored on different indexes, as long as each source pins its leading fields with `eq` and ends up ordered by the `interleaveBy` fields.
+
+## 0.26.2
+
+### Patch Changes
+
+- [#393](https://github.com/udecode/kitcn/pull/393) [`5ebba20`](https://github.com/udecode/kitcn/commit/5ebba205900489ab204901f5487788a60b9d0dd4) Thanks [@MikeyZhang75](https://github.com/MikeyZhang75)! - ## Patches
+
+  - Speed up `kitcn codegen`. Each Convex module is now read once per run instead
+    of up to four times, and the functions directory is listed once instead of
+    twice. On an 82-module app that is 57 fewer file reads and 10 fewer directory
+    listings per run, with identical generated output.
+
 ## 0.26.1
 
 ### Patch Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
-import { Bn as ConvexTextBuilderInitial, Xt as ConvexTableWithColumns } from "../capabilities-DtDfpdcH.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-3fKontPx.js";
+import { Bn as ConvexTextBuilderInitial, Xt as ConvexTableWithColumns } from "../capabilities-QNGgWHQd.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-DfFcNKtn.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

package/dist/{capabilities-DtDfpdcH.d.ts → capabilities-QNGgWHQd.d.ts}

@@ -1430,6 +1430,16 @@ type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y
 type Merge<A, B> = { [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never };
 type IndexKey = (Value | undefined)[];
 type FindManyUnionSource<TTableConfig extends TableRelationalConfig = TableRelationalConfig> = {
+  /**
+   * Index anchor for this source alone. Overrides the chain-level
+   * `.withIndex(...)`, so each source can walk its own range instead of
+   * re-walking one shared range and discarding the misses in JS.
+   *
+   * Sources may pin different indexes: `interleaveBy` re-orders every source by
+   * the same trailing fields before merging, so what has to match across
+   * sources is that ordering suffix, not the index name.
+   */
+  index?: PredicateWhereIndexConfig<TTableConfig>;
   where?: RelationsFilter<TTableConfig, any> | WhereCallback<TTableConfig>;
 };
 type PipelineRelationName<TTableConfig extends TableRelationalConfig> = Extract<keyof TTableConfig['relations'], string>;

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as Columns, D as TableName, E as RlsPolicies, O as createSystemFields, S as getRankIndexes, T as OrmSchemaExtensions, _ as loadEsbuild, a as generateMeta, b as getAggregateIndexes, c as resolveSchemaDefaultExport, f as createProjectJiti, g as loadDotenv, h as loadClackPrompts, i as resolveConfiguredBackend, l as schemaDeclaresAggregateIndexes, m as loadBabelParser, n as withLocalCodegenEnv, o as getConvexConfig, p as CRPC_BUILDER_STUB_SOURCE, r as loadCliConfig, s as collectSchemaTables, t as getLocalBackendEnvVars, u as logger, v as highlighter, w as EnableRLS, x as getIndexes, y as isColorEnabled } from "./local-env-9Qtfn3wR.mjs";
+import { C as Columns, D as TableName, E as RlsPolicies, O as createSystemFields, S as getRankIndexes, T as OrmSchemaExtensions, _ as loadEsbuild, a as generateMeta, b as getAggregateIndexes, c as resolveSchemaDefaultExport, f as createProjectJiti, g as loadDotenv, h as loadClackPrompts, i as resolveConfiguredBackend, l as schemaDeclaresAggregateIndexes, m as loadBabelParser, n as withLocalCodegenEnv, o as getConvexConfig, p as CRPC_BUILDER_STUB_SOURCE, r as loadCliConfig, s as collectSchemaTables, t as getLocalBackendEnvVars, u as logger, v as highlighter, w as EnableRLS, x as getIndexes, y as isColorEnabled } from "./local-env-Z8jj6ecD.mjs";
 import { createRequire } from "node:module";
 import fs, { existsSync, readFileSync } from "node:fs";
 import path, { basename, delimiter, dirname, extname, isAbsolute, join, posix, relative, resolve } from "node:path";

package/dist/{local-env-9Qtfn3wR.mjs → local-env-Z8jj6ecD.mjs}

@@ -2563,6 +2563,60 @@ function hasPotentialCodegenExports(source, filePath) {
 	return false;
 }
 
+//#endregion
+//#region src/cli/utils/codegen-file-cache.ts
+const MISSING_FILE_ERROR_CODES = new Set([
+	"ENOENT",
+	"ENOTDIR",
+	"EISDIR"
+]);
+function isMissingFileError(error) {
+	const code = error?.code;
+	return code !== void 0 && MISSING_FILE_ERROR_CODES.has(code);
+}
+function createCodegenFileCache() {
+	const contentsByPath = /* @__PURE__ */ new Map();
+	const read = (filePath) => {
+		const key = path.resolve(filePath);
+		const cached = contentsByPath.get(key);
+		if (cached !== void 0) return cached;
+		let content;
+		try {
+			content = fs.readFileSync(key, "utf8");
+		} catch (error) {
+			if (!isMissingFileError(error)) throw error;
+			content = null;
+		}
+		contentsByPath.set(key, content);
+		return content;
+	};
+	const write = (filePath, content) => {
+		fs.writeFileSync(filePath, content);
+		contentsByPath.set(path.resolve(filePath), content);
+	};
+	return {
+		read,
+		write,
+		writeIfChanged: (filePath, content) => {
+			if (read(filePath) === content) return false;
+			write(filePath, content);
+			return true;
+		},
+		remove: (filePath) => {
+			fs.rmSync(filePath, { force: true });
+			contentsByPath.set(path.resolve(filePath), null);
+		},
+		removeDirectory: (dirPath) => {
+			fs.rmSync(dirPath, {
+				force: true,
+				recursive: true
+			});
+			const prefix = `${path.resolve(dirPath)}${path.sep}`;
+			for (const key of contentsByPath.keys()) if (key.startsWith(prefix)) contentsByPath.set(key, null);
+		}
+	};
+}
+
 //#endregion
 //#region src/cli/utils/logger.ts
 const joinArgs = (args) => args.map(String).join(" ");
@@ -2827,7 +2881,8 @@ function findProcedureCallIndex(params) {
 }
 function buildProcedureNameLookupEntries(params) {
 	if (params.procedures.length === 0) return [];
-	const source = fs.readFileSync(params.filePath, "utf8");
+	const source = params.fileCache.read(params.filePath);
+	if (source === null) return [];
 	return params.procedures.flatMap((procedure) => {
 		const callIndex = findProcedureCallIndex({
 			exportName: procedure.exportName,
@@ -2872,9 +2927,9 @@ function extractObjectLiteral(source, startIndex) {
 	}
 	return null;
 }
-function readLegacyProcedureNameLookup(serverOutputFile) {
-	if (!fs.existsSync(serverOutputFile)) return;
-	const source = fs.readFileSync(serverOutputFile, "utf8");
+function readLegacyProcedureNameLookup(fileCache, serverOutputFile) {
+	const source = fileCache.read(serverOutputFile);
+	if (source === null) return;
 	const startMatch = LEGACY_PROCEDURE_LOOKUP_START_RE.exec(source);
 	if (!startMatch || startMatch.index === void 0) return;
 	const literal = extractObjectLiteral(source, startMatch.index + startMatch[0].lastIndexOf("{"));
@@ -3019,11 +3074,11 @@ function getRuntimeApiTypesImportPath(outputFile, functionsDir) {
 	const runtimeApiFile = path.join(functionsDir, "_generated", "api");
 	return ensureRelativeImportPath(normalizeImportPath(path.relative(path.dirname(outputFile), runtimeApiFile)));
 }
-function moduleUsesOwnGeneratedRuntime(functionsDir, moduleName) {
+function moduleUsesOwnGeneratedRuntime(fileCache, functionsDir, moduleName) {
 	if (moduleName === "generated/server") return true;
 	const moduleFilePath = path.join(functionsDir, `${moduleName}.ts`);
-	if (!fs.existsSync(moduleFilePath)) return false;
-	const source = fs.readFileSync(moduleFilePath, "utf8");
+	const source = fileCache.read(moduleFilePath);
+	if (source === null) return false;
 	const escapedRuntimeImportPath = escapeRegex(ensureRelativeImportPath(normalizeImportPath(path.relative(path.dirname(moduleFilePath), path.join(functionsDir, "generated", `${moduleName}.runtime`)))));
 	return [new RegExp(`from\\s+['"]${escapedRuntimeImportPath}(?:\\.[jt]s)?['"]`), new RegExp(`require\\(\\s*['"]${escapedRuntimeImportPath}(?:\\.[jt]s)?['"]\\s*\\)`)].some((pattern) => pattern.test(source));
 }
@@ -3159,14 +3214,7 @@ function emitGeneratedMigrationsPlaceholderFile() {
 export { defineMigration } from 'kitcn/orm';
 `;
 }
-function writeFileIfChanged(filePath, content) {
-	if (fs.existsSync(filePath)) {
-		if (fs.readFileSync(filePath, "utf8") === content) return false;
-	}
-	fs.writeFileSync(filePath, content);
-	return true;
-}
-function ensureGeneratedSupportPlaceholders(functionsDir, options) {
+function ensureGeneratedSupportPlaceholders(fileCache, functionsDir, options) {
 	const createdPlaceholderFiles = [];
 	const replacedFiles = [];
 	const serverOutputFile = getGeneratedServerOutputFile(functionsDir);
@@ -3176,23 +3224,21 @@ function ensureGeneratedSupportPlaceholders(functionsDir, options) {
 	const generatedDir = path.dirname(serverOutputFile);
 	fs.mkdirSync(generatedDir, { recursive: true });
 	const includeAuth = options?.includeAuth ?? true;
-	if (!fs.existsSync(serverOutputFile)) {
-		writeFileIfChanged(serverOutputFile, emitGeneratedServerPlaceholderFile(functionsDir));
+	const existingServerContent = fileCache.read(serverOutputFile);
+	if (existingServerContent === null) {
+		fileCache.write(serverOutputFile, emitGeneratedServerPlaceholderFile(functionsDir));
 		createdPlaceholderFiles.push(serverOutputFile);
-	} else if (options?.replaceServer) {
-		const content = fs.readFileSync(serverOutputFile, "utf8");
-		if (writeFileIfChanged(serverOutputFile, emitGeneratedServerPlaceholderFile(functionsDir))) replacedFiles.push({
-			content,
-			filePath: serverOutputFile
-		});
-	}
-	if (!fs.existsSync(procedureNamesOutputFile)) writeFileIfChanged(procedureNamesOutputFile, emitGeneratedProcedureNamesFile(options?.procedureNameLookup ?? {}));
-	if (includeAuth && !fs.existsSync(authOutputFile)) {
-		writeFileIfChanged(authOutputFile, emitGeneratedAuthPlaceholderFile());
+	} else if (options?.replaceServer && fileCache.writeIfChanged(serverOutputFile, emitGeneratedServerPlaceholderFile(functionsDir))) replacedFiles.push({
+		content: existingServerContent,
+		filePath: serverOutputFile
+	});
+	if (fileCache.read(procedureNamesOutputFile) === null) fileCache.write(procedureNamesOutputFile, emitGeneratedProcedureNamesFile(options?.procedureNameLookup ?? {}));
+	if (includeAuth && fileCache.read(authOutputFile) === null) {
+		fileCache.write(authOutputFile, emitGeneratedAuthPlaceholderFile());
 		createdPlaceholderFiles.push(authOutputFile);
 	}
-	if (!fs.existsSync(migrationsHelperOutputFile)) {
-		writeFileIfChanged(migrationsHelperOutputFile, emitGeneratedMigrationsPlaceholderFile());
+	if (fileCache.read(migrationsHelperOutputFile) === null) {
+		fileCache.write(migrationsHelperOutputFile, emitGeneratedMigrationsPlaceholderFile());
 		createdPlaceholderFiles.push(migrationsHelperOutputFile);
 	}
 	return {
@@ -3227,14 +3273,14 @@ export function ${handlerExportName}(_ctx: unknown) {
 }
 `;
 }
-function ensureGeneratedRuntimePlaceholders(functionsDir, moduleNames, runtimeExportNames) {
+function ensureGeneratedRuntimePlaceholders(fileCache, functionsDir, moduleNames, runtimeExportNames) {
 	const createdPlaceholderFiles = [];
 	for (const moduleName of moduleNames) {
 		const runtimeOutputFile = getGeneratedRuntimeOutputFile(functionsDir, moduleName);
-		if (fs.existsSync(runtimeOutputFile)) continue;
+		if (fileCache.read(runtimeOutputFile) !== null) continue;
 		const exportNames = runtimeExportNames.get(moduleName) ?? getModuleRuntimeExportNames(moduleName);
 		fs.mkdirSync(path.dirname(runtimeOutputFile), { recursive: true });
-		writeFileIfChanged(runtimeOutputFile, emitGeneratedRuntimePlaceholderFile(exportNames));
+		fileCache.write(runtimeOutputFile, emitGeneratedRuntimePlaceholderFile(exportNames));
 		createdPlaceholderFiles.push(runtimeOutputFile);
 	}
 	return createdPlaceholderFiles;
@@ -3283,11 +3329,8 @@ function resolveHasAggregateIndexes(schemaValue, schemaPath, debug) {
 		return true;
 	}
 }
-function cleanupGeneratedPluginArtifacts(functionsDir) {
-	fs.rmSync(path.join(functionsDir, GENERATED_DIR, "plugins"), {
-		recursive: true,
-		force: true
-	});
+function cleanupGeneratedPluginArtifacts(fileCache, functionsDir) {
+	fileCache.removeDirectory(path.join(functionsDir, GENERATED_DIR, "plugins"));
 }
 /**
 * Every input here is known before codegen evaluates any project module, so
@@ -3605,9 +3648,9 @@ function renderRuntimeApiTypesImport(entries, importPath) {
 	if (specifiers.length === 1) return `import type { ${specifiers[0]} } from '${importPath}';\n`;
 	return `import type {\n${specifiers.map((specifier) => `  ${specifier},\n`).join("")}} from '${importPath}';\n`;
 }
-function emitGeneratedModuleRuntimeFile(outputFile, functionsDir, moduleName, procedureEntries, runtimeExportNames) {
+function emitGeneratedModuleRuntimeFile(fileCache, outputFile, functionsDir, moduleName, procedureEntries, runtimeExportNames) {
 	const { callerExportName, handlerExportName } = runtimeExportNames?.get(moduleName) ?? getModuleRuntimeExportNames(moduleName);
-	const useGeneratedApiTypes = moduleUsesOwnGeneratedRuntime(functionsDir, moduleName);
+	const useGeneratedApiTypes = moduleUsesOwnGeneratedRuntime(fileCache, functionsDir, moduleName);
 	const runtimeApiTypesImportPath = useGeneratedApiTypes ? getRuntimeApiTypesImportPath(outputFile, functionsDir) : null;
 	const generatedServerImportPath = getGeneratedServerImportPath(outputFile, functionsDir);
 	const { callerEntries, handlerEntries } = partitionRuntimeEntriesForEmission(procedureEntries);
@@ -3696,9 +3739,9 @@ export function ${callerExportName}<TCtx extends ProcedureCallerContext>(
 ${handlerExport}
 `;
 }
-function hasNamedExport(filePath, exportName) {
-	if (!fs.existsSync(filePath)) return false;
-	const source = fs.readFileSync(filePath, "utf-8");
+function hasNamedExport(fileCache, filePath, exportName) {
+	const source = fileCache.read(filePath);
+	if (source === null) return false;
 	if (new RegExp(`\\bexport\\s+(?:const|let|var|function|class|type|interface)\\s+${exportName}\\b`).test(source)) return true;
 	for (const match of source.matchAll(/\bexport\s*{([^}]*)}/g)) {
 		const exportList = match[1] ?? "";
@@ -3706,10 +3749,9 @@ function hasNamedExport(filePath, exportName) {
 	}
 	return false;
 }
-function hasDefaultExport(filePath) {
-	if (!fs.existsSync(filePath)) return false;
-	const source = fs.readFileSync(filePath, "utf-8");
-	return DEFAULT_EXPORT_RE.test(source);
+function hasDefaultExport(fileCache, filePath) {
+	const source = fileCache.read(filePath);
+	return source !== null && DEFAULT_EXPORT_RE.test(source);
 }
 function createApiTree(meta) {
 	const root = {
@@ -3865,8 +3907,9 @@ function isCRPCHttpRouter(value) {
 /**
 * Import a module using jiti and extract cRPC metadata from exports.
 */
-async function parseModuleRuntime(filePath, jitiInstance, serverShimSpecifier) {
-	const source = fs.readFileSync(filePath, "utf8");
+async function parseModuleRuntime(fileCache, filePath, jitiInstance, serverShimSpecifier) {
+	const source = fileCache.read(filePath);
+	if (source === null) throw new Error(`kitcn codegen could not read ${filePath}`);
 	const rewrittenSource = source.replaceAll(/from\s+(['"])kitcn\/server\1/g, `from ${JSON.stringify(serverShimSpecifier)}`);
 	const result = {};
 	const httpRoutes = {};
@@ -3951,61 +3994,62 @@ async function generateMeta(sharedDir, options) {
 	};
 	const runtimeFilesPreservedFromParseFailures = /* @__PURE__ */ new Set();
 	let totalFunctions = 0;
+	const fileCache = createCodegenFileCache();
 	const authFilePath = path.join(functionsDir, "auth.ts");
-	const hasAuthFile = fs.existsSync(authFilePath);
-	const hasAuthDefaultExport = hasDefaultExport(authFilePath);
+	const hasAuthFile = fileCache.read(authFilePath) !== null;
+	const hasAuthDefaultExport = hasDefaultExport(fileCache, authFilePath);
 	const authContract = {
 		hasAuthFile,
 		hasAuthDefaultExport
 	};
 	let sharedJitiInstance;
 	const getSharedJitiInstance = () => sharedJitiInstance ??= createProjectJiti();
-	const schemaRuntimeModules = listFilesRecursive(functionsDir).filter((file) => file.endsWith(".ts") && isValidConvexFile(file)).map((file) => file.replace(TS_EXTENSION_RE, ""));
-	const schemaRuntimePlaceholders = ensureGeneratedRuntimePlaceholders(functionsDir, schemaRuntimeModules, resolveModuleRuntimeExportNames(schemaRuntimeModules, normalizedTrimSegments));
+	const convexModuleFiles = listFilesRecursive(functionsDir).filter((file) => file.endsWith(".ts") && isValidConvexFile(file));
+	const schemaRuntimeModules = convexModuleFiles.map((file) => file.replace(TS_EXTENSION_RE, ""));
+	const schemaRuntimePlaceholders = ensureGeneratedRuntimePlaceholders(fileCache, functionsDir, schemaRuntimeModules, resolveModuleRuntimeExportNames(schemaRuntimeModules, normalizedTrimSegments));
 	const schemaMetadata = await (async () => {
 		try {
 			return await withCodegenParseSentinel(() => resolveSchemaMetadataForCodegen(functionsDir, debug, getSharedJitiInstance));
 		} finally {
-			for (const schemaRuntimePlaceholder of schemaRuntimePlaceholders) fs.rmSync(schemaRuntimePlaceholder, { force: true });
+			for (const schemaRuntimePlaceholder of schemaRuntimePlaceholders) fileCache.remove(schemaRuntimePlaceholder);
 		}
 	})();
 	const hasOrmSchemaMetadata = schemaMetadata.hasOrmSchema;
 	const hasRelationsMetadata = schemaMetadata.hasRelations;
-	const hasRelationsExport = hasNamedExport(path.join(functionsDir, "schema.ts"), "relations");
-	const hasSchemaTriggersExport = hasNamedExport(path.join(functionsDir, "schema.ts"), "triggers");
-	const hasDedicatedTriggersExport = hasNamedExport(path.join(functionsDir, "triggers.ts"), "triggers");
+	const hasRelationsExport = hasNamedExport(fileCache, path.join(functionsDir, "schema.ts"), "relations");
+	const hasSchemaTriggersExport = hasNamedExport(fileCache, path.join(functionsDir, "schema.ts"), "triggers");
+	const hasDedicatedTriggersExport = hasNamedExport(fileCache, path.join(functionsDir, "triggers.ts"), "triggers");
 	const hasMigrationsManifest = fs.existsSync(path.join(functionsDir, "migrations", "manifest.ts"));
 	if (hasRelationsExport) throw new Error("Codegen error: do not export `relations` from schema.ts. Chain relations on the default schema export with `defineSchema(...).relations(...)`.");
 	if (hasSchemaTriggersExport || hasDedicatedTriggersExport) throw new Error("Codegen error: do not export `triggers` from schema.ts or triggers.ts. Chain triggers on the default schema export with `defineSchema(...).relations(...).triggers(...)`.");
 	const hasOrmSchema = hasOrmSchemaMetadata;
 	const convexGeneratedServerFile = getConvexGeneratedServerFile(functionsDir);
-	supportPlaceholderState = ensureGeneratedSupportPlaceholders(functionsDir, {
+	supportPlaceholderState = ensureGeneratedSupportPlaceholders(fileCache, functionsDir, {
 		includeAuth: generateAuth,
-		procedureNameLookup: fs.existsSync(procedureNamesOutputFile) ? void 0 : readLegacyProcedureNameLookup(serverOutputFile),
+		procedureNameLookup: fileCache.read(procedureNamesOutputFile) === null ? readLegacyProcedureNameLookup(fileCache, serverOutputFile) : void 0,
 		replaceServer: convexGeneratedServerFile === void 0
 	});
-	const emitServerFile = () => writeFileIfChanged(serverOutputFile, emitGeneratedServerFile(serverOutputFile, functionsDir, hasOrmSchema, schemaMetadata.hasAggregateIndexes, hasMigrationsManifest));
+	const emitServerFile = () => fileCache.writeIfChanged(serverOutputFile, emitGeneratedServerFile(serverOutputFile, functionsDir, hasOrmSchema, schemaMetadata.hasAggregateIndexes, hasMigrationsManifest));
 	if (convexGeneratedServerFile) emitServerFile();
 	if (generateApi) {
 		globalThis.__KITCN_CODEGEN__ = true;
 		try {
 			const jitiInstance = getSharedJitiInstance();
 			const serverShimSpecifier = normalizeImportPath(getProjectServerParserShimPath());
-			const files = listFilesRecursive(functionsDir).filter((file) => file.endsWith(".ts") && isValidConvexFile(file));
-			const parseCandidateFiles = files.filter((file) => hasPotentialCodegenExports(fs.readFileSync(path.join(functionsDir, file), "utf8"), file));
+			const parseCandidateFiles = convexModuleFiles.filter((file) => hasPotentialCodegenExports(fileCache.read(path.join(functionsDir, file)) ?? "", file));
 			const existingRuntimeFilesBeforeParse = new Set(listGeneratedRuntimeFiles(functionsDir));
 			const runtimePlaceholderModules = [...new Set([
-				...files.map((file) => file.replace(TS_EXTENSION_RE, "")),
+				...schemaRuntimeModules,
 				...hasOrmSchema ? ["generated/server"] : [],
 				...hasOrmSchema ? ["generated/aggregate"] : [],
 				...generateAuth ? [generatedAuthModuleName] : []
 			])];
-			createdRuntimePlaceholders = ensureGeneratedRuntimePlaceholders(functionsDir, runtimePlaceholderModules, resolveModuleRuntimeExportNames(runtimePlaceholderModules, normalizedTrimSegments));
+			createdRuntimePlaceholders = ensureGeneratedRuntimePlaceholders(fileCache, functionsDir, runtimePlaceholderModules, resolveModuleRuntimeExportNames(runtimePlaceholderModules, normalizedTrimSegments));
 			for (const file of parseCandidateFiles) {
 				const filePath = path.join(functionsDir, file);
 				const moduleName = file.replace(TS_EXTENSION_RE, "");
 				try {
-					const { meta: moduleMeta, httpRoutes, procedures } = await parseModuleRuntime(filePath, jitiInstance, serverShimSpecifier);
+					const { meta: moduleMeta, httpRoutes, procedures } = await parseModuleRuntime(fileCache, filePath, jitiInstance, serverShimSpecifier);
 					if (moduleMeta) {
 						meta[moduleName] = moduleMeta;
 						const fnCount = Object.keys(moduleMeta).length;
@@ -4023,6 +4067,7 @@ async function generateMeta(sharedDir, options) {
 					});
 					const procedureNameEntries = buildProcedureNameLookupEntries({
 						file,
+						fileCache,
 						filePath,
 						moduleName,
 						procedures
@@ -4045,13 +4090,13 @@ async function generateMeta(sharedDir, options) {
 		}
 	}
 	if (fatalParseFailures.length > 0) {
-		for (const createdRuntimePlaceholder of createdRuntimePlaceholders) fs.rmSync(createdRuntimePlaceholder, { force: true });
-		for (const createdSupportPlaceholder of supportPlaceholderState.createdFiles) fs.rmSync(createdSupportPlaceholder, { force: true });
-		for (const replacedSupportFile of supportPlaceholderState.replacedFiles) fs.writeFileSync(replacedSupportFile.filePath, replacedSupportFile.content, "utf8");
+		for (const createdRuntimePlaceholder of createdRuntimePlaceholders) fileCache.remove(createdRuntimePlaceholder);
+		for (const createdSupportPlaceholder of supportPlaceholderState.createdFiles) fileCache.remove(createdSupportPlaceholder);
+		for (const replacedSupportFile of supportPlaceholderState.replacedFiles) fileCache.write(replacedSupportFile.filePath, replacedSupportFile.content);
 		const failureSummary = fatalParseFailures.map(({ file, error }) => `- ${file}: ${error instanceof Error ? error.message : String(error)}`).join("\n");
 		throw new Error(`kitcn codegen aborted because module parsing failed:\n${failureSummary}`);
 	}
-	cleanupGeneratedPluginArtifacts(functionsDir);
+	cleanupGeneratedPluginArtifacts(fileCache, functionsDir);
 	if (generateApi) {
 		const routesByPath = /* @__PURE__ */ new Map();
 		for (const [key, route] of Object.entries(allHttpRoutes)) {
@@ -4070,10 +4115,10 @@ async function generateMeta(sharedDir, options) {
 		}
 		const schemaImportPath = getSchemaImportPath(outputFile, functionsDir);
 		const httpImportPath = getHttpImportPath(outputFile, functionsDir);
-		const hasTablesExport = hasNamedExport(path.join(functionsDir, "schema.ts"), "tables");
+		const hasTablesExport = hasNamedExport(fileCache, path.join(functionsDir, "schema.ts"), "tables");
 		const needsInferSelectModelImport = hasTablesExport;
 		const needsInferInsertModelImport = hasTablesExport;
-		const hasHttpRouterExport = hasNamedExport(path.join(functionsDir, "http.ts"), "httpRouter");
+		const hasHttpRouterExport = hasNamedExport(fileCache, path.join(functionsDir, "http.ts"), "httpRouter");
 		const apiTree = createApiTree(meta);
 		if (Object.hasOwn(apiTree.children, "http") || apiTree.functions.some((entry) => entry.fnName === "http")) throw new Error("Codegen conflict: root \"http\" namespace is reserved for generated HTTP router types. Rename your Convex module/function.");
 		const apiObjectLines = emitApiObject(apiTree, [], outputFile, functionsDir, 1, dedupedRoutes, hasHttpRouterExport);
@@ -4107,23 +4152,26 @@ ${optionalTypeExports}
 `;
 		const outputDirname = path.dirname(outputFile);
 		if (!fs.existsSync(outputDirname)) fs.mkdirSync(outputDirname, { recursive: true });
-		writeFileIfChanged(outputFile, output);
-	} else fs.rmSync(outputFile, { force: true });
+		fileCache.writeIfChanged(outputFile, output);
+	} else fileCache.remove(outputFile);
 	const generatedOutputDirname = path.dirname(serverOutputFile);
 	if (!fs.existsSync(generatedOutputDirname)) fs.mkdirSync(generatedOutputDirname, { recursive: true });
 	emitServerFile();
-	if (generateApi) writeFileIfChanged(procedureNamesOutputFile, emitGeneratedProcedureNamesFile(procedureNameLookup));
-	if (hasOrmSchema) writeFileIfChanged(aggregateOutputFile, emitGeneratedAggregateFile(aggregateOutputFile, functionsDir));
-	else fs.rmSync(aggregateOutputFile, { force: true });
-	fs.rmSync(ormOutputFile, { force: true });
-	fs.rmSync(crpcOutputFile, { force: true });
-	writeFileIfChanged(migrationsHelperOutputFile, emitGeneratedMigrationsFile(migrationsHelperOutputFile, functionsDir, hasRelationsMetadata));
-	fs.rmSync(legacyGeneratedMigrationsOutputFile, { force: true });
-	fs.rmSync(legacyGeneratedMigrationsRuntimeOutputFile, { force: true });
-	fs.rmSync(legacyGeneratedMigrationsUnderscoreOutputFile, { force: true });
-	if (generateAuth) writeFileIfChanged(authOutputFile, emitGeneratedAuthFile(authOutputFile, functionsDir, hasOrmSchema, authContract));
-	else fs.rmSync(authOutputFile, { force: true });
-	fs.rmSync(getLegacyGeneratedOutputFile(functionsDir), { force: true });
+	if (generateApi) fileCache.writeIfChanged(procedureNamesOutputFile, emitGeneratedProcedureNamesFile(procedureNameLookup));
+	if (hasOrmSchema) fileCache.writeIfChanged(aggregateOutputFile, emitGeneratedAggregateFile(aggregateOutputFile, functionsDir));
+	else fileCache.remove(aggregateOutputFile);
+	fileCache.remove(ormOutputFile);
+	fileCache.remove(crpcOutputFile);
+	const migrationsOutput = emitGeneratedMigrationsFile(migrationsHelperOutputFile, functionsDir, hasRelationsMetadata);
+	fileCache.writeIfChanged(migrationsHelperOutputFile, migrationsOutput);
+	fileCache.remove(legacyGeneratedMigrationsOutputFile);
+	fileCache.remove(legacyGeneratedMigrationsRuntimeOutputFile);
+	fileCache.remove(legacyGeneratedMigrationsUnderscoreOutputFile);
+	if (generateAuth) {
+		const authOutput = emitGeneratedAuthFile(authOutputFile, functionsDir, hasOrmSchema, authContract);
+		fileCache.writeIfChanged(authOutputFile, authOutput);
+	} else fileCache.remove(authOutputFile);
+	fileCache.remove(getLegacyGeneratedOutputFile(functionsDir));
 	const mergedProcedureEntries = dedupeProcedureEntries([
 		...hasOrmSchema ? buildGeneratedOrmRuntimeProcedureEntries("generated/server") : [],
 		...hasOrmSchema ? buildGeneratedAggregateRuntimeProcedureEntries("generated/aggregate") : [],
@@ -4144,20 +4192,20 @@ ${optionalTypeExports}
 	const runtimeExportNames = resolveModuleRuntimeExportNames([...runtimeProcedureEntriesByModule.keys()], normalizedTrimSegments);
 	for (const [moduleName, moduleEntries] of [...runtimeProcedureEntriesByModule].sort(([moduleA], [moduleB]) => moduleA.localeCompare(moduleB))) {
 		const runtimeOutputFile = getGeneratedRuntimeOutputFile(functionsDir, moduleName);
-		const runtimeOutput = emitGeneratedModuleRuntimeFile(runtimeOutputFile, functionsDir, moduleName, moduleEntries, runtimeExportNames);
+		const runtimeOutput = emitGeneratedModuleRuntimeFile(fileCache, runtimeOutputFile, functionsDir, moduleName, moduleEntries, runtimeExportNames);
 		fs.mkdirSync(path.dirname(runtimeOutputFile), { recursive: true });
-		writeFileIfChanged(runtimeOutputFile, runtimeOutput);
+		fileCache.writeIfChanged(runtimeOutputFile, runtimeOutput);
 		runtimeOutputFiles.push(runtimeOutputFile);
 	}
 	const runtimeOutputFileSet = new Set(runtimeOutputFiles);
 	const existingRuntimeFiles = listGeneratedRuntimeFiles(functionsDir);
 	for (const existingRuntimeFile of existingRuntimeFiles) {
 		if (runtimeOutputFileSet.has(existingRuntimeFile) || runtimeFilesPreservedFromParseFailures.has(existingRuntimeFile)) continue;
-		fs.rmSync(existingRuntimeFile, { force: true });
+		fileCache.remove(existingRuntimeFile);
 	}
 	for (const createdRuntimePlaceholder of createdRuntimePlaceholders) {
 		if (runtimeOutputFileSet.has(createdRuntimePlaceholder) || runtimeFilesPreservedFromParseFailures.has(createdRuntimePlaceholder)) continue;
-		fs.rmSync(createdRuntimePlaceholder, { force: true });
+		fileCache.remove(createdRuntimePlaceholder);
 	}
 	const elapsed = ((Date.now() - startTime) / 1e3).toFixed(2);
 	const time = (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", {

package/dist/orm/aggregate-index/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as RankOrderField, G as CountBackfillKickoffArgs, J as AggregateQueryPlan, K as CountBackfillMode, Q as RankIndexDefinition, W as CountBackfillChunkArgs, X as AggregateIndexDefinition, Y as CountQueryPlan, Z as CountIndexDefinition, q as CountBackfillStatusArgs, r as OrmCapability } from "../../capabilities-DtDfpdcH.js";
+import { $ as RankOrderField, G as CountBackfillKickoffArgs, J as AggregateQueryPlan, K as CountBackfillMode, Q as RankIndexDefinition, W as CountBackfillChunkArgs, X as AggregateIndexDefinition, Y as CountQueryPlan, Z as CountIndexDefinition, q as CountBackfillStatusArgs, r as OrmCapability } from "../../capabilities-QNGgWHQd.js";
 
 //#region src/orm/aggregate-index/capability.d.ts
 /**

package/dist/orm/index.d.ts

@@ -1,5 +1,5 @@
-import { $n as BinaryExpression, $t as OrmLifecycleOperation, A as DatabaseWithMutations, An as ConvexCheckConfig, Ar as AnyColumn, At as VectorQueryConfig, B as RlsContext, Bn as ConvexTextBuilderInitial, Br as IsUnique, Bt as RelationsBuilderColumnConfig, C as MigrationTableName, Cn as aggregateIndex, Cr as notBetween, Ct as OrderDirection, D as defineMigrationSet, Dn as uniqueIndex, Dt as ReturningResult, E as defineMigration, En as searchIndex, Er as startsWith, Et as ReturningAll, Fn as ConvexUniqueConstraintConfig, Fr as ColumnBuilderWithTableName, Ft as ExtractTablesWithRelations, Gt as defineRelations, H as EdgeMetadata, In as check, Ir as ColumnDataType, It as ManyConfig, Jt as ConvexDeletionConfig, Kt as defineRelationsPart, Ln as foreignKey, Lr as DrizzleEntity, Lt as OneConfig, M as OrmReader$1, Mn as ConvexForeignKeyConfig, Mr as ColumnBuilderBaseConfig, Mt as unsetToken, N as OrmWriter$1, Nn as ConvexUniqueConstraintBuilder, Nr as ColumnBuilderRuntimeConfig, O as detectMigrationDrift, On as vectorIndex, Or as SystemFields, Ot as ReturningSelection, Pn as ConvexUniqueConstraintBuilderOn, Pr as ColumnBuilderTypeConfig, Pt as ExtractTablesFromSchema, Qn as TableName, Qt as OrmLifecycleChange, Rn as unique, Rr as HasDefault, Rt as RelationsBuilder, S as MigrationStep, Sn as ConvexVectorIndexConfig, Sr as not, St as OrderByClause, T as buildMigrationPlan, Tn as rankIndex, Tr as or, Tt as PredicateWhereIndexConfig, U as extractRelationsConfig, Un as Brand, Ut as TableRelationalConfig, V as RlsMode, Vn as text, Vr as NotNull, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yn as OrmSchemaExtensions, Yt as ConvexTable, Zn as OrmSchemaTriggers, Zt as DiscriminatorBuilderConfig, _ as MigrationMigrateOne, _n as ConvexSearchIndexBuilder, _r as isNull, _t as MutationPaginateConfig, an as RlsPolicyConfig, ar as and, at as CountConfig, b as MigrationSet, bn as ConvexVectorIndexBuilder, br as lte, bt as MutationReturning, cn as RlsRole, cr as endsWith, ct as FilterOperators, d as MigrationDefinition, dn as ConvexAggregateIndexBuilder, dr as gt, dt as InferModelFromColumns, en as TableConfig, er as ExpressionVisitor, et as AggregateConfig, f as MigrationDirection, fn as ConvexAggregateIndexBuilderOn, fr as gte, ft as InferSelectModel, g as MigrationManifestEntry, gn as ConvexRankIndexBuilderOn, gr as isNotNull, gt as MutationExecutionMode, h as MigrationDriftIssue, hn as ConvexRankIndexBuilder, hr as isFieldReference, ht as MutationExecuteResult, i as OrmMigrationCapability, in as RlsPolicy, ir as UnaryExpression, it as BuildRelationResult, j as DatabaseWithQuery, jn as ConvexForeignKeyBuilder, jr as ColumnBuilder, jt as VectorSearchProvider, kn as ConvexCheckBuilder, kt as UpdateSet, ln as RlsRoleConfig, lr as eq, lt as GetColumnData, m as MigrationDocContext, mn as ConvexIndexBuilderOn, mr as inArray, mt as MutationExecuteConfig, n as OrmCapabilities, nn as deletion, nr as FilterExpression, nt as AggregateResult, on as RlsPolicyToOption, or as between, ot as CountResult, p as MigrationDoc, pn as ConvexIndexBuilder, pr as ilike, pt as InsertValue, qn as OrmSchemaExtensionTables, qt as ConvexDeletionBuilder, r as OrmCapability, rn as discriminator, rr as LogicalExpression, rt as BuildQueryResult, sn as rlsPolicy, sr as contains, st as DBQueryConfig, t as OrmAggregateCapability, tn as convexTable, tr as FieldReference, tt as AggregateFieldValue, u as MigrationAppliedState, un as rlsRole, ur as fieldRef, ut as InferInsertModel, v as MigrationPlan, vn as ConvexSearchIndexBuilderOn, vr as like, vt as MutationPaginatedResult, w as MigrationWriteMode, wn as index, wr as notInArray, wt as PaginatedResult, x as MigrationStateMap, xn as ConvexVectorIndexBuilderOn, xr as ne, xt as MutationRunMode, y as MigrationRunStatus, yn as ConvexSearchIndexConfig, yr as lt, yt as MutationResult, zn as ConvexTextBuilder, zr as IsPrimaryKey, zt as RelationsBuilderColumnBase } from "../capabilities-DtDfpdcH.js";
-import { $ as OrmClientWithApi$1, A as ConvexDateMode, B as ConvexBytesBuilderInitial, C as ConvexNumberBuilderInitial, D as id, E as ConvexIdBuilderInitial, F as custom, G as ConvexBigIntBuilder, H as ConvexBooleanBuilder, I as json, J as CreateOrmOptions, K as ConvexBigIntBuilderInitial, L as objectOf, M as ConvexCustomBuilder, N as ConvexCustomBuilderInitial, O as ConvexDateBuilder, P as arrayOf, Q as OrmClientBase$1, R as unionOf, S as ConvexNumberBuilder, St as defineTriggers, T as ConvexIdBuilder, U as ConvexBooleanBuilderInitial, V as bytes, W as boolean, X as GenericOrmCtx$1, Y as GenericOrm$1, Z as OrmApiResult, _ as ConvexTimestampMode, _t as OrmBeforeResult, a as requireSchemaRelations, at as ScheduledMutationBatchArgs, b as ConvexTextEnumBuilderInitial, bt as OrmTriggerContext, c as TableConfigResult, ct as scheduledDeleteFactory, d as OrmNotFoundError, et as OrmFunctions, f as ConvexVectorBuilder, g as ConvexTimestampBuilderInitial, gt as defineSchemaExtension, h as ConvexTimestampBuilder, ht as SchemaExtension, i as getSchemaTriggers, it as createOrm, j as date, k as ConvexDateBuilderInitial, l as getTableColumns, m as vector, n as defineSchema, nt as OrmWriterCtx, o as asc, ot as scheduledMutationBatchFactory, p as ConvexVectorBuilderInitial, q as bigint, r as getSchemaRelations, rt as ResolveOrmSchema, s as desc, st as ScheduledDeleteArgs, t as WhereClauseResult, tt as OrmReaderCtx, u as getTableConfig, v as timestamp, vt as OrmTableTriggers, w as integer, x as textEnum, xt as OrmTriggers, y as ConvexTextEnumBuilder, yt as OrmTriggerChange, z as ConvexBytesBuilder } from "../where-clause-compiler-3fKontPx.js";
+import { $n as BinaryExpression, $t as OrmLifecycleOperation, A as DatabaseWithMutations, An as ConvexCheckConfig, Ar as AnyColumn, At as VectorQueryConfig, B as RlsContext, Bn as ConvexTextBuilderInitial, Br as IsUnique, Bt as RelationsBuilderColumnConfig, C as MigrationTableName, Cn as aggregateIndex, Cr as notBetween, Ct as OrderDirection, D as defineMigrationSet, Dn as uniqueIndex, Dt as ReturningResult, E as defineMigration, En as searchIndex, Er as startsWith, Et as ReturningAll, Fn as ConvexUniqueConstraintConfig, Fr as ColumnBuilderWithTableName, Ft as ExtractTablesWithRelations, Gt as defineRelations, H as EdgeMetadata, In as check, Ir as ColumnDataType, It as ManyConfig, Jt as ConvexDeletionConfig, Kt as defineRelationsPart, Ln as foreignKey, Lr as DrizzleEntity, Lt as OneConfig, M as OrmReader$1, Mn as ConvexForeignKeyConfig, Mr as ColumnBuilderBaseConfig, Mt as unsetToken, N as OrmWriter$1, Nn as ConvexUniqueConstraintBuilder, Nr as ColumnBuilderRuntimeConfig, O as detectMigrationDrift, On as vectorIndex, Or as SystemFields, Ot as ReturningSelection, Pn as ConvexUniqueConstraintBuilderOn, Pr as ColumnBuilderTypeConfig, Pt as ExtractTablesFromSchema, Qn as TableName, Qt as OrmLifecycleChange, Rn as unique, Rr as HasDefault, Rt as RelationsBuilder, S as MigrationStep, Sn as ConvexVectorIndexConfig, Sr as not, St as OrderByClause, T as buildMigrationPlan, Tn as rankIndex, Tr as or, Tt as PredicateWhereIndexConfig, U as extractRelationsConfig, Un as Brand, Ut as TableRelationalConfig, V as RlsMode, Vn as text, Vr as NotNull, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yn as OrmSchemaExtensions, Yt as ConvexTable, Zn as OrmSchemaTriggers, Zt as DiscriminatorBuilderConfig, _ as MigrationMigrateOne, _n as ConvexSearchIndexBuilder, _r as isNull, _t as MutationPaginateConfig, an as RlsPolicyConfig, ar as and, at as CountConfig, b as MigrationSet, bn as ConvexVectorIndexBuilder, br as lte, bt as MutationReturning, cn as RlsRole, cr as endsWith, ct as FilterOperators, d as MigrationDefinition, dn as ConvexAggregateIndexBuilder, dr as gt, dt as InferModelFromColumns, en as TableConfig, er as ExpressionVisitor, et as AggregateConfig, f as MigrationDirection, fn as ConvexAggregateIndexBuilderOn, fr as gte, ft as InferSelectModel, g as MigrationManifestEntry, gn as ConvexRankIndexBuilderOn, gr as isNotNull, gt as MutationExecutionMode, h as MigrationDriftIssue, hn as ConvexRankIndexBuilder, hr as isFieldReference, ht as MutationExecuteResult, i as OrmMigrationCapability, in as RlsPolicy, ir as UnaryExpression, it as BuildRelationResult, j as DatabaseWithQuery, jn as ConvexForeignKeyBuilder, jr as ColumnBuilder, jt as VectorSearchProvider, kn as ConvexCheckBuilder, kt as UpdateSet, ln as RlsRoleConfig, lr as eq, lt as GetColumnData, m as MigrationDocContext, mn as ConvexIndexBuilderOn, mr as inArray, mt as MutationExecuteConfig, n as OrmCapabilities, nn as deletion, nr as FilterExpression, nt as AggregateResult, on as RlsPolicyToOption, or as between, ot as CountResult, p as MigrationDoc, pn as ConvexIndexBuilder, pr as ilike, pt as InsertValue, qn as OrmSchemaExtensionTables, qt as ConvexDeletionBuilder, r as OrmCapability, rn as discriminator, rr as LogicalExpression, rt as BuildQueryResult, sn as rlsPolicy, sr as contains, st as DBQueryConfig, t as OrmAggregateCapability, tn as convexTable, tr as FieldReference, tt as AggregateFieldValue, u as MigrationAppliedState, un as rlsRole, ur as fieldRef, ut as InferInsertModel, v as MigrationPlan, vn as ConvexSearchIndexBuilderOn, vr as like, vt as MutationPaginatedResult, w as MigrationWriteMode, wn as index, wr as notInArray, wt as PaginatedResult, x as MigrationStateMap, xn as ConvexVectorIndexBuilderOn, xr as ne, xt as MutationRunMode, y as MigrationRunStatus, yn as ConvexSearchIndexConfig, yr as lt, yt as MutationResult, zn as ConvexTextBuilder, zr as IsPrimaryKey, zt as RelationsBuilderColumnBase } from "../capabilities-QNGgWHQd.js";
+import { $ as OrmClientWithApi$1, A as ConvexDateMode, B as ConvexBytesBuilderInitial, C as ConvexNumberBuilderInitial, D as id, E as ConvexIdBuilderInitial, F as custom, G as ConvexBigIntBuilder, H as ConvexBooleanBuilder, I as json, J as CreateOrmOptions, K as ConvexBigIntBuilderInitial, L as objectOf, M as ConvexCustomBuilder, N as ConvexCustomBuilderInitial, O as ConvexDateBuilder, P as arrayOf, Q as OrmClientBase$1, R as unionOf, S as ConvexNumberBuilder, St as defineTriggers, T as ConvexIdBuilder, U as ConvexBooleanBuilderInitial, V as bytes, W as boolean, X as GenericOrmCtx$1, Y as GenericOrm$1, Z as OrmApiResult, _ as ConvexTimestampMode, _t as OrmBeforeResult, a as requireSchemaRelations, at as ScheduledMutationBatchArgs, b as ConvexTextEnumBuilderInitial, bt as OrmTriggerContext, c as TableConfigResult, ct as scheduledDeleteFactory, d as OrmNotFoundError, et as OrmFunctions, f as ConvexVectorBuilder, g as ConvexTimestampBuilderInitial, gt as defineSchemaExtension, h as ConvexTimestampBuilder, ht as SchemaExtension, i as getSchemaTriggers, it as createOrm, j as date, k as ConvexDateBuilderInitial, l as getTableColumns, m as vector, n as defineSchema, nt as OrmWriterCtx, o as asc, ot as scheduledMutationBatchFactory, p as ConvexVectorBuilderInitial, q as bigint, r as getSchemaRelations, rt as ResolveOrmSchema, s as desc, st as ScheduledDeleteArgs, t as WhereClauseResult, tt as OrmReaderCtx, u as getTableConfig, v as timestamp, vt as OrmTableTriggers, w as integer, x as textEnum, xt as OrmTriggers, y as ConvexTextEnumBuilder, yt as OrmTriggerChange, z as ConvexBytesBuilder } from "../where-clause-compiler-DfFcNKtn.js";
 import { i as pretendRequired, n as deprecated, r as pretend } from "../validators-wOIjhkfN.js";
 import { a as QueryCtxWithPreferredOrmQueryTable, i as QueryCtxWithOrmQueryTable, n as LookupByIdResultByCtx, o as getByIdWithOrmQueryFallback, r as QueryCtxWithOptionalOrmQueryTable, t as DocByCtx } from "../query-context-DJONf8X5.js";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchemaDefinition } from "convex/server";

package/dist/orm/index.js

@@ -2675,16 +2675,16 @@ var GelRelationalQuery = class GelRelationalQuery extends QueryPromise {
 		return streamQuery;
 	}
 	_buildUnionSourceStream(source, fallbackOrder) {
-		const configuredIndex = this.configuredIndex;
+		const sourceIndex = source.index ?? this.configuredIndex;
 		this._assertWhereIndexRequirement({
 			where: source.where,
 			tableConfig: this.tableConfig,
-			hasConfiguredIndex: Boolean(configuredIndex?.name),
+			hasConfiguredIndex: Boolean(sourceIndex?.name),
 			context: "pipeline.union source"
 		});
 		const schemaDefinition = this._getSchemaDefinitionOrThrow();
 		let sourceStream = stream(this.db, schemaDefinition).query(this.tableConfig.name);
-		if (configuredIndex?.name) sourceStream = sourceStream.withIndex(configuredIndex.name, configuredIndex.range ? configuredIndex.range : (q) => q);
+		if (sourceIndex?.name) sourceStream = sourceStream.withIndex(sourceIndex.name, sourceIndex.range ? sourceIndex.range : (q) => q);
 		sourceStream = sourceStream.order(fallbackOrder);
 		const sourcePredicate = this._buildTableFilterPredicate(source.where, this.tableConfig);
 		if (sourcePredicate) sourceStream = sourceStream.filterWith(sourcePredicate);

package/dist/orm/migrations/index.d.ts

@@ -1,3 +1,3 @@
-import { C as MigrationTableName, D as defineMigrationSet, E as defineMigration, O as detectMigrationDrift, S as MigrationStep, T as buildMigrationPlan, _ as MigrationMigrateOne, a as MigrationCancelArgs, b as MigrationSet, c as MigrationStatusArgs, d as MigrationDefinition, f as MigrationDirection, g as MigrationManifestEntry, h as MigrationDriftIssue, l as createMigrationHandlers, m as MigrationDocContext, o as MigrationRunArgs, p as MigrationDoc, s as MigrationRunChunkArgs, u as MigrationAppliedState, v as MigrationPlan, w as MigrationWriteMode, x as MigrationStateMap, y as MigrationRunStatus } from "../../capabilities-DtDfpdcH.js";
-import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-3fKontPx.js";
+import { C as MigrationTableName, D as defineMigrationSet, E as defineMigration, O as detectMigrationDrift, S as MigrationStep, T as buildMigrationPlan, _ as MigrationMigrateOne, a as MigrationCancelArgs, b as MigrationSet, c as MigrationStatusArgs, d as MigrationDefinition, f as MigrationDirection, g as MigrationManifestEntry, h as MigrationDriftIssue, l as createMigrationHandlers, m as MigrationDocContext, o as MigrationRunArgs, p as MigrationDoc, s as MigrationRunChunkArgs, u as MigrationAppliedState, v as MigrationPlan, w as MigrationWriteMode, x as MigrationStateMap, y as MigrationRunStatus } from "../../capabilities-QNGgWHQd.js";
+import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-DfFcNKtn.js";
 export { MIGRATION_RUN_TABLE, MIGRATION_STATE_TABLE, MIGRATION_STORAGE_TABLE_NAMES, type MigrationAppliedState, type MigrationCancelArgs, type MigrationDefinition, type MigrationDirection, type MigrationDoc, type MigrationDocContext, type MigrationDriftIssue, type MigrationManifestEntry, type MigrationMigrateOne, type MigrationPlan, type MigrationRunArgs, type MigrationRunChunkArgs, type MigrationRunStatus, type MigrationSet, type MigrationStateMap, type MigrationStatusArgs, type MigrationStep, type MigrationTableName, type MigrationWriteMode, buildMigrationPlan, createMigrationHandlers, defineMigration, defineMigrationSet, detectMigrationDrift, injectMigrationStorageTables, migrationCapability, migrationExtension, migrationStorageTables };

package/dist/watcher.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as generateMeta, d as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, u as logger } from "./local-env-9Qtfn3wR.mjs";
+import { a as generateMeta, d as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, u as logger } from "./local-env-Z8jj6ecD.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 

package/dist/{where-clause-compiler-3fKontPx.d.ts → where-clause-compiler-DfFcNKtn.d.ts}

@@ -1,4 +1,4 @@
-import { Bn as ConvexTextBuilderInitial, Dr as SystemFieldAliases, F as DeleteMode, Gn as OrmRuntimeDefaults, H as EdgeMetadata, Hn as ConvexColumnBuilder, Hr as entityKind, Ht as RelationsConfigWithSchema, I as SerializedFilterExpression, Jn as OrmSchemaExtensionTriggers, Kn as OrmSchemaExtensionRelations, L as getChecks, M as OrmReader, Mr as ColumnBuilderBaseConfig, N as OrmWriter, Nt as AnyRelationsBuilderConfig, Or as SystemFields, P as CascadeMode, Pt as ExtractTablesFromSchema, Qt as OrmLifecycleChange, R as getForeignKeys, Rr as HasDefault, Rt as RelationsBuilder, St as OrderByClause, Ut as TableRelationalConfig, Vt as RelationsBuilderConfigValue, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yt as ConvexTable, Zn as OrmSchemaTriggers, b as MigrationSet, ft as InferSelectModel, in as RlsPolicy, jr as ColumnBuilder, jt as VectorSearchProvider, k as CreateDatabaseOptions, kr as $Type, nr as FilterExpression$1, r as OrmCapability, ut as InferInsertModel, z as getUniqueIndexes } from "./capabilities-DtDfpdcH.js";
+import { Bn as ConvexTextBuilderInitial, Dr as SystemFieldAliases, F as DeleteMode, Gn as OrmRuntimeDefaults, H as EdgeMetadata, Hn as ConvexColumnBuilder, Hr as entityKind, Ht as RelationsConfigWithSchema, I as SerializedFilterExpression, Jn as OrmSchemaExtensionTriggers, Kn as OrmSchemaExtensionRelations, L as getChecks, M as OrmReader, Mr as ColumnBuilderBaseConfig, N as OrmWriter, Nt as AnyRelationsBuilderConfig, Or as SystemFields, P as CascadeMode, Pt as ExtractTablesFromSchema, Qt as OrmLifecycleChange, R as getForeignKeys, Rr as HasDefault, Rt as RelationsBuilder, St as OrderByClause, Ut as TableRelationalConfig, Vt as RelationsBuilderConfigValue, Wn as Columns, Wt as TablesRelationalConfig, Xn as OrmSchemaRelations, Xt as ConvexTableWithColumns, Yt as ConvexTable, Zn as OrmSchemaTriggers, b as MigrationSet, ft as InferSelectModel, in as RlsPolicy, jr as ColumnBuilder, jt as VectorSearchProvider, k as CreateDatabaseOptions, kr as $Type, nr as FilterExpression$1, r as OrmCapability, ut as InferInsertModel, z as getUniqueIndexes } from "./capabilities-QNGgWHQd.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Validator, Value } from "convex/values";
 import { DefineSchemaOptions, GenericDatabaseReader, GenericDatabaseWriter, GenericSchema, SchedulableFunctionReference, Scheduler, SchemaDefinition, internalActionGeneric, internalMutationGeneric } from "convex/server";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/kitcn/references/features/orm.md

@@ -543,45 +543,47 @@ return await ctx.orm.query.articles.findMany({
 
 ```ts
 return await ctx.orm.query.messages
-  .withIndex("by_from_to")
-  .select()
-  .union([
-    { where: { from: input.me, to: input.them } },
-    { where: { from: input.them, to: input.me } },
-  ])
-  .interleaveBy(["createdAt", "id"])
-  .filter(async (m) => !m.deletedAt)
-  .map(async (m) => ({ ...m, body: m.body.slice(0, 240) }))
-  .paginate({
-    cursor: input.cursor,
-    limit: input.limit,
-    maxScan: 500,
-  });
-```
-
-### Union with index ranges
-
-```ts
-const page = await ctx.orm.query.messages
   .select()
   .union([
     {
       index: {
         name: "by_from_to",
-        range: (q) => q.eq("from", me).eq("to", them),
+        range: (q) => q.eq("from", input.me).eq("to", input.them),
       },
     },
     {
       index: {
         name: "by_from_to",
-        range: (q) => q.eq("from", them).eq("to", me),
+        range: (q) => q.eq("from", input.them).eq("to", input.me),
       },
     },
   ])
   .interleaveBy(["createdAt", "id"])
-  .paginate({ cursor: null, limit: 20 });
+  .filter(async (m) => !m.deletedAt)
+  .map(async (m) => ({ ...m, body: m.body.slice(0, 240) }))
+  .paginate({
+    cursor: input.cursor,
+    limit: input.limit,
+    maxScan: 500,
+  });
 ```
 
+Per source:
+
+- `index: { name, range }` anchors that source on its own range. It overrides
+  the chain-level `.withIndex(...)`; sources that omit it use the chain index.
+- `where` filters that source's rows after the read.
+
+`interleaveBy` fields must be the trailing fields each source is already ordered
+by, so every field before them has to be pinned with `eq` in that source's
+range. Sources may name different indexes when they land on the same trailing
+fields — e.g. `by_author_likes` (authorId, numLikes) with `eq("authorId", ...)`
+merges with `numLikesAndType` (type, numLikes) with `eq("type", ...)` under
+`interleaveBy(["numLikes"])`.
+
+Anchor every source. A shared `.withIndex(...)` plus per-source `where` makes
+each source walk the same range and discard the misses after reading them.
+
 ### Pre-pagination transforms
 
 ```ts