@geekmidas/constructs 0.3.2 → 0.5.0

package/src/endpoints/audit.ts

@@ -1,9 +1,9 @@
 import type {
-  AuditActor,
-  AuditStorage,
-  AuditableAction,
-  ExtractAuditPayload,
-  ExtractAuditType,
+	AuditActor,
+	AuditableAction,
+	AuditStorage,
+	ExtractAuditPayload,
+	ExtractAuditType,
 } from '@geekmidas/audit';
 import type { Logger } from '@geekmidas/logger';
 import type { InferStandardSchema } from '@geekmidas/schema';
@@ -19,32 +19,32 @@ import type { CookieFn, HeaderFn } from './Endpoint';
  * @template TOutput - The output schema of the endpoint
  */
 export interface MappedAudit<
-  TAuditAction extends AuditableAction<string, unknown>,
-  TOutput extends StandardSchemaV1 | undefined,
-  TType extends ExtractAuditType<TAuditAction> = ExtractAuditType<TAuditAction>,
+	TAuditAction extends AuditableAction<string, unknown>,
+	TOutput extends StandardSchemaV1 | undefined,
+	TType extends ExtractAuditType<TAuditAction> = ExtractAuditType<TAuditAction>,
 > {
-  /** The audit type (must be a valid type from TAuditAction) */
-  type: TType;
-  /** Function to extract payload from the endpoint response */
-  payload: (
-    response: TOutput extends StandardSchemaV1
-      ? InferStandardSchema<TOutput>
-      : unknown,
-  ) => ExtractAuditPayload<TAuditAction, TType>;
-  /** Optional condition to determine if audit should be recorded */
-  when?: (
-    response: TOutput extends StandardSchemaV1
-      ? InferStandardSchema<TOutput>
-      : unknown,
-  ) => boolean;
-  /** Optional function to extract entity ID for easier querying */
-  entityId?: (
-    response: TOutput extends StandardSchemaV1
-      ? InferStandardSchema<TOutput>
-      : unknown,
-  ) => string | Record<string, unknown>;
-  /** Optional table name for the audit record */
-  table?: string;
+	/** The audit type (must be a valid type from TAuditAction) */
+	type: TType;
+	/** Function to extract payload from the endpoint response */
+	payload: (
+		response: TOutput extends StandardSchemaV1
+			? InferStandardSchema<TOutput>
+			: unknown,
+	) => ExtractAuditPayload<TAuditAction, TType>;
+	/** Optional condition to determine if audit should be recorded */
+	when?: (
+		response: TOutput extends StandardSchemaV1
+			? InferStandardSchema<TOutput>
+			: unknown,
+	) => boolean;
+	/** Optional function to extract entity ID for easier querying */
+	entityId?: (
+		response: TOutput extends StandardSchemaV1
+			? InferStandardSchema<TOutput>
+			: unknown,
+	) => string | Record<string, unknown>;
+	/** Optional table name for the audit record */
+	table?: string;
 }
 
 /**
@@ -55,33 +55,33 @@ export interface MappedAudit<
  * @template TLogger - Logger type
  */
 export type ActorExtractor<
-  TServices extends Service[] = [],
-  TSession = unknown,
-  TLogger extends Logger = Logger,
+	TServices extends Service[] = [],
+	TSession = unknown,
+	TLogger extends Logger = Logger,
 > = (ctx: {
-  services: ServiceRecord<TServices>;
-  session: TSession;
-  header: HeaderFn;
-  cookie: CookieFn;
-  logger: TLogger;
+	services: ServiceRecord<TServices>;
+	session: TSession;
+	header: HeaderFn;
+	cookie: CookieFn;
+	logger: TLogger;
 }) => AuditActor | Promise<AuditActor>;
 
 /**
  * Configuration for the auditor on an endpoint.
  */
 export interface EndpointAuditorConfig<
-  TAuditStorage extends AuditStorage,
-  TAuditStorageServiceName extends string,
-  TServices extends Service[],
-  TSession,
-  TLogger extends Logger,
-  TAuditAction extends AuditableAction<string, unknown>,
-  TOutput extends StandardSchemaV1 | undefined,
+	TAuditStorage extends AuditStorage,
+	TAuditStorageServiceName extends string,
+	TServices extends Service[],
+	TSession,
+	TLogger extends Logger,
+	TAuditAction extends AuditableAction<string, unknown>,
+	TOutput extends StandardSchemaV1 | undefined,
 > {
-  /** The audit storage service */
-  storageService: Service<TAuditStorageServiceName, TAuditStorage>;
-  /** Optional actor extractor function */
-  actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
-  /** Declarative audit definitions */
-  audits: MappedAudit<TAuditAction, TOutput>[];
+	/** The audit storage service */
+	storageService: Service<TAuditStorageServiceName, TAuditStorage>;
+	/** Optional actor extractor function */
+	actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+	/** Declarative audit definitions */
+	audits: MappedAudit<TAuditAction, TOutput>[];
 }

package/src/endpoints/helpers.ts

@@ -1,9 +1,8 @@
 import path from 'node:path';
-import fg from 'fast-glob';
-import { Endpoint } from './Endpoint';
-
 import type { Service } from '@geekmidas/services';
+import fg from 'fast-glob';
 import type { HttpMethod } from '../types';
+import { Endpoint } from './Endpoint';
 
 // Re-export utility functions
 
@@ -22,27 +21,27 @@ import type { HttpMethod } from '../types';
  * ```
  */
 export async function getProjectRoot(cwd: string): Promise<string> {
-  if (cwd === '/') {
-    return cwd;
-  }
+	if (cwd === '/') {
+		return cwd;
+	}
 
-  const stream = fg.stream(
-    ['yarn.lock', 'pnpm-lock.yaml', 'package-lock.json', 'deno.lock'],
-    { dot: true, cwd },
-  );
+	const stream = fg.stream(
+		['yarn.lock', 'pnpm-lock.yaml', 'package-lock.json', 'deno.lock'],
+		{ dot: true, cwd },
+	);
 
-  let isRoot = false;
+	let isRoot = false;
 
-  for await (const _ of stream) {
-    isRoot = true;
-    break;
-  }
+	for await (const _ of stream) {
+		isRoot = true;
+		break;
+	}
 
-  if (isRoot) {
-    return cwd;
-  }
+	if (isRoot) {
+		return cwd;
+	}
 
-  return getProjectRoot(path.resolve(cwd, '..'));
+	return getProjectRoot(path.resolve(cwd, '..'));
 }
 
 /**
@@ -74,26 +73,26 @@ export async function getProjectRoot(cwd: string): Promise<string> {
  * - The function filters out non-Endpoint exports automatically
  */
 export async function getEndpointsFromRoutes<TServices extends Service[]>(
-  routes: string[],
-  cwd: string,
+	routes: string[],
+	cwd: string,
 ): Promise<Endpoint<string, HttpMethod, any, any, TServices>[]> {
-  const stream = fg.stream(routes, { cwd });
+	const stream = fg.stream(routes, { cwd });
 
-  const endpoints: Endpoint<string, HttpMethod, any, any, TServices>[] = [];
+	const endpoints: Endpoint<string, HttpMethod, any, any, TServices>[] = [];
 
-  for await (const f of stream) {
-    // Resolve the absolute path for the route file
-    const routePath = path.resolve(cwd, f.toString());
-    // Dynamically import the route module
-    const route = await import(routePath);
+	for await (const f of stream) {
+		// Resolve the absolute path for the route file
+		const routePath = path.resolve(cwd, f.toString());
+		// Dynamically import the route module
+		const route = await import(routePath);
 
-    // Filter exported values to find only Endpoint instances
-    const handlers = Object.values(route).filter((value) => {
-      return Endpoint.isEndpoint(value);
-    }) as unknown as Endpoint<string, HttpMethod, any, any, TServices>[];
+		// Filter exported values to find only Endpoint instances
+		const handlers = Object.values(route).filter((value) => {
+			return Endpoint.isEndpoint(value);
+		}) as unknown as Endpoint<string, HttpMethod, any, any, TServices>[];
 
-    endpoints.push(...handlers);
-  }
+		endpoints.push(...handlers);
+	}
 
-  return endpoints;
+	return endpoints;
 }

package/src/endpoints/index.ts

@@ -1,32 +1,42 @@
 import { EndpointFactory } from './EndpointFactory';
 
-export { EndpointFactory } from './EndpointFactory';
+export { publishConstructEvents } from '../publisher';
+export {
+	type Authorizer,
+	BUILT_IN_SECURITY_SCHEMES,
+	type BuiltInSecuritySchemeId,
+	createAuthorizer,
+	getSecurityScheme,
+	isBuiltInSecurityScheme,
+	type OAuthFlow,
+	type OAuthFlows,
+	type SecurityScheme,
+} from './Authorizer';
+export type { ActorExtractor, MappedAudit } from './audit';
 export {
-  Endpoint,
-  type EndpointOutput,
-  type EndpointSchemas,
-  type EndpointHandler,
-  type EndpointContext,
+	Endpoint,
+	type EndpointContext,
+	type EndpointHandler,
+	type EndpointOutput,
+	type EndpointSchemas,
+	ResponseBuilder,
 } from './Endpoint';
 export { EndpointBuilder } from './EndpointBuilder';
-export { type MappedAudit, type ActorExtractor } from './audit';
+export { EndpointFactory } from './EndpointFactory';
 export {
-  type RlsConfig,
-  type RlsContext,
-  type RlsContextExtractor,
-  RLS_BYPASS,
-  type RlsBypass,
-} from './rls';
+	createApiGatewayCookies,
+	createApiGatewayHeaders,
+	createHonoCookies,
+	createHonoHeaders,
+	createNoopCookies,
+	createNoopHeaders,
+} from './lazyAccessors';
 export {
-  type SecurityScheme,
-  type OAuthFlows,
-  type OAuthFlow,
-  type Authorizer,
-  type BuiltInSecuritySchemeId,
-  BUILT_IN_SECURITY_SCHEMES,
-  createAuthorizer,
-  isBuiltInSecurityScheme,
-  getSecurityScheme,
-} from './Authorizer';
+	RLS_BYPASS,
+	type RlsBypass,
+	type RlsConfig,
+	type RlsContext,
+	type RlsContextExtractor,
+} from './rls';
 
 export const e = new EndpointFactory();

package/src/endpoints/lazyAccessors.ts

@@ -0,0 +1,241 @@
+/**
+ * Lazy header and cookie accessors for different adaptors.
+ *
+ * Instead of parsing all headers/cookies upfront, these accessors
+ * use native adaptor methods for single lookups and only parse
+ * everything when `header()` or `cookie()` is called without arguments.
+ */
+import type { Context } from 'hono';
+import { getCookie } from 'hono/cookie';
+import type { CookieFn, HeaderFn } from './Endpoint';
+
+/**
+ * Create a lazy header accessor for Hono.
+ * Uses `c.req.header(name)` for single lookups (native, case-insensitive).
+ * Only calls `c.req.header()` to get all headers when needed.
+ */
+export function createHonoHeaders(c: Context): HeaderFn {
+	let allHeaders: Record<string, string> | null = null;
+
+	return ((key?: string) => {
+		if (key !== undefined) {
+			// Single header lookup - use native Hono method (case-insensitive)
+			return c.req.header(key);
+		}
+		// Get all headers - cache the result
+		if (!allHeaders) {
+			allHeaders = c.req.header();
+		}
+		return allHeaders;
+	}) as HeaderFn;
+}
+
+/**
+ * Create a lazy cookie accessor for Hono.
+ * Uses `getCookie(c, name)` for single lookups (native).
+ * Only parses the cookie header when all cookies are requested.
+ */
+export function createHonoCookies(c: Context): CookieFn {
+	let allCookies: Record<string, string> | null = null;
+
+	return ((name?: string) => {
+		if (name !== undefined) {
+			// Single cookie lookup - use native Hono method
+			return getCookie(c, name);
+		}
+		// Get all cookies - parse and cache
+		if (!allCookies) {
+			allCookies = {};
+			const cookieHeader = c.req.header('cookie');
+			if (cookieHeader) {
+				for (const part of cookieHeader.split(';')) {
+					const trimmed = part.trim();
+					const eqIndex = trimmed.indexOf('=');
+					if (eqIndex > 0) {
+						const key = trimmed.slice(0, eqIndex);
+						const value = trimmed.slice(eqIndex + 1);
+						allCookies[key] = value;
+					}
+				}
+			}
+		}
+		return allCookies;
+	}) as CookieFn;
+}
+
+/**
+ * Create a lazy header accessor for API Gateway events.
+ * Handles case-insensitive lookups.
+ */
+export function createApiGatewayHeaders(
+	headers: Record<string, string | undefined> | null | undefined,
+): HeaderFn {
+	let normalizedHeaders: Record<string, string> | null = null;
+
+	const normalize = () => {
+		if (!normalizedHeaders) {
+			normalizedHeaders = {};
+			if (headers) {
+				for (const [k, v] of Object.entries(headers)) {
+					if (v !== undefined) {
+						normalizedHeaders[k.toLowerCase()] = v;
+					}
+				}
+			}
+		}
+		return normalizedHeaders;
+	};
+
+	return ((key?: string) => {
+		if (key !== undefined) {
+			// Try direct lookup first (common case: headers already lowercase)
+			if (headers) {
+				const direct = headers[key] ?? headers[key.toLowerCase()];
+				if (direct !== undefined) return direct;
+				// Fall back to normalized lookup
+				return normalize()[key.toLowerCase()];
+			}
+			return undefined;
+		}
+		return normalize();
+	}) as HeaderFn;
+}
+
+/**
+ * Create a lazy cookie accessor for API Gateway events.
+ * Decodes URL-encoded values to match browser behavior.
+ */
+export function createApiGatewayCookies(
+	cookies: string[] | undefined,
+	cookieHeader: string | undefined,
+): CookieFn {
+	let parsed: Record<string, string> | null = null;
+
+	const parse = () => {
+		if (!parsed) {
+			parsed = {};
+			// API Gateway v2 provides cookies as array
+			if (cookies) {
+				for (const cookie of cookies) {
+					const eqIndex = cookie.indexOf('=');
+					if (eqIndex > 0) {
+						const key = cookie.slice(0, eqIndex);
+						const value = cookie.slice(eqIndex + 1);
+						parsed[key] = decodeURIComponent(value);
+					}
+				}
+			} else if (cookieHeader) {
+				// Fall back to parsing cookie header
+				for (const part of cookieHeader.split(';')) {
+					const trimmed = part.trim();
+					const eqIndex = trimmed.indexOf('=');
+					if (eqIndex > 0) {
+						const key = trimmed.slice(0, eqIndex);
+						const value = trimmed.slice(eqIndex + 1);
+						parsed[key] = decodeURIComponent(value);
+					}
+				}
+			}
+		}
+		return parsed;
+	};
+
+	return ((name?: string) => {
+		if (name !== undefined) {
+			return parse()[name];
+		}
+		return parse();
+	}) as CookieFn;
+}
+
+/**
+ * Create a lazy header accessor for plain object headers (test adaptor, etc).
+ * Headers are already available as an object, just provide lazy access.
+ */
+export function createObjectHeaders(
+	headers: Record<string, string> | undefined,
+): HeaderFn {
+	let normalized: Record<string, string> | null = null;
+
+	return ((key?: string) => {
+		if (key !== undefined) {
+			// Try direct lookup first (common case)
+			if (headers) {
+				const direct = headers[key] ?? headers[key.toLowerCase()];
+				if (direct !== undefined) return direct;
+			}
+			// Fall back to normalized lookup for case-insensitivity
+			if (!normalized && headers) {
+				normalized = {};
+				for (const [k, v] of Object.entries(headers)) {
+					normalized[k.toLowerCase()] = v;
+				}
+			}
+			return normalized?.[key.toLowerCase()];
+		}
+		// Return all headers
+		if (!normalized && headers) {
+			normalized = {};
+			for (const [k, v] of Object.entries(headers)) {
+				normalized[k.toLowerCase()] = v;
+			}
+		}
+		return normalized ?? {};
+	}) as HeaderFn;
+}
+
+/**
+ * Create a lazy cookie accessor from a cookie header string.
+ * Decodes URL-encoded values to match browser behavior.
+ */
+export function createCookieHeaderAccessor(
+	cookieHeader: string | undefined,
+): CookieFn {
+	let parsed: Record<string, string> | null = null;
+
+	const parse = () => {
+		if (!parsed) {
+			parsed = {};
+			if (cookieHeader) {
+				for (const part of cookieHeader.split(';')) {
+					const trimmed = part.trim();
+					const eqIndex = trimmed.indexOf('=');
+					if (eqIndex > 0) {
+						const key = trimmed.slice(0, eqIndex);
+						const value = trimmed.slice(eqIndex + 1);
+						// Decode URL-encoded values to match Endpoint.createCookies behavior
+						parsed[key] = decodeURIComponent(value);
+					}
+				}
+			}
+		}
+		return parsed;
+	};
+
+	return ((name?: string) => {
+		if (name !== undefined) {
+			return parse()[name];
+		}
+		return parse();
+	}) as CookieFn;
+}
+
+/**
+ * Create a no-op header accessor (for minimal endpoints that don't use headers).
+ */
+export function createNoopHeaders(): HeaderFn {
+	return ((key?: string) => {
+		if (key !== undefined) return undefined;
+		return {};
+	}) as HeaderFn;
+}
+
+/**
+ * Create a no-op cookie accessor (for minimal endpoints that don't use cookies).
+ */
+export function createNoopCookies(): CookieFn {
+	return ((name?: string) => {
+		if (name !== undefined) return undefined;
+		return {};
+	}) as CookieFn;
+}

package/src/endpoints/parseHonoQuery.ts

@@ -5,49 +5,49 @@ import type { Context } from 'hono';
  * Hono provides c.req.queries() for arrays, but we need to handle dot notation for objects
  */
 export function parseHonoQuery(c: Context): Record<string, any> {
-  const allParams = c.req.query();
-  const result: Record<string, any> = {};
+	const allParams = c.req.query();
+	const result: Record<string, any> = {};
 
-  // First, handle all query parameters
-  for (const [key, value] of Object.entries(allParams)) {
-    if (key.includes('.')) {
-      // Handle dot notation for objects
-      const parts = key.split('.');
-      let current = result;
+	// First, handle all query parameters
+	for (const [key, value] of Object.entries(allParams)) {
+		if (key.includes('.')) {
+			// Handle dot notation for objects
+			const parts = key.split('.');
+			let current = result;
 
-      // Navigate/create the nested structure
-      for (let i = 0; i < parts.length - 1; i++) {
-        const part = parts[i];
-        if (!part) continue;
-        if (
-          !current[part] ||
-          typeof current[part] !== 'object' ||
-          Array.isArray(current[part])
-        ) {
-          current[part] = {};
-        }
-        current = current[part];
-      }
+			// Navigate/create the nested structure
+			for (let i = 0; i < parts.length - 1; i++) {
+				const part = parts[i];
+				if (!part) continue;
+				if (
+					!current[part] ||
+					typeof current[part] !== 'object' ||
+					Array.isArray(current[part])
+				) {
+					current[part] = {};
+				}
+				current = current[part];
+			}
 
-      // Set the final value, checking for arrays in nested keys
-      const lastPart = parts[parts.length - 1];
-      if (!lastPart) continue;
-      const multipleValues = c.req.queries(key);
-      if (multipleValues && multipleValues.length > 1) {
-        current[lastPart] = multipleValues;
-      } else {
-        current[lastPart] = value;
-      }
-    } else {
-      // For regular keys, check if there are multiple values
-      const multipleValues = c.req.queries(key);
-      if (multipleValues && multipleValues.length > 1) {
-        result[key] = multipleValues;
-      } else {
-        result[key] = value;
-      }
-    }
-  }
+			// Set the final value, checking for arrays in nested keys
+			const lastPart = parts[parts.length - 1];
+			if (!lastPart) continue;
+			const multipleValues = c.req.queries(key);
+			if (multipleValues && multipleValues.length > 1) {
+				current[lastPart] = multipleValues;
+			} else {
+				current[lastPart] = value;
+			}
+		} else {
+			// For regular keys, check if there are multiple values
+			const multipleValues = c.req.queries(key);
+			if (multipleValues && multipleValues.length > 1) {
+				result[key] = multipleValues;
+			} else {
+				result[key] = value;
+			}
+		}
+	}
 
-  return result;
+	return result;
 }