🚧 progress: First draft.

Author: make-github-pseudonymous-again

doc/manual/example.md

@@ -1,3 +1,8 @@
 # Examples
 
+```js
+import { factorial } from '@combinatorics/factorial' ;
+factorial(18) ; // 6402373705728000
+```
+
 > More examples in [the test files](https://github.com/computational-combinatorics/factorial/tree/main/test/src).

package.json

@@ -59,12 +59,15 @@
     "release": "np --message ':hatching_chick: release: Bumping to v%s.'",
     "test": "ava"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@failure-abstraction/error": "^6.0.1"
+  },
   "devDependencies": {
     "@babel/core": "7.14.3",
     "@babel/preset-env": "7.14.2",
     "@babel/register": "7.13.16",
     "@commitlint/cli": "12.1.4",
+    "@iterable-iterator/zip": "^1.0.1",
     "@js-library/commitlint-config": "0.0.4",
     "ava": "3.15.0",
     "babel-plugin-transform-remove-console": "6.9.4",

src/_factorialn.js

@@ -0,0 +1,19 @@
+import assert from 'assert';
+
+/**
+ * Returns the factorial of the input bigint _n!_ = <code>1 * 2 * ... * n</code>.
+ *
+ * @param {bigint} n The input bigint.
+ * @returns {bigint} The factorial of the input bigint.
+ */
+const _factorialn = (n) => {
+	assert(typeof n === 'bigint');
+	assert(n >= 0n);
+	let f = 1n;
+
+	while (n !== 0n) f *= n--;
+
+	return f;
+};
+
+export default _factorialn;

src/factorial.js

@@ -0,0 +1,24 @@
+import {TypeError, ValueError} from '@failure-abstraction/error';
+import lookup from './lookup.js';
+
+const N = lookup.length;
+
+/**
+ * Returns the factorial of the input number _n!_ = <code>1 * 2 * ... * n</code>.
+ *
+ * @experimental Uses doubles, will return incorrect values for large input.
+ *
+ * @param {number} n The input number.
+ * @returns {number} The factorial of the input number.
+ */
+const factorial = (n) => {
+	// eslint-disable-next-line unicorn/error-message
+	if (typeof n !== 'number') throw new TypeError();
+	if (!Number.isInteger(n)) throw new ValueError();
+	if (n < 0) throw new ValueError();
+	if (n >= N) throw new ValueError();
+
+	return lookup[n];
+};
+
+export default factorial;

src/factorialn.js

@@ -0,0 +1,17 @@
+import {TypeError, ValueError} from '@failure-abstraction/error';
+import _factorialn from './_factorialn.js';
+
+/**
+ * Factorialn.
+ *
+ * @param {bigint} n
+ */
+const factorialn = (n) => {
+	// eslint-disable-next-line unicorn/error-message
+	if (typeof n !== 'bigint') throw new TypeError();
+	if (n < 0n) throw new ValueError();
+
+	return _factorialn(n);
+};
+
+export default factorialn;

src/index.js

@@ -1,2 +1,4 @@
-const answer = 42;
-export default answer;
+export {default as _factorialn} from './_factorialn.js';
+export {default as factorial} from './factorial.js';
+export {default as factorialn} from './factorialn.js';
+export {default as lookup} from './lookup.js';

src/lookup.js

@@ -0,0 +1,8 @@
+const lookup = Float64Array.from([
+	1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800, 39916800, 479001600,
+	6227020800, 87178291200, 1307674368000, 20922789888000, 355687428096000,
+	6402373705728000, 121645100408832000, 2432902008176640000,
+	51090942171709440000, 1124000727777607680000,
+]);
+
+export default lookup;

test/src/_fixtures.js

@@ -0,0 +1,25 @@
+export const sequence = [
+	1n,
+	1n,
+	2n,
+	6n,
+	24n,
+	120n,
+	720n,
+	5040n,
+	40320n,
+	362880n,
+	3628800n,
+	39916800n,
+	479001600n,
+	6227020800n,
+	87178291200n,
+	1307674368000n,
+	20922789888000n,
+	355687428096000n,
+	6402373705728000n,
+	121645100408832000n,
+	2432902008176640000n,
+	51090942171709440000n,
+	1124000727777607680000n,
+];

test/src/api.js

@@ -0,0 +1,25 @@
+import test from 'ava';
+import {TypeError, ValueError} from '@failure-abstraction/error';
+import {enumerate} from '@iterable-iterator/zip';
+
+import {sequence} from './_fixtures.js';
+
+import {factorial, lookup} from '../../src.js';
+
+// eslint-disable-next-line eqeqeq
+const macro = (t, n, f) => t.true(factorial(n) == f);
+
+macro.title = (title, n, f) => title ?? `${n}! = ${f}`;
+
+for (const [n, f] of enumerate(sequence)) test(macro, n, f);
+
+const throws = (t, n, instanceOf) => t.throws(() => factorial(n), {instanceOf});
+
+throws.title = (title, n, instanceOf) =>
+	title ?? `${n}! throws ${instanceOf.name}`;
+
+test(throws, '', TypeError);
+test(throws, 7n, TypeError);
+test(throws, 2.3, ValueError);
+test(throws, -1, ValueError);
+test(throws, lookup.length, ValueError);

test/src/factorial.js

@@ -0,0 +1,29 @@
+import test from 'ava';
+import {TypeError, ValueError} from '@failure-abstraction/error';
+import {enumerate} from '@iterable-iterator/zip';
+
+import {sequence} from './_fixtures.js';
+
+import {factorialn as factorial} from '../../src.js';
+
+const macro = (t, n, f) => t.is(factorial(n), f);
+
+macro.title = (title, n, f) => title ?? `${n}! = ${f}`;
+
+for (const [n, f] of enumerate(sequence)) test(macro, BigInt(n), f);
+
+test(
+	macro,
+	1000n,
+	402387260077093773543702433923003985719374864210714632543799910429938512398629020592044208486969404800479988610197196058631666872994808558901323829669944590997424504087073759918823627727188732519779505950995276120874975462497043601418278094646496291056393887437886487337119181045825783647849977012476632889835955735432513185323958463075557409114262417474349347553428646576611667797396668820291207379143853719588249808126867838374559731746136085379534524221586593201928090878297308431392844403281231558611036976801357304216168747609675871348312025478589320767169132448426236131412508780208000261683151027341827977704784635868170164365024153691398281264810213092761244896359928705114964975419909342221566832572080821333186116811553615836546984046708975602900950537616475847728421889679646244945160765353408198901385442487984959953319101723355556602139450399736280750137837615307127761926849034352625200015888535147331611702103968175921510907788019393178114194545257223865541461062892187960223838971476088506276862967146674697562911234082439208160153780889893964518263243671616762179168909779911903754031274622289988005195444414282012187361745992642956581746628302955570299024324153181617210465832036786906117260158783520751516284225540265170483304226143974286933061690897968482590125458327168226458066526769958652682272807075781391858178889652208164348344825993266043367660176999612831860788386150279465955131156552036093988180612138558600301435694527224206344631797460594682573103790084024432438465657245014402821885252470935190620929023136493273497565513958720559654228749774011413346962715422845862377387538230483865688976461927383814900140767310446640259899490222221765904339901886018566526485061799702356193897017860040811889729918311021171229845901641921068884387121855646124960798722908519296819372388642614839657382291123125024186649353143970137428531926649875337218940694281434118520158014123344828015051399694290153483077644569099073152433278288269864602789864321139083506217095002597389863554277196742822248757586765752344220207573630569498825087968928162753848863396909959826280956121450994871701244516461260379029309120889086942028510640182154399457156805941872748998094254742173582401063677404595741785160829230135358081840096996372524230560855903700624271243416909004153690105933983835777939410970027753472000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000n,
+);
+
+const throws = (t, n, instanceOf) => t.throws(() => factorial(n), {instanceOf});
+
+throws.title = (title, n, instanceOf) =>
+	title ?? `${n}! throws ${instanceOf.name}`;
+
+test(throws, '', TypeError);
+test(throws, 7, TypeError);
+test(throws, 2.3, TypeError);
+test(throws, -1n, ValueError);