CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-moment-range

Fancy date ranges for Moment.js with comprehensive range operations and iteration capabilities

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

range-iteration.mddocs/

Range Iteration

Iterate over ranges using various time intervals with customizable options for step size and boundary inclusion using ES6 iterator protocol.

Capabilities

By Interval (Forward)

Iterate forward through the range by a specified time interval.

/**
 * Create forward iterator over range by time interval
 * @param interval - Time unit to iterate by
 * @param options - Iteration options
 * @returns Iterable that yields Moment objects
 */
by(interval: IntervalUnit, options?: IterationOptions): Iterable<Moment>;

interface IterationOptions {
  excludeEnd?: boolean; // Exclude the end boundary from iteration
  step?: number;        // Step size (default: 1)
  exclusive?: boolean;  // DEPRECATED: Use excludeEnd instead
}

type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';

Usage Examples:

const range = moment.range('2024-01-01', '2024-01-05');

// Basic iteration by day
for (const day of range.by('day')) {
  console.log(day.format('YYYY-MM-DD'));
}
// Output: 2024-01-01, 2024-01-02, 2024-01-03, 2024-01-04, 2024-01-05

// Exclude end boundary
for (const day of range.by('day', { excludeEnd: true })) {
  console.log(day.format('YYYY-MM-DD'));
}
// Output: 2024-01-01, 2024-01-02, 2024-01-03, 2024-01-04

// Step by 2 days
for (const day of range.by('day', { step: 2 })) {
  console.log(day.format('YYYY-MM-DD'));
}
// Output: 2024-01-01, 2024-01-03, 2024-01-05

// Convert to array
const days = Array.from(range.by('day'));
console.log(days.length); // 5

// Iterate by hours
const hourRange = moment.range('2024-01-01T00:00:00', '2024-01-01T06:00:00');
for (const hour of hourRange.by('hour')) {
  console.log(hour.format('HH:mm'));
}
// Output: 00:00, 01:00, 02:00, 03:00, 04:00, 05:00, 06:00

By Range (Forward)

Iterate forward through the range using another range as the step interval.

/**
 * Create forward iterator over range using another range as step interval  
 * @param interval - DateRange defining the step size
 * @param options - Iteration options
 * @returns Iterable that yields Moment objects
 */
byRange(interval: DateRange, options?: IterationOptions): Iterable<Moment>;

Usage Examples:

const range = moment.range('2024-01-01', '2024-01-31');

// Step by week intervals
const weekInterval = moment.range('2024-01-01', '2024-01-07'); // 7-day range
for (const start of range.byRange(weekInterval)) {
  console.log(start.format('YYYY-MM-DD'));
}
// Output: 2024-01-01, 2024-01-08, 2024-01-15, 2024-01-22, 2024-01-29

// Step by 3-day intervals
const threeDayInterval = moment.range('2024-01-01', '2024-01-03');
for (const start of range.byRange(threeDayInterval, { step: 2 })) {
  console.log(start.format('YYYY-MM-DD'));
}
// Output: Every 6 days (3-day interval * step 2)

// Custom business day range
const businessWeek = moment.range('2024-01-01', '2024-01-05'); // Mon-Fri
for (const weekStart of range.byRange(businessWeek)) {
  console.log(`Week starting: ${weekStart.format('YYYY-MM-DD')}`);
}

Reverse By Interval

Iterate backward through the range by a specified time interval.

/**
 * Create reverse iterator over range by time interval
 * @param interval - Time unit to iterate by
 * @param options - Reverse iteration options
 * @returns Iterable that yields Moment objects in reverse order
 */
reverseBy(interval: IntervalUnit, options?: ReverseIterationOptions): Iterable<Moment>;

interface ReverseIterationOptions {
  excludeStart?: boolean; // Exclude the start boundary from iteration
  step?: number;          // Step size (default: 1)
  exclusive?: boolean;    // DEPRECATED: Use excludeStart instead
}

Usage Examples:

const range = moment.range('2024-01-01', '2024-01-05');

// Basic reverse iteration by day
for (const day of range.reverseBy('day')) {
  console.log(day.format('YYYY-MM-DD'));
}
// Output: 2024-01-05, 2024-01-04, 2024-01-03, 2024-01-02, 2024-01-01

// Exclude start boundary
for (const day of range.reverseBy('day', { excludeStart: true })) {
  console.log(day.format('YYYY-MM-DD'));
}
// Output: 2024-01-05, 2024-01-04, 2024-01-03, 2024-01-02

// Step by 2 days backwards
for (const day of range.reverseBy('day', { step: 2 })) {
  console.log(day.format('YYYY-MM-DD'));
}
// Output: 2024-01-05, 2024-01-03, 2024-01-01

// Reverse iterate by hours
const hourRange = moment.range('2024-01-01T00:00:00', '2024-01-01T06:00:00');
for (const hour of hourRange.reverseBy('hour')) {
  console.log(hour.format('HH:mm'));
}
// Output: 06:00, 05:00, 04:00, 03:00, 02:00, 01:00, 00:00

Reverse By Range

Iterate backward through the range using another range as the step interval.

/**
 * Create reverse iterator over range using another range as step interval
 * @param interval - DateRange defining the step size
 * @param options - Reverse iteration options  
 * @returns Iterable that yields Moment objects in reverse order
 */
reverseByRange(interval: DateRange, options?: ReverseIterationOptions): Iterable<Moment>;

Usage Examples:

const range = moment.range('2024-01-01', '2024-01-31');

// Reverse step by week intervals
const weekInterval = moment.range('2024-01-01', '2024-01-07');
for (const start of range.reverseByRange(weekInterval)) {
  console.log(start.format('YYYY-MM-DD'));
}
// Output: 2024-01-31, 2024-01-24, 2024-01-17, 2024-01-10, 2024-01-03

// Combine with array methods
const monthStarts = Array.from(range.reverseByRange(weekInterval))
  .map(moment => moment.format('YYYY-MM-DD'))
  .slice(0, 3); // Take first 3
console.log(monthStarts); // Last 3 week starts in reverse order

Iteration Helpers

Utility methods for working with iterators.

Usage Examples:

const range = moment.range('2024-01-01', '2024-01-10');

// Convert iterator to array
const allDays = Array.from(range.by('day'));
console.log(allDays.length); // 10

// Use with array methods
const weekends = Array.from(range.by('day'))
  .filter(day => day.day() === 0 || day.day() === 6) // Sunday or Saturday
  .map(day => day.format('YYYY-MM-DD'));

// Count iterations without storing
let count = 0;
for (const day of range.by('day')) {
  count++;
}
console.log(`Range spans ${count} days`);

// Find specific dates
const businessDays = Array.from(range.by('day'))
  .filter(day => day.day() >= 1 && day.day() <= 5); // Monday-Friday

// Break early from iteration
for (const day of range.by('day')) {
  console.log(day.format('YYYY-MM-DD'));
  if (day.format('DD') === '05') break; // Stop at 5th day
}

Edge Cases and Performance

Handle special cases and optimize performance.

Usage Examples:

// Infinite ranges
const infiniteRange = moment.range(null, null);
// Iteration will throw or return empty iterator - check implementation

// Zero-length ranges
const zeroRange = moment.range('2024-01-01', '2024-01-01');
const zeroIterations = Array.from(zeroRange.by('day'));
console.log(zeroIterations.length); // 1 (includes the single day)

// Large step sizes
const yearRange = moment.range('2020-01-01', '2030-01-01');
for (const year of yearRange.by('year', { step: 2 })) {
  console.log(year.format('YYYY')); // Every 2 years
}

// Very small intervals
const minuteRange = moment.range('2024-01-01T00:00:00', '2024-01-01T01:00:00');
const minutes = Array.from(minuteRange.by('minute'));
console.log(minutes.length); // 61 minutes (includes both boundaries)

Types

interface IterationOptions {
  excludeEnd?: boolean;
  step?: number;
  exclusive?: boolean; // DEPRECATED
}

interface ReverseIterationOptions {
  excludeStart?: boolean;
  step?: number;
  exclusive?: boolean; // DEPRECATED
}

type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';

// Iterator interface (ES6 Standard)
interface Iterator<T> {
  next(): IteratorResult<T>;
}

interface IteratorResult<T> {
  done: boolean;
  value: T;
}

interface Iterable<T> {
  [Symbol.iterator](): Iterator<T>;
}

docs

index.md

moment-extensions.md

range-creation.md

range-iteration.md

range-manipulation.md

range-querying.md

tile.json