npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@financialforcedev/orizuru

v9.3.2

Published

Streamlined communication between Heroku dynos / other worker processes

Downloads

515

Readme

Orizuru

Build Status

Orizuru is a library that streamlines strongly typed communication between Heroku dynos (or other processes). It leverages Apache Avro for schema validation and communication.

Install

npm install @financialforcedev/orizuru

Usage

Configuration

All Orizuru classes require reference to a transport layer. The transport layer governs how messages are published and subscribed. We inject this as a class constructor configuration parameter.

import { Server } from '@financialforcedev/orizuru';
import { Transport } from '@financialforcedev/orizuru-transport-rabbitmq';

const transport = new Transport({
    url: 'amqp://localhost'
});

const server = new Server({
    port: 8080,
    transport
});

The example above shows how to use our RabbitMQ transport layer with a Server. The same method is used with our other classes.

Server

A Orizuru Server allows you combine Avro schemas with API POST endpoints to create webhooks that validate API post body content and publish events via your chosen transport layer implementation. POST bodies are automatically validated against the Avro schema they are paired with, so the consumer of your events always receives valid input if it is invoked.

import { json, Server } from '@financialforcedev/orizuru';
import { Transport } from '@financialforcedev/orizuru-transport-rabbitmq';

const schema = {
    name: 'ageAndDob',
    type: 'record',
    fields: [
        { name: 'age', type: 'string' },
        { name: 'dob', type: 'string' }
    ]
};

const transport = new Transport({
    url: 'amqp://localhost'
});

const server = new Server({
    port: 8080,
    transport
});

server.addRoute({
    endpoint: '/api/path/',
    middleware: [
        json()
    ],
    schema
})

server.listen();

In the above example, a POST API for /api/path/ageAndDob is created on the server before it listens on port 8080. The post body sent is validated against the schema, which requires age and dob string fields in the JSON body. If the validation succeeds, an event name passed to the transport layer will be the fully qualified name of the Avro schema type ageAndDob, along with an Avro serialised buffer of the POST body.

Additionally, if there is an object on the request called orizuru, e.g. request.orizuru, this will also be serialized and added to the buffer as context. This allows middleware to add context information to the event fired, e.g. session validation and credentials.

Publisher

The Orizuru Publisher allows you to publish events directly from Node.js via a transport layer, with Avro. This can be useful for communication between worker processes that do not expose a Web API. Messages are validated against a supplied schema, and there is also the facility to supply untyped context information.

import { IOrizuruMessage, Publisher } from '@financialforcedev/orizuru';
import { Transport } from '@financialforcedev/orizuru-transport-rabbitmq';

interface Message {
    age: string;
    dob: string;
}

interface Context extends Orizuru.Context {
    sessionId: string;
}

const schema = {
    namespace: 'foo',
    name: 'bar',
    type: 'record',
    fields: [
        { name: 'age', type: 'string' },
        { name: 'dob', type: 'string' }
    ]
};

const message: IOrizuruMessage<Context, Message>  = {
    context: {
        sessionId: '​​​​​9B055039660429865FD49FE65E7FEC4A89F9D20C5D398957C71AFF41091CC276​​​​​'
    },
    message: {
        age: 'fifty',
        dob: '07/01/1991'
    }
};

const transport = new Transport({
    url: 'amqp://localhost'
});

const publisher = new Publisher({
    transport
});

publisher.publish({ schema, message });

This example publishes an event named foo.bar with the message described. The message part is validated against the schema. The context object extends the Orizuru.Context interface, in this case containing a session id.

Handler

The handler handles messages published by the Server or Publisher. It requires a schema name and a handler.

NOTE: The supplied callback to this handler should always handle errors. This means it should never throw an exception, and any promise it returns should always have a catch block. Any errors thrown / rejecting promises returned will be swallowed.

import { Handler, IOrizuruMessage } from '@financialforcedev/orizuru';
import { Transport } from '@financialforcedev/orizuru-transport-rabbitmq';

const schema = {
    namespace: 'foo',
    name: 'bar',
    type: 'record',
    fields: [
        { name: 'age', type: 'string' },
        { name: 'dob', type: 'string' }
    ]
};

const handler = async ({ message, context }: IOrizuruMessage<any, any>) => {
    console.log('handling messages from the server API');
    console.log(message);
    console.log(context);
}

const transport = new Transport({
    url: 'amqp://localhost'
});

const handlerInstance = new Handler({
    transport
})

Promise.all([
    handlerInstance.handle({ schema, handler })
]);

The handler can handle multiple events, with callbacks for each wired in. The input to the callback { message, context } is auto deserialized, so you get the JS object represention of the API post body or the JS object published, along with the context added by server middleware or supplied to the publish function.

API Docs

Click to view TSDoc API documentation.