tessl/npm-now--build-utils

Build utilities for Now (Vercel) serverless platform runtime development

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Lambda Functions

Name: tessl/npm-now--build-utils
Author: tessl

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

Capabilities

Lambda Class

Represents a serverless Lambda function with bundled code and configuration.

/**
 * Serverless Lambda function with bundled code
 */
class Lambda {
  public type: 'Lambda';
  public zipBuffer: Buffer;
  public handler: string;
  public runtime: string;
  public memory?: number;
  public maxDuration?: number;
  public environment: { [key: string]: string };

  constructor(options: LambdaOptions);
}

interface LambdaOptions {
  zipBuffer: Buffer;
  handler: string;
  runtime: string;
  memory?: number;
  maxDuration?: number;
  environment: { [key: string]: string };
}

Create Lambda Function

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

/**
 * Create a Lambda function from files
 * @param options - Lambda creation options
 * @returns Promise resolving to Lambda instance
 */
function createLambda(options: CreateLambdaOptions): Promise<Lambda>;

interface CreateLambdaOptions {
  /** Files to include in the Lambda bundle */
  files: Files;
  /** Handler function path (e.g., "index.handler") */
  handler: string;
  /** Runtime environment (e.g., "nodejs14.x", "python3.8") */
  runtime: string;
  /** Memory allocation in MB (128-3008 in steps of 64) */
  memory?: number;
  /** Maximum execution duration in seconds (1-900) */
  maxDuration?: number;
  /** Environment variables for the Lambda */
  environment?: { [key: string]: string };
}

Usage Examples:

import { createLambda, FileFsRef } from "@now/build-utils";

// Create Lambda from Node.js files
const files = {
  "index.js": new FileFsRef({ fsPath: "/build/index.js" }),
  "package.json": new FileFsRef({ fsPath: "/build/package.json" }),
  "node_modules/": new FileFsRef({ fsPath: "/build/node_modules" })
};

const lambda = await createLambda({
  files,
  handler: "index.handler",
  runtime: "nodejs14.x",
  memory: 256,
  maxDuration: 30,
  environment: {
    NODE_ENV: "production",
    API_KEY: process.env.API_KEY
  }
});

// Create Python Lambda
const pythonLambda = await createLambda({
  files: {
    "main.py": new FileFsRef({ fsPath: "/build/main.py" }),
    "requirements.txt": new FileFsRef({ fsPath: "/build/requirements.txt" })
  },
  handler: "main.handler",
  runtime: "python3.8",
  memory: 512
});

Lambda Options from Function Configuration

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

/**
 * Extract Lambda options from function configuration
 * @param options - Configuration extraction options
 * @returns Promise resolving to Lambda options
 */
function getLambdaOptionsFromFunction(
  options: GetLambdaOptionsFromFunctionOptions
): Promise<Pick<LambdaOptions, 'memory' | 'maxDuration'>>;

interface GetLambdaOptionsFromFunctionOptions {
  /** Source file path to match against patterns */
  sourceFile: string;
  /** Configuration object containing functions settings */
  config?: Config;
}

Usage Examples:

import { getLambdaOptionsFromFunction } from "@now/build-utils";

const config = {
  functions: {
    "api/users/*.js": {
      memory: 512,
      maxDuration: 60
    },
    "api/*/heavy.js": {
      memory: 1024,
      maxDuration: 120
    }
  }
};

// Get options for specific file
const options = await getLambdaOptionsFromFunction({
  sourceFile: "api/users/create.js",
  config
});
// Returns: { memory: 512, maxDuration: 60 }

Zip Creation

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

/**
 * Create ZIP buffer from files
 * @param files - Files to include in ZIP
 * @returns Promise resolving to ZIP buffer
 */
function createZip(files: Files): Promise<Buffer>;

Usage Examples:

import { createZip, FileFsRef } from "@now/build-utils";

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

const zipBuffer = await createZip(files);
// zipBuffer contains compressed files ready for deployment

Advanced Configuration

Runtime Support

The Lambda system supports multiple runtime environments:

Node.js: nodejs12.x, nodejs14.x, nodejs16.x
Python: python3.6, python3.7, python3.8, python3.9
Go: go1.x
Ruby: ruby2.7
Java: java8, java11

Memory Configuration

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

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

Function Patterns

The functions configuration supports glob patterns for matching files:

const functionConfig = {
  functions: {
    "api/**/*.js": { memory: 256, maxDuration: 30 },
    "api/heavy/*.js": { memory: 1024, maxDuration: 120 },
    "webhooks/stripe.js": { memory: 512, maxDuration: 60 }
  }
};