@geekmidas/constructs 7.0.1 → 9.1.0

package/src/endpoints/__tests__/EndpointBuilder.spec.ts

@@ -28,8 +28,10 @@ describe('EndpointBuilder', () => {
 			const builder = new EndpointBuilder('/users', 'GET');
 			const result = builder.description('Get all users');
 
-			expect(result).toBe(builder); // Should return this for chaining
-			expect((builder as any)._description).toBe('Get all users');
+			// The value lands on the returned builder, not on the one it came
+			// from — that is what keeps a configured base reusable.
+			expect((result as any)._description).toBe('Get all users');
+			expect((builder as any)._description).toBeUndefined();
 		});
 
 		it('should pass description to endpoint', () => {
@@ -46,8 +48,8 @@ describe('EndpointBuilder', () => {
 			const builder = new EndpointBuilder('/users', 'POST');
 			const result = builder.status(201);
 
-			expect(result).toBe(builder); // Should return this for chaining
-			expect((builder as any)._status).toBe(201);
+			expect((result as any)._status).toBe(201);
+			expect((builder as any)._status).toBeUndefined();
 		});
 
 		it('should pass status to endpoint', () => {
@@ -384,8 +386,10 @@ describe('EndpointBuilder', () => {
 			const builder = new EndpointBuilder('/test', 'GET');
 			const result = builder.authorize(authFn);
 
-			expect(result).toBe(builder);
-			expect((builder as any)._authorize).toBe(authFn);
+			expect((result as any)._authorize).toBe(authFn);
+			// The base keeps whatever it had — a fresh builder carries a default
+			// authorize, so the check is that it did not take the new one.
+			expect((builder as any)._authorize).not.toBe(authFn);
 		});
 
 		it('should pass .authorize() function to endpoint', () => {
@@ -447,8 +451,12 @@ describe('EndpointBuilder', () => {
 			const builder2 = builder1.description('Test');
 			const builder3 = builder2.status(200);
 
-			expect(builder1).toBe(builder2);
-			expect(builder2).toBe(builder3);
+			// Each step is a new builder that accumulates what came before.
+			expect(builder3).toBeInstanceOf(EndpointBuilder);
+			expect((builder3 as any)._description).toBe('Test');
+			expect((builder3 as any)._status).toBe(200);
+			expect(builder2).not.toBe(builder1);
+			expect(builder3).not.toBe(builder2);
 		});
 	});
 

package/src/functions/AWSLambdaFunction.ts

@@ -13,6 +13,7 @@ import { runWithRequestContext } from '@geekmidas/services';
 import middy, { type MiddlewareObj } from '@middy/core';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Context, Handler } from 'aws-lambda';
+import { startMonitors } from '../monitor';
 import type { Function, FunctionHandler } from './Function';
 import { FunctionBuilder } from './FunctionBuilder';
 import { FunctionExecutionWrapper } from './FunctionExecutionWrapper';
@@ -127,6 +128,10 @@ export class AWSLambdaFunction<
 			onError: (req) => {
 				const logger = req.event?.logger || this.fn.logger;
 				logger.error(req.error || {}, 'Error processing function');
+				// Kept for the monitors, which otherwise only see the wrapped error.
+				if (req.event) {
+					(req.event as any).__error = req.error;
+				}
 
 				// Re-throw the wrapped error to let Lambda handle it
 				throw wrapError(req.error);
@@ -338,8 +343,29 @@ export class AWSLambdaFunction<
 			const requestId = context.awsRequestId;
 			const logger = this.fn.logger.child({ requestId }) as TLogger;
 
-			return runWithRequestContext({ logger, requestId, startTime }, () =>
-				chain(event as Parameters<typeof chain>[0], context),
+			return runWithRequestContext(
+				{ logger, requestId, startTime },
+				async () => {
+					// Around the whole chain, not as a middleware: a middleware's
+					// `after` runs before audits flush and events publish, and its
+					// `onError` never runs once `error()` rethrows.
+					const monitor = await startMonitors(
+						this.fn,
+						this.serviceDiscovery,
+						logger,
+					);
+					try {
+						const output = await chain(
+							event as Parameters<typeof chain>[0],
+							context,
+						);
+						await monitor.success(output);
+						return output;
+					} catch (error) {
+						await monitor.failure((event as any)?.__error ?? error);
+						throw error;
+					}
+				},
 			);
 		};
 

package/src/functions/BaseFunctionBuilder.ts

@@ -10,6 +10,8 @@ import type { Service } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import get from 'lodash.get';
 import { ConstructType } from '../Construct';
+import { cloneWith } from '../clone';
+import { addMonitor, type MonitorService } from '../monitor';
 
 const DEFAULT_LOGGER = new ConsoleLogger() as any;
 
@@ -36,6 +38,7 @@ export abstract class BaseFunctionBuilder<
 	protected _publisher?: Service<TEventPublisherServiceName, TEventPublisher>;
 	protected _auditorStorage?: Service<TAuditStorageServiceName, TAuditStorage>;
 	protected _databaseService?: Service<TDatabaseServiceName, TDatabase>;
+	public _monitors: MonitorService[] = [];
 
 	static isStandardSchemaV1(s: unknown): s is StandardSchemaV1 {
 		const schema = (s as StandardSchemaV1)['~standard'];
@@ -81,19 +84,27 @@ export abstract class BaseFunctionBuilder<
 	abstract logger<T extends Logger>(logger: T): any;
 
 	timeout(timeout: number): this {
-		this._timeout = timeout;
-		return this;
+		return cloneWith(this, { _timeout: timeout });
 	}
 
 	abstract output<T extends StandardSchemaV1>(schema: T): any;
 
 	abstract input<T extends ComposableStandardSchema>(schema: T): any;
 
+	/**
+	 * Report each run to a monitor — a heartbeat, an uptime check, an error
+	 * tracker. Can be called more than once; every monitor is told.
+	 */
+	monitor(monitor: MonitorService): this {
+		return cloneWith(this, { _monitors: addMonitor(this._monitors, monitor) });
+	}
+
 	event<TEvent extends MappedEvent<TEventPublisher, OutSchema>>(
 		event: TEvent,
 	): this {
-		this._events.push(event);
-		return this;
+		// Replaced rather than pushed: a clone shares whatever array the field
+		// points at, so an in-place push would be seen by the base it came from.
+		return cloneWith(this, { _events: [...this._events, event] });
 	}
 
 	publisher<T extends EventPublisher<any>, TName extends string>(
@@ -110,12 +121,12 @@ export abstract class BaseFunctionBuilder<
 		TDatabase,
 		TDatabaseServiceName
 	> {
-		this._publisher = publisher as unknown as Service<
-			TEventPublisherServiceName,
-			TEventPublisher
-		>;
-
-		return this as unknown as BaseFunctionBuilder<
+		return cloneWith(this, {
+			_publisher: publisher as unknown as Service<
+				TEventPublisherServiceName,
+				TEventPublisher
+			>,
+		}) as unknown as BaseFunctionBuilder<
 			TInput,
 			OutSchema,
 			TServices,
@@ -143,12 +154,12 @@ export abstract class BaseFunctionBuilder<
 		TDatabase,
 		TDatabaseServiceName
 	> {
-		this._auditorStorage = storage as unknown as Service<
-			TAuditStorageServiceName,
-			TAuditStorage
-		>;
-
-		return this as unknown as BaseFunctionBuilder<
+		return cloneWith(this, {
+			_auditorStorage: storage as unknown as Service<
+				TAuditStorageServiceName,
+				TAuditStorage
+			>,
+		}) as unknown as BaseFunctionBuilder<
 			TInput,
 			OutSchema,
 			TServices,
@@ -180,12 +191,12 @@ export abstract class BaseFunctionBuilder<
 		T,
 		TName
 	> {
-		this._databaseService = service as unknown as Service<
-			TDatabaseServiceName,
-			TDatabase
-		>;
-
-		return this as unknown as BaseFunctionBuilder<
+		return cloneWith(this, {
+			_databaseService: service as unknown as Service<
+				TDatabaseServiceName,
+				TDatabase
+			>,
+		}) as unknown as BaseFunctionBuilder<
 			TInput,
 			OutSchema,
 			TServices,

package/src/functions/FunctionBuilder.ts

@@ -1,17 +1,15 @@
 import type { AuditableAction, AuditStorage } from '@geekmidas/audit';
 import type { EventPublisher } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
-import { ConsoleLogger } from '@geekmidas/logger/console';
 import type { ComposableStandardSchema } from '@geekmidas/schema';
 import type { Service } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import uniqBy from 'lodash.uniqby';
 import { ConstructType } from '../Construct';
+import { cloneWith } from '../clone';
 import { BaseFunctionBuilder } from './BaseFunctionBuilder';
 import { Function, type FunctionHandler } from './Function';
 
-const DEFAULT_LOGGER = new ConsoleLogger() as any;
-
 export class FunctionBuilder<
 	TInput extends ComposableStandardSchema,
 	OutSchema extends StandardSchemaV1 | undefined = undefined,
@@ -46,13 +44,11 @@ export class FunctionBuilder<
 	}
 
 	override timeout(timeout: number): this {
-		this._timeout = timeout;
-		return this;
+		return cloneWith(this, { _timeout: timeout });
 	}
 
 	memorySize(memorySize: number): this {
-		this._memorySize = memorySize;
-		return this;
+		return cloneWith(this, { _memorySize: memorySize });
 	}
 
 	output<T extends StandardSchemaV1>(
@@ -70,9 +66,9 @@ export class FunctionBuilder<
 		TDatabaseServiceName,
 		TAuditAction
 	> {
-		this.outputSchema = schema as unknown as OutSchema;
-
-		return this as unknown as FunctionBuilder<
+		return cloneWith(this, {
+			outputSchema: schema as unknown as OutSchema,
+		}) as unknown as FunctionBuilder<
 			TInput,
 			T,
 			TServices,
@@ -102,9 +98,9 @@ export class FunctionBuilder<
 		TDatabaseServiceName,
 		TAuditAction
 	> {
-		this.inputSchema = schema as unknown as TInput;
-
-		return this as unknown as FunctionBuilder<
+		return cloneWith(this, {
+			inputSchema: schema as unknown as TInput,
+		}) as unknown as FunctionBuilder<
 			T,
 			OutSchema,
 			TServices,
@@ -134,12 +130,12 @@ export class FunctionBuilder<
 		TDatabaseServiceName,
 		TAuditAction
 	> {
-		this._services = uniqBy(
-			[...this._services, ...services],
-			(s) => s.serviceName,
-		) as TServices;
-
-		return this as unknown as FunctionBuilder<
+		return cloneWith(this, {
+			_services: uniqBy(
+				[...this._services, ...services],
+				(s) => s.serviceName,
+			) as TServices,
+		}) as unknown as FunctionBuilder<
 			TInput,
 			OutSchema,
 			[...TServices, ...T],
@@ -169,9 +165,9 @@ export class FunctionBuilder<
 		TDatabaseServiceName,
 		TAuditAction
 	> {
-		this._logger = logger as unknown as TLogger;
-
-		return this as unknown as FunctionBuilder<
+		return cloneWith(this, {
+			_logger: logger as unknown as TLogger,
+		}) as unknown as FunctionBuilder<
 			TInput,
 			OutSchema,
 			TServices,
@@ -201,12 +197,12 @@ export class FunctionBuilder<
 		TDatabaseServiceName,
 		TAuditAction
 	> {
-		this._publisher = publisher as unknown as Service<
-			TEventPublisherServiceName,
-			TEventPublisher
-		>;
-
-		return this as unknown as FunctionBuilder<
+		return cloneWith(this, {
+			_publisher: publisher as unknown as Service<
+				TEventPublisherServiceName,
+				TEventPublisher
+			>,
+		}) as unknown as FunctionBuilder<
 			TInput,
 			OutSchema,
 			TServices,
@@ -236,12 +232,12 @@ export class FunctionBuilder<
 		TDatabaseServiceName,
 		TAuditAction
 	> {
-		this._auditorStorage = storage as unknown as Service<
-			TAuditStorageServiceName,
-			TAuditStorage
-		>;
-
-		return this as unknown as FunctionBuilder<
+		return cloneWith(this, {
+			_auditorStorage: storage as unknown as Service<
+				TAuditStorageServiceName,
+				TAuditStorage
+			>,
+		}) as unknown as FunctionBuilder<
 			TInput,
 			OutSchema,
 			TServices,
@@ -307,12 +303,12 @@ export class FunctionBuilder<
 		TName,
 		TAuditAction
 	> {
-		this._databaseService = service as unknown as Service<
-			TDatabaseServiceName,
-			TDatabase
-		>;
-
-		return this as unknown as FunctionBuilder<
+		return cloneWith(this, {
+			_databaseService: service as unknown as Service<
+				TDatabaseServiceName,
+				TDatabase
+			>,
+		}) as unknown as FunctionBuilder<
 			TInput,
 			OutSchema,
 			TServices,
@@ -374,17 +370,11 @@ export class FunctionBuilder<
 			this._databaseService,
 		);
 
-		// Reset builder state after creating the function to prevent pollution
-		this._services = [] as Service[] as TServices;
-		this._logger = DEFAULT_LOGGER;
-		this._events = [];
-		this._publisher = undefined;
-		this._auditorStorage = undefined;
-		this._databaseService = undefined;
-		this.inputSchema = undefined;
-		this.outputSchema = undefined;
-		this._timeout = undefined;
-		this._memorySize = undefined;
+		// No reset. `.handle()` reads this builder and leaves it alone, so a
+		// configured base keeps its configuration for every construct built
+		// from it. The reset that used to be here wiped the base on first use.
+
+		func.monitors = this._monitors;
 
 		return func;
 	}

package/src/functions/TestFunctionAdaptor.ts

@@ -15,6 +15,7 @@ import {
 	type ServiceRecord,
 } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { startMonitors } from '../monitor';
 import { publishEvents } from '../publisher';
 import type { Function } from './Function';
 import { FunctionBuilder } from './FunctionBuilder';
@@ -159,42 +160,76 @@ export class TestFunctionAdaptor<
 		const startTime = Date.now();
 
 		return runWithRequestContext({ logger, requestId, startTime }, async () => {
-			// Execute the function
-			const response = await this.fn.fn({
-				input: parsedInput,
-				services,
+			const monitor = await startMonitors(
+				this.fn,
+				this.serviceDiscovery,
 				logger,
-				db,
-				auditor,
-			} as any);
-
-			// Parse output if schema is provided
-			const output = await this.fn.parseOutput(response);
-
-			// Flush audits if any were recorded
-			if (auditor) {
-				const records = auditor.getRecords();
-				if (records.length > 0) {
-					logger.debug(
-						{ auditCount: records.length },
-						'Flushing function audits',
-					);
-					await auditor.flush();
-				}
+			);
+			try {
+				const output = await this.run({
+					parsedInput,
+					services,
+					logger,
+					db,
+					auditor,
+				});
+				await monitor.success(output);
+				return output;
+			} catch (error) {
+				await monitor.failure(error);
+				throw error;
+			}
+		}) as Promise<InferStandardSchema<TOutSchema>>;
+	}
+
+	private async run({
+		parsedInput,
+		services,
+		logger,
+		db,
+		auditor,
+	}: {
+		parsedInput: unknown;
+		services: ServiceRecord<TServices>;
+		logger: TLogger;
+		db: TDatabase | undefined;
+		auditor: Auditor<TAuditAction> | undefined;
+	}): Promise<InferStandardSchema<TOutSchema>> {
+		// Execute the function
+		const response = await this.fn.fn({
+			input: parsedInput,
+			services,
+			logger,
+			db,
+			auditor,
+		} as any);
+
+		// Parse output if schema is provided
+		const output = await this.fn.parseOutput(response);
+
+		// Flush audits if any were recorded
+		if (auditor) {
+			const records = auditor.getRecords();
+			if (records.length > 0) {
+				logger.debug(
+					{ auditCount: records.length },
+					'Flushing function audits',
+				);
+				await auditor.flush();
 			}
+		}
 
-			// Register publisher service if provided in context
+		// Register publisher service if provided in context
 
-			await publishEvents(
-				logger,
-				this.serviceDiscovery,
-				this.fn.events,
-				output,
-				this.fn.publisherService,
-			);
+		await publishEvents(
+			logger,
+			this.serviceDiscovery,
+			this.fn.events,
+			output,
+			this.fn.publisherService,
+		);
 
-			return output;
-		}) as Promise<InferStandardSchema<TOutSchema>>;
+		return output;
 	}
 }
 

package/src/functions/__tests__/FunctionBuilder.state-isolation.spec.ts

@@ -31,6 +31,8 @@ const ServiceB = {
 	},
 } satisfies Service<'b', any>;
 
+const customLogger = new ConsoleLogger({ app: 'reusable-base' });
+
 describe('FunctionBuilder - State Isolation', () => {
 	describe('singleton instance state reset', () => {
 		it('should reset services after handle() is called', () => {
@@ -122,25 +124,26 @@ describe('FunctionBuilder - State Isolation', () => {
 		it('should not share references between different builder chains', () => {
 			const f = new FunctionBuilder();
 
-			// Start two separate chains
+			// Two chains off one base. They used to be the *same object* — every
+			// method mutated the base and returned it — so chain 1's function came
+			// out holding chain 2's services as well, and the base only survived
+			// because `.handle()` wiped it afterwards. That wipe is also what made
+			// a configured base unusable twice.
 			const builder1 = f.services([ServiceA]);
 			const builder2 = f.services([ServiceB]);
 
-			// They should be the same instance (singleton)
-			expect(builder1).toBe(builder2);
-			expect(builder1).toBe(f);
+			expect(builder1).not.toBe(builder2);
+			expect(builder1).not.toBe(f);
 
-			// But after handle, state is reset
 			const fn1 = builder1.handle(async () => ({}));
+			const fn2 = builder2.handle(async () => ({}));
 
-			// Now builder2 should have reset state
-			expect((builder2 as any)._services).toEqual([]);
-
-			// Add services again
-			const fn2 = builder2.services([ServiceB]).handle(async () => ({}));
-
-			expect(fn1.services.map((s) => s.serviceName)).toEqual(['a', 'b']);
+			// Each function gets exactly what its own chain declared.
+			expect(fn1.services.map((s) => s.serviceName)).toEqual(['a']);
 			expect(fn2.services.map((s) => s.serviceName)).toEqual(['b']);
+
+			// And the base is untouched, so it stays reusable.
+			expect((f as any)._services).toEqual([]);
 		});
 	});
 
@@ -204,4 +207,44 @@ describe('FunctionBuilder - State Isolation', () => {
 			expect((fn2 as any).auditorStorageService).toBeUndefined();
 		});
 	});
+
+	describe('a configured base, reused', () => {
+		it('carries its configuration into every function built from it', () => {
+			const base = new FunctionBuilder().logger(customLogger).timeout(60_000);
+
+			const first = base.services([ServiceA]).handle(async () => ({}));
+			const second = base.services([ServiceB]).handle(async () => ({}));
+
+			// The point of the whole shape: `const base = f.logger(log)` is a base you
+			// can keep. It used to survive exactly one `.handle()` — the reset put
+			// the logger and the timeout back to their defaults — so the second
+			// function built from it silently logged somewhere else and timed out
+			// on a different clock.
+			for (const built of [first, second]) {
+				expect(built.logger).toBe(customLogger);
+				expect(built.timeout).toBe(60_000);
+			}
+
+			// And each still gets only what its own chain declared.
+			expect(first.services.map((s) => s.serviceName)).toEqual(['a']);
+			expect(second.services.map((s) => s.serviceName)).toEqual(['b']);
+		});
+
+		it('persists configuration when handle() is called on the base itself', () => {
+			const base = new FunctionBuilder().logger(customLogger).timeout(60_000);
+
+			// No clone in between: `.handle()` is called straight on the base,
+			// twice. Cloning the config methods was not enough on its own —
+			// `.handle()` still ran a reset block that wiped whatever it was
+			// called on, so the second function came back on the default logger and
+			// the default timeout.
+			const first = base.handle(async () => ({}));
+			const second = base.handle(async () => ({}));
+
+			for (const built of [first, second]) {
+				expect(built.logger).toBe(customLogger);
+				expect(built.timeout).toBe(60_000);
+			}
+		});
+	});
 });

package/src/index.ts

@@ -8,6 +8,12 @@ export {
 	snifferContext,
 	sniffService,
 } from './Construct';
+// Monitoring interface
+export type {
+	ConstructMonitor,
+	MonitorContext,
+	MonitorService,
+} from './monitor';
 // Telemetry interface
 export type {
 	Telemetry,