Skip to content

cloudevents/sdk-javascript

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

Bumps [json5](https://github.com/json5/json5) from 2.2.0 to 2.2.3.
- [Release notes](https://github.com/json5/json5/releases)
- [Changelog](https://github.com/json5/json5/blob/main/CHANGELOG.md)
- [Commits](json5/json5@v2.2.0...v2.2.3)

---
updated-dependencies:
- dependency-name: json5
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
eccc00e

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time

JavaScript SDK for CloudEvents

Codacy Badge Codacy Badge Node.js CI npm version vulnerabilities

The CloudEvents SDK for JavaScript.

Features

  • Represent CloudEvents in memory
  • Serialize and deserialize CloudEvents in different event formats.
  • Send and recieve CloudEvents with via different protocol bindings.

Note: Supports CloudEvent version 1.0

Installation

The CloudEvents SDK requires a current LTS version of Node.js. At the moment those are Node.js 12.x, Node.js 14.x and Node.js 16.x. To install in your Node.js project:

npm install cloudevents

Receiving and Emitting Events

Receiving Events

You 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);
});

Emitting Events

The easiest way to send events is to use the built-in HTTP emitter.

const { httpTransport, emitterFor, CloudEvent } = require("cloudevents");

// Create an emitter to send events to a reciever
const emit = emitterFor(httpTransport("https://my.receiver.com/endpoint"));

// Create a new CloudEvent
const ce = new CloudEvent({ type, source, data });

// Send it to the endpoint - encoded as HTTP binary by default
emit(ce);

If you prefer to use another transport mechanism for sending events over HTTP, you can use the HTTP binding to create a Message which has properties for headers and body, allowing greater flexibility and customization. For example, the axios module is used here to send a CloudEvent.

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 to send your CloudEvents.

const { emitterFor, httpTransport, Mode, CloudEvent, Emitter } = require("cloudevents");

// Create a CloudEvent emitter function to send events to our receiver
const emit = emitterFor(httpTransport("https://example.com/receiver"));

// Use the emit() function to send a CloudEvent to its endpoint when a "cloudevent" event is emitted
// (see: https://nodejs.org/api/events.html#class-eventemitter)
Emitter.on("cloudevent", emit);

...
// In any part of the code, calling `emit()` on a `CloudEvent` instance will send the event
new CloudEvent({ type, source, data }).emit();

// You can also have several listeners to send the event to several endpoints

CloudEvent Objects

All 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"});

You can create a CloudEvent object in many ways, for example, in TypeScript:

import { CloudEvent, CloudEventV1, CloudEventV1Attributes } from "cloudevents";
const ce: CloudEventV1<string> = {
  specversion: "1.0",
  source: "/some/source",
  type: "example",
  id: "1234"
};
const event = new CloudEvent(ce);
const ce2: CloudEventV1Attributes<string> = {
  specversion: "1.0",
  source: "/some/source",
  type: "example",
};
const event2 = new CloudEvent(ce2);
const event3 = new CloudEvent({
  source: "/some/source",
  type: "example",
});

Example Applications

There are a few trivial example applications in the examples folder. There you will find Express.js, TypeScript and Websocket examples.

API Transition Guide

Guide Link

Supported specification features

Core Specification v0.3 v1.0
CloudEvents Core ✔️ ✔️

Event Formats v0.3 v1.0
AVRO Event Format
JSON Event Format ✔️ ✔️

Protocol Bindings v0.3 v1.0
AMQP Protocol Binding
HTTP Protocol Binding ✔️ ✔️
Kafka Protocol Binding ✔️
MQTT Protocol Binding ✔️
NATS Protocol Binding

Content Modes v0.3 v1.0
HTTP Binary ✔️ ✔️
HTTP Structured ✔️ ✔️
HTTP Batch ✔️ ✔️
Kafka Binary ✔️ ✔️
Kafka Structured ✔️ ✔️
Kafka Batch ✔️ ✔️
MQTT Binary ✔️ ✔️
MQTT Structured ✔️ ✔️

Community

Maintainers

Currently active maintainers who may be found in the CNCF Slack.

  • Lance Ball (@lance)
  • Lucas Holmquist (@lholmquist)

Contributing

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.