appflare 0.2.15 → 0.2.17

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/dashboard/builders/table-routes/fragments.ts

@@ -52,12 +52,15 @@ export function buildColumnHeaders(
 		.join("");
 }
 
-export function buildRowCells(columns: string[]): string {
+export function buildRowCells(columns: string[], primaryKey?: string): string {
 	return columns
-		.map(
-			(column) =>
-				`<td><div class="truncate max-w-[200px] text-sm" title="\${String((row as any).${column} ?? '')}">\${String((row as any).${column} ?? '')}</div></td>`,
-		)
+		.map((column) => {
+			if (primaryKey && column === primaryKey) {
+				return `<td><button type="button" class="truncate max-w-[200px] text-sm font-mono text-xs opacity-70 hover:opacity-100 cursor-copy text-left" title="Click to copy: \${String((row as any).${column} ?? '')}" data-copy-value="\${String((row as any).${column} ?? '')}" onclick="navigator.clipboard?.writeText(this.dataset.copyValue || '')">\${String((row as any).${column} ?? '')}</button></td>`;
+			}
+
+			return `<td><div class="truncate max-w-[200px] text-sm" title="\${String((row as any).${column} ?? '')}">\${String((row as any).${column} ?? '')}</div></td>`;
+		})
 		.join("");
 }
 

package/cli/templates/dashboard/builders/table-routes/table/index.ts

@@ -31,7 +31,7 @@ export function buildTableRoute(table: DiscoveredTable): string {
 	);
 	const searchConditions = buildSearchConditions(table);
 	const headers = buildColumnHeaders(table, columns);
-	const rowCells = buildRowCells(columns);
+	const rowCells = buildRowCells(columns, primaryKey);
 	const createInputs = createColumns
 		.map((columnName) => buildFieldInput(table, columnName, "create"))
 		.join("");

package/cli/templates/dashboard/builders/table-routes/users/html/table.ts

@@ -55,7 +55,7 @@ export function buildUsersTableHtml(): string {
 \t\t\t\t\t\t<tbody>
 \t\t\t\t\t\t\t\${data.map((row) => html\`
 \t\t\t\t\t\t\t\t<tr class="hover:bg-base-200/30 transition-colors">
-\t\t\t\t\t\t\t\t\t<td><div class="truncate max-w-[220px] text-sm font-mono text-xs opacity-60" title="\${String((row as any).id ?? '')}">\${String((row as any).id ?? '')}</div></td>
+\t\t\t\t\t\t\t\t\t<td><button type="button" class="truncate max-w-[220px] text-sm font-mono text-xs opacity-70 hover:opacity-100 cursor-copy text-left" title="Click to copy: \${String((row as any).id ?? '')}" data-copy-value="\${String((row as any).id ?? '')}" onclick="navigator.clipboard?.writeText(this.dataset.copyValue || '')">\${String((row as any).id ?? '')}</button></td>
 \t\t\t\t\t\t\t\t\t<td><div class="truncate max-w-[220px] text-sm" title="\${String((row as any).name ?? '')}">\${String((row as any).name ?? '')}</div></td>
 \t\t\t\t\t\t\t\t\t<td><div class="truncate max-w-[260px] text-sm" title="\${String((row as any).email ?? '')}">\${String((row as any).email ?? '')}</div></td>
 \t\t\t\t\t\t\t\t\t<td><span class="badge badge-sm \${String((row as any).role ?? '') === 'admin' ? 'badge-primary' : 'badge-ghost'}">\${String((row as any).role ?? '')}</span></td>
@@ -123,5 +123,6 @@ ${buildDeleteUserModal()}
 \t\t\t\t</div>
 \t\t\t\t${paginationHtml}
 \t\t\t</div>
-\t\t\`;`;
+\t\t\`;
+`;
 }