froebel/range.mjs

TypeScript utility library

import { assert } from "./except.mjs";
/**
 * Constructs a numeric between `start` and `end` inclusively.
 *
 * @param step - The step between items of the list. Must be `> 0` for ascending
 * and `< 0` for descending ranges. Defaults to `1` if ascending and `-1` if
 * descending.
 *
 * @example
 * ```
 * range(2, 6)      // -> [2, 3, 4, 5, 6]
 * range(8, 9, .3)  // -> [8, 8.3, 8.6, 8.9]
 * range(3, -2)     // -> [3, 2, 1, 0, -1, -2]
 * ```
 */

export function numberRange(start, end, step = end > start ? 1 : -1) {
  assert(Math.sign(step) === Math.sign(end - start), "step must be >0 for ascending and <0 descending ranges", RangeError);
  const sequence = [];

  for (let n = start; step > 0 ? n <= end : n >= end; n += step) {
    sequence.push(n);
  }

  return sequence;
}
/**
 * Constructs a range between characters.
 *
 * @example
 * ```
 * range('a', 'd')  // -> ['a', 'b', 'c', 'd']
 * range('Z', 'W')  // -> ['Z', 'Y', 'X', 'W']
 * ```
 */

export function alphaRange(start, end) {
  assert(start.length === 1 && end.length === 1, "alphabetical range can only be constructed between single-character strings", RangeError);
  return numberRange(start.charCodeAt(0), end.charCodeAt(0)).map(n => String.fromCharCode(n));
}

/**
 * Creates a range between two values.
 *
 * @see {@link numberRange}
 * @see {@link alphaRange}
 */
const range = (...args) => (typeof args[0] === "number" ? numberRange : alphaRange)(...args);

export default range;