figurate 1.0.0

package/DESIGN.md

@@ -0,0 +1,167 @@
+# Design
+
+This document states what `figurate` computes, over which domains, with
+which invariants, at what cost, and which alternatives were rejected.
+
+## The construction
+
+For sides `s >= 3` and index `n >= 0`, the `n`-th `s`-gonal number is
+
+```
+P(s, n) = ((s-2) n² - (s-4) n) / 2
+```
+
+The division is exact: `n((s-2)n - (s-4))` is even for every integer `n`
+(if `n` is even the first factor is; if `n` is odd, `(s-2)n - (s-4) =
+(s-2)(n-1) + 2` is even). Everything in the package is this one formula:
+
+- `s = 3` → triangular `n(n+1)/2`
+- `s = 4` → squares `n²`
+- `s = 5` → pentagonal `n(3n-1)/2`
+- `s = 6` → hexagonal `n(2n-1)`
+
+Named APIs (`triangular*`, `pentagonal*`) are one-line specializations of the
+general functions, not parallel implementations, so every general-path test
+covers them.
+
+### Domains
+
+| Quantity | Domain | Violation |
+| --- | --- | --- |
+| `s` (sides) | integer `>= 3` | `RangeError` |
+| `n` (index) | integer `>= 0` | `RangeError` |
+| `k` (generalized index) | any integer | — |
+| `x` (queried value) | any integer | negative → non-member (`false` / `null`) |
+| `number` inputs | safe integers only | `RangeError` (fractional, non-finite, or beyond ±(2^53 − 1)) |
+| non-numeric types | — | `TypeError` |
+
+Membership queries on negative `x` answer `false` rather than throwing: the
+question is well-posed and the answer is no. Domain errors (a 2-sided
+"polygon", a fractional index) throw, because the question itself is
+malformed. `polygonalFloorIndex` throws on `x < 0` since no index satisfies
+`P(s, n) <= x` there.
+
+## Inversion
+
+`P(s, n) = x` is a quadratic in `n`. With `a = s-2`, `b = s-4`:
+
+```
+n = (b + sqrt(D)) / 2a,   D = b² + 8ax
+```
+
+`x` is an `s`-gonal number iff `D` is a perfect square **and** `b + sqrt(D)`
+is divisible by `2a`. Both conditions are necessary: for `s = 5`, `x = 2`,
+`D = 49` is square but `(1+7)/6` is not an integer — `2` is not pentagonal.
+The second (negative) root is relevant only at `x = 0`, which is handled as
+the explicit index `0` before the discriminant path runs.
+
+The floor index (largest `n` with `P(s, n) <= x`) uses the same expression
+with `isqrt` in place of the exactness requirement. Because
+`isqrt(D) ∈ (sqrt(D) − 1, sqrt(D)]`, the computed candidate is off by at most
+one; a single guarded correction step on each side makes it exact.
+
+### Exact integer square root
+
+`isqrt` is Newton's method on BigInt, seeded with `2^ceil(bits/2)`
+(computed from the hexadecimal length — a power-of-two base, so conversion
+is linear). The seed is always `>= sqrt(x)`, which makes the iteration
+monotonically decreasing with a clean termination condition and no
+floating-point anywhere: correct at 10 bits and at 100,000 bits alike.
+
+### Residue pre-filters
+
+A perfect square's residue mod `m` must be a square mod `m`. Before any
+`isqrt`, the discriminant is checked against two precomputed tables:
+
+- mod 64 — one bitwise AND, passes 12/64 of uniform inputs;
+- mod 45045 = 9·5·7·11·13 — one BigInt modulo, passes ≈ 4.5%.
+
+Together ≈ 99% of uniform non-squares are refuted by table lookups, and the
+tables (64 + 45045 bytes, built once at module load) are the only
+allocations on the membership hot path; measured ≈ 4.9× over unconditional
+isqrt on random 128-bit non-members.
+
+## Generalized pentagonal numbers
+
+`g(k) = k(3k-1)/2` over all integers `k` — the exponent sequence of Euler's
+pentagonal number theorem, and the one place where a two-sided index is
+mathematically the right shape (OEIS A001318). The map is injective on ℤ:
+`g(k) = g(j)` forces `(k-j)(3(k+j) - 1) = 0` and the second factor is never
+zero, so `generalizedPentagonalIndex` returns a unique signed `k`, with
+`k > 0` exactly on the ordinary pentagonal numbers.
+
+Inversion: `24x + 1` must be a perfect square `r²`; then `r ≡ ±1 (mod 6)`
+automatically (odd squares are `1 mod 24`), and the branch is read off the
+residue: `r ≡ 5 (mod 6)` → `k = (r+1)/6`, `r ≡ 1 (mod 6)` → `k = (1-r)/6`.
+No divisibility check is needed — both branches always land on integers.
+
+The ascending iterator interleaves `k = 0, 1, -1, 2, -2, …` and advances
+additively: `g(-k) - g(k) = k` and `g(k+1) - g(-k) = 2k + 1`.
+
+## Iteration
+
+`polygonalNumbers` uses the first-difference recurrence
+
+```
+P(s, n+1) - P(s, n) = (s-2) n + 1
+```
+
+one BigInt addition per yielded value (plus one to advance the difference)
+after a single closed-form evaluation at `start`. This matters as operands
+grow: multiplication is super-linear in operand size, addition is linear.
+Generators are lazy and infinite unless bounded by `count` or the inclusive
+value bound `upTo`; both bounds compose.
+
+## Invariants (all executable in `test/`)
+
+- Round trip: `polygonalIndex(s, polygonal(s, n)) === n` for all valid inputs,
+  from `n = 0` to `n = 10^60`-scale.
+- Oracle agreement: membership, index, and floor index agree with a
+  brute-force additive enumeration for `s = 3..12`, every `x <= 20000`.
+- `isqrt` contract: `r² <= x < (r+1)²`, exhaustively to 65536 and by seeded
+  property tests to 4096 bits.
+- Near misses: `P(s, n) ± 1` is never a member (for `n >= 4`, where gaps
+  exceed 2), including at `10^30`–`10^60`-scale indices.
+- Identities: `T(n) + T(n-1) = n²`; `3·P₅(n) = T(3n-1)`; `P₆(n) = T(2n-1)`;
+  `P(s, n) = (s-2)·T(n-1) + n`; `P(s+1, n) - P(s, n) = T(n-1)`; and the
+  partition-counting recurrence of Euler's theorem reproduces `p(n)` up to
+  `n = 60` using this package's generalized pentagonal numbers.
+- Ordering: the generalized iterator equals the sorted closed-form values
+  and is strictly increasing after the initial 0.
+
+## Complexity
+
+Let `B` be the bit length of the value involved and `M(B)` the cost of a
+`B`-bit multiplication in the JS engine.
+
+| Operation | Cost |
+| --- | --- |
+| `polygonal` / `generalizedPentagonal` | `O(M(B))` |
+| `isPolygonal` / `polygonalIndex` (non-member, filtered) | `O(B)` expected — residue lookups dominate |
+| `isPolygonal` / `polygonalIndex` (member or filter survivor) | `O(M(B) log B)` — Newton isqrt |
+| `polygonalFloorIndex` | `O(M(B) log B)` |
+| iterator step | `O(B)` — one addition |
+
+## Rejected alternatives
+
+- **Float fast paths** (`Math.sqrt` seeding or full float inverses below
+  2^53): rejected. Two arithmetic regimes double the test surface and invite
+  the exact class of silent boundary bugs this package exists to rule out.
+  One exact path, uniformly.
+- **Silent `number` coercion**: rejected. Accepting `4.5` or `2^53` and
+  rounding would return confidently wrong answers; the contract is loud
+  rejection and BigInt as the primary domain.
+- **Bespoke per-family inverses** (dedicated triangular/pentagonal
+  formulas): rejected as implementations, kept as documentation. The general
+  derivation specializes to them exactly; one code path means the oracle
+  tests certify every family at once.
+- **Operations pretending closure** (adding/multiplying figurate numbers as
+  if the result were figurate): rejected as dishonest API shape. The
+  algebra that *is* real — identities across families — ships as executable
+  tests instead.
+- **A `start`-less generalized iterator**: rejected; the ascending order has
+  a natural position semantics (`0 → k=0`, `2j-1 → k=j`, `2j → k=-j`) that
+  makes resumption cheap and testable.
+- **Throwing on non-membership**: rejected in favor of `null` / `false`.
+  Non-membership is an ordinary answer, not an error; exceptions are
+  reserved for malformed questions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xyra Sinclair
+
+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,141 @@
+# figurate
+
+Exact arithmetic for figurate (polygonal) numbers over BigInt: evaluate,
+test membership, recover indices, and iterate — for triangular, pentagonal,
+generalized pentagonal, and every s-gonal family, at any magnitude.
+
+```sh
+npm install figurate
+```
+
+```js
+import {
+  triangular, isTriangular, triangularIndex,
+  pentagonal, pentagonalIndex,
+  polygonal, isPolygonal, polygonalIndex,
+  generalizedPentagonalNumbers,
+} from "figurate";
+
+triangular(100);                  // 5050n
+isTriangular(5050n);              // true
+triangularIndex(5050n);           // 100n
+pentagonal(10n ** 30n);           // 1499999999999999999999999999999500000000000000000000000000000n
+pentagonalIndex(9223372036854775807n); // null — 2^63 - 1 is not pentagonal
+polygonal(7, 10);                 // 235n — the 10th heptagonal number
+polygonalIndex(7, 235n);          // 10n
+[...generalizedPentagonalNumbers({ count: 8 })];
+// [0n, 1n, 2n, 5n, 7n, 12n, 15n, 22n]
+```
+
+Zero runtime dependencies. ESM, TypeScript declarations, Node >= 18.
+
+## Why this package
+
+Most figurate-number packages generate sequences with float arithmetic and
+stop there. `figurate` treats the s-gonal numbers as one algebraic object:
+
+- **One general construction.** Everything is `P(s, n) = ((s-2)n² - (s-4)n)/2`.
+  Triangular is `s = 3`, square is `s = 4`, pentagonal is `s = 5`; the named
+  APIs are specializations, not separate implementations.
+- **Exact at any magnitude.** All arithmetic is BigInt. `number` inputs are
+  accepted as a convenience but rejected with a `RangeError` when they are
+  fractional or outside the safe-integer range — never silently rounded.
+- **Inverses, not just generation.** Membership and index recovery solve the
+  quadratic exactly: the discriminant `(s-4)² + 8(s-2)x` must be a perfect
+  square (checked with an exact Newton integer square root) *and* the root
+  must land on an integer index. Quadratic-residue tables refute most
+  non-members without computing a square root at all.
+- **Stated boundary semantics.** `P(s, 0) = 0` and `P(s, 1) = 1` are members
+  of every family; negative values are members of none; indices are always
+  `>= 0` except the signed generalized-pentagonal index. Nothing here
+  pretends the figurate numbers are closed under ordinary arithmetic — sums
+  and products of members are generally not members, so the API exposes
+  evaluation, inversion, and iteration rather than fake "operations".
+
+## API
+
+All functions accept `bigint` or safe-integer `number` and return `bigint`.
+Invalid domains throw `RangeError`; wrong types throw `TypeError`.
+
+### General s-gonal (s ≥ 3)
+
+| Function | Meaning |
+| --- | --- |
+| `polygonal(s, n)` | `n`-th `s`-gonal number, `n >= 0` |
+| `isPolygonal(s, x)` | is `x` an `s`-gonal number? |
+| `polygonalIndex(s, x)` | the `n` with `polygonal(s, n) === x`, else `null` |
+| `polygonalFloorIndex(s, x)` | largest `n` with `polygonal(s, n) <= x` (`x >= 0`) — also the count of positive members `<= x` |
+| `polygonalNumbers(s, { start?, count?, upTo? })` | generator; additive recurrence, one addition per step |
+
+### Named families
+
+`triangular`, `isTriangular`, `triangularIndex`, `triangularFloorIndex`,
+`triangularNumbers` — and the same five for `pentagonal`. These delegate to
+the general construction with `s` fixed.
+
+### Generalized pentagonal (Euler)
+
+`g(k) = k(3k-1)/2` over all integers `k`, the exponents of Euler's pentagonal
+number theorem (OEIS A001318):
+
+| Function | Meaning |
+| --- | --- |
+| `generalizedPentagonal(k)` | `k` may be negative, zero, or positive |
+| `isGeneralizedPentagonal(x)` | membership |
+| `generalizedPentagonalIndex(x)` | the unique signed `k`, else `null` |
+| `generalizedPentagonalNumbers({ start?, count?, upTo? })` | ascending order `0, 1, 2, 5, 7, 12, 15, …` (`k = 0, 1, -1, 2, -2, …`); `start` is the position in this order |
+
+`k > 0` recovers exactly the ordinary pentagonal numbers; the map is
+injective over all of ℤ, so the signed index is unique.
+
+### Integer square root utilities
+
+| Function | Meaning |
+| --- | --- |
+| `isqrt(x)` | `floor(sqrt(x))`, exact for any `x >= 0` |
+| `sqrtExact(x)` | the exact root if `x` is a perfect square, else `null` |
+| `isPerfectSquare(x)` | boolean form of the above |
+
+### Generator options
+
+`start` (first index / position, default 0), `count` (maximum yields),
+`upTo` (inclusive value bound). With neither `count` nor `upTo` the
+generators are infinite — bound them before spreading.
+
+## Semantics worth knowing
+
+- Index origin is 0: `polygonal(s, 0) === 0n`. Prefer `{ start: 1 }` if you
+  want the classical `1, 3, 6, 10, …` without the leading zero.
+- `polygonalIndex` returns `null` for non-members (including all negatives);
+  it throws only for domain errors (`s < 3`, bad input types).
+- A perfect-square discriminant is necessary but not sufficient: for
+  `s = 5, x = 2` the discriminant is `49 = 7²` yet `2` is not pentagonal
+  (it is *generalized* pentagonal, `k = -1`). The divisibility check catches
+  this; tests pin it.
+
+## Performance
+
+Measured with `npm run bench` (Node 26, Apple Silicon; medians of 5 rounds):
+
+- Membership on random 128-bit non-members: ~126 ns/op — the residue tables
+  (mod 64 and mod 45045) refute ~99% of non-squares before any square root,
+  about 4.9× faster than an unconditional-isqrt implementation of the same
+  discriminant test.
+- Index recovery on ~200-bit members: ~0.8 µs/op, exact round trip.
+- `isqrt`: ~190 ns at 64 bits, ~2.3 µs at 1024 bits, ~0.5 ms at 32768 bits.
+- Sequence generation streams by additive recurrence (one BigInt addition
+  per step); at small magnitudes this is a modest ~1.2× over per-index
+  closed-form evaluation, and the gap grows with operand size.
+
+Numbers vary by machine; the benchmark script ships in `bench/` and compares
+only against direct formulas running in the same harness.
+
+## Design
+
+Formulas, domain proofs, invariants, complexity, and rejected alternatives
+are in [DESIGN.md](./DESIGN.md). The release checklist lives in
+[docs/canonicality.md](./docs/canonicality.md).
+
+## License
+
+MIT © Xyra Sinclair

package/dist/core.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Integer input accepted anywhere `figurate` takes an integer: a `bigint`, or
+ * a `number` that is a safe integer (`Number.isSafeInteger`). Fractional,
+ * non-finite, and unsafe-magnitude numbers are rejected with a `RangeError`
+ * rather than silently rounded; non-numeric types are rejected with a
+ * `TypeError`. All results are returned as `bigint`.
+ */
+export type IntLike = bigint | number;
+/** Options shared by the sequence generators. */
+export interface SequenceOptions {
+    /**
+     * Index (for `polygonalNumbers` and friends) or ascending position (for
+     * `generalizedPentagonalNumbers`) of the first value yielded. Default `0`.
+     */
+    start?: IntLike;
+    /** Maximum count of values to yield. Omit for no count limit. */
+    count?: IntLike;
+    /**
+     * Inclusive upper bound on yielded values; the generator returns as soon as
+     * the next value would exceed it. Omit for no value limit.
+     */
+    upTo?: IntLike;
+}
+export declare function toBigInt(value: IntLike, name: string): bigint;
+export declare function toSides(s: IntLike): bigint;
+export declare function toIndex(n: IntLike, name?: string): bigint;

package/dist/core.js

@@ -0,0 +1,28 @@
+export function toBigInt(value, name) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new RangeError(`${name} must be an integer; got ${value}`);
+        }
+        if (!Number.isSafeInteger(value)) {
+            throw new RangeError(`${name} = ${value} is outside Number's safe-integer range; pass a bigint instead`);
+        }
+        return BigInt(value);
+    }
+    throw new TypeError(`${name} must be a bigint or a safe-integer number; got ${typeof value}`);
+}
+export function toSides(s) {
+    const v = toBigInt(s, "sides");
+    if (v < 3n) {
+        throw new RangeError(`sides must be >= 3; got ${v}`);
+    }
+    return v;
+}
+export function toIndex(n, name = "n") {
+    const v = toBigInt(n, name);
+    if (v < 0n) {
+        throw new RangeError(`${name} must be >= 0; got ${v}`);
+    }
+    return v;
+}

package/dist/generalized.d.ts

@@ -0,0 +1,28 @@
+import { type IntLike, type SequenceOptions } from "./core.js";
+/**
+ * The generalized pentagonal number `g(k) = k(3k-1)/2` for any integer `k`,
+ * positive, zero, or negative. These are the exponents in Euler's pentagonal
+ * number theorem; in ascending order (`k = 0, 1, -1, 2, -2, ...`) they run
+ * `0, 1, 2, 5, 7, 12, 15, 22, 26, ...` (OEIS A001318).
+ *
+ * The map is injective over all of `Z`: `g(k) = g(j)` forces
+ * `(k - j)(3(k + j) - 1) = 0`, and `3(k + j) = 1` has no integer solution.
+ */
+export declare function generalizedPentagonal(k: IntLike): bigint;
+/**
+ * The unique integer `k` (possibly negative) with
+ * `generalizedPentagonal(k) === x`, or `null` if `x` is not a generalized
+ * pentagonal number. `k > 0` means `x` is also an ordinary pentagonal number.
+ */
+export declare function generalizedPentagonalIndex(x: IntLike): bigint | null;
+/** Whether `x` is a generalized pentagonal number. */
+export declare function isGeneralizedPentagonal(x: IntLike): boolean;
+/**
+ * Yields generalized pentagonal numbers in ascending order — the canonical
+ * `k = 0, 1, -1, 2, -2, ...` interleaving. `start` is the position in this
+ * ascending order (position `0` is `g(0) = 0`, position `2j-1` is `g(j)`,
+ * position `2j` is `g(-j)`); `count` and `upTo` behave as in
+ * `polygonalNumbers`. Steps are additive: `g(-j) - g(j) = j` and
+ * `g(j+1) - g(-j) = 2j + 1`.
+ */
+export declare function generalizedPentagonalNumbers(options?: SequenceOptions): Generator<bigint, void, void>;

package/dist/generalized.js

@@ -0,0 +1,81 @@
+import { toBigInt } from "./core.js";
+import { sqrtExactBig } from "./isqrt.js";
+import { normalizeSequenceOptions } from "./polygonal.js";
+/**
+ * The generalized pentagonal number `g(k) = k(3k-1)/2` for any integer `k`,
+ * positive, zero, or negative. These are the exponents in Euler's pentagonal
+ * number theorem; in ascending order (`k = 0, 1, -1, 2, -2, ...`) they run
+ * `0, 1, 2, 5, 7, 12, 15, 22, 26, ...` (OEIS A001318).
+ *
+ * The map is injective over all of `Z`: `g(k) = g(j)` forces
+ * `(k - j)(3(k + j) - 1) = 0`, and `3(k + j) = 1` has no integer solution.
+ */
+export function generalizedPentagonal(k) {
+    const K = toBigInt(k, "k");
+    return (K * (3n * K - 1n)) / 2n;
+}
+/** Internal: signed-index inverse on an already-validated bigint. */
+function generalizedPentagonalIndexOf(x) {
+    if (x < 0n)
+        return null;
+    // x = k(3k-1)/2 iff 24x + 1 = (6k - 1)^2. If r = sqrt(24x + 1) exists it
+    // is odd with r^2 = 1 (mod 24), so r = 1 or 5 (mod 6): r = 5 (mod 6) gives
+    // the positive branch k = (r+1)/6, r = 1 (mod 6) the branch k = (1-r)/6.
+    const r = sqrtExactBig(24n * x + 1n);
+    if (r === null)
+        return null;
+    return r % 6n === 5n ? (r + 1n) / 6n : (1n - r) / 6n;
+}
+/**
+ * The unique integer `k` (possibly negative) with
+ * `generalizedPentagonal(k) === x`, or `null` if `x` is not a generalized
+ * pentagonal number. `k > 0` means `x` is also an ordinary pentagonal number.
+ */
+export function generalizedPentagonalIndex(x) {
+    return generalizedPentagonalIndexOf(toBigInt(x, "x"));
+}
+/** Whether `x` is a generalized pentagonal number. */
+export function isGeneralizedPentagonal(x) {
+    return generalizedPentagonalIndexOf(toBigInt(x, "x")) !== null;
+}
+/**
+ * Yields generalized pentagonal numbers in ascending order — the canonical
+ * `k = 0, 1, -1, 2, -2, ...` interleaving. `start` is the position in this
+ * ascending order (position `0` is `g(0) = 0`, position `2j-1` is `g(j)`,
+ * position `2j` is `g(-j)`); `count` and `upTo` behave as in
+ * `polygonalNumbers`. Steps are additive: `g(-j) - g(j) = j` and
+ * `g(j+1) - g(-j) = 2j + 1`.
+ */
+export function* generalizedPentagonalNumbers(options = {}) {
+    const { start, count, upTo } = normalizeSequenceOptions(options);
+    // Decode the start position into (j, onPositiveBranch) and one closed-form
+    // evaluation; every later value is one or two bigint additions away.
+    let j = start === 0n ? 0n : (start + 1n) >> 1n;
+    let onPos = start !== 0n && (start & 1n) === 1n;
+    let value = j === 0n
+        ? 0n
+        : onPos
+            ? (j * (3n * j - 1n)) / 2n
+            : (j * (3n * j + 1n)) / 2n;
+    let emitted = 0n;
+    while (count === null || emitted < count) {
+        if (upTo !== null && value > upTo)
+            return;
+        yield value;
+        emitted += 1n;
+        if (j === 0n) {
+            j = 1n;
+            onPos = true;
+            value = 1n;
+        }
+        else if (onPos) {
+            value += j; // g(j) -> g(-j)
+            onPos = false;
+        }
+        else {
+            value += 2n * j + 1n; // g(-j) -> g(j+1)
+            j += 1n;
+            onPos = true;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { IntLike, SequenceOptions } from "./core.js";
+export { isPerfectSquare, isqrt, sqrtExact } from "./isqrt.js";
+export { isPolygonal, polygonal, polygonalFloorIndex, polygonalIndex, polygonalNumbers, } from "./polygonal.js";
+export { isTriangular, triangular, triangularFloorIndex, triangularIndex, triangularNumbers, } from "./triangular.js";
+export { isPentagonal, pentagonal, pentagonalFloorIndex, pentagonalIndex, pentagonalNumbers, } from "./pentagonal.js";
+export { generalizedPentagonal, generalizedPentagonalIndex, generalizedPentagonalNumbers, isGeneralizedPentagonal, } from "./generalized.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { isPerfectSquare, isqrt, sqrtExact } from "./isqrt.js";
+export { isPolygonal, polygonal, polygonalFloorIndex, polygonalIndex, polygonalNumbers, } from "./polygonal.js";
+export { isTriangular, triangular, triangularFloorIndex, triangularIndex, triangularNumbers, } from "./triangular.js";
+export { isPentagonal, pentagonal, pentagonalFloorIndex, pentagonalIndex, pentagonalNumbers, } from "./pentagonal.js";
+export { generalizedPentagonal, generalizedPentagonalIndex, generalizedPentagonalNumbers, isGeneralizedPentagonal, } from "./generalized.js";

package/dist/isqrt.d.ts

@@ -0,0 +1,22 @@
+import { type IntLike } from "./core.js";
+/**
+ * Floor of the exact integer square root of a non-negative integer.
+ *
+ * Newton's method on bigints, seeded with `2^ceil(bits/2)` which is always
+ * `>= sqrt(x)`, so the iteration decreases monotonically and stops at
+ * `floor(sqrt(x))` after O(log bits) steps. Exact at any magnitude; never
+ * routes through floating point.
+ *
+ * @throws RangeError if `x < 0` or `x` is not a valid integer input.
+ */
+export declare function isqrt(x: IntLike): bigint;
+/** Internal: `sqrtExact` on an already-validated bigint. */
+export declare function sqrtExactBig(n: bigint): bigint | null;
+/**
+ * The exact integer square root of `x` if `x` is a perfect square, otherwise
+ * `null`. Negative inputs return `null` (they are never perfect squares).
+ * Non-squares are usually refuted by residue tables without an isqrt.
+ */
+export declare function sqrtExact(x: IntLike): bigint | null;
+/** Whether `x` is a perfect square. Equivalent to `sqrtExact(x) !== null`. */
+export declare function isPerfectSquare(x: IntLike): boolean;

package/dist/isqrt.js

@@ -0,0 +1,75 @@
+import { toBigInt } from "./core.js";
+/**
+ * Quadratic-residue tables for fast perfect-square rejection. A perfect
+ * square's residue mod m must itself be a square mod m, so a table lookup
+ * refutes most non-squares without computing an integer square root.
+ *
+ * mod 64 is a single bitwise AND and rejects 52/64 of uniform non-squares;
+ * mod 45045 = 9*5*7*11*13 costs one bigint modulo and cuts the survivors to
+ * about 4.5%. Together roughly 99% of uniform non-squares never reach isqrt.
+ */
+function residueTable(m) {
+    const t = new Uint8Array(m);
+    for (let i = 0; i < m; i++)
+        t[(i * i) % m] = 1;
+    return t;
+}
+const SQ_MOD_64 = residueTable(64);
+const SQ_MOD_45045 = residueTable(45045);
+/**
+ * Bit length of a positive bigint. Hexadecimal conversion is linear in the
+ * operand size (base 16 is a power of two), unlike decimal conversion.
+ */
+function bitLength(x) {
+    const hex = x.toString(16);
+    const top = parseInt(hex[0], 16);
+    return BigInt((hex.length - 1) * 4 + (32 - Math.clz32(top)));
+}
+/**
+ * Floor of the exact integer square root of a non-negative integer.
+ *
+ * Newton's method on bigints, seeded with `2^ceil(bits/2)` which is always
+ * `>= sqrt(x)`, so the iteration decreases monotonically and stops at
+ * `floor(sqrt(x))` after O(log bits) steps. Exact at any magnitude; never
+ * routes through floating point.
+ *
+ * @throws RangeError if `x < 0` or `x` is not a valid integer input.
+ */
+export function isqrt(x) {
+    const n = toBigInt(x, "x");
+    if (n < 0n) {
+        throw new RangeError(`isqrt is undefined for negative inputs; got ${n}`);
+    }
+    if (n < 2n)
+        return n;
+    let r = 1n << ((bitLength(n) + 1n) >> 1n);
+    let next = (r + n / r) >> 1n;
+    while (next < r) {
+        r = next;
+        next = (r + n / r) >> 1n;
+    }
+    return r;
+}
+/** Internal: `sqrtExact` on an already-validated bigint. */
+export function sqrtExactBig(n) {
+    if (n < 0n)
+        return null;
+    if (SQ_MOD_64[Number(n & 63n)] === 0)
+        return null;
+    if (SQ_MOD_45045[Number(n % 45045n)] === 0)
+        return null;
+    const r = isqrt(n);
+    return r * r === n ? r : null;
+}
+/**
+ * The exact integer square root of `x` if `x` is a perfect square, otherwise
+ * `null`. Negative inputs return `null` (they are never perfect squares).
+ * Non-squares are usually refuted by residue tables without an isqrt.
+ */
+export function sqrtExact(x) {
+    return sqrtExactBig(toBigInt(x, "x"));
+}
+/** Whether `x` is a perfect square. Equivalent to `sqrtExact(x) !== null`. */
+export function isPerfectSquare(x) {
+    return sqrtExactBig(toBigInt(x, "x")) !== null;
+}

package/dist/pentagonal.d.ts

@@ -0,0 +1,21 @@
+import { type IntLike, type SequenceOptions } from "./core.js";
+/**
+ * The `n`-th pentagonal number, `P(n) = n(3n-1)/2 = polygonal(5, n)`.
+ * The discriminant specializes to `24x + 1`.
+ */
+export declare function pentagonal(n: IntLike): bigint;
+/**
+ * Whether `x` is a pentagonal number, i.e. `24x + 1` is a perfect square
+ * whose root is `5 (mod 6)` (or `x` is 0). Only non-negative indices count;
+ * for the two-sided family see `isGeneralizedPentagonal`.
+ */
+export declare function isPentagonal(x: IntLike): boolean;
+/**
+ * The index `n >= 0` with `pentagonal(n) === x`, or `null` if `x` is not
+ * pentagonal.
+ */
+export declare function pentagonalIndex(x: IntLike): bigint | null;
+/** The largest `n >= 0` with `pentagonal(n) <= x`. Requires `x >= 0`. */
+export declare function pentagonalFloorIndex(x: IntLike): bigint;
+/** Yields pentagonal numbers; see `polygonalNumbers` for option semantics. */
+export declare function pentagonalNumbers(options?: SequenceOptions): Generator<bigint, void, void>;

package/dist/pentagonal.js

@@ -0,0 +1,32 @@
+import {} from "./core.js";
+import { isPolygonal, polygonal, polygonalFloorIndex, polygonalIndex, polygonalNumbers, } from "./polygonal.js";
+/**
+ * The `n`-th pentagonal number, `P(n) = n(3n-1)/2 = polygonal(5, n)`.
+ * The discriminant specializes to `24x + 1`.
+ */
+export function pentagonal(n) {
+    return polygonal(5n, n);
+}
+/**
+ * Whether `x` is a pentagonal number, i.e. `24x + 1` is a perfect square
+ * whose root is `5 (mod 6)` (or `x` is 0). Only non-negative indices count;
+ * for the two-sided family see `isGeneralizedPentagonal`.
+ */
+export function isPentagonal(x) {
+    return isPolygonal(5n, x);
+}
+/**
+ * The index `n >= 0` with `pentagonal(n) === x`, or `null` if `x` is not
+ * pentagonal.
+ */
+export function pentagonalIndex(x) {
+    return polygonalIndex(5n, x);
+}
+/** The largest `n >= 0` with `pentagonal(n) <= x`. Requires `x >= 0`. */
+export function pentagonalFloorIndex(x) {
+    return polygonalFloorIndex(5n, x);
+}
+/** Yields pentagonal numbers; see `polygonalNumbers` for option semantics. */
+export function pentagonalNumbers(options = {}) {
+    return polygonalNumbers(5n, options);
+}

package/dist/polygonal.d.ts

@@ -0,0 +1,54 @@
+import { type IntLike, type SequenceOptions } from "./core.js";
+/** Internal: P(s, n) on already-validated bigints. */
+export declare function polygonalOf(s: bigint, n: bigint): bigint;
+/**
+ * The `n`-th `s`-gonal number, `P(s, n) = ((s-2)n^2 - (s-4)n) / 2`.
+ *
+ * Domains: `s >= 3`, `n >= 0`. `P(s, 0) = 0` and `P(s, 1) = 1` for every
+ * family; `P(s, 2) = s`.
+ *
+ * @throws RangeError if `s < 3`, `n < 0`, or an input is not a valid integer.
+ */
+export declare function polygonal(s: IntLike, n: IntLike): bigint;
+/** Internal: inverse on already-validated bigints. */
+export declare function polygonalIndexOf(s: bigint, x: bigint): bigint | null;
+/**
+ * The index `n >= 0` with `polygonal(s, n) === x`, or `null` if `x` is not an
+ * `s`-gonal number. Negative `x` returns `null`. Exact at any magnitude: the
+ * discriminant `(s-4)^2 + 8(s-2)x` must be a perfect square and the root must
+ * land on an integer index.
+ *
+ * @throws RangeError if `s < 3` or an input is not a valid integer.
+ */
+export declare function polygonalIndex(s: IntLike, x: IntLike): bigint | null;
+/**
+ * Whether `x` is an `s`-gonal number. `0` and `1` are members of every
+ * family (indices 0 and 1); negative `x` is never a member.
+ *
+ * @throws RangeError if `s < 3` or an input is not a valid integer.
+ */
+export declare function isPolygonal(s: IntLike, x: IntLike): boolean;
+/**
+ * The largest index `n >= 0` with `polygonal(s, n) <= x`, i.e. the count of
+ * positive `s`-gonal numbers `<= x`. Requires `x >= 0` (every `n` satisfies
+ * `polygonal(s, n) > x` when `x < 0`, so no floor index exists).
+ *
+ * @throws RangeError if `s < 3`, `x < 0`, or an input is not a valid integer.
+ */
+export declare function polygonalFloorIndex(s: IntLike, x: IntLike): bigint;
+export declare function normalizeSequenceOptions(options: SequenceOptions): {
+    start: bigint;
+    count: bigint | null;
+    upTo: bigint | null;
+};
+/**
+ * Yields `s`-gonal numbers `polygonal(s, n)` for `n = start, start+1, ...`,
+ * bounded by `count` and/or the inclusive value bound `upTo`. With neither
+ * bound the generator is infinite. Values are produced by the additive
+ * recurrence `P(s, n+1) - P(s, n) = (s-2)n + 1` — one bigint addition per
+ * step after a single closed-form evaluation at `start`.
+ *
+ * @throws RangeError if `s < 3`, `start < 0`, `count < 0`, or an input is not
+ * a valid integer.
+ */
+export declare function polygonalNumbers(s: IntLike, options?: SequenceOptions): Generator<bigint, void, void>;

package/dist/polygonal.js

@@ -0,0 +1,116 @@
+import { toBigInt, toIndex, toSides, } from "./core.js";
+import { isqrt, sqrtExactBig } from "./isqrt.js";
+/** Internal: P(s, n) on already-validated bigints. */
+export function polygonalOf(s, n) {
+    // n((s-2)n - (s-4)) is always even: n even makes it even, and n odd makes
+    // (s-2)n - (s-4) = (s-2)(n-1) + 2 even, so the division by 2 is exact.
+    return ((s - 2n) * n * n - (s - 4n) * n) / 2n;
+}
+/**
+ * The `n`-th `s`-gonal number, `P(s, n) = ((s-2)n^2 - (s-4)n) / 2`.
+ *
+ * Domains: `s >= 3`, `n >= 0`. `P(s, 0) = 0` and `P(s, 1) = 1` for every
+ * family; `P(s, 2) = s`.
+ *
+ * @throws RangeError if `s < 3`, `n < 0`, or an input is not a valid integer.
+ */
+export function polygonal(s, n) {
+    return polygonalOf(toSides(s), toIndex(n));
+}
+/** Internal: inverse on already-validated bigints. */
+export function polygonalIndexOf(s, x) {
+    if (x < 0n)
+        return null;
+    if (x === 0n)
+        return 0n; // the quadratic's other root; not on the + branch
+    // Solve (s-2)n^2 - (s-4)n - 2x = 0 for the positive root:
+    // n = ((s-4) + sqrt(D)) / (2(s-2)) with D = (s-4)^2 + 8(s-2)x.
+    const a = s - 2n;
+    const b = s - 4n;
+    const r = sqrtExactBig(b * b + 8n * a * x);
+    if (r === null)
+        return null;
+    const numerator = b + r;
+    const denominator = 2n * a;
+    if (numerator % denominator !== 0n)
+        return null;
+    return numerator / denominator;
+}
+/**
+ * The index `n >= 0` with `polygonal(s, n) === x`, or `null` if `x` is not an
+ * `s`-gonal number. Negative `x` returns `null`. Exact at any magnitude: the
+ * discriminant `(s-4)^2 + 8(s-2)x` must be a perfect square and the root must
+ * land on an integer index.
+ *
+ * @throws RangeError if `s < 3` or an input is not a valid integer.
+ */
+export function polygonalIndex(s, x) {
+    return polygonalIndexOf(toSides(s), toBigInt(x, "x"));
+}
+/**
+ * Whether `x` is an `s`-gonal number. `0` and `1` are members of every
+ * family (indices 0 and 1); negative `x` is never a member.
+ *
+ * @throws RangeError if `s < 3` or an input is not a valid integer.
+ */
+export function isPolygonal(s, x) {
+    return polygonalIndexOf(toSides(s), toBigInt(x, "x")) !== null;
+}
+/**
+ * The largest index `n >= 0` with `polygonal(s, n) <= x`, i.e. the count of
+ * positive `s`-gonal numbers `<= x`. Requires `x >= 0` (every `n` satisfies
+ * `polygonal(s, n) > x` when `x < 0`, so no floor index exists).
+ *
+ * @throws RangeError if `s < 3`, `x < 0`, or an input is not a valid integer.
+ */
+export function polygonalFloorIndex(s, x) {
+    const S = toSides(s);
+    const X = toBigInt(x, "x");
+    if (X < 0n) {
+        throw new RangeError(`x must be >= 0 for a floor index; got ${X}`);
+    }
+    if (X === 0n)
+        return 0n;
+    const a = S - 2n;
+    const b = S - 4n;
+    // isqrt floors the real sqrt, so m is floor(real root) or one below it;
+    // b + isqrt(D) >= 0 for all s >= 3, so bigint division here is a floor.
+    let m = (b + isqrt(b * b + 8n * a * X)) / (2n * a);
+    while (polygonalOf(S, m + 1n) <= X)
+        m += 1n;
+    while (m > 0n && polygonalOf(S, m) > X)
+        m -= 1n;
+    return m;
+}
+export function normalizeSequenceOptions(options) {
+    const start = toIndex(options.start ?? 0n, "start");
+    const count = options.count === undefined ? null : toIndex(options.count, "count");
+    const upTo = options.upTo === undefined ? null : toBigInt(options.upTo, "upTo");
+    return { start, count, upTo };
+}
+/**
+ * Yields `s`-gonal numbers `polygonal(s, n)` for `n = start, start+1, ...`,
+ * bounded by `count` and/or the inclusive value bound `upTo`. With neither
+ * bound the generator is infinite. Values are produced by the additive
+ * recurrence `P(s, n+1) - P(s, n) = (s-2)n + 1` — one bigint addition per
+ * step after a single closed-form evaluation at `start`.
+ *
+ * @throws RangeError if `s < 3`, `start < 0`, `count < 0`, or an input is not
+ * a valid integer.
+ */
+export function* polygonalNumbers(s, options = {}) {
+    const S = toSides(s);
+    const { start, count, upTo } = normalizeSequenceOptions(options);
+    const step = S - 2n;
+    let value = polygonalOf(S, start);
+    let delta = step * start + 1n;
+    let emitted = 0n;
+    while (count === null || emitted < count) {
+        if (upTo !== null && value > upTo)
+            return;
+        yield value;
+        emitted += 1n;
+        value += delta;
+        delta += step;
+    }
+}

package/dist/triangular.d.ts

@@ -0,0 +1,17 @@
+import { type IntLike, type SequenceOptions } from "./core.js";
+/**
+ * The `n`-th triangular number, `T(n) = n(n+1)/2 = polygonal(3, n)`.
+ * The discriminant specializes to `8x + 1`.
+ */
+export declare function triangular(n: IntLike): bigint;
+/** Whether `x` is a triangular number, i.e. `8x + 1` is a perfect square. */
+export declare function isTriangular(x: IntLike): boolean;
+/**
+ * The index `n >= 0` with `triangular(n) === x`, or `null` if `x` is not
+ * triangular.
+ */
+export declare function triangularIndex(x: IntLike): bigint | null;
+/** The largest `n >= 0` with `triangular(n) <= x`. Requires `x >= 0`. */
+export declare function triangularFloorIndex(x: IntLike): bigint;
+/** Yields triangular numbers; see `polygonalNumbers` for option semantics. */
+export declare function triangularNumbers(options?: SequenceOptions): Generator<bigint, void, void>;

package/dist/triangular.js

@@ -0,0 +1,28 @@
+import {} from "./core.js";
+import { isPolygonal, polygonal, polygonalFloorIndex, polygonalIndex, polygonalNumbers, } from "./polygonal.js";
+/**
+ * The `n`-th triangular number, `T(n) = n(n+1)/2 = polygonal(3, n)`.
+ * The discriminant specializes to `8x + 1`.
+ */
+export function triangular(n) {
+    return polygonal(3n, n);
+}
+/** Whether `x` is a triangular number, i.e. `8x + 1` is a perfect square. */
+export function isTriangular(x) {
+    return isPolygonal(3n, x);
+}
+/**
+ * The index `n >= 0` with `triangular(n) === x`, or `null` if `x` is not
+ * triangular.
+ */
+export function triangularIndex(x) {
+    return polygonalIndex(3n, x);
+}
+/** The largest `n >= 0` with `triangular(n) <= x`. Requires `x >= 0`. */
+export function triangularFloorIndex(x) {
+    return polygonalFloorIndex(3n, x);
+}
+/** Yields triangular numbers; see `polygonalNumbers` for option semantics. */
+export function triangularNumbers(options = {}) {
+    return polygonalNumbers(3n, options);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "figurate",
+  "version": "1.0.0",
+  "description": "Exact BigInt arithmetic for figurate (polygonal) numbers: forward evaluation, membership, index recovery, and iterators for triangular, pentagonal, generalized pentagonal, and every s-gonal family.",
+  "keywords": [
+    "figurate",
+    "polygonal",
+    "triangular",
+    "pentagonal",
+    "generalized-pentagonal",
+    "bigint",
+    "exact",
+    "integer-square-root",
+    "number-theory",
+    "math"
+  ],
+  "license": "MIT",
+  "author": "Xyra Sinclair",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XyraSinclair/figurate.git"
+  },
+  "homepage": "https://github.com/XyraSinclair/figurate#readme",
+  "bugs": {
+    "url": "https://github.com/XyraSinclair/figurate/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "DESIGN.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test build/test/*.test.js",
+    "bench": "npm run build && node bench/run.mjs",
+    "smoke": "bash scripts/smoke.sh",
+    "release": "npm publish --access public",
+    "prepublishOnly": "npm test && npm run smoke"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.130",
+    "typescript": "^5.5.0"
+  }
+}