sdk-javascript

Javascript SDK for CloudEvents

This is a WIP

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)

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?

/* 
 * 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 = 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?

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

See how to implement the method injection here

Learn about Builder Design Pattern

Check out the produced event payload using this tool