iterange
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

iterange

deno land deno doc GitHub release (latest by date) codecov GitHub

test NPM

Numeric sequence lazy generator, TC39 proposal-iterator.range implementation.

Entrypoint

This project provides ponyfill and polyfill.

Polyfill has a side effect, so the endpoint is isolated.

The entrypoint of each are as follows:

Type Entrypoint
Ponyfill mod.ts
Polyfill polyfill.ts

Incremental sequence

Specify start and end. By default, step is 1 and end is exclusive.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const start = 0;
const end = 5;

assertEquals([...range(start, end)], [0, 1, 2, 3, 4]);

Decremental sequence

If end is less than start, a decremental sequence is generated.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(1, -3);

assertEquals(iterator.next().value, 1);
assertEquals(iterator.next().value, 0);
assertEquals(iterator.next().value, -1);

Step

You can change the interval(step) of the sequence. The default is 1 (or 1n for bigint).

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(0, Infinity, 2);

assertEquals(iterator.next().value, 0);
assertEquals(iterator.next().value, 2);
assertEquals(iterator.next().value, 4);

Inclusive end range

By default, end is exclusive. This can be changed by specifying options.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

assertEquals([...range(0, 5, { inclusive: true })], [0, 1, 2, 3, 4, 5]);

Step option

Option accepts another step field. This is equivalent to step.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(0, -Infinity, { step: -2 });

assertEquals(iterator.next().value, 0);
assertEquals(iterator.next().value, -2);
assertEquals(iterator.next().value, -4);

Bigint

The range supports bigint as well as number.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(0n, 100n, { step: 10n });

assertEquals(iterator.next().value, 0n);
assertEquals(iterator.next().value, 10n);
assertEquals(iterator.next().value, 20n);

That is, the following cannot be compiled and are type safe:

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";

//@ts-expect-error
range(0, 0n);
//@ts-expect-error
range(0, 100, 3n);
//@ts-expect-error
range(1n, Infinity, { step: 1 });

Throwing error

Throws RangeError in the following cases:

  • start, end or step is NaN
  • start is infinity
  • if step is 0, start and end are not the same
import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => range(NaN, 0).next());
assertThrows(() => range(0, NaN).next());
assertThrows(() => range(0, Infinity, NaN).next());
assertThrows(() => range(Infinity, Infinity).next());
assertThrows(() => range(0n, 1n, { step: 0n }).next());

Polyfill

Polyfill affects the global object. You must be very careful when using it.

Depends on the Iterator object. If there is no Iterator, a runtime error will occur.

import "https://deno.land/x/iterange@$VERSION/polyfill.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

assert(Iterator.range);

API

See deno doc for all APIs.

License

Copyright © 2023-present Tomoki Miyauchi.

Released under the MIT license

Package Sidebar

Install

npm i iterange

Weekly Downloads

50

Version

1.0.0

License

MIT

Unpacked Size

23 kB

Total Files

21

Last publish

Collaborators

  • miyauci