appflare 0.2.15 → 0.2.16

package/Documentation.md

@@ -45,6 +45,33 @@ Schema is defined with `schema`, `table`, and `v` from Appflare.
 
 Example source: `packages/backend/schema.ts`.
 
+### 2.3 Relation helpers (`v.one`, `v.many`, `v.manyToMany`)
+
+- `v.one("target")` creates a single-reference relation and infers a local FK field.
+- `v.many("target")` is inverse one-to-many and infers an FK on the target table.
+- `v.manyToMany("target")` creates a many-to-many relation by synthesizing a junction table.
+
+Many-to-many example:
+
+```ts
+export const schemas = schema({
+	pets: table({
+		id: v.uuid(),
+		trips: v.manyToMany("trips"),
+	}),
+	trips: table({
+		id: v.uuid(),
+		pets: v.manyToMany("pets"),
+	}),
+});
+```
+
+Default behavior for `v.manyToMany`:
+
+- Generates one deterministic junction table per pair.
+- Junction rows are pure links (two FK columns, no payload columns).
+- Reciprocal declarations must agree on options (`junctionTable`, field names, FK actions), otherwise generation throws a conflict error.
+
 ---
 
 ## 3) How to create handlers

package/cli/schema-compiler.ts

@@ -5,6 +5,7 @@ import type {
 	ColumnDefinition,
 	ColumnType,
 	ManyRelationDefinition,
+	ManyToManyRelationDefinition,
 	OneRelationDefinition,
 	SchemaDefinition,
 	TableDefinition,
@@ -196,6 +197,296 @@ function resolveNotNullFromNullableFlags(
 	return defaultNotNull;
 }
 
+type ManyToManyPair = {
+	leftTable: string;
+	leftReferenceField: string;
+	rightTable: string;
+	rightReferenceField: string;
+	junctionTable: string;
+	leftField: string;
+	rightField: string;
+	leftSqlName?: string;
+	rightSqlName?: string;
+	onDelete?: OneRelationDefinition["onDelete"];
+	onUpdate?: OneRelationDefinition["onUpdate"];
+};
+
+function endpointKey(tableName: string, referenceField: string): string {
+	return `${tableName}:${referenceField}`;
+}
+
+function normalizeManyToManyPairKey(
+	sourceTable: string,
+	sourceReferenceField: string,
+	targetTable: string,
+	targetReferenceField: string,
+): {
+	key: string;
+	leftTable: string;
+	leftReferenceField: string;
+	rightTable: string;
+	rightReferenceField: string;
+	sourceIsLeft: boolean;
+} {
+	const source = endpointKey(sourceTable, sourceReferenceField);
+	const target = endpointKey(targetTable, targetReferenceField);
+	const sourceIsLeft = source <= target;
+
+	if (sourceIsLeft) {
+		return {
+			key: `${source}|${target}`,
+			leftTable: sourceTable,
+			leftReferenceField: sourceReferenceField,
+			rightTable: targetTable,
+			rightReferenceField: targetReferenceField,
+			sourceIsLeft: true,
+		};
+	}
+
+	return {
+		key: `${target}|${source}`,
+		leftTable: targetTable,
+		leftReferenceField: targetReferenceField,
+		rightTable: sourceTable,
+		rightReferenceField: sourceReferenceField,
+		sourceIsLeft: false,
+	};
+}
+
+function defaultManyToManyJunctionTable(
+	leftTable: string,
+	rightTable: string,
+): string {
+	return `${leftTable}${toPascalCase(rightTable)}Links`;
+}
+
+function defaultManyToManyFieldName(
+	ownerTable: string,
+	otherTable: string,
+	suffix: "source" | "target",
+): string {
+	const ownerSingular = singularize(ownerTable);
+	const otherSingular = singularize(otherTable);
+
+	if (ownerSingular === otherSingular) {
+		return `${suffix}${toPascalCase(ownerSingular)}Id`;
+	}
+
+	return `${ownerSingular}Id`;
+}
+
+function mergeManyToManyPairConfig(
+	existing: ManyToManyPair,
+	incoming: ManyToManyPair,
+	pairKey: string,
+): ManyToManyPair {
+	if (existing.junctionTable !== incoming.junctionTable) {
+		throw new Error(
+			`manyToMany pair '${pairKey}' has conflicting junctionTable values ('${existing.junctionTable}' vs '${incoming.junctionTable}').`,
+		);
+	}
+
+	if (existing.leftField !== incoming.leftField) {
+		throw new Error(
+			`manyToMany pair '${pairKey}' has conflicting left field values ('${existing.leftField}' vs '${incoming.leftField}').`,
+		);
+	}
+
+	if (existing.rightField !== incoming.rightField) {
+		throw new Error(
+			`manyToMany pair '${pairKey}' has conflicting right field values ('${existing.rightField}' vs '${incoming.rightField}').`,
+		);
+	}
+
+	if (existing.leftSqlName !== incoming.leftSqlName) {
+		throw new Error(
+			`manyToMany pair '${pairKey}' has conflicting left sql name values ('${existing.leftSqlName}' vs '${incoming.leftSqlName}').`,
+		);
+	}
+
+	if (existing.rightSqlName !== incoming.rightSqlName) {
+		throw new Error(
+			`manyToMany pair '${pairKey}' has conflicting right sql name values ('${existing.rightSqlName}' vs '${incoming.rightSqlName}').`,
+		);
+	}
+
+	if (existing.onDelete !== incoming.onDelete) {
+		throw new Error(
+			`manyToMany pair '${pairKey}' has conflicting onDelete values ('${existing.onDelete}' vs '${incoming.onDelete}').`,
+		);
+	}
+
+	if (existing.onUpdate !== incoming.onUpdate) {
+		throw new Error(
+			`manyToMany pair '${pairKey}' has conflicting onUpdate values ('${existing.onUpdate}' vs '${incoming.onUpdate}').`,
+		);
+	}
+
+	return existing;
+}
+
+function normalizeManyToManyRelations(definition: SchemaDefinition): void {
+	const pairMap = new Map<string, ManyToManyPair>();
+
+	for (const [sourceTableName, sourceTable] of Object.entries(
+		definition.tables,
+	)) {
+		for (const relation of Object.values(sourceTable.relations)) {
+			if (relation.relation !== "manyToMany") {
+				continue;
+			}
+
+			const sourceReferenceField = relation.referenceField ?? "id";
+			const targetReferenceField = relation.targetReferenceField ?? "id";
+
+			const normalizedPair = normalizeManyToManyPairKey(
+				sourceTableName,
+				sourceReferenceField,
+				relation.targetTable,
+				targetReferenceField,
+			);
+
+			const defaultLeftField = defaultManyToManyFieldName(
+				normalizedPair.leftTable,
+				normalizedPair.rightTable,
+				"source",
+			);
+			const defaultRightField = defaultManyToManyFieldName(
+				normalizedPair.rightTable,
+				normalizedPair.leftTable,
+				"target",
+			);
+
+			const pair: ManyToManyPair = {
+				leftTable: normalizedPair.leftTable,
+				leftReferenceField: normalizedPair.leftReferenceField,
+				rightTable: normalizedPair.rightTable,
+				rightReferenceField: normalizedPair.rightReferenceField,
+				junctionTable:
+					relation.junctionTable ??
+					defaultManyToManyJunctionTable(
+						normalizedPair.leftTable,
+						normalizedPair.rightTable,
+					),
+				leftField: normalizedPair.sourceIsLeft
+					? (relation.sourceField ?? defaultLeftField)
+					: (relation.targetField ?? defaultLeftField),
+				rightField: normalizedPair.sourceIsLeft
+					? (relation.targetField ?? defaultRightField)
+					: (relation.sourceField ?? defaultRightField),
+				leftSqlName: normalizedPair.sourceIsLeft
+					? relation.sourceSqlName
+					: relation.targetSqlName,
+				rightSqlName: normalizedPair.sourceIsLeft
+					? relation.targetSqlName
+					: relation.sourceSqlName,
+				onDelete: relation.onDelete,
+				onUpdate: relation.onUpdate,
+			};
+
+			if (pair.leftField === pair.rightField) {
+				throw new Error(
+					`manyToMany pair '${normalizedPair.key}' resolves to duplicate junction fields '${pair.leftField}'. Set sourceField/targetField explicitly.`,
+				);
+			}
+
+			const existing = pairMap.get(normalizedPair.key);
+			if (existing) {
+				mergeManyToManyPairConfig(existing, pair, normalizedPair.key);
+			} else {
+				pairMap.set(normalizedPair.key, pair);
+			}
+
+			relation.referenceField = sourceReferenceField;
+			relation.targetReferenceField = targetReferenceField;
+			relation.junctionTable = pair.junctionTable;
+			relation.sourceField = normalizedPair.sourceIsLeft
+				? pair.leftField
+				: pair.rightField;
+			relation.targetField = normalizedPair.sourceIsLeft
+				? pair.rightField
+				: pair.leftField;
+			relation.sourceSqlName = normalizedPair.sourceIsLeft
+				? pair.leftSqlName
+				: pair.rightSqlName;
+			relation.targetSqlName = normalizedPair.sourceIsLeft
+				? pair.rightSqlName
+				: pair.leftSqlName;
+		}
+	}
+
+	for (const pair of pairMap.values()) {
+		if (pair.junctionTable in definition.tables) {
+			throw new Error(
+				`manyToMany auto junction table '${pair.junctionTable}' conflicts with an existing table. Set a different junctionTable name.`,
+			);
+		}
+
+		const leftType =
+			getLocalReferenceType(
+				definition,
+				pair.leftTable,
+				pair.leftReferenceField,
+			) ?? "string";
+		const rightType =
+			getLocalReferenceType(
+				definition,
+				pair.rightTable,
+				pair.rightReferenceField,
+			) ?? "string";
+
+		definition.tables[pair.junctionTable] = {
+			kind: "table",
+			columns: {
+				[pair.leftField]: {
+					kind: "column",
+					type: leftType,
+					sqlName: pair.leftSqlName,
+					notNull: true,
+					nullable: false,
+					references: {
+						table: pair.leftTable,
+						column: pair.leftReferenceField,
+						onDelete: pair.onDelete,
+						onUpdate: pair.onUpdate,
+					},
+					index: true,
+				},
+				[pair.rightField]: {
+					kind: "column",
+					type: rightType,
+					sqlName: pair.rightSqlName,
+					notNull: true,
+					nullable: false,
+					references: {
+						table: pair.rightTable,
+						column: pair.rightReferenceField,
+						onDelete: pair.onDelete,
+						onUpdate: pair.onUpdate,
+					},
+					index: true,
+				},
+			},
+			relations: {
+				[pair.leftTable]: {
+					kind: "relation",
+					relation: "one",
+					targetTable: pair.leftTable,
+					field: pair.leftField,
+					referenceField: pair.leftReferenceField,
+				},
+				[pair.rightTable]: {
+					kind: "relation",
+					relation: "one",
+					targetTable: pair.rightTable,
+					field: pair.rightField,
+					referenceField: pair.rightReferenceField,
+				},
+			},
+		};
+	}
+}
+
 function validateNullableFlags(definition: SchemaDefinition): void {
 	for (const [tableName, table] of Object.entries(definition.tables)) {
 		for (const [columnName, column] of Object.entries(table.columns)) {
@@ -207,7 +498,11 @@ function validateNullableFlags(definition: SchemaDefinition): void {
 		}
 
 		for (const [relationName, relation] of Object.entries(table.relations)) {
-			if (relation.notNull === true && relation.nullable === true) {
+			if (
+				relation.relation !== "manyToMany" &&
+				relation.notNull === true &&
+				relation.nullable === true
+			) {
 				throw new Error(
 					`Invalid nullable configuration on '${tableName}.${relationName}': cannot set both notNull and nullable to true.`,
 				);
@@ -279,6 +574,7 @@ function normalizeSchemaDefinition(
 			const referenceField = relation.referenceField ?? "id";
 			const inferredField =
 				relation.field ?? `${singularize(sourceTableName)}Id`;
+			relation.field = inferredField;
 			const inferredType =
 				getLocalReferenceType(normalized, sourceTableName, referenceField) ??
 				relation.fkType ??
@@ -306,6 +602,8 @@ function normalizeSchemaDefinition(
 		}
 	}
 
+	normalizeManyToManyRelations(normalized);
+
 	return normalized;
 }
 
@@ -432,6 +730,117 @@ function resolveColumnReference(
 	};
 }
 
+function emitManyToManyRuntimeMetadata(definition: SchemaDefinition): string {
+	const tableEntries: string[] = [];
+
+	for (const [tableName, table] of Object.entries(definition.tables)) {
+		const relationEntries: string[] = [];
+
+		for (const [relationName, relation] of Object.entries(table.relations)) {
+			if (relation.relation !== "manyToMany") {
+				continue;
+			}
+
+			if (!relation.junctionTable) {
+				continue;
+			}
+
+			relationEntries.push(
+				`${quote(relationName)}: {
+				targetTable: ${quote(relation.targetTable)},
+				junctionTable: ${quote(relation.junctionTable)},
+				sourceField: ${quote(relation.sourceField ?? "")},
+				targetField: ${quote(relation.targetField ?? "")},
+			},`,
+			);
+		}
+
+		if (relationEntries.length === 0) {
+			continue;
+		}
+
+		tableEntries.push(
+			`${quote(tableName)}: {
+${relationEntries.map((entry) => `\t${entry}`).join("\n")}
+	},`,
+		);
+	}
+
+	if (tableEntries.length === 0) {
+		return "export const __appflareManyToMany = {} as const;\n";
+	}
+
+	return `export const __appflareManyToMany = {
+${tableEntries.map((entry) => `\t${entry}`).join("\n")}
+} as const;
+`;
+}
+
+function emitRuntimeRelationMetadata(definition: SchemaDefinition): string {
+	const tableEntries: string[] = [];
+
+	for (const [tableName, table] of Object.entries(definition.tables)) {
+		const relationEntries: string[] = [];
+
+		for (const [relationName, relation] of Object.entries(table.relations)) {
+			if (relation.relation === "one") {
+				relationEntries.push(
+					`${quote(relationName)}: {
+				kind: "one",
+				targetTable: ${quote(relation.targetTable)},
+				sourceField: ${quote(relation.field ?? "")},
+				referenceField: ${quote(relation.referenceField ?? "id")},
+			},`,
+				);
+				continue;
+			}
+
+			if (relation.relation === "many") {
+				relationEntries.push(
+					`${quote(relationName)}: {
+				kind: "many",
+				targetTable: ${quote(relation.targetTable)},
+				sourceField: ${quote(relation.field ?? "")},
+				referenceField: ${quote(relation.referenceField ?? "id")},
+			},`,
+				);
+				continue;
+			}
+
+			relationEntries.push(
+				`${quote(relationName)}: {
+			kind: "manyToMany",
+				targetTable: ${quote(relation.targetTable)},
+				junctionTable: ${quote(relation.junctionTable ?? "")},
+				sourceField: ${quote(relation.sourceField ?? "")},
+				targetField: ${quote(relation.targetField ?? "")},
+				referenceField: ${quote(relation.referenceField ?? "id")},
+				targetReferenceField: ${quote(relation.targetReferenceField ?? "id")},
+			},`,
+			);
+		}
+
+		if (relationEntries.length === 0) {
+			continue;
+		}
+
+		tableEntries.push(
+			`${quote(tableName)}: {
+${relationEntries.map((entry) => `\t${entry}`).join("\n")}
+	},`,
+		);
+	}
+
+	if (tableEntries.length === 0) {
+		return "export const __appflareRelations = {} as const;\n";
+	}
+
+	return `export const __appflareRelations = {
+${tableEntries.map((entry) => `\t${entry}`).join("\n")}
+} as const;
+`;
+}
+
 function emitDrizzleSchema(
 	definition: SchemaDefinition,
 	strategy: "camelToSnake",
@@ -536,8 +945,17 @@ function emitDrizzleSchema(
 				return relation.relation === "many";
 			},
 		) as Array<[string, ManyRelationDefinition]>;
+		const manyToManyRelations = Object.entries(table.relations).filter(
+			([, relation]) => {
+				return relation.relation === "manyToMany";
+			},
+		) as Array<[string, ManyToManyRelationDefinition]>;
 
-		if (oneRelations.length === 0 && manyRelations.length === 0) {
+		if (
+			oneRelations.length === 0 &&
+			manyRelations.length === 0 &&
+			manyToManyRelations.length === 0
+		) {
 			continue;
 		}
 
@@ -551,6 +969,14 @@ function emitDrizzleSchema(
 		for (const [relationName, relation] of manyRelations) {
 			relationLines.push(`\t${relationName}: many(${relation.targetTable}),`);
 		}
+		for (const [relationName, relation] of manyToManyRelations) {
+			if (!relation.junctionTable) {
+				throw new Error(
+					`manyToMany relation '${tableName}.${relationName}' is missing junctionTable after normalization.`,
+				);
+			}
+			relationLines.push(`\t${relationName}: many(${relation.junctionTable}),`);
+		}
 
 		relationBlocks.push(
 			`export const ${tableName}Relations = relations(${tableName}, ({ one, many }) => ({\n${relationLines.join("\n")}\n}));`,
@@ -564,6 +990,10 @@ ${buildExternalTableImportLines(externalTables)}
 ${tableBlocks.join("\n\n")}
 
 ${relationBlocks.join("\n\n")}
+
+${emitManyToManyRuntimeMetadata(definition)}
+
+${emitRuntimeRelationMetadata(definition)}
 `;
 }
 

package/cli/templates/handlers/generators/types/query-definitions/filter-and-where-types.ts

@@ -114,7 +114,7 @@ type RelationAggregateSelectionInput<TModel extends Record<string, unknown>> = {
 	_avg?: RelationAvgSelectionInput<TModel>;
 };
 
-type QueryWithRelationInput<TEntry> =
+type QueryNativeWithRelationInput<TEntry> =
 	| (Extract<TEntry, true> extends never ? never : true)
 	| (Extract<TEntry, Record<string, unknown>> extends infer TRelation
 			? TRelation extends Record<string, unknown>
@@ -122,24 +122,57 @@ type QueryWithRelationInput<TEntry> =
 						RelationAggregateSelectionInput<RelationModelFromConfig<TRelation>> & {
 						where?: WhereInput<RelationModelFromConfig<TRelation>>;
 						with?: TRelation extends { with?: infer TNestedWith }
-							? QueryWithInput<TNestedWith>
+							? QueryWithInputForTable<TableName, TNestedWith>
 							: never;
 				  }
 				: never
 			: never);
 
-type QueryWithInput<TWith> = TWith extends Record<string, unknown>
+type QueryManyToManyWithRelationInput<TTargetTable extends TableName> =
+	| true
+	| (Omit<NonNullable<TableFindManyArgs<TTargetTable>>, "where" | "with"> &
+			RelationAggregateSelectionInput<TableModel<TTargetTable>> & {
+				where?: WhereInput<TableModel<TTargetTable>>;
+				with?: QueryWithInputForTable<
+					TTargetTable,
+					NativeFindManyWith<TTargetTable>
+				>;
+		  });
+
+type QueryWithRelationInputForTable<
+	TSourceTable extends TableName,
+	TRelationName extends string,
+	TEntry,
+> = ManyToManyTargetTableName<TSourceTable, TRelationName> extends infer TTarget
+	? TTarget extends TableName
+		? QueryManyToManyWithRelationInput<TTarget>
+		: QueryNativeWithRelationInput<TEntry>
+	: QueryNativeWithRelationInput<TEntry>;
+
+type QueryWithInputForTable<
+	TSourceTable extends TableName,
+	TWith,
+> = TWith extends Record<string, unknown>
 	? {
-			[K in keyof TWith]?: QueryWithRelationInput<TWith[K]>;
+			[K in keyof TWith]?: QueryWithRelationInputForTable<
+				TSourceTable,
+				Extract<K, string>,
+				TWith[K]
+			>;
 	  }
 	: TWith;
 
+type QueryWithInput<TName extends TableName, TWith> = QueryWithInputForTable<
+	TName,
+	TWith
+>;
+
 export type QueryFindManyArgs<TName extends TableName> = Omit<
 	NonNullable<TableFindManyArgs<TName>>,
 	"where" | "with"
 > & {
 	where?: WhereInput<TableModel<TName>>;
-	with?: QueryWithInput<NativeFindManyWith<TName>>;
+	with?: QueryWithInput<TName, NativeFindManyWith<TName>>;
 };
 
 export type QueryFindFirstArgs<TName extends TableName> = Omit<
@@ -147,11 +180,59 @@ export type QueryFindFirstArgs<TName extends TableName> = Omit<
 	"where" | "with"
 > & {
 	where?: WhereInput<TableModel<TName>>;
-	with?: QueryWithInput<NativeFindFirstWith<TName>>;
+	with?: QueryWithInput<TName, NativeFindFirstWith<TName>>;
+};
+
+type SingularizeRelationName<TName extends string> =
+	TName extends \`\${infer TRoot\}ies\`
+		? \`\${TRoot\}y\`
+		: TName extends \`\${infer TRoot\}s\`
+			? TRoot
+			: TName;
+
+type RelationInsertItem<TTargetTable extends TableName> =
+	| TableModel<TTargetTable>
+	| TableInsertModel<TTargetTable>
+	| ("id" extends keyof TableModel<TTargetTable>
+			? TableModel<TTargetTable>["id"]
+			: never);
+
+type RelationInsertValue<
+	TSourceTable extends TableName,
+	TRelationName extends RuntimeRelationName<TSourceTable>,
+> = RuntimeRelationTargetTable<TSourceTable, TRelationName> extends infer TTargetTable
+	? TTargetTable extends TableName
+		? RuntimeRelationKind<TSourceTable, TRelationName> extends "one"
+			? RelationInsertItem<TTargetTable>
+			: RelationInsertItem<TTargetTable> | Array<RelationInsertItem<TTargetTable>>
+		: never
+	: never;
+
+type RelationInsertFields<TName extends TableName> = {
+	[TRelationName in RuntimeRelationName<TName>]?: RelationInsertValue<
+		TName,
+		TRelationName
+	>;
+};
+
+type RelationInsertIdAliasFields<TName extends TableName> = {
+	[TRelationName in RuntimeRelationName<TName> as \`\${TRelationName\}Id\`]?: RelationInsertValue<
+		TName,
+		TRelationName
+	>;
+} & {
+	[TRelationName in RuntimeRelationName<TName> as \`\${SingularizeRelationName<TRelationName>\}Id\`]?: RelationInsertValue<
+		TName,
+		TRelationName
+	>;
 };
 
+type QueryInsertValue<TName extends TableName> = TableInsertScalarModel<TName> &
+	RelationInsertFields<TName> &
+	RelationInsertIdAliasFields<TName>;
+
 export type QueryInsertArgs<TName extends TableName> = {
-	values: TableInsertModel<TName> | Array<TableInsertModel<TName>>;
+	values: QueryInsertValue<TName> | Array<QueryInsertValue<TName>>;
 };
 
 export type QueryUpdateArgs<TName extends TableName> = {

package/cli/templates/handlers/generators/types/query-definitions/query-api-types.ts

@@ -1,6 +1,6 @@
 export function generateQueryApiTypesSection(): string {
 	return `type AggregateWithInput<TName extends TableName> =
-	QueryWithInput<NativeFindManyWith<TName>>;
+	QueryWithInput<TName, NativeFindManyWith<TName>>;
 
 type NumericFieldKey<TName extends TableName> = NumericModelFieldKey<
 	TableModel<TName>