range-pie 2.4.1 → 3.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 SkorpionG2000
+Copyright (c) 2026 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

package/README.md

@@ -155,13 +155,14 @@ 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.
+The 'at' method accepts a number as argument to get the value at the specified index in a range. Returns `undefined` if the index is out of range, perfectly matching `Array.prototype.at`. Negative indices count backwards from the end of the 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
+console.log(range.at(-1)); // 4 (negative index wraps from the end)
+console.log(range.at(10)); // undefined (out of bounds)
 ```
 
 ### toString()
@@ -400,7 +401,7 @@ const array = [...range]; // [0, 1, 2]
 
 ### Proxy Access
 
-Proxy access allows access to the array elements using bracket notation, just like a regular array.
+Proxy access allows access to the array elements using bracket notation, just like a regular array. Out-of-bounds access returns `undefined`.
 
 ```javascript
 const range = new PyRange(5);
@@ -408,6 +409,7 @@ const proxy = range.asProxy();
 
 console.log(proxy[0]); // 0
 console.log(proxy[3]); // 3
+console.log(proxy[10]); // undefined
 ```
 
 ### TypeScript Support

package/dist/py-range.d.ts

@@ -6,6 +6,8 @@ declare class PyRange implements Iterable<number> {
     private _stop;
     private _step;
     private _length;
+    private static toIntegerOrInfinity;
+    private static isArrayIndexProperty;
     /**
      * Creates a new PyRange instance.
      * @param {...number} args - The arguments of the range. The possible forms are
@@ -21,7 +23,9 @@ declare class PyRange implements Iterable<number> {
      * @property {number} step - The step of the range.
      * @property {number} length - The length of the range.
      */
-    constructor(...args: number[]);
+    constructor(stop: number);
+    constructor(start: number, stop: number);
+    constructor(start: number, stop: number, step: number);
     /**
      * Gets the length of this range.
      *
@@ -52,11 +56,17 @@ declare class PyRange implements Iterable<number> {
     get step(): number;
     /**
      * 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
+     *
+     * Negative indices are supported and wrap from the end, matching the
+     * behaviour of `Array.prototype.at()`. For example, `at(-1)` returns the
+     * last element.
+     *
+     * @param {number} index - The index of the value to retrieve. Negative
+     *   indices count from the end of the range.
+     * @returns {number|undefined} The value at the specified index, or
+     *   undefined when the normalised index is out of range.
      */
-    at(index: number): number;
+    at(index: number): number | undefined;
     /**
      * Converts the range to a string.
      * @returns {string} A string of the form `Range(start, stop, step)`.
@@ -71,6 +81,7 @@ declare class PyRange implements Iterable<number> {
      * Validates that the callback is a function.
      * @param {Function} cb - The callback to validate.
      * @throws {TypeError} If the callback is not a function.
+     * @internal
      */
     private static validateCb;
     /**
@@ -92,15 +103,23 @@ declare class PyRange implements Iterable<number> {
     filter(callback: (value: number, index: number, range: PyRange) => boolean): number[];
     /**
      * Reduces the range to a single value.
+     *
+     * Uses rest parameters to reliably distinguish between "no initial value
+     * provided" and "explicit `undefined` passed as initial value", matching
+     * the behaviour of `Array.prototype.reduce()`.
+     *
      * @param {function(T, number, number, PyRange): T} 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 {T} [initialValue] - The initial value of the accumulator.
      * @returns {T} The final value of the accumulator.
+     * @throws {TypeError} If the range is empty and no initial value is provided.
      * @template T
      */
-    reduce<T>(callback: (accumulator: T, value: number, index: number, range: PyRange) => T, initialValue?: T): T;
+    reduce(callback: (accumulator: number, value: number, index: number, range: PyRange) => number): number;
+    reduce(callback: (accumulator: number, value: number, index: number, range: PyRange) => number, initialValue: number): number;
+    reduce<U>(callback: (accumulator: U, value: number, index: number, range: PyRange) => U, initialValue: U): U;
     /**
      * Determines whether at least one element of the range satisfies the
      * provided test.
@@ -189,6 +208,10 @@ declare class PyRange implements Iterable<number> {
     slice(begin?: number, end?: number): PyRange;
     /**
      * Reverses the order of the elements in this range, returning a new PyRange object.
+     *
+     * The new range starts at the last actual element of this range and steps
+     * in the opposite direction. The original range is not modified.
+     *
      * @returns {PyRange} A new PyRange object with the elements in reverse order.
      */
     reverse(): PyRange;
@@ -219,18 +242,18 @@ declare class PyRange implements Iterable<number> {
     values(): IterableIterator<number>;
     /**
      * Implements the iterable protocol for this range.
-     * @returns {Iterator<number>} An iterator for this range.
+     * @returns {IterableIterator<number>} An iterator for this range.
      */
-    [Symbol.iterator](): Iterator<number>;
+    [Symbol.iterator](): IterableIterator<number>;
     /**
      * 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 {PyRange & { [key: number]: number }} A proxy for the PyRange instance.
+     * @returns {PyRange & { [key: number]: number | undefined }} A proxy for the PyRange instance.
      */
     asProxy(): PyRange & {
-        [key: number]: number;
+        [key: number]: number | undefined;
     };
 }
 export { PyRange };

package/dist/py-range.js

@@ -5,21 +5,22 @@ exports.PyRange = void 0;
  * A class that simulates Python's range function, combined with several useful JavaScript array methods.
  */
 class PyRange {
-    /**
-     * Creates a new PyRange instance.
-     * @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.
-     */
+    _start;
+    _stop;
+    _step;
+    _length;
+    static toIntegerOrInfinity(value) {
+        const numeric = +value;
+        return Number.isNaN(numeric) ? 0 : Math.trunc(numeric);
+    }
+    static isArrayIndexProperty(prop) {
+        const index = Number(prop);
+        return (prop !== "" &&
+            Number.isInteger(index) &&
+            index >= 0 &&
+            index < 2 ** 32 - 1 &&
+            String(index) === prop);
+    }
     constructor(...args) {
         if (!args.every((arg) => typeof arg === "number")) {
             throw new TypeError("All arguments must be numbers");
@@ -83,15 +84,23 @@ class PyRange {
     }
     /**
      * 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
+     *
+     * Negative indices are supported and wrap from the end, matching the
+     * behaviour of `Array.prototype.at()`. For example, `at(-1)` returns the
+     * last element.
+     *
+     * @param {number} index - The index of the value to retrieve. Negative
+     *   indices count from the end of the range.
+     * @returns {number|undefined} The value at the specified index, or
+     *   undefined when the normalised index is out of range.
      */
     at(index) {
-        if (index < 0 || index >= this._length) {
-            throw new RangeError("Index out of range");
+        const relativeIndex = PyRange.toIntegerOrInfinity(index);
+        const normalised = relativeIndex < 0 ? this._length + relativeIndex : relativeIndex;
+        if (normalised < 0 || normalised >= this._length) {
+            return undefined;
         }
-        return this._start + index * this._step;
+        return this._start + normalised * this._step;
     }
     /**
      * Converts the range to a string.
@@ -111,6 +120,7 @@ class PyRange {
      * Validates that the callback is a function.
      * @param {Function} cb - The callback to validate.
      * @throws {TypeError} If the callback is not a function.
+     * @internal
      */
     static validateCb(cb) {
         if (typeof cb !== "function") {
@@ -151,25 +161,16 @@ class PyRange {
         }
         return result;
     }
-    /**
-     * Reduces the range to a single value.
-     * @param {function(T, number, number, PyRange): T} 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 {T} [initialValue] - The initial value of the accumulator.
-     * @returns {T} The final value of the accumulator.
-     * @template T
-     */
-    reduce(callback, initialValue) {
+    reduce(callback, ...args) {
         PyRange.validateCb(callback);
-        if (this._length === 0 && initialValue === undefined) {
+        const hasInitial = args.length > 0;
+        if (this._length === 0 && !hasInitial) {
             throw new TypeError("Reduce of empty range with no initial value");
         }
         let accumulator;
         let startIndex;
-        if (initialValue !== undefined) {
-            accumulator = initialValue;
+        if (hasInitial) {
+            accumulator = args[0];
             startIndex = 0;
         }
         else {
@@ -373,13 +374,22 @@ class PyRange {
     }
     /**
      * Reverses the order of the elements in this range, returning a new PyRange object.
+     *
+     * The new range starts at the last actual element of this range and steps
+     * in the opposite direction. The original range is not modified.
+     *
      * @returns {PyRange} A new PyRange object with the elements in reverse order.
      */
     reverse() {
-        const result = new PyRange(this._stop, this._start, -this._step);
-        // Force the length to be the same as the original range
-        result._length = this._length;
-        return result;
+        if (this._length === 0) {
+            // Return an empty range with the same step direction — nothing to reverse
+            return new PyRange(this._start, this._start, this._step);
+        }
+        // The new start is the last actual element (not _stop which is exclusive)
+        const newStart = this.at(this._length - 1);
+        // The new stop is one step past the first element in the new direction
+        const newStop = this._start - this._step;
+        return new PyRange(newStart, newStop, -this._step);
     }
     /**
      * Returns an iterator of `[index, value]` pairs for each element in the range.
@@ -418,7 +428,7 @@ class PyRange {
     }
     /**
      * Implements the iterable protocol for this range.
-     * @returns {Iterator<number>} An iterator for this range.
+     * @returns {IterableIterator<number>} An iterator for this range.
      */
     [Symbol.iterator]() {
         let index = 0;
@@ -436,6 +446,9 @@ class PyRange {
                     return { value, done: false };
                 }
             },
+            [Symbol.iterator]() {
+                return this;
+            },
         };
     }
     /**
@@ -443,7 +456,7 @@ class PyRange {
      * 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 {PyRange & { [key: number]: number }} A proxy for the PyRange instance.
+     * @returns {PyRange & { [key: number]: number | undefined }} A proxy for the PyRange instance.
      */
     asProxy() {
         return new Proxy(this, {
@@ -451,8 +464,12 @@ class PyRange {
                 if (typeof prop === "symbol") {
                     return Reflect.get(target, prop, receiver);
                 }
-                if (!isNaN(Number(prop))) {
-                    return target.at(parseInt(String(prop), 10));
+                if (PyRange.isArrayIndexProperty(prop)) {
+                    const idx = Number(prop);
+                    // Match Array behaviour: out-of-bounds returns undefined, not throw
+                    if (idx >= target.length)
+                        return undefined;
+                    return target.at(idx);
                 }
                 return Reflect.get(target, prop, receiver);
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "range-pie",
-  "version": "2.4.1",
+  "version": "3.0.0",
   "description": "A TypeScript class that simulates Python's range function, combined with several useful JavaScript array methods.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -22,25 +22,27 @@
   ],
   "scripts": {
     "build": "tsc",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "build:prod": "tsc -p tsconfig.prod.json",
     "build:watch": "tsc --watch",
     "prepare": "husky",
     "prepublishOnly": "npm run build:prod && npm run test",
     "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "lint": "eslint . --ext .ts,.js",
     "lint:fix": "eslint . --ext .ts,.js --fix",
-    "test:watch": "jest --watch",
     "clean": "rimraf dist",
-    "format": "prettier --write \"src/**/*.{ts,js}\" \"test/**/*.{ts,js}\" \"examples/**/*.{ts,js}\" \"*.{js,json}\"",
-    "format:check": "prettier --check \"src/**/*.{ts,js}\" \"test/**/*.{ts,js}\" \"examples/**/*.{ts,js}\" \"*.{js,json}\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "example:basic": "node examples/basic-usage.js",
     "example:array": "node examples/array-methods.js",
     "example:advanced": "node examples/advanced-usage.js",
     "example:ts": "ts-node examples/typescript-usage.ts",
     "example:methods": "for file in examples/methods/*.ts; do echo \"\\n=== Running $file ===\"; ts-node \"$file\"; done",
     "knip": "knip",
-    "precommit": "npm run typecheck && npx --no-install lint-staged"
+    "lint-staged": "lint-staged",
+    "precommit": "npm run typecheck && npm run lint-staged"
   },
   "keywords": [
     "range",
@@ -60,20 +62,23 @@
     "url": "git+https://github.com/SkorpionG/range-pie.git"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.4",
+    "@eslint/js": "^10.0.1",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.4.0",
-    "eslint": "^9.39.4",
-    "globals": "^17.4.0",
+    "@types/node": "^26.0.1",
+    "eslint": "^10.6.0",
+    "globals": "^17.7.0",
     "husky": "^9.1.7",
-    "jest": "^30.3.0",
-    "knip": "^5.86.0",
-    "lint-staged": "^16.3.3",
-    "prettier": "^3.8.1",
+    "jest": "^30.4.2",
+    "knip": "^6.23.0",
+    "lint-staged": "^17.0.8",
+    "prettier": "^3.9.1",
     "rimraf": "^6.1.3",
-    "ts-jest": "^29.4.6",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.0"
+    "ts-jest": "^29.4.11",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.0"
+  },
+  "overrides": {
+    "js-yaml": "^4.1.2"
   }
 }