@noony-serverless/core 0.2.1 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ A powerful and flexible serverless middleware framework for Google Cloud Functio
 The `Handler` class manages the middleware execution pipeline with `before`, `after`, and `onError` lifecycle hooks:
 
 ```typescript
-const handler = new Handler<RequestType>()
+const handler = new Handler<RequestType, UserType>()
   .use(errorHandler())
   .use(bodyParser())
   .use(bodyValidator(schema))
@@ -23,7 +23,7 @@ const handler = new Handler<RequestType>()
 The context system provides full TypeScript support with generic typing:
 
 ```typescript
-interface Context<T = unknown> {
+interface Context<T = unknown, U = unknown> {
   req: CustomRequest<T>;     // Request with parsedBody and validatedBody
   res: CustomResponse;       // Response object
   container?: Container;     // TypeDI dependency injection
@@ -72,7 +72,7 @@ const userSchema = z.object({
 type UserRequest = z.infer<typeof userSchema>;
 
 // Create handler with full type safety
-const createUserHandler = new Handler<UserRequest>()
+const createUserHandler = new Handler<UserRequest, unknown>()
   .use(new ErrorHandlerMiddleware())
   .use(new BodyValidationMiddleware(userSchema))
   .use(new ResponseWrapperMiddleware())
@@ -117,7 +117,7 @@ const messageSchema = z.object({
 type PubSubMessage = z.infer<typeof messageSchema>;
 
 // Create Pub/Sub handler
-const pubsubHandler = new Handler<PubSubMessage>()
+const pubsubHandler = new Handler<PubSubMessage, unknown>()
   .use(new ErrorHandlerMiddleware())
   .use(new BodyParserMiddleware()) // Decodes base64 Pub/Sub messages
   .use(new BodyValidationMiddleware(messageSchema))
@@ -296,7 +296,7 @@ app.post('/users', async (req, res) => {
 ### 1. Middleware Order
 
 ```typescript
-const handler = new Handler<RequestType>()
+const handler = new Handler<RequestType, UserType>()
   .use(new ErrorHandlerMiddleware())        // Always first
   .use(new HeaderVariablesMiddleware(...))  // Required headers
   .use(new AuthenticationMiddleware(...))   // Authentication
@@ -324,7 +324,7 @@ interface UserContext {
 }
 
 // Use throughout the handler
-const handler = new Handler<UserRequest>();
+const handler = new Handler<UserRequest, UserContext>();
 ```
 
 ### 3. Error Handling
@@ -361,7 +361,7 @@ import {
 } from '@noony/serverless';
 
 // No type casting needed with proper generics
-const handler = new Handler<UserRequest>()
+const handler = new Handler<UserRequest, UserContext>()
   .handle(async (context) => {
     // TypeScript knows validatedBody is UserRequest
     const { name, email } = context.req.validatedBody!;

package/build/core/containerPool.d.ts

@@ -0,0 +1,44 @@
+import { ContainerInstance } from 'typedi';
+/**
+ * Performance optimization: Container Pool for reusing TypeDI containers
+ * This reduces object creation overhead and improves memory efficiency
+ */
+declare class ContainerPool {
+    private availableContainers;
+    private maxPoolSize;
+    private createdContainers;
+    constructor(maxPoolSize?: number);
+    /**
+     * Get a container from the pool or create a new one
+     */
+    acquire(): ContainerInstance;
+    /**
+     * Return a container to the pool for reuse
+     */
+    release(container: ContainerInstance): void;
+    /**
+     * Reset container state to prevent cross-request contamination
+     * Note: TypeDI containers are isolated by default, so we mainly need
+     * to clear any manually set values
+     */
+    private resetContainer;
+    /**
+     * Get pool statistics for monitoring
+     */
+    getStats(): {
+        available: number;
+        created: number;
+        maxSize: number;
+    };
+    /**
+     * Warm up the pool by pre-creating containers
+     */
+    warmUp(count?: number): void;
+    /**
+     * Clear all containers from the pool
+     */
+    clear(): void;
+}
+declare const containerPool: ContainerPool;
+export { ContainerPool, containerPool };
+//# sourceMappingURL=containerPool.d.ts.map

package/build/core/containerPool.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containerPool = exports.ContainerPool = void 0;
+const typedi_1 = require("typedi");
+/**
+ * Performance optimization: Container Pool for reusing TypeDI containers
+ * This reduces object creation overhead and improves memory efficiency
+ */
+class ContainerPool {
+    availableContainers = [];
+    maxPoolSize = 10;
+    createdContainers = 0;
+    constructor(maxPoolSize = 10) {
+        this.maxPoolSize = maxPoolSize;
+    }
+    /**
+     * Get a container from the pool or create a new one
+     */
+    acquire() {
+        if (this.availableContainers.length > 0) {
+            return this.availableContainers.pop();
+        }
+        // Create new container if pool is empty and under limit
+        if (this.createdContainers < this.maxPoolSize) {
+            this.createdContainers++;
+            return typedi_1.Container.of();
+        }
+        // If pool is at capacity, create a temporary container
+        // This should rarely happen in normal usage
+        return typedi_1.Container.of();
+    }
+    /**
+     * Return a container to the pool for reuse
+     */
+    release(container) {
+        if (this.availableContainers.length < this.maxPoolSize) {
+            // Reset container state by removing all instances
+            // This prevents memory leaks and cross-request contamination
+            this.resetContainer(container);
+            this.availableContainers.push(container);
+        }
+        // If pool is full, let the container be garbage collected
+    }
+    /**
+     * Reset container state to prevent cross-request contamination
+     * Note: TypeDI containers are isolated by default, so we mainly need
+     * to clear any manually set values
+     */
+    resetContainer(_container) {
+        try {
+            // For TypeDI containers created with Container.of(), each container
+            // is already isolated. We just need to ensure no memory leaks.
+            // The container will be garbage collected when released from pool
+            // if it contains too much data
+            // TypeDI containers are self-contained and don't need explicit reset
+            // This is a placeholder for future enhancements if needed
+        }
+        catch (error) {
+            // If any issues occur, don't add back to pool
+            console.warn('Failed to reset container, discarding:', error);
+        }
+    }
+    /**
+     * Get pool statistics for monitoring
+     */
+    getStats() {
+        return {
+            available: this.availableContainers.length,
+            created: this.createdContainers,
+            maxSize: this.maxPoolSize,
+        };
+    }
+    /**
+     * Warm up the pool by pre-creating containers
+     */
+    warmUp(count = 5) {
+        const warmUpCount = Math.min(count, this.maxPoolSize);
+        for (let i = 0; i < warmUpCount; i++) {
+            if (this.createdContainers < this.maxPoolSize) {
+                const container = typedi_1.Container.of();
+                this.createdContainers++;
+                this.availableContainers.push(container);
+            }
+        }
+    }
+    /**
+     * Clear all containers from the pool
+     */
+    clear() {
+        this.availableContainers = [];
+        this.createdContainers = 0;
+    }
+}
+exports.ContainerPool = ContainerPool;
+// Global container pool instance
+const containerPool = new ContainerPool(15); // Slightly higher limit for serverless
+exports.containerPool = containerPool;
+// Warm up the pool for better cold start performance
+containerPool.warmUp(3);
+//# sourceMappingURL=containerPool.js.map

package/build/core/core.d.ts

@@ -1,4 +1,5 @@
-import { ContainerInstance } from 'typedi';
+import { Request, Response } from '@google-cloud/functions-framework';
+import { Container, ContainerInstance } from 'typedi';
 /**
  * Framework-agnostic HTTP method enum
  */
@@ -14,7 +15,7 @@ export declare enum HttpMethod {
 /**
  * Framework-agnostic request interface that can work with any HTTP framework
  */
-export interface NoonyRequest<T = unknown> {
+export interface GenericRequest<T = unknown> {
     method: HttpMethod | string;
     url: string;
     path?: string;
@@ -31,20 +32,30 @@ export interface NoonyRequest<T = unknown> {
 /**
  * Framework-agnostic response interface that can work with any HTTP framework
  */
-export interface NoonyResponse {
-    status(code: number): NoonyResponse;
-    json(data: unknown): NoonyResponse | void;
-    send(data: unknown): NoonyResponse | void;
-    header(name: string, value: string): NoonyResponse;
-    headers(headers: Record<string, string>): NoonyResponse;
+export interface GenericResponse {
+    status(code: number): GenericResponse;
+    json(data: unknown): GenericResponse | void;
+    send(data: unknown): GenericResponse | void;
+    header(name: string, value: string): GenericResponse;
+    headers(headers: Record<string, string>): GenericResponse;
     end(): void;
     statusCode?: number;
     headersSent?: boolean;
 }
-/** @deprecated Use NoonyRequest instead */
-export type GenericRequest<T = unknown> = NoonyRequest<T>;
-/** @deprecated Use NoonyResponse instead */
-export type GenericResponse = NoonyResponse;
+/**
+ * Legacy GCP Functions-specific request interface for backward compatibility
+ * @deprecated Use GenericRequest instead
+ */
+export interface CustomRequest<T = unknown> extends Request {
+    parsedBody?: T;
+    validatedBody?: T;
+}
+/**
+ * Legacy GCP Functions-specific response interface for backward compatibility
+ * @deprecated Use GenericResponse instead
+ */
+export interface CustomResponse extends Response {
+}
 /**
  * Security configuration for request processing
  */
@@ -63,29 +74,69 @@ export interface HandlerOptions {
     security?: SecurityConfig;
     enableAsyncContext?: boolean;
 }
+/**
+ * Base authenticated user interface that projects can extend
+ */
+export interface BaseAuthenticatedUser {
+    id: string;
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Modern request type alias (recommended)
+ */
+export type NoonyRequest<T = unknown> = GenericRequest<T>;
+/**
+ * Modern response type alias (recommended)
+ */
+export type NoonyResponse = GenericResponse;
 /**
  * Represents the execution context for handling a request and response in an application.
  *
- * @template T Specifies the type of the custom request payload.
+ * @template TBody Specifies the type of the request body payload.
+ * @template TUser Specifies the type of the authenticated user (defaults to unknown).
  */
-export interface Context<T = unknown> {
-    readonly req: NoonyRequest<T>;
+export interface Context<TBody = unknown, TUser = unknown> {
+    readonly req: NoonyRequest<TBody>;
     readonly res: NoonyResponse;
-    container?: ContainerInstance;
+    container: ContainerInstance;
     error?: Error | null;
     readonly businessData: Map<string, unknown>;
-    user?: unknown;
+    user?: TUser;
     readonly startTime: number;
     readonly requestId: string;
     timeoutSignal?: AbortSignal;
     responseData?: unknown;
 }
+/**
+ * Legacy context interface for backward compatibility
+ * @deprecated Use Context with GenericRequest/GenericResponse instead
+ */
+export interface LegacyContext<T = unknown, V = unknown> {
+    req: CustomRequest<T>;
+    res: CustomResponse;
+    container?: Container;
+    error?: Error | null;
+    businessData: Map<string, unknown>;
+    user?: V;
+}
 /**
  * Utility function to generate unique request IDs
  */
 export declare function generateRequestId(): string;
+/**
+ * Adapter to convert GCP Functions Request to GenericRequest
+ */
+export declare function adaptGCPRequest<T = unknown>(gcpRequest: Request): GenericRequest<T>;
+/**
+ * Adapter to convert GCP Functions Response to GenericResponse
+ */
+export declare function adaptGCPResponse(gcpResponse: Response): GenericResponse;
 /**
  * Creates a context object for framework-agnostic handlers
+ * @template TBody The type of the request body
+ * @template TUser The type of the authenticated user
  */
-export declare function createContext<T = unknown>(req: NoonyRequest<T>, res: NoonyResponse, options?: Partial<Context<T>>): Context<T>;
+export declare function createContext<TBody = unknown, TUser = unknown>(req: NoonyRequest<TBody>, res: NoonyResponse, options?: Partial<Context<TBody, TUser>>): Context<TBody, TUser>;
 //# sourceMappingURL=core.d.ts.map

package/build/core/core.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpMethod = void 0;
 exports.generateRequestId = generateRequestId;
+exports.adaptGCPRequest = adaptGCPRequest;
+exports.adaptGCPResponse = adaptGCPResponse;
 exports.createContext = createContext;
 const typedi_1 = require("typedi");
 /**
@@ -17,16 +19,75 @@ var HttpMethod;
     HttpMethod["OPTIONS"] = "OPTIONS";
     HttpMethod["HEAD"] = "HEAD";
 })(HttpMethod || (exports.HttpMethod = HttpMethod = {}));
-// Legacy context interface removed - use Context with NoonyRequest/NoonyResponse instead
 /**
  * Utility function to generate unique request IDs
  */
 function generateRequestId() {
     return `req_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
 }
-// Complex adapter functions removed - using smart universal adapter in Handler instead
+/**
+ * Adapter to convert GCP Functions Request to GenericRequest
+ */
+function adaptGCPRequest(gcpRequest) {
+    return {
+        method: gcpRequest.method || HttpMethod.GET,
+        url: gcpRequest.url || '/',
+        path: gcpRequest.path,
+        headers: gcpRequest.headers || {},
+        query: gcpRequest.query || {},
+        params: gcpRequest.params || {},
+        body: gcpRequest.body,
+        rawBody: gcpRequest.rawBody,
+        ip: gcpRequest.ip,
+        userAgent: gcpRequest.get?.('user-agent'),
+    };
+}
+/**
+ * Adapter to convert GCP Functions Response to GenericResponse
+ */
+function adaptGCPResponse(gcpResponse) {
+    let currentStatusCode = 200;
+    let isHeadersSent = false;
+    return {
+        status: (code) => {
+            currentStatusCode = code;
+            gcpResponse.status(code);
+            return adaptGCPResponse(gcpResponse);
+        },
+        json: (data) => {
+            isHeadersSent = true;
+            gcpResponse.json(data);
+        },
+        send: (data) => {
+            isHeadersSent = true;
+            gcpResponse.send(data);
+        },
+        header: (name, value) => {
+            gcpResponse.header(name, value);
+            return adaptGCPResponse(gcpResponse);
+        },
+        headers: (headers) => {
+            Object.entries(headers).forEach(([key, value]) => {
+                gcpResponse.header(key, value);
+            });
+            return adaptGCPResponse(gcpResponse);
+        },
+        end: () => {
+            isHeadersSent = true;
+            gcpResponse.end();
+        },
+        get statusCode() {
+            return gcpResponse.statusCode || currentStatusCode;
+        },
+        get headersSent() {
+            return gcpResponse.headersSent || isHeadersSent;
+        },
+    };
+}
 /**
  * Creates a context object for framework-agnostic handlers
+ * @template TBody The type of the request body
+ * @template TUser The type of the authenticated user
  */
 function createContext(req, res, options = {}) {
     return {

package/build/core/errors.d.ts

@@ -22,4 +22,47 @@ export declare class TimeoutError extends HttpError {
 export declare class TooLargeError extends HttpError {
     constructor(message?: string, details?: unknown);
 }
+/**
+ * 401 Unauthorized - Authentication required
+ * Alias for AuthenticationError for better semantic clarity
+ */
+export declare class UnauthorizedError extends HttpError {
+    constructor(message?: string);
+}
+/**
+ * 403 Forbidden - Insufficient permissions
+ * Use this for authorization failures (user is authenticated but lacks permission)
+ */
+export declare class ForbiddenError extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 404 Not Found - Resource not found
+ */
+export declare class NotFoundError extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 409 Conflict - Resource already exists or state conflict
+ */
+export declare class ConflictError extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 500 Internal Server Error - Unexpected errors with optional cause chaining
+ */
+export declare class InternalServerError extends HttpError {
+    cause?: Error | undefined;
+    constructor(message?: string, cause?: Error | undefined, details?: unknown);
+}
+/**
+ * Service layer error with error code
+ * Use this in service classes for business logic errors
+ * Not tied to specific HTTP status codes
+ */
+export declare class ServiceError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
 //# sourceMappingURL=errors.d.ts.map

package/build/core/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TooLargeError = exports.TimeoutError = exports.SecurityError = exports.BusinessError = exports.AuthenticationError = exports.ValidationError = exports.HttpError = void 0;
+exports.ServiceError = exports.InternalServerError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.TooLargeError = exports.TimeoutError = exports.SecurityError = exports.BusinessError = exports.AuthenticationError = exports.ValidationError = exports.HttpError = void 0;
 class HttpError extends Error {
     status;
     code;
@@ -56,4 +56,77 @@ class TooLargeError extends HttpError {
     }
 }
 exports.TooLargeError = TooLargeError;
+/**
+ * 401 Unauthorized - Authentication required
+ * Alias for AuthenticationError for better semantic clarity
+ */
+class UnauthorizedError extends HttpError {
+    constructor(message = 'Authentication required') {
+        super(401, message, 'UNAUTHORIZED_ERROR');
+        this.name = 'UnauthorizedError';
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;
+/**
+ * 403 Forbidden - Insufficient permissions
+ * Use this for authorization failures (user is authenticated but lacks permission)
+ */
+class ForbiddenError extends HttpError {
+    constructor(message = 'Access denied', details) {
+        super(403, message, 'FORBIDDEN_ERROR', details);
+        this.name = 'ForbiddenError';
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+/**
+ * 404 Not Found - Resource not found
+ */
+class NotFoundError extends HttpError {
+    constructor(message = 'Resource not found', details) {
+        super(404, message, 'NOT_FOUND_ERROR', details);
+        this.name = 'NotFoundError';
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * 409 Conflict - Resource already exists or state conflict
+ */
+class ConflictError extends HttpError {
+    constructor(message = 'Resource already exists', details) {
+        super(409, message, 'CONFLICT_ERROR', details);
+        this.name = 'ConflictError';
+    }
+}
+exports.ConflictError = ConflictError;
+/**
+ * 500 Internal Server Error - Unexpected errors with optional cause chaining
+ */
+class InternalServerError extends HttpError {
+    cause;
+    constructor(message = 'Internal server error', cause, details) {
+        super(500, message, 'INTERNAL_SERVER_ERROR', details);
+        this.cause = cause;
+        this.name = 'InternalServerError';
+        if (cause) {
+            this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
+        }
+    }
+}
+exports.InternalServerError = InternalServerError;
+/**
+ * Service layer error with error code
+ * Use this in service classes for business logic errors
+ * Not tied to specific HTTP status codes
+ */
+class ServiceError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'ServiceError';
+    }
+}
+exports.ServiceError = ServiceError;
 //# sourceMappingURL=errors.js.map

package/build/core/handler.d.ts

@@ -1,4 +1,4 @@
-import { Context, NoonyRequest, NoonyResponse } from './core';
+import { Context, CustomRequest, CustomResponse, GenericRequest, GenericResponse } from './core';
 /**
  * Interface representing a base structure for middleware with optional lifecycle methods.
  *
@@ -7,12 +7,13 @@ import { Context, NoonyRequest, NoonyResponse } from './core';
  * executed before and after a process, as well as handling errors that
  * occur during the process.
  *
- * @template T - The type of the request data. Defaults to unknown.
+ * @template T - The type of the request or input context. Defaults to unknown.
+ * @template U - The type of the response or output context. Defaults to unknown.
  */
-export interface BaseMiddleware<T = unknown> {
-    before?: (context: Context<T>) => Promise<void>;
-    after?: (context: Context<T>) => Promise<void>;
-    onError?: (error: Error, context: Context<T>) => Promise<void>;
+export interface BaseMiddleware<T = unknown, U = unknown> {
+    before?: (context: Context<T, U>) => Promise<void>;
+    after?: (context: Context<T, U>) => Promise<void>;
+    onError?: (error: Error, context: Context<T, U>) => Promise<void>;
 }
 /**
  * The Handler class is responsible for managing and executing middleware functions
@@ -22,8 +23,6 @@ export interface BaseMiddleware<T = unknown> {
  * process a request/response flow either before the main handler (via `before`),
  * after the main handler (via `after`), or handle errors (via `onError`).
  *
- * @example
- * ```typescript
  * interface MessagePayload {
  *   action: string;
  *   data: Record<string, unknown>;
@@ -34,29 +33,25 @@ export interface BaseMiddleware<T = unknown> {
  *   .use(bodyParser())
  *   .handle(async (context) => {
  *     const { req } = context;
- *     // Handle the request with type-safe access to req.validatedBody
+ *     // Handle the request
  *   });
- * ```
  * @template T Type for the input request data.
+ * @template U Type for the additional context or response data.
  */
-export declare class Handler<T = unknown> {
+export declare class Handler<T = unknown, U = unknown> {
     private baseMiddlewares;
     private handler;
     private reversedMiddlewares;
     private errorMiddlewares;
     private middlewaresPrecomputed;
-    static use<T = unknown>(middleware: BaseMiddleware<T>): Handler<T>;
-    use(middleware: BaseMiddleware<T>): Handler<T>;
-    handle(handler: (context: Context<T>) => Promise<void>): Handler<T>;
+    static use<T = unknown, U = unknown>(middleware: BaseMiddleware<T, U>): Handler<T, U>;
+    use<NewT = T, NewU = U>(middleware: BaseMiddleware<NewT, NewU>): Handler<NewT, NewU>;
+    handle(handler: (context: Context<T, U>) => Promise<void>): Handler<T, U>;
     /**
      * Performance optimization: Pre-compute middleware arrays to avoid runtime array operations
      */
     private precomputeMiddlewareArrays;
-    /**
-     * Universal execute method that works with any HTTP framework
-     * Automatically detects and adapts GCP, Express, AWS Lambda, Fastify, etc.
-     */
-    execute(nativeReq: unknown, nativeRes: unknown): Promise<void>;
+    execute(req: CustomRequest<T>, res: CustomResponse): Promise<void>;
     /**
      * Execute before middlewares with optimized batching for independent middlewares
      */
@@ -70,24 +65,8 @@ export declare class Handler<T = unknown> {
      */
     private executeErrorMiddlewares;
     /**
-     * Universal request adapter - converts any framework's request to NoonyRequest
-     */
-    private adaptToNoonyRequest;
-    /**
-     * Universal response adapter - converts any framework's response to NoonyResponse
-     */
-    private adaptToNoonyResponse;
-    /**
-     * Create response adapter for AWS Lambda
-     */
-    private createAWSLambdaResponse;
-    /**
-     * Create response adapter for standard HTTP frameworks (GCP, Express, Fastify)
-     */
-    private createStandardHTTPResponse;
-    /**
-     * @deprecated Use execute() instead - automatically detects framework
+     * Framework-agnostic execute method that works with GenericRequest/GenericResponse
      */
-    executeGeneric(req: NoonyRequest<T>, res: NoonyResponse): Promise<void>;
+    executeGeneric(req: GenericRequest<T>, res: GenericResponse): Promise<void>;
 }
 //# sourceMappingURL=handler.d.ts.map