fill-range

const fill = require('fill-range');

import fill from 'fill-range';

const fill = require('fill-range');

// Generate number ranges
console.log(fill(1, 5));         // => [1, 2, 3, 4, 5]
console.log(fill('1', '5'));     // => [1, 2, 3, 4, 5]

// Generate letter ranges
console.log(fill('a', 'e'));     // => ['a', 'b', 'c', 'd', 'e']
console.log(fill('A', 'E'));     // => ['A', 'B', 'C', 'D', 'E']

// Generate ranges with step increments
console.log(fill(1, 10, 2));     // => [1, 3, 5, 7, 9]
console.log(fill('a', 'z', 5));  // => ['a', 'f', 'k', 'p', 'u', 'z']

// Generate regex patterns
console.log(fill(2, 10, { toRegex: true })); // => '[2-9]|10'

/**
 * Fill in a range of numbers or letters, optionally passing an increment or step to use, or create a regex-compatible range with options.toRegex
 * @param {string|number} start - The number or letter to start with
 * @param {string|number} [end] - The number or letter to end with
 * @param {string|number|object|function} [step] - Step increment, options object, or transform function
 * @param {object} [options] - Configuration options
 * @returns {array|string} Array of values or regex string when toRegex is true
 */
function fill(start, end, step, options);

// Function overloads
function fill(start); // Single value
function fill(start, end); // Range with default step
function fill(start, end, step); // Range with custom step
function fill(start, end, transform); // Range with transform function
function fill(start, end, options); // Range with options object
function fill(start, end, step, options); // Full signature

// Numeric ranges
fill(1, 5);              // => [1, 2, 3, 4, 5]
fill(-3, 3);             // => [-3, -2, -1, 0, 1, 2, 3]
fill('001', '005');      // => ['001', '002', '003', '004', '005'] (zero-padded)

// Alphabetic ranges
fill('a', 'e');          // => ['a', 'b', 'c', 'd', 'e']
fill('Z', 'A');          // => ['Z', 'Y', 'X', 'W', 'V', 'U', 'T', 'S', 'R', 'Q', 'P', 'O', 'N', 'M', 'L', 'K', 'J', 'I', 'H', 'G', 'F', 'E', 'D', 'C', 'B', 'A']

// With step increments
fill(0, 25, 5);          // => [0, 5, 10, 15, 20, 25]
fill('a', 'z', 4);       // => ['a', 'e', 'i', 'm', 'q', 'u', 'y']

// Single value
fill('x');               // => ['x']

interface FillOptions {
  /** Cast all returned values to strings (default: undefined) */
  stringify?: boolean;
  
  /** Throw RangeError on invalid ranges instead of returning empty array (default: false) */
  strictRanges?: boolean;
  
  /** Create regex-compatible string instead of array (default: undefined) */
  toRegex?: boolean;
  
  /** Wrap regex output in parentheses, requires toRegex: true (default: undefined) */
  wrap?: boolean;
  
  /** Enable capturing groups in regex output, requires toRegex: true (default: undefined) */
  capture?: boolean;
  
  /** Force strict zero padding in regex patterns, requires toRegex: true (default: undefined) */
  strictZeros?: boolean;
  
  /** Step increment for the range (default: 1) */
  step?: number;
  
  /** Custom transform function for each value (default: undefined) */
  transform?: (value: any, index: number) => any;
}

// String output control
fill(1, 5, { stringify: true });    // => ['1', '2', '3', '4', '5']

// Regex generation
fill(2, 8, { toRegex: true });      // => '[2-8]'
fill(2, 10, { toRegex: true });     // => '[2-9]|10'
fill('a', 'e', { toRegex: true });  // => '[a-e]'

// Regex with wrapping and capturing
fill(2, 10, { toRegex: true, wrap: true });    // => '(?:[2-9]|10)'
fill(2, 10, { toRegex: true, capture: true }); // => '([2-9]|10)'

// Custom step
fill(1, 10, { step: 3 });           // => [1, 4, 7, 10]

// Custom transformation
fill(1, 5, { transform: val => String(val).padStart(3, '0') }); 
// => ['001', '002', '003', '004', '005']

// Strict error handling
fill('1.1', '2', { strictRanges: true }); // throws RangeError

// Complex regex examples - these are return values, not function signatures
// Use fill() with toRegex: true to generate these patterns

// Zero-padded numeric ranges  
fill('002', '008', { toRegex: true });     // => '0{0,2}[2-8]'
fill('02', '10', { toRegex: true });       // => '0?[2-9]|10'

// Strict zero padding
fill('03', '01', { toRegex: true, strictZeros: true }); // => '0[1-3]'
fill('001', '020', { toRegex: true, strictZeros: true }); // => '00[1-9]|01[0-9]|020'

// Negative number ranges
fill(-10, 10, { toRegex: true });          // => '-[1-9]|-?10|[0-9]'
fill(-10, -2, 2, { toRegex: true });       // => '-(?:2|4|6|8|10)'

// Step-based regex patterns
fill(2, 8, { toRegex: true, step: 2 });    // => '2|4|6|8'
fill('a', 'z', 3, { toRegex: true });      // => 'a|d|g|j|m|p|s|v|y'

// Generate regex for form validation
const agePattern = fill(18, 99, { toRegex: true });
const regex = new RegExp(`^${agePattern}$`);

// Generate regex for alphanumeric codes
const codePattern = fill('A', 'Z', { toRegex: true });
console.log(codePattern); // => '[A-Z]'

// Complex numeric patterns with padding
const paddedPattern = fill('001', '100', { toRegex: true });
// => '0{0,2}[1-9]|0?[1-9][0-9]|100'

/**
 * Custom transform function signature
 * @param {any} value - Current value in the range  
 * @param {number} index - Zero-based index of current value
 * @returns {any} Transformed value
 */
type TransformFunction = (value: any, index: number) => any;

// Transform function as third parameter
fill(1, 5, value => String(value).padStart(2, '0'));
// => ['01', '02', '03', '04', '05']

// Transform function in options
fill(1, 5, { transform: (val, idx) => `item-${val}-${idx}` });
// => ['item-1-0', 'item-2-1', 'item-3-2', 'item-4-3', 'item-5-4']

// Complex transformations
fill('a', 'e', { 
  transform: (char, index) => ({
    letter: char,
    code: char.charCodeAt(0),
    position: index + 1
  })
});
// => [
//   { letter: 'a', code: 97, position: 1 },
//   { letter: 'b', code: 98, position: 2 },
//   ...
// ]

// Default behavior - returns empty array for invalid ranges
fill('1.1', '2');        // => [] (decimals not supported)
fill('a', '2');          // => [] (incompatible range values)  
fill(1, 10, 'foo');      // => [] (invalid step argument)

// Strict mode - throws RangeError or TypeError
fill('1.1', '2', { strictRanges: true });   // throws RangeError
fill(1, 10, 'foo', { strictRanges: true }); // throws TypeError