py-range-js

Python-style range utilities for JavaScript and TypeScript.

This small library provides a Range class and a range() factory function that behave similarly to Python's built-in range() — lazy, iterable, and typed for TypeScript projects.

Package: py-range-js
Version: 1.0.0

Highlights

• Small, dependency-free TypeScript implementation
• Iterables compatible with for..of, Array.from, and spread ([...])
• Methods: length, at(), includes(), toString()
• Supports positive and negative step values

Contents

• Installation
• Quick start (JavaScript & TypeScript)
• API reference
• Examples
• Build from source
• Contributing & license

Install

Install from npm:

npm install py-range-js
# or
yarn add py-range-js

If you are working with the repository locally, run:

npm install
npm run build

Quick Start (TypeScript)

import { range, Range } from 'py-range-js';

for (const n of range(5)) {
	console.log(n); // 0,1,2,3,4
}

const r = range(1, 10, 2); // Range from 1 up to (but not including) 10, step 2
console.log(r.length); // number of items
console.log(r.at(0)); // 1
console.log(r.includes(5)); // true

// Negative step
for (const n of range(5, -1, -1)) {
	console.log(n); // 5,4,3,2,1,0
}

Quick Start (JavaScript)

const { range } = require('py-range-js');

console.log([...range(3)]); // [0,1,2]

API Reference

• class Range implements Iterable<number>

  • new Range(start: number, stop?: number, step: number = 1)
    • If stop is omitted, the constructor treats the first argument as stop and start defaults to 0 (like Python).
    • Throws an Error if step === 0.
  • readonly start: number — inclusive start value.
  • readonly stop: number — exclusive stop value.
  • readonly step: number — step increment (may be negative).
  • get length(): number — number of elements in the range.
  • at(index: number): number — return value at index. Negative index counts from the end. Throws RangeError if out-of-bounds.
  • includes(value: number): boolean — whether value is in the range (fast check using arithmetic).
  • [Symbol.iterator]() — yields values from start to stop by step.
  • toString() — returns a short string like Range(0, 5, 1).

• function range(start: number, stop?: number, step?: number): Range — factory helper returning a Range instance.

Behavior notes:

• stop is exclusive: values yielded satisfy start <= value < stop for positive step, or start >= value > stop for negative step.
• length returns the number of yielded values and will be 0 for empty ranges.

Examples

• Convert to array:

Array.from(range(0, 10, 2)); // [0,2,4,6,8]

• Slicing-like access with at (negative index supported):

const r = range(0, 5);
r.at(-1); // 4

• Membership:

range(2, 10, 2).includes(6); // true
range(2, 10, 2).includes(7); // false

Build & Distribution

This project uses TypeScript and Rollup to produce CommonJS and ES module builds plus type declarations in dist/.

• Build:

npm run build

• Output files (from package.json / rollup.config.js):
  • dist/index.esm.js (ESM)
  • dist/index.cjs.js (CJS)
  • dist/index.d.ts (TypeScript types)

Development notes

• TypeScript settings are in tsconfig.json (target ES2020, declaration: true).
• Rollup configuration is in rollup.config.js using @rollup/plugin-typescript.

Contributing

Contributions are welcome! Please open issues for bug reports or feature requests and submit pull requests for fixes and enhancements.

Guidelines:

• Keep changes focused and well-tested.
• Update or add examples if you introduce new behavior.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author / Maintainer: michael9992155 (see package.json)