{"id":18981886,"url":"https://github.com/nodeshift/faas-js-runtime","last_synced_at":"2025-04-06T08:13:49.348Z","repository":{"id":39706742,"uuid":"215444511","full_name":"nodeshift/faas-js-runtime","owner":"nodeshift","description":"A function invocation framework for Node.js and TypeScript","archived":false,"fork":false,"pushed_at":"2024-10-29T20:31:35.000Z","size":1623,"stargazers_count":16,"open_issues_count":17,"forks_count":19,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-10-29T22:49:08.820Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodeshift.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":"2019-10-16T03:01:12.000Z","updated_at":"2024-10-29T20:30:54.000Z","dependencies_parsed_at":"2023-11-30T16:26:03.512Z","dependency_job_id":"9b282400-1846-43f9-b844-2bc404cdbd9c","html_url":"https://github.com/nodeshift/faas-js-runtime","commit_stats":{"total_commits":192,"total_committers":14,"mean_commits":"13.714285714285714","dds":0.53125,"last_synced_commit":"ef6bc7765955b44ca2b2065ae1beafaeeffc49d3"},"previous_names":["openshift-cloud-functions/faas-js-runtime"],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Ffaas-js-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Ffaas-js-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Ffaas-js-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Ffaas-js-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodeshift","download_url":"https://codeload.github.com/nodeshift/faas-js-runtime/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247451665,"owners_count":20940944,"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-11-08T16:11:36.242Z","updated_at":"2025-04-06T08:13:49.331Z","avatar_url":"https://github.com/nodeshift.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node.js Function Framework\n\n[![Node.js CI](https://github.com/nodeshift/faas-js-runtime/workflows/Node.js%20CI/badge.svg)](https://github.com/nodeshift/faas-js-runtime/actions?query=workflow%3A%22Node.js+CI%22+branch%3Amaster)\n[![codecov](https://codecov.io/gh/nodeshift/faas-js-runtime/branch/main/graph/badge.svg?token=Z72LKANFJI)](https://codecov.io/gh/nodeshift/faas-js-runtime)\n\nThis module provides a Node.js framework for executing a function that\nexists in a user-provided directory path as an `index.js` file. The\ndirectory may also contain an optional `package.json` file which can\nbe used to declare runtime dependencies for the function. You can also\nprovide a path to an arbitrary JavaScript file instead of a directory\npath, allowing you to execute a single file as a function.\n\n|                 | Project Info  |\n| --------------- | ------------- |\n| License:        | Apache-2.0  |\n| Issue tracker:  | https://github.com/nodeshift/faas-js-runtime/issues  |\n| Engines:        | Node.js \u003e= 16 |\n\nThe function is loaded and then invoked for incoming HTTP requests\nat `localhost:8080`. The incoming request may be a\n[Cloud Event](https://github.com/cloudevents/sdk-javascript#readme.) or\njust a simple HTTP GET/POST request. The invoked user function can be\n`async` but that is not required.\n\n## The Function Interface\n\nThe function file that is loaded may export a single function or a `Function`\nobject. The `Function` object allows developers to add lifecycle hooks for\ninitialization and shutdown, as well as providing a way to implement custom\nhealth checks.\n\nThe `Function` interface is defined as:\n\n```typescript\nexport interface Function {\n  // The initialization function, called before the server is started\n  // This function is optional and should be synchronous.\n  init?: () =\u003e any;\n\n  // The shutdown function, called after the server is stopped\n  // This function is optional and should be synchronous.\n  shutdown?: () =\u003e any;\n\n  // Function that returns an array of CORS origins\n  // This function is optional.\n  cors?: () =\u003e string[];\n\n  // The liveness function, called to check if the server is alive\n  // This function is optional and should return 200/OK if the server is alive.\n  liveness?: HealthCheck;\n\n  // The readiness function, called to check if the server is ready to accept requests\n  // This function is optional and should return 200/OK if the server is ready.\n  readiness?: HealthCheck;\n\n  logLevel?: LogLevel;\n\n  // The function to handle HTTP requests\n  handle: CloudEventFunction | HTTPFunction;\n}\n```\n\n## Handle Signature\n\nThis module supports two different function signatures: HTTP or CloudEvents. In the type definitions below, we use TypeScript to express interfaces and types, but this module is usable from JavaScript as well.\n\n### HTTP Functions\n\nThe HTTP function signature is the simplest. It is invoked for every HTTP request that does not contain a CloudEvent.\n\n```typescript\ninterface HTTPFunction {\n  (context: Context, body?: IncomingBody): HTTPFunctionReturn;\n}\n```\n\nWhere the `IncomingBody` is either a string, a Buffer, a JavaScript object, or undefined, depending on what was supplied in the HTTP POST message body. The `HTTTPFunctionReturn` type is defined as:\n\n```typescript\ntype HTTPFunctionReturn = Promise\u003cStructuredReturn\u003e | StructuredReturn | ResponseBody | void;\n```\n\nWhere the `StructuredReturn` is a JavaScript object with the following properties:\n\n```typescript\ninterface StructuredReturn {\n  statusCode?: number;\n  headers?: Record\u003cstring, string\u003e;\n  body?: ResponseBody;\n}\n```\n\nIf the function returns a `StructuredReturn` object, then the `statusCode` and `headers` properties are used to construct the HTTP response. If the `body` property is present, it is used as the response body. If the function returns `void` or `undefined`, then the response body is empty.\n\nThe `ResponseBody` is either a string, a JavaScript object, or a Buffer. JavaScript objects will be serialized as JSON. Buffers will be sent as binary data.\n\n### CloudEvent Functions\n\nCloudEvent functions are used in environments where the incoming HTTP request is a CloudEvent. The function signature is:\n\n```typescript\ninterface CloudEventFunction {\n  (context: Context, event: CloudEvent): CloudEventFunctionReturn;\n}\n```\n\nWhere the return type is defined as:\n\n```typescript\ntype CloudEventFunctionReturn = Promise\u003cCloudEvent\u003e | CloudEvent | HTTPFunctionReturn;\n```\n\nThe function return type can be anything that a simple HTTP function can return or a CloudEvent. Whatever is returned, it will be sent back to the caller as a response.\n\n### Health Checks\n\nThe `Function` interface also allows for the addition of a `liveness` and `readiness` function. These functions are used to implement health checks for the function. The `liveness` function is called to check if the function is alive. The `readiness` function is called to check if the function is ready to accept requests. If either of these functions return a non-200 status code, then the function is considered unhealthy.\n\nA health check function is defined as:\n\n```typescript\n/**\n * The HealthCheck interface describes a health check function,\n * including the optional path to which it should be bound.\n */\nexport interface HealthCheck {\n  (request: Http2ServerRequest, reply: Http2ServerResponse): any;\n  path?: string;\n}\n```\n\nBy default, the health checks are bound to the `/health/liveness` and `/health/readiness` paths. You can override this by setting the `path` property on the `HealthCheck` object, or by setting the `LIVENESS_URL` and `READINESS_URL` environment variables.\n\n## CLI\n\nThe easiest way to get started is to use the CLI. You can call it\nwith the path to any JavaScript file which has a default export that\nis a function, or that exports a `Function` type. For example,\n\n```js\n// index.js\nfunction handle(context) {\n  const event = context.cloudevent;\n  // business logic\n  return {\n    statusCode: 200,\n    statusMessage: 'OK'\n  }\n}\n\nmodule.exports = handle;\n```\n\nYou can expose this function as an HTTP endpoint at `localhost:8080`\nwith the CLI.\n\n```console\nnpx faas-js-runtime ./index.js\n```\n\n### --bodyLimit\nSets the maximum allowed payload size for incoming requests. Default is '1mb'.\n\nExample:\n```console\nfaas-js-runtime function.js --bodyLimit 2mb\n```\n\n## Debugging Locally\n\nDuring local development, it is often necessary to set breakpoints in your code for debugging.  Since functions are just javascript files, using any current debugging(VS Code, Chrome Dev Tools) method will work. The linked blog post shows how to setup and use VS Code for development debugging.\n\nhttps://developers.redhat.com/articles/2021/07/13/nodejs-serverless-functions-red-hat-openshift-part-2-debugging-locally\n\n## Debugging Remotely\n\nIt is also possible to debug your function while it is running on a remote cluster.  The linked blog posts shows how to setup and use the Chrome Dev Tools inspector for debugging on a cluster.\n\nhttps://developers.redhat.com/articles/2021/12/08/nodejs-serverless-functions-red-hat-openshift-part-3-debugging-cluster\n\n\n\n### Functions as ES Modules\n\nFunctions can be written and imported as ES modules with either the `.mjs` file extension or by adding the `type` property to the functions package.json and setting it to `module`.\n\n```js\n// index.mjs\nconst handle = async function(context) =\u003e { ... };\n\n// Export the function\nexport { handle };\n```\n\nIf using the `type` property, the package.json might look something like this:\n```js\n{\n  \"name\": \"moduleName\",\n  \"type\": \"module\"\n}\n```\n\n\n\n## Usage as a Module\n\nIn the current working directory, there is an `index.js` file like this.\n\n```js\nconst { start } = require('faas-js-runtime');\nconst options = {\n  // Pino is used as the logger implementation. Supported log levels are\n  // documented at this link:\n  // https://github.com/pinojs/pino/blob/master/docs/api.md#options\n  logLevel: 'info'\n}\n\n// The function directory is in ./function-dir\nstart(require(`${__dirname}/function-dir/`), server =\u003e {\n  // The server is now listening on localhost:8080\n  // and the function defined in `function-dir/index.js`\n  // will be invoked for each HTTP\n  // request to this endpoint.\n  console.log('Server listening');\n\n  // Whenever you want to shutdown the framework\n  server.close();\n}, options);\n```\n\nIn `./function-dir`, there is an `index.js` file that looks\nlike this.\n\n```js\nmodule.exports = async function myFunction(context) {\n  const ret = 'This is a test for Node.js functions. Success.';\n  return new Promise((resolve, reject) =\u003e {\n    setTimeout(_ =\u003e {\n      context.log.info('sending response to client')\n      resolve(ret);\n    }, 500);\n  });\n};\n```\n\nYou can use `curl` to `POST` to the endpoint:\n```console\n$ curl -X POST -d 'hello=world' \\\n  -H'Content-type: application/x-www-form-urlencoded' http://localhost:8080\n```\n\nYou can use `curl` to `POST` JSON data to the endpoint:\n```console\n$ curl -X POST -d '{\"hello\": \"world\"}' \\\n  -H'Content-type: application/json' \\\n  http://localhost:8080\n```\n\nYou can use `curl` to `POST` an event to the endpoint:\n```console\n$ curl -X POST -d '{\"hello\": \"world\"}' \\\n  -H'Content-type: application/json' \\\n  -H'Ce-id: 1' \\\n  -H'Ce-source: cloud-event-example' \\\n  -H'Ce-type: dev.knative.example' \\\n  -H'Ce-specversion: 1.0' \\\n  http://localhost:8080\n```\n\n### Sample\n\nYou can see this in action by running `node bin/cli.js sample/index.js`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeshift%2Ffaas-js-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodeshift%2Ffaas-js-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeshift%2Ffaas-js-runtime/lists"}