Avsc is a pure JavaScript implementation of the Apache Avro specification, currently stable at version 5.7.9. It provides fast and compact data serialization and deserialization, often outperforming JSON with smaller encodings. Key features include comprehensive support for Avro type inference, schema evolution, logical types (e.g., handling JavaScript Date objects transparently), and remote procedure calls (RPC) with IDL support. The library is actively maintained, with recent minor updates indicating ongoing development. It differentiates itself by offering a complete Avro ecosystem within JavaScript, making it suitable for high-performance data interchange and integration with Avro-based systems like Apache Kafka, especially in Node.js environments. The package also ships with built-in TypeScript type definitions.
npm install avscVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define an Avro schema, create an Avro `Type`, and then use it to encode and decode JavaScript objects into binary buffers. It also shows basic type inference.
Review and update code that handles Avro union types. If you relied on a wrapper object around union values, you may need to adjust your parsing logic or explicitly configure `avsc` to use the legacy wrapped union representation if available (though it's recommended to migrate to the unwrapped format).
For applications requiring exact 64-bit integer precision, configure `avsc` to use custom 'long' types such as `BigInt` (Node.js >= 10) or libraries like `long.js`. This is done via options when creating `Type` instances, e.g., `Type.forSchema(schema, { logicalTypes: { 'long': MyBigIntLongType } })`.For complex IDL definitions with multiple imports, consider flattening your schema into a single file or using pre-processing steps to resolve imports before passing them to `avsc.readProtocol` or `avro.assemble`. `parseTypeSchema` specifically does not support imports.
Strictly adhere to Avro schema evolution rules (e.g., only add nullable fields, do not remove existing fields, ensure compatible type changes). Thoroughly test schema compatibility between different versions of your data producers and consumers.
Verify the integrity of the Avro binary data. Ensure the schema used for decoding (`reader's schema`) is compatible with the schema used for encoding (`writer's schema`). If reading from a file, check file corruption or incorrect file type.
Ensure that all non-nullable fields defined in your Avro schema are present in the JavaScript object you are attempting to serialize, or make the field nullable in the schema definition (e.g., `['null', 'string']`).
Review your Avro schema definition carefully against the Avro specification. Check for typos, missing `type` properties, incorrect capitalization of primitive types, or invalid complex type structures.
Ensure all named types are fully defined or accessible within the context of the combined schemas when performing schema evolution. Check for correct namespaces and names of referenced types.