arkormx 0.2.2 → 0.2.3

package/dist/cli.mjs

@@ -26,6 +26,79 @@ var ArkormException = class extends Error {
 	}
 };
 
+//#endregion
+//#region src/database/ForeignKeyBuilder.ts
+/**
+* The ForeignKeyBuilder class provides a fluent interface for defining 
+* foreign key constraints in a migration. It allows you to specify 
+* the referenced table and column, as well as actions to take on 
+* delete and aliases for the relation.
+*
+* @author Legacy (3m1n3nc3)
+* @since 0.2.2
+*/
+var ForeignKeyBuilder = class {
+	foreignKey;
+	constructor(foreignKey) {
+		this.foreignKey = foreignKey;
+	}
+	/**
+	* Defines the referenced table and column for this foreign key constraint.
+	* 
+	* @param table 
+	* @param column 
+	* @returns 
+	*/
+	references(table, column) {
+		this.foreignKey.referencesTable = table;
+		this.foreignKey.referencesColumn = column;
+		return this;
+	}
+	/**
+	* Defines the action to take when a referenced record is deleted, such 
+	* as "CASCADE", "SET NULL", or "RESTRICT".
+	* 
+	* @param action 
+	* @returns 
+	*/
+	onDelete(action) {
+		this.foreignKey.onDelete = action;
+		return this;
+	}
+	/**
+	* Defines an alias for the relation represented by this foreign key, which 
+	* can be used in the ORM for more intuitive access to related models.
+	* 
+	* @param name 
+	* @returns 
+	*/
+	alias(name) {
+		this.foreignKey.relationAlias = name;
+		return this;
+	}
+	/**
+	* Defines an alias for the inverse relation represented by this foreign key.
+	* 
+	* @param name 
+	* @returns 
+	*/
+	inverseAlias(name) {
+		this.foreignKey.inverseRelationAlias = name;
+		return this;
+	}
+	/**
+	* Defines an alias for the foreign key field itself, which can be 
+	* used in the ORM for more intuitive access to the foreign key value.
+	* 
+	* @param fieldName 
+	* @returns 
+	*/
+	as(fieldName) {
+		this.foreignKey.fieldAlias = fieldName;
+		return this;
+	}
+};
+
 //#endregion
 //#region src/database/TableBuilder.ts
 /**
@@ -39,6 +112,7 @@ var TableBuilder = class {
 	columns = [];
 	dropColumnNames = [];
 	indexes = [];
+	foreignKeys = [];
 	latestColumnName;
 	/**
 	* Defines a primary key column in the table.
@@ -281,6 +355,32 @@ var TableBuilder = class {
 		return this;
 	}
 	/**
+	* Defines a foreign key relation for an existing column.
+	*
+	* @param column The local foreign key column name.
+	* @returns A fluent foreign key builder.
+	*/
+	foreignKey(column) {
+		const entry = {
+			column,
+			referencesTable: "",
+			referencesColumn: "id"
+		};
+		this.foreignKeys.push(entry);
+		return new ForeignKeyBuilder(entry);
+	}
+	/**
+	* Defines a foreign key relation for a column, using a 
+	* conventional naming pattern.
+	* 
+	* @param column 
+	* @returns 
+	*/
+	foreign(column) {
+		const columnName = this.resolveColumn(column).name;
+		return this.foreignKey(columnName + (column ? "" : "Id"));
+	}
+	/**
 	* Returns a deep copy of the defined columns for the table.
 	* 
 	* @returns 
@@ -308,6 +408,14 @@ var TableBuilder = class {
 		}));
 	}
 	/**
+	* Returns a deep copy of the defined foreign keys for the table.
+	*
+	* @returns
+	*/
+	getForeignKeys() {
+		return this.foreignKeys.map((foreignKey) => ({ ...foreignKey }));
+	}
+	/**
 	* Defines a column in the table with the given name.
 	* 
 	* @param name      The name of the column.
@@ -370,7 +478,8 @@ var SchemaBuilder = class {
 			type: "createTable",
 			table,
 			columns: builder.getColumns(),
-			indexes: builder.getIndexes()
+			indexes: builder.getIndexes(),
+			foreignKeys: builder.getForeignKeys()
 		});
 		return this;
 	}
@@ -389,7 +498,8 @@ var SchemaBuilder = class {
 			table,
 			addColumns: builder.getColumns(),
 			dropColumns: builder.getDropColumns(),
-			addIndexes: builder.getIndexes()
+			addIndexes: builder.getIndexes(),
+			addForeignKeys: builder.getForeignKeys()
 		});
 		return this;
 	}
@@ -419,7 +529,8 @@ var SchemaBuilder = class {
 				indexes: operation.indexes.map((index) => ({
 					...index,
 					columns: [...index.columns]
-				}))
+				})),
+				foreignKeys: operation.foreignKeys.map((foreignKey) => ({ ...foreignKey }))
 			};
 			if (operation.type === "alterTable") return {
 				...operation,
@@ -428,7 +539,8 @@ var SchemaBuilder = class {
 				addIndexes: operation.addIndexes.map((index) => ({
 					...index,
 					columns: [...index.columns]
-				}))
+				})),
+				addForeignKeys: operation.addForeignKeys.map((foreignKey) => ({ ...foreignKey }))
 			};
 			return { ...operation };
 		});
@@ -513,13 +625,139 @@ const buildFieldLine = (column) => {
 /**
 * Build a Prisma model-level @@index definition line.
 * 
-* @param index 
+* @param index     The schema index definition to convert to a Prisma \@\@index line.
 * @returns 
 */
 const buildIndexLine = (index) => {
 	return `  @@index([${index.columns.join(", ")}]${typeof index.name === "string" && index.name.trim().length > 0 ? `, name: "${index.name.replace(/"/g, "\\\"")}"` : ""})`;
 };
 /**
+* Derive a relation field name from a foreign key column name by applying 
+* common conventions, such as removing "Id" suffixes and converting to camelCase.
+* 
+* @param columnName    The name of the foreign key column.
+* @returns             The derived relation field name.
+*/
+const deriveRelationFieldName = (columnName) => {
+	const trimmed = columnName.trim();
+	if (!trimmed) return "relation";
+	if (trimmed.endsWith("Id") && trimmed.length > 2) {
+		const root = trimmed.slice(0, -2);
+		return `${root.charAt(0).toLowerCase()}${root.slice(1)}`;
+	}
+	if (trimmed.endsWith("_id") && trimmed.length > 3) return trimmed.slice(0, -3).replace(/_([a-zA-Z0-9])/g, (_, letter) => letter.toUpperCase());
+	return `${trimmed.charAt(0).toLowerCase()}${trimmed.slice(1)}`;
+};
+const pascalWords = (value) => {
+	return value.match(/[A-Z][a-z0-9]*/g) ?? [value];
+};
+/**
+* Derive a relation name for the inverse side of a relation based on the 
+* source and target model names, using an explicit alias if provided or a 
+* convention of combining the target model name with the last segment of 
+* the source model name.
+* 
+* @param sourceModelName    The name of the source model in the relation.
+* @param targetModelName    The name of the target model in the relation.
+* @param explicitAlias      An optional explicit alias for the inverse relation.
+* @returns                  The derived or explicit inverse relation alias.
+*/
+const deriveInverseRelationAlias = (sourceModelName, targetModelName, explicitAlias) => {
+	if (explicitAlias && explicitAlias.trim().length > 0) return explicitAlias.trim();
+	const sourceWords = pascalWords(sourceModelName);
+	return `${sourceWords[sourceWords.length - 1] ?? sourceModelName}${targetModelName}`;
+};
+const deriveCollectionFieldName = (modelName) => {
+	if (!modelName) return "items";
+	const camel = `${modelName.charAt(0).toLowerCase()}${modelName.slice(1)}`;
+	if (camel.endsWith("s")) return `${camel}es`;
+	return `${camel}s`;
+};
+/** 
+* Format a SchemaForeignKeyAction value as a Prisma onDelete action string.
+* 
+* @param action    The foreign key action to format.
+* @returns         The corresponding Prisma onDelete action string.
+*/
+const formatRelationAction = (action) => {
+	if (action === "cascade") return "Cascade";
+	if (action === "restrict") return "Restrict";
+	if (action === "setNull") return "SetNull";
+	if (action === "setDefault") return "SetDefault";
+	return "NoAction";
+};
+/**
+* Build a Prisma relation field line based on a SchemaForeignKey 
+* definition, including relation name and onDelete action.
+* 
+* @param foreignKey    The foreign key definition to convert to a relation line.
+* @returns             The corresponding Prisma schema line for the relation field.
+*/
+const buildRelationLine = (foreignKey) => {
+	if (!foreignKey.referencesTable.trim()) throw new ArkormException(`Foreign key [${foreignKey.column}] must define a referenced table.`);
+	if (!foreignKey.referencesColumn.trim()) throw new ArkormException(`Foreign key [${foreignKey.column}] must define a referenced column.`);
+	const fieldName = foreignKey.fieldAlias?.trim() || deriveRelationFieldName(foreignKey.column);
+	const targetModel = toModelName(foreignKey.referencesTable);
+	const relationName = foreignKey.relationAlias?.trim();
+	const relationPrefix = relationName ? `@relation("${relationName.replace(/"/g, "\\\"")}", ` : "@relation(";
+	const onDelete = foreignKey.onDelete ? `, onDelete: ${formatRelationAction(foreignKey.onDelete)}` : "";
+	return `  ${fieldName} ${targetModel} ${relationPrefix}fields: [${foreignKey.column}], references: [${foreignKey.referencesColumn}]${onDelete})`;
+};
+/**
+* Build a Prisma relation field line for the inverse side of a relation, based 
+* on the source and target model names and the foreign key definition, using 
+* naming conventions and any explicit inverse alias provided.
+* 
+* @param sourceModelName   The name of the source model in the relation.
+* @param targetModelName   The name of the target model in the relation.
+* @param foreignKey        The foreign key definition for the relation.
+* @returns                 The Prisma schema line for the inverse relation field.
+*/
+const buildInverseRelationLine = (sourceModelName, targetModelName, foreignKey) => {
+	return `  ${deriveCollectionFieldName(sourceModelName)} ${sourceModelName}[] @relation("${deriveInverseRelationAlias(sourceModelName, targetModelName, foreignKey.inverseRelationAlias).replace(/"/g, "\\\"")}")`;
+};
+/**
+* Inject a line into the body of a Prisma model block if it does not already 
+* exist, using a provided existence check function to determine if the line 
+* is already present.
+* 
+* @param bodyLines The lines of the model block body to modify.
+* @param line      The line to inject if it does not already exist.
+* @param exists    A function that checks if a given line already exists in the body.
+* @returns 
+*/
+const injectLineIntoModelBody = (bodyLines, line, exists) => {
+	if (bodyLines.some(exists)) return bodyLines;
+	const insertIndex = Math.max(1, bodyLines.length - 1);
+	bodyLines.splice(insertIndex, 0, line);
+	return bodyLines;
+};
+/**
+* Apply inverse relation definitions to a Prisma schema string based on the 
+* foreign keys defined in a create or alter table operation, ensuring that 
+* related models have corresponding relation fields for bi-directional navigation.
+* 
+* @param schema The Prisma schema string to modify.
+* @param sourceModelName The name of the source model in the relation.
+* @param foreignKeys An array of foreign key definitions to process.
+* @returns The updated Prisma schema string with inverse relations applied.
+*/
+const applyInverseRelations = (schema, sourceModelName, foreignKeys) => {
+	let nextSchema = schema;
+	for (const foreignKey of foreignKeys) {
+		const targetModel = findModelBlock(nextSchema, foreignKey.referencesTable);
+		if (!targetModel) continue;
+		const inverseLine = buildInverseRelationLine(sourceModelName, targetModel.modelName, foreignKey);
+		const targetBodyLines = targetModel.block.split("\n");
+		const fieldName = deriveCollectionFieldName(sourceModelName);
+		const fieldRegex = new RegExp(`^\\s*${escapeRegex(fieldName)}\\s+`);
+		injectLineIntoModelBody(targetBodyLines, inverseLine, (line) => fieldRegex.test(line));
+		const updatedTarget = targetBodyLines.join("\n");
+		nextSchema = `${nextSchema.slice(0, targetModel.start)}${updatedTarget}${nextSchema.slice(targetModel.end)}`;
+	}
+	return nextSchema;
+};
+/**
 * Build a Prisma model block string based on a SchemaTableCreateOperation, including 
 * all fields and any necessary mapping.
 * 
@@ -530,12 +768,14 @@ const buildModelBlock = (operation) => {
 	const modelName = toModelName(operation.table);
 	const mapped = operation.table !== modelName.toLowerCase();
 	const fields = operation.columns.map(buildFieldLine);
+	const relations = (operation.foreignKeys ?? []).map(buildRelationLine);
 	const metadata = [...(operation.indexes ?? []).map(buildIndexLine), ...mapped ? [`  @@map("${str(operation.table).snake()}")`] : []];
 	return `model ${modelName} {\n${(metadata.length > 0 ? [
 		...fields,
+		...relations,
 		"",
 		...metadata
-	] : fields).join("\n")}\n}`;
+	] : [...fields, ...relations]).join("\n")}\n}`;
 };
 /**
 * Find the Prisma model block in a schema string that corresponds to a given 
@@ -585,7 +825,7 @@ const findModelBlock = (schema, table) => {
 const applyCreateTableOperation = (schema, operation) => {
 	if (findModelBlock(schema, operation.table)) throw new ArkormException(`Prisma model for table [${operation.table}] already exists.`);
 	const block = buildModelBlock(operation);
-	return `${schema.trimEnd()}\n\n${block}\n`;
+	return applyInverseRelations(`${schema.trimEnd()}\n\n${block}\n`, toModelName(operation.table), operation.foreignKeys ?? []);
 };
 /**
 * Apply an alter table operation to a Prisma schema string, modifying the model 
@@ -622,8 +862,13 @@ const applyAlterTableOperation = (schema, operation) => {
 		const insertIndex = Math.max(1, bodyLines.length - 1);
 		bodyLines.splice(insertIndex, 0, indexLine);
 	});
+	for (const foreignKey of operation.addForeignKeys ?? []) {
+		const relationLine = buildRelationLine(foreignKey);
+		const relationRegex = new RegExp(`^\\s*${escapeRegex(foreignKey.fieldAlias?.trim() || deriveRelationFieldName(foreignKey.column))}\\s+`);
+		injectLineIntoModelBody(bodyLines, relationLine, (line) => relationRegex.test(line));
+	}
 	block = bodyLines.join("\n");
-	return `${schema.slice(0, model.start)}${block}${schema.slice(model.end)}`;
+	return applyInverseRelations(`${schema.slice(0, model.start)}${block}${schema.slice(model.end)}`, model.modelName, operation.addForeignKeys ?? []);
 };
 /**
 * Apply a drop table operation to a Prisma schema string, removing the model block