cloudevents
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.3 • Public • Published

    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 versions 0.3, 1.0

    Installation

    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 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

    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 endpoint

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

    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 ✔️ ✔️

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

    Community

    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.

    Install

    npm i cloudevents

    DownloadsWeekly Downloads

    30,401

    Version

    4.0.3

    License

    Apache-2.0

    Unpacked Size

    1.86 MB

    Total Files

    103

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar