@geekmidas/constructs 7.0.1 → 10.0.0-alpha.0

package/src/endpoints/MswEndpointAdaptor.ts

@@ -1,226 +0,0 @@
-import { EnvironmentParser } from '@geekmidas/envkit';
-import type { Service } from '@geekmidas/services';
-import { ServiceDiscovery } from '@geekmidas/services';
-import { Hono } from 'hono';
-import { type HttpHandler, http } from 'msw';
-import type { Endpoint } from './Endpoint';
-import { HonoEndpoint } from './HonoEndpointAdaptor';
-
-/**
- * Header used to identify which test context a request belongs to.
- * Each concurrent test registers its own context (services, db transaction, etc.)
- * and the MSW handler looks it up by this header value.
- */
-export const TEST_CONTEXT_HEADER = 'x-test-context-id';
-
-/**
- * Per-test context containing an isolated ServiceDiscovery instance.
- * Registered in the context map and looked up per-request via the context ID header.
- */
-export interface MswTestContext {
-	serviceDiscovery: ServiceDiscovery<any>;
-}
-
-/**
- * Options for creating MSW handlers from endpoint constructs.
- *
- * @example
- * ```typescript
- * import { createMswHandlers, registerTestContext } from '@geekmidas/constructs/testing';
- * import { setupServer } from 'msw/node';
- *
- * // Create handlers once (global)
- * const { handlers, registerContext, removeContext } = createMswHandlers(
- *   [getUsers, createUser],
- *   { baseURL: 'http://localhost:3000' },
- * );
- * const server = setupServer(...handlers);
- *
- * // Per test: register an isolated context with its own services/transaction
- * it('should list users', async ({ db }) => {
- *   const contextId = crypto.randomUUID();
- *   registerContext(contextId, {
- *     services: { database: db, auth: mockAuth },
- *   });
- *
- *   const api = createApi({
- *     baseURL: 'http://localhost:3000',
- *     headers: { [TEST_CONTEXT_HEADER]: contextId },
- *   });
- *
- *   const result = await api('GET /users');
- *   expect(result).toBeDefined();
- *
- *   removeContext(contextId);
- * });
- * ```
- */
-export interface CreateMswHandlersOptions {
-	/** Base URL the client fetches from (e.g., 'http://localhost:3000') */
-	baseURL: string;
-}
-
-/**
- * Options for registering a per-test context.
- * Follows the same pattern as TestRequestAdaptor — services, database,
- * publisher, and auditorStorage are provided explicitly.
- */
-export interface RegisterContextOptions {
-	/** Service instances keyed by serviceName */
-	services?: Record<string, unknown>;
-	/** Database instance — required when endpoints use .database() */
-	database?: unknown;
-	/** Event publisher service definition */
-	publisher?: Service;
-	/** Audit storage instance — required when endpoints use .auditor() */
-	auditorStorage?: unknown;
-}
-
-const MSW_HTTP_METHODS = [
-	'get',
-	'post',
-	'put',
-	'patch',
-	'delete',
-	'options',
-] as const;
-
-type MswHttpMethod = (typeof MSW_HTTP_METHODS)[number];
-
-/**
- * Result of creating MSW handlers from endpoint constructs.
- */
-export interface CreateMswHandlersResult {
-	/** MSW handlers to pass to setupServer() */
-	handlers: HttpHandler[];
-	/** Register an isolated context for a test */
-	registerContext: (id: string, options: RegisterContextOptions) => void;
-}
-
-/**
- * Creates MSW HTTP handlers from endpoint constructs.
- *
- * Mounts endpoints on a Hono app and creates MSW handlers that intercept
- * fetch requests and route them through `app.request()` — giving frontend
- * tests full endpoint behavior (validation, auth, sessions) without HTTP.
- *
- * Each test registers its own isolated context via `registerContext()`,
- * which is resolved per-request using the `x-test-context-id` header.
- * This allows concurrent tests with their own transactions and services.
- *
- * @param endpoints - Array of endpoint constructs to create handlers for
- * @param options - Configuration including baseURL
- * @returns MSW handlers, the Hono app, and context management functions
- */
-export function createMswHandlers(
-	endpoints: Endpoint<any, any, any, any, any, any>[],
-	options: CreateMswHandlersOptions,
-): CreateMswHandlersResult {
-	const { baseURL } = options;
-	const contexts = new Map<string, MswTestContext>();
-
-	/**
-	 * Register an isolated context for a test.
-	 * Creates a fresh ServiceDiscovery and pre-registers all provided services.
-	 */
-	function registerContext(id: string, ctxOptions: RegisterContextOptions) {
-		const envParser = new EnvironmentParser({});
-		const serviceDiscovery = new ServiceDiscovery(envParser);
-
-		const serviceDefs: Service[] = [];
-
-		// Register explicit services
-		if (ctxOptions.services) {
-			for (const [name, instance] of Object.entries(ctxOptions.services)) {
-				serviceDefs.push({
-					serviceName: name,
-					register: () => instance,
-				} as Service);
-			}
-		}
-
-		// Register database service from endpoint metadata
-		if (ctxOptions.database !== undefined) {
-			for (const endpoint of endpoints) {
-				if (endpoint.databaseService) {
-					serviceDefs.push({
-						serviceName: endpoint.databaseService.serviceName,
-						register: () => ctxOptions.database,
-					} as Service);
-					break;
-				}
-			}
-		}
-
-		// Register publisher service
-		if (ctxOptions.publisher) {
-			serviceDefs.push(ctxOptions.publisher);
-		}
-
-		// Register auditor storage service from endpoint metadata
-		if (ctxOptions.auditorStorage !== undefined) {
-			for (const endpoint of endpoints) {
-				if (endpoint.auditorStorageService) {
-					serviceDefs.push({
-						serviceName: endpoint.auditorStorageService.serviceName,
-						register: () => ctxOptions.auditorStorage,
-					} as Service);
-					break;
-				}
-			}
-		}
-
-		if (serviceDefs.length > 0) {
-			serviceDiscovery.register(serviceDefs);
-		}
-
-		contexts.set(id, { serviceDiscovery });
-	}
-
-	// Create a Hono app per-request that uses the correct ServiceDiscovery.
-	// We use a wrapper app that resolves the context from the header,
-	// then delegates to a context-specific Hono app.
-	const handlers: HttpHandler[] = [];
-
-	for (const endpoint of endpoints) {
-		const method = endpoint.method.toLowerCase() as MswHttpMethod;
-		if (!MSW_HTTP_METHODS.includes(method)) continue;
-
-		const mswUrl = `${baseURL}${endpoint.route}`;
-		const mswMethod = http[method];
-
-		handlers.push(
-			mswMethod(mswUrl, async ({ request }) => {
-				const contextId = request.headers.get(TEST_CONTEXT_HEADER);
-				const ctx = contextId ? contexts.get(contextId) : undefined;
-
-				if (!ctx) {
-					return new Response(
-						JSON.stringify({
-							error: 'Missing or unknown test context ID',
-							hint: `Set the '${TEST_CONTEXT_HEADER}' header to a registered context ID`,
-						}),
-						{ status: 500, headers: { 'content-type': 'application/json' } },
-					);
-				}
-
-				// Build a fresh Hono app with this context's ServiceDiscovery
-				const app = new Hono();
-				HonoEndpoint.addRoute(endpoint, ctx.serviceDiscovery as any, app);
-
-				const response = await app.request(request);
-
-				return new Response(response.body, {
-					status: response.status,
-					statusText: response.statusText,
-					headers: response.headers,
-				});
-			}),
-		);
-	}
-
-	return {
-		handlers,
-		registerContext,
-	};
-}

package/src/endpoints/TestEndpointAdaptor.ts

@@ -1,422 +0,0 @@
-import type {
-	AuditActor,
-	AuditableAction,
-	AuditStorage,
-} from '@geekmidas/audit';
-import { DefaultAuditor } from '@geekmidas/audit';
-import { EnvironmentParser } from '@geekmidas/envkit';
-import { ForbiddenError } from '@geekmidas/errors';
-import type { EventPublisher } from '@geekmidas/events';
-import type { Logger } from '@geekmidas/logger';
-import type {
-	InferComposableStandardSchema,
-	InferStandardSchema,
-} from '@geekmidas/schema';
-import {
-	runWithRequestContext,
-	type Service,
-	ServiceDiscovery,
-	type ServiceRecord,
-} from '@geekmidas/services';
-import type { StandardSchemaV1 } from '@standard-schema/spec';
-import { publishConstructEvents } from '../publisher';
-import type { HttpMethod } from '../types';
-import type { MappedAudit } from './audit';
-import {
-	type CookieOptions,
-	Endpoint,
-	type EndpointSchemas,
-	ResponseBuilder,
-} from './Endpoint';
-import {
-	createCookieHeaderAccessor,
-	createObjectHeaders,
-} from './lazyAccessors';
-import {
-	type AuditExecutionContext,
-	executeWithAuditTransaction,
-} from './processAudits';
-
-export type TestHttpResponse<TBody = any> = {
-	body: TBody;
-	status: number;
-	headers: Record<string, string | string[]>;
-};
-
-/**
- * Serializes a cookie into a Set-Cookie header string
- */
-function serializeCookie(
-	name: string,
-	value: string,
-	options?: CookieOptions,
-): string {
-	let cookieString = `${name}=${value}`;
-
-	if (options) {
-		if (options.maxAge !== undefined) {
-			cookieString += `; Max-Age=${options.maxAge}`;
-		}
-		if (options.expires) {
-			cookieString += `; Expires=${options.expires.toUTCString()}`;
-		}
-		if (options.domain) {
-			cookieString += `; Domain=${options.domain}`;
-		}
-		if (options.path) {
-			cookieString += `; Path=${options.path}`;
-		}
-		if (options.httpOnly) {
-			cookieString += '; HttpOnly';
-		}
-		if (options.secure) {
-			cookieString += '; Secure';
-		}
-		if (options.sameSite) {
-			cookieString += `; SameSite=${options.sameSite}`;
-		}
-	}
-
-	return cookieString;
-}
-
-export class TestEndpointAdaptor<
-	TRoute extends string,
-	TMethod extends HttpMethod,
-	TInput extends EndpointSchemas = {},
-	TOutSchema extends StandardSchemaV1 | undefined = undefined,
-	TServices extends Service[] = [],
-	TLogger extends Logger = Logger,
-	TSession = unknown,
-	TEventPublisher extends EventPublisher<any> | undefined = undefined,
-	TEventPublisherServiceName extends string = string,
-	TAuditStorage extends AuditStorage | undefined = undefined,
-	TAuditStorageServiceName extends string = string,
-	TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-		string,
-		unknown
-	>,
-	TDatabase = undefined,
-	TDatabaseServiceName extends string = string,
-> {
-	static getDefaultServiceDiscover<
-		TRoute extends string,
-		TMethod extends HttpMethod,
-		TInput extends EndpointSchemas = {},
-		TOutSchema extends StandardSchemaV1 | undefined = undefined,
-		TServices extends Service[] = [],
-		TLogger extends Logger = Logger,
-		TSession = unknown,
-		TEventPublisher extends EventPublisher<any> | undefined = undefined,
-		TEventPublisherServiceName extends string = string,
-		TAuditStorage extends AuditStorage | undefined = undefined,
-		TAuditStorageServiceName extends string = string,
-		TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-			string,
-			unknown
-		>,
-		TDatabase = undefined,
-		TDatabaseServiceName extends string = string,
-	>(
-		_endpoint: Endpoint<
-			TRoute,
-			TMethod,
-			TInput,
-			TOutSchema,
-			TServices,
-			TLogger,
-			TSession,
-			TEventPublisher,
-			TEventPublisherServiceName,
-			TAuditStorage,
-			TAuditStorageServiceName,
-			TAuditAction,
-			TDatabase,
-			TDatabaseServiceName
-		>,
-	) {
-		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
-	}
-	constructor(
-		private readonly endpoint: Endpoint<
-			TRoute,
-			TMethod,
-			TInput,
-			TOutSchema,
-			TServices,
-			TLogger,
-			TSession,
-			TEventPublisher,
-			TEventPublisherServiceName,
-			TAuditStorage,
-			TAuditStorageServiceName,
-			TAuditAction,
-			TDatabase,
-			TDatabaseServiceName
-		>,
-		private serviceDiscovery: ServiceDiscovery<any> = TestEndpointAdaptor.getDefaultServiceDiscover(
-			endpoint,
-		),
-	) {}
-
-	async fullRequest(
-		ctx: TestRequestAdaptor<
-			TInput,
-			TServices,
-			TEventPublisher,
-			TEventPublisherServiceName,
-			TAuditStorage,
-			TAuditStorageServiceName,
-			TDatabase,
-			TDatabaseServiceName
-		>,
-	): Promise<TestHttpResponse<InferStandardSchema<TOutSchema>>> {
-		const body = await this.endpoint.parseInput((ctx as any).body, 'body');
-		const query = await this.endpoint.parseInput((ctx as any).query, 'query');
-		const params = await this.endpoint.parseInput(
-			(ctx as any).params,
-			'params',
-		);
-
-		// Lazy accessors - defer parsing until needed
-		const header = createObjectHeaders(ctx.headers);
-		const cookie = createCookieHeaderAccessor(ctx.headers.cookie);
-
-		// Request context setup
-		const startTime = Date.now();
-		const requestId =
-			(ctx as any).requestId ??
-			ctx.headers['x-request-id'] ??
-			crypto.randomUUID();
-
-		const logger = this.endpoint.logger.child({
-			requestId,
-			route: this.endpoint.route,
-			host: ctx.headers.host,
-			method: this.endpoint.method,
-		}) as TLogger;
-
-		// Get database from context for session extraction
-		const rawDb = (ctx as any).database as TDatabase;
-
-		// Wrap handler execution in request context
-		return runWithRequestContext({ logger, requestId, startTime }, async () => {
-			const session = await this.endpoint.getSession({
-				logger,
-				services: ctx.services,
-				header,
-				cookie,
-				...(rawDb !== undefined && { db: rawDb }),
-			} as any);
-
-			// Check authorization
-			const isAuthorized = await this.endpoint.authorize({
-				header,
-				cookie,
-				services: ctx.services,
-				logger,
-				session,
-				...(rawDb !== undefined && { db: rawDb }),
-				body,
-				query,
-				params,
-			} as any);
-
-			if (!isAuthorized) {
-				logger.warn('Forbidden access attempt');
-				throw new ForbiddenError(
-					'Forbidden access to the endpoint',
-					'You do not have permission to access this resource.',
-				);
-			}
-
-			// Create audit context if audit storage is provided
-			// The auditorStorage instance is required when endpoint uses .auditor()
-			const auditorStorage = (ctx as any).auditorStorage as TAuditStorage;
-			let auditContext: AuditExecutionContext<TAuditAction> | undefined;
-
-			if (auditorStorage) {
-				// Extract actor if configured
-				let actor: AuditActor = { id: 'system', type: 'system' };
-				if (this.endpoint.actorExtractor) {
-					try {
-						actor = await this.endpoint.actorExtractor({
-							services: ctx.services as any,
-							session,
-							header,
-							cookie,
-							logger,
-						});
-					} catch (error) {
-						logger.error(error as Error, 'Failed to extract actor for audits');
-					}
-				}
-
-				const auditor = new DefaultAuditor<TAuditAction>({
-					actor,
-					storage: auditorStorage as AuditStorage,
-					metadata: {
-						endpoint: this.endpoint.route,
-						method: this.endpoint.method,
-					},
-				});
-
-				auditContext = { auditor, storage: auditorStorage as AuditStorage };
-			}
-
-			// Warn if declarative audits are configured but no audit storage
-			const audits = this.endpoint.audits as MappedAudit<
-				TAuditAction,
-				TOutSchema
-			>[];
-			if (!auditContext && audits?.length) {
-				logger.warn('No auditor storage service available');
-			}
-
-			// Execute handler with automatic audit transaction support
-			const result = await executeWithAuditTransaction(
-				auditContext,
-				async (auditor) => {
-					// Use audit transaction as db if available (when storage has same database)
-					// For testing, the tester controls whether to use transactional auditing
-					const trx = auditor?.getTransaction?.();
-					const db = trx ?? rawDb;
-
-					const responseBuilder = new ResponseBuilder();
-					const response = await this.endpoint.handler(
-						{
-							body,
-							query,
-							params,
-							session,
-							services: ctx.services,
-							logger,
-							header,
-							cookie,
-							auditor,
-							db,
-						} as any,
-						responseBuilder,
-					);
-
-					// Check if response has metadata
-					let data = response;
-					let metadata = responseBuilder.getMetadata();
-
-					if (Endpoint.hasMetadata(response)) {
-						data = response.data;
-						metadata = response.metadata;
-					}
-
-					const output = await this.endpoint.parseOutput(data);
-
-					return { output, metadata, responseBuilder };
-				},
-				// Process declarative audits after handler (inside transaction)
-				async (result, auditor) => {
-					if (!audits?.length) return;
-
-					for (const audit of audits) {
-						if (audit.when && !audit.when(result.output as any)) {
-							continue;
-						}
-						const payload = audit.payload(result.output as any);
-						const entityId = audit.entityId?.(result.output as any);
-						auditor.audit(audit.type as any, payload as any, {
-							table: audit.table,
-							entityId,
-						});
-					}
-				},
-				// Pass rawDb so storage can reuse existing transactions
-				{ db: rawDb },
-			);
-
-			const { output, metadata } = result;
-
-			ctx.publisher && (await this.serviceDiscovery.register([ctx.publisher]));
-			await publishConstructEvents(
-				this.endpoint,
-				output,
-				this.serviceDiscovery,
-			);
-
-			// Convert cookies to Set-Cookie headers
-			const headers: Record<string, string | string[]> = {
-				...(metadata.headers || {}),
-			};
-
-			if (metadata.cookies && metadata.cookies.size > 0) {
-				const setCookieValues: string[] = [];
-				for (const [name, cookie] of metadata.cookies.entries()) {
-					setCookieValues.push(
-						serializeCookie(name, cookie.value, cookie.options),
-					);
-				}
-				headers['set-cookie'] = setCookieValues;
-			}
-
-			// Return HTTP response format
-			return {
-				body: output,
-				status: metadata.status || 200,
-				headers,
-			};
-		});
-	}
-
-	async request(
-		ctx: TestRequestAdaptor<
-			TInput,
-			TServices,
-			TEventPublisher,
-			TEventPublisherServiceName,
-			TAuditStorage,
-			TAuditStorageServiceName,
-			TDatabase,
-			TDatabaseServiceName
-		>,
-	): Promise<InferStandardSchema<TOutSchema>> {
-		const response = await this.fullRequest(ctx);
-		return response.body;
-	}
-}
-
-/**
- * Conditional audit storage requirement - required when TAuditStorage is configured
- */
-type AuditStorageRequirement<
-	TAuditStorage extends AuditStorage | undefined = undefined,
-> = TAuditStorage extends undefined
-	? {}
-	: {
-			/** Audit storage instance - required when endpoint uses .auditor() */
-			auditorStorage: TAuditStorage;
-		};
-
-/**
- * Conditional database requirement - required when TDatabase is configured
- */
-type DatabaseRequirement<TDatabase = undefined> = TDatabase extends undefined
-	? {}
-	: {
-			/** Database instance - required when endpoint uses .database() */
-			database: TDatabase;
-		};
-
-export type TestRequestAdaptor<
-	TInput extends EndpointSchemas = {},
-	TServices extends Service[] = [],
-	TEventPublisher extends EventPublisher<any> | undefined = undefined,
-	TEventPublisherServiceName extends string = string,
-	TAuditStorage extends AuditStorage | undefined = undefined,
-	_TAuditStorageServiceName extends string = string,
-	TDatabase = undefined,
-	_TDatabaseServiceName extends string = string,
-> = {
-	services: ServiceRecord<TServices>;
-	headers: Record<string, string>;
-	publisher?: Service<TEventPublisherServiceName, TEventPublisher>;
-} & InferComposableStandardSchema<TInput> &
-	AuditStorageRequirement<TAuditStorage> &
-	DatabaseRequirement<TDatabase>;