range-pie

A TypeScript/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. Fully typed for TypeScript users while remaining compatible with JavaScript projects.

Table of Contents

• Installation

• Basic Usage

  • JavaScript
  • TypeScript

• API Reference

  • Constructor Options
  • Properties
  • at()
  • toString()
  • toArray()
  • map()
  • filter()
  • reduce()
  • some()
  • every()
  • find()
  • findIndex()
  • findLastIndex()
  • forEach()
  • includes()
  • indexOf()
  • lastIndexOf()
  • pop()
  • slice()
  • reverse()
  • entries()
  • keys()
  • values()

• Advanced Usage

  • Iteration
  • Proxy Access

• Examples

  • Methods chaining
  • Using as Array-like Object
  • Example Files
    • Running the Examples
    • Available Examples
    • Method-Specific Demonstrations

Installation

npm install range-pie

Basic Usage

JavaScript

// CommonJS - Both import styles are supported
const { PyRange } = require('range-pie');  // Named import style
// OR
const PyRange = require('range-pie');     // Default import style

// 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]

// Create a reverse range
const range4 = new PyRange(5, 2);
console.log([...range4]); // [5, 4, 3]

TypeScript

// ES Modules - Both import styles are supported
import { PyRange } from 'range-pie';  // Named import style
// OR
import PyRange from 'range-pie';      // Default import style

// Create a range from 0 to 5
const range = new PyRange(5);
console.log([...range]); // [0, 1, 2, 3, 4]

// Type-safe operations
const doubledValues: number[] = range.map(x => x * 2);
console.log(doubledValues); // [0, 2, 4, 6, 8]

// Type inference works with generics
const stringValues: string[] = range.map(x => `Value: ${x}`);
console.log(stringValues); // ['Value: 0', 'Value: 1', 'Value: 2', 'Value: 3', 'Value: 4']

API Reference

Constructor Options

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)

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)

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)

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

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.

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.

const range = new PyRange(1, 10, 2);
console.log(range.toString()); // "PyRange(1, 10, 2)"

toArray()

Transform a PyRange object to an JavaScript array

const range = new PyRange(1, 4);
console.log(range.toArray()); // [1, 2, 3]

map()

It works the same as Array.prototype.map

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

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

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

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

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

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

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

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

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

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

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

const range = new PyRange(1, 5, 1);  // [1, 2, 3, 4]
console.log(range.lastIndexOf(3));    // 2
console.log(range.lastIndexOf(5));    // -1

pop()

Similar to Array.prototype.pop, this method removes the last value from the range, shortens the range and returns that value.

const range = new PyRange(1, 5);  // [1, 2, 3, 4]
console.log(range.pop());  // 4
console.log([...range]);   // [1, 2, 3]

slice()

This method behaves similarly to Array.prototype.slice. It returns a new PyRange instance containing elements from the specified indices. The original range is not modified.

const range = new PyRange(0, 10);  // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
const sliced = range.slice(2, 5);
console.log([...sliced]); // [2, 3, 4]
console.log([...range]);  // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] (unchanged)

// Negative indices are supported
const lastThree = range.slice(-3);
console.log([...lastThree]); // [7, 8, 9]

reverse()

It works the same as Array.prototype.reverse

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]);

entries()

It works the same as Array.prototype.entries. It returns an iterator of [index, value] pairs.

const range = new PyRange(1, 4);  // [1, 2, 3]
for (const [index, value] of range.entries()) {
  console.log(index, value);
}
// 0 1
// 1 2
// 2 3

keys()

It works the same as Array.prototype.keys. It returns an iterator of the indices of the range.

const range = new PyRange(3);  // [0, 1, 2]
console.log([...range.keys()]); // [0, 1, 2]

values()

It works the same as Array.prototype.values. It returns an iterator of the values in the range.

const range = new PyRange(3);  // [0, 1, 2]
console.log([...range.values()]); // [0, 1, 2]

Advanced Usage

Iteration

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.

const range = new PyRange(5);
const proxy = range.asProxy();

console.log(proxy[0]); // 0
console.log(proxy[3]); // 3

TypeScript Support

This package is written in TypeScript and provides full type definitions for all methods and properties. TypeScript users get the following benefits:

• Type checking for all method parameters and return values
• Autocompletion in IDEs
• Generic type support for methods like map() and reduce()
• Better documentation through type annotations

// Type inference with generics
const range = new PyRange(5);

// TypeScript knows this is a number[]
const numbers = range.map(x => x * 2);

// TypeScript knows this is a string[]
const strings = range.map(x => `Number: ${x}`);

// TypeScript knows this is a boolean[]
const booleans = range.map(x => x % 2 === 0);

Examples

Methods chaining

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

const range = new PyRange(5).asProxy();
const firstThree = [range[0], range[1], range[2]];
console.log(firstThree); // [0, 1, 2]

Example Files

This package includes several example files to help you get started. You can find them in the examples directory after installing the package.

Running the Examples

If you've cloned the repository, you can run the examples using npm scripts:

# Run basic usage examples
npm run example:basic

# Run array methods examples
npm run example:array

# Run advanced usage examples
npm run example:advanced

# Run TypeScript examples (requires ts-node)
npm run example:ts

Or you can run them directly with Node.js:

node node_modules/range-pie/examples/basic-usage.js
node node_modules/range-pie/examples/array-methods.js
node node_modules/range-pie/examples/advanced-usage.js

# For TypeScript examples
ts-node node_modules/range-pie/examples/typescript-usage.ts

Available Examples

• basic-usage.js: Shows fundamental PyRange operations
• array-methods.js: Demonstrates all array-like methods
• advanced-usage.js: Covers advanced features like method chaining and proxy usage
• typescript-usage.ts: Shows TypeScript-specific features and type safety

Method-Specific Demonstrations

For detailed demonstrations of individual methods, see the examples/methods/ folder. Each method has its own comprehensive demo file with detailed explanations and use cases.

# Run all method demonstrations
npm run example:methods

For instructions on running individual method demos and more details, see the README in the examples/methods folder.