@geekmidas/constructs 3.1.0 → 4.0.0

package/src/adaptors/middy.ts

@@ -1,225 +0,0 @@
-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/adaptors/trpc.ts

@@ -1,192 +0,0 @@
-import type { EnvironmentParser } from '@geekmidas/envkit';
-import type { Logger } from '@geekmidas/logger';
-import {
-	runWithRequestContext,
-	type Service,
-	ServiceDiscovery,
-	type ServiceRecord,
-} from '@geekmidas/services';
-import type {
-	TRPCMiddlewareBuilder,
-	TRPCMiddlewareFunction,
-} from '@trpc/server';
-
-/**
- * Shape of `t.middleware` from `@trpc/server`. We accept this rather than the
- * initialized `t` object so callers retain ownership of their tRPC instance
- * (no double-initialization, no opinion on context/meta shape).
- */
-type CreateMiddleware<TContext, TMeta> = <$ContextOverrides>(
-	fn: TRPCMiddlewareFunction<
-		TContext,
-		TMeta,
-		object,
-		$ContextOverrides,
-		unknown
-	>,
-) => TRPCMiddlewareBuilder<TContext, TMeta, $ContextOverrides, unknown>;
-
-/**
- * Result of `createServicesMiddleware`: a function that accepts a service
- * tuple and returns a tRPC middleware that merges resolved services onto the
- * context.
- */
-export type ServicesMiddleware<
-	TContext extends object,
-	TMeta extends object,
-> = <const T extends Service[]>(
-	services: [...T],
-) => TRPCMiddlewareBuilder<TContext, TMeta, ServiceRecord<T>, unknown>;
-
-/**
- * Context shape required by `createServicesMiddleware` overload 2.
- * Procedures that pull services via context-stored discovery must expose it
- * under `serviceDiscovery`.
- */
-export interface ContextWithServiceDiscovery {
-	serviceDiscovery: ServiceDiscovery;
-}
-
-/**
- * Minimum context required for request-context propagation. `logger` must be
- * present so services can call `serviceContext.getLogger()`. `requestId` and
- * `startTime` are auto-generated if missing.
- */
-export interface ContextWithLogger {
-	logger: Logger;
-	requestId?: string;
-	startTime?: number;
-}
-
-/**
- * Create a tRPC middleware that:
- *
- * 1. Resolves the requested services via `ServiceDiscovery`.
- * 2. Wraps the downstream call in `runWithRequestContext` so any code reached
- *    by the procedure (including service method implementations) can read the
- *    current logger/request id via `serviceContext`.
- * 3. Merges the resolved services onto the tRPC context so handlers can access
- *    them by service name (`ctx.database`, `ctx.cache`, ...).
- *
- * Two overloads:
- * - Pass an `envParser` to create a per-request `ServiceDiscovery` instance.
- * - Omit `envParser` to read `ctx.serviceDiscovery` from the tRPC context.
- *
- * @example
- * ```ts
- * import { initTRPC } from '@trpc/server';
- * import { createServicesMiddleware } from '@geekmidas/constructs/trpc';
- *
- * const t = initTRPC.context<Context>().create();
- * const withServices = createServicesMiddleware(t.middleware, envParser);
- *
- * export const authedProcedure = t.procedure.use(
- *   withServices([databaseService, cacheService]),
- * );
- * ```
- */
-export function createServicesMiddleware<
-	TContext extends ContextWithLogger & object,
-	TMeta extends object,
->(
-	mw: CreateMiddleware<TContext, TMeta>,
-	envParser: EnvironmentParser<{}>,
-): ServicesMiddleware<TContext, TMeta>;
-export function createServicesMiddleware<
-	TContext extends ContextWithLogger & ContextWithServiceDiscovery & object,
-	TMeta extends object,
->(mw: CreateMiddleware<TContext, TMeta>): ServicesMiddleware<TContext, TMeta>;
-export function createServicesMiddleware<
-	TContext extends ContextWithLogger & object,
-	TMeta extends object,
->(
-	mw: CreateMiddleware<TContext, TMeta>,
-	envParser?: EnvironmentParser<{}>,
-): ServicesMiddleware<TContext, TMeta> {
-	return (<const T extends Service[]>(services: [...T]) => {
-		const builder = mw(async (opts) => {
-			const ctx = opts.ctx as TContext & Partial<ContextWithServiceDiscovery>;
-
-			const discovery =
-				ctx.serviceDiscovery ??
-				ServiceDiscovery.getInstance(
-					envParser ??
-						(() => {
-							// Hit only if overload 2 was selected but ctx.serviceDiscovery is
-							// missing at runtime — surface the mistake immediately rather
-							// than letting an undefined env parser fail deep inside register.
-							throw new Error(
-								'createServicesMiddleware: no `envParser` provided and ' +
-									'`ctx.serviceDiscovery` is missing. Pass an EnvironmentParser ' +
-									'to createServicesMiddleware(), or attach a ServiceDiscovery ' +
-									'instance to the tRPC context.',
-							);
-						})(),
-				);
-
-			const requestId = ctx.requestId ?? crypto.randomUUID();
-			const startTime = ctx.startTime ?? Date.now();
-
-			return runWithRequestContext(
-				{ logger: ctx.logger, requestId, startTime },
-				async () => {
-					const resolved = await discovery.register(services);
-					return opts.next({
-						ctx: { ...opts.ctx, ...resolved } as typeof opts.ctx &
-							ServiceRecord<T>,
-					});
-				},
-			);
-		});
-
-		// Tag the inner middleware function with the requested services so external
-		// tooling (e.g. detect-procedures route generators) can introspect a
-		// procedure's service dependencies without re-executing middleware.
-		const middlewares = (
-			builder as unknown as { _middlewares?: Array<{ _services?: Service[] }> }
-		)._middlewares;
-		if (middlewares?.length) {
-			const last = middlewares[middlewares.length - 1];
-			if (last) last._services = services as unknown as Service[];
-		}
-
-		return builder as TRPCMiddlewareBuilder<
-			TContext,
-			TMeta,
-			ServiceRecord<T>,
-			unknown
-		>;
-	}) as ServicesMiddleware<TContext, TMeta>;
-}
-
-/**
- * Create a tRPC middleware that establishes a request context for downstream
- * code without resolving any services. Useful when services aren't needed on
- * a procedure but the handler (or libraries it calls) still wants to read
- * `serviceContext.getLogger()` / `getRequestId()` / `getRequestStartTime()`.
- *
- * `requestId` and `startTime` are pulled from the tRPC context when present,
- * otherwise generated (`crypto.randomUUID()` and `Date.now()`).
- *
- * @example
- * ```ts
- * const withRequestContext = createRequestContextMiddleware(t.middleware);
- * export const baseProcedure = t.procedure.use(withRequestContext);
- * ```
- */
-export function createRequestContextMiddleware<
-	TContext extends ContextWithLogger & object,
-	TMeta extends object,
->(
-	mw: CreateMiddleware<TContext, TMeta>,
-): TRPCMiddlewareBuilder<TContext, TMeta, object, unknown> {
-	return mw(async (opts) => {
-		const ctx = opts.ctx as TContext;
-		const requestId = ctx.requestId ?? crypto.randomUUID();
-		const startTime = ctx.startTime ?? Date.now();
-		return runWithRequestContext(
-			{ logger: ctx.logger, requestId, startTime },
-			() => opts.next(),
-		);
-	});
-}