Utility Functions

// Access utilities from main module (not typically needed)
const utils = require('avro-js/lib/utils');
const { Lcg, Tap, OrderedQueue } = utils;

/**
 * Linear congruential generator for deterministic random data generation
 * @param {number} seed - Optional seed value for reproducible sequences
 */
class Lcg {
  constructor(seed);
  
  /**
   * Generate random boolean value
   * @returns {boolean} Random boolean
   */
  nextBoolean();
  
  /**
   * Generate random integer within range
   * @param {number} start - Start of range (inclusive), or end if end undefined
   * @param {number} end - End of range (exclusive)
   * @returns {number} Random integer
   */
  nextInt(start, end);
  
  /**
   * Generate random float within range
   * @param {number} start - Start of range (inclusive), or end if end undefined
   * @param {number} end - End of range (exclusive)
   * @returns {number} Random float
   */
  nextFloat(start, end);
  
  /**
   * Generate random string with specified length and character set
   * @param {number} len - Length of string to generate
   * @param {string} flags - Character set flags ('a'=lowercase, 'A'=uppercase, '#'=digits, '!'=symbols)
   * @returns {string} Random string
   */
  nextString(len, flags);
  
  /**
   * Generate random buffer with specified byte length
   * @param {number} len - Number of bytes to generate
   * @returns {Buffer} Random buffer
   */
  nextBuffer(len);
  
  /**
   * Choose random element from array or string
   * @param {Array|string} arr - Array or string to choose from
   * @returns {*} Random element
   */
  choice(arr);
}

const { Lcg } = require('avro-js/lib/utils');

// Create seeded generator for reproducible results
const rng = new Lcg(12345);

// Generate random data
const randomBool = rng.nextBoolean();
const randomInt = rng.nextInt(1, 100);  // 1-99
const randomFloat = rng.nextFloat(0, 1); // 0.0-1.0
const randomStr = rng.nextString(10, 'aA#'); // alphanumeric, 10 chars
const randomBytes = rng.nextBuffer(16); // 16 random bytes
const choice = rng.choice(['red', 'green', 'blue']);

/**
 * Ordered queue for managing indexed items that must be retrieved consecutively
 */
class OrderedQueue {
  constructor();
  
  /**
   * Add item with index to queue
   * @param {Object} item - Item with 'index' property
   */
  push(item);
  
  /**
   * Retrieve next consecutive item from queue
   * @returns {Object|null} Next item in sequence, or null if not available
   */
  pop();
}

const { OrderedQueue } = require('avro-js/lib/utils');

const queue = new OrderedQueue();

// Add items out of order
queue.push({ index: 2, data: 'second' });
queue.push({ index: 0, data: 'first' });
queue.push({ index: 1, data: 'middle' });

// Retrieve in order
console.log(queue.pop()); // { index: 0, data: 'first' }
console.log(queue.pop()); // { index: 1, data: 'middle' }
console.log(queue.pop()); // { index: 2, data: 'second' }

/**
 * Buffer reading/writing abstraction with position tracking
 * @param {Buffer} buf - Buffer to operate on
 * @param {number} pos - Starting position (default: 0)
 */
class Tap {
  constructor(buf, pos);
  
  /**
   * Check if tap is in valid state (no buffer overflow)
   * @returns {boolean} True if position is within buffer bounds
   */
  isValid();
  
  /**
   * Get buffer contents up to current position
   * @returns {Buffer} Buffer slice from start to current position
   */
  getValue();
  
  // Boolean operations
  readBoolean();
  skipBoolean();
  writeBoolean(b);
  
  // Integer operations (Avro zigzag encoding)
  readInt();
  readLong();
  skipInt();
  skipLong();
  writeInt(n);
  writeLong(n);
  
  // Float operations
  readFloat();
  skipFloat();
  writeFloat(f);
  readDouble();
  skipDouble();
  writeDouble(d);
  
  // Fixed-length data
  readFixed(len);
  skipFixed(len);
  writeFixed(buf, len);
  
  // Variable-length data
  readBytes();
  skipBytes();
  writeBytes(buf);
  readString();
  skipString();
  writeString(s);
  
  // Binary comparison methods
  matchBoolean(tap);
  matchInt(tap);
  matchLong(tap);
  matchFloat(tap);
  matchDouble(tap);
  matchFixed(tap, len);
  matchBytes(tap);
  matchString(tap);
  
  // Long integer support
  unpackLongBytes();
  packLongBytes(buf);
}

/**
 * Capitalize first letter of string
 * @param {string} s - String to capitalize
 * @returns {string} Capitalized string
 */
function capitalize(s);

/**
 * Compare two numbers
 * @param {number} n1 - First number
 * @param {number} n2 - Second number
 * @returns {number} -1, 0, or 1 for less than, equal, or greater than
 */
function compare(n1, n2);

/**
 * Compute hash of string
 * @param {string} str - String to hash
 * @param {string} algorithm - Hash algorithm (default: 'md5')
 * @returns {Buffer} Hash bytes
 */
function getHash(str, algorithm);

/**
 * Find single index of value in array
 * @param {Array} arr - Array to search
 * @param {*} v - Value to find
 * @returns {number} Index if found once, -1 if not found, -2 if found multiple times
 */
function singleIndexOf(arr, v);

/**
 * Convert array to map using key function
 * @param {Array} arr - Array of elements
 * @param {Function} fn - Function to extract key from element
 * @returns {Object} Map of key to element
 */
function toMap(arr, fn);

/**
 * Check if array has duplicate values
 * @param {Array} arr - Array to check
 * @param {Function} fn - Optional function to extract comparison value
 * @returns {boolean} True if duplicates found
 */
function hasDuplicates(arr, fn);

/**
 * Abstract function placeholder (throws error when called)
 * @throws {Error} Always throws "abstract" error
 */
function abstractFunction();

const utils = require('avro-js/lib/utils');

// String operations
const capitalized = utils.capitalize('hello'); // 'Hello'
const hash = utils.getHash('test data', 'sha256');

// Array operations
const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
const userMap = utils.toMap(users, u => u.id);
// Result: { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } }

const hasDupes = utils.hasDuplicates([1, 2, 2, 3]); // true
const uniqueIndex = utils.singleIndexOf([1, 2, 3], 2); // 1

const { Tap } = require('avro-js/lib/utils');

// Create tap for writing
const writeBuf = Buffer.alloc(100);
const writeTap = new Tap(writeBuf, 0);

// Write Avro-encoded data
writeTap.writeInt(12345);
writeTap.writeString('hello world');
writeTap.writeDouble(3.14159);

if (!writeTap.isValid()) {
  throw new Error('Buffer overflow during write');
}

// Create tap for reading
const readBuf = writeTap.getValue();
const readTap = new Tap(readBuf, 0);

// Read back the data
const number = readTap.readInt();       // 12345
const text = readTap.readString();      // 'hello world'  
const pi = readTap.readDouble();        // 3.14159