Configuration Options

/**
 * Configuration options for CSV generation
 * Extends Node.js stream.ReadableOptions for full stream compatibility
 */
interface Options extends stream.ReadableOptions {
  /** Define the number of generated fields and the generation method */
  columns?: number | (string | ColumnsFunction)[];
  /** Set the field delimiter */
  delimiter?: string;
  /** Period to run in milliseconds */
  duration?: number;
  /** If specified, then buffers will be decoded to strings using the specified encoding */
  encoding?: BufferEncoding | undefined;
  /** When to stop the generation */
  end?: number | Date;
  /** One or multiple characters to print at the end of the file; only apply when objectMode is disabled */
  eof?: boolean | string;
  /** Generate buffers equals length as defined by the `highWaterMark` option */
  fixed_size?: boolean;
  fixedSize?: boolean;
  /** The maximum number of bytes to store in the internal buffer before ceasing to read from the underlying resource */
  high_water_mark?: number;
  highWaterMark?: number;
  /** Number of lines or records to generate */
  length?: number;
  /** Maximum number of characters per word */
  max_word_length?: number;
  maxWordLength?: number;
  /** Whether this stream should behave as a stream of objects */
  object_mode?: boolean;
  objectMode?: boolean;
  /** One or multiple characters used to delimit records */
  row_delimiter?: string;
  /** Generate idempotent random characters if a number provided */
  seed?: boolean | number;
  /** The time to wait between the generation of each records */
  sleep?: number;
}

/**
 * Column configuration options
 */
columns?: number | (string | ColumnsFunction)[];

/**
 * Built-in column types
 */
type ColumnType = 'ascii' | 'int' | 'bool';

/**
 * Custom column generation function
 * Must return string, number, or null - other types throw INVALID_VALUE error
 */
type ColumnsFunction = (args: ColumnsFunctionArgs) => string | number | null;

interface ColumnsFunctionArgs {
  options: Options;
  state: State;
}

// Number of columns (generates 'ascii' type by default)
const generator = generate({ columns: 5 });

// Mixed built-in types
const generator = generate({
  columns: ['ascii', 'int', 'bool', 'ascii', 'int']
});

// Custom column functions
const generator = generate({
  columns: [
    'ascii',                          // Built-in type
    ({ state }) => state.count_created.toString(),  // Record number
    () => new Date().toISOString(),   // Current timestamp
    ({ options }) => Math.random() < 0.5 ? 'A' : 'B'  // Random choice
  ]
});

// Generate email-like data
const generator = generate({
  columns: [
    ({ state }) => `user${state.count_created}`,     // Username
    () => '@',                                       // Separator
    ({ options }) => 'example.com'                   // Domain
  ],
  delimiter: '',  // No delimiter between fields
  objectMode: true
});

/** Field delimiter (default: ",") */
delimiter?: string;

/** Record delimiter (default: "\n") */
row_delimiter?: string;

/** End-of-file marker */
eof?: boolean | string;

/** Object mode for array output instead of CSV strings */
object_mode?: boolean;
objectMode?: boolean;

/** Text encoding for string output */
encoding?: BufferEncoding | undefined;

// Custom delimiters
const tsvGenerator = generate({
  columns: 3,
  length: 5,
  delimiter: '\t',        // Tab-separated values
  row_delimiter: '\r\n'   // Windows line endings
});

// End-of-file marker
const generator = generate({
  columns: 2,
  length: 3,
  eof: true  // Adds row delimiter at end
});

// Custom EOF marker
const generator = generate({
  columns: 2,
  length: 3,
  eof: '\n--- END ---\n'
});

// Object mode output
const objectGenerator = generate({
  columns: ['ascii', 'int'],
  length: 3,
  objectMode: true  // Returns arrays instead of CSV strings
});

/** Number of records to generate */
length?: number;

/** Maximum runtime in milliseconds */
duration?: number;

/** End generation at specific date/time */
end?: number | Date;

/** Delay between records in milliseconds */
sleep?: number;

// Generate specific number of records
const generator = generate({
  columns: 3,
  length: 100  // Exactly 100 records
});

// Time-based generation
const generator = generate({
  columns: 2,
  duration: 5000  // Generate for 5 seconds
});

// End at specific time
const generator = generate({
  columns: 2,
  end: new Date('2024-12-31T23:59:59Z')
});

// Throttled generation
const generator = generate({
  columns: 3,
  length: 10,
  sleep: 100  // 100ms delay between records
});

/** Seed for deterministic random generation */
seed?: boolean | number;

/** Maximum word length for ascii columns */
max_word_length?: number;
maxWordLength?: number;

// Deterministic generation with seed
const generator1 = generate({
  columns: 3,
  length: 5,
  seed: 12345  // Same seed = same output
});

const generator2 = generate({
  columns: 3,
  length: 5,
  seed: 12345  // Identical output to generator1
});

// Control word length
const generator = generate({
  columns: ['ascii', 'ascii'],
  length: 3,
  maxWordLength: 5,  // ASCII strings max 5 characters
  seed: 1
});

// Disable seeding (use true random)
const randomGenerator = generate({
  columns: 2,
  length: 5,
  seed: false  // Different output each run
});

/** Stream buffer size */
high_water_mark?: number;
highWaterMark?: number;

/** Generate fixed-size buffers */
fixed_size?: boolean;
fixedSize?: boolean;

// Large buffer for better performance
const generator = generate({
  columns: 10,
  length: 1000,
  highWaterMark: 64 * 1024  // 64KB buffer
});

// Fixed-size buffer generation
const generator = generate({
  columns: 5,
  length: 100,
  fixedSize: true,
  highWaterMark: 1024  // Generates exactly 1024-byte chunks
});

// Small buffer for memory-constrained environments
const generator = generate({
  columns: 2,
  length: 1000,
  highWaterMark: 1024  // 1KB buffer
});

// These pairs are equivalent:
fixed_size: true     ↔ fixedSize: true
high_water_mark: 1024 ↔ highWaterMark: 1024
max_word_length: 10  ↔ maxWordLength: 10
object_mode: true    ↔ objectMode: true
row_delimiter: '\n'  ↔ rowDelimiter: '\n'  // Note: rowDelimiter not available, only row_delimiter

// Both styles work identically
const generator1 = generate({
  object_mode: true,
  max_word_length: 8,
  high_water_mark: 2048
});

const generator2 = generate({
  objectMode: true,
  maxWordLength: 8,
  highWaterMark: 2048
});
// generator1 and generator2 behave identically

// Configuration validation errors
throw Error(`Invalid column type: got "${type}", default values are ["ascii", "int", "bool"]`);

// Runtime validation errors  
throw Error(`INVALID_VALUE: values returned by column function must be a string, a number or null, got ${JSON.stringify(value)}`);

// Invalid column type throws error
try {
  const generator = generate({
    columns: ['ascii', 'invalid-type'], // Error: Invalid column type
    length: 5
  });
} catch (error) {
  console.error(error.message);
  // "Invalid column type: got "invalid-type", default values are ["ascii","int","bool"]"
}

// Invalid column function return value throws error  
const generator = generate({
  columns: [
    () => ({ invalid: 'object' })  // Error: must return string, number, or null
  ],
  length: 1
});

generator.on('error', (error) => {
  console.error(error.message);
  // "INVALID_VALUE: values returned by column function must be a string, a number or null, got {"invalid":"object"}"
});