@geekmidas/services 9.0.2 → 10.0.0-alpha.0

package/src/__tests__/middy.spec.ts

@@ -1,218 +0,0 @@
-import { EnvironmentParser } from '@geekmidas/envkit';
-import type { Logger } from '@geekmidas/logger';
-import middy from '@middy/core';
-import type { Context } from 'aws-lambda';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { serviceContext } from '../context';
-import { addServices, requestContext, withServices } from '../middy';
-import { ServiceDiscovery } from '../ServiceDiscovery';
-import type { Service } from '../types';
-
-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()], {
-					logger: makeSpyLogger(),
-					envParser,
-				}),
-			);
-
-			await invoke(handler);
-
-			expect(greeting).toBe('hello');
-			expect(registeredRequestId).toBe('aws-req-1');
-		});
-	});
-});

package/src/__tests__/trpc.spec.ts

@@ -1,218 +0,0 @@
-import { EnvironmentParser } from '@geekmidas/envkit';
-import type { Logger } from '@geekmidas/logger';
-import { initTRPC } from '@trpc/server';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { serviceContext } from '../context';
-import { ServiceDiscovery } from '../ServiceDiscovery';
-import {
-	createRequestContextMiddleware,
-	createServicesMiddleware,
-} from '../trpc';
-import type { Service } from '../types';
-
-beforeEach(() => {
-	// ServiceDiscovery is a process-wide singleton that caches resolved
-	// instances. Reset so each test gets a fresh registry.
-	ServiceDiscovery.reset();
-});
-
-function makeLogger(): Logger {
-	const logger: Logger = {
-		debug: vi.fn(),
-		info: vi.fn(),
-		warn: vi.fn(),
-		error: vi.fn(),
-		fatal: vi.fn(),
-		trace: vi.fn(),
-		child: vi.fn(() => logger),
-	};
-	return logger;
-}
-
-describe('createServicesMiddleware (with envParser)', () => {
-	it('resolves services and merges them onto ctx', async () => {
-		const databaseService = {
-			serviceName: 'database' as const,
-			register: () => ({ query: (sql: string) => `result: ${sql}` }),
-		} satisfies Service<'database', { query: (sql: string) => string }>;
-
-		const t = initTRPC.context<{ logger: Logger }>().create();
-		const withServices = createServicesMiddleware(
-			t.middleware,
-			new EnvironmentParser({}),
-		);
-
-		const caller = t.router({
-			run: t.procedure
-				.use(withServices([databaseService]))
-				.query(({ ctx }) => ctx.database.query('select 1')),
-		});
-
-		const result = await caller.createCaller({ logger: makeLogger() }).run();
-
-		expect(result).toBe('result: select 1');
-	});
-
-	it('makes serviceContext.getLogger() readable from inside a service method', async () => {
-		let observedLogger: Logger | null = null;
-		const dbService = {
-			serviceName: 'database' as const,
-			register: () => ({
-				touch() {
-					observedLogger = serviceContext.getLogger();
-					observedLogger.info('touched');
-					return 'ok';
-				},
-			}),
-		} satisfies Service<'database', { touch: () => string }>;
-
-		const t = initTRPC.context<{ logger: Logger }>().create();
-		const withServices = createServicesMiddleware(
-			t.middleware,
-			new EnvironmentParser({}),
-		);
-
-		const requestLogger = makeLogger();
-
-		const caller = t.router({
-			run: t.procedure
-				.use(withServices([dbService]))
-				.query(({ ctx }) => ctx.database.touch()),
-		});
-
-		await caller.createCaller({ logger: requestLogger }).run();
-
-		// getLogger() returns a request-scoped proxy (not the raw logger), so we
-		// assert it delegates to the request logger rather than checking identity.
-		expect(observedLogger).not.toBeNull();
-		expect(requestLogger.info).toHaveBeenCalledWith('touched');
-	});
-
-	it('throws cleanly when service code runs outside the procedure', () => {
-		// Sanity check that serviceContext stays scoped to the procedure call —
-		// reads outside any procedure must throw.
-		expect(() => serviceContext.getLogger()).toThrow();
-	});
-});
-
-describe('createServicesMiddleware (context-supplied discovery)', () => {
-	it('uses ctx.serviceDiscovery when no envParser is provided', async () => {
-		const cacheService = {
-			serviceName: 'cache' as const,
-			register: () => ({ get: (key: string) => `cached:${key}` }),
-		} satisfies Service<'cache', { get: (key: string) => string }>;
-
-		type Ctx = { logger: Logger; serviceDiscovery: ServiceDiscovery };
-		const t = initTRPC.context<Ctx>().create();
-		const withServices = createServicesMiddleware<Ctx, object>(t.middleware);
-
-		const caller = t.router({
-			run: t.procedure
-				.use(withServices([cacheService]))
-				.query(({ ctx }) => ctx.cache.get('k')),
-		});
-
-		const discovery = ServiceDiscovery.getInstance(new EnvironmentParser({}));
-
-		const result = await caller
-			.createCaller({ logger: makeLogger(), serviceDiscovery: discovery })
-			.run();
-
-		expect(result).toBe('cached:k');
-	});
-});
-
-describe('createRequestContextMiddleware', () => {
-	it('exposes ctx.logger via serviceContext.getLogger() for the handler', async () => {
-		const t = initTRPC.context<{ logger: Logger }>().create();
-		const withRequestContext = createRequestContextMiddleware(t.middleware);
-
-		let observed: Logger | null = null;
-		const caller = t.router({
-			run: t.procedure.use(withRequestContext).query(() => {
-				observed = serviceContext.getLogger();
-				observed.info('handled');
-				return 'done';
-			}),
-		});
-
-		const requestLogger = makeLogger();
-		const result = await caller.createCaller({ logger: requestLogger }).run();
-
-		expect(result).toBe('done');
-		// The request-scoped proxy delegates to ctx.logger.
-		expect(observed).not.toBeNull();
-		expect(requestLogger.info).toHaveBeenCalledWith('handled');
-	});
-
-	it('auto-generates requestId and startTime when ctx does not provide them', async () => {
-		const t = initTRPC.context<{ logger: Logger }>().create();
-		const withRequestContext = createRequestContextMiddleware(t.middleware);
-
-		let requestId: string | null = null;
-		let startTime: number | null = null;
-
-		const caller = t.router({
-			run: t.procedure.use(withRequestContext).query(() => {
-				requestId = serviceContext.getRequestId();
-				startTime = serviceContext.getRequestStartTime();
-				return 'ok';
-			}),
-		});
-
-		await caller.createCaller({ logger: makeLogger() }).run();
-
-		expect(requestId).toBeTypeOf('string');
-		expect(requestId!.length).toBeGreaterThan(0);
-		expect(typeof startTime).toBe('number');
-	});
-
-	it('honors caller-supplied requestId and startTime when present on ctx', async () => {
-		type Ctx = { logger: Logger; requestId?: string; startTime?: number };
-		const t = initTRPC.context<Ctx>().create();
-		const withRequestContext = createRequestContextMiddleware(t.middleware);
-
-		let observedId: string | null = null;
-		let observedStart: number | null = null;
-
-		const caller = t.router({
-			run: t.procedure.use(withRequestContext).query(() => {
-				observedId = serviceContext.getRequestId();
-				observedStart = serviceContext.getRequestStartTime();
-				return 'ok';
-			}),
-		});
-
-		await caller
-			.createCaller({
-				logger: makeLogger(),
-				requestId: 'req_abc',
-				startTime: 12345,
-			})
-			.run();
-
-		expect(observedId).toBe('req_abc');
-		expect(observedStart).toBe(12345);
-	});
-});
-
-describe('tagging for tooling', () => {
-	it('attaches the resolved services tuple to the inner middleware', () => {
-		const svc = {
-			serviceName: 'sample' as const,
-			register: () => ({}),
-		} satisfies Service<'sample', {}>;
-
-		const t = initTRPC.context<{ logger: Logger }>().create();
-		const withServices = createServicesMiddleware(
-			t.middleware,
-			new EnvironmentParser({}),
-		);
-
-		const builder = withServices([svc]);
-		const middlewares = (
-			builder as unknown as { _middlewares: Array<{ _services?: Service[] }> }
-		)._middlewares;
-		expect(middlewares?.at(-1)?._services).toEqual([svc]);
-	});
-});

package/src/context.ts

@@ -1,222 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import type { Logger } from '@geekmidas/logger';
-import type { ServiceContext } from './types';
-
-/**
- * Internal storage for request context data.
- * Not exported - services use ServiceContext interface.
- */
-export interface RequestContextData {
-	logger: Logger;
-	requestId: string;
-	startTime: number;
-}
-
-/**
- * Internal AsyncLocalStorage instance for request context.
- * Not exported - use runWithRequestContext() to establish context
- * and serviceContext to access it.
- */
-const requestContextStorage = new AsyncLocalStorage<RequestContextData>();
-
-/**
- * Resolve the logger for the current request, or throw if there is none.
- */
-function resolveRequestLogger(): Logger {
-	const store = requestContextStorage.getStore();
-	if (!store) {
-		throw new Error(
-			'ServiceContext.getLogger() called outside request context. ' +
-				'Ensure code runs within runWithRequestContext().',
-		);
-	}
-	return store.logger;
-}
-
-/**
- * Create a Logger that re-resolves its underlying logger on every call instead
- * of capturing it once.
- *
- * This is what makes it safe for a **singleton** service to grab the logger a
- * single time (e.g. during `register()`, which `ServiceDiscovery` only runs
- * once and then caches) and reuse that reference for every request: each log
- * call resolves the *current* request's logger from `AsyncLocalStorage`, so
- * requests no longer inherit the first request's logger (and its `requestId`,
- * user bindings, etc.).
- *
- * Implemented as a `Proxy` rather than a fixed list of methods so it forwards
- * the *entire* surface of whatever logger is supplied — including members
- * beyond the base `Logger` interface (e.g. a richer pino-backed logger's
- * `flush()` or `level`) and any methods added to `Logger` in the future.
- *
- * @param bindings - `child()` bindings applied, in order, on top of the
- *   resolved logger before each call.
- */
-function createRequestScopedLogger(bindings: object[] = []): Logger {
-	// Memoise the resolved (optionally child) logger per underlying base logger
-	// so we don't rebuild the child chain on every access within a request.
-	// Recomputed whenever the current request's logger changes — there is no
-	// await between the check and use, so this is safe under concurrency.
-	let cachedBase: Logger | undefined;
-	let cachedResolved: Logger | undefined;
-
-	const resolve = (): Logger => {
-		const base = resolveRequestLogger();
-		if (base !== cachedBase) {
-			cachedBase = base;
-			cachedResolved = bindings.reduce<Logger>(
-				(log, obj) => log.child(obj),
-				base,
-			);
-		}
-		return cachedResolved as Logger;
-	};
-
-	return new Proxy({} as Logger, {
-		get(_target, prop) {
-			// `child()` must stay request-scoped: return a new proxy carrying the
-			// extra binding, NOT the underlying logger's child (which would freeze
-			// to the current request).
-			if (prop === 'child') {
-				return (obj: object) => createRequestScopedLogger([...bindings, obj]);
-			}
-			// Never look like a thenable, and don't answer symbol/inspection probes
-			// (util.inspect, Symbol.toPrimitive, etc.) with bound functions.
-			if (prop === 'then' || typeof prop === 'symbol') {
-				return undefined;
-			}
-			const value = (resolve() as unknown as Record<string, unknown>)[prop];
-			// Functions are re-resolved at *call* time so detached references
-			// (`const info = logger.info`) still target the current request's
-			// logger. Non-function members (e.g. `level`) forward as their live
-			// value on the current request's logger.
-			return typeof value === 'function'
-				? (...args: unknown[]) => {
-						// Re-resolve at call time so detached references target the
-						// current request's logger, and invoke with that logger as
-						// `this`: pino's log methods read internal state off the
-						// receiver (`this[Symbol(pino.msgPrefix)]`), so calling them
-						// unbound throws "Cannot read properties of undefined".
-						const resolved = resolve();
-						const fn = (resolved as unknown as Record<string, unknown>)[
-							prop
-						] as (...a: unknown[]) => unknown;
-						return fn.apply(resolved, args);
-					}
-				: value;
-		},
-		// Keep `'prop' in logger` / hasOwnProperty truthful against the underlying
-		// logger so feature-detection works.
-		has(_target, prop) {
-			if (prop === 'child') return true;
-			if (prop === 'then' || typeof prop === 'symbol') return false;
-			return prop in (resolve() as object);
-		},
-	});
-}
-
-/**
- * Stable, process-wide request-scoped logger proxy. Shared across requests on
- * purpose — it carries no request state itself, delegating to the current
- * `AsyncLocalStorage` store on each call.
- */
-const requestScopedLogger = createRequestScopedLogger();
-
-/**
- * ServiceContext implementation.
- * Singleton that reads from AsyncLocalStorage.
- * Methods throw if called outside a request context (catches bugs early).
- */
-export const serviceContext: ServiceContext = {
-	getLogger() {
-		// Throw eagerly if there is no context, preserving the "catch bugs early"
-		// contract for callers that read the logger at an unexpected time.
-		resolveRequestLogger();
-		// Return the shared proxy rather than the raw `store.logger`. A service
-		// that captures this once still logs against the correct per-request
-		// logger because the proxy re-resolves on every call.
-		return requestScopedLogger;
-	},
-
-	getRequestId() {
-		const store = requestContextStorage.getStore();
-		if (!store) {
-			throw new Error(
-				'ServiceContext.getRequestId() called outside request context. ' +
-					'Ensure code runs within runWithRequestContext().',
-			);
-		}
-		return store.requestId;
-	},
-
-	getRequestStartTime() {
-		const store = requestContextStorage.getStore();
-		if (!store) {
-			throw new Error(
-				'ServiceContext.getRequestStartTime() called outside request context. ' +
-					'Ensure code runs within runWithRequestContext().',
-			);
-		}
-		return store.startTime;
-	},
-
-	hasContext() {
-		return requestContextStorage.getStore() !== undefined;
-	},
-};
-
-/**
- * Run a function with request context.
- * Used by endpoint/function/subscriber adaptors.
- *
- * @param data - Request context data (logger, requestId, startTime)
- * @param fn - Function to run with context
- * @returns Result of the function
- *
- * @example
- * ```typescript
- * const result = await runWithRequestContext(
- *   { logger, requestId, startTime: Date.now() },
- *   async () => {
- *     // Inside here, serviceContext.getLogger() returns `logger`
- *     // serviceContext.getRequestId() returns `requestId`
- *     return await handleRequest();
- *   }
- * );
- * ```
- */
-export function runWithRequestContext<T>(
-	data: RequestContextData,
-	fn: () => T | Promise<T>,
-): T | Promise<T> {
-	return requestContextStorage.run(data, fn);
-}
-
-/**
- * Mutate the current async task's store so that subsequent code in this task
- * (and any descendants) sees the supplied request context.
- *
- * Unlike `runWithRequestContext`, this does not scope the context to a
- * callback — useful when the caller can't wrap a function, for example in a
- * Vitest fixture that suspends on `use()` and yields control to the test
- * runner before the test body executes.
- *
- * **Test setup only.** In production handlers, prefer `runWithRequestContext`
- * so the frame is automatically cleaned up.
- */
-export function enterRequestContext(data: RequestContextData): void {
-	requestContextStorage.enterWith(data);
-}
-
-/**
- * Clear the request context for the current async task. Pairs with
- * `enterRequestContext`. After calling, `serviceContext.hasContext()` returns
- * false for the remainder of the current async resource.
- */
-export function exitRequestContext(): void {
-	// AsyncLocalStorage<T>.enterWith requires T, but Node accepts undefined at
-	// runtime — passing it resets getStore() back to undefined.
-	(requestContextStorage as unknown as AsyncLocalStorage<unknown>).enterWith(
-		undefined,
-	);
-}

package/src/index.ts

@@ -1,17 +0,0 @@
-// Re-export types
-
-// Re-export context utilities
-export {
-	enterRequestContext,
-	exitRequestContext,
-	type RequestContextData,
-	runWithRequestContext,
-	serviceContext,
-} from './context';
-// Re-export ServiceDiscovery and utility types
-export {
-	type ExtractServiceNames,
-	ServiceDiscovery,
-	type ServiceRecord,
-} from './ServiceDiscovery';
-export type { Service, ServiceContext, ServiceRegisterOptions } from './types';