@marlonwq/primality 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Márlon C.
+
+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,70 @@
+# Primality
+A high-performance TypeScript library for primality testing using Miller-Rabin and Fermat algorithms. Designed with BigInt support for cryptographic-grade calculations.
+
+[![NPM Version](https://img.shields.io/npm/v/@marlonwq/primality)](https://www.npmjs.com/package/@marlonwq/primality)
+[![NPM Downloads](https://img.shields.io/npm/dm/@marlonwq/primality)](https://www.npmjs.com/package/@marlonwq/primality)
+![GitHub Repo stars](https://img.shields.io/github/stars/marlonwq/primality)
+[![License](https://img.shields.io/npm/l/@marlonwq/primality)](https://github.com/marlonwq/primality/blob/main/LICENSE)
+
+## Features
+- **Miller-Rabin Test**: Robust probabilistic test.
+- **Fermat Primality Test**: Fast probabilistic test based on Fermat's Little Theorem.
+- **BigInt Support**: Test extremely large numbers without precision loss.
+- **Zero Dependencies**: Lightweight and optimized for performance.
+
+## Installation
+```sh
+pnpm add @marlonwq/primality
+```
+
+## Usage
+
+```typescript
+import { isPrimeMillerRabin, isPrimeFermat } from '@marlonwq/primality';
+
+// Using Miller-Rabin (Recommended for high accuracy)
+// Use the 'n' suffix for BigInt literals
+const num1 = 104729n;
+console.log(isPrimeMillerRabin(num1)); // true
+
+// Using Fermat (Faster, but watch out for Carmichael numbers)
+const num2 = 561n; 
+console.log(isPrimeFermat(num2)); // true (Fermat's false positive)
+console.log(isPrimeMillerRabin(num2)); // false (Miller-Rabin's correct answer)
+```
+
+## How it Works
+
+<details>
+<summary>Click to expand the mathematical background</summary>
+
+The Miller-Rabin test is an evolution of **Fermat's Little Theorem**. Fermat states that if $p$ is prime, then for any integer $a$, $a^{p-1} \equiv 1 \pmod p$. However, some composite numbers (known as **Carmichael numbers**) also satisfy this condition, leading to false positives.
+
+### The Miller-Rabin Secret
+The core of Miller-Rabin is the fact that in a prime field $\mathbb{Z}_p$, the equation $x^2 \equiv 1 \pmod p$ has only two solutions: $x = 1$ and $x = p - 1$ (or $-1$).
+
+**The Algorithm Steps:**
+1. Write $n - 1$ as $2^s \cdot d$ by repeatedly factoring out powers of 2.
+2. Pick a random base $a$ in the range $[2, n - 2]$.
+3. Compute $x = a^d \pmod n$. If $x = 1$ or $x = n - 1$, the number is a **probable prime**.
+4. Otherwise, square $x$ repeatedly ($x = x^2 \pmod n$) up to $s - 1$ times.
+5. If at any point $x = n - 1$, the number is a **probable prime**.
+6. If the loop finishes without ever hitting $n - 1$, the number is **definitely composite**.
+
+### Accuracy
+Miller-Rabin is a probabilistic algorithm. Each iteration ($k$) reduces the probability of a composite number being declared prime to less than $1/4$. With $k=40$, the error probability is less than $4^{-40}$ — a value so infinitesimal that it is statistically more likely for a meteor to strike your computer than for the test to provide a wrong answer.
+
+</details>
+
+## Contributing
+We use `pnpm` as our package manager. To get started:
+
+```
+pnpm install
+pnpm build
+pnpm test
+```
+If you find this project helpful, please consider contributing in the following ways: Submitting a [pull request](https://github.com/marlonwq/primality/pulls), opening an [issue](https://github.com/marlonwq/primality/issues), giving the project a star or [buying me a coffee!](https://ko-fi.com/marlonwq)!
+
+## License
+[MIT](https://github.com/marlonwq/primality/blob/main/LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Fermat Primality Test
+ * @param n - The number to test (BigInt)
+ * @param iterations - Number of trials (higher is more accurate)
+ * @returns boolean - True if probably prime, false if composite
+ */
+declare function isPrimeFermat(n: bigint, iterations?: number): boolean;
+
+/**
+ * Miller-Rabin Primality Test
+ * @param n - The number to test (BigInt)
+ * @param k - Number of iterations (accuracy). Default is 40 for high confidence.
+ */
+declare function isPrimeMillerRabin(n: bigint, k?: number): boolean;
+
+export { isPrimeFermat, isPrimeMillerRabin };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fermat Primality Test
+ * @param n - The number to test (BigInt)
+ * @param iterations - Number of trials (higher is more accurate)
+ * @returns boolean - True if probably prime, false if composite
+ */
+declare function isPrimeFermat(n: bigint, iterations?: number): boolean;
+
+/**
+ * Miller-Rabin Primality Test
+ * @param n - The number to test (BigInt)
+ * @param k - Number of iterations (accuracy). Default is 40 for high confidence.
+ */
+declare function isPrimeMillerRabin(n: bigint, k?: number): boolean;
+
+export { isPrimeFermat, isPrimeMillerRabin };

package/dist/index.js

@@ -0,0 +1,106 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  isPrimeFermat: () => isPrimeFermat,
+  isPrimeMillerRabin: () => isPrimeMillerRabin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/fermat.ts
+function isPrimeFermat(n, iterations = 5) {
+  if (n <= 1n) return false;
+  if (n <= 3n) return true;
+  if (n % 2n === 0n) return false;
+  for (let i = 0; i < iterations; i++) {
+    const a = BigInt(Math.floor(Math.random() * (Number(n) - 4))) + 2n;
+    if (powerModular(a, n - 1n, n) !== 1n) {
+      return false;
+    }
+  }
+  return true;
+}
+function powerModular(base, exp, mod) {
+  let res = 1n;
+  base = base % mod;
+  while (exp > 0n) {
+    if (exp % 2n === 1n) res = res * base % mod;
+    base = base * base % mod;
+    exp = exp / 2n;
+  }
+  return res;
+}
+
+// src/miller-rabin.ts
+function getRandomBigInt(min, max) {
+  const range = max - min;
+  const bits = range.toString(2).length;
+  let res;
+  do {
+    let randStr = "";
+    for (let i = 0; i < bits; i++) {
+      randStr += Math.random() > 0.5 ? "1" : "0";
+    }
+    res = BigInt("0b" + randStr);
+  } while (res > range);
+  return res + min;
+}
+function isPrimeMillerRabin(n, k = 40) {
+  if (n <= 1n) return false;
+  if (n <= 3n) return true;
+  if (n % 2n === 0n) return false;
+  let d = n - 1n;
+  let s = 0n;
+  while (d % 2n === 0n) {
+    d /= 2n;
+    s++;
+  }
+  for (let i = 0; i < k; i++) {
+    const a = getRandomBigInt(2n, n - 2n);
+    let x = powerModular2(a, d, n);
+    if (x === 1n || x === n - 1n) continue;
+    let composite = true;
+    for (let r = 1n; r < s; r++) {
+      x = x * x % n;
+      if (x === n - 1n) {
+        composite = false;
+        break;
+      }
+    }
+    if (composite) return false;
+  }
+  return true;
+}
+function powerModular2(base, exp, mod) {
+  let res = 1n;
+  base = base % mod;
+  while (exp > 0n) {
+    if (exp % 2n === 1n) res = res * base % mod;
+    base = base * base % mod;
+    exp = exp / 2n;
+  }
+  return res;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isPrimeFermat,
+  isPrimeMillerRabin
+});

package/dist/index.mjs

@@ -0,0 +1,78 @@
+// src/fermat.ts
+function isPrimeFermat(n, iterations = 5) {
+  if (n <= 1n) return false;
+  if (n <= 3n) return true;
+  if (n % 2n === 0n) return false;
+  for (let i = 0; i < iterations; i++) {
+    const a = BigInt(Math.floor(Math.random() * (Number(n) - 4))) + 2n;
+    if (powerModular(a, n - 1n, n) !== 1n) {
+      return false;
+    }
+  }
+  return true;
+}
+function powerModular(base, exp, mod) {
+  let res = 1n;
+  base = base % mod;
+  while (exp > 0n) {
+    if (exp % 2n === 1n) res = res * base % mod;
+    base = base * base % mod;
+    exp = exp / 2n;
+  }
+  return res;
+}
+
+// src/miller-rabin.ts
+function getRandomBigInt(min, max) {
+  const range = max - min;
+  const bits = range.toString(2).length;
+  let res;
+  do {
+    let randStr = "";
+    for (let i = 0; i < bits; i++) {
+      randStr += Math.random() > 0.5 ? "1" : "0";
+    }
+    res = BigInt("0b" + randStr);
+  } while (res > range);
+  return res + min;
+}
+function isPrimeMillerRabin(n, k = 40) {
+  if (n <= 1n) return false;
+  if (n <= 3n) return true;
+  if (n % 2n === 0n) return false;
+  let d = n - 1n;
+  let s = 0n;
+  while (d % 2n === 0n) {
+    d /= 2n;
+    s++;
+  }
+  for (let i = 0; i < k; i++) {
+    const a = getRandomBigInt(2n, n - 2n);
+    let x = powerModular2(a, d, n);
+    if (x === 1n || x === n - 1n) continue;
+    let composite = true;
+    for (let r = 1n; r < s; r++) {
+      x = x * x % n;
+      if (x === n - 1n) {
+        composite = false;
+        break;
+      }
+    }
+    if (composite) return false;
+  }
+  return true;
+}
+function powerModular2(base, exp, mod) {
+  let res = 1n;
+  base = base % mod;
+  while (exp > 0n) {
+    if (exp % 2n === 1n) res = res * base % mod;
+    base = base * base % mod;
+    exp = exp / 2n;
+  }
+  return res;
+}
+export {
+  isPrimeFermat,
+  isPrimeMillerRabin
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@marlonwq/primality",
+  "version": "1.0.0",
+  "description": "A high-performance TypeScript library for primality testing using Miller-Rabin and Fermat algorithms.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --out-dir dist --clean",
+    "test": "vitest"
+  },
+  "keywords": [
+    "math",
+    "primality",
+    "primes",
+    "miller-rabin",
+    "fermat",
+    "number-theory",
+    "cryptography",
+    "RSA",
+    "RSA cryptography",
+    "performance"
+  ],
+  "author": "Márlon",
+  "license": "MIT",
+  "packageManager": "pnpm@10.28.0",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}