@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/pkgs/migrations/migration-builders.ts

@@ -1,170 +0,0 @@
-import type { ColumnDataType, Expression, Kysely } from 'kysely';
-import type {
-	Database,
-	KyselyDatabaseType,
-} from '~/pkgs/db-adapters/adapters/kysely-adapter/types';
-import { getLogger } from '~/pkgs/utils/logger';
-import type { C15TOptions } from '~/types';
-import { getType } from './type-mapping';
-import type { ColumnsToAdd, MigrationOperation, TableToCreate } from './types';
-
-/**
- * Builds migrations for adding columns to existing tables
- *
- * This function creates ALTER TABLE statements to add missing columns
- * to existing tables in the database.
- *
- * @param db - Kysely database instance used to build SQL operations
- * @param toBeAdded - Collection of tables and columns that need to be added
- * @param dbType - Database type to determine appropriate column types
- * @returns Array of migration operations ready to be executed
- */
-export function buildColumnAddMigrations(
-	db: Kysely<Database>,
-	toBeAdded: ColumnsToAdd[],
-	dbType: KyselyDatabaseType
-): MigrationOperation[] {
-	// Array to collect all migration operations
-	const migrations: MigrationOperation[] = [];
-
-	// Process each table that needs columns added
-	for (const table of toBeAdded) {
-		// For each field in the table that needs to be added
-		for (const [fieldName, field] of Object.entries(table.fields)) {
-			// Get the appropriate database-specific type for this field
-			const type = getType(field, dbType) as
-				| ColumnDataType
-				| Expression<C15TOptions['database']>;
-
-			// Build an ALTER TABLE statement using Kysely's fluent API
-			const exec = db.schema
-				.alterTable(table.table)
-				// Add the column with the appropriate name and type
-				.addColumn(fieldName, type, (col) => {
-					// Start with nullability constraint based on field requirements
-					let column = field.required !== false ? col.notNull() : col;
-
-					// Add foreign key reference if specified
-					if (field.references) {
-						column = column.references(
-							`${field.references.model}.${field.references.field}`
-						);
-					}
-
-					// Add unique constraint if specified
-					if (field.unique) {
-						column = column.unique();
-					}
-
-					return column;
-				});
-
-			// Add this migration operation to our collection
-			migrations.push(exec);
-		}
-	}
-
-	return migrations;
-}
-
-/**
- * Builds migrations for creating new tables
- *
- * This function creates CREATE TABLE statements for tables
- * that don't exist in the database but are defined in the schema.
- *
- * @param db - Kysely database instance used to build SQL operations
- * @param toBeCreated - Collection of tables that need to be created
- * @param dbType - Database type to determine appropriate column types
- * @returns Array of migration operations ready to be executed
- */
-export function buildTableCreateMigrations(
-	db: Kysely<Database>,
-	toBeCreated: TableToCreate[],
-	dbType: KyselyDatabaseType
-): MigrationOperation[] {
-	const logger = getLogger();
-	const migrations: MigrationOperation[] = [];
-
-	// Process each table that needs to be created
-	for (const table of toBeCreated) {
-		// Log all field names to detect potential duplicate 'id' issues
-		const fieldNames = Object.keys(table.fields);
-		logger.info(
-			`Creating table ${table.table} with fields: ${fieldNames.join(', ')}`
-		);
-
-		// Check for potential ID field conflict - warning for explicit 'id' field
-		// This is important because we automatically add an 'id' primary key
-		if (fieldNames.includes('id')) {
-			logger.warn(
-				`⚠️ Table ${table.table} already has an explicit 'id' field, which may conflict with the auto-generated primary key`
-			);
-		}
-
-		// Check for another potential issue: field with fieldName 'id' but different key
-		// This could cause column duplication errors
-		for (const [fieldName, field] of Object.entries(table.fields)) {
-			if (field.fieldName === 'id' && fieldName !== 'id') {
-				logger.error(
-					`❌ ERROR: Table ${table.table} has field '${fieldName}' with fieldName 'id' - this will cause a duplicate column error`
-				);
-			}
-		}
-
-		// Start building the CREATE TABLE statement
-		// Always add an 'id' primary key column first
-		let dbT = db.schema.createTable(table.table).addColumn(
-			'id',
-			// Choose appropriate ID type based on database
-			// MySQL and MSSQL use varchar(36) for UUIDs, others use text
-			dbType === 'mysql' || dbType === 'mssql' ? 'varchar(36)' : 'text',
-			// Make it a primary key and non-nullable
-			(col) => col.primaryKey().notNull()
-		);
-
-		// Now add all the subject-defined fields to the table
-		for (const [fieldName, field] of Object.entries(table.fields)) {
-			// Get appropriate database-specific type for this field
-			const type = getType(field, dbType) as
-				| ColumnDataType
-				| Expression<C15TOptions['database']>;
-
-			// Log what we're doing for debugging purposes
-			logger.info(
-				`Adding column ${fieldName} (fieldName: ${field.fieldName || fieldName}) to table ${table.table}`
-			);
-
-			// Add this column to the CREATE TABLE statement
-			dbT = dbT.addColumn(fieldName, type, (col) => {
-				// Apply constraints to the column
-
-				// 1. Nullability constraint - make NOT NULL if field is required
-				let column = field.required !== false ? col.notNull() : col;
-
-				// 2. Foreign key constraint - add REFERENCES if field references another table
-				if (field.references) {
-					column = column.references(
-						`${field.references.model}.${field.references.field}`
-					);
-				}
-
-				// 3. Uniqueness constraint - add UNIQUE if the field must have unique values
-				if (field.unique) {
-					column = column.unique();
-				}
-
-				return column;
-			});
-		}
-
-		// Generate and log the raw SQL for debugging/preview
-		const sqlDebug = dbT.compile().sql;
-		logger.info(`SQL for table ${table.table}:\n${sqlDebug}`);
-
-		// Add this completed CREATE TABLE statement to our migrations collection
-		migrations.push(dbT);
-	}
-
-	return migrations;
-}

package/src/pkgs/migrations/migration-execution.ts

@@ -1,72 +0,0 @@
-import { getLogger } from '~/pkgs/utils/logger';
-import type { MigrationOperation } from './types';
-
-/**
- * Creates functions to run or compile the generated migrations
- *
- * @param migrations - Migration operations to execute
- * @returns Object with runMigrations and compileMigrations functions
- */
-export function createMigrationExecutors(migrations: MigrationOperation[]) {
-	const logger = getLogger();
-
-	/**
-	 * Executes all migration operations against the database
-	 *
-	 * This function runs each migration in sequence, executing the SQL operations
-	 * directly against the connected database. If any migration fails, the
-	 * process is halted with an error.
-	 *
-	 * @remarks
-	 * Migrations are executed in the order they were added to the migrations array.
-	 * Column additions are typically executed before table creations to ensure
-	 * any references between them are properly established.
-	 *
-	 * Error handling includes:
-	 * - Detailed logging of which migration failed
-	 * - Capturing the exact SQL that caused the error
-	 * - Rethrowing the error to allow callers to implement recovery strategies
-	 *
-	 * @throws Will throw the original database error with additional context
-	 *
-	 * @returns A promise that resolves when all migrations are complete
-	 *
-	 * @example
-	 * ```typescript
-	 * try {
-	 *   await runMigrations();
-	 *   console.log('All migrations completed successfully');
-	 * } catch (error) {
-	 *   console.error('Migration failed:', error);
-	 * }
-	 * ```
-	 */
-	async function runMigrations() {
-		// Loop through each migration operation in sequence
-		for (const migration of migrations) {
-			try {
-				// Execute this migration against the database
-				await migration.execute();
-			} catch (error) {
-				// If a migration fails, log the specific SQL that failed
-				const sql = migration.compile().sql;
-				logger.error(`Migration failed! SQL:\n${sql}`);
-
-				// Rethrow the error to allow the caller to handle it
-				throw error;
-			}
-		}
-	}
-
-	/**
-	 * Compiles all migrations to SQL without executing them
-	 *
-	 * @returns SQL string of all migrations
-	 */
-	async function compileMigrations() {
-		const compiled = migrations.map((m) => m.compile().sql);
-		return `${compiled.join(';\n\n')};`;
-	}
-
-	return { runMigrations, compileMigrations };
-}

package/src/pkgs/migrations/schema-comparison.ts

@@ -1,203 +0,0 @@
-import type { LoggerOptions } from '@c15t/logger';
-import type { TableMetadata } from 'kysely';
-import type { Field } from '~/pkgs/data-model';
-import type { KyselyDatabaseType } from '~/pkgs/db-adapters/adapters/kysely-adapter/types';
-import { getLogger } from '~/pkgs/utils/logger';
-import type { C15TOptions } from '~/types';
-
-import { getSchema } from './get-schema';
-import { matchType } from './type-mapping';
-import type {
-	ColumnsToAdd,
-	TableSchemaDefinition,
-	TableToCreate,
-} from './types';
-
-/**
- * Analyzes schema differences between the expected schema and actual database
- *
- * This function compares the schema defined in the application with the
- * actual database structure to determine what changes need to be made.
- *
- * @param config - c15t configuration containing the schema definition
- * @param tableMetadata - Database table metadata from introspection, containing
- *                        information about existing tables and columns
- * @param dbType - The database type (postgres, mysql, sqlite, mssql) which affects
- *                 how types are compared and mapped
- *
- * @returns An object containing tables to be created and columns to be added
- *
- * @example
- * ```typescript
- * const changes = analyzeSchemaChanges(
- *   appConfig,
- *   databaseMetadata,
- *   'postgres'
- * );
- *
- * console.log(`Need to create ${changes.toBeCreated.length} tables`);
- * console.log(`Need to add columns to ${changes.toBeAdded.length} tables`);
- * ```
- */
-export function analyzeSchemaChanges(
-	config: C15TOptions,
-	tableMetadata: TableMetadata[],
-	dbType: KyselyDatabaseType
-): { toBeCreated: TableToCreate[]; toBeAdded: ColumnsToAdd[] } {
-	const betterAuthSchema = getSchema(config);
-	const logger = getLogger(config.logger as LoggerOptions);
-	const toBeCreated: TableToCreate[] = [];
-	const toBeAdded: ColumnsToAdd[] = [];
-
-	for (const [key, value] of Object.entries(betterAuthSchema)) {
-		const table = tableMetadata.find((t: { name: string }) => t.name === key);
-		if (!table) {
-			handleNewTable(key, value as TableSchemaDefinition, toBeCreated);
-			continue;
-		}
-
-		handleExistingTable(
-			key,
-			value as TableSchemaDefinition,
-			table,
-			toBeAdded,
-			dbType,
-			logger
-		);
-	}
-
-	return { toBeCreated, toBeAdded };
-}
-
-/**
- * Handles logic for a table that needs to be created
- *
- * This function adds a new table to the list of tables to be created,
- * handling cases where the table might already be in the list, or
- * where it needs to be inserted at a specific position based on order.
- *
- * @param tableName - The name of the table to be created
- * @param value - Table definition containing fields and order
- * @param toBeCreated - Array of tables to be created, modified in-place
- *
- * @remarks
- * The function uses the table's order property to maintain dependencies
- * between tables. Tables with lower order values are created first.
- *
- * If a table with the same name already exists in the list, its fields
- * will be merged with the new fields rather than replacing the entry.
- */
-function handleNewTable(
-	tableName: string,
-	value: TableSchemaDefinition,
-	toBeCreated: TableToCreate[]
-): void {
-	const tIndex = toBeCreated.findIndex((t) => t.table === tableName);
-	const tableData = {
-		table: tableName,
-		fields: value.fields,
-		order: value.order || Number.POSITIVE_INFINITY,
-	};
-
-	const insertIndex = toBeCreated.findIndex(
-		(t) => (t.order || Number.POSITIVE_INFINITY) > tableData.order
-	);
-
-	if (insertIndex === -1) {
-		if (tIndex === -1) {
-			toBeCreated.push(tableData);
-		} else {
-			const existingTable = toBeCreated[tIndex];
-			if (existingTable) {
-				existingTable.fields = {
-					...existingTable.fields,
-					...value.fields,
-				};
-			}
-		}
-	} else {
-		toBeCreated.splice(insertIndex, 0, tableData);
-	}
-}
-
-/**
- * Handles logic for an existing table that might need columns added
- *
- * This function compares the expected table fields with the actual
- * table columns to determine which columns need to be added.
- * It also logs warnings for type mismatches.
- *
- * @param tableName - The name of the table being checked
- * @param value - Table definition containing expected fields and order
- * @param table - Actual table metadata from database introspection
- * @param toBeAdded - Array of table columns to be added, modified in-place
- * @param dbType - Database type for type matching
- * @param logger - Logger instance for warnings and errors
- *
- * @remarks
- * Fields are compared by name and type. If a field exists in the expected schema
- * but not in the actual table, it will be added to the list of columns to add.
- *
- * If a field exists in both but has a different type, a warning is logged.
- * Type matching takes into account differences in type names between database systems.
- *
- * @example
- * ```typescript
- * // This might produce logs like:
- * // "Field subjectId in table subjects has a different type in the database. Expected string but got varchar."
- * handleExistingTable(
- *   'subjects',
- *   { fields: { subjectId: { type: 'string', required: true } }, order: 1 },
- *   dbTable,
- *   columnsToAdd,
- *   'postgres',
- *   logger
- * );
- * ```
- */
-function handleExistingTable(
-	tableName: string,
-	value: TableSchemaDefinition,
-	table: TableMetadata,
-	toBeAdded: ColumnsToAdd[],
-	dbType: KyselyDatabaseType,
-	logger: ReturnType<typeof getLogger>
-): void {
-	// Collection of fields that need to be added to the existing table
-	const toBeAddedFields: Record<string, Field> = {};
-
-	// Iterate through each field in the expected schema for this table
-	for (const [fieldName, field] of Object.entries(value.fields)) {
-		// Check if the field exists in the actual database table
-		const column = table.columns.find((c) => c.name === fieldName);
-		const typedField = field as Field;
-
-		// If the field doesn't exist in the database, mark it to be added
-		if (!column) {
-			toBeAddedFields[fieldName] = typedField;
-			continue; // Skip the rest of this iteration
-		}
-
-		// Field exists, so check if its type matches the expected type
-		// If types match, no action needed so continue to next field
-		if (matchType(column.dataType, typedField.type, dbType)) {
-			continue;
-		}
-
-		// If we reach here, the field exists but has a different type
-		// We don't alter column types to avoid data loss, just log a warning
-		logger.warn(
-			`Field ${fieldName} in table ${tableName} has a different type in the database. Expected ${typedField.type} but got ${column.dataType}.`
-		);
-	}
-
-	// After checking all fields, if we found fields that need to be added,
-	// add an entry to the toBeAdded array with all fields for this table
-	if (Object.keys(toBeAddedFields).length > 0) {
-		toBeAdded.push({
-			table: tableName,
-			fields: toBeAddedFields,
-			order: value.order || Number.POSITIVE_INFINITY, // Use specified order or lowest priority
-		});
-	}
-}

package/src/pkgs/migrations/type-mapping.ts

@@ -1,244 +0,0 @@
-import type { Field, FieldType } from '~/pkgs/data-model';
-import type { KyselyDatabaseType } from '~/pkgs/db-adapters/adapters/kysely-adapter/types';
-
-/**
- * Type mappings for PostgreSQL
- * Maps c15t field types to PostgreSQL-specific column types
- */
-const postgresMap = {
-	string: ['character varying', 'text'],
-	number: [
-		'int4',
-		'integer',
-		'bigint',
-		'smallint',
-		'numeric',
-		'real',
-		'double precision',
-	],
-	boolean: ['bool', 'boolean'],
-	date: ['timestamp', 'date'],
-	json: ['json', 'jsonb'],
-	timezone: ['text', 'character varying'], // Timezone stored as text in PostgreSQL
-};
-
-/**
- * Type mappings for MySQL
- * Maps c15t field types to MySQL-specific column types
- */
-const mysqlMap = {
-	string: ['varchar(255)', 'varchar(36)', 'text'], // Common MySQL string variants
-	number: [
-		'integer',
-		'int',
-		'bigint',
-		'smallint',
-		'decimal',
-		'float',
-		'double',
-	],
-	boolean: ['boolean', 'tinyint'],
-	date: ['timestamp', 'datetime', 'date'],
-	json: ['json'],
-	timezone: ['varchar(50)'], // Fixed length for timezone strings
-};
-
-/**
- * Type mappings for SQLite
- * Maps c15t field types to SQLite-specific column types
- */
-const sqliteMap = {
-	string: ['TEXT'],
-	number: ['INTEGER', 'REAL'],
-	boolean: ['INTEGER', 'BOOLEAN'], // 0 or 1
-	date: ['DATE', 'INTEGER'],
-	json: ['TEXT'], // SQLite doesn't have native JSON, stored as TEXT
-	timezone: ['TEXT'], // Timezone stored as text in SQLite
-};
-/**
- * Type mappings for Microsoft SQL Server
- * Maps c15t field types to MSSQL-specific column types
- *
- * @remarks
- * For double-precision floating point values, MSSQL uses FLOAT(53) which is
- * equivalent to DOUBLE PRECISION in other databases. We map both 'double' and
- * 'float' to the appropriate MSSQL types.
- */
-const mssqlMap = {
-	string: ['text', 'varchar'],
-	number: ['int', 'bigint', 'smallint', 'decimal', 'float(53)', 'float(24)'],
-	boolean: ['bit', 'smallint'],
-	date: ['datetime', 'date'],
-	json: ['nvarchar(max)'], // MSSQL uses nvarchar for JSON storage
-	timezone: ['varchar', 'text'], // Timezone stored as text in MSSQL
-};
-
-/**
- * All database type mappings
- * Provides a unified interface to access type mappings for all supported databases
- */
-const map = {
-	postgres: postgresMap,
-	mysql: mysqlMap,
-	sqlite: sqliteMap,
-	mssql: mssqlMap,
-} as const;
-
-/**
- * Determines MySQL string type based on field attributes
- *
- * @param field - Field attributes including unique and references properties
- * @returns The appropriate MySQL type for the string field
- *
- * @example
- * ```typescript
- * // Returns 'varchar(255)' for unique fields
- * getMySqlStringType({ type: 'string', unique: true });
- *
- * // Returns 'varchar(36)' for reference fields
- * getMySqlStringType({ type: 'string', references: 'subjects' });
- *
- * // Returns 'text' for regular string fields
- * getMySqlStringType({ type: 'string' });
- * ```
- */
-export function getMySqlStringType(field: Field): string {
-	if (field.unique) {
-		return 'varchar(255)';
-	}
-	if (field.references) {
-		return 'varchar(36)';
-	}
-	return 'text';
-}
-
-/**
- * Checks if a database column type matches the expected field type
- *
- * @param columnDataType - The actual column type in the database
- * @param fieldType - The expected field type from c15t
- * @param dbType - The database type (postgres, mysql, etc.)
- * @returns True if types match, false otherwise
- *
- * @remarks
- * This function handles type compatibility across different databases,
- * accounting for the fact that the same logical type may have different
- * names in different database systems.
- *
- * Array types (string[] and number[]) are treated specially and matched
- * against JSON-compatible column types.
- *
- * @example
- * ```typescript
- * // Returns true because 'text' is compatible with 'string' in PostgreSQL
- * matchType('text', 'string', 'postgres');
- *
- * // Returns true because 'jsonb' is compatible with array types
- * matchType('jsonb', 'string[]', 'postgres');
- * ```
- */
-export function matchType(
-	columnDataType: string,
-	fieldType: FieldType,
-	dbType: KyselyDatabaseType
-): boolean {
-	if (fieldType === 'string[]' || fieldType === 'number[]') {
-		return columnDataType.toLowerCase().includes('json');
-	}
-	const types = map[dbType];
-	const type = Array.isArray(fieldType)
-		? types.string.map((t) => t.toLowerCase())
-		: types[fieldType].map((t) => t.toLowerCase());
-	const matches = type.includes(columnDataType.toLowerCase());
-	return matches;
-}
-
-/**
- * Gets the appropriate database type for a field
- *
- * @param field - Field attributes including type and other properties
- * @param dbType - Database type to get the appropriate type for
- * @returns The appropriate database-specific type
- *
- * @remarks
- * This function determines the most appropriate database type for a given field,
- * taking into account:
- * - The field's base type (string, number, boolean, etc.)
- * - Special attributes (unique, references, bigint)
- * - Database-specific requirements and best practices
- *
- * @example
- * ```typescript
- * // Returns 'text' for a regular string field in SQLite
- * getType({ type: 'string' }, 'sqlite');
- *
- * // Returns 'jsonb' for a JSON field in PostgreSQL
- * getType({ type: 'json' }, 'postgres');
- *
- * // Returns 'bigint' for a number field with bigint flag
- * getType({ type: 'number', bigint: true }, 'mysql');
- * ```
- */
-export function getType(field: Field, dbType: KyselyDatabaseType = 'sqlite') {
-	const type = field.type;
-	const typeMap = {
-		string: {
-			sqlite: 'text',
-			postgres: 'text',
-			mysql: getMySqlStringType(field),
-			mssql: getMySqlStringType(field),
-		},
-		boolean: {
-			sqlite: 'integer',
-			postgres: 'boolean',
-			mysql: 'boolean',
-			mssql: 'smallint',
-		},
-		number: {
-			sqlite: field.bigint ? 'bigint' : 'integer',
-			postgres: field.bigint ? 'bigint' : 'integer',
-			mysql: field.bigint ? 'bigint' : 'integer',
-			mssql: field.bigint ? 'bigint' : 'integer',
-		},
-		date: {
-			sqlite: 'date',
-			postgres: 'timestamp',
-			mysql: 'datetime',
-			mssql: 'datetime',
-		},
-		timezone: {
-			sqlite: 'text',
-			postgres: 'text',
-			mysql: 'varchar(50)',
-			mssql: 'nvarchar(50)',
-		},
-		json: {
-			sqlite: 'text', // SQLite doesn't have native JSON
-			postgres: 'jsonb', // PostgreSQL prefers jsonb for better performance
-			mysql: 'json',
-			mssql: 'nvarchar(max)', // SQL Server stores JSON as nvarchar
-		},
-	} as const;
-
-	if (dbType === 'sqlite' && (type === 'string[]' || type === 'number[]')) {
-		return 'text';
-	}
-	if (type === 'string[]' || type === 'number[]') {
-		switch (dbType) {
-			case 'postgres':
-				return 'jsonb';
-			case 'mysql':
-			case 'mssql':
-				return 'json';
-			default:
-				return 'text';
-		}
-	}
-
-	// Handle json type
-	if (type === 'json') {
-		return typeMap.json[dbType];
-	}
-
-	return typeMap[type][dbType];
-}