@geekmidas/services 2.0.1 → 10.0.0-alpha.0

package/src/middy.ts

@@ -1,226 +0,0 @@
-import type { EnvironmentParser } from '@geekmidas/envkit';
-import type { Logger } from '@geekmidas/logger';
-import type { MiddlewareObj } from '@middy/core';
-import type { Context } from 'aws-lambda';
-import { enterRequestContext, exitRequestContext } from './context';
-import { ServiceDiscovery, type ServiceRecord } from './ServiceDiscovery';
-import type { Service } from './types';
-
-/**
- * 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 for {@link requestContext}. Generic over the logger type so a custom
- * logger that extends {@link Logger} is preserved rather than widened.
- */
-export interface RequestContextOptions<TLogger extends Logger = Logger> {
-	/**
-	 * Logger to derive the per-request child logger from. Required — the caller
-	 * decides which logger to use (there is no implicit default).
-	 */
-	logger: TLogger;
-	/**
-	 * Derive the request id from the event/context.
-	 * Defaults to `context.awsRequestId` (always present in a Lambda invocation).
-	 */
-	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 {@link addServices} — how services are resolved. No logger is
- * needed because resolving services doesn't establish a request context.
- */
-export interface ServiceResolverOptions {
-	/**
-	 * Environment parser used to build the {@link ServiceDiscovery}. Required —
-	 * the caller supplies the parser (there is no implicit `process.env` default).
-	 */
-	envParser: EnvironmentParser<{}>;
-	/**
-	 * Explicit {@link ServiceDiscovery} to resolve services from. Takes
-	 * precedence over `envParser`.
-	 */
-	serviceDiscovery?: ServiceDiscovery;
-}
-
-/**
- * Options for {@link withServices}: request context (logger) + service resolution.
- */
-export type ServiceMiddlewareOptions<TLogger extends Logger = Logger> =
-	RequestContextOptions<TLogger> & ServiceResolverOptions;
-
-function deriveRequestId(
-	options: RequestContextOptions,
-	event: unknown,
-	context: Context,
-): string {
-	// Lambda always populates context.awsRequestId; getRequestId can override it.
-	return options.getRequestId?.(event, context) ?? context.awsRequestId;
-}
-
-function buildLogger(
-	baseLogger: Logger,
-	options: RequestContextOptions,
-	requestId: string,
-	event: unknown,
-	context: Context,
-): Logger {
-	return baseLogger.child({
-		requestId,
-		...(options.bindings?.(event, 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/services/middy';
- *
- * export const handler = middy(async () => {
- *   serviceContext.getLogger().info('tick');
- * }).use(requestContext({ logger }));
- * ```
- */
-export function requestContext<TLogger extends Logger = Logger>(
-	options: RequestContextOptions<TLogger>,
-): MiddlewareObj<unknown, unknown, Error, Context> {
-	const baseLogger = options.logger;
-	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: ServiceResolverOptions): ServiceDiscovery {
-	return (
-		options.serviceDiscovery ?? ServiceDiscovery.getInstance(options.envParser)
-	);
-}
-
-/**
- * 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/services/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: ServiceResolverOptions,
-): MiddlewareObj<EventServices<T>, unknown, Error, Context> {
-	const discovery = resolveDiscovery(options);
-
-	return {
-		before: async (request) => {
-			const resolved = await discovery.register(services);
-			const event = request.event as { services?: Record<string, unknown> };
-			// Merge so chained addServices(...) calls accumulate on event.services.
-			event.services = { ...(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/services/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[],
-	TLogger extends Logger = Logger,
->(
-	services: [...T],
-	options: ServiceMiddlewareOptions<TLogger>,
-): [
-	MiddlewareObj<unknown, unknown, Error, Context>,
-	MiddlewareObj<EventServices<T>, unknown, Error, Context>,
-] {
-	return [requestContext(options), addServices(services, options)];
-}

package/src/trpc.ts

@@ -1,190 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import type { EnvironmentParser } from '@geekmidas/envkit';
-import type { Logger } from '@geekmidas/logger';
-import type {
-	TRPCMiddlewareBuilder,
-	TRPCMiddlewareFunction,
-} from '@trpc/server';
-import { runWithRequestContext } from './context';
-import { ServiceDiscovery, type ServiceRecord } from './ServiceDiscovery';
-import type { Service } from './types';
-
-/**
- * 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/services/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 ?? 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 (`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 ?? randomUUID();
-		const startTime = ctx.startTime ?? Date.now();
-		return runWithRequestContext(
-			{ logger: ctx.logger, requestId, startTime },
-			() => opts.next(),
-		);
-	});
-}

package/src/types.ts

@@ -1,92 +0,0 @@
-import type { EnvironmentParser } from '@geekmidas/envkit';
-import type { Logger } from '@geekmidas/logger';
-
-/**
- * Request context available to services.
- * Methods are guaranteed to return values when called within a request context.
- * Throws if called outside a request context (catches bugs early).
- */
-export interface ServiceContext {
-	/**
-	 * Get the current request's logger.
-	 *
-	 * Returns a **request-scoped proxy** that re-resolves the underlying logger
-	 * from AsyncLocalStorage on every call. This makes it safe for a singleton
-	 * service to capture the logger once (e.g. during `register()`) and reuse it
-	 * across requests — each log call routes to the current request's logger
-	 * instead of freezing the first request's logger.
-	 *
-	 * @throws Error if called outside a request context
-	 */
-	getLogger(): Logger;
-
-	/**
-	 * Get the current request ID.
-	 * @throws Error if called outside a request context
-	 */
-	getRequestId(): string;
-
-	/**
-	 * Get the current request's start time (from Date.now()).
-	 * Useful for calculating request duration.
-	 * @throws Error if called outside a request context
-	 */
-	getRequestStartTime(): number;
-
-	/**
-	 * Check if currently running inside a request context.
-	 * Use this to guard calls if you need to handle both cases.
-	 */
-	hasContext(): boolean;
-}
-
-/**
- * Options passed to service register method.
- */
-export interface ServiceRegisterOptions {
-	/** Environment parser for configuration */
-	envParser: EnvironmentParser<{}>;
-	/** Request context for logging and tracing */
-	context: ServiceContext;
-}
-
-/**
- * Service interface for the simplified service pattern.
- * Services are objects with a serviceName and register method.
- *
- * @template TName - The literal string type for the service name
- * @template TInstance - The type of the service instance that will be registered
- *
- * @example
- * ```typescript
- * const databaseService = {
- *   serviceName: 'database' as const,
- *   register({ envParser, context }: ServiceRegisterOptions) {
- *     const config = envParser.create((get) => ({
- *       url: get('DATABASE_URL').string()
- *     })).parse();
- *
- *     return {
- *       async query(sql: string) {
- *         const logger = context.getLogger();
- *         logger.debug({ sql }, 'Executing query');
- *         // ... execute query
- *       }
- *     };
- *   }
- * } satisfies Service<'database', DatabaseInstance>;
- * ```
- */
-export interface Service<TName extends string = string, TInstance = unknown> {
-	/**
-	 * Unique name for the service, used for lookup via services.get()
-	 */
-	serviceName: TName;
-	/**
-	 * Register method that returns the actual service instance.
-	 * Called once on first access, then cached.
-	 *
-	 * @param options - Registration options including envParser and context
-	 */
-	register(options: ServiceRegisterOptions): TInstance | Promise<TInstance>;
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "composite": true
-  },
-  "include": ["src/**/*"]
-}

package/tsdown.config.ts

@@ -1,13 +0,0 @@
-import { defineConfig } from 'tsdown';
-
-export default defineConfig({
-	entry: ['src/index.ts', 'src/context.ts', 'src/trpc.ts', 'src/middy.ts'],
-	clean: true,
-	outDir: 'dist',
-	format: ['cjs', 'esm'],
-	sourcemap: true,
-	dts: true,
-	outExtensions: (ctx) => ({
-		js: ctx.format === 'es' ? '.mjs' : '.cjs',
-	}),
-});