tanagra.js

Watch Star Issue

A simple, lightweight node.js serialization library supporting ES6 classes (including Maps). Currently serializes to both JSON and Google Protobuf formats.

Overview

The tanagra.js project aims to provide javascript developers with the ability to serialize complex, nested classes into a format which can be transmitted over a network or stored in a datastore such as redis. The deserialized objects contain all the data and functions of the original classes, allowing them to be used in code as the originals were. The library requires only standard Javascript (currently tested with ES6 and node.js), with no dependency on experimental features, Babel transpiling or TypeScript.

Project structure

The project is divided into a number of modules:

• tanagra-core - common functionality required by the different serialization formats, including the function for marking classes as serializable
• tanagra-json - serializes the data into JSON format
• tanagra-protobuf - serializes the data into Google protobuffers format (experimental)
• tanagra-protobuf-redis-cache - a helper library for storing serialized protobufs in redis
• tanagra-auto-mapper - walks the module tree in node.js to build up a map of classes, meaning the user doesn't have to specify the type to deserialize to (experimental)

Installation

$ npm add --save tanagra-core
$ npm add --save tanagra-json
$ npm add --save tanagra-protobuf
$ npm add --save tanagra-protobuf-redis-cache
$ npm add --save tanagra-auto-mapper

Alternatively, to install the packages required for default (JSON) serialization:

$ npm add --save tanagra

Basic usage

The following example declares a serializable class, and uses the tanagra-json module to serialize/deserialize it:

const serializable = require('tanagra-core').serializable

class Foo {
  constructor(bar, baz1, baz2, fooBar1, fooBar2) {
    this.someNumber = 123
    this.someString = 'hello, world!'
    this.bar = bar // a complex object with a prototype
    this.bazArray = [baz1, baz2]
    this.fooBarMap = new Map([
      ['a', fooBar1],
      ['b', fooBar2]
    ])
  }
}

// Mark class `Foo` as serializable and containing sub-types `Bar` and `Baz`
module.exports = serializable(Foo, [Bar, Baz], [
  // previous versions of the class
  [Bar, Baz, FooBar], // this version also references FooBar
  [FooBarBaz]         // this version references a different type altogether, FooBarBaz
])

// ...

const json = require('tanagra-json') // alternatively, `require('tanagra-protobuf')`
json.init()                          // `await json.init()` if you're using `tanagra-protobuf`

const foo = new Foo(bar, baz)
const encoded = json.encodeEntity(foo)

// ...

const decoded = json.decodeEntity(encoded, Foo)

Bug reports and feature requests

Can be filed via GitHub.

Contributing

I welcome contributions to the project. You might want to start with some n00b issues. Otherwise, just browse the issues and pick one. You might want to email me to let me know you're working on it.

Roadmap

• Better handling of dynamic changes to class structure at runtime
• Better support for pre-ES6 data-structures (functions-as-classes)
• Full support for Google protobufs (including caching in Redis)
• Support for client-side Javascript
• Support for ESNext decorators
• Support for Typescript