@c15t/backend 0.0.1-rc.10

package/src/db/migration/type-mapping.ts

@@ -0,0 +1,255 @@
+import type { Field, FieldType } from '~/db/core/fields';
+/**
+ * Database type mapping functionality
+ *
+ * This module handles mapping between abstract field types and
+ * database-specific column types. It provides utilities for:
+ * 1. Converting between c15t field types and database-specific types
+ * 2. Checking type compatibility across different databases
+ * 3. Determining appropriate database types based on field attributes
+ *
+ * @module migration/type-mapping
+ */
+import type { KyselyDatabaseType } from '../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];
+}

package/src/db/migration/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Types used throughout the migration system
+ *
+ * @module migration/types
+ */
+
+import type {
+	AlterTableColumnAlteringBuilder,
+	CreateTableBuilder,
+} from 'kysely';
+import type { Field } from '~/db/core/fields';
+
+/**
+ * Type representing a table to be created during migration
+ */
+export interface TableToCreate {
+	table: string;
+	fields: Record<string, Field>;
+	order: number;
+}
+
+/**
+ * Type representing table columns to be added during migration
+ */
+export interface ColumnsToAdd {
+	table: string;
+	fields: Record<string, Field>;
+	order: number;
+}
+
+/**
+ * Type for migration operations
+ */
+export type MigrationOperation =
+	| AlterTableColumnAlteringBuilder
+	| CreateTableBuilder<string, string>;
+
+/**
+ * Result of migration generation
+ */
+export interface MigrationResult {
+	toBeCreated: TableToCreate[];
+	toBeAdded: ColumnsToAdd[];
+	runMigrations: () => Promise<void>;
+	compileMigrations: () => Promise<string>;
+}

package/src/db/schema/audit-log/index.ts

@@ -0,0 +1,3 @@
+export * from './registry';
+export * from './schema';
+export * from './table';

package/src/db/schema/audit-log/registry.ts

@@ -0,0 +1,228 @@
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import type { GenericEndpointContext } from '~/types';
+import type { RegistryContext } from '~/types/context';
+import { validateEntityOutput } from '../definition';
+import type { AuditLog } from './schema';
+/**
+ * Creates and returns a set of consent audit log adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating and querying audit logs
+ * while applying hooks and enforcing data validation rules.
+ *
+ * @param adapter - The database adapter used for direct database operations
+ * @param ctx - The context object containing the database adapter, hooks, and options
+ * @returns An object containing type-safe consent audit log operations
+ *
+ * @example
+ * ```typescript
+ * const auditLogAdapter = createAuditLogAdapter({
+ *   adapter: databaseAdapter,
+ *   createWithHooks,
+ *   options: c15tOptions
+ * });
+ *
+ * // Create a new audit log entry
+ * const log = await auditLogAdapter.createAuditLog({
+ *   entityType: 'consent',
+ *   entityId: 'cns_hadt8w7nngm7xmx2bn',
+ *   actionType: 'update',
+ *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
+ *   changes: { status: { from: 'active', to: 'withdrawn' } }
+ * });
+ * ```
+ */
+export function auditLogRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks } = getWithHooks(adapter, ctx);
+
+	return {
+		/**
+		 * Creates a new consent audit log entry in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param auditLog - Audit log data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created audit log entry with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createAuditLog: async (
+			auditLog: Omit<AuditLog, 'id' | 'createdAt'> & Partial<AuditLog>,
+			context?: GenericEndpointContext
+		) => {
+			const createdLog = await createWithHooks({
+				data: {
+					createdAt: new Date(),
+					...auditLog,
+				},
+				model: 'auditLog',
+				customFn: undefined,
+				context,
+			});
+
+			if (!createdLog) {
+				throw new Error(
+					'Failed to create consent audit log - operation returned null'
+				);
+			}
+
+			return createdLog as AuditLog;
+		},
+
+		/**
+		 * Finds all audit log entries matching specified filters.
+		 * Returns logs with processed output fields according to the schema configuration.
+		 *
+		 * @param entityType - Optional entity type to filter logs (e.g., 'consent', 'subject')
+		 * @param entityId - Optional entity ID to filter logs
+		 * @param actionType - Optional action type to filter logs (e.g., 'create', 'update')
+		 * @param limit - Optional maximum number of logs to return
+		 * @param offset - Optional number of logs to skip for pagination
+		 * @returns Array of audit log entries matching the criteria
+		 */
+		findAuditLogs: async (
+			entityType?: string,
+			entityId?: string,
+			actionType?: string,
+			limit?: number,
+			offset?: number
+		) => {
+			const whereConditions: Where<'auditLog'> = [];
+
+			if (entityType) {
+				whereConditions.push({
+					field: 'entityType',
+					value: entityType,
+				});
+			}
+
+			if (entityId) {
+				whereConditions.push({
+					field: 'entityId',
+					value: entityId,
+				});
+			}
+
+			if (actionType) {
+				whereConditions.push({
+					field: 'actionType',
+					value: actionType,
+				});
+			}
+
+			const logs = await adapter.findMany({
+				model: 'auditLog',
+				where: whereConditions,
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+				limit,
+				offset,
+			});
+
+			return logs.map((log) =>
+				validateEntityOutput('auditLog', log, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds a specific audit log entry by its ID.
+		 * Returns the log with processed output fields according to the schema configuration.
+		 *
+		 * @param auditLogId - The unique identifier of the audit log entry
+		 * @returns The audit log entry if found, null otherwise
+		 */
+		findAuditLogById: async (auditLogId: string) => {
+			const log = await adapter.findOne({
+				model: 'auditLog',
+				where: [
+					{
+						field: 'id',
+						value: auditLogId,
+					},
+				],
+			});
+			return log ? validateEntityOutput('auditLog', log, ctx.options) : null;
+		},
+
+		/**
+		 * Finds all audit log entries for a specific entity.
+		 * Returns logs with processed output fields according to the schema configuration.
+		 *
+		 * @param entityType - The type of entity (e.g., 'consent', 'subject')
+		 * @param entityId - The unique identifier of the entity
+		 * @param limit - Optional maximum number of logs to return
+		 * @returns Array of audit log entries for the specified entity
+		 */
+		findAuditLogsByEntity: async (
+			entityType: string,
+			entityId: string,
+			limit?: number
+		) => {
+			const logs = await adapter.findMany({
+				model: 'auditLog',
+				where: [
+					{
+						field: 'entityType',
+						value: entityType,
+					},
+					{
+						field: 'entityId',
+						value: entityId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+				limit,
+			});
+			return logs.map((log) =>
+				validateEntityOutput('auditLog', log, ctx.options)
+			);
+		},
+
+		/**
+		 * Counts the total number of audit log entries matching specified filters.
+		 * Useful for pagination and reporting.
+		 *
+		 * @param entityType - Optional entity type to filter logs
+		 * @param entityId - Optional entity ID to filter logs
+		 * @param actionType - Optional action type to filter logs
+		 * @returns The total count of matching audit log entries
+		 */
+		countAuditLogs: async (
+			entityType?: string,
+			entityId?: string,
+			actionType?: string
+		) => {
+			const whereConditions: Where<'auditLog'> = [];
+
+			if (entityType) {
+				whereConditions.push({
+					field: 'entityType',
+					value: entityType,
+				});
+			}
+
+			if (entityId) {
+				whereConditions.push({
+					field: 'entityId',
+					value: entityId,
+				});
+			}
+
+			if (actionType) {
+				whereConditions.push({
+					field: 'actionType',
+					value: actionType,
+				});
+			}
+
+			return adapter.count({
+				model: 'auditLog',
+				where: whereConditions,
+			});
+		},
+	};
+}

package/src/db/schema/audit-log/schema.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating consent audit log entities.
+ *
+ * This defines the structure and validation rules for audit log entries:
+ * - Required fields: entityType, entityId, actionType
+ * - Optional fields: subjectId, ipAddress, changes, metadata
+ * - Default current date/time for creation timestamp
+ *
+ * @example
+ * ```typescript
+ * const auditLogData = {
+ *   id: 'log_w5qufx2a66m7xkn3ty',
+ *   entityType: 'consent',
+ *   entityId: 'cns_hadt8w7nngm7xmx2bn',
+ *   actionType: 'update',
+ *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
+ *   changes: { status: { from: 'active', to: 'withdrawn' } }
+ * };
+ *
+ * // Validate and parse the audit log data
+ * const validAuditLog = auditLogSchema.parse(auditLogData);
+ * ```
+ */
+export const auditLogSchema = z.object({
+	id: z.string(),
+	entityType: z.string(),
+	entityId: z.string(),
+	actionType: z.string(),
+	subjectId: z.string().optional(),
+	ipAddress: z.string().optional(),
+	userAgent: z.string().optional(),
+	changes: z.record(z.unknown()).optional(),
+	metadata: z.record(z.unknown()).optional(),
+	createdAt: z.date().default(() => new Date()),
+});
+
+/**
+ * Type definition for AuditLog
+ *
+ * This type represents the structure of a consent audit log entry
+ * as defined by the auditLogSchema. It includes all fields
+ * that are part of the audit log entity.
+ */
+export type AuditLog = z.infer<typeof auditLogSchema>;