smikitky / node-multi-integer-range Goto Github PK

Extend this library to support ranges containing zero and negative integers.

Actually the current manipulation methods probably handle negative integers just fine, so the main task is changing the string parser and toString().

When passing a string to the parser, negative integers always have to be contained in parentheses, e.g., (-10),(-3)-(-1),0,2-4. This syntax is obviously cumbersome, but '-5' will eventually be interpreted not as "minus 5" but as an open-ended range that means "all integers <= 5". See #2

String parser should properly throw an error for strings like 9999999999999999999999999. All numbers should be between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER, or we will lose precision.

These constants are not defined in IE, so we will include these numbers in the source for now.

const { multirange } = require('multi-integer-range');

const a = multirange([1,5,7], { parseUnbounded: true });
const b = multirange(a);
console.log(b);

• Expected: b.options.parseUnbounded === true
• Actual: b.options.parseUnbounded === false

• Export as a pure ES module (*.mjs, Node >= 14)
• Drop support for non-ES5-compatible runtimes (i.e., assumes symbols, Array.isArray, etc)
• Stop using a class in favor of function-style API (in the spirit of date-fns, lodash/fp, etc)
• (Option) Adopt immutability?
• Support currying to support "chaining"

Before:

import MultiRange from 'multi-integer-range'; // 4.x
const str = new MultiRange('1-3,8-10')
  .append(5)
  .subtract('10-')
  .toString(); // 1-3,5,8-9

After (using pipeline operators and currying):

import * as mr from 'multi-integer-range'; // 5.x
const str = mr.create('1-3,8-10')
  |> mr.append(5)
  |> mr.subtract('10-')
  |> mr.stringify; // 1-3,5,8-9

Main pros and cons:

• 👍 Smaller bundle size (with tree-shaking)
• 👎 Loss of encapsulation (which was enforced only by TypeScript, anyway)
• 👎 A bit messy code when pipeline operators aren't available
• 👎 Immutability results in a small performance loss

It would be great if there was the ability to get a union and an intersection of two ranges. Something like:

let range1 = new MultiRange('1-2');
let range2 = new MultiRange('2-3,5');
let union = range1.union(range2);
let intersect = range1.intersect(range2);
console.log(union.equals('1-3,5'));
console.log(intersect.equals('2'));

Thank you. Having a numerical range is very helpful with something I'm working on and I'm so glad I don't have to reinvent the wheel.

If you are using this library in your TypeScript project with --target ES6, and use ES6 iterator (for ... of loops, spread operator), then you will encounter a compile-time error. The compiler will say "error TS2488: Type must have a 'Symbol.iterator' method that returns an iterator." The compiled JS file works fine.

import { MultiRange } from 'multi-integer-range';
for (let i of new MultiRange('1-5')) console.log(i); // compile (but not runtime) error!
const arr = [...(new MultiRange('1-5'))]; // compile (but not runtime) error!

This is because the *.d.ts file included in the package is ES5-compatible, and does not have any declarations for ES6 iterators and symbols. To work around this, please add the following somewhere in your --target ES6 project:

declare module "multi-integer-range" {
    interface MultiRange {
        [Symbol.iterator](): Iterator<number>;
    }
}

If you're using TypeScript with --target ES5 flag, don't use for...of loops with MultiRange anyway; TypeScript only supports for...of loops for plain old arrays in ES5 mode.

Steps

• Allow raw bigint values as input (new MultiRange([[555n, 999n]]))
• Add an option to parse strings as bigint

  new MultiRange('999999999999999999', { bigInt: true });
  // Should throw RangeError without bigInt option

• Update type definitions after TypeScript officially supports BigInt

We will not do automatic type conversions to/from plain numbers. You should use use either number or bigint exclusively within a single instance of MultiRange.

• TC39 BigInt proposal (now stage 3): https://github.com/tc39/proposal-bigint
• TypeScript issue: microsoft/TypeScript#15096

Hi,

Could node-multi-integer-range support open-ended ranges?

E.g.

• 0- All integers.
• 10- All integers >= 10.

Methods like toArray would have to be aware of the open-endedness.

Another example is 2.1. Byte Ranges in https://tools.ietf.org/html/rfc7233#page-5.

Due to the recent updates of both TypeScript and multi-integer-range, those who use TypeScript to build your own project may run into compatibility issues.

Here's the summary:

• If you are not using TypeScript in your own project, forget this issue. This library works fine with vanilla JS, Babel, CoffeeScript, etc. (Otherwise please let me know!)
• Regardless of whether you want to enable --strictNullChecks, you need to update your TypeScript to 2.0.x before upgrading this library to 3.0.x. If you want to stay in TypeScript <= 1.8.x for a little longer, feel free to keep using multi-integer-range 2.0.x, which has no known major bugs.
• Regardless of the TypeScript version, do not use ES6 iterator (eg, for-of, spread operator) if your project is --target=es5. Down-level transformation works only with plain arrays.
• Regardless of the TypeScript version, add the snippet in README somewhere in your project if your project is --target=es6 and uses ES6 iterator.

A MultiRange object can hold negative and infinity values by default, but this is not always the intended behavior. We'll introduce an optional parameter to explicitly turn off negative/unbounded ranges on parsing, like so:

// Raises a SyntaxError because negative ranges are turned off
new MultiRange('(-3)-5', { negative: false });

// Raises a SyntaxError because unbounded ranges are turned off
new MultiRange('3-', { unbounded: false });

The passed option will take effect on subsequent chained methods:

// Still raises a SyntaxError
new MultiRange('1-5', { unbounded: false }).append(7).append('10-');

// Even after cloning
new MultiRange('1-5', { unbounded: false }).clone().append('10-');

For performance reasons, this will not take effect when you modify values programmatically (i.e. not using the string parser)

// Does not throw an error
multirange('1-5', { unbounded: false }).add([[10, Infinity]]);

// Does not throw an error
multirange('1-5', { negative: false }).add(-3);