@hazeljs/serverless 0.2.0-alpha.1

package/dist/cloud-function.adapter.js

@@ -0,0 +1,271 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudFunctionAdapter = void 0;
+exports.createCloudFunctionHandler = createCloudFunctionHandler;
+exports.createCloudFunctionEventHandler = createCloudFunctionEventHandler;
+const core_1 = require("@hazeljs/core");
+const core_2 = __importDefault(require("@hazeljs/core"));
+const serverless_decorator_1 = require("./serverless.decorator");
+const cold_start_optimizer_1 = require("./cold-start.optimizer");
+/**
+ * Cloud Function adapter for HazelJS
+ */
+class CloudFunctionAdapter {
+    constructor(moduleClass, options = {}) {
+        this.moduleClass = moduleClass;
+        this.options = options;
+        this.isColdStart = true;
+        this.optimizer = cold_start_optimizer_1.ColdStartOptimizer.getInstance();
+    }
+    /**
+     * Initialize the HazelJS application
+     */
+    async initialize() {
+        if (this.app) {
+            return;
+        }
+        const startTime = Date.now();
+        core_2.default.info('Initializing HazelJS application for Cloud Functions...');
+        // Check if cold start optimization is enabled
+        const metadata = (0, serverless_decorator_1.getServerlessMetadata)(this.moduleClass);
+        if (metadata?.coldStartOptimization) {
+            await this.optimizer.warmUp();
+        }
+        // Create HazelJS application
+        this.app = new core_1.HazelApp(this.moduleClass);
+        if (this.options.onInit && this.app) {
+            await this.options.onInit(this.app);
+        }
+        const duration = Date.now() - startTime;
+        core_2.default.info(`Cloud Function initialization completed in ${duration}ms`);
+    }
+    /**
+     * Create Cloud Function HTTP handler
+     */
+    createHttpHandler() {
+        return async (req, res) => {
+            try {
+                // Log cold start
+                if (this.isColdStart) {
+                    core_2.default.info('Cloud Function cold start detected');
+                    this.isColdStart = false;
+                }
+                // Initialize application
+                await this.initialize();
+                // Convert Cloud Function request to internal format
+                const request = this.convertCloudFunctionRequest(req);
+                // Process request through HazelJS
+                const response = await this.processRequest(request);
+                // Send response
+                res.status(response.statusCode);
+                if (response.headers) {
+                    Object.entries(response.headers).forEach(([key, value]) => {
+                        res.set(key, value);
+                    });
+                }
+                res.send(response.body);
+            }
+            catch (error) {
+                this.options.onError?.(error);
+                core_2.default.error('Cloud Function handler error:', error);
+                res.status(500).json({
+                    error: 'Internal Server Error',
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                });
+            }
+        };
+    }
+    /**
+     * Create Cloud Function event handler (for Pub/Sub, Storage, etc.).
+     * Stub: initializes the app and logs the event but does not route to user-defined handlers.
+     * Implement custom event handling in your module or a separate entrypoint and invoke it from here.
+     */
+    createEventHandler() {
+        return async (event, context) => {
+            try {
+                // Log cold start
+                if (this.isColdStart) {
+                    core_2.default.info('Cloud Function event cold start detected');
+                    this.isColdStart = false;
+                }
+                // Initialize application
+                await this.initialize();
+                core_2.default.info('Processing Cloud Function event:', {
+                    eventType: context.eventType,
+                    resource: context.resource,
+                });
+                // Stub: extend this to dispatch event to your handlers (e.g. Pub/Sub, Storage)
+                core_2.default.info('Event processed successfully');
+            }
+            catch (error) {
+                this.options.onError?.(error);
+                core_2.default.error('Cloud Function event handler error:', error);
+                throw error;
+            }
+        };
+    }
+    /**
+     * Convert Cloud Function request to internal format
+     */
+    convertCloudFunctionRequest(req) {
+        return {
+            method: req.method,
+            url: req.url,
+            path: req.path,
+            headers: this.normalizeHeaders(req.headers),
+            query: this.normalizeQuery(req.query),
+            body: req.body,
+            rawBody: req.rawBody,
+        };
+    }
+    /**
+     * Normalize headers (convert string[] to string)
+     */
+    normalizeHeaders(headers) {
+        const normalized = {};
+        for (const [key, value] of Object.entries(headers)) {
+            normalized[key] = Array.isArray(value) ? value[0] : value;
+        }
+        return normalized;
+    }
+    /**
+     * Normalize query parameters
+     */
+    normalizeQuery(query) {
+        const normalized = {};
+        for (const [key, value] of Object.entries(query)) {
+            normalized[key] = Array.isArray(value) ? value[0] : value;
+        }
+        return normalized;
+    }
+    /**
+     * Process request through HazelJS router
+     */
+    async processRequest(request) {
+        if (!this.app) {
+            return {
+                statusCode: 500,
+                body: JSON.stringify({ message: 'Application not initialized' }),
+                headers: { 'Content-Type': 'application/json' },
+            };
+        }
+        const router = this.app.getRouter();
+        // Build request context for the router
+        const context = {
+            method: request.method,
+            url: request.url,
+            headers: request.headers,
+            query: request.query,
+            params: {},
+            body: request.body,
+        };
+        try {
+            const route = await router.match(request.method, request.url, context);
+            if (!route) {
+                return {
+                    statusCode: 404,
+                    body: JSON.stringify({ statusCode: 404, message: 'Route not found' }),
+                    headers: { 'Content-Type': 'application/json' },
+                };
+            }
+            // Create a synthetic request/response to capture the handler output
+            const syntheticReq = {
+                method: request.method,
+                url: request.url,
+                headers: request.headers,
+                query: request.query,
+                params: route.context?.params ?? context.params ?? {},
+                body: request.body,
+            };
+            let responseBody;
+            let responseStatus = 200;
+            const responseHeaders = { 'Content-Type': 'application/json' };
+            const syntheticRes = {
+                statusCode: 200,
+                status(code) {
+                    responseStatus = code;
+                    return syntheticRes;
+                },
+                json(data) {
+                    responseBody = data;
+                    responseStatus = responseStatus || 200;
+                },
+                send(data) {
+                    responseBody = data;
+                },
+                setHeader(key, value) {
+                    responseHeaders[key] = value;
+                },
+                getHeader(key) {
+                    return responseHeaders[key];
+                },
+            };
+            const result = await route.handler(syntheticReq, syntheticRes, route.context);
+            if (result !== undefined && responseBody === undefined) {
+                responseBody = result;
+            }
+            return {
+                statusCode: responseStatus,
+                body: typeof responseBody === 'string' ? responseBody : JSON.stringify(responseBody),
+                headers: responseHeaders,
+            };
+        }
+        catch (error) {
+            const statusCode = error.statusCode || 500;
+            const message = error instanceof Error ? error.message : 'Internal Server Error';
+            return {
+                statusCode,
+                body: JSON.stringify({ statusCode, message }),
+                headers: { 'Content-Type': 'application/json' },
+            };
+        }
+    }
+    /**
+     * Get application instance
+     */
+    getApp() {
+        return this.app;
+    }
+    /**
+     * Check if this is a cold start
+     */
+    isCold() {
+        return this.isColdStart;
+    }
+}
+exports.CloudFunctionAdapter = CloudFunctionAdapter;
+/**
+ * Create a Cloud Function HTTP handler for a HazelJS module
+ *
+ * @example
+ * ```typescript
+ * // index.ts
+ * import { createCloudFunctionHandler } from '@hazeljs/core';
+ * import { AppModule } from './app.module';
+ *
+ * export const handler = createCloudFunctionHandler(AppModule);
+ * ```
+ */
+function createCloudFunctionHandler(moduleClass, options) {
+    const adapter = new CloudFunctionAdapter(moduleClass, options ?? {});
+    return adapter.createHttpHandler();
+}
+/**
+ * Create a Cloud Function event handler for a HazelJS module
+ *
+ * @example
+ * ```typescript
+ * // index.ts
+ * import { createCloudFunctionEventHandler } from '@hazeljs/core';
+ * import { AppModule } from './app.module';
+ *
+ * export const handler = createCloudFunctionEventHandler(AppModule);
+ * ```
+ */
+function createCloudFunctionEventHandler(moduleClass, options) {
+    const adapter = new CloudFunctionAdapter(moduleClass, options ?? {});
+    return adapter.createEventHandler();
+}

package/dist/cold-start.optimizer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Cold start optimization strategies.
+ * Best-effort and environment-dependent; preloads built-in modules and the DI container.
+ */
+export declare class ColdStartOptimizer {
+    private static instance;
+    private isWarmedUp;
+    private warmupTimestamp?;
+    private preloadedModules;
+    private constructor();
+    static getInstance(): ColdStartOptimizer;
+    /**
+     * Warm up the application
+     */
+    warmUp(): Promise<void>;
+    /**
+     * Pre-initialize the DI container
+     */
+    private preInitializeContainer;
+    /**
+     * Preload critical modules
+     */
+    private preloadCriticalModules;
+    /**
+     * Setup connection pools (placeholder; override or extend for DB/API connection warming).
+     */
+    private setupConnectionPools;
+    /**
+     * Check if the application is warmed up
+     */
+    isWarm(): boolean;
+    /**
+     * Get warmup timestamp
+     */
+    getWarmupTimestamp(): number | undefined;
+    /**
+     * Get warmup duration
+     */
+    getWarmupDuration(): number | undefined;
+    /**
+     * Reset warmup state (for testing)
+     */
+    reset(): void;
+    /**
+     * Get preloaded modules
+     */
+    getPreloadedModules(): string[];
+}
+/**
+ * Decorator to enable cold start optimization for a method
+ */
+export declare function OptimizeColdStart(): MethodDecorator;
+/**
+ * Keep-alive helper to schedule periodic pings.
+ * Does not perform an HTTP request; use a cron, external pinger, or implement fetch/http.get in the interval
+ * to actually warm the function.
+ */
+export declare class KeepAliveHelper {
+    private intervalId?;
+    private pingUrl?;
+    /**
+     * Start keep-alive interval (logs only; implement your own HTTP ping or use provisioned concurrency for warming).
+     */
+    start(url: string, intervalMs?: number): void;
+    /**
+     * Stop keep-alive pings
+     */
+    stop(): void;
+}
+//# sourceMappingURL=cold-start.optimizer.d.ts.map

package/dist/cold-start.optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cold-start.optimizer.d.ts","sourceRoot":"","sources":["../src/cold-start.optimizer.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAqB;IAC5C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAA0B;IAElD,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,kBAAkB;IAOxC;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B7B;;OAEG;YACW,sBAAsB;IAOpC;;OAEG;YACW,sBAAsB;IAgBpC;;OAEG;YACW,oBAAoB;IAIlC;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,kBAAkB,IAAI,MAAM,GAAG,SAAS;IAIxC;;OAEG;IACH,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAKvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,mBAAmB,IAAI,MAAM,EAAE;CAGhC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,eAAe,CAgBnD;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,UAAU,CAAC,CAAiB;IACpC,OAAO,CAAC,OAAO,CAAC,CAAS;IAEzB;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAE,MAAsB,GAAG,IAAI;IAe5D;;OAEG;IACH,IAAI,IAAI,IAAI;CAOb"}

package/dist/cold-start.optimizer.js

@@ -0,0 +1,202 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeepAliveHelper = exports.ColdStartOptimizer = void 0;
+exports.OptimizeColdStart = OptimizeColdStart;
+const core_1 = __importDefault(require("@hazeljs/core"));
+const core_2 = require("@hazeljs/core");
+/**
+ * Cold start optimization strategies.
+ * Best-effort and environment-dependent; preloads built-in modules and the DI container.
+ */
+class ColdStartOptimizer {
+    constructor() {
+        this.isWarmedUp = false;
+        this.preloadedModules = new Set();
+    }
+    static getInstance() {
+        if (!ColdStartOptimizer.instance) {
+            ColdStartOptimizer.instance = new ColdStartOptimizer();
+        }
+        return ColdStartOptimizer.instance;
+    }
+    /**
+     * Warm up the application
+     */
+    async warmUp() {
+        if (this.isWarmedUp) {
+            core_1.default.debug('Application already warmed up');
+            return;
+        }
+        const startTime = Date.now();
+        core_1.default.info('Starting cold start optimization...');
+        try {
+            // Pre-initialize container
+            await this.preInitializeContainer();
+            // Preload critical modules
+            await this.preloadCriticalModules();
+            // Setup connection pools
+            await this.setupConnectionPools();
+            this.isWarmedUp = true;
+            this.warmupTimestamp = Date.now();
+            const duration = Date.now() - startTime;
+            core_1.default.info(`Cold start optimization completed in ${duration}ms`);
+        }
+        catch (error) {
+            core_1.default.error('Cold start optimization failed:', error);
+            throw error;
+        }
+    }
+    /**
+     * Pre-initialize the DI container
+     */
+    async preInitializeContainer() {
+        core_1.default.debug('Pre-initializing DI container...');
+        core_2.Container.getInstance();
+        // Container is already initialized, just log it
+        core_1.default.debug('DI container ready');
+    }
+    /**
+     * Preload critical modules
+     */
+    async preloadCriticalModules() {
+        core_1.default.debug('Preloading critical modules...');
+        const criticalModules = ['http', 'https', 'crypto', 'buffer'];
+        for (const moduleName of criticalModules) {
+            try {
+                await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s)));
+                this.preloadedModules.add(moduleName);
+                core_1.default.debug(`Preloaded module: ${moduleName}`);
+            }
+            catch (error) {
+                core_1.default.warn(`Failed to preload module ${moduleName}:`, error);
+            }
+        }
+    }
+    /**
+     * Setup connection pools (placeholder; override or extend for DB/API connection warming).
+     */
+    async setupConnectionPools() {
+        core_1.default.debug('Setting up connection pools...');
+    }
+    /**
+     * Check if the application is warmed up
+     */
+    isWarm() {
+        return this.isWarmedUp;
+    }
+    /**
+     * Get warmup timestamp
+     */
+    getWarmupTimestamp() {
+        return this.warmupTimestamp;
+    }
+    /**
+     * Get warmup duration
+     */
+    getWarmupDuration() {
+        if (!this.warmupTimestamp)
+            return undefined;
+        return Date.now() - this.warmupTimestamp;
+    }
+    /**
+     * Reset warmup state (for testing)
+     */
+    reset() {
+        this.isWarmedUp = false;
+        this.warmupTimestamp = undefined;
+        this.preloadedModules.clear();
+    }
+    /**
+     * Get preloaded modules
+     */
+    getPreloadedModules() {
+        return Array.from(this.preloadedModules);
+    }
+}
+exports.ColdStartOptimizer = ColdStartOptimizer;
+/**
+ * Decorator to enable cold start optimization for a method
+ */
+function OptimizeColdStart() {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const optimizer = ColdStartOptimizer.getInstance();
+            if (!optimizer.isWarm()) {
+                await optimizer.warmUp();
+            }
+            return originalMethod.apply(this, args);
+        };
+        return descriptor;
+    };
+}
+/**
+ * Keep-alive helper to schedule periodic pings.
+ * Does not perform an HTTP request; use a cron, external pinger, or implement fetch/http.get in the interval
+ * to actually warm the function.
+ */
+class KeepAliveHelper {
+    /**
+     * Start keep-alive interval (logs only; implement your own HTTP ping or use provisioned concurrency for warming).
+     */
+    start(url, intervalMs = 5 * 60 * 1000) {
+        this.pingUrl = url;
+        this.intervalId = setInterval(async () => {
+            try {
+                core_1.default.debug(`Sending keep-alive ping to ${url}`);
+                // Implement fetch(url) or http.get(url) here to actually warm the function
+            }
+            catch (error) {
+                core_1.default.error('Keep-alive ping failed:', error);
+            }
+        }, intervalMs);
+        core_1.default.info(`Keep-alive started for ${url} (interval: ${intervalMs}ms)`);
+    }
+    /**
+     * Stop keep-alive pings
+     */
+    stop() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = undefined;
+            core_1.default.info('Keep-alive stopped');
+        }
+    }
+}
+exports.KeepAliveHelper = KeepAliveHelper;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @hazeljs/serverless - Serverless adapters for HazelJS
+ */
+export { Serverless, getServerlessMetadata, isServerless, type ServerlessOptions, type ServerlessHandler, type ServerlessContext, type ServerlessEvent, type ServerlessResponse, } from './serverless.decorator';
+export { ColdStartOptimizer, OptimizeColdStart, KeepAliveHelper } from './cold-start.optimizer';
+export { LambdaAdapter, createLambdaHandler, type LambdaEvent, type LambdaContext, type LambdaHandlerOptions, } from './lambda.adapter';
+export { CloudFunctionAdapter, createCloudFunctionHandler, createCloudFunctionEventHandler, type CloudFunctionRequest, type CloudFunctionResponse, type CloudFunctionHandlerOptions, } from './cloud-function.adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,UAAU,EACV,qBAAqB,EACrB,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAChG,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,+BAA+B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * @hazeljs/serverless - Serverless adapters for HazelJS
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCloudFunctionEventHandler = exports.createCloudFunctionHandler = exports.CloudFunctionAdapter = exports.createLambdaHandler = exports.LambdaAdapter = exports.KeepAliveHelper = exports.OptimizeColdStart = exports.ColdStartOptimizer = exports.isServerless = exports.getServerlessMetadata = exports.Serverless = void 0;
+var serverless_decorator_1 = require("./serverless.decorator");
+Object.defineProperty(exports, "Serverless", { enumerable: true, get: function () { return serverless_decorator_1.Serverless; } });
+Object.defineProperty(exports, "getServerlessMetadata", { enumerable: true, get: function () { return serverless_decorator_1.getServerlessMetadata; } });
+Object.defineProperty(exports, "isServerless", { enumerable: true, get: function () { return serverless_decorator_1.isServerless; } });
+var cold_start_optimizer_1 = require("./cold-start.optimizer");
+Object.defineProperty(exports, "ColdStartOptimizer", { enumerable: true, get: function () { return cold_start_optimizer_1.ColdStartOptimizer; } });
+Object.defineProperty(exports, "OptimizeColdStart", { enumerable: true, get: function () { return cold_start_optimizer_1.OptimizeColdStart; } });
+Object.defineProperty(exports, "KeepAliveHelper", { enumerable: true, get: function () { return cold_start_optimizer_1.KeepAliveHelper; } });
+var lambda_adapter_1 = require("./lambda.adapter");
+Object.defineProperty(exports, "LambdaAdapter", { enumerable: true, get: function () { return lambda_adapter_1.LambdaAdapter; } });
+Object.defineProperty(exports, "createLambdaHandler", { enumerable: true, get: function () { return lambda_adapter_1.createLambdaHandler; } });
+var cloud_function_adapter_1 = require("./cloud-function.adapter");
+Object.defineProperty(exports, "CloudFunctionAdapter", { enumerable: true, get: function () { return cloud_function_adapter_1.CloudFunctionAdapter; } });
+Object.defineProperty(exports, "createCloudFunctionHandler", { enumerable: true, get: function () { return cloud_function_adapter_1.createCloudFunctionHandler; } });
+Object.defineProperty(exports, "createCloudFunctionEventHandler", { enumerable: true, get: function () { return cloud_function_adapter_1.createCloudFunctionEventHandler; } });

package/dist/integration.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Integration tests: real HazelJS app through Lambda and Cloud Function adapters.
+ * No mocks of @hazeljs/core — uses real HazelApp, router, and controllers.
+ */
+import 'reflect-metadata';
+//# sourceMappingURL=integration.test.d.ts.map

package/dist/integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.test.d.ts","sourceRoot":"","sources":["../src/integration.test.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,kBAAkB,CAAC"}