The CloudEvents SDK for JavaScript.
- Represent CloudEvents in memory
- Serialize and deserialize CloudEvents in different event formats.
- Send and recieve CloudEvents with via different protocol bindings.
Note: Supports CloudEvent versions 0.3, 1.0
The CloudEvents SDK requires a current LTS version of Node.js. At the moment those are Node.js 10.x and Node.js 12.x. To install in your Node.js project:
npm install cloudeventsYou can choose any popular web framework for port binding. A CloudEvent
object can be created by simply providing the HTTP protocol binding
the incoming headers and request body.
const app = require("express")();
const { HTTP } = require("cloudevents");
app.post("/", (req, res) => {
// body and headers come from an incoming HTTP request, e.g. express.js
const receivedEvent = HTTP.toEvent({ headers: req.headers, body: req.body });
console.log(receivedEvent);
});You can send events over HTTP in either binary or structured format
using the HTTP binding to create a Message which has properties
for headers and body.
const axios = require("axios").default;
const { HTTP, CloudEvent } = require("cloudevents");
const ce = new CloudEvent({ type, source, data });
const message = HTTP.binary(ce); // Or HTTP.structured(ce)
axios({
method: "post",
url: "...",
data: message.body,
headers: message.headers,
});You may also use the emitterFor() function as a convenience.
const axios = require("axios").default;
const { emitterFor, Mode, CloudEvent } = require("cloudevents");
function sendWithAxios(message) {
// Do what you need with the message headers
// and body in this function, then send the
// event
axios({
method: "post",
url: "...",
data: message.body,
headers: message.headers,
});
}
const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
emit(new CloudEvent({ type, source, data }));You may also use the Emitter singleton
const axios = require("axios").default;
const { emitterFor, Mode, CloudEvent, Emitter } = require("cloudevents");
function sendWithAxios(message) {
// Do what you need with the message headers
// and body in this function, then send the
// event
axios({
method: "post",
url: "...",
data: message.body,
headers: message.headers,
});
}
const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
// Set the emit
Emitter.on("cloudevent", emit);
...
// In any part of the code will send the event
new CloudEvent({ type, source, data }).emit();
// You can also have several listener to send the event to several endpointAll 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:
const {
CloudEvent,
} = require("cloudevents");
// Create a new CloudEvent
const ce = new CloudEvent({...});
// Add a new extension to an existing CloudEvent
const ce2 = ce.cloneWith({extension: "Value"});There are a few trivial example applications in the examples folder. There you will find Express.js, TypeScript and Websocket examples.
| Core Specification | v0.3 | v1.0 |
|---|---|---|
| CloudEvents Core | ✔️ | ✔️ |
| Event Formats | v0.3 | v1.0 |
|---|---|---|
| AVRO Event Format | ❌ | ❌ |
| JSON Event Format | ✔️ | ✔️ |
| Transport Protocols | v0.3 | v1.0 |
|---|---|---|
| AMQP Protocol Binding | ❌ | ❌ |
| HTTP Protocol Binding | ✔️ | ✔️ |
| Kafka Protocol Binding | ❌ | ❌ |
| MQTT Protocol Binding | ❌ | ❌ |
| NATS Protocol Binding | ❌ | ❌ |
- There are bi-weekly calls immediately following the Serverless/CloudEvents call at 9am PT (US Pacific). Which means they will typically start at 10am PT, but if the other call ends early then the SDK call will start early as well. See the CloudEvents meeting minutes to determine which week will have the call.
- Slack: #cloudeventssdk channel under CNCF's Slack workspace.
- Maintainers typically available on Slack
- Lance Ball
- Lucas Holmquist
- Grant Timmerman
- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
We love contributions from the community! Please check the Contributor's Guide for information on how to get involved.
Each SDK may have its own unique processes, tooling and guidelines, common
governance related material can be found in the
CloudEvents community
directory. In particular, in there you will find information concerning
how SDK projects are
managed,
guidelines
for how PR reviews and approval, and our
Code of Conduct
information.