Apache Avro in JavaScript: avsc vs avro-js

When working with Apache Avro in the JavaScript ecosystem, you need a library that can handle schema definition, binary encoding, and decoding reliably. avsc and avro-js are the two primary options, but they differ significantly in maintenance, feature completeness, and API design. Let's break down how they handle real-world serialization tasks.

📜 Schema Handling and Type Creation

avsc provides a robust API for parsing schemas and creating types. It supports schema resolution and evolution out of the box.

// avsc: Parse schema and create type
const avsc = require('avsc');

const schema = {
  type: 'record',
  name: 'User',
  fields: [
    { name: 'id', type: 'long' },
    { name: 'username', type: 'string' }
  ]
};

const type = avsc.Type.forSchema(schema);
const value = { id: 123, username: 'alice' };
const buffer = type.toBuffer(value);

avro-js uses a similar concept but with a different API structure. It requires creating a schema object first.

// avro-js: Create schema and encode
const avro = require('avro-js');

const schema = avro.schema({
  type: 'record',
  name: 'User',
  fields: [
    { name: 'id', type: 'long' },
    { name: 'username', type: 'string' }
  ]
});

const value = { id: 123, username: 'alice' };
const buffer = schema.toBuffer(value);

🔄 Encoding and Decoding Data

avsc handles encoding and decoding with built-in validation. It throws clear errors if the data doesn't match the schema.

// avsc: Decode with validation
const decoded = type.fromBuffer(buffer);
// decoded: { id: 123, username: 'alice' }

// Invalid data throws an error
try {
  type.fromBuffer(Buffer.from('invalid'));
} catch (err) {
  console.error(err.message); // Clear error message
}

avro-js also supports encoding and decoding but may have less detailed error messages in older versions.

// avro-js: Decode data
const decoded = schema.fromBuffer(buffer);
// decoded: { id: 123, username: 'alice' }

// Error handling varies by version
try {
  schema.fromBuffer(Buffer.from('invalid'));
} catch (err) {
  console.error(err.message);
}

🧬 Advanced Features: Logical Types and Unions

avsc has first-class support for logical types (e.g., dates, decimals) and complex unions.

// avsc: Logical types support
const schemaWithLogical = {
  type: 'record',
  name: 'Event',
  fields: [
    { name: 'timestamp', type: { type: 'long', logicalType: 'timestamp-millis' } }
  ]
};

const type = avsc.Type.forSchema(schemaWithLogical);
const buffer = type.toBuffer({ timestamp: new Date() });
const event = type.fromBuffer(buffer); // timestamp is a Date object

avro-js supports logical types but may require additional configuration or have limited support for newer logical types depending on the version.

// avro-js: Logical types support
const schemaWithLogical = avro.schema({
  type: 'record',
  name: 'Event',
  fields: [
    { name: 'timestamp', type: { type: 'long', logicalType: 'timestamp-millis' } }
  ]
});

const buffer = schemaWithLogical.toBuffer({ timestamp: new Date() });
const event = schemaWithLogical.fromBuffer(buffer);

🛡️ Schema Evolution and Compatibility

avsc excels at schema evolution. It allows you to decode data written with an older schema using a new schema (reader/writer schema resolution).

// avsc: Schema resolution
const writerType = avsc.Type.forSchema(writerSchema);
const readerType = avsc.Type.forSchema(readerSchema);

const buffer = writerType.toBuffer({ id: 1, username: 'alice', email: 'a@example.com' });

// Decode with reader schema (missing fields handled gracefully)
const value = readerType.fromBuffer(buffer, writerType);

avro-js supports schema evolution but the API for reader/writer resolution is less documented and may require manual handling in some cases.

// avro-js: Schema resolution
// Similar concept but API may differ slightly
const buffer = writerSchema.toBuffer(data);
const value = readerSchema.fromBuffer(buffer, writerSchema);

🌐 Browser and Bundle Considerations

avsc is designed to work in both Node.js and browser environments. It has no native dependencies.

// avsc: Browser usage
// Works with bundlers like Webpack or Vite
import * as avsc from 'avsc';
// No special configuration needed for most cases

avro-js also works in browsers but may require polyfills for older environments or specific bundler configurations.

// avro-js: Browser usage
import * as avro from 'avro-js';
// May need additional setup for certain bundlers

📝 TypeScript Support

avsc includes TypeScript definitions, making it easier to use in typed projects.

// avsc: TypeScript usage
import * as avsc from 'avsc';

const schema: avsc.Schema = {
  type: 'record',
  name: 'User',
  fields: [{ name: 'id', type: 'long' }]
};

const type = avsc.Type.forSchema(schema);

avro-js has community-maintained types or older definitions that may not cover all APIs.

// avro-js: TypeScript usage
import * as avro from 'avro-js';
// Types may be less complete than avsc

📊 Summary Table

💡 The Big Picture

avsc is the clear choice for modern JavaScript development. It offers better maintenance, clearer APIs, and more robust support for advanced Avro features like schema evolution and logical types. Its TypeScript support makes it ideal for large-scale frontend or full-stack applications.

avro-js is a viable option only for legacy projects where migration is too costly. For any new work, the ecosystem has standardized around avsc due to its reliability and feature completeness.

Final Thought: Data serialization is critical for interoperability. Choosing a well-maintained library like avsc reduces the risk of bugs and ensures compatibility with the broader Apache Avro ecosystem.