Avsc

Pure JavaScript implementation of the Avro specification.

Features

• Full Avro schema support, including recursive schemas, sort order, and schema evolution.
• Fast! Typically twice as fast as JSON with much smaller encodings (varies per schema).
• Unopinionated 64-bit integer compatibility.
• No dependencies, avsc even runs in the browser.

Performance

Representative decoding throughput rates (higher is better):

Libraries compared:

• node-avsc, this package.
• node-json, built-in JSON serializer.
• node-pson, an alternative to JSON.
• node-etp-avro, existing Avro implementation.
• node-avro-io, other popular Avro implementation.

These rates are for decoding a realistic record schema, modeled after a popular open-source API. Encoding rates are slightly lower but ratios across libraries are similar. You can find the raw numbers and more details on the benchmarks page.

Installation

$ npm install avsc

avsc is compatible with all versions of node.js since 0.11 and major browsers via browserify.

Documentation

• Overview
• API
• Advanced usage

Examples

Inside a node.js module, or using browserify:

var avsc = require('avsc');

• Encode and decode objects:

  // We can declare a schema inline:
  var type = avsc.parse({
    name: 'Pet',
    type: 'record',
    fields: [
      {name: 'kind', type: {name: 'Kind', type: 'enum', symbols: ['CAT', 'DOG']}},
      {name: 'name', type: 'string'}
    ]
  });
  var pet = {kind: 'CAT', name: 'Albert'};
  var buf = type.toBuffer(pet); // Serialized object.
  var obj = type.fromBuffer(buf); // {kind: 'CAT', name: 'Albert'}

• Generate random instances of a schema:

  // We can also parse a JSON-stringified schema:
  var type = avsc.parse('{"type": "fixed", "name": "Id", "size": 4}');
  var id = type.random(); // E.g. Buffer([48, 152, 2, 123])

• Check whether an object fits a given schema:

  // Or we can specify a path to a schema file (not in the browser):
  var type = avsc.parse('./Person.avsc');
  var person = {name: 'Bob', address: {city: 'Cambridge', zip: '02139'}};
  var status = type.isValid(person); // Boolean status.

• Get a readable stream of decoded records from an Avro container file (not in the browser):

  avsc.createFileDecoder('./records.avro')
    .on('metadata', function (type) { /* `type` is the writer's type. */ })
    .on('data', function (record) { /* Do something with the record. */ });

Limitations

• Protocols aren't yet implemented.