or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser.mdfiles.mdindex.mdschemas.mdservices.mdstreams.mdtypes.md
tile.json

schemas.mddocs/

Schema Processing

IDL parsing and protocol assembly functionality for working with Avro Interface Definition Language and complex schema compositions.

Capabilities

Protocol Assembly

Assemble an IDL file into a decoded protocol with dependency resolution.

/**
 * Assemble an IDL file into a decoded protocol
 * @param filePath - Path to IDL file
 * @param opts - Assembly options
 * @param callback - Completion callback
 */
function assembleProtocol(filePath, opts, callback);

Usage Examples:

const avsc = require('avsc');

// Assemble protocol from file
avsc.assembleProtocol('./calculator.avdl', (err, protocol) => {
  if (err) {
    console.error('Assembly failed:', err);
    return;
  }
  
  console.log('Protocol:', protocol.protocol);
  const service = avsc.Service.forProtocol(protocol);
});

// With options
avsc.assembleProtocol('./calculator.avdl', {
  importHook: (filePath, kind, name) => {
    // Custom import resolution
    return fs.readFileSync(path.resolve(filePath));
  }
}, (err, protocol) => {
  // Handle result
});

Protocol Reading

Read protocol from IDL string with parsing and validation.

/**
 * Read protocol from IDL string
 * @param protocolIdl - Protocol IDL string
 * @param opts - Parsing options
 * @returns Parsed protocol object
 */
function readProtocol(protocolIdl, opts);

Usage Examples:

const avsc = require('avsc');

const idl = `
protocol Calculator {
  record AddRequest {
    int a;
    int b;
  }
  
  int add(AddRequest request);
}`;

// Parse protocol IDL
const protocol = avsc.readProtocol(idl);
console.log('Protocol name:', protocol.protocol);
console.log('Messages:', Object.keys(protocol.messages));

// With namespace option
const protocol = avsc.readProtocol(idl, {
  namespace: 'com.example'
});

Schema Reading

Read schema from IDL string with type resolution.

/**
 * Read schema from IDL string
 * @param schemaIdl - Schema IDL string
 * @param opts - Parsing options
 * @returns Parsed schema object
 */
function readSchema(schemaIdl, opts);

Usage Examples:

const avsc = require('avsc');

// Simple schema IDL
const schema = avsc.readSchema(`
record User {
  string name;
  int age;
  union { null, string } email = null;
}`);

console.log('Schema:', JSON.stringify(schema, null, 2));

// Complex schema with references
const schema = avsc.readSchema(`
enum Color { RED, GREEN, BLUE }

record Product {
  string name;
  Color color;
  double price;
}`, {
  namespace: 'com.example.catalog'
});

Note: The generic read function is available internally in the specs module but not exported in the main avsc module. Use readSchema or readProtocol instead for specific parsing needs, or access it through the internal parse function which uses specs.read internally.

IDL Syntax Support

AVSC supports full Avro IDL syntax including:

Schema Definitions

// Primitive types
string, int, long, float, double, boolean, bytes, null

// Complex types
record User {
  string name;
  int age;
  array<string> tags = [];
}

enum Status { ACTIVE, INACTIVE, PENDING }

fixed Hash(16);

map<string> metadata;

union { null, string, int } flexible;

Protocol Definitions

protocol Calculator {
  // Import other protocols/schemas
  import idl "common.avdl";
  import protocol "math.avpr";
  import schema "types.avsc";
  
  // Type definitions
  record Request {
    double a;
    double b;
  }
  
  // Error definitions
  error DivisionByZero {
    string message;
  }
  
  // Message definitions
  double add(Request req);
  double divide(Request req) throws DivisionByZero;
  
  // One-way messages
  oneway void log(string message);
}

Annotations and Documentation

/**
 * User record with contact information
 */
record User {
  /** User's full name */
  string name;
  
  /** Age in years */
  int age;
  
  /** Optional email address */
  union { null, string } email = null;
} = User;

Internal Components

Tokenizer

IDL tokenizer for parsing Avro Interface Definition Language.

class Tokenizer {
  /**
   * Create tokenizer for IDL string
   * @param str - IDL string to tokenize
   */
  constructor(str);
  
  /**
   * Get next token
   * @returns Token object or null if end
   */
  next();
  
  /**
   * Peek at next token without consuming
   * @returns Token object or null
   */
  peek();
}

Registry

Type registry for named type resolution and caching.

class Registry {
  /**
   * Register named type
   * @param name - Type name
   * @param type - Type instance
   */
  register(name, type);
  
  /**
   * Lookup type by name
   * @param name - Type name
   * @returns Type instance or undefined
   */
  lookup(name);
  
  /**
   * Clear registry
   */
  clear();
}

Types

interface AssemblyOptions {
  /** Hook for custom import resolution */
  importHook?: (filePath: string, kind: string, name?: string) => string | Buffer;
  
  /** Base directory for relative imports */
  baseDir?: string;
}

interface ReadOptions {
  /** Default namespace for named types */
  namespace?: string;
  
  /** Type registry for name resolution */
  registry?: Registry;
  
  /** Custom logical type implementations */
  logicalTypes?: {[type: string]: any};
}

interface Token {
  /** Token type */
  type: 'identifier' | 'string' | 'number' | 'symbol' | 'keyword';
  
  /** Token value */
  value: string | number;
  
  /** Position information */
  pos: number;
  
  /** Line number */
  line: number;
  
  /** Column number */
  column: number;
}

interface ProtocolObject {
  /** Protocol name */
  protocol: string;
  
  /** Protocol namespace */
  namespace?: string;
  
  /** Documentation */
  doc?: string;
  
  /** Named type definitions */
  types?: any[];
  
  /** Message definitions */
  messages: {[name: string]: MessageDefinition};
}

interface MessageDefinition {
  /** Request schema */
  request: any;
  
  /** Response schema */
  response: any;
  
  /** Error schemas */
  errors?: any[];
  
  /** Documentation */
  doc?: string;
  
  /** One-way message flag */
  'one-way'?: boolean;
}