Update LCG params

README.md

@@ -6,16 +6,18 @@
 integers up to 64 bits in length to compact, random-looking character strings.
 
 Values are first transformed by a Linear Congruential Generator so as to
-conceal the underlying number sequence, then the output is encoded using a
+obfuscate the underlying number sequence, then the output is encoded using a
 Base41 encoding scheme.
 
 ```
-2097142 -> "cWCLd"
+1 -> "FyFLmR"
+2 -> "JwKVWj"
+3 -> "XcCjDG"
 ```
 
 The Keymask instance can be personalized using a 256-bit seed value. As long as
-you keep this value secret, it will be extremely difficult for anyone to
-reverse map the encoded values.
+you keep this value secret, it will be extremely difficult for anyone who
+doesn't know the seed to reverse map the encoded values.
 
 ## Motivation
 
@@ -30,8 +32,8 @@ displayed to end-users without revealing these kinds of details.
 
 ## Why Base41?
 
-**TL;DR:** Efficient, URL-safe, free of visualy similar characters, unikely to
-form recognizable words or phrases.
+**TL;DR:** Efficient, URL-safe, free of visualy similar characters, extremely
+unikely to form recognizable words or phrases.
 
 Base41 is a highly efficient encoding for 16-, 32- and 64-bit values,
 comparable to Base57 or Base85 in this respect. Whereas Base85 encodes 64 bits
@@ -52,9 +54,9 @@ For its part, Base57 (or the somewhat more common Base58) is also free of
 special characters, therefore URL-safe. However, since it includes virtually
 the full range of alphanumeric characters, encoded values can inadvertently
 contain recognizable words, phrases or slang, including potentially offensive
-language. This can occasionally be problematic when the encoded values are
-associated with human users (for example, a user id) and visible to them (for
-example, in the URL of their public profile page).
+language. This can be problematic when the encoded values are associated with
+human users (for example, a user id) and visible to them (for example, in the
+URL of their public profile page).
 
 Dropping down to Base41 allows us to remove all vowels and numerals from the
 encoding alphabet, which makes it virtually impossible to generate crude or
@@ -70,9 +72,9 @@ manager (npm, yarn, pnpm...).
 ## Usage
 
 The module exports three classes, `Keymask`, `Generator` (the LCG) and
-`Base41` (the encoder). These can be used independently of each other if need
-be. However, for the most part, the main `Keymask` class is all you need, as it
-presents a simple unified interface to the other two.
+`Base41` (the encoder). The LCG and encoder can be used independently of each
+other if need be. However, the main `Keymask` class presents a simple unified
+interface to the supporting classes and will typically be all you need.
 
 The `Keymask` class constructor can be passed an object containing various
 optional settings, described below. The default constructor will create an
@@ -90,7 +92,7 @@ const keymask = new Keymask();
 const masked = keymask.mask(123456789);
 const unmasked = keymask.unmask(masked);
 
-console.log(masked); // "wZnfgq"
+console.log(masked); // "wMjMGR"
 console.log(unmasked); // 123456789
 ```
 
@@ -129,7 +131,7 @@ const keymask = new Keymask({
 const masked = keymask.mask(123456789);
 const unmasked = keymask.unmask(masked);
 
-console.log(masked); // "znrdFM"
+console.log(masked); // "KbxsJQ"
 console.log(unmasked); // 123456789
 
 ```
@@ -173,7 +175,7 @@ const keymask = new Keymask({
 const masked = keymask.mask(12);
 const unmasked = keymask.unmask(masked);
 
-console.log(masked); // "YmMrxk"
+console.log(masked); // "pKJhNV"
 console.log(unmasked); // 12
 ```
 
@@ -196,20 +198,24 @@ const keymask = new Keymask({
 const masked = keymask.mask(123456789n);
 const unmasked = keymask.unmask(masked);
 
-console.log(masked); // "wZnfgq"
+console.log(masked); // "wMjMGR"
 console.log(unmasked); // 123456789n
 ```
 
 ## Performance
 
 Both the Linear Congruential Generator and the Base41 encoding are extremely
 simple operations, with execution times measured in microseconds or fractions
-of a microsecond. In most systems, this has very little potential of forming
-a bottleneck (so long as you are processing less than ~1 million per second).
+of a microsecond. In most systems, there is very little chance that Keymask
+computations will form a significant bottleneck (provided you are processing
+less than ~1 million per second).
 
 On commodity hardware (2020 M1 Macbook Air), a single invocation of
-`Keymask.mask()` takes on the order of 10-20 microseconds (dominated by the
-LCG), whereas a tight loop of one million invocations takes an average of
-around 0.22 microseconds per call (dominated by the Base41 encoding). As is
-often the case, performance characteristics differ substantially depending on
-whether or not the code is being executed by the JIT compiler.
+`Keymask.mask()` takes on the order of 20 microseconds (irrespective of output
+length), whereas a tight loop of one million invocations takes an average of
+between 0.2 and 0.7 microseconds per call (strongly dependent on the output
+length). As is often the case, performance characteristics differ substantially
+depending on whether or not the code is being executed by the JIT compiler.
+
+For best performance, the `Keymask` class instance should be cached for
+repeated usage.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "keymask-base41",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Map sequential IDs or serial numbers to random-looking Base41-encoded strings",
   "type": "module",
   "exports": {
@@ -11,6 +11,7 @@
   },
   "main": "dist/index.cjs",
   "module": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],

src/Generator.ts

@@ -1,20 +1,24 @@
 /**
  * LCG parameters from https://www.ams.org/journals/mcom/1999-68-225/S0025-5718-99-00996-5/S0025-5718-99-00996-5.pdf
+ * In each case, the selected parameters are those that are least proximal to
+ * low harmonic factors of the modulus (1...8). See `util/harmonics.js`. This
+ * means that they are least likely to present repeating patterns across short
+ * sequences of values.
  */
 const lcgMap: (number[] | bigint[])[] = [
   [],
-  [41, 26, 30],
+  [41, 22, 28],
   [1021, 331, 401], // 2^10 - 3
-  [65521, 2469, 47104], // 2^16 - 15
-  [2097143, 1939807, 1969917], // 2^21 - 9
-  [67108859, 6763103, 66117721], // 2^26 - 5
-  [4294967291n, 279470273n, 1815976680n], // 2^32 - 5
-  [137438953447n, 85876534675n, 116895888786n], // 2^37 - 25
-  [4398046511093n, 92644101553n, 626031856758n], // 2^42 - 11
+  [65521, 17364, 32236], // 2^16 - 15
+  [2097143, 1043187, 1352851], // 2^21 - 9
+  [67108859, 19552116, 24409594], // 2^26 - 5
+  [4294967291n, 1588635695n, 3870709308n], // 2^32 - 5
+  [137438953447n, 31450092817n, 76886758244n], // 2^37 - 25
+  [4398046511093n, 2928603677866n, 3015630915308n], // 2^42 - 11
   [281474976710597n, 59279420901007n, 163724808306782n], // 2^48 - 59
-  [9007199254740881n, 5667072534355537n, 7982986707690649n], // 2^53 - 111
-  [288230376151711717n, 28146528635210647n, 206638310974457555n], // 2^58 - 27
-  [18446744073709551557n, 811465980874026894n, 18263440312458789471n] // 2^64 - 59
+  [9007199254740881n, 2082839274626558n, 3141627116318043n], // 2^53 - 111
+  [288230376151711717n, 56502943171806276n, 101565695086122187n], // 2^58 - 27
+  [18446744073709551557n, 9044836419713972268n, 13891176665706064842n] // 2^64 - 59
 ];
 
 export class Generator {