@c15t/backend 0.0.1-rc.10

package/src/db/create-registry.ts

@@ -0,0 +1,31 @@
+import type { RegistryContext } from '~/types/context';
+
+import {
+	auditLogRegistry,
+	consentGeoLocationRegistry,
+	consentPurposeJunctionRegistry,
+	consentPurposeRegistry,
+	consentRecordRegistry,
+	consentRegistry,
+	consentWithdrawalRegistry,
+	domainRegistry,
+	geoLocationRegistry,
+	policyRegistry,
+	subjectRegistry,
+} from './schema/index';
+
+export const createRegistry = (ctx: RegistryContext) => {
+	return {
+		...auditLogRegistry(ctx),
+		...consentRegistry(ctx),
+		...domainRegistry(ctx),
+		...geoLocationRegistry(ctx),
+		...consentGeoLocationRegistry(ctx),
+		...consentPurposeJunctionRegistry(ctx),
+		...consentPurposeRegistry(ctx),
+		...policyRegistry(ctx),
+		...consentRecordRegistry(ctx),
+		...subjectRegistry(ctx),
+		...consentWithdrawalRegistry(ctx),
+	};
+};

package/src/db/hooks/create-hooks.ts

@@ -0,0 +1,88 @@
+import type { Adapter } from '../adapters/types';
+import type { EntityName } from '../core/types';
+import type { CreateWithHooksProps, HookContext } from './types';
+import { processHooks } from './utils';
+
+/**
+ * Creates a record with hooks applied before and after creation.
+ *
+ * @typeParam TInputData - Type of the data being created
+ * @typeParam TOutputData - Type of the data returned after creation
+ *
+ * @param adapter - The database adapter to use
+ * @param ctx - Context containing hooks and options
+ * @param props - Properties for the create operation
+ * @returns The created record or null if a hook aborted the operation
+ *
+ * @remarks
+ * This function orchestrates the entity creation process, executing hooks
+ * at appropriate times to allow validation, transformation, and post-processing.
+ * It supports both standard adapter-based creation and custom creation functions.
+ *
+ * @example
+ * ```typescript
+ * const subject = await createWithHook(
+ *   mysqlAdapter,
+ *   { hooks: subjectHooks, options: config },
+ *   {
+ *     data: { name: 'Alice' },
+ *     model: 'subject'
+ *   }
+ * );
+ * ```
+ */
+export async function createWithHook<
+	TInputData extends Record<string, unknown> = Record<string, unknown>,
+	TOutputData extends Record<string, unknown> = TInputData,
+>(
+	adapter: Adapter,
+	ctx: HookContext,
+	props: CreateWithHooksProps<TInputData>
+): Promise<TOutputData | null> {
+	const { data, model, customFn, context } = props;
+	const hooks = ctx.hooks || [];
+
+	// Process before hooks
+	const transformedData = await processHooks<EntityName, TInputData>(
+		data,
+		model,
+		'create',
+		'before',
+		hooks,
+		context
+	);
+	if (transformedData === null) {
+		return null;
+	}
+
+	// Execute operation
+	let created: TOutputData | null = null;
+
+	if (customFn) {
+		created = (await customFn.fn(transformedData)) as TOutputData | null;
+		if (!customFn.executeMainFn && created) {
+			return created;
+		}
+	}
+
+	if (!created) {
+		created = (await adapter.create({
+			model: model as EntityName,
+			data: transformedData,
+		})) as unknown as TOutputData;
+	}
+
+	// Process after hooks
+	if (created) {
+		await processHooks<EntityName, TOutputData>(
+			created,
+			model,
+			'create',
+			'after',
+			hooks,
+			context
+		);
+	}
+
+	return created;
+}

package/src/db/hooks/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Database Hooks Module
+ *
+ * A comprehensive system for intercepting, validating, and transforming data
+ * during database operations. Hooks provide a powerful way to implement
+ * cross-cutting concerns like validation, authorization, and data enrichment.
+ *
+ * This module provides:
+ * - Type definitions for hooks and their operations
+ * - Core hook processing utilities
+ * - Operation-specific hook implementations (create, update, updateMany)
+ * - A factory for generating hook-enabled database operations
+ *
+ * @module db/hooks
+ *
+ * @example
+ * ```typescript
+ * import { getWithHooks } from '~/db/hooks';
+ * import { adapter } from '~/adapters';
+ *
+ * // Create hook-enabled database operations
+ * const { createWithHooks } = getWithHooks(adapter, {
+ *   options: config,
+ *   hooks: config.databaseHooks || []
+ * });
+ *
+ * // Use hooks with database operations
+ * const subject = await createWithHooks({
+ *   data: { name: 'Alice', email: 'alice@example.com' },
+ *   model: 'subject'
+ * });
+ * ```
+ */
+export * from './types';
+export * from './utils';
+export * from './create-hooks';
+export * from './update-hooks';
+export * from './update-many-hooks';
+export * from './with-hooks-factory';

package/src/db/hooks/types.ts

@@ -0,0 +1,164 @@
+import type { Where } from '~/db/adapters/types';
+import type { C15TOptions, GenericEndpointContext } from '~/types';
+import type { EntityName, EntityTypeMap } from '../core/types';
+
+/**
+ * Defines execution phases when hooks can run in the database operation lifecycle.
+ */
+export type HookPhase = 'before' | 'after';
+
+/**
+ * Defines database operations that can have hooks attached.
+ */
+export type HookOperation = 'create' | 'update';
+
+/**
+ * Result types for hook execution that control the flow of operations.
+ *
+ * @typeParam TData - The data type being processed by the hook
+ *
+ * @remarks
+ * Hook functions can return different result types to control operation flow:
+ * - `{ kind: 'abort' }` - Abort the operation entirely
+ * - `{ kind: 'transform', data: TData }` - Transform the data and continue
+ * - `{ kind: 'continue' }` - Continue with unchanged data
+ *
+ * @example
+ * ```typescript
+ * // Abort if validation fails
+ * if (!isValid(data)) {
+ *   return { kind: 'abort' };
+ * }
+ * ```
+ */
+export type HookResult<TData> =
+	| { kind: 'abort' }
+	| { kind: 'transform'; data: TData }
+	| { kind: 'continue' };
+
+/**
+ * Hook function for a specific entity type, providing before/after hooks
+ * for create and update operations.
+ *
+ * @typeParam TEntityName - The entity type this hook applies to
+ *
+ * @remarks
+ * ModelHook provides a structured way to define hooks for different
+ * database operations on a specific entity type.
+ *
+ * @example
+ * ```typescript
+ * const subjectHook: ModelHook<'subject'> = {
+ *   create: {
+ *     before: (subjectData) => ({
+ *       kind: 'transform',
+ *       data: { ...subjectData, createdAt: new Date() }
+ *     })
+ *   }
+ * };
+ * ```
+ */
+export interface ModelHook<TEntityName extends EntityName = EntityName> {
+	create?: {
+		before?: (
+			data: EntityTypeMap[TEntityName],
+			context?: GenericEndpointContext
+		) =>
+			| Promise<HookResult<EntityTypeMap[TEntityName]> | undefined>
+			| HookResult<EntityTypeMap[TEntityName]>
+			| undefined;
+		after?: (
+			data: EntityTypeMap[TEntityName],
+			context?: GenericEndpointContext
+		) => Promise<void> | void;
+	};
+	update?: {
+		before?: (
+			data: Partial<EntityTypeMap[TEntityName]>,
+			context?: GenericEndpointContext
+		) =>
+			| Promise<HookResult<Partial<EntityTypeMap[TEntityName]>> | undefined>
+			| HookResult<Partial<EntityTypeMap[TEntityName]>>
+			| undefined;
+		after?: (
+			data: EntityTypeMap[TEntityName],
+			context?: GenericEndpointContext
+		) => Promise<void> | void;
+	};
+}
+
+/**
+ * A collection of hooks for different entity types in the database.
+ *
+ * @remarks
+ * This is the primary way to register hooks in the system.
+ */
+export type DatabaseHook = {
+	[TEntityName in EntityName]?: ModelHook<TEntityName>;
+};
+
+/**
+ * Context object containing application options and registered hooks.
+ */
+export interface HookContext {
+	hooks: DatabaseHook[];
+	options: C15TOptions;
+}
+
+/**
+ * Interface for defining custom operation functions that can be used
+ * in place of or alongside standard database operations.
+ *
+ * @typeParam TInputData - The input data type for the operation
+ * @typeParam TOutputData - The output data type for the operation
+ *
+ * @remarks
+ * Custom functions allow for specialized behavior when standard
+ * CRUD operations aren't sufficient.
+ */
+export interface CustomOperationFunction<
+	TInputData extends Record<string, unknown> = Record<string, unknown>,
+	TOutputData = TInputData,
+> {
+	fn: (data: TOutputData) => Promise<TOutputData | null> | TOutputData | null;
+	executeMainFn?: boolean;
+}
+
+/**
+ * Properties for creating a record with hooks.
+ *
+ * @typeParam TData - The data type being created
+ *
+ * @remarks
+ * This is the parameter object for the createWithHook function.
+ */
+export interface CreateWithHooksProps<
+	TData extends Record<string, unknown> = Record<string, unknown>,
+> {
+	data: TData;
+	model: EntityName;
+	customFn?: CustomOperationFunction<TData>;
+	context?: GenericEndpointContext;
+}
+
+/**
+ * Properties for updating records with hooks.
+ *
+ * @typeParam TInputData - The input data type for the update
+ * @typeParam TOutputData - The expected output data type
+ * @typeParam TResultData - The final result data type
+ *
+ * @remarks
+ * This is the parameter object for updateWithHooks and updateManyWithHooks functions.
+ */
+export interface UpdateWithHooksProps<
+	TInputData extends Record<string, unknown> = Record<string, unknown>,
+	TOutputData = TInputData,
+	TResultData = TOutputData,
+> {
+	data: Partial<TInputData>;
+	where: Where<EntityName>;
+	model: EntityName;
+	customFn?: CustomOperationFunction<Partial<TInputData>, TResultData>;
+	context?: GenericEndpointContext;
+}

package/src/db/hooks/update-hooks.ts

@@ -0,0 +1,91 @@
+import type { Adapter } from '../adapters/types';
+import type { EntityName } from '../core/types';
+import type { HookContext, UpdateWithHooksProps } from './types';
+import { processHooks } from './utils';
+
+/**
+ * Updates a record with hooks applied before and after the update operation.
+ *
+ * @typeParam TInputData - Type of the data being updated
+ * @typeParam TOutputData - Type of the data returned after update
+ *
+ * @param adapter - The database adapter to use
+ * @param ctx - Context containing hooks and options
+ * @param props - Properties for the update operation
+ * @returns The updated record or null if a hook aborted the operation
+ *
+ * @remarks
+ * This function orchestrates the entity update process, executing hooks
+ * at appropriate times to allow validation, transformation, and post-processing.
+ * It supports both standard adapter-based updates and custom update functions.
+ *
+ * @example
+ * ```typescript
+ * const updatedSubject = await updateWithHooks(
+ *   mysqlAdapter,
+ *   { hooks: subjectHooks, options: config },
+ *   {
+ *     data: { status: 'active' },
+ *     where: { id: 'sub_x1pftyoufsm7xgo1kv' },
+ *     model: 'subject'
+ *   }
+ * );
+ * ```
+ */
+export async function updateWithHooks<
+	TInputData extends Record<string, unknown> = Record<string, unknown>,
+	TOutputData extends Record<string, unknown> = TInputData,
+>(
+	adapter: Adapter,
+	ctx: HookContext,
+	props: UpdateWithHooksProps<TInputData, TOutputData>
+): Promise<TOutputData | null> {
+	const { data, where, model, customFn, context } = props;
+	const hooks = ctx.hooks || [];
+
+	// Process before hooks
+	const transformedData = await processHooks<EntityName, Partial<TInputData>>(
+		data,
+		model,
+		'update',
+		'before',
+		hooks,
+		context
+	);
+	if (transformedData === null) {
+		return null;
+	}
+
+	// Execute operation
+	let updated: TOutputData | null = null;
+	if (customFn) {
+		// Ensure customFn handles partial updates correctly
+		const result = await customFn.fn(transformedData as TOutputData);
+		updated = result;
+		if (!customFn.executeMainFn && updated) {
+			return updated;
+		}
+	}
+
+	if (!updated) {
+		updated = (await adapter.update({
+			model: model as EntityName,
+			update: transformedData,
+			where,
+		})) as TOutputData | null;
+	}
+
+	// Process after hooks
+	if (updated) {
+		await processHooks<EntityName, TOutputData>(
+			updated,
+			model,
+			'update',
+			'after',
+			hooks,
+			context
+		);
+	}
+
+	return updated;
+}

package/src/db/hooks/update-many-hooks.ts

@@ -0,0 +1,176 @@
+import type { Adapter } from '~/db/adapters/types';
+import type { EntityName } from '~/db/core/types';
+import type {
+	CustomOperationFunction,
+	HookContext,
+	UpdateWithHooksProps,
+} from './types';
+import { processAfterHooksForMany, processHooks } from './utils';
+
+/**
+ * Executes a custom function if provided for batch updates.
+ *
+ * This internal helper handles custom function execution and determines
+ * whether the standard update operation should also be performed.
+ *
+ * @template TInputData - Type of the input data
+ * @template TOutputData - Type of the output data
+ *
+ * @param data - The data to process
+ * @param customFn - Optional custom function to execute
+ *
+ * @returns Object containing the result and whether to continue with standard update
+ */
+async function executeCustomFunction<
+	TInputData extends Record<string, unknown>,
+	TOutputData,
+>(
+	data: TInputData,
+	customFn?: CustomOperationFunction<Partial<TInputData>, TOutputData>
+): Promise<{ result: TOutputData | null; shouldContinue: boolean }> {
+	if (!customFn) {
+		return { result: null, shouldContinue: true };
+	}
+	const result = (await customFn.fn(
+		data as unknown as TOutputData
+	)) as TOutputData | null;
+	const shouldContinue = !result || !!customFn.executeMainFn;
+
+	return { result, shouldContinue };
+}
+
+/**
+ * Processes the result from updateMany adapter operations.
+ *
+ * This internal helper normalizes various result formats that may be
+ * returned by different adapters when performing batch updates.
+ *
+ * @template TEntityData - The entity data type
+ *
+ * @param result - The raw result from the adapter
+ * @returns Normalized array of entity data or null
+ */
+function processUpdateManyResult<TEntityData extends Record<string, unknown>>(
+	result: unknown
+): TEntityData[] | null {
+	if (Array.isArray(result)) {
+		return result;
+	}
+
+	if (typeof result === 'number' && result > 0) {
+		return []; // Empty array if we just got a count
+	}
+
+	return null;
+}
+
+/**
+ * Updates multiple records with hooks applied before and after the batch update.
+ *
+ * This function orchestrates the batch update process, executing hooks
+ * at appropriate times to allow validation, transformation, and post-processing
+ * for multiple records simultaneously.
+ *
+ * @template TInputData - Type of the data being updated
+ * @template TOutputData - Type of the data returned after update
+ *
+ * @param adapter - The database adapter to use
+ * @param ctx - Context containing hooks and options
+ * @param props - Properties for the updateMany operation
+ *
+ * @returns The updated records or null if a hook aborted the operation
+ *
+ * @example
+ * ```typescript
+ * // Batch update subjects
+ * const updatedSubjects = await updateManyWithHooks(
+ *   mysqlAdapter,
+ *   { hooks: subjectHooks, options: config },
+ *   {
+ *     data: { isVerified: true },
+ *     where: { emailDomain: 'example.com' },
+ *     model: 'subject'
+ *   }
+ * );
+ *
+ * // With custom function for complex batch processing
+ * const updatedPosts = await updateManyWithHooks(
+ *   mysqlAdapter,
+ *   { hooks: postHooks, options: config },
+ *   {
+ *     data: { isArchived: true },
+ *     where: { createdAt: { lt: oneYearAgo } },
+ *     model: 'post',
+ *     customFn: {
+ *       fn: async (data) => {
+ *         // Get posts to be archived
+ *         const postsToArchive = await postService.findOldPosts();
+ *         // Custom batch processing
+ *         const archivedPosts = await postService.batchArchive(postsToArchive, data);
+ *         return archivedPosts;
+ *       },
+ *       executeMainFn: false // Skip standard update as custom function handles it
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function updateManyWithHooks<
+	TInputData extends Record<string, unknown> = Record<string, unknown>,
+	TOutputData extends Record<string, unknown> = TInputData,
+>(
+	adapter: Adapter,
+	ctx: HookContext,
+	props: UpdateWithHooksProps<TInputData, TOutputData>
+): Promise<TOutputData[] | null> {
+	const { data, where, model, customFn, context } = props;
+	const hooks = ctx.hooks || [];
+
+	// Process before hooks
+	const transformedData = await processHooks<EntityName, Partial<TInputData>>(
+		data,
+		model,
+		'update',
+		'before',
+		hooks,
+		context
+	);
+	if (transformedData === null) {
+		return null;
+	}
+
+	// Try custom function first
+	const { result: customResult, shouldContinue } = await executeCustomFunction<
+		Partial<TInputData>,
+		TOutputData[]
+		//@ts-expect-error
+	>(transformedData, customFn);
+
+	if (customResult && !shouldContinue) {
+		return customResult;
+	}
+
+	// Use adapter if needed
+	let updated = customResult;
+	if (!updated) {
+		const adapterResult = await adapter.updateMany({
+			model: model as EntityName,
+			update: transformedData,
+			where,
+		});
+
+		updated = processUpdateManyResult<TOutputData>(adapterResult);
+	}
+
+	// Process after hooks
+	if (updated && updated.length > 0) {
+		await processAfterHooksForMany<EntityName, TOutputData>(
+			updated,
+			model,
+			hooks,
+			context
+		);
+	}
+
+	return updated;
+}