@hazeljs/serverless 0.2.0-beta.1

package/README.md

@@ -0,0 +1,500 @@
+# @hazeljs/serverless
+
+**Serverless Adapters for HazelJS - AWS Lambda & Google Cloud Functions**
+
+Deploy HazelJS applications to serverless platforms with zero configuration changes.
+
+[![npm version](https://img.shields.io/npm/v/@hazeljs/serverless.svg)](https://www.npmjs.com/package/@hazeljs/serverless)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ☁️ **AWS Lambda** - Deploy to AWS Lambda
+- 🌐 **Google Cloud Functions** - Deploy to GCP
+- 🔄 **Zero Config** - No code changes needed
+- 🎯 **Cold Start Optimization** - Minimize cold start times
+- 📊 **Request/Response Mapping** - Automatic event transformation
+- 🔐 **Environment Variables** - Seamless config management
+- 🎨 **Decorator Support** - `@Serverless` decorator
+- 📦 **Bundle Optimization** - Tree-shaking and minification
+
+## Installation
+
+```bash
+npm install @hazeljs/serverless
+```
+
+## AWS Lambda
+
+### Quick Start
+
+```typescript
+// lambda.ts
+import { createLambdaHandler } from '@hazeljs/serverless';
+import { AppModule } from './app.module';
+
+export const handler = createLambdaHandler(AppModule);
+```
+
+### With Options
+
+```typescript
+import { createLambdaHandler } from '@hazeljs/serverless';
+import { AppModule } from './app.module';
+
+export const handler = createLambdaHandler(AppModule, {
+  // Enable binary response
+  binaryMimeTypes: ['image/*', 'application/pdf'],
+  
+  // Custom initialization
+  onInit: async (app) => {
+    console.log('Lambda initialized');
+  },
+  
+  // Custom error handling
+  onError: (error) => {
+    console.error('Lambda error:', error);
+  },
+});
+```
+
+### Deployment
+
+#### Using AWS SAM
+
+```yaml
+# template.yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+
+Resources:
+  HazelFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: dist/
+      Handler: lambda.handler
+      Runtime: nodejs20.x
+      MemorySize: 512
+      Timeout: 30
+      Environment:
+        Variables:
+          NODE_ENV: production
+          DATABASE_URL: !Ref DatabaseUrl
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /{proxy+}
+            Method: ANY
+```
+
+Deploy:
+
+```bash
+npm run build
+sam build
+sam deploy --guided
+```
+
+#### Using Serverless Framework
+
+```yaml
+# serverless.yml
+service: hazeljs-app
+
+provider:
+  name: aws
+  runtime: nodejs20.x
+  stage: ${opt:stage, 'dev'}
+  region: us-east-1
+  environment:
+    NODE_ENV: ${self:provider.stage}
+    DATABASE_URL: ${env:DATABASE_URL}
+
+functions:
+  api:
+    handler: dist/lambda.handler
+    events:
+      - http:
+          path: /{proxy+}
+          method: ANY
+          cors: true
+
+package:
+  individually: true
+  patterns:
+    - '!node_modules/**'
+    - 'node_modules/@hazeljs/**'
+    - 'dist/**'
+```
+
+Deploy:
+
+```bash
+npm run build
+serverless deploy
+```
+
+## Google Cloud Functions
+
+### Quick Start
+
+```typescript
+// index.ts
+import { createCloudFunctionHandler } from '@hazeljs/serverless';
+import { AppModule } from './app.module';
+
+export const hazelApp = createCloudFunctionHandler(AppModule);
+```
+
+### With Options
+
+```typescript
+import { createCloudFunctionHandler } from '@hazeljs/serverless';
+import { AppModule } from './app.module';
+
+export const hazelApp = createCloudFunctionHandler(AppModule, {
+  // Custom initialization
+  onInit: async (app) => {
+    console.log('Cloud Function initialized');
+  },
+  
+  // Custom error handling
+  onError: (error) => {
+    console.error('Cloud Function error:', error);
+  },
+});
+```
+
+### Deployment
+
+#### Using gcloud CLI
+
+```bash
+# Build
+npm run build
+
+# Deploy
+gcloud functions deploy hazeljs-app \
+  --runtime nodejs20 \
+  --trigger-http \
+  --allow-unauthenticated \
+  --entry-point hazelApp \
+  --source dist \
+  --set-env-vars NODE_ENV=production,DATABASE_URL=your-db-url
+```
+
+#### Using Cloud Functions YAML
+
+```yaml
+# function.yaml
+runtime: nodejs20
+entryPoint: hazelApp
+environmentVariables:
+  NODE_ENV: production
+  DATABASE_URL: ${DATABASE_URL}
+```
+
+Deploy:
+
+```bash
+gcloud functions deploy hazeljs-app --config function.yaml
+```
+
+## Decorator-Based Optimization
+
+Mark routes for serverless optimization:
+
+```typescript
+import { Controller, Get } from '@hazeljs/core';
+import { Serverless } from '@hazeljs/serverless';
+
+@Controller('/api')
+export class ApiController {
+  @Get('/hello')
+  @Serverless({ optimize: true })
+  hello() {
+    return { message: 'Hello from serverless!' };
+  }
+
+  @Get('/data')
+  @Serverless({
+    optimize: true,
+    cache: {
+      enabled: true,
+      ttl: 300, // 5 minutes
+    },
+  })
+  getData() {
+    return { data: 'cached response' };
+  }
+}
+```
+
+## Cold Start Optimization
+
+### Minimize Bundle Size
+
+```typescript
+// Use dynamic imports for heavy dependencies
+@Get('/heavy')
+async heavyOperation() {
+  const { processData } = await import('./heavy-processor');
+  return processData();
+}
+```
+
+### Connection Pooling
+
+```typescript
+// Reuse database connections across invocations
+let cachedDb: any = null;
+
+async function connectToDatabase() {
+  if (cachedDb) {
+    return cachedDb;
+  }
+
+  cachedDb = await createDatabaseConnection();
+  return cachedDb;
+}
+
+@Injectable()
+export class DatabaseService {
+  async query(sql: string) {
+    const db = await connectToDatabase();
+    return db.query(sql);
+  }
+}
+```
+
+### Provisioned Concurrency (AWS Lambda)
+
+```yaml
+# template.yaml
+Resources:
+  HazelFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      # ... other properties
+      ProvisionedConcurrencyConfig:
+        ProvisionedConcurrentExecutions: 5
+```
+
+## Environment-Specific Configuration
+
+```typescript
+// config/serverless.config.ts
+export const serverlessConfig = {
+  development: {
+    timeout: 30,
+    memorySize: 512,
+  },
+  production: {
+    timeout: 60,
+    memorySize: 1024,
+    provisionedConcurrency: 5,
+  },
+};
+
+// lambda.ts
+const config = serverlessConfig[process.env.NODE_ENV || 'development'];
+
+export const handler = createLambdaHandler(AppModule, {
+  timeout: config.timeout,
+});
+```
+
+## Request/Response Handling
+
+### AWS Lambda Event Types
+
+```typescript
+import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+
+// Access raw Lambda event
+@Get('/lambda-info')
+getLambdaInfo(@Req() req: any) {
+  const event: APIGatewayProxyEvent = req.apiGateway.event;
+  
+  return {
+    requestId: event.requestContext.requestId,
+    sourceIp: event.requestContext.identity.sourceIp,
+    userAgent: event.headers['user-agent'],
+  };
+}
+```
+
+### Binary Responses
+
+```typescript
+@Get('/image')
+@Serverless({ binaryResponse: true })
+async getImage(@Res() res: Response) {
+  const image = await fs.readFile('image.png');
+  res.setHeader('Content-Type', 'image/png');
+  res.send(image);
+}
+```
+
+## Logging
+
+### CloudWatch Logs (AWS)
+
+```typescript
+import { Logger } from '@hazeljs/core';
+
+@Injectable()
+export class MyService {
+  private logger = new Logger(MyService.name);
+
+  async doSomething() {
+    this.logger.log('Processing request');
+    this.logger.error('An error occurred');
+    this.logger.warn('Warning message');
+  }
+}
+```
+
+### Cloud Logging (GCP)
+
+```typescript
+import { Logger } from '@hazeljs/core';
+
+@Injectable()
+export class MyService {
+  private logger = new Logger(MyService.name);
+
+  async doSomething() {
+    // Logs automatically sent to Cloud Logging
+    this.logger.log('Processing request', {
+      userId: '123',
+      action: 'create',
+    });
+  }
+}
+```
+
+## Best Practices
+
+1. **Minimize Dependencies** - Only include necessary packages
+2. **Reuse Connections** - Cache database and API connections
+3. **Use Environment Variables** - Store configuration externally
+4. **Optimize Bundle Size** - Use tree-shaking and minification
+5. **Handle Cold Starts** - Implement warming strategies
+6. **Monitor Performance** - Track execution time and memory usage
+7. **Set Appropriate Timeouts** - Balance cost and functionality
+8. **Use Provisioned Concurrency** - For latency-sensitive endpoints
+
+## Monitoring
+
+### AWS Lambda
+
+```typescript
+// Add X-Ray tracing
+import AWSXRay from 'aws-xray-sdk-core';
+
+const AWS = AWSXRay.captureAWS(require('aws-sdk'));
+
+// Custom metrics
+import { CloudWatch } from 'aws-sdk';
+
+const cloudwatch = new CloudWatch();
+
+async function recordMetric(name: string, value: number) {
+  await cloudwatch.putMetricData({
+    Namespace: 'HazelJS',
+    MetricData: [{
+      MetricName: name,
+      Value: value,
+      Unit: 'Count',
+    }],
+  }).promise();
+}
+```
+
+### Google Cloud Functions
+
+```typescript
+// Add Cloud Trace
+import { TraceAgent } from '@google-cloud/trace-agent';
+
+TraceAgent.start();
+
+// Custom metrics
+import { Monitoring } from '@google-cloud/monitoring';
+
+const monitoring = new Monitoring.MetricServiceClient();
+
+async function recordMetric(name: string, value: number) {
+  const request = {
+    name: monitoring.projectPath(projectId),
+    timeSeries: [{
+      metric: { type: `custom.googleapis.com/${name}` },
+      points: [{
+        interval: { endTime: { seconds: Date.now() / 1000 } },
+        value: { doubleValue: value },
+      }],
+    }],
+  };
+  
+  await monitoring.createTimeSeries(request);
+}
+```
+
+## Cost Optimization
+
+### Request Batching
+
+```typescript
+// Batch multiple operations
+@Post('/batch')
+async batchProcess(@Body() items: any[]) {
+  const results = await Promise.all(
+    items.map(item => this.processItem(item))
+  );
+  return results;
+}
+```
+
+### Caching
+
+```typescript
+import { Cache } from '@hazeljs/cache';
+
+@Injectable()
+export class DataService {
+  @Cache({ key: 'expensive-data', ttl: 3600 })
+  async getExpensiveData() {
+    // This will be cached for 1 hour
+    return await this.fetchFromDatabase();
+  }
+}
+```
+
+## Examples
+
+See the [examples](../../example/src/serverless) directory for complete working examples.
+
+## Testing
+
+```bash
+npm test
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [HazelJS](https://hazeljs.com)
+
+## Links
+
+- [Documentation](https://hazeljs.com/docs/packages/serverless)
+- [AWS Lambda Docs](https://docs.aws.amazon.com/lambda/)
+- [Google Cloud Functions Docs](https://cloud.google.com/functions/docs)
+- [GitHub](https://github.com/hazel-js/hazeljs)
+- [Issues](https://github.com/hazeljs/hazel-js/issues)
+- [Discord](https://discord.gg/hazeljs)

package/dist/cloud-function.adapter.d.ts

@@ -0,0 +1,97 @@
+import { HazelApp } from '@hazeljs/core';
+import { Type } from '@hazeljs/core';
+/**
+ * Google Cloud Function Request
+ */
+export interface CloudFunctionRequest {
+    method: string;
+    url: string;
+    path: string;
+    headers: Record<string, string | string[]>;
+    query: Record<string, string | string[]>;
+    body?: unknown;
+    rawBody?: Buffer;
+}
+/**
+ * Google Cloud Function Response
+ */
+export interface CloudFunctionResponse {
+    status(code: number): CloudFunctionResponse;
+    set(field: string, value: string): CloudFunctionResponse;
+    send(body: unknown): void;
+    json(body: unknown): void;
+    end(): void;
+}
+/**
+ * Cloud Function adapter for HazelJS
+ */
+export declare class CloudFunctionAdapter {
+    private moduleClass;
+    private app?;
+    private optimizer;
+    private isColdStart;
+    constructor(moduleClass: Type<unknown>);
+    /**
+     * Initialize the HazelJS application
+     */
+    private initialize;
+    /**
+     * Create Cloud Function HTTP handler
+     */
+    createHttpHandler(): (req: CloudFunctionRequest, res: CloudFunctionResponse) => Promise<void>;
+    /**
+     * Create Cloud Function event handler (for Pub/Sub, Storage, etc.)
+     */
+    createEventHandler(): (event: unknown, context: unknown) => Promise<void>;
+    /**
+     * Convert Cloud Function request to internal format
+     */
+    private convertCloudFunctionRequest;
+    /**
+     * Normalize headers (convert string[] to string)
+     */
+    private normalizeHeaders;
+    /**
+     * Normalize query parameters
+     */
+    private normalizeQuery;
+    /**
+     * Process request through HazelJS router
+     */
+    private processRequest;
+    /**
+     * Get application instance
+     */
+    getApp(): HazelApp | undefined;
+    /**
+     * Check if this is a cold start
+     */
+    isCold(): boolean;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare function createCloudFunctionHandler(moduleClass: Type<unknown>): (req: CloudFunctionRequest, res: CloudFunctionResponse) => Promise<void>;
+/**
+ * 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);
+ * ```
+ */
+export declare function createCloudFunctionEventHandler(moduleClass: Type<unknown>): (event: unknown, context: unknown) => Promise<void>;
+//# sourceMappingURL=cloud-function.adapter.d.ts.map

package/dist/cloud-function.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-function.adapter.d.ts","sourceRoot":"","sources":["../src/cloud-function.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAKrC;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAAC;IAC5C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAAC;IACzD,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,GAAG,IAAI,IAAI,CAAC;CACb;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAKnB,OAAO,CAAC,WAAW;IAJ/B,OAAO,CAAC,GAAG,CAAC,CAAW;IACvB,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,WAAW,CAAQ;gBAEP,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC;IAI9C;;OAEG;YACW,UAAU;IAqBxB;;OAEG;IACH,iBAAiB,KACD,KAAK,oBAAoB,EAAE,KAAK,qBAAqB,KAAG,OAAO,CAAC,IAAI,CAAC;IAqCrF;;OAEG;IACH,kBAAkB,KACF,OAAO,OAAO,EAAE,SAAS,OAAO,KAAG,OAAO,CAAC,IAAI,CAAC;IA0BhE;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAoBnC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;YACW,cAAc;IAsF5B;;OAEG;IACH,MAAM,IAAI,QAAQ,GAAG,SAAS;IAI9B;;OAEG;IACH,MAAM,IAAI,OAAO;CAGlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,GACzB,CAAC,GAAG,EAAE,oBAAoB,EAAE,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAG1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,GACzB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAGrD"}