@geekmidas/constructs 0.3.1 → 0.5.0

package/dist/telemetry-BTaiRqPo.d.cts

@@ -0,0 +1,95 @@
+import { Context } from "aws-lambda";
+
+//#region src/telemetry.d.ts
+
+/**
+ * Context object returned by onRequestStart, passed to subsequent hooks
+ */
+interface TelemetryContext {
+  /**
+   * Any data the telemetry implementation needs to track across the request lifecycle
+   */
+  [key: string]: unknown;
+}
+/**
+ * Request information passed to telemetry hooks
+ */
+interface TelemetryRequest {
+  /**
+   * The raw Lambda event
+   */
+  event: any;
+  /**
+   * The Lambda context
+   */
+  context: Context;
+}
+/**
+ * Response information passed to onRequestEnd
+ */
+interface TelemetryResponse {
+  /**
+   * HTTP status code
+   */
+  statusCode: number;
+  /**
+   * Response body (may be stringified JSON)
+   */
+  body?: string;
+  /**
+   * Response headers
+   */
+  headers?: Record<string, string>;
+}
+/**
+ * Telemetry interface for instrumenting endpoint requests
+ *
+ * @example
+ * ```typescript
+ * const telemetry: Telemetry = {
+ *   onRequestStart(req) {
+ *     const span = tracer.startSpan('http.request');
+ *     return { span };
+ *   },
+ *   onRequestEnd(ctx, response) {
+ *     ctx.span.setStatus(response.statusCode);
+ *     ctx.span.end();
+ *   },
+ *   onRequestError(ctx, error) {
+ *     ctx.span.recordException(error);
+ *     ctx.span.end();
+ *   },
+ * };
+ *
+ * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {
+ *   telemetry,
+ * });
+ * ```
+ */
+interface Telemetry {
+  /**
+   * Called at the start of each request
+   *
+   * @param request - The incoming request information
+   * @returns Context object that will be passed to onRequestEnd/onRequestError
+   */
+  onRequestStart(request: TelemetryRequest): TelemetryContext;
+  /**
+   * Called when the request completes successfully
+   *
+   * @param ctx - The context returned by onRequestStart
+   * @param response - The response information
+   */
+  onRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void;
+  /**
+   * Called when the request fails with an error
+   *
+   * @param ctx - The context returned by onRequestStart
+   * @param error - The error that occurred
+   */
+  onRequestError(ctx: TelemetryContext, error: Error): void;
+}
+//# sourceMappingURL=telemetry.d.ts.map
+//#endregion
+export { Telemetry, TelemetryContext, TelemetryRequest, TelemetryResponse };
+//# sourceMappingURL=telemetry-BTaiRqPo.d.cts.map

package/dist/telemetry-BTaiRqPo.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-BTaiRqPo.d.cts","names":[],"sources":["../src/telemetry.ts"],"sourcesContent":[],"mappings":";;;;;;;AA6FmB,UAlFF,gBAAA,CAkFE;EAAgB;;;EAQgB,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;UAhFlC,gBAAA;;;;;;;;WASP;;;;;UAMO,iBAAA;;;;;;;;;;;;YAcN;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4BM,SAAA;;;;;;;0BAOQ,mBAAmB;;;;;;;oBAQzB,4BAA4B;;;;;;;sBAQ1B,yBAAyB"}

package/dist/telemetry-yAHf5yDs.d.mts

@@ -0,0 +1,95 @@
+import { Context } from "aws-lambda";
+
+//#region src/telemetry.d.ts
+
+/**
+ * Context object returned by onRequestStart, passed to subsequent hooks
+ */
+interface TelemetryContext {
+  /**
+   * Any data the telemetry implementation needs to track across the request lifecycle
+   */
+  [key: string]: unknown;
+}
+/**
+ * Request information passed to telemetry hooks
+ */
+interface TelemetryRequest {
+  /**
+   * The raw Lambda event
+   */
+  event: any;
+  /**
+   * The Lambda context
+   */
+  context: Context;
+}
+/**
+ * Response information passed to onRequestEnd
+ */
+interface TelemetryResponse {
+  /**
+   * HTTP status code
+   */
+  statusCode: number;
+  /**
+   * Response body (may be stringified JSON)
+   */
+  body?: string;
+  /**
+   * Response headers
+   */
+  headers?: Record<string, string>;
+}
+/**
+ * Telemetry interface for instrumenting endpoint requests
+ *
+ * @example
+ * ```typescript
+ * const telemetry: Telemetry = {
+ *   onRequestStart(req) {
+ *     const span = tracer.startSpan('http.request');
+ *     return { span };
+ *   },
+ *   onRequestEnd(ctx, response) {
+ *     ctx.span.setStatus(response.statusCode);
+ *     ctx.span.end();
+ *   },
+ *   onRequestError(ctx, error) {
+ *     ctx.span.recordException(error);
+ *     ctx.span.end();
+ *   },
+ * };
+ *
+ * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {
+ *   telemetry,
+ * });
+ * ```
+ */
+interface Telemetry {
+  /**
+   * Called at the start of each request
+   *
+   * @param request - The incoming request information
+   * @returns Context object that will be passed to onRequestEnd/onRequestError
+   */
+  onRequestStart(request: TelemetryRequest): TelemetryContext;
+  /**
+   * Called when the request completes successfully
+   *
+   * @param ctx - The context returned by onRequestStart
+   * @param response - The response information
+   */
+  onRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void;
+  /**
+   * Called when the request fails with an error
+   *
+   * @param ctx - The context returned by onRequestStart
+   * @param error - The error that occurred
+   */
+  onRequestError(ctx: TelemetryContext, error: Error): void;
+}
+//# sourceMappingURL=telemetry.d.ts.map
+//#endregion
+export { Telemetry, TelemetryContext, TelemetryRequest, TelemetryResponse };
+//# sourceMappingURL=telemetry-yAHf5yDs.d.mts.map

package/dist/telemetry-yAHf5yDs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-yAHf5yDs.d.mts","names":[],"sources":["../src/telemetry.ts"],"sourcesContent":[],"mappings":";;;;;;;AA6FmB,UAlFF,gBAAA,CAkFE;EAAgB;;;EAQgB,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;UAhFlC,gBAAA;;;;;;;;WASP;;;;;UAMO,iBAAA;;;;;;;;;;;;YAcN;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4BM,SAAA;;;;;;;0BAOQ,mBAAmB;;;;;;;oBAQzB,4BAA4B;;;;;;;sBAQ1B,yBAAyB"}

package/dist/telemetry.d.cts

@@ -0,0 +1,2 @@
+import { Telemetry, TelemetryContext, TelemetryRequest, TelemetryResponse } from "./telemetry-BTaiRqPo.cjs";
+export { Telemetry, TelemetryContext, TelemetryRequest, TelemetryResponse };

package/dist/telemetry.d.mts

@@ -0,0 +1,2 @@
+import { Telemetry, TelemetryContext, TelemetryRequest, TelemetryResponse } from "./telemetry-yAHf5yDs.mjs";
+export { Telemetry, TelemetryContext, TelemetryRequest, TelemetryResponse };

package/dist/types-B5H3piDg.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"types-B5H3piDg.d.cts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";KAAY,6BAAA,MACE,CADF,IACO,CADQ,CACN,CADM,CAAA,SAAA,SAAA,GAAA,KAAA,GACyB,CADzB,GAC6B,CAD7B,CAC+B,CAD/B,CAAA,EAAA;AACb,KAGF,UAAA,GAHE,KAAA,GAAA,MAAA,GAAA,KAAA,GAAA,OAAA,GAAA,QAAA,GAAA,SAAA;AAAK,KAWP,eAXO,CAAA,UAWmB,UAXnB,CAAA,GAWiC,SAXjC,CAW2C,CAX3C,CAAA"}
+{"version":3,"file":"types-B5H3piDg.d.cts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";KAAY,6BAAA,MACC,CADD,IACM,CADS,CACP,CADO,CAAA,SAAA,SAAA,GAAA,KAAA,GACwB,CADxB,GAC4B,CAD5B,CAC8B,CAD9B,CAAA,EAAA;AACd,KAGD,UAAA,GAHC,KAAA,GAAA,MAAA,GAAA,KAAA,GAAA,OAAA,GAAA,QAAA,GAAA,SAAA;AAAK,KAWN,eAXM,CAAA,UAWoB,UAXpB,CAAA,GAWkC,SAXlC,CAW4C,CAX5C,CAAA"}

package/dist/{types-DdIlpxAd.d.mts → types-Dw-iLd3Y.d.mts}

@@ -6,4 +6,4 @@ type LowerHttpMethod<T extends HttpMethod> = Lowercase<T>;
 
 //#endregion
 export { HttpMethod, LowerHttpMethod, RemoveUndefined };
-//# sourceMappingURL=types-DdIlpxAd.d.mts.map
+//# sourceMappingURL=types-Dw-iLd3Y.d.mts.map

package/dist/types-Dw-iLd3Y.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-Dw-iLd3Y.d.mts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";KAAY,6BAAA,MACC,CADD,IACM,CADS,CACP,CADO,CAAA,SAAA,SAAA,GAAA,KAAA,GACwB,CADxB,GAC4B,CAD5B,CAC8B,CAD9B,CAAA,EAAA;AACd,KAGD,UAAA,GAHC,KAAA,GAAA,MAAA,GAAA,KAAA,GAAA,OAAA,GAAA,QAAA,GAAA,SAAA;AAAK,KAWN,eAXM,CAAA,UAWoB,UAXpB,CAAA,GAWkC,SAXlC,CAW4C,CAX5C,CAAA"}

package/dist/types.d.mts

@@ -1,2 +1,2 @@
-import { HttpMethod, LowerHttpMethod, RemoveUndefined } from "./types-DdIlpxAd.mjs";
+import { HttpMethod, LowerHttpMethod, RemoveUndefined } from "./types-Dw-iLd3Y.mjs";
 export { HttpMethod, LowerHttpMethod, RemoveUndefined };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/constructs",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -77,32 +77,32 @@
     "kysely": "~0.28.8",
     "pg": "~8.16.3",
     "zod": "~4.1.13",
-    "@geekmidas/audit": "^0.1.0",
-    "@geekmidas/cache": "^0.1.0",
-    "@geekmidas/db": "^0.2.0",
-    "@geekmidas/envkit": "^0.2.0",
+    "@geekmidas/audit": "^0.2.0",
+    "@geekmidas/cache": "^0.2.0",
     "@geekmidas/errors": "^0.1.0",
-    "@geekmidas/events": "^0.1.0",
-    "@geekmidas/rate-limit": "^0.2.0",
-    "@geekmidas/services": "^0.1.0",
-    "@geekmidas/logger": "^0.3.0",
+    "@geekmidas/envkit": "^0.3.0",
+    "@geekmidas/db": "^0.3.0",
+    "@geekmidas/events": "^0.2.0",
+    "@geekmidas/logger": "^0.4.0",
     "@geekmidas/schema": "^0.1.0",
-    "@geekmidas/testkit": "^0.4.0"
+    "@geekmidas/services": "^0.2.0",
+    "@geekmidas/testkit": "^0.6.0",
+    "@geekmidas/rate-limit": "^0.3.0"
   },
   "peerDependencies": {
     "@middy/core": ">=6.3.1",
     "@types/aws-lambda": ">=8.10.92",
     "hono": ">=4.8.2",
-    "@geekmidas/audit": "^0.1.0",
-    "@geekmidas/cache": "^0.1.0",
-    "@geekmidas/db": "^0.2.0",
-    "@geekmidas/envkit": "^0.2.0",
+    "@geekmidas/audit": "^0.2.0",
+    "@geekmidas/cache": "^0.2.0",
+    "@geekmidas/db": "^0.3.0",
+    "@geekmidas/envkit": "^0.3.0",
+    "@geekmidas/events": "^0.2.0",
+    "@geekmidas/rate-limit": "^0.3.0",
     "@geekmidas/errors": "^0.1.0",
-    "@geekmidas/events": "^0.1.0",
-    "@geekmidas/logger": "^0.3.0",
-    "@geekmidas/rate-limit": "^0.2.0",
+    "@geekmidas/logger": "^0.4.0",
     "@geekmidas/schema": "^0.1.0",
-    "@geekmidas/services": "^0.1.0"
+    "@geekmidas/services": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "@geekmidas/audit": {

package/src/Construct.ts

@@ -2,7 +2,7 @@ import type { AuditStorage } from '@geekmidas/audit';
 import { SnifferEnvironmentParser } from '@geekmidas/envkit/sniffer';
 import type { EventPublisher, MappedEvent } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
-import type { Service } from '@geekmidas/services';
+import type { Service, ServiceContext } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import compact from 'lodash.compact';
 
@@ -10,102 +10,133 @@ import compact from 'lodash.compact';
 // Key: service class/constructor, Value: array of env var names
 const serviceEnvCache = new Map<Service, string[]>();
 
+/**
+ * Noop context for environment sniffing.
+ * Used when calling service.register() to detect env vars without a real request.
+ * Returns dummy values since services should only use context in instance methods,
+ * not during registration.
+ */
+const snifferContext: ServiceContext = {
+	getLogger() {
+		// Return a noop logger for sniffing - services shouldn't log during registration
+		return {
+			debug: () => {},
+			info: () => {},
+			warn: () => {},
+			error: () => {},
+			child: () => snifferContext.getLogger(),
+		} as unknown as Logger;
+	},
+	getRequestId() {
+		return 'sniffer-context';
+	},
+	getRequestStartTime() {
+		return Date.now();
+	},
+	hasContext() {
+		return false;
+	},
+};
+
 export abstract class Construct<
-  TLogger extends Logger = Logger,
-  TServiceName extends string = string,
-  T extends EventPublisher<any> | undefined = undefined,
-  OutSchema extends StandardSchemaV1 | undefined = undefined,
-  TServices extends Service[] = [],
-  TAuditStorageServiceName extends string = string,
-  TAuditStorage extends AuditStorage | undefined = undefined,
+	TLogger extends Logger = Logger,
+	TServiceName extends string = string,
+	T extends EventPublisher<any> | undefined = undefined,
+	OutSchema extends StandardSchemaV1 | undefined = undefined,
+	TServices extends Service[] = [],
+	TAuditStorageServiceName extends string = string,
+	TAuditStorage extends AuditStorage | undefined = undefined,
 > {
-  constructor(
-    public readonly type: ConstructType,
-    public readonly logger: TLogger,
-    public readonly services: TServices,
-    public readonly events: MappedEvent<T, any>[] = [],
+	constructor(
+		public readonly type: ConstructType,
+		public readonly logger: TLogger,
+		public readonly services: TServices,
+		public readonly events: MappedEvent<T, any>[] = [],
 
-    public readonly publisherService?: Service<TServiceName, T>,
-    public outputSchema?: OutSchema,
-    public readonly timeout?: number,
-    public readonly memorySize?: number,
-    public readonly auditorStorageService?: Service<
-      TAuditStorageServiceName,
-      TAuditStorage
-    >,
-  ) {}
+		public readonly publisherService?: Service<TServiceName, T>,
+		public outputSchema?: OutSchema,
+		public readonly timeout?: number,
+		public readonly memorySize?: number,
+		public readonly auditorStorageService?: Service<
+			TAuditStorageServiceName,
+			TAuditStorage
+		>,
+	) {}
 
-  /**
-   * Returns an array of environment variable names required by this construct's services.
-   * This is determined by running a "sniffer" EnvironmentParser through each service's
-   * register method to track which environment variables are accessed.
-   *
-   * Results are cached per service class to handle singleton patterns where
-   * subsequent register() calls may short-circuit and not access env vars.
-   *
-   * @returns Promise that resolves to array of environment variable names, sorted alphabetically
-   *
-   * @example
-   * ```typescript
-   * const endpoint = e
-   *   .services([databaseService, authService])
-   *   .get('/users')
-   *   .handle(async () => []);
-   *
-   * const envVars = await endpoint.getEnvironment(); // ['AUTH_SECRET', 'DATABASE_URL']
-   * ```
-   */
-  async getEnvironment(): Promise<string[]> {
-    const envVars = new Set<string>();
-    const services: Service[] = compact([
-      ...this.services,
-      this.publisherService,
-      this.auditorStorageService,
-    ]);
+	/**
+	 * Returns an array of environment variable names required by this construct's services.
+	 * This is determined by running a "sniffer" EnvironmentParser through each service's
+	 * register method to track which environment variables are accessed.
+	 *
+	 * Results are cached per service class to handle singleton patterns where
+	 * subsequent register() calls may short-circuit and not access env vars.
+	 *
+	 * @returns Promise that resolves to array of environment variable names, sorted alphabetically
+	 *
+	 * @example
+	 * ```typescript
+	 * const endpoint = e
+	 *   .services([databaseService, authService])
+	 *   .get('/users')
+	 *   .handle(async () => []);
+	 *
+	 * const envVars = await endpoint.getEnvironment(); // ['AUTH_SECRET', 'DATABASE_URL']
+	 * ```
+	 */
+	async getEnvironment(): Promise<string[]> {
+		const envVars = new Set<string>();
+		const services: Service[] = compact([
+			...this.services,
+			this.publisherService,
+			this.auditorStorageService,
+		]);
 
-    try {
-      for (const service of services) {
-        // Check cache first - handles singleton services that short-circuit
-        if (serviceEnvCache.has(service)) {
-          const cached = serviceEnvCache.get(service)!;
-          cached.forEach((v) => envVars.add(v));
-          continue;
-        }
+		try {
+			for (const service of services) {
+				// Check cache first - handles singleton services that short-circuit
+				if (serviceEnvCache.has(service)) {
+					const cached = serviceEnvCache.get(service)!;
+					cached.forEach((v) => envVars.add(v));
+					continue;
+				}
 
-        // Sniff the service for env vars
-        const sniffer = new SnifferEnvironmentParser();
-        try {
-          const result = service.register(sniffer as any);
+				// Sniff the service for env vars
+				const sniffer = new SnifferEnvironmentParser();
+				try {
+					const result = service.register({
+						envParser: sniffer as any,
+						context: snifferContext,
+					});
 
-          // Await if it's a Promise (async services)
-          if (result && typeof result === 'object' && 'then' in result) {
-            await Promise.resolve(result);
-          }
-        } catch {
-          // Service registration may fail but env vars are still tracked
-        }
+					// Await if it's a Promise (async services)
+					if (result && typeof result === 'object' && 'then' in result) {
+						await Promise.resolve(result);
+					}
+				} catch {
+					// Service registration may fail but env vars are still tracked
+				}
 
-        // Cache and collect the env vars
-        const serviceEnvVars = sniffer.getEnvironmentVariables();
-        serviceEnvCache.set(service, serviceEnvVars);
-        serviceEnvVars.forEach((v) => envVars.add(v));
-      }
+				// Cache and collect the env vars
+				const serviceEnvVars = sniffer.getEnvironmentVariables();
+				serviceEnvCache.set(service, serviceEnvVars);
+				serviceEnvVars.forEach((v) => envVars.add(v));
+			}
 
-      return Array.from(envVars).sort();
-    } catch (error) {
-      this.logger.error(
-        { error },
-        'Error determining environment variables for construct',
-      );
+			return Array.from(envVars).sort();
+		} catch (error) {
+			this.logger.error(
+				{ error },
+				'Error determining environment variables for construct',
+			);
 
-      return [];
-    }
-  }
+			return [];
+		}
+	}
 }
 
 export enum ConstructType {
-  Cron = 'dev.geekmidas.function.cron',
-  Endpoint = 'dev.geekmidas.function.endpoint',
-  Function = 'dev.geekmidas.function.function',
-  Subscriber = 'dev.geekmidas.function.subscriber',
+	Cron = 'dev.geekmidas.function.cron',
+	Endpoint = 'dev.geekmidas.function.endpoint',
+	Function = 'dev.geekmidas.function.function',
+	Subscriber = 'dev.geekmidas.function.subscriber',
 }