{"id":15080,"library":"avro-js","title":"Avro-js JavaScript Implementation","description":"avro-js is a pure JavaScript implementation of the Apache Avro specification, providing efficient data serialization and deserialization. It is currently stable at version 1.12.1, with the Apache Avro project demonstrating an active release cadence, including regular minor and patch updates across its language SDKs. Key differentiators include its reported speed (often twice as fast as JSON with significantly smaller encodings), comprehensive Avro feature support (including recursive schemas, sort order, and schema evolution), and the ability to serialize arbitrary JavaScript objects through logical types. Notably, it boasts zero runtime dependencies and is designed to run both in Node.js environments and modern web browsers. While the core project evolves the Avro specification and multi-language SDKs, avro-js focuses solely on the JavaScript ecosystem.","status":"active","version":"1.12.1","language":"javascript","source_language":"en","source_url":"https://github.com/apache/avro","tags":["javascript","avro","json"],"install":[{"cmd":"npm install avro-js","lang":"bash","label":"npm"},{"cmd":"yarn add avro-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add avro-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The avro-js library is a CommonJS module. For ESM environments, use `import * as avro` to import the entire module object, as there is no default export.","wrong":"import avro from 'avro-js';","symbol":"avro","correct":"import * as avro from 'avro-js';"},{"note":"Specific methods like `parse` are properties of the main `avro` module object, not direct named exports. Access them via the imported `avro` namespace object.","wrong":"import { parse } from 'avro-js';\nconst type = parse(schema);","symbol":"avro.parse","correct":"import * as avro from 'avro-js';\nconst type = avro.parse(schema);"},{"note":"This function is a property of the main `avro` module object and is Node.js-specific for file I/O operations. It is not available in browser environments.","wrong":"import { createFileDecoder } from 'avro-js';","symbol":"avro.createFileDecoder","correct":"import * as avro from 'avro-js';\navro.createFileDecoder('./records.avro')"}],"quickstart":{"code":"import * as avro from 'avro-js';\n\n// 1. Define an Avro schema for a 'Pet' record\nconst petType = avro.parse({\n  name: 'Pet',\n  type: 'record',\n  fields: [\n    {name: 'kind', type: {name: 'Kind', type: 'enum', symbols: ['CAT', 'DOG', 'FISH']}},\n    {name: 'name', type: 'string'},\n    {name: 'age', type: 'int', default: 0}\n  ]\n});\n\n// 2. Create a JavaScript object conforming to the schema\nconst myPet = {kind: 'CAT', name: 'Albert', age: 5};\n\n// 3. Serialize the object to an Avro binary buffer\nconst buffer = petType.toBuffer(myPet);\nconsole.log('Serialized Buffer:', buffer.toString('hex'));\n\n// 4. Deserialize the buffer back into a JavaScript object\nconst deserializedPet = petType.fromBuffer(buffer);\nconsole.log('Deserialized Object:', deserializedPet);\n\n// 5. Generate a random instance of the schema\nconst randomIdType = avro.parse('{\"type\": \"fixed\", \"name\": \"Id\", \"size\": 4}');\nconst randomId = randomIdType.random();\nconsole.log('Random ID (Buffer):', randomId.toString('hex'));\n\n// 6. Check if an object is valid against a schema\nconst isValid = petType.isValid({kind: 'DOG', name: 'Buddy'});\nconsole.log('Is valid pet object:', isValid);\n\nconst isInvalid = petType.isValid({kind: 'FISH', unknownField: 'extra'});\nconsole.log('Is invalid pet object (extra field):', isInvalid);","lang":"javascript","description":"Demonstrates basic Avro schema parsing, object serialization to a buffer, deserialization back to an object, random instance generation, and schema validation."},"warnings":[{"fix":"For a union type like `[\"null\", \"MyRecord\"]` where `MyRecord` is recursive, always structure nested data as `{ MyRecord: { field1: value1, ... } }` instead of directly `{ field1: value1, ... }`.","message":"When defining recursive schemas, `avro-js` does not use duck-typing for nested records within unions. You must explicitly specify the record type name for recursive instances, e.g., `{ \"RecordName\": { ... } }` rather than just `{ ... }`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In browser environments, load schemas as JSON strings or JavaScript objects using `avro.parse(jsonString)` or `avro.parse(jsonObject)`. Avoid all file I/O methods.","message":"File system operations, such as `avro.parse('./path/to/schema.avsc')` for loading schema files or `avro.createFileDecoder()` for reading Avro container files, are strictly for Node.js environments and are not supported in web browsers.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To preserve precision for `long` types, configure `avro-js` to use `BigInt` or a library like `long.js` for `long` schema types. This often involves customizing logical types or type hooks during schema parsing. Refer to the `avro-js` documentation for specific configuration options related to 64-bit integers.","message":"Avro `long` types correspond to 64-bit signed integers. JavaScript's native `Number` type uses 64-bit floating-point format and can only safely represent integers up to `2^53 - 1`. Handling `long` values outside this range can lead to precision loss without explicit configuration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always validate Avro schemas carefully using online tools or a schema linter. Pay close attention to JSON syntax rules and Avro's complex type definitions, especially for `record`, `enum`, `array`, `map`, and `union` types. Ensure all required fields like `name` and `type` are correctly defined.","message":"While Avro schemas are JSON-based, strict adherence to the Avro specification is required for schema parsing and data validation. Common JSON syntax errors (e.g., trailing commas, unquoted property names) or Avro-specific schema definition errors (e.g., invalid field types, missing required attributes) can lead to parsing failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"When dealing with recursive or optional record types within a union, explicitly wrap the nested object with its Avro record name, e.g., `{ next: { LongList: { value: 2, next: null } } }` instead of `{ next: { value: 2, next: null } }`.","cause":"Attempting to serialize an object that uses an untagged record within a union type where the record type name is expected.","error":"Error: Invalid value for union type: expected 'null' or 'LongList', got object"},{"fix":"For modern JavaScript environments, use `import * as avro from 'avro-js';`. If running in Node.js ES Modules, ensure your `package.json` specifies `\"type\": \"module\"` and adjust imports accordingly. If `avro-js` is primarily CJS, use `import avro from 'avro-js';` with caution, as it implies a default export which may not exist, or `import * as avro from 'avro-js';`.","cause":"Using CommonJS `require()` syntax in a JavaScript module that is treated as an ES Module (e.g., in a Node.js project with `\"type\": \"module\"` or in a browser via modern bundling without CommonJS transpilation).","error":"ReferenceError: require is not defined"},{"fix":"Ensure that `avro-js` file-based operations are only executed in Node.js. For browser applications, load schemas as pre-fetched JSON strings or JavaScript objects and use `avro.parse(jsonString)` or `avro.parse(jsonObject)`.","cause":"Attempting to use `avro.parse('./path.avsc')` or `avro.createFileDecoder()` in a browser environment, which lack Node.js file system (`fs`) modules.","error":"ReferenceError: fs is not defined"},{"fix":"Ensure that the JavaScript object being passed for serialization contains all fields that are defined as required in the corresponding Avro schema. Provide a value for the missing field or update the schema to make the field optional or provide a default.","cause":"An object being serialized is missing a field that is marked as required (i.e., not a union with 'null' and no default value) in the Avro schema.","error":"Error: Missing required field: 'fieldName'"}],"ecosystem":"npm"}