@c15t/backend 0.0.1-rc.10

package/src/db/hooks/utils.ts

@@ -0,0 +1,151 @@
+import type { GenericEndpointContext } from '~/types';
+import type { EntityName, EntityTypeMap } from '../core/types';
+import type { DatabaseHook, HookOperation, HookPhase } from './types';
+
+/**
+ * Process hooks for a given phase and operation.
+ *
+ * @typeParam TEntityData - Type of the entity data being processed
+ *
+ * @param data - The data to process through hooks
+ * @param model - The entity type/model name
+ * @param operation - The operation being performed (create/update)
+ * @param phase - The hook execution phase (before/after)
+ * @param hooks - Array of hook sets to process
+ * @param context - Optional request context
+ * @returns The processed data, potentially transformed, or null if aborted
+ *
+ * @remarks
+ * This core utility function handles the execution of hooks for various
+ * database operations. It traverses all registered hooks for the specified
+ * entity, operation, and phase, applying transformations or aborting as needed.
+ *
+ * @example
+ * ```typescript
+ * const processedData = await processHooks(
+ *   { name: 'Alice' },
+ *   'subject',
+ *   'create',
+ *   'before',
+ *   registeredHooks
+ * );
+ * ```
+ */
+export async function processHooks<
+	TEntityName extends EntityName,
+	TEntityData extends Record<string, unknown>,
+>(
+	data: TEntityData,
+	model: TEntityName,
+	operation: HookOperation,
+	phase: HookPhase,
+	hooks: DatabaseHook[],
+	context?: GenericEndpointContext
+): Promise<TEntityData | null> {
+	let currentData = { ...data };
+
+	for (const hookSet of hooks) {
+		// Skip if no hooks for this model
+		const modelHooks = hookSet[model];
+		if (!modelHooks) {
+			continue;
+		}
+
+		// Skip if no hooks for this operation
+		const operationHooks = modelHooks[operation];
+		if (!operationHooks) {
+			continue;
+		}
+
+		// Skip if no hooks for this phase
+		const hookFn = operationHooks[phase];
+		if (!hookFn) {
+			continue;
+		}
+
+		if (phase === 'before') {
+			const result = await hookFn(
+				currentData as unknown as EntityTypeMap[TEntityName],
+				context
+			);
+
+			if (result && typeof result === 'object' && 'kind' in result) {
+				switch (result.kind) {
+					case 'abort':
+						return null;
+					case 'transform': {
+						const transformData = result.data;
+						currentData = {
+							...currentData,
+							...transformData,
+						};
+						break;
+					}
+					default:
+						// Continue with current data
+						break;
+				}
+			}
+		} else {
+			// For 'after' hooks, we use the same type casting approach
+			await hookFn(
+				currentData as unknown as EntityTypeMap[TEntityName],
+				context
+			);
+		}
+	}
+
+	return currentData;
+}
+
+/**
+ * Process hooks for multiple records.
+ *
+ * @typeParam TEntityName - Type of the entity name
+ * @typeParam TEntityData - Type of the entity data
+ *
+ * @param records - Array of records to process
+ * @param model - The entity type/model name
+ * @param hooks - Array of hook sets to process
+ * @param context - Optional request context
+ * @returns Promise that resolves when all hooks have been processed
+ *
+ * @remarks
+ * This utility function handles processing after-update hooks for a batch
+ * of records, ensuring each record goes through the appropriate hooks.
+ *
+ * @example
+ * ```typescript
+ * // Process 'after update' hooks for multiple subjects
+ * await processAfterHooksForMany(
+ *   updatedSubjects,
+ *   'subject',
+ *   registeredHooks,
+ *   { batchId: 'sub_x1pftyoufsm7xgo1kv' }
+ * );
+ * ```
+ */
+export async function processAfterHooksForMany<
+	TEntityName extends EntityName,
+	TEntityData extends Record<string, unknown>,
+>(
+	records: TEntityData[],
+	model: TEntityName,
+	hooks: DatabaseHook[],
+	context?: GenericEndpointContext
+): Promise<void> {
+	if (!records.length) {
+		return;
+	}
+
+	for (const record of records) {
+		await processHooks<TEntityName, TEntityData>(
+			record,
+			model,
+			'update',
+			'after',
+			hooks,
+			context
+		);
+	}
+}

package/src/db/hooks/with-hooks-factory.ts

@@ -0,0 +1,68 @@
+import type { Adapter } from '~/db/adapters/types';
+import { createWithHook } from './create-hooks';
+import type {
+	CreateWithHooksProps,
+	HookContext,
+	UpdateWithHooksProps,
+} from './types';
+import { updateWithHooks } from './update-hooks';
+import { updateManyWithHooks } from './update-many-hooks';
+
+/**
+ * Creates a set of functions that apply hooks before and after database operations.
+ *
+ * @param adapter - The database adapter to use for operations
+ * @param ctx - Context object containing options and hooks
+ * @returns Object with hook-enabled database operation functions
+ *
+ * @remarks
+ * This factory function generates hook-enabled versions of common database operations
+ * (create, update, updateMany), allowing for consistent hook processing across
+ * the application.
+ *
+ * @example
+ * ```typescript
+ * const { createWithHooks } = getWithHooks(adapter, {
+ *   options: c15tOptions,
+ *   hooks: c15tOptions.databaseHooks || []
+ * });
+ *
+ * const subject = await createWithHooks({
+ *   data: { name: 'Alice' },
+ *   model: 'subject'
+ * });
+ * ```
+ */
+export function getWithHooks(adapter: Adapter, ctx: HookContext) {
+	return {
+		createWithHooks: <
+			TInputData extends Record<string, unknown>,
+			TOutputData extends Record<string, unknown> = TInputData,
+		>({
+			data,
+			model,
+			customFn,
+			context,
+		}: CreateWithHooksProps<TInputData>) =>
+			createWithHook<TInputData, TOutputData>(adapter, ctx, {
+				data,
+				model,
+				customFn,
+				context,
+			}),
+
+		updateWithHooks: <
+			TInputData extends Record<string, unknown>,
+			TOutputData extends Record<string, unknown> = TInputData,
+		>(
+			props: UpdateWithHooksProps<TInputData, TOutputData>
+		) => updateWithHooks<TInputData, TOutputData>(adapter, ctx, props),
+
+		updateManyWithHooks: <
+			TInputData extends Record<string, unknown>,
+			TOutputData extends Record<string, unknown> = TInputData,
+		>(
+			props: UpdateWithHooksProps<TInputData, TOutputData>
+		) => updateManyWithHooks<TInputData, TOutputData>(adapter, ctx, props),
+	};
+}

package/src/db/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Database Module - Main Entry Point
+ *
+ * This module provides a type-safe interface for interacting with the database.
+ */
+
+// Schema-related exports
+export {
+	getConsentTables,
+	parseInputData,
+	parseEntityOutputData,
+	getAllFields,
+} from './schema/index';
+
+// Field-related exports
+export type {
+	Field,
+	FieldType,
+} from './core/fields';
+
+export {
+	stringField,
+	numberField,
+	booleanField,
+	dateField,
+	stringArrayField,
+	numberArrayField,
+} from './core/fields';
+
+export { getMigrations } from './migration/index';
+
+export { getAdapter } from './utils/adapter-factory';

package/src/db/migration/get-migration.ts

@@ -0,0 +1,89 @@
+import type { C15TOptions } from '~/types';
+import { createLogger } from '../../utils/logger';
+import { createKyselyAdapter } from '../adapters/kysely-adapter/dialect';
+import {
+	buildColumnAddMigrations,
+	buildTableCreateMigrations,
+} from './migration-builders';
+import { createMigrationExecutors } from './migration-execution';
+import { analyzeSchemaChanges } from './schema-comparison';
+import type { MigrationResult } from './types';
+
+/**
+ * Generates database migrations based on schema differences
+ *
+ * This is the main entry point for the migration system. It orchestrates
+ * the entire process from connecting to the database to generating migrations.
+ *
+ * @param config - C15T configuration containing database connection and schema details
+ *
+ * @returns MigrationResult containing:
+ *   - toBeCreated: Tables that need to be created
+ *   - toBeAdded: Columns that need to be added to existing tables
+ *   - runMigrations: Function to execute all migrations
+ *   - compileMigrations: Function to compile migrations to SQL without executing
+ *
+ * @throws Will exit the process if the Kysely adapter is not available
+ *
+ * @example
+ * ```typescript
+ * // Generate migrations and execute them
+ * const { runMigrations } = await getMigrations(config);
+ * await runMigrations();
+ *
+ * // Or generate migrations and get the SQL
+ * const { compileMigrations } = await getMigrations(config);
+ * const sql = await compileMigrations();
+ * console.log("Migration SQL:", sql);
+ * ```
+ */
+export async function getMigrations(
+	config: C15TOptions
+): Promise<MigrationResult> {
+	const logger = createLogger(config.logger);
+
+	// Initialize database connection
+	let { kysely: db, databaseType: dbType } = await createKyselyAdapter(config);
+
+	// Check if the database type is supported
+	if (!dbType) {
+		logger.warn(
+			'Could not determine database type, defaulting to sqlite. Please provide a type in the database options to avoid this.'
+		);
+		dbType = 'sqlite';
+	}
+
+	// Check if the database is connected
+	if (!db) {
+		logger.error(
+			"Only kysely adapter is supported for migrations. You can use `generate` command to generate the schema, if you're using a different adapter."
+		);
+		process.exit(1);
+	}
+
+	// Get database metadata
+	const tableMetadata = await db.introspection.getTables();
+
+	// Analyze schema differences
+	const { toBeCreated, toBeAdded } = analyzeSchemaChanges(
+		config,
+		tableMetadata,
+		dbType
+	);
+
+	// Build migration operations
+	const columnMigrations = buildColumnAddMigrations(db, toBeAdded, dbType);
+	const tableMigrations = buildTableCreateMigrations(db, toBeCreated, dbType);
+	const migrations = [...columnMigrations, ...tableMigrations];
+
+	// Create migration executors
+	const { runMigrations, compileMigrations } =
+		createMigrationExecutors(migrations);
+
+	return {
+		toBeCreated,
+		toBeAdded,
+		runMigrations,
+		compileMigrations,
+	};
+}

package/src/db/migration/get-schema/get-schema.ts

@@ -0,0 +1,44 @@
+import { getConsentTables } from '~/db';
+import type { C15TOptions } from '~/types';
+import { processTablesIntoSchema } from './process-tables';
+import type { SchemaDefinition } from './types';
+
+/**
+ * Generates a complete database schema from the C15T configuration
+ *
+ * This function serves as the main entry point for schema generation.
+ * It retrieves table definitions from the consent module and processes
+ * them into a structured schema representation.
+ *
+ * @param config - The complete C15T configuration
+ * @returns A structured schema definition with fields and table properties
+ *
+ * @example
+ * ```typescript
+ * import type { C15TOptions } from '~/types';
+ *
+ * // Your configuration
+ * const c15tConfig: C15TOptions = {
+ *   // configuration properties
+ * };
+ *
+ * const schema = getSchema(c15tConfig);
+ * // Use schema for migrations or database operations
+ * ```
+ */
+export function getSchema(config: C15TOptions): SchemaDefinition {
+	try {
+		// Retrieve table definitions from the consent module
+		const tables = getConsentTables(config);
+
+		// Process tables into a structured schema
+		return processTablesIntoSchema(tables);
+	} catch (error) {
+		// Log the error or handle it according to your application's needs
+		// biome-ignore lint/suspicious/noConsole: <explanation>
+		console.error('Failed to generate schema:', error);
+		throw new Error(
+			`Schema generation failed: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+}

package/src/db/migration/get-schema/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Schema Module
+ *
+ * This module handles the generation and processing of database schemas
+ * based on the C15T configuration. It transforms table definitions into
+ * a structured schema representation that can be used for database operations.
+ *
+ * @module schema
+ *
+ * Example usage:
+ * ```typescript
+ * import { getSchema } from '~/db/migration/get-schema';
+ * import type { SchemaDefinition } from '~/db/migration/get-schema';
+ *
+ * // Get schema based on configuration
+ * const schema: SchemaDefinition = getSchema(config);
+ * ```
+ */
+export { getSchema } from './get-schema';
+export type { SchemaDefinition, TableSchemaDefinition } from './types';

package/src/db/migration/get-schema/process-fields.ts

@@ -0,0 +1,66 @@
+import type { Field } from '~/db/core/fields';
+import type { EntityName } from '~/db/core/types';
+import type { C15TDBSchema } from '~/db/schema/definition';
+
+/**
+ * Processes field definitions for a table
+ *
+ * This function handles field attributes, field name mappings, and references
+ * to other tables. It ensures that all fields are properly configured and
+ * references are correctly set up.
+ *
+ * @param fields - Raw field definitions from the table
+ * @param tables - All available tables for resolving references
+ * @returns Processed field definitions
+ */
+export function processFields<T extends EntityName>(
+	fields: C15TDBSchema[T]['fields'],
+	tables: C15TDBSchema
+): Record<string, Field> {
+	const actualFields: Record<string, Field> = {};
+
+	// Process each field in the fields collection
+	for (const [fieldKey, field] of Object.entries(fields)) {
+		// Skip undefined fields
+		if (!field) {
+			continue;
+		}
+
+		// Use the specified fieldName or the key if fieldName is not provided
+		const fieldName = field.fieldName || fieldKey;
+
+		// Cast field to Field to ensure it has the right type
+		const typedField = field as Field;
+		actualFields[fieldName] = typedField;
+
+		// Handle references to other tables - first check if the field has a references property
+		if (typedField && 'references' in typedField && typedField.references) {
+			const EntityName = typedField.references.model as EntityName;
+			const refTable = tables[EntityName];
+
+			// Only set up the reference if the referenced table exists
+			if (refTable) {
+				// Create a new object for references to avoid modifying the original
+				actualFields[fieldName] = {
+					...typedField,
+					references: {
+						model: refTable.entityName,
+						entity: refTable.entityName,
+						field: typedField.references.field,
+						onDelete: typedField.references.onDelete,
+					},
+				};
+			} else {
+				// Log warning and remove invalid reference if table not found
+				// biome-ignore lint/suspicious/noConsole: no Logger implementation
+				console.warn(
+					`Warning: Referenced table '${EntityName}' not found for field '${fieldName}'. The reference will be removed to prevent inconsistent state.`
+				);
+				const { references, ...fieldWithoutRef } = typedField;
+				actualFields[fieldName] = fieldWithoutRef;
+			}
+		}
+	}
+
+	return actualFields;
+}

package/src/db/migration/get-schema/process-tables.ts

@@ -0,0 +1,68 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TDBSchema } from '../../schema/definition';
+import { processFields } from './process-fields';
+import type { SchemaDefinition } from './types';
+
+/**
+ * Processes table definitions into a structured schema
+ *
+ * This function transforms the raw table definitions into a formal schema structure,
+ * handling field processing, references, and merging of table definitions.
+ *
+ * @param tables - Raw table definitions from the consent module
+ * @returns A structured schema definition
+ */
+export function processTablesIntoSchema(
+	tables: C15TDBSchema
+): SchemaDefinition {
+	const schema: SchemaDefinition = {};
+
+	// Process each table in the tables collection
+	for (const [key, table] of Object.entries(tables)) {
+		// Skip undefined tables
+		if (!table) {
+			continue;
+		}
+
+		// Process the fields for this table
+		let actualFields: Record<string, Field>;
+		try {
+			const fields = table.fields;
+			if (typeof fields !== 'object' || fields === null) {
+				// biome-ignore lint/suspicious/noConsole: its okay
+				console.warn(
+					`Invalid fields for table ${key}: Expected object, got ${typeof fields}`
+				);
+				continue;
+			}
+			actualFields = processFields(fields, tables);
+		} catch (error) {
+			// biome-ignore lint/suspicious/noConsole: its okay
+			console.error(`Error processing fields for table ${key}:`, error);
+			continue; // Skip this table if field processing fails
+		}
+
+		// Determine the model name (use the key if EntityName is not specified)
+		const EntityName = table.entityName || key;
+
+		// Update existing schema entry or create a new one
+		if (schema[EntityName]) {
+			// Merge with existing schema entry if one exists
+			schema[EntityName] = {
+				...schema[EntityName],
+				fields: {
+					...schema[EntityName]?.fields,
+					...actualFields,
+				},
+			};
+		} else {
+			// Create a new schema entry
+			schema[EntityName] = {
+				fields: actualFields,
+				order: table.order || Number.POSITIVE_INFINITY, // Default to lowest priority
+			};
+		}
+	}
+
+	return schema;
+}

package/src/db/migration/get-schema/types.ts

@@ -0,0 +1,18 @@
+import type { Field } from '~/db/core/fields';
+
+/**
+ * Represents a complete table definition within the schema
+ *
+ * @property fields - Map of field names to their attribute definitions
+ * @property order - Priority order for table creation (lower numbers are created first)
+ */
+export interface TableSchemaDefinition {
+	fields: Record<string, Field>;
+	order: number;
+}
+
+/**
+ * Represents the complete database schema
+ * Maps table names to their definitions
+ */
+export type SchemaDefinition = Record<string, TableSchemaDefinition>;

package/src/db/migration/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Migration system for c15t
+ *
+ * This module provides functionality to generate and execute database migrations
+ * based on schema definitions.
+ *
+ * This is inspired by the better-auth migration system
+ * (https://github.com/betterauth/better-auth or relevant link)
+ *
+ * @module migration
+ */
+export { getMigrations } from './get-migration';
+export type {
+	MigrationResult,
+	MigrationOperation,
+	ColumnsToAdd,
+	TableToCreate,
+} from './types';