@noony-serverless/core 0.3.4 → 0.4.0

package/build/utils/wrapper-utils.d.ts

@@ -0,0 +1,177 @@
+import type { HttpFunction } from '@google-cloud/functions-framework';
+import type { Request, Response } from 'express';
+import { Handler } from '../core/handler';
+/**
+ * Create an HttpFunction wrapper for a Noony handler
+ *
+ * Wraps a Noony handler into a Google Cloud Functions `HttpFunction` for production deployment.
+ * This pattern ensures proper initialization, error handling, and prevents double responses.
+ *
+ * @param noonyHandler - The Noony handler to wrap (contains middleware chain and controller)
+ * @param functionName - Name for error logging purposes
+ * @param initializeDependencies - Async function that initializes dependencies (database, services, etc.)
+ *                                  Uses singleton pattern to prevent re-initialization on warm starts
+ * @returns HttpFunction compatible with `@google-cloud/functions-framework`
+ *
+ * @remarks
+ * This function ensures:
+ * - Dependencies are initialized before handler execution (optimized for cold/warm starts)
+ * - Errors are caught and returned as proper HTTP responses
+ * - Response is not sent twice (`headersSent` check)
+ * - `RESPONSE_SENT` errors are ignored (response already sent by middleware)
+ * - Real errors return 500 with generic message for security
+ *
+ * @example
+ * Creating and registering Cloud Functions:
+ * ```typescript
+ * import { http } from '@google-cloud/functions-framework';
+ * import { createHttpFunction } from '@noony-serverless/core';
+ * import { loginHandler } from './handlers/auth.handlers';
+ *
+ * // Initialize dependencies once per cold start
+ * let initialized = false;
+ * async function initializeDependencies(): Promise<void> {
+ *   if (initialized) return;
+ *   const db = await databaseService.connect();
+ *   await initializeServices(db);
+ *   initialized = true;
+ * }
+ *
+ * // Create and register function
+ * const loginFunction = createHttpFunction(
+ *   loginHandler,
+ *   'login',
+ *   initializeDependencies
+ * );
+ * http('login', loginFunction);
+ * export const login = loginFunction;
+ * ```
+ *
+ * @example
+ * Execution flow:
+ * ```
+ * HTTP Request → createHttpFunction wrapper
+ *                    │
+ *                    ▼
+ *            initializeDependencies() (only on cold start)
+ *                    │
+ *                    ▼
+ *            noonyHandler.execute(req, res)
+ *                    │
+ *                    ├─── errorHandler()
+ *                    ├─── authMiddleware()
+ *                    ├─── requirePermission()
+ *                    ├─── bodyValidator()
+ *                    ├─── ResponseWrapperMiddleware
+ *                    └─── Controller function
+ *                              │
+ *                              ▼
+ *                      HTTP Response
+ * ```
+ *
+ * @see {@link wrapNoonyHandler} for Express integration (local development)
+ */
+export declare function createHttpFunction(noonyHandler: Handler<unknown>, functionName: string, initializeDependencies: () => Promise<void>): HttpFunction;
+/**
+ * Wrap a Noony handler for use with Express routing
+ *
+ * Wraps a Noony handler into an Express route handler for local development environments.
+ * This pattern enables running all endpoints through a single Express app with standard
+ * Express routing, middleware, and error handling.
+ *
+ * @param noonyHandler - The Noony handler to wrap (contains middleware chain and controller)
+ * @param functionName - Name for error logging purposes
+ * @param initializeDependencies - Async function that initializes dependencies (database, services, etc.)
+ *                                  Uses singleton pattern to prevent re-initialization across requests
+ * @returns Express route handler compatible with Express Router: `(req: Request, res: Response) => Promise<void>`
+ *
+ * @remarks
+ * This wrapper ensures:
+ * - Dependencies are initialized before handler execution (singleton pattern for efficiency)
+ * - Noony handlers work seamlessly with Express routing and middleware
+ * - Errors are caught and returned as proper HTTP responses
+ * - Response is not sent twice (`headersSent` check)
+ * - `RESPONSE_SENT` errors are ignored (response already sent by middleware)
+ * - Real errors return 500 with generic message for security
+ *
+ * **Differences from createHttpFunction:**
+ *
+ * | Aspect | createHttpFunction | wrapNoonyHandler |
+ * |--------|-------------------|------------------|
+ * | **Use case** | Production deployment | Local development |
+ * | **Framework** | Cloud Functions Framework | Express |
+ * | **Return type** | `HttpFunction` | Express handler |
+ * | **Registration** | `http('name', fn)` | `app.get('/path', fn)` |
+ * | **Deployment** | Individual functions | Single Express app |
+ *
+ * @example
+ * Creating Express app with multiple routes:
+ * ```typescript
+ * import express, { Express } from 'express';
+ * import { wrapNoonyHandler } from '@noony-serverless/core';
+ * import { loginHandler, logoutHandler, getConfigHandler } from './handlers';
+ *
+ * // Initialize dependencies once per app startup
+ * let initialized = false;
+ * async function initializeDependencies(): Promise<void> {
+ *   if (initialized) return;
+ *   const db = await databaseService.connect();
+ *   await initializeServices(db);
+ *   initialized = true;
+ * }
+ *
+ * function createExpressApp(): Express {
+ *   const app = express();
+ *
+ *   // Global Express middleware
+ *   app.use(cors());
+ *   app.use(express.json());
+ *
+ *   // Health check (no DB required)
+ *   app.get('/health', (_req, res) => {
+ *     res.json({ success: true, data: { status: 'healthy' } });
+ *   });
+ *
+ *   // Auth routes
+ *   app.post('/api/auth/login', wrapNoonyHandler(loginHandler, 'login', initializeDependencies));
+ *   app.post('/api/auth/logout', wrapNoonyHandler(logoutHandler, 'logout', initializeDependencies));
+ *
+ *   // Config routes
+ *   app.get('/api/config', wrapNoonyHandler(getConfigHandler, 'getConfig', initializeDependencies));
+ *
+ *   // 404 handler
+ *   app.use((_req, res) => {
+ *     res.status(404).json({
+ *       success: false,
+ *       error: { code: 'NOT_FOUND', message: 'Endpoint not found' }
+ *     });
+ *   });
+ *
+ *   return app;
+ * }
+ *
+ * // Start server
+ * const app = createExpressApp();
+ * const PORT = process.env.PORT || 3000;
+ * app.listen(PORT, () => {
+ *   console.log(`Server running on port ${PORT}`);
+ * });
+ * ```
+ *
+ * @example
+ * Express routing with path parameters:
+ * ```typescript
+ * const app = express();
+ *
+ * // Routes with path parameters work seamlessly
+ * app.get('/api/users/:userId', wrapNoonyHandler(getUserHandler, 'getUser', initializeDependencies));
+ * app.patch('/api/config/sections/:sectionId', wrapNoonyHandler(updateSectionHandler, 'updateSection', initializeDependencies));
+ * app.delete('/api/config/sections/:sectionId', wrapNoonyHandler(deleteSectionHandler, 'deleteSection', initializeDependencies));
+ *
+ * // Path parameters available in Noony handler via context.req.params
+ * ```
+ *
+ * @see {@link createHttpFunction} for Cloud Functions Framework integration (production deployment)
+ */
+export declare function wrapNoonyHandler(noonyHandler: Handler<unknown>, functionName: string, initializeDependencies: () => Promise<void>): (req: Request, res: Response) => Promise<void>;
+//# sourceMappingURL=wrapper-utils.d.ts.map

package/build/utils/wrapper-utils.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpFunction = createHttpFunction;
+exports.wrapNoonyHandler = wrapNoonyHandler;
+const logger_1 = require("../core/logger");
+/**
+ * Create an HttpFunction wrapper for a Noony handler
+ *
+ * Wraps a Noony handler into a Google Cloud Functions `HttpFunction` for production deployment.
+ * This pattern ensures proper initialization, error handling, and prevents double responses.
+ *
+ * @param noonyHandler - The Noony handler to wrap (contains middleware chain and controller)
+ * @param functionName - Name for error logging purposes
+ * @param initializeDependencies - Async function that initializes dependencies (database, services, etc.)
+ *                                  Uses singleton pattern to prevent re-initialization on warm starts
+ * @returns HttpFunction compatible with `@google-cloud/functions-framework`
+ *
+ * @remarks
+ * This function ensures:
+ * - Dependencies are initialized before handler execution (optimized for cold/warm starts)
+ * - Errors are caught and returned as proper HTTP responses
+ * - Response is not sent twice (`headersSent` check)
+ * - `RESPONSE_SENT` errors are ignored (response already sent by middleware)
+ * - Real errors return 500 with generic message for security
+ *
+ * @example
+ * Creating and registering Cloud Functions:
+ * ```typescript
+ * import { http } from '@google-cloud/functions-framework';
+ * import { createHttpFunction } from '@noony-serverless/core';
+ * import { loginHandler } from './handlers/auth.handlers';
+ *
+ * // Initialize dependencies once per cold start
+ * let initialized = false;
+ * async function initializeDependencies(): Promise<void> {
+ *   if (initialized) return;
+ *   const db = await databaseService.connect();
+ *   await initializeServices(db);
+ *   initialized = true;
+ * }
+ *
+ * // Create and register function
+ * const loginFunction = createHttpFunction(
+ *   loginHandler,
+ *   'login',
+ *   initializeDependencies
+ * );
+ * http('login', loginFunction);
+ * export const login = loginFunction;
+ * ```
+ *
+ * @example
+ * Execution flow:
+ * ```
+ * HTTP Request → createHttpFunction wrapper
+ *                    │
+ *                    ▼
+ *            initializeDependencies() (only on cold start)
+ *                    │
+ *                    ▼
+ *            noonyHandler.execute(req, res)
+ *                    │
+ *                    ├─── errorHandler()
+ *                    ├─── authMiddleware()
+ *                    ├─── requirePermission()
+ *                    ├─── bodyValidator()
+ *                    ├─── ResponseWrapperMiddleware
+ *                    └─── Controller function
+ *                              │
+ *                              ▼
+ *                      HTTP Response
+ * ```
+ *
+ * @see {@link wrapNoonyHandler} for Express integration (local development)
+ */
+function createHttpFunction(noonyHandler, functionName, initializeDependencies) {
+    return async (req, res) => {
+        try {
+            // Ensure dependencies are initialized
+            await initializeDependencies();
+            // Execute Noony handler (runs middleware chain + controller)
+            // Cast is safe because Handler.execute internally adapts GCP Request/Response
+            await noonyHandler.execute(req, res);
+        }
+        catch (error) {
+            // Only handle errors if they're real errors (not RESPONSE_SENT markers)
+            if (error instanceof Error && error.message === 'RESPONSE_SENT') {
+                return;
+            }
+            logger_1.logger.error(`${functionName} function error`, {
+                error: error instanceof Error ? error.message : 'Unknown error',
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            // Graceful error handling - only send if headers not already sent
+            if (!res.headersSent) {
+                res.status(500).json({
+                    success: false,
+                    error: {
+                        code: 'INTERNAL_SERVER_ERROR',
+                        message: 'An unexpected error occurred',
+                    },
+                });
+            }
+        }
+    };
+}
+/**
+ * Wrap a Noony handler for use with Express routing
+ *
+ * Wraps a Noony handler into an Express route handler for local development environments.
+ * This pattern enables running all endpoints through a single Express app with standard
+ * Express routing, middleware, and error handling.
+ *
+ * @param noonyHandler - The Noony handler to wrap (contains middleware chain and controller)
+ * @param functionName - Name for error logging purposes
+ * @param initializeDependencies - Async function that initializes dependencies (database, services, etc.)
+ *                                  Uses singleton pattern to prevent re-initialization across requests
+ * @returns Express route handler compatible with Express Router: `(req: Request, res: Response) => Promise<void>`
+ *
+ * @remarks
+ * This wrapper ensures:
+ * - Dependencies are initialized before handler execution (singleton pattern for efficiency)
+ * - Noony handlers work seamlessly with Express routing and middleware
+ * - Errors are caught and returned as proper HTTP responses
+ * - Response is not sent twice (`headersSent` check)
+ * - `RESPONSE_SENT` errors are ignored (response already sent by middleware)
+ * - Real errors return 500 with generic message for security
+ *
+ * **Differences from createHttpFunction:**
+ *
+ * | Aspect | createHttpFunction | wrapNoonyHandler |
+ * |--------|-------------------|------------------|
+ * | **Use case** | Production deployment | Local development |
+ * | **Framework** | Cloud Functions Framework | Express |
+ * | **Return type** | `HttpFunction` | Express handler |
+ * | **Registration** | `http('name', fn)` | `app.get('/path', fn)` |
+ * | **Deployment** | Individual functions | Single Express app |
+ *
+ * @example
+ * Creating Express app with multiple routes:
+ * ```typescript
+ * import express, { Express } from 'express';
+ * import { wrapNoonyHandler } from '@noony-serverless/core';
+ * import { loginHandler, logoutHandler, getConfigHandler } from './handlers';
+ *
+ * // Initialize dependencies once per app startup
+ * let initialized = false;
+ * async function initializeDependencies(): Promise<void> {
+ *   if (initialized) return;
+ *   const db = await databaseService.connect();
+ *   await initializeServices(db);
+ *   initialized = true;
+ * }
+ *
+ * function createExpressApp(): Express {
+ *   const app = express();
+ *
+ *   // Global Express middleware
+ *   app.use(cors());
+ *   app.use(express.json());
+ *
+ *   // Health check (no DB required)
+ *   app.get('/health', (_req, res) => {
+ *     res.json({ success: true, data: { status: 'healthy' } });
+ *   });
+ *
+ *   // Auth routes
+ *   app.post('/api/auth/login', wrapNoonyHandler(loginHandler, 'login', initializeDependencies));
+ *   app.post('/api/auth/logout', wrapNoonyHandler(logoutHandler, 'logout', initializeDependencies));
+ *
+ *   // Config routes
+ *   app.get('/api/config', wrapNoonyHandler(getConfigHandler, 'getConfig', initializeDependencies));
+ *
+ *   // 404 handler
+ *   app.use((_req, res) => {
+ *     res.status(404).json({
+ *       success: false,
+ *       error: { code: 'NOT_FOUND', message: 'Endpoint not found' }
+ *     });
+ *   });
+ *
+ *   return app;
+ * }
+ *
+ * // Start server
+ * const app = createExpressApp();
+ * const PORT = process.env.PORT || 3000;
+ * app.listen(PORT, () => {
+ *   console.log(`Server running on port ${PORT}`);
+ * });
+ * ```
+ *
+ * @example
+ * Express routing with path parameters:
+ * ```typescript
+ * const app = express();
+ *
+ * // Routes with path parameters work seamlessly
+ * app.get('/api/users/:userId', wrapNoonyHandler(getUserHandler, 'getUser', initializeDependencies));
+ * app.patch('/api/config/sections/:sectionId', wrapNoonyHandler(updateSectionHandler, 'updateSection', initializeDependencies));
+ * app.delete('/api/config/sections/:sectionId', wrapNoonyHandler(deleteSectionHandler, 'deleteSection', initializeDependencies));
+ *
+ * // Path parameters available in Noony handler via context.req.params
+ * ```
+ *
+ * @see {@link createHttpFunction} for Cloud Functions Framework integration (production deployment)
+ */
+function wrapNoonyHandler(noonyHandler, functionName, initializeDependencies) {
+    return async (req, res) => {
+        try {
+            // Ensure dependencies are initialized
+            await initializeDependencies();
+            // Execute Noony handler with Express req/res (cast to generic types)
+            await noonyHandler.executeGeneric(req, res);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'RESPONSE_SENT') {
+                return;
+            }
+            logger_1.logger.error(`${functionName} handler error`, {
+                error: error instanceof Error ? error.message : 'Unknown error',
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            if (!res.headersSent) {
+                res.status(500).json({
+                    success: false,
+                    error: {
+                        code: 'INTERNAL_SERVER_ERROR',
+                        message: 'An unexpected error occurred',
+                    },
+                });
+            }
+        }
+    };
+}
+//# sourceMappingURL=wrapper-utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noony-serverless/core",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "A Middy base framework compatible with Firebase and GCP Cloud Functions with TypeScript",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -71,5 +71,64 @@
     "ts-jest": "^29.1.1",
     "typescript": "^5.3.3"
   },
-  "private": false
+  "peerDependencies": {
+    "@fastify/otel": "^1.0.0",
+    "@google-cloud/opentelemetry-cloud-trace-propagator": "^0.21.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.200.0",
+    "@opentelemetry/core": "^1.28.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.205.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.205.0",
+    "@opentelemetry/instrumentation-http": "^0.200.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-node": "^2.0.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "dd-trace": "^5.0.0",
+    "newrelic": "^12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/opentelemetry-cloud-trace-propagator": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/core": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/semantic-conventions": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-metrics-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/auto-instrumentations-node": {
+      "optional": true
+    },
+    "@fastify/otel": {
+      "optional": true
+    },
+    "newrelic": {
+      "optional": true
+    },
+    "dd-trace": {
+      "optional": true
+    }
+  },
+  "private": false,
+  "optionalDependencies": {
+    "@google-cloud/opentelemetry-cloud-trace-propagator": "^0.21.0"
+  }
 }