Type System

/**
 * Parse a schema and return the corresponding type or service
 * @param schema - Avro schema object, JSON string, or IDL string
 * @param opts - Parsing options
 * @returns Type or Service instance
 */
function parse(schema, opts);

const avsc = require('avsc');

// Parse a simple schema
const stringType = avsc.parse('string');

// Parse a record schema
const userType = avsc.parse({
  type: 'record',
  name: 'User',
  fields: [
    {name: 'name', type: 'string'},
    {name: 'age', type: 'int'},
    {name: 'email', type: ['null', 'string'], default: null}
  ]
});

// Parse with options
const type = avsc.parse(schema, {
  wrapUnions: true,
  namespace: 'com.example'
});

class Type {
  /**
   * Create type from schema
   * @param schema - Avro schema
   * @param opts - Type creation options
   * @returns Type instance
   */
  static forSchema(schema, opts);
  
  /**
   * Create union type from multiple types
   * @param types - Array of types or schemas
   * @param opts - Type creation options
   * @returns Union type instance
   */
  static forTypes(types, opts);
  
  /**
   * Infer type from JavaScript value
   * @param value - JavaScript value to analyze
   * @param opts - Inference options
   * @returns Inferred type
   */
  static forValue(value, opts);
  
  /**
   * Check if object is a Type instance
   * @param obj - Object to check
   * @param prefixes - Optional type name prefixes to match
   * @returns Boolean indicating if object is a Type
   */
  static isType(obj, ...prefixes);
  
  /**
   * Serialize value to buffer
   * @param value - JavaScript value to serialize
   * @returns Buffer containing serialized data
   */
  toBuffer(value);
  
  /**
   * Deserialize value from buffer
   * @param buffer - Buffer containing serialized data
   * @param resolver - Optional schema resolver for evolution
   * @param noCheck - Skip validation if true
   * @returns Deserialized JavaScript value
   */
  fromBuffer(buffer, resolver, noCheck);
  
  /**
   * Parse value from string representation
   * @param str - String representation of value
   * @returns Parsed JavaScript value
   */
  fromString(str);
  
  /**
   * Validate value against schema
   * @param value - Value to validate
   * @param opts - Validation options
   * @returns Boolean indicating validity
   */
  isValid(value, opts);
  
  /**
   * Clone value with optional transformations
   * @param value - Value to clone
   * @param opts - Clone options
   * @returns Cloned value
   */
  clone(value, opts);
  
  /**
   * Compare two values according to Avro specification
   * @param val1 - First value
   * @param val2 - Second value
   * @returns -1, 0, or 1 for less than, equal, or greater than
   */
  compare(val1, val2);
  
  /**
   * Compare two buffers containing serialized data
   * @param buf1 - First buffer
   * @param buf2 - Second buffer
   * @returns -1, 0, or 1 for comparison result
   */
  compareBuffers(buf1, buf2);
  
  /**
   * Create resolver for schema evolution
   * @param type - Target type for evolution
   * @param opts - Resolver options
   * @returns Schema resolver
   */
  createResolver(type, opts);
  
  /**
   * Check equality with another type
   * @param type - Type to compare with
   * @returns Boolean indicating equality
   */
  equals(type);
  
  /**
   * Get type fingerprint
   * @param algorithm - Hash algorithm (default: 'sha256')
   * @returns Buffer containing fingerprint
   */
  fingerprint(algorithm);
  
  /**
   * Get schema object representation
   * @param opts - Schema options
   * @returns Schema object
   */
  schema(opts);
  
  /**
   * Convert value to string representation
   * @param value - Value to convert
   * @returns String representation
   */
  toString(value);
  
  /**
   * Wrap value for union types
   * @param value - Value to wrap
   * @returns Wrapped value object
   */
  wrap(value);
  
  /**
   * Generate random value conforming to schema
   * @returns Random value
   */
  random();
  
  /**
   * Get string representation of type
   * @returns String representation
   */
  inspect();
  
  /**
   * Encode value to buffer at specific position
   * @param val - Value to encode
   * @param buf - Target buffer
   * @param pos - Position in buffer
   * @returns Updated position
   */
  encode(val, buf, pos);
  
  /**
   * Decode value from buffer at specific position
   * @param buf - Source buffer
   * @param pos - Position in buffer
   * @param resolver - Optional schema resolver
   * @returns Object with value and updated position
   */
  decode(buf, pos, resolver);
  
  /**
   * Get JSON representation of type
   * @returns JSON schema representation
   */
  toJSON();
}

// Create type from schema
const type = avsc.Type.forSchema({
  type: 'record',
  name: 'Person',
  fields: [
    {name: 'name', type: 'string'},
    {name: 'age', type: 'int'}
  ]
});

// Serialize and deserialize
const person = {name: 'Alice', age: 30};
const buffer = type.toBuffer(person);
const decoded = type.fromBuffer(buffer);

// Validation
const isValid = type.isValid({name: 'Bob', age: 25}); // true
const isInvalid = type.isValid({name: 123, age: 'young'}); // false

// Type inference
const inferredType = avsc.Type.forValue({
  id: 123,
  name: 'test',
  active: true
});

// Schema evolution
const writerType = avsc.Type.forSchema(writerSchema);
const readerType = avsc.Type.forSchema(readerSchema);
const resolver = readerType.createResolver(writerType);
const evolved = readerType.fromBuffer(buffer, resolver);

interface Type {
  /** Type aliases from schema */
  aliases: string[];
  
  /** Documentation string from schema */
  doc: string;
  
  /** Type name if named type */
  name: string;
  
  /** Union branch name for union types */
  branchName: string;
  
  /** String representation of type name */
  typeName: string;
}

namespace types {
  // Primitive types
  class NullType extends Type {
    /** Always returns null */
    random(): null;
  }
  
  class BooleanType extends Type {
    /** Returns random boolean */
    random(): boolean;
  }
  
  class IntType extends Type {
    /** Returns random 32-bit integer */
    random(): number;
  }
  
  class LongType extends Type {
    /** Returns random 64-bit integer (as number or Long object) */
    random(): number | Long;
    
    /** Create custom long type with specific methods */
    static __with(methods: LongMethods, noUnpack?: boolean): typeof LongType;
  }
  
  class FloatType extends Type {
    /** Returns random 32-bit float */
    random(): number;
  }
  
  class DoubleType extends Type {
    /** Returns random 64-bit double */
    random(): number;
  }
  
  class BytesType extends Type {
    /** Returns random Buffer */
    random(): Buffer;
  }
  
  class StringType extends Type {
    /** Returns random string */
    random(): string;
  }
  
  // Complex types
  class RecordType extends Type {
    /** Record fields */
    readonly fields: Field[];
    
    /** Record constructor function */
    readonly recordConstructor: Function;
    
    /** Get field by name */
    field(name: string): Field | undefined;
    
    /** Returns random record object */
    random(): object;
  }
  
  class EnumType extends Type {
    /** Enum symbols */
    readonly symbols: string[];
    
    /** Returns random enum symbol */
    random(): string;
  }
  
  class ArrayType extends Type {
    /** Type of array items */
    readonly itemsType: Type;
    
    /** Returns random array */
    random(): any[];
  }
  
  class MapType extends Type {
    /** Type of map values */
    readonly valuesType: Type;
    
    /** Returns random map object */
    random(): {[key: string]: any};
  }
  
  class FixedType extends Type {
    /** Fixed byte length */
    readonly size: number;
    
    /** Returns random Buffer of fixed size */
    random(): Buffer;
  }
  
  class UnionType extends Type {
    /** Union branch types */
    readonly types: Type[];
    
    /** Returns random union value */
    random(): any;
  }
  
  // Union variants
  class UnwrappedUnionType extends UnionType {
    /** Returns unwrapped union value */
    random(): any;
  }
  
  class WrappedUnionType extends UnionType {
    /** Returns wrapped union value */
    random(): {[branchName: string]: any};
  }
  
  // Special types
  class LogicalType extends Type {
    /** Underlying concrete type */
    readonly underlyingType: Type;
    
    /** Convert from logical to underlying value */
    abstract _fromValue(val: any): any;
    
    /** Convert from underlying to logical value */  
    abstract _toValue(val: any): any;
    
    /** Create resolver for logical type */
    abstract _resolve(type: Type): Function;
    
    /** Export logical type schema */
    abstract _export(attrs: any): any;
  }
}

class Field {
  /** Field name */
  readonly name: string;
  
  /** Field type */
  readonly type: Type;
  
  /** Field aliases */
  readonly aliases: string[];
  
  /** Field documentation */
  readonly doc?: string;
  
  /** Field sort order */
  readonly order?: 'ascending' | 'descending' | 'ignore';
  
  /**
   * Get field default value
   * @returns Default value or undefined if no default
   */
  defaultValue(): any;
}

interface ForSchemaOptions {
  /** Throw error on unknown logical types */
  assertLogicalTypes?: boolean;
  
  /** Custom logical type implementations */
  logicalTypes?: {[type: string]: LogicalTypeConstructor};
  
  /** Default namespace for named types */
  namespace?: string;
  
  /** Disallow anonymous types */
  noAnonymousTypes?: boolean;
  
  /** Omit convenience methods on records */
  omitRecordMethods?: boolean;
  
  /** Type registry for named type resolution */
  registry?: {[name: string]: Type};
  
  /** Hook for custom type creation */
  typeHook?: (schema: any, opts: ForSchemaOptions) => Type | undefined;
  
  /** Union wrapping mode */
  wrapUnions?: boolean | 'auto' | 'always' | 'never';
}

interface CloneOptions {
  /** Coerce buffers to specific type */
  coerceBuffers?: boolean;
  
  /** Hook for field-level transformations */
  fieldHook?: (field: any, value: any, type: Type) => any;
  
  /** Add namespace qualifiers to names */
  qualifyNames?: boolean;
  
  /** Skip fields missing in target schema */
  skipMissingFields?: boolean;
  
  /** Wrap union values */
  wrapUnions?: boolean;
}

interface IsValidOptions {
  /** Disallow undeclared fields in records */
  noUndeclaredFields?: boolean;
  
  /** Hook for validation errors */
  errorHook?: (path: string[], val: any, type: Type) => void;
}

interface SchemaOptions {
  /** Export schema attributes */
  exportAttrs?: boolean;
  
  /** Do not dereference named types */
  noDeref?: boolean;
}

interface LogicalTypeConstructor {
  new (schema: any, opts?: any): LogicalType;
}

interface LongMethods {
  /** Convert to number */
  toNumber?: () => number;
  
  /** Convert to string */
  toString?: () => string;
  
  /** Add operation */
  add?: (other: any) => any;
  
  /** Subtract operation */
  subtract?: (other: any) => any;
  
  /** Compare operation */
  compare?: (other: any) => number;
  
  /** Equal operation */
  equals?: (other: any) => boolean;
}

interface ResolverOptions {
  /** Skip validation during resolution */
  noCheck?: boolean;
  
  /** Coerce types during resolution */
  coerceTypes?: boolean;
}

interface Long {
  /** High 32 bits */
  high: number;
  
  /** Low 32 bits */
  low: number;
  
  /** Whether number is unsigned */
  unsigned: boolean;
  
  /** Convert to number */
  toNumber(): number;
  
  /** Convert to string */
  toString(): string;
}