{"id":13648008,"url":"https://github.com/cloudevents/sdk-javascript","last_synced_at":"2025-05-14T07:11:03.525Z","repository":{"id":37602867,"uuid":"149662999","full_name":"cloudevents/sdk-javascript","owner":"cloudevents","description":"JavaScript/TypeScript SDK for CloudEvents ","archived":false,"fork":false,"pushed_at":"2025-04-30T08:07:41.000Z","size":3893,"stargazers_count":362,"open_issues_count":19,"forks_count":69,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-05T13:43:14.373Z","etag":null,"topics":["cloudevents","cncf","events"],"latest_commit_sha":null,"homepage":"https://cloudevents.github.io/sdk-javascript/","language":"TypeScript","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/cloudevents.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2018-09-20T19:54:57.000Z","updated_at":"2025-05-03T01:59:38.000Z","dependencies_parsed_at":"2022-07-12T16:33:11.878Z","dependency_job_id":"4db8defe-6284-4f6e-9c79-e5d39a0660db","html_url":"https://github.com/cloudevents/sdk-javascript","commit_stats":{"total_commits":744,"total_committers":30,"mean_commits":24.8,"dds":"0.40456989247311825","last_synced_commit":"7ff64f8b82e1c5a824bbe985df4948d79e919e8c"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudevents%2Fsdk-javascript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudevents%2Fsdk-javascript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudevents%2Fsdk-javascript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudevents%2Fsdk-javascript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudevents","download_url":"https://codeload.github.com/cloudevents/sdk-javascript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253300813,"owners_count":21886516,"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":["cloudevents","cncf","events"],"created_at":"2024-08-02T01:03:53.555Z","updated_at":"2025-05-14T07:10:58.498Z","avatar_url":"https://github.com/cloudevents.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# JavaScript SDK for CloudEvents\n\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/2e29a55fb4084ecca4642d72dc4c83d4)](https://www.codacy.com/gh/cloudevents/sdk-javascript/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=cloudevents/sdk-javascript\u0026amp;utm_campaign=Badge_Grade)\n[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/2e29a55fb4084ecca4642d72dc4c83d4)](https://www.codacy.com/gh/cloudevents/sdk-javascript/dashboard?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=cloudevents/sdk-javascript\u0026utm_campaign=Badge_Coverage)\n![Node.js CI](https://github.com/cloudevents/sdk-javascript/workflows/Node.js%20CI/badge.svg)\n[![npm version](https://img.shields.io/npm/v/cloudevents.svg)](https://www.npmjs.com/package/cloudevents)\n[![vulnerabilities](https://snyk.io/test/github/cloudevents/sdk-javascript/badge.svg)](https://snyk.io/test/github/cloudevents/sdk-javascript)\n\nThe CloudEvents SDK for JavaScript.\n\n## Features\n\n- Represent CloudEvents in memory\n- Serialize and deserialize CloudEvents in different [event formats](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format).\n- Send and receive CloudEvents with via different [protocol bindings](https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding).\n\n_Note:_ Supports CloudEvent version 1.0\n\n## Installation\n\nThe CloudEvents SDK requires a current LTS version of Node.js. At the moment\nthose are Node.js 16.x, and Node.js 18.x. To install in your Node.js project:\n\n```console\nnpm install cloudevents\n```\n\n### Receiving and Emitting Events\n\n#### Receiving Events\n\nYou can choose any popular web framework for port binding. A `CloudEvent`\nobject can be created by simply providing the `HTTP` protocol binding\nthe incoming headers and request body.\n\n```js\nconst app = require(\"express\")();\nconst { HTTP } = require(\"cloudevents\");\n\napp.post(\"/\", (req, res) =\u003e {\n  // body and headers come from an incoming HTTP request, e.g. express.js\n  const receivedEvent = HTTP.toEvent({ headers: req.headers, body: req.body });\n  console.log(receivedEvent);\n});\n```\n\n#### Emitting Events\n\nThe easiest way to send events is to use the built-in HTTP emitter.\n\n```js\nconst { httpTransport, emitterFor, CloudEvent } = require(\"cloudevents\");\n\n// Create an emitter to send events to a receiver\nconst emit = emitterFor(httpTransport(\"https://my.receiver.com/endpoint\"));\n\n// Create a new CloudEvent\nconst ce = new CloudEvent({ type, source, data });\n\n// Send it to the endpoint - encoded as HTTP binary by default\nemit(ce);\n```\n\nIf you prefer to use another transport mechanism for sending events\nover HTTP, you can use the `HTTP` binding to create a `Message` which\nhas properties for `headers` and `body`, allowing greater flexibility\nand customization. For example, the `axios` module is used here to send\na CloudEvent.\n\n```js\nconst axios = require(\"axios\").default;\nconst { HTTP, CloudEvent } = require(\"cloudevents\");\n\nconst ce = new CloudEvent({ type, source, data });\nconst message = HTTP.binary(ce); // Or HTTP.structured(ce)\n\naxios({\n  method: \"post\",\n  url: \"...\",\n  data: message.body,\n  headers: message.headers,\n});\n```\n\nYou may also use the `emitterFor()` function as a convenience.\n\n```js\nconst axios = require(\"axios\").default;\nconst { emitterFor, Mode, CloudEvent } = require(\"cloudevents\");\n\nfunction sendWithAxios(message) {\n  // Do what you need with the message headers\n  // and body in this function, then send the\n  // event\n  axios({\n    method: \"post\",\n    url: \"...\",\n    data: message.body,\n    headers: message.headers,\n  });\n}\n\nconst emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });\nemit(new CloudEvent({ type, source, data }));\n```\n\nYou may also use the `Emitter` singleton to send your `CloudEvents`.\n\n```js\nconst { emitterFor, httpTransport, Mode, CloudEvent, Emitter } = require(\"cloudevents\");\n\n// Create a CloudEvent emitter function to send events to our receiver\nconst emit = emitterFor(httpTransport(\"https://example.com/receiver\"));\n\n// Use the emit() function to send a CloudEvent to its endpoint when a \"cloudevent\" event is emitted\n// (see: https://nodejs.org/api/events.html#class-eventemitter)\nEmitter.on(\"cloudevent\", emit);\n\n...\n// In any part of the code, calling `emit()` on a `CloudEvent` instance will send the event\nnew CloudEvent({ type, source, data }).emit();\n\n// You can also have several listeners to send the event to several endpoints\n```\n\n## CloudEvent Objects\n\nAll created `CloudEvent` objects are read-only. If you need to update a property or add a new extension to an existing cloud event object, you can use the `cloneWith` method. This will return a new `CloudEvent` with any update or new properties. For example:\n\n```js\nconst {\n  CloudEvent,\n} = require(\"cloudevents\");\n\n// Create a new CloudEvent\nconst ce = new CloudEvent({...});\n\n// Add a new extension to an existing CloudEvent\nconst ce2 = ce.cloneWith({extension: \"Value\"});\n```\n\nYou can create a `CloudEvent` object in many ways, for example, in TypeScript:\n\n```ts\nimport { CloudEvent, CloudEventV1, CloudEventV1Attributes } from \"cloudevents\";\nconst ce: CloudEventV1\u003cstring\u003e = {\n  specversion: \"1.0\",\n  source: \"/some/source\",\n  type: \"example\",\n  id: \"1234\"\n};\nconst event = new CloudEvent(ce);\nconst ce2: CloudEventV1Attributes\u003cstring\u003e = {\n  specversion: \"1.0\",\n  source: \"/some/source\",\n  type: \"example\",\n};\nconst event2 = new CloudEvent(ce2);\nconst event3 = new CloudEvent({\n  source: \"/some/source\",\n  type: \"example\",\n});\n```\n\n### A Note About Big Integers\n\nWhen parsing JSON data, if a JSON field value is a number, and that number\nis really big, JavaScript loses precision. For example, the Twitter API exposes\nthe Tweet ID. This is a large number that exceeds the integer space of `Number`.\n\nIn order to address this situation, you can set the environment variable\n`CE_USE_BIG_INT` to the string value `\"true\"` to enable the use of the\n[`json-bigint`](https://www.npmjs.com/package/json-bigint) package. This\npackage is not used by default due to the resulting slowdown in parse speed\nby a factor of 7x.\n\nSee for more information: https://github.com/cloudevents/sdk-javascript/issues/489\n\n### Example Applications\n\nThere are a few trivial example applications in\n[the examples folder](https://github.com/cloudevents/sdk-javascript/tree/main/examples).\nThere you will find Express.js, TypeScript and Websocket examples.\n\n\n### API Transition Guide\n\n[Guide Link](./API_TRANSITION_GUIDE.md)\n\n## Supported specification features\n\n| Core Specification | [v0.3](https://github.com/cloudevents/spec/blob/v0.3/spec.md) | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) |\n| ------------------ | ------------------------------------------------------------- | ------------------------------------------------------------- |\n| CloudEvents Core   | :white_check_mark:                                            | :white_check_mark:                                            |\n\n---\n\n| Event Formats     | [v0.3](https://github.com/cloudevents/spec/tree/v0.3) | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format) |\n| ----------------- | ----------------------------------------------------- | ----------------------------------------------------- |\n| AVRO Event Format | :x:                                                   | :x:                                                   |\n| JSON Event Format | :white_check_mark:                                    | :white_check_mark:                                    |\n\n---\n\n| Protocol Bindings    | [v0.3](https://github.com/cloudevents/spec/tree/v0.3) | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding) |\n| ---------------------- | ----------------------------------------------------- | ----------------------------------------------------- |\n| AMQP Protocol Binding  | :x:                                                   | :x:                                                   |\n| HTTP Protocol Binding  | :white_check_mark:                                    | :white_check_mark:                                    |\n| Kafka Protocol Binding | :x:                                                   | :white_check_mark:                                                   |\n| MQTT Protocol Binding  | :white_check_mark:                                                   | :x:                                                   |\n| NATS Protocol Binding  | :x:                                                   | :x:                                                   |\n\n---\n\n| Content Modes    | [v0.3](https://github.com/cloudevents/spec/tree/v0.3) | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md#13-content-modes) |\n| ---------------------- | ----------------------------------------------------- | ----------------------------------------------------- |\n| HTTP Binary  | :white_check_mark:                                                   | :white_check_mark:                                                   |\n| HTTP Structured  | :white_check_mark:                                    | :white_check_mark:                                    |\n| HTTP Batch  | :white_check_mark:                                    | :white_check_mark:                                    |\n| Kafka Binary  | :white_check_mark:                                                   | :white_check_mark:                                                   |\n| Kafka Structured  | :white_check_mark:                                    | :white_check_mark:                                    |\n| Kafka Batch  | :white_check_mark:                                    | :white_check_mark:\n| MQTT Binary  | :white_check_mark:                                                   | :white_check_mark:                                                   |\n| MQTT Structured  | :white_check_mark:                                    | :white_check_mark:                                    |\n\n## Community\n\n- There are bi-weekly calls immediately following the [Serverless/CloudEvents\n  call](https://github.com/cloudevents/spec#meeting-time) at\n  9am PT (US Pacific). Which means they will typically start at 10am PT, but\n  if the other call ends early then the SDK call will start early as well.\n  See the [CloudEvents meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#)\n  to determine which week will have the call.\n- Slack: #cloudeventssdk channel under\n  [CNCF's Slack workspace](https://slack.cncf.io/).\n- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk\n\n## Maintainers\n\nCurrently active maintainers who may be found in the CNCF Slack.\n\n- Lance Ball (@lance)\n- Lucas Holmquist (@lholmquist)\n\n## Contributing\n\nWe love contributions from the community! Please check the\n[Contributor's Guide](https://github.com/cloudevents/sdk-javascript/blob/main/CONTRIBUTING.md)\nfor information on how to get involved.\n\nEach SDK may have its own unique processes, tooling and guidelines, common\ngovernance related material can be found in the\n[CloudEvents `community`](https://github.com/cloudevents/spec/tree/master/community)\ndirectory. In particular, in there you will find information concerning\nhow SDK projects are\n[managed](https://github.com/cloudevents/spec/blob/master/community/SDK-GOVERNANCE.md),\n[guidelines](https://github.com/cloudevents/spec/blob/master/community/SDK-maintainer-guidelines.md)\nfor how PR reviews and approval, and our\n[Code of Conduct](https://github.com/cloudevents/spec/blob/master/community/GOVERNANCE.md#additional-information)\ninformation.\n\nIf there is a security concern with one of the CloudEvents specifications, or\nwith one of the project's SDKs, please send an email to\n[cncf-cloudevents-security@lists.cncf.io](mailto:cncf-cloudevents-security@lists.cncf.io).\n\n## Additional SDK Resources\n\n- [List of current active maintainers](MAINTAINERS.md)\n- [How to contribute to the project](CONTRIBUTING.md)\n- [SDK's License](LICENSE)\n- [SDK's Release process](RELEASING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudevents%2Fsdk-javascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudevents%2Fsdk-javascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudevents%2Fsdk-javascript/lists"}