Range Module

// Import Sugar namespace
import Sugar from "sugar";
// Range class available as Sugar.Range
// Range creation methods available as Sugar.Date.range, Sugar.Number.range, Sugar.String.range

const Sugar = require("sugar");
// Range class available as Sugar.Range
// Range creation methods available via module namespaces
Sugar.Date.range(start, end);
Sugar.Number.range(start, end);
Sugar.String.range(start, end);

/**
 * Creates a range of dates between start and end points
 * @param start - Start date (any format Sugar.Date.create accepts)
 * @param end - End date (any format Sugar.Date.create accepts)
 * @returns Range instance containing dates
 */
function range(start?: any, end?: any): Range;

import Sugar from "sugar";

// Create a date range
const dateRange = Sugar.Date.range('2023-01-01', '2023-12-31');
const thisWeek = Sugar.Date.range('monday', 'sunday');
const nextMonth = Sugar.Date.range('next month', 'end of next month');

/**
 * Creates a range of numbers between start and end points
 * @param start - Starting number (default: 0)
 * @param end - Ending number (default: start value, start becomes 0)
 * @returns Range instance containing numbers
 */
function range(start?: number, end?: number): Range;

import Sugar from "sugar";

// Create number ranges
const oneToTen = Sugar.Number.range(1, 10);
const zeroToFive = Sugar.Number.range(5); // start defaults to 0
const negativeRange = Sugar.Number.range(-5, 5);

/**
 * Creates a range of strings between start and end characters
 * @param start - Starting character or string
 * @param end - Ending character or string
 * @returns Range instance containing strings
 */
function range(start?: string, end?: string): Range;

import Sugar from "sugar";

// Create string ranges
const alphabet = Sugar.String.range('a', 'z');
const numbers = Sugar.String.range('0', '9');
const customRange = Sugar.String.range('aa', 'zz');

/**
 * Range class for creating and manipulating ranges
 * @param start - Starting value of the range
 * @param end - Ending value of the range
 */
class Range {
  constructor(start: any, end: any);
}

/**
 * Constrains an element to fall within the range bounds
 * @param el - Element to clamp to the range
 * @returns Element clamped to range bounds
 */
clamp<T>(el: T): T;

import Sugar from "sugar";

const numberRange = Sugar.Number.range(1, 10);
numberRange.clamp(15); // Returns 10
numberRange.clamp(-5); // Returns 1
numberRange.clamp(5);  // Returns 5

/**
 * Creates a deep copy of the range
 * @returns New Range instance with same bounds
 */
clone(): Range;

/**
 * Tests whether an element falls within the range
 * @param el - Element to test for containment
 * @returns true if element is within range bounds
 */
contains<T>(el: T): boolean;

import Sugar from "sugar";

const dateRange = Sugar.Date.range('2023-01-01', '2023-12-31');
dateRange.contains('2023-06-15'); // true
dateRange.contains('2024-01-01'); // false

const stringRange = Sugar.String.range('a', 'z');
stringRange.contains('m'); // true
stringRange.contains('A'); // false

/**
 * Tests whether the range is valid (start <= end)
 * @returns true if range has valid bounds
 */
isValid(): boolean;

/**
 * Converts the range to an array of all values within the range
 * @returns Array containing all values in the range
 */
toArray<T>(): T[];

import Sugar from "sugar";

Sugar.Number.range(1, 5).toArray(); // [1, 2, 3, 4, 5]
Sugar.String.range('a', 'e').toArray(); // ['a', 'b', 'c', 'd', 'e']

/**
 * Returns a string representation of the range
 * @returns String representation of the range bounds
 */
toString(): string;

/**
 * Returns the intersection of this range with another range
 * @param range - Range to intersect with
 * @returns New Range representing the intersection, or null if no overlap
 */
intersect(range: Range): Range | null;

import Sugar from "sugar";

const range1 = Sugar.Number.range(1, 10);
const range2 = Sugar.Number.range(5, 15);
const intersection = range1.intersect(range2); // Range from 5 to 10

const range3 = Sugar.Number.range(20, 30);
const noOverlap = range1.intersect(range3); // null

/**
 * Returns the union of this range with another range
 * @param range - Range to union with
 * @returns New Range representing the union
 */
union(range: Range): Range;

import Sugar from "sugar";

const range1 = Sugar.Number.range(1, 5);
const range2 = Sugar.Number.range(3, 8);
const union = range1.union(range2); // Range from 1 to 8

const range3 = Sugar.Number.range(10, 15);
const extended = range1.union(range3); // Range from 1 to 15

/**
 * Returns the total span of the range
 * @returns Span value representing range size
 */
span(): any;

/**
 * Iterates over the range with specified intervals
 * @param amount - Step amount (string for dates, number for others)
 * @param everyFn - Function to call for each iteration step
 * @returns Array of results from function calls
 */
every<T>(amount: string | number, everyFn?: (value: any, index: number) => T): T[];

import Sugar from "sugar";

// Iterate over date range by days
const dateRange = Sugar.Date.range('2023-01-01', '2023-01-07');
dateRange.every('day', (date, index) => {
  console.log(`Day ${index + 1}: ${date}`);
});

// Iterate over number range by steps
const numbers = Sugar.Number.range(1, 10);
numbers.every(2, (num, index) => {
  return num * 2; // [2, 6, 10, 14, 18]
});

/**
 * Returns the range span in days
 * @returns Number of days in the range
 */
days(): number;

/**
 * Returns the range span in hours
 * @returns Number of hours in the range
 */
hours(): number;

/**
 * Returns the range span in milliseconds
 * @returns Number of milliseconds in the range
 */
milliseconds(): number;

/**
 * Returns the range span in minutes
 * @returns Number of minutes in the range
 */
minutes(): number;

/**
 * Returns the range span in months
 * @returns Number of months in the range
 */
months(): number;

/**
 * Returns the range span in seconds
 * @returns Number of seconds in the range
 */
seconds(): number;

/**
 * Returns the range span in weeks
 * @returns Number of weeks in the range
 */
weeks(): number;

/**
 * Returns the range span in years
 * @returns Number of years in the range
 */
years(): number;

import Sugar from "sugar";

const dateRange = Sugar.Date.range('2023-01-01', '2023-12-31');
dateRange.days();    // 365
dateRange.hours();   // 8760
dateRange.months();  // 12
dateRange.years();   // 1

const shortRange = Sugar.Date.range('today', 'tomorrow');
shortRange.days();   // 1
shortRange.hours();  // 24

/**
 * Range class for creating ranges of dates, numbers, or strings
 */
class Range {
  constructor(start: any, end: any);
  
  // Core operations
  clamp<T>(el: T): T;
  clone(): Range;
  contains<T>(el: T): boolean;
  isValid(): boolean;
  
  // Conversion
  toArray<T>(): T[];
  toString(): string;
  
  // Set operations
  intersect(range: Range): Range | null;
  union(range: Range): Range;
  span(): any;
  
  // Iteration
  every<T>(amount: string | number, everyFn?: (value: any, index: number) => T): T[];
  
  // Date-specific methods (available when range contains dates)
  days(): number;
  hours(): number;
  milliseconds(): number;
  minutes(): number;
  months(): number;
  seconds(): number;
  weeks(): number;
  years(): number;
}