utp.js v1.0.4

UTP.js is simple, fast and lightweight binary typed protocol for Node.js and Browser with zero dependencies and built-in RPC

Quick Start

1. Install

npm install utp.js

or

yarn add utp.js

2. Add user defined scheme

import UTP from 'utp.js'

UTP.addSchema('MY_DATA', [
  { name: 'id', type: UTP.TYPE.UINT32 },
  { name: 'name', type: UTP.TYPE.STRING },
  { name: 'type', type: UTP.TYPE.ENUM, list: ['ONE', 'TWO', 'THREE'] },
  { name: 'rights', type: UTP.TYPE.ARRAY, items: { type: UTP.TYPE.UINT8 } },
  { name: 'active', type: UTP.TYPE.BOOL }
])

3. Encode data to binary packet

const data = UTP.encode('MY_DATA', {
  id: 4512,
  name: 'Username',
  type: 'ONE',
  rights: [1, 2, 3],
  active: true
})

4. Decode data to JavaScript object

const packet = UTP.decode(data)
console.log('Decoded header', packet.header)
console.log('Decoded data', packet.data)

/**
 * 
 * Output
 * Decoded header {
 *   schemaIndex: 8,
 *   packetIndex: 1,
 *   version: 1,
 *   size: 36,
 *   schemaName: 'MY_DATA'
 * }
 * Decoded data {
 *   id: 4512,
 *   name: 'Username',
 *   type: 'ONE',
 *   rights: [ 1, 2, 3 ],
 *   active: true
 * }
 */

5. Register RPC method

UTP.addSchema('AUTH_SIGNIN', [
  { name: 'email', type: UTP.TYPE.STRING }
])

UTP.registerRPC('auth.getCode', 'AUTH_SIGNIN')

6. Encode RPC data to binary packet

const data = UTP.encodeRPC('auth.getCode', {
  email
})

7. Decode RPC data

const packet = UTP.decode(data)
console.log('Decoded header', packet.header)
console.log('Decoded data', packet.data)

/**
 * Output
 * Decoded header {
 *   schemaIndex: 7,
 *   packetIndex: 1,
 *   version: 1,
 *   size: 51,
 *   schemaName: 'RPC',
 *   method: 'auth.getCode'
 * }
 * Decoded data { email: 'test@email.address' }
 */

8. Update protocol definitions on clients

// .... on the server you add new schemes and register RPC methods

UTP.setVersion(10000)

// PROTO is default schema for encode
const defs = UTP.encode()

// on the client the protocol definitions have an automatic update after unlocking and decoding the PROTO packet
UTP.setLock(false)
UTP.decode(defs)

UTP.getVersion() // 10000

Predefined schemes

HELLO/PING/PONG

[]

ERROR

[
  { name: 'code', type: UTP.TYPE.UINT16 },
  { name: 'text', type: UTP.TYPE.STRING }
]

PROTO

[
  { name: 'VERSION', type: UTP.TYPE.UINT32 },
  { name: 'TYPES', type: UTP.TYPE.JSON },
  { name: 'SCHEMES_NAMES', type: UTP.TYPE.ARRAY, items: { type: UTP.TYPE.STRING } },
  { name: 'SCHEMES', type: UTP.TYPE.ARRAY, items: { type: UTP.TYPE.ARRAY, items: { type: UTP.TYPE.SCHEMA, schema: 'SCHEMA' } } },
  { name: 'RPC', type: 'JSON' }
]

SCHEMA

[
  { name: 'name', type: UTP.TYPE.STRING },
  { name: 'type', type: UTP.TYPE.ENUM, list: DEFS.TYPES_NAMES },
  { name: 'items', type: UTP.TYPE.SCHEMA, schema: 'SCHEMA_ITEMS', optional: true },
  { name: 'schema', type: UTP.TYPE.STRING, optional: true },
  { name: 'list', type: UTP.TYPE.ARRAY, items: { type: UTP.TYPE.STRING }, optional: true },
  { name: 'maxlength', type: UTP.TYPE.INT32, optional: true },
  { name: 'optional', type: UTP.TYPE.BOOL, optional: true }
]

SCHEMA_ITEMS

[
  { name: 'type', type: UTP.TYPE.ENUM, list: DEFS.TYPES_NAMES },
  { name: 'schema', type: UTP.TYPE.STRING, optional: true },
  { name: 'items', type: UTP.TYPE.SCHEMA, schema: 'SCHEMA_ITEMS', optional: true },
  { name: 'list', type: UTP.TYPE.ARRAY, items: { type: UTP.TYPE.STRING }, optional: true }
]

RPC

[
  { name: 'method', type: UTP.TYPE.STRING },
  { name: 'packet', type: UTP.TYPE.PACKET, optional: true }
]

Predefined types

Basic types

Additional types

Extended types

License

• See LICENSE