cloudevent.js

cloudevent.js

JavaScript/Node.js implementation of CloudEvents

The purpose of this library is to create instances of CloudEvents in a simple way (with some useful defaults), or in a full way (all attributes). Optional, it's possible to validate created instances to be sure they are compliant with the standard.

Then, created instances can be serialized, for example to be sent (or saved/stored) somewhere.

Note that many features are exposed directly from the CloudEvent class with standard class instance methods, and even as class static methods (that operates on a given CloudEvent).

More features will follow.

Usage

Get a reference to the library:

// Node.js example

const CloudEvent = require('cloudevent.js')

create some sample CloudEvent instances:

// create some sample instances but without mandatory fields (for validation) ...
const ceEmpty = new CloudEvent() // create an empty CloudEvent instance (not valid for the validator, even in default case, when strict mode flag is disabled)
const ceMinimalMandatoryUndefinedNoStrict = new CloudEvent(undefined, undefined, undefined, undefined, { strict: false }) // expected success
const ceMinimalMandatoryUndefinedStrict = new CloudEvent(undefined, undefined, undefined, undefined, { strict: true }) // expected failure, so ceMinimalMandatoryUndefinedStrict will not be defined

// create some sample minimal instances, good even for validation ...
const ceMinimal = new CloudEvent('1', // eventID
  'com.github.smartiniOnGitHub.cloudeventjs.testevent', // eventType
  '/', // source
  {} // data (empty) // optional, but useful the same in this sample usage
)

// create some instance with all attributes ...
// define some common attributes
const ceCommonOptions = {
  eventTypeVersion: '1.0.0',
  eventTime: new Date(),
  extensions: { 'exampleExtension': 'value' },
  contentType: 'application/json',
  schemaURL: 'http://my-schema.localhost.localdomain',
  strict: false // same as default
}
const ceCommonOptionsStrict = { ...ceCommonOptions, strict: true }
// create some instances with an undefined mandatory argument (handled by defaults), but with strict flag disabled: expected success ...
// note that null values are not handled by default values, only undefined values ...
const ceFull = new CloudEvent('1/full',
  'com.github.smartiniOnGitHub.cloudeventjs.testevent',
  '/test',
  { 'hello': 'world', year: 2018 }, // data
  ceCommonOptions
)
const ceFullStrict = new CloudEvent('2/full-strict',
  'com.github.smartiniOnGitHub.cloudeventjs.testevent',
  '/test',
  { 'hello': 'world', year: 2018 }, // data
  ceCommonOptionsStrict // use common options, but set strict mode to true
)
assert(ceFullStrict.isStrict)
assert(!ceFull.isStrict) // ensure common options object has not been changed when reusing some of its values for the second instance
assert(!CloudEvent.isStrictEvent(ceFull)) // the same, but using static method

optional, do some validations/checks on created instances. As sample, use class static methods like 'isValidEvent' and 'ValidateEvent', or instance methods like 'isValid', 'validate', etc ...

assert(!ceEmpty.isValid())
assert(!ceMinimalMandatoryUndefinedNoStrict.isValid())
assert(ceMinimal.isValid())
assert(ceFull.isValid())
assert(ceFullStrict.isValid())
// the same, but using static method
assert(!CloudEvent.isValidEvent(ceEmpty))
assert(!CloudEvent.isValidEvent(ceMinimalMandatoryUndefinedNoStrict))
assert(CloudEvent.isValidEvent(ceMinimal))
assert(CloudEvent.isValidEvent(ceFull))
assert(CloudEvent.isValidEvent(ceFullStrict))
assert(CloudEvent.validateEvent(ceEmpty).length > 0)
assert(CloudEvent.validateEvent(ceEmpty, { strict: true }).length > 0)
assert(CloudEvent.validateEvent(ceMinimalMandatoryUndefinedNoStrict).length > 0)
assert(CloudEvent.validateEvent(ceMinimal).length === 0)
assert(CloudEvent.validateEvent(ceFull).length === 0)
assert(CloudEvent.validateEvent(ceFull, { strict: false }).length === 0)
assert(CloudEvent.validateEvent(ceFull, { strict: true }).length === 0)
assert(CloudEvent.validateEvent(ceFullStrict).length === 0)
assert(CloudEvent.validateEvent(ceFullStrict, { strict: false }).length === 0)
assert(CloudEvent.validateEvent(ceFullStrict, { strict: true }).length === 0)

console.log(`Validation on ceEmpty: isValid: ${ceEmpty.isValid()}, `)

console.log(`Validation output for ceEmpty, default strict mode is: size: ${CloudEvent.validateEvent(ceEmpty).length}, details:\n` + CloudEvent.validateEvent(ceEmpty))
console.log(`Validation output for ceEmpty, force strict mode to true is size: ${CloudEvent.validateEvent(ceEmpty, { strict: true }).length}, details:\n` + CloudEvent.validateEvent(ceEmpty, { strict: true }))

serialization examples:

const ceFullSerializedStatic = CloudEvent.serializeEvent(ceFull)
const ceFullSerialized = ceFull.serialize()
console.log(`Serialization output for ceFull, details:\n` + ceFullSerialized)

// then use (send/store/etc) serialized instances ...

Look into the example folder for more sample scripts that uses the library (inline but it's the same using it from npm registry).

Requirements

Node.js 8.14.x or later.

Note

Note that in this implementation there is even the ability to validate CloudEvent instances in a stricter way, by setting to true the attribute 'strict' in options in costructor options; or specify it during validation. That attribute when set will be put in the 'extensions' standard attribute of a CloudEvent.

You can find Code Documentation for the API of the library here.

See the CloudEvents Specification here.

The package name 'cloudevent.js' will change just after the '0.2.0' release to the simpler 'cloudevent' (published the same as '0.2.0' release), so it will be easier to get it at npm.

Contributing

1. Fork it ( https://github.com/smartiniOnGitHub/cloudevent.js/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

Licensed under Apache-2.0.

---

Changelog

0.2.0 (2018-12-09)

Summary Changelog:

• Updated dependencies
• Add Badges in the README for simpler download/identify from NPM web site
• Remove cloudEventsVersion attribute from constructor (it's defined in the implementation, as a read-only private property); so the change in release number
• Move source attribute from constructor options to a constructor property (for simpler set/override) and remove its default value; so the change in release number
• Add JSON Schema for CloudEvent, related to current attributes (so it makes sense to expose here, even if used only by other serializing libraries)
• Deprecate the current package name, the new name (simpler) will be cloudevent (drop the .js from the package name); this release will have both, but later versions will be published only with the new name; unluckily I can't use 'cloudevents' because it's already used