{"id":13583227,"url":"https://github.com/ashiina/lambda-local","last_synced_at":"2025-04-06T18:32:01.480Z","repository":{"id":25963753,"uuid":"29405654","full_name":"ashiina/lambda-local","owner":"ashiina","description":"Commandline tool to run Amazon Lambda function on local machines.","archived":false,"fork":false,"pushed_at":"2024-04-13T22:00:21.000Z","size":324,"stargazers_count":726,"open_issues_count":10,"forks_count":101,"subscribers_count":19,"default_branch":"develop","last_synced_at":"2024-05-01T14:59:54.878Z","etag":null,"topics":["amazon-lambda","aws-sdk","lambda","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashiina.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-17T21:05:17.000Z","updated_at":"2024-06-16T18:40:53.996Z","dependencies_parsed_at":"2024-04-13T22:29:22.306Z","dependency_job_id":"19364ab0-f514-4d90-a359-fbb921217468","html_url":"https://github.com/ashiina/lambda-local","commit_stats":{"total_commits":265,"total_committers":39,"mean_commits":6.794871794871795,"dds":0.6188679245283019,"last_synced_commit":"48630c88918135e33bdea9ad3eee61afe69b7747"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashiina%2Flambda-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashiina%2Flambda-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashiina%2Flambda-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashiina%2Flambda-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashiina","download_url":"https://codeload.github.com/ashiina/lambda-local/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247531104,"owners_count":20953893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-lambda","aws-sdk","lambda","nodejs"],"created_at":"2024-08-01T15:03:20.321Z","updated_at":"2025-04-06T18:32:00.966Z","avatar_url":"https://github.com/ashiina.png","language":"JavaScript","readme":"# Lambda-local\n\n[![NPM](https://nodei.co/npm/lambda-local.png?compact=true)](https://www.npmjs.com/package/lambda-local)\n\n[![Lambda-local unit tests](https://github.com/ashiina/lambda-local/actions/workflows/unittests.yml/badge.svg?branch=develop\u0026event=push)](https://github.com/ashiina/lambda-local/actions?query=event%3Apush)\n\nLambda-local lets you test **NodeJS Amazon Lambda functions** on your local machine, by providing a simplistic API and command-line tool.\n\nIt does not aim to be perfectly feature proof as projects like [serverless-offline](https://github.com/dherault/serverless-offline) or [docker-lambda](https://github.com/lambci/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).\n\nThe main target are unit tests and running lambda functions locally.\n\n## Install\n\n```bash\nnpm install -g lambda-local\n```\n\n## Build\n\n```bash\nmake build\n```\nOr\n```bash\nnpm install\nnpm install --only=dev\nnpm run build\n```\n\n## Usage\n\n- **As an API:** You can also use Lambda local directly in a script. For instance, it is interesting in a [MochaJS][1] test suite in order to get test coverage.\n- **As a command line tool:** You can use Lambda-local as a command line tool.\n\nIf you're unsure about some definitions, see [Definitions](#about-definitions) for terminology.\n\n## About: API\n\n### LambdaLocal\n\nAPI accessible with:\n```js\nconst lambdaLocal = require(\"lambda-local\");\n```\n\nOr on TypeScript (supported on 1.7.0+):\n\n```js\nimport lambdaLocal = require(\"lambda-local\");\n```\n\n#### `lambdaLocal.execute(options)`\n\nExecutes a lambda given the `options` object, which is a dictionary where the keys may be:\n\n| Key name | Description |\n| --- | --- |\n| `event`|requested event as a json object|\n| `lambdaPath`|requested path to the lambda function|\n| `lambdaFunc`|pass the lambda function. You cannot use it at the same time as lambdaPath|\n| `profilePath`|optional, path to your AWS credentials file|\n| `profileName`|optional, aws profile name. Must be used with |\n| `lambdaHandler`|optional handler name, default to `handler`|\n| `region`|optional, AWS region, default to `us-east-1`|| `callbackWaitsForEmptyEventLoop`|optional, default to `false`. Setting it to True will wait for an empty loop before returning.|\n| `timeoutMs`|optional, timeout, default to 3000 ms|\n| `esm`|boolean, marks that the script is an ECMAScript module (use import), default false|\n| `environment`|optional, extra environment variables for the lambda|\n| `envfile`|optional, load an environment file before booting|\n| `envdestroy`|optional, destroy added environment on closing, default to false|\n| `verboseLevel`|optional, default 3. Level 2 dismiss handler() text, level 1 dismiss lambda-local text and level 0 dismiss also the result. Level -1 only displays handler() text.|\n| `callback`|optional, lambda third parameter [callback][1]. When left out a Promise is returned|\n| `onInvocationEnd`|optional. called once the invocation ended. useful when awslambda.streamifyResponse is used to distinguish between end of response stream and end of invocation. |\n| `clientContext`|optional, used to populated clientContext property of lambda second parameter (context)\n| `contextOverwrite`| optional, a function that overwrites the context object. It can get and overwrite the values of the context (such as awsRequestId). |\n\n#### `lambdaLocal.setLogger(logger)`\n#### `lambdaLocal.getLogger()`\n\nThose functions allow to access the [winston](https://www.npmjs.com/package/winston) logger used by lambda-local.\n\n## API examples\n\nA lot of examples, especially used among Mocha, may be found in the test files over: [here](https://github.com/ashiina/lambda-local/tree/develop/test)\n\n##### Basic usage: Using Promises\n\n```js\nconst lambdaLocal = require('lambda-local');\n\nvar jsonPayload = {\n    'key': 1,\n    'another_key': \"Some text\"\n}\n\nlambdaLocal.execute({\n    event: jsonPayload,\n    lambdaPath: path.join(__dirname, 'path_to_index.js'),\n    profilePath: '~/.aws/credentials',\n    profileName: 'default',\n    timeoutMs: 3000\n}).then(function(done) {\n    console.log(done);\n}).catch(function(err) {\n    console.log(err);\n});\n```\n\n#### Basic usage: using callbacks\n\n```js\nconst lambdaLocal = require('lambda-local');\n\nvar jsonPayload = {\n    'key': 1,\n    'another_key': \"Some text\"\n}\n\nlambdaLocal.execute({\n    event: jsonPayload,\n    lambdaPath: path.join(__dirname, 'path_to_index.js'),\n    profilePath: '~/.aws/credentials',\n    profileName: 'default',\n    timeoutMs: 3000,\n    callback: function(err, data) {\n        if (err) {\n            console.log(err);\n        } else {\n            console.log(data);\n        }\n    },\n    clientContext: JSON.stringify({clientId: 'xxxx'})\n});\n```\n\n## About: CLI\n\n### Available Arguments\n*    `-l, --lambda-path \u003clambda index path\u003e`            (required) Specify Lambda function file name.\n*    `-e, --event-path \u003cevent path\u003e`                    (required --watch is not in use) Specify event data file name.\n*    `-h, --handler \u003chandler name\u003e`                     (optional) Lambda function handler name. Default is \"handler\".\n*    `-t, --timeout \u003ctimeout\u003e`                          (optional) Seconds until lambda function timeout. Default is 3 seconds.\n*    `--esm`                                            (optional) Load lambda function as ECMAScript module.\n*    `-r, --region \u003caws region\u003e`                        (optional) Sets the AWS region, defaults to us-east-1.\n*    `-P, --profile-path \u003caws profile name\u003e`            (optional) Read the specified AWS credentials file.\n*    `-p, --profile \u003caws profile name\u003e`                 (optional) Use with **-P**: Read the AWS profile of the file.\n*    `-E, --environment \u003cJSON {key:value}\u003e`             (optional) Set extra environment variables for the lambda\n*    `--wait-empty-event-loop`                          (optional) Sets callbackWaitsForEmptyEventLoop=True =\u003e will wait for an empty loop before returning. This is false by default because our implementation isn\\'t perfect and only \"emulates\" it.\n*    `--envdestroy`                                     (optional) Destroy added environment on closing. Defaults to false\n*    `-v, --verboselevel \u003c3/2/1/0\u003e`                     (optional) Default 3. Level 2 dismiss handler() text, level 1 dismiss lambda-local text and level 0 dismiss also the result.\n*    `--envfile \u003cpath/to/env/file\u003e`                     (optional) Set extra environment variables from an env file\n*    `--inspect [[host:]port]`                          (optional) Starts lambda-local using the NodeJS inspector (available in nodejs \u003e 8.0.0)\n*    `-W, --watch [port]`                               (optional) Starts lambda-local in watch mode listening to the specified port [1-65535].\n\n### CLI examples\n\n```bash\n# Simple usage\nlambda-local -l index.js -h handler -e examples/s3-put.js\n\n# Input environment variables\nlambda-local -l index.js -h handler -e examples/s3-put.js -E '{\"key\":\"value\",\"key2\":\"value2\"}'\n```\n\n#### Running lambda functions as a HTTP Server (Amazon API Gateway payload format version 2.0.)\n\nA 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). You can then call the lambda as mentionned here:\nhttps://docs.aws.amazon.com/lambda/latest/dg/urls-invocation.html\n\n```bash\nlambda-local -l examples/handler_gateway2.js -h handler --watch 8008\n\ncurl --request POST \\\n  --url http://localhost:8008/ \\\n  --header 'content-type: application/json' \\\n  --data '{\n        \"key1\": \"value1\",\n        \"key2\": \"value2\",\n        \"key3\": \"value3\"\n}'\n{\"message\":\"This is a response\"}\n```\n\nYou can also use the following format for your event, in order to avoid using the Amazon API Gateway format:\n```\n{\n    \"event\": {\n        \"key1\": \"value1\",\n        \"key2\": \"value2\",\n        \"key3\": \"value3\"\n    }\n}\n```\n\nIn this case, the event will be passed directly to the handler.\n\n## About: Definitions\n\n### Event data\nEvent sample data are placed in `examples` folder - feel free to use the files in here, or create your own event data.\nEvent data are just JSON objects exported:\n\n```js\n// Sample event data\nmodule.exports = {\n    foo: \"bar\"\n};\n```\n\n### Context\nThe `context` object has been sampled from what's visible when running an actual Lambda function on AWS, and the [available documentation](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html)\nThey 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.\n\n### AWS-SDK\nAs 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.\n\n## Other links\n\n- If you are willing to test an app based on the ASK-SDK, have a look at https://github.com/taimos/ask-sdk-test\n\n## Development\n\n * Run `make` to install npm modules. (Required to develop \u0026 test lambda-local)\n * Run `make test` to execute the mocha test.\n* Run `make clean` to reset the repository.\n\n## License\n\nThis library is released under the MIT license.\n\n[1]: http://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashiina%2Flambda-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashiina%2Flambda-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashiina%2Flambda-local/lists"}