appflare 0.2.14 → 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,
@@ -121,6 +122,8 @@ function ensureInferredReferenceColumn(
 		fkType?: ColumnType;
 		sqlName?: string;
 		notNull?: boolean;
+		onDelete?: OneRelationDefinition["onDelete"];
+		onUpdate?: OneRelationDefinition["onUpdate"];
 	},
 	inferredType: ColumnType,
 ): void {
@@ -138,7 +141,17 @@ function ensureInferredReferenceColumn(
 
 		table.columns[columnName] = {
 			...existing,
-			references: { table: referenceTable, column: referenceField },
+			notNull:
+				existing.notNull ??
+				(existing.nullable === true ? false : options.notNull),
+			nullable:
+				existing.nullable ?? (options.notNull === false ? true : undefined),
+			references: {
+				table: referenceTable,
+				column: referenceField,
+				onDelete: existing.references?.onDelete ?? options.onDelete,
+				onUpdate: existing.references?.onUpdate ?? options.onUpdate,
+			},
 		};
 		return;
 	}
@@ -148,16 +161,360 @@ function ensureInferredReferenceColumn(
 		type: options.fkType ?? inferredType,
 		sqlName: options.sqlName,
 		notNull: options.notNull ?? true,
+		nullable: options.notNull === false ? true : undefined,
 		references: {
 			table: referenceTable,
 			column: referenceField,
+			onDelete: options.onDelete,
+			onUpdate: options.onUpdate,
 		},
 	};
 }
 
+function resolveNotNullFromNullableFlags(
+	fieldPath: string,
+	flags: { notNull?: boolean; nullable?: boolean },
+	defaultNotNull: boolean,
+): boolean {
+	if (flags.notNull === true && flags.nullable === true) {
+		throw new Error(
+			`Invalid nullable configuration on '${fieldPath}': cannot set both notNull and nullable to true.`,
+		);
+	}
+
+	if (flags.notNull === true) {
+		return true;
+	}
+
+	if (flags.nullable === true) {
+		return false;
+	}
+
+	if (flags.notNull === false) {
+		return false;
+	}
+
+	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)) {
+			if (column.notNull === true && column.nullable === true) {
+				throw new Error(
+					`Invalid nullable configuration on '${tableName}.${columnName}': cannot set both notNull and nullable to true.`,
+				);
+			}
+		}
+
+		for (const [relationName, relation] of Object.entries(table.relations)) {
+			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.`,
+				);
+			}
+		}
+	}
+}
+
 function normalizeSchemaDefinition(
 	definition: SchemaDefinition,
 ): SchemaDefinition {
+	validateNullableFlags(definition);
 	const normalized = cloneSchemaDefinition(definition);
 
 	for (const [tableName, table] of Object.entries(normalized.tables)) {
@@ -188,7 +545,13 @@ function normalizeSchemaDefinition(
 				{
 					fkType: relation.fkType,
 					sqlName: relation.sqlName,
-					notNull: relation.notNull,
+					notNull: resolveNotNullFromNullableFlags(
+						`${tableName}.${relationName}`,
+						relation,
+						true,
+					),
+					onDelete: relation.onDelete,
+					onUpdate: relation.onUpdate,
 				},
 				inferredType,
 			);
@@ -211,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 ??
@@ -225,18 +589,27 @@ function normalizeSchemaDefinition(
 				{
 					fkType: relation.fkType,
 					sqlName: relation.sqlName,
-					notNull: relation.notNull,
+					notNull: resolveNotNullFromNullableFlags(
+						`${sourceTableName}.${relation.targetTable}`,
+						relation,
+						true,
+					),
+					onDelete: relation.onDelete,
+					onUpdate: relation.onUpdate,
 				},
 				inferredType,
 			);
 		}
 	}
 
+	normalizeManyToManyRelations(normalized);
+
 	return normalized;
 }
 
 function isOptionalInsertColumn(column: ColumnDefinition): boolean {
 	return (
+		column.primaryKey === true ||
 		column.notNull !== true ||
 		column.autoIncrement === true ||
 		column.sqlDefault !== undefined ||
@@ -357,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",
@@ -388,6 +872,10 @@ function emitDrizzleSchema(
 		for (const [fieldName, column] of Object.entries(table.columns)) {
 			let expr = drizzleBaseColumn(fieldName, column, strategy);
 
+			if (column.uuidPrimaryKey) {
+				expr += ".$defaultFn(() => crypto.randomUUID())";
+			}
+
 			if (column.primaryKey) {
 				expr += column.autoIncrement
 					? ".primaryKey({ autoIncrement: true })"
@@ -402,7 +890,18 @@ function emitDrizzleSchema(
 
 			const reference = resolveColumnReference(fieldName, column, table);
 			if (reference) {
-				expr += `.references(() => ${reference.tableName}.${reference.fieldName})`;
+				if (column.references?.onDelete || column.references?.onUpdate) {
+					const actions: string[] = [];
+					if (column.references.onDelete) {
+						actions.push(`onDelete: ${quote(column.references.onDelete)}`);
+					}
+					if (column.references.onUpdate) {
+						actions.push(`onUpdate: ${quote(column.references.onUpdate)}`);
+					}
+					expr += `.references(() => ${reference.tableName}.${reference.fieldName}, { ${actions.join(", ")} })`;
+				} else {
+					expr += `.references(() => ${reference.tableName}.${reference.fieldName})`;
+				}
 			}
 
 			if (column.unique) {
@@ -446,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;
 		}
 
@@ -461,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}));`,
@@ -474,12 +990,17 @@ ${buildExternalTableImportLines(externalTables)}
 ${tableBlocks.join("\n\n")}
 
 ${relationBlocks.join("\n\n")}
+
+${emitManyToManyRuntimeMetadata(definition)}
+
+${emitRuntimeRelationMetadata(definition)}
 `;
 }
 
 function zodSchemaExpression(
 	column: ColumnDefinition,
 	optional: boolean,
+	nullable: boolean,
 ): string {
 	let expr = "z.unknown()";
 	if (column.type === "int") {
@@ -499,6 +1020,10 @@ function zodSchemaExpression(
 		expr += ".optional()";
 	}
 
+	if (nullable) {
+		expr += ".nullable()";
+	}
+
 	return expr;
 }
 
@@ -512,10 +1037,10 @@ function emitZodSchemas(definition: SchemaDefinition): string {
 
 		for (const [fieldName, column] of Object.entries(table.columns)) {
 			insertLines.push(
-				`\t${fieldName}: ${zodSchemaExpression(column, isOptionalInsertColumn(column))},`,
+				`\t${fieldName}: ${zodSchemaExpression(column, isOptionalInsertColumn(column), isNullableSelectColumn(column))},`,
 			);
 			selectLines.push(
-				`\t${fieldName}: ${zodSchemaExpression(column, isNullableSelectColumn(column))},`,
+				`\t${fieldName}: ${zodSchemaExpression(column, isNullableSelectColumn(column), isNullableSelectColumn(column))},`,
 			);
 		}
 
@@ -558,11 +1083,12 @@ function emitTypes(definition: SchemaDefinition): string {
 
 		for (const [fieldName, column] of Object.entries(table.columns)) {
 			const tsType = toTypeScriptType(column);
+			const nullableSuffix = isNullableSelectColumn(column) ? " | null" : "";
 			selectFields.push(
-				`\t${fieldName}${isNullableSelectColumn(column) ? "?" : ""}: ${tsType};`,
+				`\t${fieldName}${isNullableSelectColumn(column) ? "?" : ""}: ${tsType}${nullableSuffix};`,
 			);
 			insertFields.push(
-				`\t${fieldName}${isOptionalInsertColumn(column) ? "?" : ""}: ${tsType};`,
+				`\t${fieldName}${isOptionalInsertColumn(column) ? "?" : ""}: ${tsType}${nullableSuffix};`,
 			);
 		}