This package provides simple, well typed API for creating Avro Schemas.
npm install avroschema-definer
This package is used to create Avro Schema definitions. It was written in typescript and provide a lot of usefull info from typings, such as infering interface types from schema.
This package does not compile your schemas, it just provide simple API for creation of schemas (see avsc for compilation purposes).
Here is an example:
import A from 'avroschema-definer'
// Lets define a simple object schema
const UserSchema = A.name('user').namespace('com.mysite').record({
name: A.string(),
id: A.string().logicalType('uuid'),
password: A.string(),
role: A.enum('client', 'suplier'),
birthday: A.union(A.null(), A.long()).default(null)
})
// Now lets get interface of User from schema
type User = typeof UserSchema.type;
/*
type User = {
name: string,
email: string,
password: string,
role: 'client' | 'suplier',
birthday: number | null
}
*/
// Or get plain Avro Schema using .valueOf()
console.log(UserSchema.valueOf())
/*
{
name: 'user',
namespace: 'com.mysite',
type: 'record',
fields: [
{ name: 'name', type: { type: 'string' } },
{ name: 'id', type: { type: 'string', logicalType: 'uuid' } },
{ name: 'password', type: { type: 'string' } },
{
name: 'role',
type: {
name: 'role_value',
type: 'enum',
symbols: [ 'client', 'suplier' ]
}
},
{
default: null,
name: 'birthday',
type: [ { type: 'null' }, { type: 'long' } ]
}
]
}
*/
Working with plain .avsc schemas can be painfull. So I written small cli which can transpile your plain avro schemas into avroschema-definer
code.
$ avroschema-definer template --help
avroschema-definer template <schema> [template] [out]
Allows you to transpile your .avsc files into js/ts code using ejs templates.
Options:
--template, -t Path to .ejs template file. If not provided default template
will be used. Options that can be used in the template:
comment.description? - Description parsed from comments
comment.tags?[tag].(tag | name | type | description) - Tags
in format (@tag {type} name description) parsed from comments
schema - Your plain avro schema parsed using `JSON.parse`
avscToDefinerCode(schema) - Function that transpile your
plain avro schema in avroschema-definer code
[By default: null]
--out, -o Output file path (relative to CWD)
[By default: "./outputSchema.ts"]
--schema, -s Path to your .avsc file to parse (relative to CWD)
Example:
Lets say we have plain schema.avsc
:
/**
* Some description
*
* @variableName NameFromCommentTag
*/
{
"namespace": "namespace",
"type": "record",
"name": "someRecord",
"fields": [
{ "name": "field", "aliases": ["first"], "type": { "type": "string", "logicalType": "uuid" }, "doc": "some field" },
{ "name": "arr", "order": "ascending", "type": { "type": "array", "items": "string" }, "doc": "some field" },
{ "name": "union", "type": ["string", "null"], "doc": "some union field" },
{ "name": "fixed", "type": { "type": "fixed", "size": 10, "logicalType": "decimal", "precision": 10, "scale": 10 }, "doc": "some union field" },
{ "name": "map", "type": { "type": "map", "values": "string" }, "doc": "some union field" },
{ "name": "enum", "type": { "type": "enum", "symbols": ["some", "any"], "default": "some" } }
]
}`
We can transpile it to avroschema-definer
code with such command:
$ avroschema-definer template schema.avsc
After that ./outputSchema.ts
will be created with next output:
import A from 'avroschema-definer'
/**
* Some description // <--- This was parsed from schema.avsc top comment
*/
// This name was also parsed from `@variableName NameFromCommentTag` tag from `schema.avsc`
// |
// |
const NameFromCommentTag = A.name('someRecord').namespace('namespace').record({
field: A.string().logicalType('uuid').doc('some field').aliases('first'),
arr: A.array(A.string()).doc('some field').order('ascending'),
union: A.union(A.string(), A.null()).doc('some union field'),
fixed: A.fixed(10).logicalType<number>('decimal', { precision: 10, scale: 10}).doc('some union field'),
map: A.map(A.string()).doc('some union field'),
enum: A.enum('some', 'any').default("some")
})
By default this script use next .ejs
template:
import A from 'avroschema-definer'
<% if (comment.description) { %>
/**
* <%= comment.description %>
*/
<% } %>
const <%= comment.tags ? comment.tags.variableName.name : 'Schema' %> = <%- avscToDefinerCode(schema) %>
export default <%= comment.tags ? comment.tags.variableName.name : 'Schema' %>
You can pass custom .ejs
template with --template
option.
Full list of options available during rendering you can find in cli help:
$ avroschema-definer template --help
Example of using transpiler from code:
import { templater, avscToDefinerCode } from 'avroschema-definer'
const result = templater('Your <%= additionalData %> ejs template')(plainAvroSchemaString, { additionalData: 'awesome' })
console.log(result) // Your awesome ejs template
// Or you can use plain transpiler
console.log(avscToDefinerCode({ type: "string" })) // A.string()
Give a βοΈ if this project helped you!
Full documentation available here
Main exported variable A: SchemaFactory extends BaseSchema
Method | Description | Avro Schema |
---|---|---|
A.null() | No value | { "type": "null" } |
A.boolean() | A binary value | { "type": "boolean" } |
A.int() | 32-bit signed integer | { "type": "int" } |
A.long() | 64-bit signed integer | { "type": "long" } |
A.float() | Single precision (32-bit) IEEE 754 floating-point number | { "type": "float" } |
A.double() | Double precision (64-bit) IEEE 754 floating-point number | { "type": "double" } |
A.bytes() | Sequence of 8-bit unsigned bytes | { "type": "bytes" } |
A.string() | Unicode character sequence | { "type": "string" } |
A.record(fields: { fieldName: Schema }) | Fully typed record | { "type": "record", fields: [] } } |
A.enum(...symbols: string[]) | Listing symbols, as JSON strings | { type: "enum", symbols: [] } |
A.array(items: Schema) | Schema for the array of items | { "type": "array" items: {} } |
A.union(...schemas: Schema[]) | Declares a schema which may be one of given types | [{ type: "" }, { type: "" }] |
A.fixed(size: number) | Schema which specify the number of bytes per value | { "type": "fixed", "size": 16 } |
A.raw(plain: {}) | Set custom schema values | { ...plain } |
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
npm run test
π€ Igor Solomakha fumo.sujimoshi@gmail.com
- Github: @Sujimoshi
Copyright Β© 2020 Igor Solomakha fumo.sujimoshi@gmail.com.
This project is ISC licensed.
This README was generated with β€οΈ by readme-md-generator