Javascript SDK for CloudEvents
Clone or download
Latest commit 0a0e24e Dec 10, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Spec 0.2 impl Dec 6, 2018
test Spec 0.2 impl Dec 6, 2018
.gitignore Project start Nov 9, 2018
.travis.yml setup github release Dec 9, 2018
LICENSE Initial commit Sep 20, 2018
README.md format the how to use Dec 9, 2018
index.js Remove commented code Nov 14, 2018
package.json Fix the package name Dec 9, 2018

README.md

Codacy Badge Build Status

sdk-javascript

Javascript SDK for CloudEvents

This is a WIP

Installation

This CloudEvents SDK requires nodejs 6.11+

Nodejs

npm install cloudevents-sdk

Specification Support

These are the supported specifications by this version.

Specifications v0.1 v0.2
CloudEvents yes yes
HTTP Transport Binding yes yes
JSON Event Format yes yes

How to use

The Cloudevent constructor arguments.

/*
 * spec  : if is null, set the spec 0.1 impl
 * format: if is null, set the JSON Format 0.1 impl
 */
Cloudevent(spec, format);

How to construct instances?

var Cloudevent = require("cloudevents-sdk");

/*
 * Constructs a default instance with:
 *   - Spec 0.1
 *   - JSON Format 0.1
 */
var cloudevent01 = new Cloudevent();

/*
 * Implemented using Builder Design Pattern
 */
cloudevent01
  .type("com.github.pull.create")
  .source("urn:event:from:myapi/resourse/123");

/*
 * Backward compatibility by injecting methods from spec implementation to Cloudevent
 */
cloudevent01
 .eventTypeVersion("1.0");

/*
 * Constructs an instance with:
 *   - Spec 0.2
 *   - JSON Format 0.1
 */
var cloudevent02 = new Cloudevent(Cloudevent.specs['0.2']);

/*
 * Different specs, but the same API.
 */
cloudevent02
  .type("com.github.pull.create")
  .source("urn:event:from:myapi/resourse/123");

How to get the formatted payload?

var Cloudevent = require("cloudevents-sdk");

var cloudevent = new Cloudevent()
                       .type("com.github.pull.create")
                       .source("urn:event:from:myapi/resourse/123");

/*
 * Format the payload and return it.
 */
var formatted = cloudevent.format();

How to emit an event?

var Cloudevent = require("cloudevents-sdk");

// The event
var cloudevent = new Cloudevent()
                       .type("com.github.pull.create")
                       .source("urn:event:from:myapi/resourse/123");

// The binding configuration using POST
var config = {
  method: 'POST',
  url   : 'https://mywebhook.com'
};

// The binding instance
var binding = Cloudevent.bindings['http-structured0.1'](config);

// Emit the event using Promise
binding.emit(cloudevent)
  .then(response => {
    // Treat the response
    console.log(response.data);

  }).catch(err => {
    // Treat the error
    console.error(err);
  });

Repository Structure

├── index.js
├── lib
│   ├── bindings
│   │   └── http
│   │       └── structured_0_1.js
│   ├── cloudevent.js
│   ├── format
│   │   └── json_0_1.js
│   └── specs
│       ├── spec_0_1.js
│       └── spec_0_2.js
├── LICENSE
├── package.json
├── README.md
└── test
    ├── cloudevent_spec_0_1.js
    ├── cloudevent_spec_0_2.js
    └── http_binding_0_1.js
  • index.js: library exports

  • lib/bindings: every binding implementation goes here

  • lib/bindings/http: every http binding implementation goes here

  • lib/bindings/http/structured_0_1.js: implementation of structured HTTP Binding

  • lib/cloudevent.js: implementation of Cloudevent, an interface

  • lib/format/: every format implementation goes here

  • lib/format/json_0_1.js: implementation for JSON formatting version 0.1

  • lib/specs/: every spec implementation goes here

  • lib/specs/spec_0_1.js: implementation for spec version 0.1

  • lib/specs/spec_0_2.js: implementation for spec version 0.2

  • test/cloudevent_spec_0_1.js: unit testing for spec 0.1

  • test/cloudevent_spec_0_2.js: unit testing for spec 0.2

Unit Testing

The unit test checks the result of formatted payload and the constraints.

npm test

The API

Cloudevent class

/*
 * Format the payload and return an Object.
 */
Object Cloudevent.format()

/*
 * Format the payload as String.
 */
String Cloudevent.toString()

Formatter classes

Every formatter class must implement these methods to work properly.

/*
 * Format the Cloudevent payload argument and return an Object.
 */
Object Formatter.format(payload)

/*
 * Format the Cloudevent payload as String.
 */
String Formatter.toString(payload)

Spec classes

Every Spec class must implement these methods to work properly.

/*
 * The constructor must receives the Cloudevent type.
 */
Spec(Cloudevent)

/*
 * Checks the spec constraints, throwing an error if do not pass.
 */
Spec.check()

Binding classes

Every Binding class must implement these methods to work properly.

/*
 * The constructor must receives the map of configurations.
 */
Binding(config)

/*
 * Emits the event using an instance of Cloudevent.
 */
Binding.emit(cloudevent)

See how to implement the method injection here

Learn about Builder Design Pattern

Check out the produced event payload using this tool