lambda-local
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    Lambda-local

    NPM

    Build Status

    Lambda-local lets you test NodeJS Amazon Lambda functions on your local machine, by providing a simplistic API and command-line tool.

    It does not aim to be perfectly feature proof as projects like serverless-offline or docker-lambda, but rather to remain very light (it still provides a fully built Context, handles all of its parameters and functions, and everything is customizable easily).

    The main target are unit tests and running lambda functions locally.

    Install

    npm install -g lambda-local

    Build

    make build

    Or

    npm install
    npm install --only=dev
    npm run build

    Usage

    • As an API: You can also use Lambda local directly in a script. For instance, it is interesting in a MochaJS test suite in order to get test coverage.
    • As a command line tool: You can use Lambda-local as a command line tool.

    If you're unsure about some definitions, see Definitions for terminology.

    About: API

    LambdaLocal

    API accessible with:

    const lambdaLocal = require("lambda-local");

    Or on TypeScript (supported on 1.7.0+):

    import lambdaLocal = require("lambda-local");

    lambdaLocal.execute(options)

    Executes a lambda given the options object, which is a dictionary where the keys may be:

    Key name Description
    event requested event as a json object
    lambdaPath requested path to the lambda function
    lambdaFunc pass the lambda function. You cannot use it at the same time as lambdaPath
    profilePath optional, path to your AWS credentials file
    profileName optional, aws profile name. Must be used with
    lambdaHandler optional handler name, default to handler
    region optional, AWS region, default to us-east-1
    timeoutMs optional, timeout, default to 3000 ms
    environment optional, extra environment variables for the lambda
    envfile optional, load an environment file before booting
    envdestroy optional, destroy added environment on closing, default to false
    verboseLevel optional, default 3. Level 2 dismiss handler() text, level 1 dismiss lambda-local text and level 0 dismiss also the result.
    callback optional, lambda third parameter callback. When left out a Promise is returned
    clientContext optional, used to populated clientContext property of lambda second parameter (context)

    lambdaLocal.setLogger(logger)

    lambdaLocal.getLogger()

    Those functions allow to access the winston logger used by lambda-local.

    API examples

    A lot of examples, especially used among Mocha, may be found in the test files over: here

    Basic usage: Using Promises
    const lambdaLocal = require('lambda-local');
    
    var jsonPayload = {
        'key': 1,
        'another_key': "Some text"
    }
    
    lambdaLocal.execute({
        event: jsonPayload,
        lambdaPath: path.join(__dirname, 'path_to_index.js'),
        profilePath: '~/.aws/credentials',
        profileName: 'default',
        timeoutMs: 3000
    }).then(function(done) {
        console.log(done);
    }).catch(function(err) {
        console.log(err);
    });

    Basic usage: using callbacks

    const lambdaLocal = require('lambda-local');
    
    var jsonPayload = {
        'key': 1,
        'another_key': "Some text"
    }
    
    lambdaLocal.execute({
        event: jsonPayload,
        lambdaPath: path.join(__dirname, 'path_to_index.js'),
        profilePath: '~/.aws/credentials',
        profileName: 'default',
        timeoutMs: 3000,
        callback: function(err, data) {
            if (err) {
                console.log(err);
            } else {
                console.log(data);
            }
        },
        clientContext: JSON.stringify({clientId: 'xxxx'})
    });

    About: CLI

    Available Arguments

    • -l, --lambda-path <lambda index path> (required) Specify Lambda function file name.
    • -e, --event-path <event path> (required --watch is not in use) Specify event data file name.
    • -h, --handler <handler name> (optional) Lambda function handler name. Default is "handler".
    • -t, --timeout <timeout> (optional) Seconds until lambda function timeout. Default is 3 seconds.
    • -r, --region <aws region> (optional) Sets the AWS region, defaults to us-east-1.
    • -P, --profile-path <aws profile name> (optional) Read the specified AWS credentials file.
    • -p, --profile <aws profile name> (optional) Use with -P: Read the AWS profile of the file.
    • -E, --environment <JSON {key:value}> (optional) Set extra environment variables for the lambda
    • --wait-empty-event-loop (optional) Sets callbackWaitsForEmptyEventLoop=True => will wait for an empty loop before returning. This is false by default because our implementation isn't perfect and only "emulates" it.
    • --envdestroy (optional) Destroy added environment on closing. Defaults to false
    • -v, --verboselevel <3/2/1/0> (optional) Default 3. Level 2 dismiss handler() text, level 1 dismiss lambda-local text and level 0 dismiss also the result.
    • --envfile <path/to/env/file> (optional) Set extra environment variables from an env file
    • --inspect [[host:]port] (optional) Starts lambda-local using the NodeJS inspector (available in nodejs > 8.0.0)
    • -W, --watch [port] (optional) Starts lambda-local in watch mode listening to the specified port [1-65535].

    CLI examples

    # Simple usage
    lambda-local -l index.js -h handler -e examples/s3-put.js
    
    # Input environment variables
    lambda-local -l index.js -h handler -e examples/s3-put.js -E '{"key":"value","key2":"value2"}'

    Running lambda functions as a HTTP Server

    A simple way you can run lambda functions locally, without the need to create any special template files (like Serverless plugin and SAM requires), just adding the parameter --watch. It will raise a http server listening to the specified port (default is 8008), then you can pass the event payload to the handler via request body.

    lambda-local -l examples/handler_helloworld.js -h handler --watch 8008
    
    curl --request POST \
      --url http://localhost:8008/ \
      --header 'content-type: application/json' \
      --data '{
    	"event": {
    		"key1": "value1",
    		"key2": "value2",
    		"key3": "value3"
    	}
    }'

    About: Definitions

    Event data

    Event sample data are placed in examples folder - feel free to use the files in here, or create your own event data. Event data are just JSON objects exported:

    // Sample event data
    module.exports = {
    	foo: "bar"
    };

    Context

    The context object has been sampled from what's visible when running an actual Lambda function on AWS, and the available documentation They may change the internals of this object, and Lambda-local does not guarantee that this will always be up-to-date with the actual context object.

    AWS-SDK

    As of version 2.0.0, lambda-local no longer packages AWS-SDK in its dependencies. To run a function that makes use of this module, make sure to install it as a dependency in your project.

    Other links

    Development

    • Run make to install npm modules. (Required to develop & test lambda-local)
    • Run make test to execute the mocha test.
    • Run make clean to reset the repository.

    License

    This library is released under the MIT license.

    Install

    npm i lambda-local

    DownloadsWeekly Downloads

    73,704

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    62.6 kB

    Total Files

    30

    Last publish

    Collaborators

    • ashiina
    • gpotter2