Skip to content

docs: update readme to include http builtin transport #483

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 21, 2022
Merged

docs: update readme to include http builtin transport #483

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de17b5b
doc: update readme to include http builtin transport
lance Mar 18, 2022
2a58257
fixup: PR review feedback
lance Mar 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 28 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The CloudEvents SDK for JavaScript.
- Serialize and deserialize CloudEvents in different [event formats](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format).
- Send and recieve CloudEvents with via different [protocol bindings](https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding).

_Note:_ Supports CloudEvent versions 0.3, 1.0
_Note:_ Supports CloudEvent version 1.0

## Installation

Expand Down Expand Up @@ -46,9 +46,26 @@ app.post("/", (req, res) => {

#### 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`.
The easiest way to send events is to use the built-in HTTP emitter.

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

// Create an emitter to send events to an 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.

```js
const axios = require("axios").default;
Expand Down Expand Up @@ -87,30 +104,20 @@ const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
emit(new CloudEvent({ type, source, data }));
```

You may also use the `Emitter` singleton
You may also use the `Emitter` singleton to send your `CloudEvents`.

```js
const axios = require("axios").default;
const { emitterFor, Mode, CloudEvent, Emitter } = require("cloudevents");
const { emitterFor, httpTransport, 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,
});
}
// Create a CloudEvent emitter function to send events to our receiver
const emit = emitterFor(httpTransport("https://example.com/receiver"));

const emit = emitterFor(sendWithAxios, { mode: Mode.BINARY });
// Set the emit
// 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 will send the event
// 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
Expand Down