{"id":14384966,"url":"https://github.com/beginner-corp/lambda","last_synced_at":"2025-08-23T18:31:07.034Z","repository":{"id":66077964,"uuid":"54931444","full_name":"beginner-corp/lambda","owner":"beginner-corp","description":" :heart_decoration: Authoring tools for AWS Lambda functions","archived":true,"fork":false,"pushed_at":"2017-05-18T16:07:56.000Z","size":80,"stargazers_count":173,"open_issues_count":1,"forks_count":15,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-08-29T18:36:33.429Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beginner-corp.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-03-28T23:45:20.000Z","updated_at":"2024-08-06T00:29:13.000Z","dependencies_parsed_at":"2024-01-14T20:18:57.939Z","dependency_job_id":"8ab6f7ae-bdae-4550-bf2f-411ddd0a92ed","html_url":"https://github.com/beginner-corp/lambda","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Flambda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Flambda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Flambda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Flambda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beginner-corp","download_url":"https://codeload.github.com/beginner-corp/lambda/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230720960,"owners_count":18270483,"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":[],"created_at":"2024-08-28T18:01:49.275Z","updated_at":"2024-12-21T13:30:28.814Z","avatar_url":"https://github.com/beginner-corp.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[ ![Codeship Status for smallwins/lambda](https://codeship.com/projects/2e4082e0-d808-0133-2035-1eae90b9310e/status?branch=master)](https://codeship.com/projects/143109)\n\n---\n\n## @smallwins/lambda :seedling::raised_hands:λ  \n\n- Author your AWS Lambda functions as pure node style callbacks (aka errbacks)\n- Familiar middleware pattern for composition\n- Event sources like DynamoDB triggers and SNS topics too\n- Helpful npm scripts `lambda-create`, `lambda-list`, `lambda-deploy` and `lambda-invoke` (and more)\n\n#### :satellite::satellite::satellite: λ returning json results :mailbox:\n\nHere is a vanilla AWS Lambda example for performing a sum. Given `event.query.x = 1` it will return `{count:2}`.\n\n```javascript\nexports.handler = function sum(event, context) {\n  var errors = []\n  if (typeof event.query === 'undefined') {\n    errors.push(ReferenceError('missing event.query'))\n  }\n  if (event.query \u0026\u0026 typeof event.query != 'object') {\n    errors.push(TypeError('event.query not an object'))\n  }\n  if (typeof event.query.x === 'undefined') {\n    errors.push(ReferenceError('event.query not an object'))\n  }\n  if (event.query.x \u0026\u0026 typeof event.query.x != 'number') {\n    errors.push(TypeError('event.query not an object'))\n  }\n  if (errors.length) {\n    // otherwise Error would return [{}, {}, {}, {}]\n    var err = errors.map(function(e) {return e.message})\n    context.fail(err) \n  }\n  else {\n    context.succeed({count:event.query.x + 1})\n  }\n}\n```\n\nA huge amount of vanilla AWS Lambda code is working around quirky parameter validation. API Gateway gives you control over the parameters you can expect but this still means one or more of: headers, querystring, form body, or url parameters. Event source style lambdas are not much better because you can often still get differing payloads from different origin sources. In the example above we are validating *one* querystring parameter `x`. Imagine a big payload! 😮\n\nWorse still, writing a good program we want to use JavaScript's builtin `Error` but it still needs manual serialization (and you still lose the stack trace). The latter part of this vanilla code uses the funky AWS `context` object.\n\nWe can do better:\n\n```javascript\nvar validate = require('@smallwins/validate')\nvar lambda = require('@smallwins/lambda')\n\nfunction sum(event, callback) {\n  var schema = {\n    'query':   {required:true, type:Object},\n    'query.x': {required:true, type:Number}\n  }\n  var errors = validate(event, schema)\n  if (errors) {\n    callback(errors)\n  }\n  else {\n    var result = {count:event.query.x + 1}\n    callback(null, result)\n  }\n}\n\nexports.handler = lambda(sum)\n```\n\n`@smallwins/validate` cleans up parameter validation. The callback style above enjoys symmetry with the rest of Node and will automatically serialize `Error`s into JSON friendly objects including any stack trace. All you need to do is wrap a your node style function in `lambda` which returns your function with an AWS Lambda friendly signature.\n\n#### :loop::loop::loop: easily chain dependant actions ala middleware :loop::loop::loop:\n\nBuilding on this foundation we can compose multiple functions into a single Lambda. It is very common to want to run functions in series. Lets compose a Lambda that: \n\n- Validates parameters\n- Checks for an authorized account\n- And then returns data safely\n- Or if anything fails return JSON serialized `Error` array\n\n```javascript\nvar validate = require('@smallwins/validate')\nvar lambda = require('@smallwins/lambda')\n\nfunction valid(event, callback) {\n  var schema = {\n    'body':          {required:true, type:Object},\n    'body.username': {required:true, type:String},\n    'body.password': {required:true, type:String}\n  }\n  validate(event, schema, callback)\n}\n\nfunction authorized(event, callback) {\n  var loggedIn = event.body.username === 'sutro' \u0026\u0026 event.body.password === 'cat'\n  if (!loggedIn) {\n    // err first\n    callback(Error('not found'))\n  }\n  else {\n    // successful login\n    event.account = {\n      loggedIn: loggedIn,\n      name: 'sutro furry pants'\n    }\n    callback(null, event)\n  }\n}\n\nfunction safe(event, callback) {\n  callback(null, {account:event.account})\n}\n\nexports.handler = lambda(valid, authorized, safe)\n```\n\nIn the example above our functions are executed in series passing event through each invocation. `valid` will pass event to `authorized` which in turn passes it to `save`. Any `Error` returns immediately so if we make it the last function we just send back the resulting account data. Clean!\n\n#### :floppy_disk: save a record from a dynamodb trigger :boom::gun:\n\nAWS DynamoDB triggers invoke a Lambda function if anything happens to a table. The payload is usually a big array of records. `@smallwins/lambda` allows you to focus on processing a single record but executes the function in parallel on all the results in the Dynamo invocation.\n\n```javascript\nvar lambda = require('@smallwins/lambda')\n\nfunction save(record, callback) {\n  console.log('save a version ', record)\n  callback(null, record)\n}\n\nexports.handler = lambda.triggers.dynamo.save(save)\n```\n\n#### :bookmark: respond to a message published on sns\n\nIts very common to compose your application events using AWS SNS. `@smallwins/lambda` runs in parallel over the records in the trigger, similar to the Dynamo.\n\n```javascript\n// somewhere in your codebase you'll want to trigger a lambda\nvar aws = require('aws-sdk')\nvar sns = new aws.SNS\n\nsns.publish({\n  Message: JSON.stringify({hello:'world'}),\n  TopicArn: 'arn:aws:sns:us-east-1'\n}, console.log)\n```\n\n```javascript\n// then, in your lambda\nvar lambda = require('@smallwins/lambda')\n\nfunction msg(message, callback) {\n  console.log('received msg ', message) // logs {hello:\"world\"}\n  callback(null, message)\n}\n\nexports.handler = lambda.triggers.sns(msg)\n```\n\n## :love_letter: api :thought_balloon::sparkles:\n\n- `lambda(...fns)` create a Lambda that returns a serialized json result `{ok:true|false}`\n- `lambda([fns], callback)` create a Lambda and handle result with your own errback formatter\n- `lambda.local(fn, fakeEvent, (err, result)=\u003e)` run a Lambda locally offline by faking the event obj\n- `lambda.triggers.dynamo.insert(fn)` run on INSERT only\n- `lambda.triggers.dynamo.modify(fn)` run on MODIFY only\n- `lambda.triggers.dynamo.remove(fn)` run on REMOVE only\n- `lambda.triggers.dynamo.all(fn)` run on INSERT, MODIFY and REMOVE\n- `lambda.triggers.dynamo.save(fn)` run on INSERT and MODIFY\n- `lambda.triggers.dynamo.change(fn)` run on INSERT and REMOVE\n- `lambda.triggers.sns(fn)` run for every sns trigger invocation; expects `record.Sns.Message` to be a serialized JSON payload\n\nA handler looks something like this:\n\n```javascript    \nfunction handler(event, callback) {\n  // process event, use to pass data\n  var result = {ok:true, event:event}\n  callback(null, result)\n}\n```\n\n#### :heavy_exclamation_mark: regarding errors :x::interrobang:\n\nGood error handling makes programs easier to maintain. [This is a great guide digging in more.](https://www.joyent.com/developers/node/design/errors) When using `@smallwins/lambda` always use `Error` type as the first parameter to the callback: \n\n```javascript\nfunction fails(event, callback) {\n  callback(Error('something went wrong')\n}\n```\n\nOr an `Error` array:\n\n```javascript\nfunction fails(event, callback) {\n  callback([\n    Error('missing email'), \n    Error('missing password')\n  ])\n}\n```\n\n`@smallwins/lambda` serializes errors into Slack RPC style JSON. Easier to work with from API Gateway:\n\n```javascript\n{\n  ok: false, \n  errors: [\n    {name:'Error', message:'missing email', stack'...'},\n    {name:'Error', message:'missing password', stack'...'}\n  ]\n}\n```\n\n#### \u003ckbd\u003e#! automatations\u003c/kbd\u003e :memo:\n\n`@smallwins/lambda` includes some helpful automation code perfect for npm scripts. If you have a project that looks like this:\n\n```\nproject-of-lambdas/\n |-test/\n |-src/\n |  '-lambdas/\n |     |-signup/\n |     |  |-index.js\n |     |  |-test.js\n |     |  '-package.json \u003c--- name property should equal the deployed lambda name\n |     |-login/\n |     '-logout/\n '-package.json\n\n```\n\nAnd a `package.json` like this:\n\n```javascript\n{\n  \"name\":\"project-of-lambdas\",\n  \"scripts\": {\n    \"create\":\"AWS_PROFILE=smallwins lambda-create\",\n    \"list\":\"AWS_PROFILE=smallwins lambda-list\",\n    \"deploy\":\"AWS_PROFILE=smallwins lambda-deploy\",\n    \"invoke\":\"AWS_PROFILE=smallwins lambda-invoke\",\n    \"local\":\"AWS_PROFILE=smallwins lambda-local\",\n    \"deps\":\"AWS_PROFILE=smallwins lambda-deps\",\n    \"log\":\"AWS_PROFILE=smallwins lambda-log\"\n  }\n}\n```\n\nYou get:\n\n#### :fast_forward: npm run scripts :running::dash:\n\nThis is :key:! Staying in the flow with your terminal by reducing hunts for information in the AWS Console. :shipit::chart_with_upwards_trend:\n\n- :point_right: \u003ckbd\u003enpm run \u003cb\u003ecreate\u003c/b\u003e src/lambdas/forgot\u003c/kbd\u003e creates a new lambda named `forgot` at `src/lambdas/forgot` \n- :point_right: \u003ckbd\u003enpm run \u003cb\u003elist\u003c/b\u003e\u003c/kbd\u003e lists all deployed lambdas and all their alias@versions\n- :point_right: \u003ckbd\u003enpm run \u003cb\u003edeploy\u003c/b\u003e src/lambdas/signup brian\u003c/kbd\u003e deploys the lambda with the alias `brian`\n- :point_right: \u003ckbd\u003enpm run \u003cb\u003einvoke\u003c/b\u003e src/lambdas/login brian '{\"email\":\"b@brian.io\", \"pswd\":\"...\"}'\u003c/kbd\u003e to remote invoke a deployed lambda\n- :point_right: \u003ckbd\u003enpm run \u003cb\u003elocal\u003c/b\u003e src/lambdas/login brian '{\"email\":\"b@brian.io\", \"pswd\":\"...\"}'\u003c/kbd\u003e to locally invoke a lambda\n- :point_right: \u003ckbd\u003enpm run \u003cb\u003edeps\u003c/b\u003e src/lambdas/*\u003c/kbd\u003e for a report of all your lambda deps\n- :point_right: \u003ckbd\u003enpm run \u003cb\u003elog\u003c/b\u003e src/lambdas/logout\u003c/kbd\u003e to view the cloudwatch invocation logs for that lambda (remote `console.log` statements show up here)\n\n_Note: these scripts assume each lambda has it's own nested `package.json` file with a `name` property that matches the lambda name._\n\n### testing :white_check_mark: \n\nYou can invoke a Lambda locally with a mock payload using `lambda.local`. Say you have this lambda function:\n\n```javascript\n// always-ok.js\nvar lambda = require('@smallwins/lambda')\n\nfunction fakeFn(event, callback) {\n  callback(null, Object.assign({hello:'world'}, event))\n}\n\nexports.handler = lambda(fakeFn)\n```\n\nYou can imagine the test:\n\n```javascript\n// always-test.js\nvar fn = require('./always-ok').handler\n\nlambda.local(fn, {fake:'payload'}, console.log)\n// logs {hello:'world', fake:'payload', ok:true}\n```\n\n`./scripts/invoke.js` is also a module and can be useful for testing. It will remotely invoke your lambda.\n\n```javascript\nvar invoke = require('@smallwins/lambda/scripts/invoke')\n\ninvoke('path/to/lambda', alias, payload, (err, response)=\u003e {\n  console.log(err, response)\n})\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeginner-corp%2Flambda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeginner-corp%2Flambda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeginner-corp%2Flambda/lists"}