0
# Lambda Functions
1

2
Utilities for creating and managing serverless Lambda functions, including bundling files into deployment packages.
3

4
## Capabilities
5

6
### Lambda Class
7

8
Represents a serverless Lambda function with bundled code and configuration.
9

10
```typescript { .api }
11
/**
12
 * Serverless Lambda function with bundled code
13
 */
14
class Lambda {
15
  public type: 'Lambda';
16
  public zipBuffer: Buffer;
17
  public handler: string;
18
  public runtime: string;
19
  public memory?: number;
20
  public maxDuration?: number;
21
  public environment: { [key: string]: string };
22

23
  constructor(options: LambdaOptions);
24
}
25

26
interface LambdaOptions {
27
  zipBuffer: Buffer;
28
  handler: string;
29
  runtime: string;
30
  memory?: number;
31
  maxDuration?: number;
32
  environment: { [key: string]: string };
33
}
34
```
35

36
### Create Lambda Function
37

38
Creates a Lambda instance from files, handling bundling and compression automatically.
39

40
```typescript { .api }
41
/**
42
 * Create a Lambda function from files
43
 * @param options - Lambda creation options
44
 * @returns Promise resolving to Lambda instance
45
 */
46
function createLambda(options: CreateLambdaOptions): Promise<Lambda>;
47

48
interface CreateLambdaOptions {
49
  /** Files to include in the Lambda bundle */
50
  files: Files;
51
  /** Handler function path (e.g., "index.handler") */
52
  handler: string;
53
  /** Runtime environment (e.g., "nodejs14.x", "python3.8") */
54
  runtime: string;
55
  /** Memory allocation in MB (128-3008 in steps of 64) */
56
  memory?: number;
57
  /** Maximum execution duration in seconds (1-900) */
58
  maxDuration?: number;
59
  /** Environment variables for the Lambda */
60
  environment?: { [key: string]: string };
61
}
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
import { createLambda, FileFsRef } from "@now/build-utils";
68

69
// Create Lambda from Node.js files
70
const files = {
71
  "index.js": new FileFsRef({ fsPath: "/build/index.js" }),
72
  "package.json": new FileFsRef({ fsPath: "/build/package.json" }),
73
  "node_modules/": new FileFsRef({ fsPath: "/build/node_modules" })
74
};
75

76
const lambda = await createLambda({
77
  files,
78
  handler: "index.handler",
79
  runtime: "nodejs14.x",
80
  memory: 256,
81
  maxDuration: 30,
82
  environment: {
83
    NODE_ENV: "production",
84
    API_KEY: process.env.API_KEY
85
  }
86
});
87

88
// Create Python Lambda
89
const pythonLambda = await createLambda({
90
  files: {
91
    "main.py": new FileFsRef({ fsPath: "/build/main.py" }),
92
    "requirements.txt": new FileFsRef({ fsPath: "/build/requirements.txt" })
93
  },
94
  handler: "main.handler",
95
  runtime: "python3.8",
96
  memory: 512
97
});
98
```
99

100
### Lambda Options from Function Configuration
101

102
Extracts Lambda-specific options (memory, maxDuration) from function configuration using pattern matching.
103

104
```typescript { .api }
105
/**
106
 * Extract Lambda options from function configuration
107
 * @param options - Configuration extraction options
108
 * @returns Promise resolving to Lambda options
109
 */
110
function getLambdaOptionsFromFunction(
111
  options: GetLambdaOptionsFromFunctionOptions
112
): Promise<Pick<LambdaOptions, 'memory' | 'maxDuration'>>;
113

114
interface GetLambdaOptionsFromFunctionOptions {
115
  /** Source file path to match against patterns */
116
  sourceFile: string;
117
  /** Configuration object containing functions settings */
118
  config?: Config;
119
}
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
import { getLambdaOptionsFromFunction } from "@now/build-utils";
126

127
const config = {
128
  functions: {
129
    "api/users/*.js": {
130
      memory: 512,
131
      maxDuration: 60
132
    },
133
    "api/*/heavy.js": {
134
      memory: 1024,
135
      maxDuration: 120
136
    }
137
  }
138
};
139

140
// Get options for specific file
141
const options = await getLambdaOptionsFromFunction({
142
  sourceFile: "api/users/create.js",
143
  config
144
});
145
// Returns: { memory: 512, maxDuration: 60 }
146
```
147

148
### Zip Creation
149

150
Creates ZIP archives from Files collections, handling symbolic links and proper file modes.
151

152
```typescript { .api }
153
/**
154
 * Create ZIP buffer from files
155
 * @param files - Files to include in ZIP
156
 * @returns Promise resolving to ZIP buffer
157
 */
158
function createZip(files: Files): Promise<Buffer>;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { createZip, FileFsRef } from "@now/build-utils";
165

166
const files = {
167
  "index.js": new FileFsRef({ fsPath: "/src/index.js" }),
168
  "lib/utils.js": new FileFsRef({ fsPath: "/src/lib/utils.js" })
169
};
170

171
const zipBuffer = await createZip(files);
172
// zipBuffer contains compressed files ready for deployment
173
```
174

175
## Advanced Configuration
176

177
### Runtime Support
178

179
The Lambda system supports multiple runtime environments:
180

181
- **Node.js**: `nodejs12.x`, `nodejs14.x`, `nodejs16.x`
182
- **Python**: `python3.6`, `python3.7`, `python3.8`, `python3.9`  
183
- **Go**: `go1.x`
184
- **Ruby**: `ruby2.7`
185
- **Java**: `java8`, `java11`
186

187
### Memory Configuration
188

189
Memory can be configured from 128 MB to 3008 MB in increments of 64 MB:
190

191
```typescript
192
// Valid memory values
193
const validMemory = [128, 192, 256, 320, 384, 448, 512, 576, 640, 704, 768, 832, 896, 960, 1024, /* ... up to 3008 */];
194
```
195

196
### Function Patterns
197

198
The `functions` configuration supports glob patterns for matching files:
199

200
```typescript
201
const functionConfig = {
202
  functions: {
203
    "api/**/*.js": { memory: 256, maxDuration: 30 },
204
    "api/heavy/*.js": { memory: 1024, maxDuration: 120 },
205
    "webhooks/stripe.js": { memory: 512, maxDuration: 60 }
206
  }
207
};
208
```
209

210
## Error Handling
211

212
Lambda creation may throw errors for:
213

214
- Invalid runtime specifications
215
- Memory values outside allowed range (128-3008 MB)
216
- Duration values outside allowed range (1-900 seconds)
217
- File bundling failures
218
- ZIP compression errors