fix(Array): range fn based on the iterator range proposal

Author: Thanga-Ganapathy

.changeset/beige-turkeys-repeat.md

@@ -0,0 +1,5 @@
+---
+"@opentf/utils": minor
+---
+
+Fixed range fn based on the iterator range proposal.

apps/docs/pages/Array/range.mdx

@@ -1,57 +1,73 @@
+import { Callout } from "nextra/components";
 import REPL from "../../components/REPL";
 
-> It generates a sequence of numbers starting at the first argument, progressing by the third argument, and stopping at the second argument.
+> Generates a sequence of numbers starting at the `first` argument, progressing by the `step` argument, and stopping at the `second` argument.
+
+<Callout emoji="✅" type="info">
+It is based on the [Range proposal](https://tc39.es/proposal-iterator.range/) & [Iterator.range](https://github.com/tc39/proposal-iterator.range).
+</Callout>
 
 ## Syntax
 
 ```ts
-range(start: number, stop: number, step?: number): number[];
+range(
+  start: number,
+  end: number,
+  options?: number | { step: number; inclusive: false }
+): number[]
 ```
+
+<Callout type="info">
+The `step` value can be auto infered based on the `start` & `end` values.
+</Callout>
+
+<Callout type="info">
+The `third` argument can be either a `step` value or `options` object.
+</Callout>
+
 ## Usage
 
 ```ts
 import { range } from '@opentf/utils';
 
-range();
+range(start, stop);
 ```
 
 ## Examples
 
 ```ts
-range() //=> []
-
-range(0) //=> []
+range() // It throws error
 
-range(1) //=> []
+range(0) // It throws error
 
-range(1, 2) //=> [1, 2]
+range(NaN, 0) // It throws error
 
-range(10, 50, 10) //=> [10, 20, 30, 40, 50]
+range(0, 0) //=> []
 
-range(10, 12, 0.5) //=> [10, 10.5, 11, 11.5, 12]
+range(0, 0, { inclusive: true }) //=> [0]
 
-range(-10, -5) //=> [-10, -9, -8, -7, -6, -5]
+range(0, 5) //=> [0, 1, 2, 3, 4]
 
-range(0, -4, -1) //=> [0, -1, -2, -3, -4]
+range(0, 5, { inclusive: true }) //=> [0, 1, 2, 3, 4, 5]
 
-range(-4) //=> []
+range(3, 9, { step: 3 }) //=> [3, 6]
 
-range(1, 2, 0) //=> []
+range(0, -5) //=> [0, -1, -2, -3, -4]
 
-range(-1, -2, 1) //=> []
+range(0, -4, { step: -1 }) //=> [0, -1, -2, -3]
 
-range(-1, -2, -1) //=> [-1, -2]
-
-range(1, 2, 1) //=> [1, 2]
-
-range(0, 5) //=> [0, 1, 2, 3, 4, 5]
-
-range(3, 9, 3) //=> [3, 6, 9]
+range(-10, -5) //=> [-10, -9, -8, -7, -6]
 
+range(10, 12, { step: 0.5 }) //=> [10, 10.5, 11, 11.5]
 ```
 
 ## Try
 
 <REPL code={`const { range } = require('@opentf/utils');
 
-range(1, 5);`} />
+log(range(1, 5));
+
+for (const item of range(1, 5, {inclusive: true})) {
+  log(item);
+}
+`} />

packages/utils/__tests__/array/range.spec.js

@@ -1,21 +1,104 @@
 import { range } from '../../src';
 
-describe('Array', () => {
-  test('range', () => {
-    expect(range()).toEqual([]);
-    expect(range(0)).toEqual([]);
-    expect(range(1)).toEqual([]);
-    expect(range(1, 2)).toEqual([1, 2]);
-    expect(range(10, 50, 10)).toEqual([10, 20, 30, 40, 50]);
-    expect(range(10, 12, 0.5)).toEqual([10, 10.5, 11, 11.5, 12]);
-    expect(range(-10, -5)).toEqual([-10, -9, -8, -7, -6, -5]);
-    expect(range(0, -4, -1)).toEqual([0, -1, -2, -3, -4]);
-    expect(range(-4)).toEqual([]);
-    expect(range(1, 2, 0)).toEqual([]);
-    expect(range(-1, -2, 1)).toEqual([]);
-    expect(range(-1, -2, -1)).toEqual([-1, -2]);
-    expect(range(1, 2, 1)).toEqual([1, 2]);
-    expect(range(0, 5)).toEqual([0, 1, 2, 3, 4, 5]);
-    expect(range(3, 9, 3)).toEqual([3, 6, 9]);
+describe('Array > range', () => {
+  test('Error handling: Type Mismatch', () => {
+    const sharedMatrix = [
+      [],
+      [0],
+      [0n],
+      [0, 1, function () {}],
+      [0n, 1n, function () {}],
+      [0, function () {}, 2],
+      [function () {}, 2, 2],
+      [0n, 1],
+      [0n, 1, 1],
+      [0n, 1, { step: 1 }],
+      [0, 1n],
+      [0, 1n, 1],
+      [0, 1n, { step: 1 }],
+      [0, 1, 1n],
+      [0, 1, { step: 1n }],
+    ];
+    for (const each of sharedMatrix) {
+      expect(() => range(...each)).toThrowError();
+    }
+  });
+
+  test('empty', () => {
+    expect(range(0, 0)).toEqual([]);
+    expect(range(0, -5, 1)).toEqual([]);
+  });
+
+  test('positive integers', () => {
+    expect(range(0, 5)).toEqual([0, 1, 2, 3, 4]);
+    expect(range(1, 2)).toEqual([1]);
+    expect(range(1, 2, { step: 1 })).toEqual([1]);
+    expect(range(10, 50, { step: 10 })).toEqual([10, 20, 30, 40]);
+    expect(range(10, 50, 10)).toEqual([10, 20, 30, 40]);
+    expect(range(3, 9, { step: 3 })).toEqual([3, 6]);
+  });
+
+  test('negative integers', () => {
+    expect(range(0, -5)).toEqual([0, -1, -2, -3, -4]);
+    expect(range(0, -4, { step: -1 })).toEqual([0, -1, -2, -3]);
+    expect(range(-1, 5)).toEqual([-1, 0, 1, 2, 3, 4]);
+    expect(range(0, -5, { step: -1 })).toEqual([0, -1, -2, -3, -4]);
+    expect(range(-1, -2)).toEqual([-1]);
+    expect(range(-1, -2, { step: -1 })).toEqual([-1]);
+    expect(range(-10, -5)).toEqual([-10, -9, -8, -7, -6]);
+  });
+
+  test('decimal', () => {
+    expect(range(10, 12, { step: 0.5 })).toEqual([10, 10.5, 11, 11.5]);
+    expect(range(0, 1, { step: 0.1 })).toEqual([
+      0, 0.1, 0.2, 0.30000000000000004, 0.4, 0.5, 0.6000000000000001,
+      0.7000000000000001, 0.8, 0.9,
+    ]);
+  });
+
+  test('inclusive true', () => {
+    expect(range(0, 5, { inclusive: true })).toEqual([0, 1, 2, 3, 4, 5]);
+    expect(range(-1, -2, { step: -1, inclusive: true })).toEqual([-1, -2]);
+  });
+
+  test('Use with for of loop', () => {
+    const res = [];
+    for (const item of range(1, 5)) {
+      res.push(item);
+    }
+    expect(res).toEqual([1, 2, 3, 4]);
+  });
+
+  test('NaN', () => {
+    expect(() => range(NaN, 0)).toThrowError();
+    expect(() => range(0, NaN)).toThrowError();
+    expect(() => range(NaN, NaN)).toThrowError();
+
+    expect(() => range(0, 0, { step: NaN })).toThrowError();
+    expect(() => range(0, 5, NaN)).toThrowError();
+  });
+
+  test('Step infer', () => {
+    expect(range(0, -2)).toEqual([0, -1]);
+    expect(range(0, -2, { inclusive: true })).toEqual([0, -1, -2]);
+  });
+
+  test('Error: Zero as step', () => {
+    expect(() => range(0, 10, 0)).toThrowError();
+    expect(() => range(0, 10, { step: 0 })).toThrowError();
+    expect(() => range(0n, 10n, 0n)).toThrowError();
+    expect(() => range(0n, 10n, { step: 0n })).toThrowError();
+  });
+
+  test('Error: Infinity as start / step', () => {
+    expect(() => range(Infinity, 10, 0)).toThrowError();
+    expect(() => range(-Infinity, 10, 0)).toThrowError();
+    expect(() => range(0, 10, Infinity)).toThrowError();
+    expect(() => range(0, 10, { step: Infinity })).toThrowError();
+  });
+
+  test('Inclusive on same start-end', () => {
+    expect(range(0, 0, { inclusive: false })).toEqual([]);
+    expect(range(0, 0, { inclusive: true })).toEqual([0]);
   });
 });

packages/utils/__tests__/types/isInfinity.spec.ts

@@ -0,0 +1,20 @@
+import { isInfinity } from '../../src';
+
+describe('Types > isInfinity', () => {
+  test('invalid cases', () => {
+    expect(isInfinity()).toBe(false);
+    expect(isInfinity('')).toBe(false);
+    expect(isInfinity(0)).toBe(false);
+    expect(isInfinity(false)).toBe(false);
+    expect(isInfinity(null)).toBe(false);
+    expect(isInfinity(NaN)).toBe(false);
+    expect(isInfinity('Infinity')).toBe(false);
+    expect(isInfinity('1/0')).toBe(false);
+  });
+
+  test('valid cases', () => {
+    expect(isInfinity(Infinity)).toBe(true);
+    expect(isInfinity(Infinity)).toBe(true);
+    expect(isInfinity(-Infinity)).toBe(true);
+  });
+});

packages/utils/src/array/range.ts

@@ -1,17 +1,99 @@
+import isInfinity from '../types/isInfinity';
+import isNum from '../types/isNum';
+
 /**
  * It generates a sequence of numbers starting at the first argument,
  * progressing by the third argument, and stopping at the second argument.
  *
  * @example
  *
- * range(0, 5) // [0, 1, 2, 3, 4, 5]
- * range(10, 50, 10) // [10, 20, 30, 40, 50]
+ * range(0, 5) // [0, 1, 2, 3, 4]
  */
+export default function range(
+  start: number,
+  end: number,
+  options?: number | { step: number; inclusive: boolean }
+) {
+  if (Number.isNaN(start) || Number.isNaN(end)) {
+    throw new RangeError();
+  }
+
+  if (!isNum(start) || !isNum(end)) {
+    throw new TypeError();
+  }
+
+  if (isInfinity(start)) {
+    throw RangeError();
+  }
+
+  const ifIncrease = end > start;
+
+  let inclusiveEnd = false;
+  let step;
+
+  if (options === undefined || options === null) {
+    step = undefined;
+  } else if (typeof options === 'object') {
+    step = options.step;
+    inclusiveEnd = Boolean(options.inclusive);
+  } else if (isNum(options)) {
+    step = options;
+  } else {
+    throw new TypeError();
+  }
+
+  if (Number.isNaN(step)) {
+    throw new RangeError();
+  }
+
+  if (step === undefined || step === null) {
+    step = ifIncrease ? 1 : -1;
+  }
+
+  if (typeof step !== 'number') {
+    throw new TypeError();
+  }
+
+  if (isInfinity(step)) {
+    throw RangeError();
+  }
+
+  if (step === 0 && start !== end) {
+    throw new RangeError();
+  }
+
+  const arr: number[] = [];
+  const ifStepIncrease = step > 0;
+
+  if (ifIncrease !== ifStepIncrease) {
+    return arr;
+  }
+
+  let hitsEnd = false;
+  let curCount = 0;
+
+  while (hitsEnd === false) {
+    const val = start + step * curCount;
+
+    if (val === end) {
+      hitsEnd = true;
+    }
+
+    curCount = curCount + 1;
+    let endCondition = false;
+
+    if (ifIncrease) {
+      endCondition = inclusiveEnd ? val > end : val >= end;
+    } else {
+      endCondition = inclusiveEnd ? end > val : end >= val;
+    }
+
+    if (endCondition) {
+      return arr;
+    }
+
+    arr.push(val);
+  }
 
-export default function range(start = 0, stop: number, step = 1): number[] {
-  if (step === 0) return [];
-  return Array.from(
-    { length: (stop - start) / step + 1 },
-    (_, i) => start + i * step
-  );
+  return arr;
 }

packages/utils/src/index.ts

@@ -73,6 +73,7 @@ export { default as isBlob } from './types/isBlob';
 export { default as isPromise } from './types/isPromise';
 export { default as isPureObj } from './types/isPureObj';
 export { default as isDef } from './types/isDef';
+export { default as isInfinity } from './types/isInfinity';
 
 // Object
 export { default as has } from './object/has';

packages/utils/src/types/isInfinity.ts

@@ -0,0 +1,18 @@
+/**
+ * Checks if the given value is Infinity.
+ *
+ * @example
+ *
+ * isInfinity(0) //=> false
+ *
+ * isInfinity(NaN) //=> false
+ *
+ * isInfinity(Infinity) //=> true
+ */
+export default function isInfinity(x: unknown) {
+  if (typeof x !== 'number') return false;
+  if (Number.isNaN(x)) return false;
+  if (Number.isFinite(x)) return false;
+
+  return true;
+}

packages/utils/src/types/isNum.ts

@@ -14,7 +14,6 @@
  * isNum(Infinity) //=> false
  *
  */
-
 export default function isNum(val: unknown, coerce = false): val is number {
   let n = val;
   if (coerce && typeof val === 'string' && val.trim().length) {