Registry / serialization / avro-typescript

avro-typescript

library1.3.0jsnpmunverified

avro-typescript is a dedicated library for generating TypeScript interfaces from Apache Avro schemas. It takes an Avro schema, typically provided as a JavaScript object parsed from JSON, and outputs the corresponding TypeScript code as a string. The library is currently at version 1.3.0 and appears to be actively maintained, with recent updates addressing issues like top-level enum support. It supports most standard Avro features, including enumerated types, maps, named records, unions, and primitives, along with mandatory and optional fields. A key differentiator is its ability to override logical Avro types (e.g., converting an Avro `int` with a `date` logical type to a TypeScript `Date` object) by passing a mapping in the options. This tool operates effectively in both Node.js and browser environments, focusing solely on type generation rather than schema parsing or serialization/deserialization, which often relies on companion libraries like `avsc`.

serialization type-stubs

npm install avro-typescript

github ↗package ↗

INSTALL

IMPORT

SIG · AVRO-TYPESCRIPT

avro-typescript

serializationjavascriptv1.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

avroToTypeScript

✓ import { avroToTypeScript } from 'avro-typescript';

✗ const avroToTypeScript = require('avro-typescript');

The library primarily uses named ESM imports. While CommonJS `require` might work in some transpiled environments, native ESM import is the recommended approach for modern Node.js and bundlers.

RecordType

✓ import { RecordType } from 'avro-typescript';

✗ import { RecordType } from 'avro-typescript/dist/types';

The `RecordType` interface is exported directly from the main package entry point, representing a standard Avro record schema structure for type safety when defining schemas programmatically.

Options

✓ import { Options } from 'avro-typescript';

For customizing generation, such as overriding logical types, import the `Options` interface to type the configuration object passed to `avroToTypeScript`.

This quickstart demonstrates how to use `avro-typescript` to generate TypeScript interfaces from an Avro schema, including handling optional fields, enums, arrays, and logical type overrides to map Avro `timestamp-millis` to TypeScript `Date`.

import { avroToTypeScript, RecordType } from 'avro-typescript'; import * as fs from 'fs'; import * as path from 'path'; // Define a sample Avro schema (typically loaded from a .avsc file) const avroSchema: RecordType = { type: 'record', name: 'UserProfile', namespace: 'com.example.user', fields: [ { name: 'id', type: 'string' }, { name: 'username', type: 'string' }, { name: 'email', type: ['null', 'string'], default: null, }, { name: 'createdAt', type: { type: 'long', logicalType: 'timestamp-millis' }, }, { name: 'status', type: { type: 'enum', name: 'UserStatus', symbols: ['ACTIVE', 'INACTIVE', 'PENDING'], }, default: 'PENDING', }, { name: 'tags', type: { type: 'array', items: 'string' }, default: [], }, ], }; // Options for generating TypeScript, including logical type overrides const generationOptions = { logicalTypes: { 'timestamp-millis': 'Date', }, }; // Generate TypeScript code const typescriptCode = avroToTypeScript(avroSchema, generationOptions); console.log('Generated TypeScript:\n'); console.log(typescriptCode); // Example of writing to a file (optional) const outputPath = path.join(process.cwd(), 'generated-types.d.ts'); fs.writeFileSync(outputPath, typescriptCode); console.log(`\nTypeScript types written to ${outputPath}`); /* Expected output (simplified): Generated TypeScript: export namespace com.example.user { export interface UserProfile { id: string; username: string; email: string | null; createdAt: Date; status: UserStatus; tags: string[]; } export type UserStatus = 'ACTIVE' | 'INACTIVE' | 'PENDING'; } TypeScript types written to .../generated-types.d.ts */

Debug

Known issues

gotchaThe library does not currently provide explicit support for Avro namespaces in the generated TypeScript output (e.g., creating nested modules or namespaces). While the Avro schema itself might define a `namespace`, the output interfaces will typically be at the top level or derive their names directly, potentially leading to name collisions if not managed carefully by the user. Other generators like `@ovotech/avro-ts` offer explicit namespace handling.

fix

Manually manage output file structure or use an external tool to wrap generated types in TypeScript namespaces if strict namespace isolation is required. Be aware of potential name collisions if schemas from different Avro namespaces define types with identical names.

affects: >=1.0.0

gotchaWhen using Avro logical types (e.g., `date`, `timestamp-millis`, `decimal`), `avro-typescript` will default to the underlying primitive Avro type (e.g., `int`, `long`, `bytes`) in the generated TypeScript if no `logicalTypes` override is provided in the options. This can lead to less precise types (e.g., `number` instead of `Date`).

fix

Always pass a `logicalTypes` map in the options object to `avroToTypeScript` to explicitly define the desired TypeScript type for each logical type in your schema, e.g., `{ 'timestamp-millis': 'Date', 'date': 'string' }`.

affects: >=1.0.0

gotchaAvro schemas can define default values for fields, implying they are optional. While `avro-typescript` handles `null` in unions to make fields optional, it does not currently generate TypeScript types that reflect all Avro default values as optional fields in the interface. The `To-do` list indicates a future feature for 'Generate a function to set defaults as per the schema', suggesting full default value integration might be incomplete.

fix

Review generated types for fields with Avro defaults and manually mark them as optional (e.g., `field?: Type;`) in your codebase if strict type-checking of optionality based on Avro defaults is critical for your application logic.

affects: >=1.0.0

Errors

Common errors & fixes

TS2503: Cannot find namespace 'MyAvroNamespace'

This error often occurs when you're trying to reference a TypeScript type that you expect to be wrapped in a namespace corresponding to an Avro namespace, but `avro-typescript` (as of current versions) does not generate explicit TypeScript namespaces. Alternatively, it can happen if types generated by `avro-typescript` are used in conjunction with types generated by other Avro tools that *do* create namespaces, leading to a mismatch.

fix

Ensure that the generated TypeScript types are directly accessible without a namespace prefix, or if using a mix of generation tools, adjust your imports or manually wrap `avro-typescript` generated types into the expected namespace. Consider using unique type names across different Avro namespaces if direct namespace support is not available from your chosen generator.

org.apache.avro.SchemaParseException: Undefined name: MyTypeName

While not a direct TypeScript error, this is a common Avro schema parsing error that arises when the Avro schema itself is invalid, often due to a type referencing another type (`MyTypeName`) that hasn't been defined within the current schema or an imported schema. If `avro-typescript` receives such an invalid schema, its generation might fail or produce incorrect output.

fix

Validate your Avro schema independently using an Avro schema parser or linter before feeding it to `avro-typescript`. Ensure all referenced named types (records, enums, fixed) are correctly defined within the schema or imported if they reside in separate files (though `avro-typescript` expects a single, resolved schema object).

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/joewood/avro-typescript ↗

packagehttps://www.npmjs.com/package/avro-typescript ↗