continuedfraction.js 0.0.1 → 0.1.0

package/LICENSE

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

@@ -4,7 +4,9 @@
 [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
 
 
-A lightweight JavaScript library sitting on the shoulders of [Fraction.js](https://github.com/rawify/Fraction.js) for generating and evaluating **standard** and **generalized** continued fractions. It is built with generator-based sequences and convergent recurrences for fast execution.
+ContinuedFraction.js is published as [`continuedfraction.js`](https://www.npmjs.com/package/continuedfraction.js). It generates simple and generalized continued fractions and evaluates a bounded number of terms to an exact [Fraction.js](https://github.com/rawify/Fraction.js) convergent.
+
+Use it to inspect continued-fraction terms or construct rational approximations of square roots, real values, rational values, φ, e, π, and 4/π. Use Fraction.js directly when the input is already rational and no term sequence is needed. It is not an arbitrary-precision transcendental-function package: each result is a rational convergent chosen by the requested term count.
 
 ## Features
 
@@ -12,15 +14,19 @@ A lightweight JavaScript library sitting on the shoulders of [Fraction.js](https
 - Convert any real number or rational to its continued‑fraction
 - Infinite generators for classic constants: φ (golden ratio), e, π, 4/π
 - Evaluate (simple or generalized) continued fractions to a `Fraction`
+- Enumerate exact convergents or collect a bounded number of terms
+- Strict TypeScript types for terms, sources, and coefficients
 
-## Example
+## Quick example
+
+```javascript
+import ContinuedFraction from 'continuedfraction.js';
 
-```js
 const frac = ContinuedFraction.eval(
   ContinuedFraction.fromFraction(3021, 203),
-  10 // Max Steps
+  10
 );
-console.log(frac.toString()); // → "3021/203"
+console.log(frac.toFraction()); // "3021/203"
 ```
 
 ## Installation
@@ -43,27 +49,115 @@ Alternatively, download or clone the repository:
 git clone https://github.com/rawify/ContinuedFraction.js
 ```
 
-## Usage
+## Usage and runtime
+
+`ContinuedFraction` is a static class and cannot be instantiated. Use its methods directly.
+
+### CommonJS
+
+```javascript
+const ContinuedFraction = require('continuedfraction.js');
+const terms = ContinuedFraction.toArray(ContinuedFraction.sqrt(2), 8);
+```
+
+### ES modules
+
+```javascript
+import ContinuedFraction, { ContinuedFraction as NamedContinuedFraction } from 'continuedfraction.js';
+const terms = ContinuedFraction.toArray(ContinuedFraction.sqrt(2), 8);
+```
 
-Include the `continuedfraction.min.js` file in your project:
+### Standalone browser script
 
 ```html
-<script src="path/to/continuedfraction.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/continuedfraction.js@0.1.0/dist/continuedfraction.min.js"></script>
 <script>
-  var x = ContinuedFraction.sqrt(2);
+  const terms = ContinuedFraction.toArray(ContinuedFraction.sqrt(2), 8);
 </script>
 ```
 
-Or in a Node.js project:
+### Native browser module
+
+```html
+<script type="module">
+  import ContinuedFraction from 'https://cdn.jsdelivr.net/npm/continuedfraction.js@0.1.0/dist/continuedfraction.mjs';
+  const terms = ContinuedFraction.toArray(ContinuedFraction.sqrt(2), 8);
+</script>
+```
+
+The package supports Node.js 20 or newer. Its CommonJS build uses the declared Fraction.js dependency; the ESM and standalone browser builds are self-contained. CommonJS also exposes `.default` and `.ContinuedFraction` aliases for compatibility.
+
+## Recipes
+
+### Approximate an irrational square root
+
+`sqrt()` generates the periodic simple continued fraction; `eval()` consumes at most the requested number of terms.
 
 ```javascript
-const ContinuedFraction = require('continuedfraction.js');
+import ContinuedFraction from 'continuedfraction.js';
+
+const approximation = ContinuedFraction.eval(
+  ContinuedFraction.sqrt(2),
+  8
+);
+
+console.log(approximation.toFraction()); // "577/408"
+console.log(approximation.valueOf());    // 1.4142156862745099
+```
+
+`sqrt(N)` expects a non-negative safe integer and throws `RangeError` otherwise. Perfect squares terminate after one term; non-squares produce an infinite generator.
+
+### Inspect and reconstruct a rational value
+
+Rational expansions terminate. Fraction.js represents their terms as `BigInt`, so convert them before JSON serialization when the values are known to fit safely in `Number`.
+
+```javascript
+import ContinuedFraction from 'continuedfraction.js';
+
+const terms = [...ContinuedFraction.fromFraction(415, 93)];
+const restored = ContinuedFraction.eval(
+  ContinuedFraction.fromFraction(415, 93),
+  10
+);
+
+console.log(terms.map(Number));       // [4, 2, 6, 7]
+console.log(restored.toFraction());  // "415/93"
+```
+
+Do not convert large `BigInt` terms to `Number` unless they are within the safe-integer range.
+
+### Build convergents for e and a perfect square
+
+Generator functions can be passed directly to `eval()`. This creates a new generator for each evaluation.
+
+```javascript
+import ContinuedFraction from 'continuedfraction.js';
+
+const e = ContinuedFraction.eval(ContinuedFraction.E, 10);
+const squareTerms = [...ContinuedFraction.sqrt(49)];
+
+console.log(e.toFraction());       // "1457/536"
+console.log(squareTerms.map(Number)); // [7]
 ```
 
-or
+Always bound iteration over `E()`, `PHI()`, `PI()`, `FOUR_OVER_PI()`, or a non-square `sqrt()` generator. Spreading an infinite generator never completes.
+
+### Inspect every convergent
+
+`convergents()` yields exact Fraction.js values lazily. `fromTerms()` turns an existing sequence into a generator, while `toArray()` safely collects a bounded prefix.
 
 ```javascript
 import ContinuedFraction from 'continuedfraction.js';
+
+const convergents = ContinuedFraction.toArray(
+  ContinuedFraction.convergents(
+    ContinuedFraction.fromTerms([1, 2, 2, 2])
+  ),
+  4
+);
+
+console.log(convergents.map((value) => value.toFraction()));
+// ["1", "3/2", "7/5", "17/12"]
 ```
 
 ## ContinuedFraction API
@@ -75,30 +169,40 @@ Import the static utility class and use its generators and evaluator:
 const sqrtGen = ContinuedFraction.sqrt(23);
 console.log(sqrtGen.next().value); // 4
 console.log(sqrtGen.next().value); // 1, 3, 1, 8, …
+```
 
+```javascript
 // 2) Continued‑fraction of a decimal
 let cnt = 0;
 for (let piCf of ContinuedFraction.fromNumber(Math.PI)) {
   console.log(piCf);
   if (cnt++ >= 10) break;
 }
+```
 
+```javascript
 // 3) Golden ratio φ terms
 const phiGen = ContinuedFraction.PHI();
 console.log(phiGen.next().value); // 1, and forever 1…
+```
 
+```javascript
 // 4) Evaluate the first 10 terms of e’s CF to a Fraction
 const approxE = ContinuedFraction.eval(ContinuedFraction.E, 10);
-console.log(approxE.toString()); // e ≈ “193/71”
+console.log(approxE.toFraction()); // "1457/536"
+```
 
+```javascript
 // 5) Generalized CF for π, 4/π
 const genPi = ContinuedFraction.PI();
 console.log(genPi.next().value);   // { a: 3, b: 0 }
 console.log(genPi.next().value);   // { a: 6, b: 1 }
+```
 
+```javascript
 // 6) Continued‑fraction from two integers
 const halfCf = ContinuedFraction.fromFraction(1, 2);
-console.log([...halfCf]); // [0, 2]
+console.log([...halfCf]); // [0n, 2n]
 ```
 
 ### Methods
@@ -106,28 +210,35 @@ console.log([...halfCf]); // [0, 2]
 | Method                   | Signature                                                         | Description                                                             |
 | ------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
 | `sqrt(N: number)`        | `Generator<number>`                                               | Simple CF terms of √N                                                   |
-| `fromNumber(n)`          | `Generator<number>`                                               | CF terms of any real via Fraction.js                                    |
-| `fromFraction(a, b)`     | `Generator<number>`                                               | CF terms of the rational a/b                                            |
+| `fromNumber(n)`          | `Generator<bigint>`                                               | CF terms of any real via Fraction.js                                    |
+| `fromFraction(a, b?)`    | `Generator<bigint>`                                               | CF terms of a rational value or a/b                                     |
+| `fromTerms(terms)`       | `Generator<Term>`                                                 | Yield an existing finite or infinite term sequence                      |
 | `PHI()`                  | `Generator<number>`                                               | Infinite 1’s for the golden ratio                                       |
 | `FOUR_OVER_PI()`         | `Generator<CFTerm>`                                               | Generalized CF terms for 4/π                                            |
 | `PI()`                   | `Generator<CFTerm>`                                               | Generalized CF terms for π                                              |
 | `E()`                    | `Generator<number>`                                               | CF expansion of e                                                       |
-| `eval(generator, steps)` | `(Generator|() => Generator, steps?: number) ⇒ Fraction`          | Evaluate (generalized) continued fraction to a `Fraction` approximation |
-
-## Coding Style
-
-As every library I publish, ContinuedFraction is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library.
+| `toArray(source, steps)` | `Term[]`                                                          | Collect at most `steps` terms; the default is `10`                      |
+| `convergents(source)`    | `Generator<Fraction>`                                             | Yield every exact convergent lazily                                     |
+| `eval(source, steps)`    | `Fraction`                                                        | Evaluate up to `steps` terms; the default is `10`                       |
 
 ## Building the library
 
-After cloning the Git repository run:
+The source is strict TypeScript. The build emits CommonJS, ESM, a standalone browser bundle, source maps, and format-specific declarations.
 
-```
+After cloning the Git repository, run:
+
+```bash
 npm install
 npm run build
 ```
 
+Run all runtime and type-level tests with:
+
+```bash
+npm test
+```
+
 ## Copyright and Licensing
 
-Copyright (c) 2025, [Robert Eisele](https://raw.org/)
+Copyright (c) 2026, [Robert Eisele](https://raw.org/)
 Licensed under the MIT license.

package/dist/continuedfraction.d.mts

@@ -0,0 +1,115 @@
+/**
+ * @license ContinuedFraction.js v0.1.0
+ * https://github.com/rawify/ContinuedFraction.js
+ *
+ * Copyright (c) 2026, Robert Eisele (https://raw.org/)
+ * Licensed under the MIT license.
+ **/
+import { type Fraction as FractionValue } from 'fraction.js';
+/** A value accepted by Fraction.js as a continued-fraction coefficient. */
+export type Coefficient = number | string | bigint | FractionValue;
+/** A term of a generalized continued fraction. */
+export interface CFTerm {
+    /** The a_n coefficient. */
+    a: Coefficient;
+    /** The b_n coefficient. */
+    b: Coefficient;
+}
+/** A simple or generalized continued-fraction term. */
+export type ContinuedFractionTerm = Coefficient | CFTerm;
+/** A term iterator or a function that creates one. */
+export type ContinuedFractionSource<T = ContinuedFractionTerm> = Iterator<T> | (() => Iterator<T>);
+/**
+ * Utility class for generating and evaluating continued fractions.
+ * All methods are static; the class cannot be instantiated.
+ */
+export declare class ContinuedFraction {
+    private constructor();
+    /**
+     * Infinite generator for the continued-fraction terms of sqrt(N).
+     *   sqrt(N) = [a0; (a1, a2, ..., a_p)], with a period boundary at ak = 2*a0.
+     * For perfect squares, yields only a0 = floor(sqrt(N)) and then returns.
+     *
+     * @param N Integer whose square-root CF expansion is desired (N >= 0).
+     * @yields Next continued-fraction term of sqrt(N).
+     */
+    static sqrt(N: number): Generator<number, void, unknown>;
+    /**
+     * Generator for continued-fraction terms of any real number via Fraction.js.
+     *
+     * @param n The real number to convert (as number, string, or bigint).
+     * @yields Next continued-fraction term of n.
+     */
+    static fromNumber(n: Coefficient): Generator<bigint, void, unknown>;
+    /**
+     * Generator for continued-fraction terms of a rational a/b via Fraction.js.
+     *
+     * @param a Numerator, Fraction, or complete fraction string.
+     * @param b Optional denominator.
+     * @yields Next continued-fraction term of a/b.
+     */
+    static fromFraction(a: Coefficient, b?: Coefficient): Generator<bigint, void, unknown>;
+    /**
+     * Yields a finite sequence of simple or generalized terms unchanged.
+     *
+     * @param terms Continued-fraction terms.
+     * @yields Each supplied term in order.
+     */
+    static fromTerms<T extends ContinuedFractionTerm>(terms: Iterable<T>): Generator<T, void, unknown>;
+    /**
+     * Infinite generator of the golden ratio phi = [1; 1, 1, 1, ...].
+     *
+     * @yields Always 1.
+     */
+    static PHI(): Generator<number, never, unknown>;
+    /**
+     * Infinite generator for Brouncker's generalized continued fraction of 4/pi:
+     *   4/pi = 1 + 1^2/(2 + 3^2/(2 + 5^2/(2 + ...)))
+     *
+     * @yields Term pair (a_n, b_n) of the generalized continued fraction.
+     *   - first: a_0 = 1
+     *   - then: a_n = 2, b_n = (2n-1)^2 (n >= 1)
+     */
+    static FOUR_OVER_PI(): Generator<CFTerm, never, unknown>;
+    /**
+     * Infinite generator for a generalized continued fraction of pi:
+     *   pi = 3 + 1^2/(6 + 3^2/(6 + 5^2/(6 + ...)))
+     *
+     * @yields Term pair (a_n, b_n) of the generalized continued fraction.
+     *   - first: a_0 = 3
+     *   - then: a_n = 6, b_n = (2n-1)^2 (n >= 1)
+     */
+    static PI(): Generator<CFTerm, never, unknown>;
+    /**
+     * Infinite generator of e = [2; 1, 2, 1, 1, 4, 1, ...].
+     * Terms follow the pattern [2; (1, 2m, 1) for m = 1, 2, 3, ...].
+     *
+     * @yields Next continued-fraction term of e.
+     */
+    static E(): Generator<number, never, unknown>;
+    /**
+     * Collects at most `steps` terms from a continued fraction.
+     *
+     * @param source Continued-fraction term iterator or a function returning one.
+     * @param steps Maximum number of terms to collect.
+     * @returns Collected terms in source order.
+     */
+    static toArray<T>(source: ContinuedFractionSource<T>, steps?: number): T[];
+    /**
+     * Generates every convergent of a simple or generalized continued fraction.
+     *
+     * @param source Continued-fraction term iterator or a function returning one.
+     * @yields Exact convergents as Fraction instances.
+     */
+    static convergents(source: ContinuedFractionSource): Generator<FractionValue, void, unknown>;
+    /**
+     * Evaluates a simple or generalized continued fraction generator.
+     * For generalized fractions terms are objects `{ a, b }`; otherwise they are coefficients.
+     *
+     * @param source Continued-fraction term iterator or a function returning one.
+     * @param steps Number of terms to evaluate.
+     * @returns Rational approximation as Fraction.
+     */
+    static eval(source: ContinuedFractionSource, steps?: number): FractionValue;
+}
+export default ContinuedFraction;

package/dist/continuedfraction.d.ts

@@ -0,0 +1,16 @@
+import type { CFTerm as CFTermType, Coefficient as CoefficientType, ContinuedFraction as ContinuedFractionType, ContinuedFractionSource as ContinuedFractionSourceType, ContinuedFractionTerm as ContinuedFractionTermType } from './continuedfraction.d.mts';
+
+declare const ContinuedFraction: typeof ContinuedFractionType & {
+  readonly default: typeof ContinuedFractionType;
+  readonly ContinuedFraction: typeof ContinuedFractionType;
+};
+
+declare namespace ContinuedFraction {
+  type CFTerm = CFTermType;
+  type Coefficient = CoefficientType;
+  type ContinuedFraction = ContinuedFractionType;
+  type ContinuedFractionSource<T = ContinuedFractionTermType> = ContinuedFractionSourceType<T>;
+  type ContinuedFractionTerm = ContinuedFractionTermType;
+}
+
+export = ContinuedFraction;