@metarhia/jstp

JSTP / JavaScript Transfer Protocol

JSTP is an RPC protocol and framework which provides two-way asynchronous data transfer with support of multiple parallel non-blocking interactions that is so transparent that an app may not even distinguish between local async functions and remote procedures.

And, as a nice bonus, there's a blazing fast JSON5 implementation bundled in!

This project is bound by a Code of Conduct.

Installation

JSTP works in Node.js and web browsers:

$ npm install --save @metarhia/jstp

Or, alternatively, there is jstp.umd.js UMD bundle.

We also have official client-side implementations for Swift and Java that work effortlessly on iOS and Android 🎉

There is also an interactive CLI provided by this package:

$ npm install -g @metarhia/jstp
$ jstp-cli

Getting Started

Server:

'use strict';

const jstp = require('@metarhia/jstp');

// Application is the core high-level abstraction of the framework. An app
// consists of a number of interfaces, and each interface has its methods.
const app = new jstp.Application('testApp', {
  someService: {
    sayHi(connection, name, callback) {
      callback(null, `Hi, ${name}!`);
    },
  },
});

// Let's create a TCP server for this app. Other available transports are
// WebSocket and Unix domain sockets. One might notice that an array of
// applications is passed the `createServer()`. That's because it can serve
// any number of applications.
const server = jstp.net.createServer([app]);
server.listen(3000, () => {
  console.log('TCP server listening on port 3000 🚀');
});

Client:

'use strict';

const jstp = require('@metarhia/jstp');

// Create a TCP connection to server and connect to the `testApp` application.
// Clients can have applications too for full-duplex RPC,
// but we don't need that in this example. Client is `null` in this example,
// this implies that username and password are both `null`
// here — that is, the protocol-level authentication is not leveraged in this
// example. The next argument is an array of interfaces to inspect and build
// remote proxy objects for. Remaining arguments are for
// net.connect (host and port) and last argument is a callback
// to be called on successful connection or error.
jstp.net.connectAndInspect(
  'testApp',
  null,
  ['someService'],
  3000,
  'localhost',
  handleConnect
);

function handleConnect(error, connection, app) {
  if (error) {
    console.error(`Could not connect to the server: ${error}`);
    return;
  }

  // The `app` object contains remote proxy objects for each interface that has
  // been requested which allow to use remote APIs as regular async functions.
  // Remote proxies are also `EventEmitter`s: they can be used to `.emit()`
  // events to another side of a connection and listen to them using `.on()`.
  app.someService.sayHi('JSTP', (error, message) => {
    if (error) {
      console.error(`Oops, something went wrong: ${error}`);
      return;
    }
    console.log(`Server said "${message}" 😲`);
  });
}

Project Maintainers

Kudos to @tshemsedinov for the initial idea and proof-of-concept implementation. Current project team is:

• @aqrln — Alexey Orlenko <[e-mail]>
• @belochub — Mykola Bilochub <[e-mail]>
• @lundibundi — Denys Otrishko <[e-mail]>
• @nechaido — Dmytro Nechai <[e-mail]>
• @tshemsedinov — Timur Shemsedinov <[e-mail]>

Changelog

Version 2.3.0 (2019-04-25, @belochub)

This release introduces support for async methods in applications. Other notable changes include fixes for ExpiringMap storage, reconnection, argument output in the CLI, support for passing additional info in errors, and introduction of the package documentation and tutorial.

Notable changes:

• lib: fix invalid args handling in reconnectFn() (Mykola Bilochub) #411
• lib: fix ExpiringMap internal storage growing (Mykola Bilochub) #414
• docs: use mkdocs for documentation (Mykola Bilochub) #410 [semver-minor]
• cli: improve args serialization (Mykola Bilochub) #415 [semver-minor]
• docs: add tutorial to documentation (mille-nium) #417 [semver-minor]
• lib: add support for custom error serialization (Mykola Bilochub) #418 [semver-minor]
• lib: allow passing additional info to RemoteError (Mykola Bilochub) #425 [semver-minor]
• lib: add support for async methods in Applications (Mykola Bilochub) #423 [semver-minor]

All changes:

• deps: use prettier for code formatting (Dmytro Nechai) #402
• deps: update devDependencies (Mykola Bilochub) #403
• npm: add Prettier configs to .npmignore (Mykola Bilochub) #408
• deps: update Prettier and fix configs (Mykola Bilochub) #409
• lib: fix invalid args handling in reconnectFn() (Mykola Bilochub) #411
• lib: fix ExpiringMap internal storage growing (Mykola Bilochub) #414
• deps: update mdsf and devDependencies (Mykola Bilochub) #416
• docs: use mkdocs for documentation (Mykola Bilochub) #410 [semver-minor]
• cli: improve args serialization (Mykola Bilochub) #415 [semver-minor]
• docs: add tutorial to documentation (mille-nium) #417 [semver-minor]
• docs: fix incorrect term usage (Mykola Bilochub) #421
• lib: add support for custom error serialization (Mykola Bilochub) #418 [semver-minor]
• docs: replace http with https in all links (Mykola Bilochub) #424
• lib: allow passing additional info to RemoteError (Mykola Bilochub) #425 [semver-minor]
• lib: add support for async methods in Applications (Mykola Bilochub) #423 [semver-minor]
• deps: update dependencies (Mykola Bilochub) #420