range-pie 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SkorpionG2000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# range-pie
+
+A JavaScript library that brings Python's range functionality to JavaScript, enhanced with familiar array methods. This lightweight utility provides a seamless way to work with numeric sequences while maintaining JavaScript's functional programming paradigm.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [API Reference](#api-reference)
+
+  - [Constructor Options](#constructor-options)
+  - [Properties](#properties)
+  - [at()](#at)
+  - [toString()](#tostring)
+  - [toArray()](#toarray)
+  - [map()](#map)
+  - [filter()](#filter)
+  - [reduce()](#reduce)
+  - [some()](#some)
+  - [every()](#every)
+  - [find()](#find)
+  - [findIndex()](#findindex)
+  - [findLastIndex()](#findlastindex)
+  - [forEach()](#foreach)
+  - [includes()](#includes)
+  - [indexOf()](#indexof)
+  - [lastIndexOf()](#lastindexof)
+  - [reverse()](#reverse)
+
+- [Advanced Usage](#advanced-usage)
+
+  - [Iteration](#iteration)
+  - [Proxy Access](#proxy-access)
+
+- [Examples](#examples)
+
+  - [Methods chaining](#methods-chaining)
+  - [Using as Array-like Object](#using-as-array-like-object)
+
+## Installation
+
+```bash
+npm install python-range
+```
+
+## Basic Usage
+
+```javascript
+const { PyRange } = require('range-pie');
+
+// Create a range from 0 to 5
+const range = new PyRange(5);
+console.log([...range]); // [0, 1, 2, 3, 4]
+
+// Create a range with start and stop
+const range2 = new PyRange(2, 8);
+console.log([...range2]); // [2, 3, 4, 5, 6, 7]
+
+// Create a range with step
+const range3 = new PyRange(0, 10, 2);
+console.log([...range3]); // [0, 2, 4, 6, 8]
+```
+
+## API Reference
+
+### Constructor Options
+
+```javascript
+new PyRange(stop)               // 0 to stop-1
+new PyRange(start, stop)        // start to stop-1
+new PyRange(start, stop, step)  // start to stop-1 with step
+```
+
+- **PyRange(stop:number)**
+
+```javascript
+console.log(PyRange(10));
+// PyRange { _start: 0, _stop: 10, _step: 1, _length: 10 }
+
+console.log(PyRange(-5));
+// PyRange { _start: 0, _stop: -5, _step: -1, _length: 5 }
+```
+
+- **PyRange(start:number, stop:number)**
+
+```javascript
+console.log(PyRange(1, 10));
+// PyRange { _start: 1, _stop: 10, _step: 1, _length: 9 }
+
+console.log(PyRange(-10, 0));
+// PyRange { _start: -10, _stop: 0, _step: 1, _length: 10 }
+```
+
+- **PyRange(start:number, stop:number, step:number)**
+
+```javascript
+console.log(PyRange(2, 5, 2));
+// PyRange { _start: 2, _stop: 5, _step: 2, _length: 2 }
+
+console.log(PyRange(2, -10, -1));
+// PyRange { _start: 2, _stop: -10, _step: -1, _length: 12 }
+```
+
+### Properties
+
+```javascript
+const range = new PyRange(1, 10, 2);
+console.log(range.start);  // 1
+console.log(range.stop);   // 10
+console.log(range.step);   // 2
+console.log(range.length); // 5
+```
+
+### at()
+
+The 'at' method accepts a number as argument to gets the value at the specified index in a range. Generate a RangeError if the index is out of range.
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.at(0));  // 1
+console.log(range.at(2));  // 3
+console.log(range.at(-1)); // RangeError
+```
+
+### toString()
+
+Transform a PyRange object to a string representation.
+
+```javascript
+const range = new PyRange(1, 10, 2);
+console.log(range.toString()); // "PyRange(1, 10, 2)"
+```
+
+### toArray()
+
+Transform a PyRange object to an JavaScript array
+
+```javascript
+const range = new PyRange(1, 4);
+console.log(range.toArray()); // [1, 2, 3]
+```
+
+### map()
+
+It works the same as [**`Array.prototype.map`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+
+```javascript
+const range = new PyRange(1, 4);  // [1, 2, 3]
+console.log(range.map(x => x * 2));  // [2, 4, 6]
+```
+
+### filter()
+
+It works the same as [**`Array.prototype.filter`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter)
+
+```javascript
+const range = new PyRange(1, 6);  // [1, 2, 3, 4, 5]
+console.log(range.filter(x => x % 2 === 0));  // [2, 4]
+```
+
+### reduce()
+
+It works the same as [**`Array.prototype.reduce`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce)
+
+```javascript
+const range = new PyRange(1, 4);  // [1, 2, 3]
+const sum = range.reduce((acc, curr) => acc + curr, 0);
+console.log(sum);  // 6
+```
+
+### some()
+
+It works the same as [**`Array.prototype.some`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.some(x => x > 3));  // true
+console.log(range.some(x => x < 0));  // false
+```
+
+### every()
+
+It works the same as [**`Array.prototype.every`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.every(x => x > 0));  // true
+console.log(range.every(x => x > 2));  // false
+```
+
+### find()
+
+It works the same as [**`Array.prototype.find`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.find(x => x > 2));  // 3
+console.log(range.find(x => x > 5));  // undefined
+```
+
+### findIndex()
+
+It works the same as [**`Array.prototype.findIndex`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.findIndex(x => x > 2));  // 2
+console.log(range.findIndex(x => x > 5));  // -1
+```
+
+### findLastIndex()
+
+It works the same as [**`Array.prototype.findLastIndex`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.findLastIndex(x => x > 2));  // 3
+console.log(range.findLastIndex(x => x > 5));  // -1
+```
+
+### forEach()
+
+It works the same as [**`Array.prototype.forEach`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)
+
+```javascript
+const range = new PyRange(1, 4);  // [1, 2, 3]
+range.forEach(x => console.log(x));  
+// 1
+// 2
+// 3
+```
+
+### includes()
+
+It works the same as [**`Array.prototype.includes`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.includes(3));  // true
+console.log(range.includes(5));  // false
+```
+
+### indexOf()
+
+It works the same as [**`Array.prototype.indexOf`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log(range.indexOf(3));    // 2
+console.log(range.indexOf(5));    // -1
+```
+
+### lastIndexOf()
+
+It works the same as [**`Array.prototype.lastIndexOf`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf)
+
+```javascript
+const range = new PyRange(1, 5, 1);  // [1, 2, 3, 4]
+console.log(range.lastIndexOf(3));    // 2
+console.log(range.lastIndexOf(5));    // -1
+```
+
+### reverse()
+
+It works the same as [**`Array.prototype.reverse`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse)
+
+```javascript
+const range = new PyRange(1, 5);  // [1, 2, 3, 4]
+console.log([...range]);          // [1, 2, 3, 4]
+
+const reversed = range.reverse(); // [4, 3, 2, 1]
+console.log([...reversed]);      // [4, 3, 2, 1]
+
+const rangeWithStep = new PyRange(1, 10, 2);  // [1, 3, 5, 7, 9]
+const reversedStep = rangeWithStep.reverse(); // [9, 7, 5, 3, 1]
+console.log([...reversedStep]);
+```
+
+## Advanced Usage
+
+### Iteration
+
+```javascript
+const range = new PyRange(3);
+
+// For...of loop
+for (const num of range) {
+    console.log(num); // 0, 1, 2
+}
+
+// Spread operator
+const array = [...range]; // [0, 1, 2]
+```
+
+### Proxy Access
+
+Proxy access allows access to the array elements using bracket notation, just like a regular array.
+
+```javascript
+const range = new PyRange(5);
+const proxy = range.asProxy();
+
+console.log(proxy[0]); // 0
+console.log(proxy[3]); // 3
+```
+
+## Examples
+
+### Methods chaining
+
+```javascript
+const range = new PyRange(1, 6);
+const squares = range
+    .filter(x => x % 2 === 0)
+    .map(x => x * x);
+console.log(squares); // [4, 16]
+```
+
+### Using as Array-like Object
+
+```javascript
+const range = new PyRange(5).asProxy();
+const firstThree = [range[0], range[1], range[2]];
+console.log(firstThree); // [0, 1, 2]
+```

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "range-pie",
+  "version": "1.0.0",
+  "description": "A JavaScript class that simulate Python's range function, combined with several useful JavaScript array methods.",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "keywords": [
+    "range",
+    "Python range",
+    "Python",
+    "JavaScript",
+    "JavaScript Array",
+    "Array",
+    "py-range",
+    "PyRange"
+  ],
+  "author": "SkorpionG2000",
+  "license": "MIT",
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+"use strict";
+const PyRange = require("./py-range.js");
+
+module.exports = PyRange;
+module.exports.PyRange = PyRange;

package/src/py-range.js

@@ -0,0 +1,376 @@
+"use strict";
+
+class PyRange {
+  /**
+   * A class that simulate Python's range function, combined with several useful JavaScript array methods.
+   * @param {...number} args - The arguments of the range. The possible forms are
+   *   - `PyRange(stop)`
+   *   - `PyRange(start, stop)`
+   *   - `PyRange(start, stop, step)`
+   * @throws {TypeError} If any of the arguments is not a number.
+   * @throws {TypeError} If any of the arguments is not an integer.
+   * @throws {Error} If the step is zero.
+   * @throws {Error} If the arguments count is not between 1 and 3.
+   * @property {number} start - The start of the range, inclusive.
+   * @property {number} stop - The stop of the range, exclusive.
+   * @property {number} step - The step of the range.
+   * @property {number} length - The length of the range.
+   */
+  constructor(...args) {
+    if (!args.every((arg) => typeof arg === "number")) {
+      throw new TypeError("All arguments must be numbers");
+    }
+
+    if (!args.every(Number.isInteger)) {
+      throw new TypeError("All arguments must be integers");
+    }
+
+    const [start, stop, step] =
+      args.length === 1
+        ? [0, args[0], 1]
+        : args.length === 2
+        ? [args[0], args[1], 1]
+        : args.length === 3
+        ? [args[0], args[1], args[2]]
+        : (() => {
+            throw new Error("Invalid arguments count: must between 1 and 3");
+          })();
+
+    if (step === 0) {
+      throw new Error("Step cannot be zero");
+    }
+
+    this._start = start;
+    this._stop = stop;
+    this._step = stop < start && args.length !== 3 ? -step : step;
+
+    const diff = this._step > 0 ? stop - start : start - stop;
+    this._length = Math.max(Math.ceil(diff / Math.abs(this._step)), 0);
+  }
+
+  /**
+   * Gets the length of this range.
+   *
+   * @returns {number} the length of this range
+   * @readonly
+   */
+  get length() {
+    return this._length;
+  }
+
+  /**
+   * Gets the starting value of the range.
+   *
+   * @returns {number} The starting value of the range.
+   * @readonly
+   */
+  get start() {
+    return this._start;
+  }
+
+  /**
+   * Gets the ending value of the range.
+   *
+   * @returns {number} The ending value of the range.
+   * @readonly
+   */
+  get stop() {
+    return this._stop;
+  }
+
+  /**
+   * Gets the step value of the range.
+   *
+   * @returns {number} The step value of the range.
+   * @readonly
+   */
+  get step() {
+    return this._step;
+  }
+
+  /**
+   * Gets the value at the specified index in this range.
+   * @param {number} index - The index of the value to retrieve
+   * @returns {number} The value at the specified index
+   * @throws {RangeError} If the index is out of range
+   */
+  at(index) {
+    if (index < 0 || index >= this._length) {
+      throw new RangeError("Index out of range");
+    }
+    return this._start + index * this._step;
+  }
+
+  /**
+   * Converts the range to a string.
+   * @returns {string} A string of the form `Range(start, stop, step)`.
+   */
+  toString() {
+    return `PyRange(${this._start}, ${this._stop}, ${this._step})`;
+  }
+
+  /**
+   * Converts the range to an array.
+   * @returns {number[]} An array of numbers with the same elements as this range.
+   */
+  toArray() {
+    return [...this];
+  }
+
+  static #validateCb(cb) {
+    if (typeof cb !== "function") {
+      throw new TypeError("Callback must be a function");
+    }
+  }
+
+  /**
+   * Creates a new array with the results of applying the given callback
+   * function to every element in this range.
+   * @param {function(number, number, PyRange): *} callback - The callback
+   * function to apply to every element.
+   * @returns {Array.<*>} A new array of the same length as this range.
+   */
+  map(callback) {
+    PyRange.#validateCb(callback);
+
+    const result = new Array(this._length);
+
+    for (let i = 0; i < this._length; i++) {
+      result[i] = callback(this.at(i), i, this);
+    }
+
+    return result;
+  }
+
+  /**
+   * Creates a new array with all elements that pass the test implemented by
+   * the provided function.
+   * @param {function(number, number, PyRange): boolean} callback - The
+   * predicate function to apply to every element
+   * @returns {number[]} A new array of elements that pass the test
+   */
+  filter(callback) {
+    PyRange.#validateCb(callback);
+
+    const result = [];
+
+    for (let i = 0; i < this._length; i++) {
+      if (callback(this.at(i), i, this)) {
+        result.push(this.at(i));
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Reduces the range to a single value.
+   * @param {function(*, number, number, PyRange): *} callback - The callback
+   * function to apply to every element. The callback should take four
+   * arguments: the accumulator, the current value, the index of the current
+   * value, and the range object.
+   * @param {*} [initialValue] - The initial value of the accumulator.
+   * @returns {*} The final value of the accumulator.
+   */
+  reduce(callback, initialValue) {
+    PyRange.#validateCb(callback);
+
+    let accumulator = initialValue;
+
+    for (let i = 0; i < this._length; i++) {
+      accumulator = callback(accumulator, this.at(i), i, this);
+    }
+
+    return accumulator;
+  }
+
+  /**
+   * Determines whether at least one element of the range satisfies the
+   * provided test.
+   * @param {function(number, number, PyRange): boolean} callback - The
+   * predicate function to apply to every element
+   * @returns {boolean} True if at least one element of the range passes the
+   * test, false otherwise.
+   */
+  some(callback) {
+    PyRange.#validateCb(callback);
+
+    for (let i = 0; i < this._length; i++) {
+      if (callback(this.at(i), i, this)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Determines whether all elements of the range satisfy the provided test.
+   * @param {function(number, number, PyRange): boolean} callback - The
+   * predicate function to apply to every element
+   * @returns {boolean} True if all elements of the range pass the test,
+   * false otherwise.
+   */
+  every(callback) {
+    PyRange.#validateCb(callback);
+
+    for (let i = 0; i < this._length; i++) {
+      if (!callback(this.at(i), i, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Finds the first element in this range that satisfies the provided test.
+   * @param {function(number, number, PyRange): boolean} callback - The
+   * predicate function to apply to every element
+   * @returns {number|undefined} The first element that passes the test,
+   * or undefined if no element passes the test.
+   */
+  find(callback) {
+    PyRange.#validateCb(callback);
+
+    for (let i = 0; i < this._length; i++) {
+      if (callback(this.at(i), i, this)) {
+        return this.at(i);
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Finds the index of the first element in this range that satisfies the provided test.
+   * @param {function(number, number, PyRange): boolean} callback - The predicate function to apply to each element.
+   * @returns {number} The index of the first element that passes the test, or -1 if no element passes the test.
+   */
+  findIndex(callback) {
+    PyRange.#validateCb(callback);
+
+    for (let i = 0; i < this._length; i++) {
+      if (callback(this.at(i), i, this)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  /**
+   * Finds the index of the last element in this range that satisfies the provided test.
+   * @param {function(number, number, PyRange): boolean} callback - The predicate function to apply to each element.
+   * @returns {number} The index of the last element that passes the test, or -1 if no element passes the test.
+   */
+  findLastIndex(callback) {
+    PyRange.#validateCb(callback);
+
+    for (let i = this._length - 1; i >= 0; i--) {
+      if (callback(this.at(i), i, this)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  /**
+   * Executes a provided function once for each element in this range.
+   * @param {function(number, number, PyRange): void} callback - The
+   * function to execute for each element.
+   */
+  forEach(callback) {
+    PyRange.#validateCb(callback);
+
+    for (let i = 0; i < this._length; i++) {
+      callback(this.at(i), i, this);
+    }
+  }
+
+  /**
+   * Determines whether the given value is present in this range.
+   * @param {*} value - The value to search for.
+   * @returns {boolean} True if the value is present, false otherwise.
+   */
+  includes(value) {
+    return this.some((item) => item === value);
+  }
+
+  /**
+   * Returns the index of the first occurrence of the specified value, or -1 if it is not present.
+   * @param {*} value - The value to search for.
+   * @returns {number} The index of the value, or -1 if it is not present.
+   */
+  indexOf(value) {
+    for (let i = 0; i < this._length; i++) {
+      if (this.at(i) === value) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  /**
+   * Returns the index of the last occurrence of the specified value, or -1 if it is not present.
+   * @param {*} value - The value to search for.
+   * @returns {number} The index of the last occurrence of the value, or -1 if it is not present.
+   */
+  lastIndexOf(value) {
+    for (let i = this._length - 1; i >= 0; i--) {
+      if (this.at(i) === value) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  /**
+   * Reverses the order of the elements in this range, returning a new PyRange object.
+   * @returns {PyRange} A new PyRange object with the elements in reverse order.
+   */
+  reverse() {
+    const result = new PyRange(this._stop, this._start, -this._step);
+    result._length = this._length;
+    return result;
+  }
+
+  [Symbol.iterator]() {
+    let index = 0;
+    let current = this._start;
+    const { _stop: _, _step: step, _length: length } = this;
+
+    return {
+      next: () => {
+        if (index >= length) {
+          return { done: true };
+        } else {
+          const value = current;
+          current += step;
+          index++;
+          return { value, done: false };
+        }
+      },
+    };
+  }
+
+  /**
+   * Returns a Proxy for this range, allowing indexed access.
+   * This proxy enables accessing range elements via array-like indexing.
+   * If the property is a number, it will return the element at that index.
+   *
+   * @returns {Proxy} A proxy for the PyRange instance.
+   */
+  asProxy() {
+    return new Proxy(this, {
+      get(target, prop) {
+        if (typeof prop === "symbol") {
+          return target[prop];
+        }
+        if (!isNaN(prop)) {
+          return target.at(parseInt(prop));
+        }
+        return target[prop];
+      },
+    });
+  }
+}
+
+module.exports = PyRange;
+module.exports.PyRange = PyRange;