@geekmidas/constructs 9.0.2 → 10.0.0-alpha.0

package/src/Construct.ts

@@ -1,204 +0,0 @@
-import type { AuditStorage } from '@geekmidas/audit';
-import {
-	SnifferEnvironmentParser,
-	type SniffResult,
-	sniffWithFireAndForget,
-} from '@geekmidas/envkit/sniffer';
-import type { EventPublisher, MappedEvent } from '@geekmidas/events';
-import type { Logger } from '@geekmidas/logger';
-import type { Service, ServiceContext } from '@geekmidas/services';
-import type { StandardSchemaV1 } from '@standard-schema/spec';
-import compact from 'lodash.compact';
-
-// Cache for service environment variables to handle singleton services
-// Stores both the full list and the optional subset so the same sniff result
-// can satisfy both getEnvironment() and getEnvironment({ markOptional: true }).
-const serviceEnvCache = new Map<
-	Service,
-	{ envVars: string[]; optionalEnvVars: string[] }
->();
-
-/**
- * Noop context for environment sniffing.
- * Used when calling service.register() to detect env vars without a real request.
- * Returns dummy values since services should only use context in instance methods,
- * not during registration.
- */
-const snifferContext: ServiceContext = {
-	getLogger() {
-		// Return a noop logger for sniffing - services shouldn't log during registration
-		return {
-			debug: () => {},
-			info: () => {},
-			warn: () => {},
-			error: () => {},
-			child: () => snifferContext.getLogger(),
-		} as unknown as Logger;
-	},
-	getRequestId() {
-		return 'sniffer-context';
-	},
-	getRequestStartTime() {
-		return Date.now();
-	},
-	hasContext() {
-		return false;
-	},
-};
-
-export abstract class Construct<
-	TLogger extends Logger = Logger,
-	TServiceName extends string = string,
-	T extends EventPublisher<any> | undefined = undefined,
-	OutSchema extends StandardSchemaV1 | undefined = undefined,
-	TServices extends Service[] = [],
-	TAuditStorageServiceName extends string = string,
-	TAuditStorage extends AuditStorage | undefined = undefined,
-	TDatabaseServiceName extends string = string,
-	TDatabase = unknown,
-> {
-	/** Database service for this construct (used by Endpoint for RLS/audit context) */
-	public databaseService?: Service<TDatabaseServiceName, TDatabase>;
-
-	constructor(
-		public readonly type: ConstructType,
-		public readonly logger: TLogger,
-		public readonly services: TServices,
-		public readonly events: MappedEvent<T, any>[] = [],
-
-		public readonly publisherService?: Service<TServiceName, T>,
-		public outputSchema?: OutSchema,
-		public readonly timeout?: number,
-		public readonly memorySize?: number,
-		public readonly auditorStorageService?: Service<
-			TAuditStorageServiceName,
-			TAuditStorage
-		>,
-	) {}
-
-	/**
-	 * Returns an array of environment variable names required by this construct's services.
-	 * This is determined by running a "sniffer" EnvironmentParser through each service's
-	 * register method to track which environment variables are accessed.
-	 *
-	 * Results are cached per service class to handle singleton patterns where
-	 * subsequent register() calls may short-circuit and not access env vars.
-	 *
-	 * @param markOptional - When true, optional vars (those accessed via `.optional()` or
-	 *   `.default()`) are suffixed with `?` in the returned array (e.g. `'PORT?'`).
-	 * @returns Promise that resolves to array of environment variable names, sorted alphabetically
-	 *
-	 * @example
-	 * ```typescript
-	 * const endpoint = e
-	 *   .services([databaseService, authService])
-	 *   .get('/users')
-	 *   .handle(async () => []);
-	 *
-	 * await endpoint.getEnvironment();               // ['AUTH_SECRET', 'DATABASE_URL']
-	 * await endpoint.getEnvironment({ markOptional: true }); // ['AUTH_SECRET', 'DATABASE_URL', 'PORT?']
-	 * ```
-	 */
-	async getEnvironment(
-		opts: { markOptional?: boolean } = {},
-	): Promise<string[]> {
-		const { markOptional = false } = opts;
-		const envVars = new Set<string>();
-		const optionalVars = new Set<string>();
-		const services: Service[] = compact([
-			...this.services,
-			this.publisherService,
-			this.publisherService,
-			this.auditorStorageService,
-			this.databaseService,
-		]);
-
-		try {
-			for (const service of services) {
-				// Check cache first - handles singleton services that short-circuit
-				if (serviceEnvCache.has(service)) {
-					const cached = serviceEnvCache.get(service)!;
-					cached.envVars.forEach((v) => envVars.add(v));
-					cached.optionalEnvVars.forEach((v) => optionalVars.add(v));
-					continue;
-				}
-
-				// Use sniffService to properly handle all error scenarios
-				const result = await sniffService(service);
-
-				// Log any issues for debugging
-				if (result.error) {
-					this.logger.warn(
-						{ error: result.error.message, service: service.serviceName },
-						'Service threw error during env sniffing (env vars still captured)',
-					);
-				}
-				if (result.unhandledRejections.length > 0) {
-					this.logger.warn(
-						{
-							errors: result.unhandledRejections.map((e) => e.message),
-							service: service.serviceName,
-						},
-						'Fire-and-forget rejections during env sniffing (suppressed)',
-					);
-				}
-
-				// Cache and collect env vars (both required and optional)
-				serviceEnvCache.set(service, {
-					envVars: result.envVars,
-					optionalEnvVars: result.optionalEnvVars,
-				});
-				result.envVars.forEach((v) => envVars.add(v));
-				result.optionalEnvVars.forEach((v) => optionalVars.add(v));
-			}
-
-			const sorted = Array.from(envVars).sort();
-			if (!markOptional || optionalVars.size === 0) return sorted;
-			return sorted.map((v) => (optionalVars.has(v) ? `${v}?` : v));
-		} catch (error) {
-			this.logger.error(
-				{ error },
-				'Error determining environment variables for construct',
-			);
-
-			return [];
-		}
-	}
-}
-
-export enum ConstructType {
-	Cron = 'dev.geekmidas.function.cron',
-	Endpoint = 'dev.geekmidas.function.endpoint',
-	Function = 'dev.geekmidas.function.function',
-	Subscriber = 'dev.geekmidas.function.subscriber',
-	Queue = 'dev.geekmidas.function.queue',
-	Topic = 'dev.geekmidas.resource.topic',
-}
-
-/**
- * Utility to test sniffing a service for environment variables.
- * Useful for debugging services that throw errors during sniffing.
- *
- * @example
- * ```typescript
- * import { sniffService } from '@geekmidas/constructs';
- * import { authService } from './services/AuthService';
- *
- * const result = await sniffService(authService);
- * console.log('Env vars:', result.envVars);
- * console.log('Error:', result.error);
- * ```
- */
-export async function sniffService(service: Service): Promise<SniffResult> {
-	const sniffer = new SnifferEnvironmentParser();
-
-	return sniffWithFireAndForget(sniffer, () =>
-		service.register({
-			envParser: sniffer as any,
-			context: snifferContext,
-		}),
-	);
-}
-
-// Export for testing
-export { snifferContext };

package/src/__benchmarks__/build-time-optimization.bench.ts

@@ -1,274 +0,0 @@
-/**
- * Build-Time Optimization Benchmarks
- *
- * Compares:
- * - Raw Hono (baseline)
- * - HonoEndpoint.addRoutes (current runtime approach)
- * - Build-time generated inline handlers (Phase 2 optimization)
- *
- * Run with: pnpm bench packages/constructs/src/__benchmarks__/build-time-optimization.bench.ts
- */
-import { EnvironmentParser } from '@geekmidas/envkit';
-import { ServiceDiscovery } from '@geekmidas/services';
-import { Hono } from 'hono';
-import { validator } from 'hono/validator';
-import { bench, describe } from 'vitest';
-import { Endpoint, ResponseBuilder } from '../endpoints';
-import { HonoEndpoint } from '../endpoints/HonoEndpointAdaptor';
-import {
-	authEndpoint,
-	mockLogger,
-	postEndpoint,
-	simpleEndpoint,
-} from './fixtures';
-
-const envParser = new EnvironmentParser({});
-
-// ============================================================================
-// Build-Time Generated Style: Validator Factories (reusable)
-// ============================================================================
-
-const validateBody = (endpoint: any) =>
-	validator('json', async (value, c) => {
-		if (!endpoint.input?.body) return undefined;
-		const parsed = await Endpoint.validate(endpoint.input.body, value);
-		if (parsed.issues) return c.json(parsed.issues, 422);
-		return parsed.value;
-	});
-
-const _validateQuery = (endpoint: any) =>
-	validator('query', async (_, c) => {
-		if (!endpoint.input?.query) return undefined;
-		const rawQuery = Object.fromEntries(new URL(c.req.url).searchParams);
-		const parsed = await Endpoint.validate(endpoint.input.query, rawQuery);
-		if (parsed.issues) return c.json(parsed.issues, 422);
-		return parsed.value;
-	});
-
-// ============================================================================
-// App Setup: Raw Hono (baseline)
-// ============================================================================
-
-const rawHonoApp = new Hono();
-rawHonoApp.get('/health', (c) =>
-	c.json({ status: 'ok', timestamp: Date.now() }),
-);
-
-// ============================================================================
-// App Setup: HonoEndpoint.addRoutes (current runtime approach)
-// ============================================================================
-
-const runtimeApp = new Hono();
-const runtimeServiceDiscovery = ServiceDiscovery.getInstance(envParser);
-HonoEndpoint.addRoutes(
-	[simpleEndpoint] as any,
-	runtimeServiceDiscovery as any,
-	runtimeApp,
-);
-
-// ============================================================================
-// App Setup: Build-Time Generated Minimal Handler
-// ============================================================================
-
-const buildTimeMinimalApp = new Hono();
-// Simulates generated code for minimal-tier endpoint (no auth, no services)
-buildTimeMinimalApp.get('/health', async (c) => {
-	const result = await simpleEndpoint.handler(
-		{
-			services: {},
-			logger: mockLogger,
-			body: undefined,
-			query: undefined,
-			params: undefined,
-			session: undefined,
-			header: Endpoint.createHeaders(c.req.header()),
-			cookie: Endpoint.createCookies(c.req.header().cookie),
-			auditor: undefined,
-			db: undefined,
-		} as any,
-		{ getMetadata: () => ({}) } as any,
-	);
-	return c.json(result, simpleEndpoint.status as any);
-});
-
-// ============================================================================
-// App Setup: Build-Time Generated Standard Handler (with auth)
-// ============================================================================
-
-const buildTimeStandardApp = new Hono();
-const standardServiceDiscovery = ServiceDiscovery.getInstance(envParser);
-
-// Simulates generated code for standard-tier endpoint (auth + services)
-buildTimeStandardApp.get('/profile', async (c) => {
-	const headerValues = c.req.header();
-	const header = Endpoint.createHeaders(headerValues);
-	const cookie = Endpoint.createCookies(headerValues.cookie);
-
-	const services = await standardServiceDiscovery.register(
-		authEndpoint.services,
-	);
-
-	// Authentication
-	const session = await authEndpoint.getSession({
-		services,
-		logger: mockLogger,
-		header,
-		cookie,
-	} as any);
-
-	const isAuthorized = await authEndpoint.authorize({
-		header,
-		cookie,
-		services,
-		logger: mockLogger,
-		session,
-	} as any);
-
-	if (!isAuthorized) {
-		return c.json({ error: 'Unauthorized' }, 401);
-	}
-
-	const responseBuilder = new ResponseBuilder();
-	const result = await authEndpoint.handler(
-		{
-			services,
-			logger: mockLogger,
-			body: undefined,
-			query: undefined,
-			params: undefined,
-			session,
-			header,
-			cookie,
-			auditor: undefined,
-			db: undefined,
-		} as any,
-		responseBuilder,
-	);
-
-	const status = (responseBuilder.getMetadata().status ??
-		authEndpoint.status) as any;
-	return c.json(result, status);
-});
-
-// Runtime version of auth endpoint for comparison
-const runtimeAuthApp = new Hono();
-HonoEndpoint.addRoutes(
-	[authEndpoint] as any,
-	standardServiceDiscovery as any,
-	runtimeAuthApp,
-);
-
-// ============================================================================
-// App Setup: Build-Time Generated with Body Validation
-// ============================================================================
-
-const buildTimeBodyApp = new Hono();
-const bodyServiceDiscovery = ServiceDiscovery.getInstance(envParser);
-
-// Simulates generated code with body validation
-buildTimeBodyApp.post('/users', validateBody(postEndpoint), async (c) => {
-	const headerValues = c.req.header();
-	const header = Endpoint.createHeaders(headerValues);
-	const cookie = Endpoint.createCookies(headerValues.cookie);
-
-	const services = await bodyServiceDiscovery.register(postEndpoint.services);
-
-	const responseBuilder = new ResponseBuilder();
-	const result = await postEndpoint.handler(
-		{
-			services,
-			logger: mockLogger,
-			body: (c.req.valid as any)('json'),
-			query: undefined,
-			params: undefined,
-			session: undefined,
-			header,
-			cookie,
-			auditor: undefined,
-			db: undefined,
-		} as any,
-		responseBuilder,
-	);
-
-	const status = (responseBuilder.getMetadata().status ??
-		postEndpoint.status) as any;
-	return c.json(result, status);
-});
-
-// Runtime version for comparison
-const runtimeBodyApp = new Hono();
-HonoEndpoint.addRoutes(
-	[postEndpoint] as any,
-	bodyServiceDiscovery as any,
-	runtimeBodyApp,
-);
-
-// ============================================================================
-// Request Helpers
-// ============================================================================
-
-function createRequest(
-	path: string,
-	options: {
-		method?: string;
-		body?: unknown;
-		headers?: Record<string, string>;
-	} = {},
-): Request {
-	const { method = 'GET', body, headers = {} } = options;
-	const init: RequestInit = {
-		method,
-		headers: { 'Content-Type': 'application/json', ...headers },
-	};
-	if (body) init.body = JSON.stringify(body);
-	return new Request(`http://localhost${path}`, init) as Request;
-}
-
-// ============================================================================
-// Benchmarks
-// ============================================================================
-
-describe('Build-Time vs Runtime: Minimal Endpoint (GET /health)', () => {
-	const req = createRequest('/health');
-
-	bench('Raw Hono (baseline)', async () => {
-		await rawHonoApp.fetch(req);
-	});
-
-	bench('HonoEndpoint.addRoutes (runtime)', async () => {
-		await runtimeApp.fetch(req);
-	});
-
-	bench('Build-time generated (minimal tier)', async () => {
-		await buildTimeMinimalApp.fetch(req);
-	});
-});
-
-describe('Build-Time vs Runtime: Auth Endpoint (GET /profile)', () => {
-	const req = createRequest('/profile', {
-		headers: { Authorization: 'Bearer test-token' },
-	});
-
-	bench('HonoEndpoint.addRoutes (runtime)', async () => {
-		await runtimeAuthApp.fetch(req);
-	});
-
-	bench('Build-time generated (standard tier)', async () => {
-		await buildTimeStandardApp.fetch(req);
-	});
-});
-
-describe('Build-Time vs Runtime: Body Validation (POST /users)', () => {
-	const req = createRequest('/users', {
-		method: 'POST',
-		body: { name: 'Test User', email: 'test@example.com' },
-	});
-
-	bench('HonoEndpoint.addRoutes (runtime)', async () => {
-		await runtimeBodyApp.fetch(req);
-	});
-
-	bench('Build-time generated (standard tier)', async () => {
-		await buildTimeBodyApp.fetch(req);
-	});
-});