arkormx 0.2.1 → 0.2.3

package/dist/index.cjs

@@ -117,6 +117,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
 /**
@@ -130,6 +203,7 @@ var TableBuilder = class {
 	columns = [];
 	dropColumnNames = [];
 	indexes = [];
+	foreignKeys = [];
 	latestColumnName;
 	/**
 	* Defines a primary key column in the table.
@@ -194,7 +268,7 @@ var TableBuilder = class {
 	* 
 	* @param name      The name of the integer column.
 	* @param options   Additional options for the integer column.
-	* @returns 
+	* @returns         The current TableBuilder instance for chaining.
 	*/
 	integer(name, options = {}) {
 		return this.column(name, "integer", options);
@@ -204,7 +278,7 @@ var TableBuilder = class {
 	* 
 	* @param name      The name of the big integer column.
 	* @param options   Additional options for the big integer column.
-	* @returns 
+	* @returns         The current TableBuilder instance for chaining.
 	*/
 	bigInteger(name, options = {}) {
 		return this.column(name, "bigInteger", options);
@@ -214,17 +288,29 @@ var TableBuilder = class {
 	* 
 	* @param name      The name of the float column.
 	* @param options   Additional options for the float column.
-	* @returns 
+	* @returns         The current TableBuilder instance for chaining.
 	*/
 	float(name, options = {}) {
 		return this.column(name, "float", options);
 	}
 	/**
+	* Marks a column as unique in the table.
+	* 
+	* @param name Optional explicit column name. 
+	* When omitted, applies to the latest defined column.
+	* @returns The current TableBuilder instance for chaining.
+	*/
+	unique(name) {
+		const column = this.resolveColumn(name);
+		column.unique = true;
+		return this;
+	}
+	/**
 	* Defines a boolean column in the table.
 	* 
 	* @param name      The name of the boolean column. 
 	* @param options   Additional options for the boolean column.
-	* @returns 
+	* @returns         The current TableBuilder instance for chaining.
 	*/
 	boolean(name, options = {}) {
 		return this.column(name, "boolean", options);
@@ -360,6 +446,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 
@@ -387,6 +499,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.
@@ -449,7 +569,8 @@ var SchemaBuilder = class {
 			type: "createTable",
 			table,
 			columns: builder.getColumns(),
-			indexes: builder.getIndexes()
+			indexes: builder.getIndexes(),
+			foreignKeys: builder.getForeignKeys()
 		});
 		return this;
 	}
@@ -468,7 +589,8 @@ var SchemaBuilder = class {
 			table,
 			addColumns: builder.getColumns(),
 			dropColumns: builder.getDropColumns(),
-			addIndexes: builder.getIndexes()
+			addIndexes: builder.getIndexes(),
+			addForeignKeys: builder.getForeignKeys()
 		});
 		return this;
 	}
@@ -498,7 +620,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,
@@ -507,7 +630,8 @@ var SchemaBuilder = class {
 				addIndexes: operation.addIndexes.map((index) => ({
 					...index,
 					columns: [...index.columns]
-				}))
+				})),
+				addForeignKeys: operation.addForeignKeys.map((foreignKey) => ({ ...foreignKey }))
 			};
 			return { ...operation };
 		});
@@ -592,13 +716,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.
 * 
@@ -609,12 +859,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("${(0, _h3ravel_support.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 
@@ -664,7 +916,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 
@@ -701,8 +953,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
@@ -4862,6 +5119,7 @@ var Model = class Model {
 exports.ArkormCollection = ArkormCollection;
 exports.ArkormException = ArkormException;
 exports.CliApp = CliApp;
+exports.ForeignKeyBuilder = ForeignKeyBuilder;
 exports.InitCommand = InitCommand;
 exports.InlineFactory = InlineFactory;
 exports.LengthAwarePaginator = LengthAwarePaginator;
@@ -4892,18 +5150,24 @@ exports.applyMigrationToPrismaSchema = applyMigrationToPrismaSchema;
 exports.applyOperationsToPrismaSchema = applyOperationsToPrismaSchema;
 exports.buildFieldLine = buildFieldLine;
 exports.buildIndexLine = buildIndexLine;
+exports.buildInverseRelationLine = buildInverseRelationLine;
 exports.buildMigrationSource = buildMigrationSource;
 exports.buildModelBlock = buildModelBlock;
+exports.buildRelationLine = buildRelationLine;
 exports.configureArkormRuntime = configureArkormRuntime;
 exports.createMigrationTimestamp = createMigrationTimestamp;
 exports.createPrismaAdapter = createPrismaAdapter;
 exports.createPrismaDelegateMap = createPrismaDelegateMap;
 exports.defineConfig = defineConfig;
 exports.defineFactory = defineFactory;
+exports.deriveCollectionFieldName = deriveCollectionFieldName;
+exports.deriveInverseRelationAlias = deriveInverseRelationAlias;
+exports.deriveRelationFieldName = deriveRelationFieldName;
 exports.ensureArkormConfigLoading = ensureArkormConfigLoading;
 exports.escapeRegex = escapeRegex;
 exports.findModelBlock = findModelBlock;
 exports.formatDefaultValue = formatDefaultValue;
+exports.formatRelationAction = formatRelationAction;
 exports.generateMigrationFile = generateMigrationFile;
 exports.getDefaultStubsPath = getDefaultStubsPath;
 exports.getMigrationPlan = getMigrationPlan;

package/dist/index.d.cts

@@ -27,11 +27,22 @@ interface SchemaIndex {
   columns: string[];
   name?: string;
 }
+type SchemaForeignKeyAction = 'cascade' | 'restrict' | 'setNull' | 'noAction' | 'setDefault';
+interface SchemaForeignKey {
+  column: string;
+  referencesTable: string;
+  referencesColumn: string;
+  onDelete?: SchemaForeignKeyAction;
+  relationAlias?: string;
+  inverseRelationAlias?: string;
+  fieldAlias?: string;
+}
 interface SchemaTableCreateOperation {
   type: 'createTable';
   table: string;
   columns: SchemaColumn[];
   indexes: SchemaIndex[];
+  foreignKeys: SchemaForeignKey[];
 }
 interface SchemaTableAlterOperation {
   type: 'alterTable';
@@ -39,6 +50,7 @@ interface SchemaTableAlterOperation {
   addColumns: SchemaColumn[];
   dropColumns: string[];
   addIndexes: SchemaIndex[];
+  addForeignKeys: SchemaForeignKey[];
 }
 interface SchemaTableDropOperation {
   type: 'dropTable';
@@ -2286,6 +2298,60 @@ declare class SeedCommand extends Command<CliApp> {
   private loadSeederClassesFromFile;
 }
 //#endregion
+//#region src/database/ForeignKeyBuilder.d.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
+ */
+declare class ForeignKeyBuilder {
+  private readonly foreignKey;
+  constructor(foreignKey: SchemaForeignKey);
+  /**
+   * Defines the referenced table and column for this foreign key constraint.
+   *
+   * @param table
+   * @param column
+   * @returns
+   */
+  references(table: string, column: string): this;
+  /**
+   * Defines the action to take when a referenced record is deleted, such
+   * as "CASCADE", "SET NULL", or "RESTRICT".
+   *
+   * @param action
+   * @returns
+   */
+  onDelete(action: SchemaForeignKeyAction): 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: string): this;
+  /**
+   * Defines an alias for the inverse relation represented by this foreign key.
+   *
+   * @param name
+   * @returns
+   */
+  inverseAlias(name: string): 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: string): this;
+}
+//#endregion
 //#region src/database/TableBuilder.d.ts
 /**
  * The TableBuilder class provides a fluent interface for defining
@@ -2298,6 +2364,7 @@ declare class TableBuilder {
   private readonly columns;
   private readonly dropColumnNames;
   private readonly indexes;
+  private readonly foreignKeys;
   private latestColumnName;
   /**
    * Defines a primary key column in the table.
@@ -2351,7 +2418,7 @@ declare class TableBuilder {
    *
    * @param name      The name of the integer column.
    * @param options   Additional options for the integer column.
-   * @returns
+   * @returns         The current TableBuilder instance for chaining.
    */
   integer(name: string, options?: Partial<SchemaColumn>): this;
   /**
@@ -2359,7 +2426,7 @@ declare class TableBuilder {
    *
    * @param name      The name of the big integer column.
    * @param options   Additional options for the big integer column.
-   * @returns
+   * @returns         The current TableBuilder instance for chaining.
    */
   bigInteger(name: string, options?: Partial<SchemaColumn>): this;
   /**
@@ -2367,15 +2434,23 @@ declare class TableBuilder {
    *
    * @param name      The name of the float column.
    * @param options   Additional options for the float column.
-   * @returns
+   * @returns         The current TableBuilder instance for chaining.
    */
   float(name: string, options?: Partial<SchemaColumn>): this;
+  /**
+   * Marks a column as unique in the table.
+   *
+   * @param name Optional explicit column name.
+   * When omitted, applies to the latest defined column.
+   * @returns The current TableBuilder instance for chaining.
+   */
+  unique(name?: string): this;
   /**
    * Defines a boolean column in the table.
    *
    * @param name      The name of the boolean column.
    * @param options   Additional options for the boolean column.
-   * @returns
+   * @returns         The current TableBuilder instance for chaining.
    */
   boolean(name: string, options?: Partial<SchemaColumn>): this;
   /**
@@ -2467,6 +2542,21 @@ declare class TableBuilder {
    * @returns       The current TableBuilder instance for chaining.
    */
   index(columns?: string | string[], name?: string): 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: string): ForeignKeyBuilder;
+  /**
+   * Defines a foreign key relation for a column, using a
+   * conventional naming pattern.
+   *
+   * @param column
+   * @returns
+   */
+  foreign(column?: string): ForeignKeyBuilder;
   /**
    * Returns a deep copy of the defined columns for the table.
    *
@@ -2485,6 +2575,12 @@ declare class TableBuilder {
    * @returns
    */
   getIndexes(): SchemaIndex[];
+  /**
+   * Returns a deep copy of the defined foreign keys for the table.
+   *
+   * @returns
+   */
+  getForeignKeys(): SchemaForeignKey[];
   /**
    * Defines a column in the table with the given name.
    *
@@ -2675,10 +2771,57 @@ declare const buildFieldLine: (column: SchemaColumn) => string;
 /**
  * Build a Prisma model-level @@index definition line.
  *
- * @param index
+ * @param index     The schema index definition to convert to a Prisma \@\@index line.
  * @returns
  */
 declare const buildIndexLine: (index: SchemaIndex) => string;
+/**
+ * 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.
+ */
+declare const deriveRelationFieldName: (columnName: string) => string;
+/**
+ * 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.
+ */
+declare const deriveInverseRelationAlias: (sourceModelName: string, targetModelName: string, explicitAlias?: string) => string;
+declare const deriveCollectionFieldName: (modelName: string) => string;
+/**
+ * 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.
+ */
+declare const formatRelationAction: (action: SchemaForeignKeyAction) => string;
+/**
+ * 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.
+ */
+declare const buildRelationLine: (foreignKey: SchemaForeignKey) => string;
+/**
+ * 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.
+ */
+declare const buildInverseRelationLine: (sourceModelName: string, targetModelName: string, foreignKey: SchemaForeignKey) => string;
 /**
  * Build a Prisma model block string based on a SchemaTableCreateOperation, including
  * all fields and any necessary mapping.
@@ -2937,4 +3080,4 @@ declare class URLDriver {
   url(page: number): string;
 }
 //#endregion
-export { ArkormCollection, ArkormException, CliApp, InitCommand, InlineFactory, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, Migration, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_MODEL_REGEX, Paginator, PrismaDelegateMap, QueryBuilder, SEEDER_BRAND, SchemaBuilder, SeedCommand, Seeder, SeederCallArgument, SeederConstructor, SeederInput, TableBuilder, URLDriver, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildFieldLine, buildIndexLine, buildMigrationSource, buildModelBlock, configureArkormRuntime, createMigrationTimestamp, createPrismaAdapter, createPrismaDelegateMap, defineConfig, defineFactory, ensureArkormConfigLoading, escapeRegex, findModelBlock, formatDefaultValue, generateMigrationFile, getDefaultStubsPath, getMigrationPlan, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, loadArkormConfig, pad, resetArkormRuntimeForTests, resolveCast, resolveMigrationClassName, resolvePrismaType, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName };
+export { ArkormCollection, ArkormException, CliApp, ForeignKeyBuilder, InitCommand, InlineFactory, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, Migration, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_MODEL_REGEX, Paginator, PrismaDelegateMap, QueryBuilder, SEEDER_BRAND, SchemaBuilder, SeedCommand, Seeder, SeederCallArgument, SeederConstructor, SeederInput, TableBuilder, URLDriver, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationSource, buildModelBlock, buildRelationLine, configureArkormRuntime, createMigrationTimestamp, createPrismaAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationFieldName, ensureArkormConfigLoading, escapeRegex, findModelBlock, formatDefaultValue, formatRelationAction, generateMigrationFile, getDefaultStubsPath, getMigrationPlan, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, loadArkormConfig, pad, resetArkormRuntimeForTests, resolveCast, resolveMigrationClassName, resolvePrismaType, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName };