---

Very simple structure with helper methods to define range of values in following scenarios

• from A
• to A
• between A and B

Community

Join our discord server

Installation

1npm install @pallad/range

Usage

Range consists of 3 different interfaces

Range.Start that defines only a start without an end.

1interface Start<T> {
2    start: T
3}

Range.End that defines only an end without a start.

1interface End<T> {
2    end: T;
3}

Range.Full that defines both a start and an end.

1type Full<T> = Start<T> & End<T>

The Range type itself is an union of all of them.

1type Range<T> = Range.Full<T> | Range.Start<T> | Range.End<T>;  

Creating

You can create Range from regular creation function, array or tuple.

Regular create

1// full range
2Range.create(1, 100);
3// start range
4Range.create(1);
5// end range
6Range.create(undefined, 100);

From array or Tuple

1// start range
2Range.fromArray([1])
3// full range
4Range.fromArray([1, 100])
5
6// full range - other values are ignores
7Range.fromArray([1, 100, 1003, 3000])
8// end range
9Range.fromArray([undefined, 100])
10

If creation fails, TypeError is thrown.

1// fails - undefined values
2Range.create(undefined, null)
3
4// fails - start greater than end
5Range.create(100, 1)
6
7// fails - empty array
8Range.fromArray([])
9// fails - undefined values only
10Range.fromArray([undefined, null])

1Range.create(1, 100).value;
2Range.create(null, undefined).value // 'Cannot create Range from undefined or null values'

Enchanted range

Enchanted range is a range object with extra methods. Enchanted object is immutable.

1const enchantedRange = enchant(Range.create(1, 100));
2
3enchantedRange.isWithin(40); // true
4enchantedRange.isWithin(500); // false
5
6enchantedRange.map({
7    start: ({start}) => `from ${start}`,
8    end: ({end}) => `to ${end}`,
9    full: ({start, end}) => `between ${start} and ${end}`
10}); // 'between 1 and 100`
11
12enchantedRange.toTuple(); // [1, 100]

Checking if value is a Range

1Range.is({start: 10}) // true
2Range.is({end: 10}) // true
3Range.is({start: 1, end: 10}) // true

Custom comparator

Boundaries comparison is a crucial feature of Range struct, therefore internally uses @pallad/compare for comparison. Sometimes it is not enough and you can provide your own comparison function.

1Range.create({value: 1}, {value: 100}, (a, b) => a.value - b.value); // no fail
2Range.fromArray([{value: 1}, {value: 100}], (a, b) => a.value - b.value); // no fail

Helper methods

Mapping

Mapping converts range to any other value.

Range.map accepts object with properties named start, end and full where each of it might be a function or any other value. If property value is a function then result of that function gets returned, otherwise it takes the value.

1const range = Range.create(1, 100);
2// mapping to simple values
3Range.map(range, {start: 'start', end: 'end', full: 'full'}) // 'full'
4
5// mapping functions
6enchantedRange.map({
7    start: ({start}) => `from ${start}`,
8    end: ({end}) => `to ${end}`,
9    full: ({start, end}) => `between ${start} and ${end}`
10}); // 'between 1 and 100`

Check if value falls in range

Range.isWithin checks if given values falls in range. Internally uses @pallad/compare so custom comparison functions for value objects are supported.

1Range.isWithin(Range.create(1, 100), 50) // true
2Range.isWithin(Range.create(1, 100), 500) // false

Exclusivity

By default isWithin treats every range as inclusive for both edges. You can change that behavior with second argument.

1const range = Range.create(1, 100);
2
3// exclusivity = false 
4Range.isWithin(range, 100, false) // true 
5Range.isWithin(range, 1, false) // true
6
7// same as above
8Range.isWithin(range, 100) // true 
9Range.isWithin(range, 1) // true 
10
11// exclusivity = true 
12Range.isWithin(range, 100, true) // false
13Range.isWithin(range, 1, true) // false
14
15// start exclusive 
16Range.isWithin(range, 100, {start: true}) // true
17Range.isWithin(range, 1, {start: true}) // false
18
19// end exclusive 
20Range.isWithin(range, 100, {end: true}) // false 
21Range.isWithin(range, 1, {end: true}) // true

Converting a range of a type to another range

1
2Range.convert(Range.create(1, 100), (value) => value + 's'); // Range<string> { start: '1s', end: '100s' }
3Range.convert(Range.create(1), (value) => value + 's'); // Range<string> { start: '1s'}
4Range.convert(Range.create(undefined, q00), (value) => value + 's'); // Range<string> { end: '100s'}

Sometimes you need to map to values that cannot be easily compared, therefore you need to provide custom comparison function to ensure proper creation of new range

1const range = Range.create(2, 100);
2
3// custom comparison function is needed since '2s' > '100s' using regular string comparison
4Range.convert(range, (value) => value + 's', (a, b) => parseInt(a) - parseInt(b));