@geekmidas/constructs 3.0.14 → 3.1.0

package/src/adaptors/__tests__/middy.spec.ts

@@ -0,0 +1,212 @@
+import { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import type { Service } from '@geekmidas/services';
+import { ServiceDiscovery, serviceContext } from '@geekmidas/services';
+import middy from '@middy/core';
+import type { Context } from 'aws-lambda';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { addServices, requestContext, withServices } from '../middy';
+
+const createMockContext = (): Context =>
+	({
+		functionName: 'standalone',
+		functionVersion: '1',
+		invokedFunctionArn:
+			'arn:aws:lambda:us-east-1:123456789012:function:standalone',
+		memoryLimitInMB: '128',
+		awsRequestId: 'aws-req-1',
+		logGroupName: '/aws/lambda/standalone',
+		logStreamName: 'stream',
+		getRemainingTimeInMillis: () => 30000,
+		done: vi.fn(),
+		fail: vi.fn(),
+		succeed: vi.fn(),
+		callbackWaitsForEmptyEventLoop: true,
+	}) as unknown as Context;
+
+/**
+ * Invoke a Middy-wrapped handler with a mock Lambda context. The service
+ * middlewares augment the context type to require `services`, but at runtime
+ * they populate it before the handler runs — so the mock starts without it and
+ * we invoke through a loosely-typed shim.
+ */
+const invoke = (
+	handler: (event: any, context: any) => any,
+	event: unknown = {},
+): Promise<unknown> => Promise.resolve(handler(event, createMockContext()));
+
+function makeSpyLogger(): Logger {
+	const logger: Logger = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		child: vi.fn(() => logger),
+	};
+	return logger;
+}
+
+interface Greeter {
+	greet(): string;
+	registeredRequestId: string;
+}
+
+class GreeterService implements Service<'greeter', Greeter> {
+	serviceName = 'greeter' as const;
+	async register(): Promise<Greeter> {
+		// Service code can read the request context during registration.
+		const registeredRequestId = serviceContext.getRequestId();
+		return {
+			registeredRequestId,
+			greet() {
+				serviceContext.getLogger().info('greeting');
+				return 'hello';
+			},
+		};
+	}
+}
+
+interface Counter {
+	next(): number;
+}
+
+class CounterService implements Service<'counter', Counter> {
+	serviceName = 'counter' as const;
+	async register(): Promise<Counter> {
+		let n = 0;
+		return { next: () => ++n };
+	}
+}
+
+describe('middy adaptor', () => {
+	beforeEach(() => {
+		// ServiceDiscovery is a process-wide singleton that caches resolved
+		// instances; reset so each test starts clean.
+		ServiceDiscovery.reset();
+	});
+
+	describe('requestContext', () => {
+		it('makes serviceContext available inside a plain handler', async () => {
+			const logger = makeSpyLogger();
+			let seenRequestId: string | undefined;
+			let hadContext = false;
+
+			const handler = middy(async () => {
+				hadContext = serviceContext.hasContext();
+				seenRequestId = serviceContext.getRequestId();
+				serviceContext.getLogger().info('tick');
+			}).use(requestContext({ logger }));
+
+			await invoke(handler);
+
+			expect(hadContext).toBe(true);
+			expect(seenRequestId).toBe('aws-req-1');
+			expect(logger.info).toHaveBeenCalledWith('tick');
+		});
+
+		it('gives each invocation its own fresh context', async () => {
+			const seen: string[] = [];
+			let counter = 0;
+			const handler = middy(async () => {
+				seen.push(serviceContext.getRequestId());
+			}).use(
+				requestContext({
+					logger: makeSpyLogger(),
+					getRequestId: () => `req-${++counter}`,
+				}),
+			);
+
+			await invoke(handler);
+			await invoke(handler);
+
+			// The second invocation must not inherit the first's request id.
+			expect(seen).toEqual(['req-1', 'req-2']);
+		});
+
+		it('propagates handler errors', async () => {
+			const handler = middy(async () => {
+				throw new Error('boom');
+			}).use(requestContext({ logger: makeSpyLogger() }));
+
+			await expect(invoke(handler)).rejects.toThrow('boom');
+		});
+
+		it('derives the request id via getRequestId override', async () => {
+			let seen: string | undefined;
+			const handler = middy(async () => {
+				seen = serviceContext.getRequestId();
+			}).use(
+				requestContext({
+					logger: makeSpyLogger(),
+					getRequestId: () => 'custom-id',
+				}),
+			);
+
+			await invoke(handler);
+			expect(seen).toBe('custom-id');
+		});
+	});
+
+	describe('addServices', () => {
+		it('resolves services onto event.services (paired with requestContext)', async () => {
+			const envParser = new EnvironmentParser({});
+			const logger = makeSpyLogger();
+			let greeting: string | undefined;
+			let counted: number | undefined;
+			let registeredRequestId: string | undefined;
+
+			const handler = middy(async (event: { services: any }) => {
+				registeredRequestId = event.services.greeter.registeredRequestId;
+				greeting = event.services.greeter.greet();
+				counted = event.services.counter.next();
+			})
+				.use(requestContext({ logger, getRequestId: () => 'shared-id' }))
+				.use(
+					addServices([new GreeterService(), new CounterService()], {
+						envParser,
+					}),
+				);
+
+			await invoke(handler);
+
+			expect(greeting).toBe('hello');
+			expect(counted).toBe(1);
+			// register() and the service method ran inside the requestContext.
+			expect(registeredRequestId).toBe('shared-id');
+			expect(logger.info).toHaveBeenCalledWith('greeting');
+		});
+
+		it('resolves context-free services without a requestContext', async () => {
+			const envParser = new EnvironmentParser({});
+			let counted: number | undefined;
+
+			const handler = middy(async (event: { services: any }) => {
+				counted = event.services.counter.next();
+			}).use(addServices([new CounterService()], { envParser }));
+
+			await invoke(handler);
+
+			expect(counted).toBe(1);
+		});
+	});
+
+	describe('withServices', () => {
+		it('establishes context and resolves services out of the box', async () => {
+			const envParser = new EnvironmentParser({});
+			let greeting: string | undefined;
+			let registeredRequestId: string | undefined;
+
+			const handler = middy(async (event: { services: any }) => {
+				registeredRequestId = event.services.greeter.registeredRequestId;
+				greeting = event.services.greeter.greet();
+			}).use(withServices([new GreeterService()], { envParser }));
+
+			await invoke(handler);
+
+			expect(greeting).toBe('hello');
+			expect(registeredRequestId).toBe('aws-req-1');
+		});
+	});
+});

package/src/adaptors/aws.ts

@@ -1,3 +1,4 @@
+export { AWSScheduledFunction } from '../crons/AWSScheduledFunction';
 export { AmazonApiGatewayV1Endpoint } from '../endpoints/AmazonApiGatewayV1EndpointAdaptor';
 export { AmazonApiGatewayV2Endpoint } from '../endpoints/AmazonApiGatewayV2EndpointAdaptor';
 export { AWSLambdaFunction } from '../functions/AWSLambdaFunction';

package/src/adaptors/middy.ts

@@ -0,0 +1,225 @@
+import { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import { ConsoleLogger } from '@geekmidas/logger/console';
+import {
+	enterRequestContext,
+	exitRequestContext,
+	type Service,
+	ServiceDiscovery,
+	type ServiceRecord,
+} from '@geekmidas/services';
+import type { MiddlewareObj } from '@middy/core';
+import type { Context } from 'aws-lambda';
+import set from 'lodash.set';
+
+/**
+ * Middy middleware helpers that bring `@geekmidas/services` request context and
+ * service discovery to **standalone** Middy Lambda handlers — i.e. functions
+ * that aren't built with the `@geekmidas/constructs` Function/Cron constructs
+ * but still want `serviceContext.getLogger()` and resolved services.
+ *
+ * Why middleware (and not `runWithRequestContext`)? Middy runs `before → handler
+ * → after` as sequential awaits in a single async context, so establishing the
+ * context with `AsyncLocalStorage.enterWith` (via `enterRequestContext`) in a
+ * `before` hook propagates to the handler. `after`/`onError` reset it.
+ *
+ * Teardown is best-effort: like `enterRequestContext`, the reset is observable
+ * to code the handler reaches but not necessarily to the frame that invoked the
+ * Middy handler. This is fine for Lambda, where each invocation runs in its own
+ * fresh async context — `requestContext` always establishes a brand-new context
+ * per invocation, so requests never inherit a previous invocation's logger.
+ *
+ * @module
+ */
+
+/**
+ * Options shared by the request-context-aware middlewares.
+ */
+export interface RequestContextOptions {
+	/**
+	 * Base logger to derive the per-request child logger from.
+	 * Defaults to a new {@link ConsoleLogger}.
+	 */
+	logger?: Logger;
+	/**
+	 * Derive the request id from the event/context.
+	 * Defaults to `context.awsRequestId`, falling back to `crypto.randomUUID()`.
+	 */
+	getRequestId?: (event: unknown, context: Context) => string;
+	/**
+	 * Extra bindings to attach to the per-request child logger.
+	 */
+	bindings?: (event: unknown, context: Context) => Record<string, unknown>;
+}
+
+/**
+ * Options for the service-resolving middlewares.
+ */
+export interface ServiceMiddlewareOptions extends RequestContextOptions {
+	/**
+	 * Environment parser used to build the default {@link ServiceDiscovery}.
+	 * Defaults to `new EnvironmentParser({ ...process.env })`.
+	 */
+	envParser?: EnvironmentParser<{}>;
+	/**
+	 * Explicit {@link ServiceDiscovery} to resolve services from. Takes
+	 * precedence over `envParser`.
+	 */
+	serviceDiscovery?: ServiceDiscovery;
+}
+
+function deriveRequestId(
+	options: RequestContextOptions,
+	event: unknown,
+	context: Context | undefined,
+): string {
+	return (
+		options.getRequestId?.(event, context as Context) ??
+		context?.awsRequestId ??
+		crypto.randomUUID()
+	);
+}
+
+function buildLogger(
+	baseLogger: Logger,
+	options: RequestContextOptions,
+	requestId: string,
+	event: unknown,
+	context: Context | undefined,
+): Logger {
+	return baseLogger.child({
+		requestId,
+		...(options.bindings?.(event, context as Context) ?? {}),
+	});
+}
+
+/**
+ * Middy middleware that establishes a request context for the handler so any
+ * code it reaches — including `@geekmidas/services` service methods — can call
+ * `serviceContext.getLogger()` / `getRequestId()` / `getRequestStartTime()`.
+ *
+ * Use this on standalone functions that need request-scoped logging. To also
+ * resolve services, pair it with {@link addServices}, or use
+ * {@link withServices} which bundles both.
+ *
+ * @example
+ * ```ts
+ * import middy from '@middy/core';
+ * import { serviceContext } from '@geekmidas/services';
+ * import { requestContext } from '@geekmidas/constructs/middy';
+ *
+ * export const handler = middy(async () => {
+ *   serviceContext.getLogger().info('tick');
+ * }).use(requestContext());
+ * ```
+ */
+export function requestContext(
+	options: RequestContextOptions = {},
+): MiddlewareObj<unknown, unknown, Error, Context> {
+	const baseLogger = options.logger ?? new ConsoleLogger();
+	return {
+		before: (request) => {
+			const { event, context } = request;
+			const requestId = deriveRequestId(options, event, context);
+			const logger = buildLogger(
+				baseLogger,
+				options,
+				requestId,
+				event,
+				context,
+			);
+			enterRequestContext({ logger, requestId, startTime: Date.now() });
+		},
+		after: () => {
+			exitRequestContext();
+		},
+		onError: () => {
+			exitRequestContext();
+		},
+	};
+}
+
+function resolveDiscovery(options: ServiceMiddlewareOptions): ServiceDiscovery {
+	return (
+		options.serviceDiscovery ??
+		ServiceDiscovery.getInstance(
+			options.envParser ?? new EnvironmentParser({ ...process.env }),
+		)
+	);
+}
+
+/**
+ * Event augmentation applied by {@link addServices} / {@link withServices}:
+ * resolved services keyed by `serviceName`. Intersect it with your own event
+ * type to type the handler, e.g. `(event: EventServices<T> & APIGatewayEvent)`.
+ */
+export type EventServices<T extends Service[]> = {
+	services: ServiceRecord<T>;
+};
+
+/**
+ * Middy middleware that resolves an array of {@link Service}s via
+ * {@link ServiceDiscovery} and attaches the resolved record to `event.services`
+ * (keyed by each service's `serviceName`), matching how the `Function`/`Cron`
+ * constructs expose services on the event.
+ *
+ * This middleware only resolves services; it does **not** establish a request
+ * context. If your services read `serviceContext` (e.g. `getLogger()`), pair it
+ * with {@link requestContext}, or use {@link withServices} which bundles both.
+ *
+ * Chainable — `.use(addServices([a])).use(addServices([b]))` accumulates onto
+ * `event.services`.
+ *
+ * @example
+ * ```ts
+ * import middy from '@middy/core';
+ * import { addServices, requestContext } from '@geekmidas/constructs/middy';
+ *
+ * export const handler = middy(async (event) => {
+ *   await event.services.database.users.deletePast();
+ *   event.services.cache.clear();
+ * })
+ *   .use(requestContext())
+ *   .use(addServices([databaseService, cacheService], { envParser }));
+ * ```
+ */
+export function addServices<const T extends Service[]>(
+	services: [...T],
+	options: ServiceMiddlewareOptions = {},
+): MiddlewareObj<EventServices<T>, unknown, Error, Context> {
+	const discovery = resolveDiscovery(options);
+
+	return {
+		before: async (request) => {
+			const resolved = await discovery.register(services);
+			set(request, 'event.services', resolved);
+		},
+	};
+}
+
+/**
+ * Batteries-included Middy setup for service-backed handlers: returns a pair of
+ * middlewares — {@link requestContext} followed by {@link addServices} — so a
+ * single `.use(withServices([...]))` gives the handler both a request context
+ * and the resolved services on `event.services`.
+ *
+ * @example
+ * ```ts
+ * import middy from '@middy/core';
+ * import { withServices } from '@geekmidas/constructs/middy';
+ *
+ * export const handler = middy(async (event) => {
+ *   await event.services.database.users.deletePast();
+ *   event.services.cache.clear();
+ * }).use(withServices([databaseService, cacheService], { envParser }));
+ * ```
+ */
+export function withServices<const T extends Service[]>(
+	services: [...T],
+	options: ServiceMiddlewareOptions = {},
+): [
+	MiddlewareObj<unknown, unknown, Error, Context>,
+	MiddlewareObj<EventServices<T>, unknown, Error, Context>,
+] {
+	return [requestContext(options), addServices(services, options)];
+}

package/src/crons/AWSScheduledFunction.ts

@@ -0,0 +1,72 @@
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { EventPublisher } from '@geekmidas/events';
+import type { Logger } from '@geekmidas/logger';
+import type { ComposableStandardSchema } from '@geekmidas/schema';
+import type { Service } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { AWSLambdaFunction } from '../functions/AWSLambdaFunction';
+import type { Cron } from './Cron';
+
+/**
+ * AWS Lambda adaptor for {@link Cron} constructs.
+ *
+ * A `Cron` is a {@link import('../functions').Function} that is invoked on a
+ * schedule (an EventBridge rule) rather than by an API request. Because of
+ * that, the runtime execution pipeline is identical to a regular Lambda
+ * function: input parsing, service/database/auditor wiring, event publishing,
+ * error handling, and the `runWithRequestContext` wrapper that powers
+ * request-scoped logging via `serviceContext.getLogger()`.
+ *
+ * This adaptor therefore reuses {@link AWSLambdaFunction} wholesale and only
+ * narrows the constructor to accept a `Cron`. The schedule expression itself
+ * (`cron.schedule`) is **deploy-time** infrastructure consumed by the CLI to
+ * provision the EventBridge rule — it is not needed at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { AWSScheduledFunction } from '@geekmidas/constructs/crons';
+ * import { cancelPastBookings } from '../../../src/crons/cancelPastBookings.js';
+ * import { envParser } from '../../../src/env';
+ *
+ * const adapter = new AWSScheduledFunction(envParser, cancelPastBookings);
+ *
+ * export const handler = adapter.handler;
+ * ```
+ */
+export class AWSScheduledFunction<
+	TInput extends ComposableStandardSchema | undefined = undefined,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+	TOutSchema extends StandardSchemaV1 | undefined = undefined,
+	TEventPublisher extends EventPublisher<any> | undefined = undefined,
+	TEventPublisherServiceName extends string = string,
+	TDatabase = undefined,
+	TDatabaseServiceName extends string = string,
+> extends AWSLambdaFunction<
+	TInput,
+	TOutSchema,
+	TServices,
+	TLogger,
+	TEventPublisher,
+	TEventPublisherServiceName,
+	undefined,
+	string,
+	TDatabase,
+	TDatabaseServiceName
+> {
+	constructor(
+		envParser: EnvironmentParser<{}>,
+		cron: Cron<
+			TInput,
+			TServices,
+			TLogger,
+			TOutSchema,
+			TEventPublisher,
+			TEventPublisherServiceName,
+			TDatabase,
+			TDatabaseServiceName
+		>,
+	) {
+		super(envParser, cron);
+	}
+}

package/src/crons/__tests__/AWSScheduledFunction.spec.ts

@@ -0,0 +1,152 @@
+import { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import type { Service } from '@geekmidas/services';
+import { ServiceDiscovery, serviceContext } from '@geekmidas/services';
+import type { Context } from 'aws-lambda';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod/v4';
+import { AWSScheduledFunction } from '../AWSScheduledFunction';
+import { CronBuilder } from '../CronBuilder';
+
+/** Spy logger whose `child()` returns itself, so all log calls land on it. */
+function makeSpyLogger(): Logger {
+	const logger: Logger = {
+		trace: vi.fn(),
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		fatal: vi.fn(),
+		child: vi.fn(() => logger),
+	};
+	return logger;
+}
+
+// Minimal EventBridge scheduled-event envelope (no user payload).
+const scheduledEvent = {
+	id: 'cdc73f9d-aea9-11e3-9d5a-835b769c0d9c',
+	version: '0',
+	account: '123456789012',
+	time: '2026-06-09T00:00:00Z',
+	region: 'us-east-1',
+	source: 'aws.events',
+	resources: ['arn:aws:events:us-east-1:123456789012:rule/daily'],
+	'detail-type': 'Scheduled Event',
+	detail: {},
+};
+
+const createMockContext = (): Context =>
+	({
+		functionName: 'cancelPastBookings',
+		functionVersion: '1',
+		invokedFunctionArn:
+			'arn:aws:lambda:us-east-1:123456789012:function:cancelPastBookings',
+		memoryLimitInMB: '128',
+		awsRequestId: 'test-request-id',
+		logGroupName: '/aws/lambda/cancelPastBookings',
+		logStreamName: '2026/06/09/[$LATEST]test-stream',
+		getRemainingTimeInMillis: () => 30000,
+		done: vi.fn(),
+		fail: vi.fn(),
+		succeed: vi.fn(),
+		callbackWaitsForEmptyEventLoop: true,
+	}) as unknown as Context;
+
+class CounterService implements Service<'counter', CounterService> {
+	serviceName = 'counter' as const;
+	count = 0;
+	async register() {
+		return this;
+	}
+	increment() {
+		this.count += 1;
+		return this.count;
+	}
+}
+
+describe('AWSScheduledFunction', () => {
+	let envParser: EnvironmentParser<{}>;
+
+	beforeEach(() => {
+		// ServiceDiscovery is a process-wide singleton that caches resolved
+		// instances; reset so each test (and ordering) starts clean.
+		ServiceDiscovery.reset();
+		envParser = new EnvironmentParser({});
+		vi.clearAllMocks();
+	});
+
+	it('runs the cron handler on a scheduled event', async () => {
+		const ran = vi.fn();
+		const cron = new CronBuilder().schedule('rate(1 day)').handle(async () => {
+			ran();
+		});
+
+		const adapter = new AWSScheduledFunction(envParser, cron);
+		const result = await adapter.handler(
+			scheduledEvent,
+			createMockContext(),
+			vi.fn(),
+		);
+
+		expect(ran).toHaveBeenCalledTimes(1);
+		// With no output schema the adaptor returns undefined, matching
+		// AWSLambdaFunction — crons typically don't return a response.
+		expect(result).toBeUndefined();
+	});
+
+	it('parses and returns output when the cron declares an output schema', async () => {
+		const cron = new CronBuilder()
+			.schedule('rate(1 day)')
+			.output(z.object({ cancelled: z.number() }))
+			.handle(async () => ({ cancelled: 3 }));
+
+		const adapter = new AWSScheduledFunction(envParser, cron);
+		const result = await adapter.handler(
+			scheduledEvent,
+			createMockContext(),
+			vi.fn(),
+		);
+
+		expect(result).toEqual({ cancelled: 3 });
+	});
+
+	it('exposes services to the cron handler', async () => {
+		let observed = 0;
+		const cron = new CronBuilder()
+			.schedule('rate(1 hour)')
+			.services([new CounterService()])
+			.handle(async ({ services }) => {
+				observed = services.counter.increment();
+			});
+
+		const adapter = new AWSScheduledFunction(envParser, cron);
+		await adapter.handler(scheduledEvent, createMockContext(), vi.fn());
+
+		expect(observed).toBe(1);
+	});
+
+	it('establishes request context so serviceContext.getLogger() works', async () => {
+		// The cron runs through the same runWithRequestContext wrapper as
+		// functions, so service code can resolve the request-scoped logger. We
+		// assert delegation via the cron's own logger rather than spying on the
+		// shared serviceContext proxy (which is a process-wide singleton).
+		let hadContext = false;
+		const logger = makeSpyLogger();
+
+		const cron = new CronBuilder()
+			.schedule('rate(1 day)')
+			.logger(logger)
+			.handle(async () => {
+				hadContext = serviceContext.hasContext();
+				serviceContext.getLogger().info('cron tick');
+			});
+
+		const adapter = new AWSScheduledFunction(envParser, cron);
+		await adapter.handler(scheduledEvent, createMockContext(), vi.fn());
+
+		expect(hadContext).toBe(true);
+		expect(logger.info).toHaveBeenCalledWith('cron tick');
+		// Context must not leak past the invocation.
+		expect(serviceContext.hasContext()).toBe(false);
+	});
+});

package/src/crons/index.ts

@@ -1,3 +1,4 @@
+export { AWSScheduledFunction } from './AWSScheduledFunction';
 export {
 	Cron,
 	type CronExpression,

package/tsdown.config.ts

@@ -12,6 +12,7 @@ export default defineConfig({
 		'src/adaptors/aws.ts',
 		'src/adaptors/testing.ts',
 		'src/adaptors/trpc.ts',
+		'src/adaptors/middy.ts',
 	],
 	clean: true,
 	outDir: 'dist',