feat: add typescript bindings to the encoder

This is a beta test addressing issue #43 for testing. It adds typescript bindings in a index.d.ts
file.

.eslintignore

@@ -1,3 +1,4 @@
 node_modules
 coverage
-CHANGELOG.md
+CHANGELOG.md
+*.d.ts

API.md

@@ -29,11 +29,11 @@ A class for encoding and decoding base 10 integers to a custom alphanumeric base
 
 ### Parameters
 
--   `configOptions` **[object][21]?** Optional object defining initial settings for the class (optional, default `{}`)
+-   `configOptions` **[object][21]?** Optional object defining initial settings for the class (optional, default `{allowLowerCaseDictionary:false,dictionary:'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}`)
 
-    -   `configOptions.allowLowerCaseDictionary` **[boolean][22]?** Whether or not to allow lower case letters in the dictionary
-    -   `configOptions.dictionary` **[string][23]?** Starting dictionary to use. Must contain only letters or numbers. Characters cannot be repeated.
-        If `allowLowerCaseDictionary = true`, then lower case letters are not considered the same as upper case. (e.g. 'ABCabc' has 6 unique characters.)
+    -   `configOptions.allowLowerCaseDictionary` **[boolean][22]** Whether or not to allow lower case letters in the dictionary (optional, default `false`)
+    -   `configOptions.dictionary` **[string][23]** Starting dictionary to use. Must contain only letters or numbers. Characters cannot be repeated.
+        If `allowLowerCaseDictionary = true`, then lower case letters are not considered the same as upper case. (e.g. 'ABCabc' has 6 unique characters.) (optional, default `'ABCDEFGHIJKLMNOPQRSTUVWXYZ'`)
 
 ### Examples
 
@@ -240,6 +240,10 @@ console.log(encoder.deconstruct('')) // undefined
 Returns **[Array][27]<[number][25]>** An array of numbers. Characters not present in the dictionary are treated as letters and return `undefined` for that array value.
 Passing an empty string (`''`), `null`, or `undefined` will return `undefined` for the whole function.
 
+##
+
+Type: [string][23]
+
 [1]: #alphanumericencoder
 [2]: #parameters
 [3]: #examples

index.d.ts

@@ -0,0 +1,25 @@
+// Manually generated from https://www.typescriptlang.org/play
+
+export class AlphanumericEncoder {
+    constructor(configOptions?: {
+        allowLowerCaseDictionary: boolean | undefined
+        dictionary: string | undefined
+    })
+    private _defaultDictionary
+    private _dictionaryInUse
+    private _allowLowerCaseDictionary
+
+    set allowLowerCaseDictionary(arg: boolean)
+    get allowLowerCaseDictionary(): boolean
+
+    set dictionary(arg: string)
+    get dictionary(): string
+
+    resetDefaultDictionary(): void
+
+    encode(integerToEncode: number): string
+
+    decode(stringToDecode: string): number
+
+    deconstruct(stringToDeconstruct: string | number): number[]
+}

index.js

@@ -1,10 +1,8 @@
-// @ts-check
-
 /**
  * A class for encoding and decoding base 10 integers to a custom alphanumeric base representation.
  * @param {object} [configOptions] Optional object defining initial settings for the class
- * @param {boolean} [configOptions.allowLowerCaseDictionary] Whether or not to allow lower case letters in the dictionary
- * @param {string} [configOptions.dictionary] Starting dictionary to use. Must contain only letters or numbers. Characters cannot be repeated.
+ * @param {boolean} [configOptions.allowLowerCaseDictionary=false] Whether or not to allow lower case letters in the dictionary
+ * @param {string} [configOptions.dictionary='ABCDEFGHIJKLMNOPQRSTUVWXYZ'] Starting dictionary to use. Must contain only letters or numbers. Characters cannot be repeated.
  * If `allowLowerCaseDictionary = true`, then lower case letters are not considered the same as upper case. (e.g. 'ABCabc' has 6 unique characters.)
  * @example
  * // Import into a project
@@ -26,7 +24,12 @@
  * const encoder = new AlphanumericEncoder(configOptions)
  */
 class AlphanumericEncoder {
-    constructor(configOptions = {}) {
+    constructor(
+        configOptions = {
+            allowLowerCaseDictionary: false,
+            dictionary: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+        }
+    ) {
         /**
          * @private
          * @type {string} Internal value used to initialize and reset the dictionary
@@ -209,8 +212,15 @@ class AlphanumericEncoder {
             )
         }
 
+        /**
+         * Takes a letter between 0 and max letter length and returns the corresponding letter
+         *
+         * @private
+         * @param {number} num The index to search for
+         * @param {string} dictionary The dictionary used to search
+         * @returns {string} The letter corresponding to this number index
+         */
         function numToLetter(num, dictionary) {
-            // Takes a letter between 0 and max letter length and returns the corresponding letter
             if (num === 0) {
                 return undefined
             }
@@ -330,12 +340,17 @@ class AlphanumericEncoder {
         }
 
         const safeString = String(stringToDeconstruct) // Force argument to string to process number arguments and prevent slice from throwing an error
+        /**
+         * @private
+         * @type {number[]} Array of numbers after splitting a string.
+         * Elements include (in order) the number or decoded number from a letter.
+         */
         const deconstructedArray = []
         let character = ''
         let componentPart = safeString.slice(0, 1) // Initialize with the first character (which has been guranteed present by above guard functions)
 
         // A helper function to push the final component into the array that gets returned. Numbers get added as is, strings get decoded.
-        const addDecodedElement = (componentString) => {
+        const addDecodedElement = (/** @type {string} */ componentString) => {
             if (componentString.match(/[0-9]/)) {
                 deconstructedArray.push(Number.parseInt(componentString, 10)) // Numbers
             } else {

index.test.js

@@ -1,8 +1,9 @@
-// @ts-check
-
 const AlphanumericEncoder = require('./index')
 
-let encoder = new AlphanumericEncoder()
+let encoder = new AlphanumericEncoder({
+    allowLowerCaseDictionary: false,
+    dictionary: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+})
 
 const numberToEncodedLetters = [
     [1, 'A'],
@@ -67,7 +68,6 @@ describe('Allow Lower Case Dictionaries', () => {
     test.each([true, 1, [123], { value: 1 }])(
         'allowLowerCaseDictionary with truthy value %p',
         (truthyTestValue) => {
-            // @ts-ignore
             encoder.allowLowerCaseDictionary = truthyTestValue
             expect(encoder.allowLowerCaseDictionary).toBeTruthy()
         }
@@ -86,7 +86,6 @@ describe('Allow Lower Case Dictionaries', () => {
     test.each([false, 0, null, undefined])(
         'allowLowerCaseDictionary with falsy value %p',
         (truthyTestValue) => {
-            // @ts-ignore
             encoder.allowLowerCaseDictionary = truthyTestValue
             expect(encoder.allowLowerCaseDictionary).toBeFalsy()
         }
@@ -317,7 +316,7 @@ describe('Test Decoding', () => {
 
     test('Expect decoding strings to integers greater than Number.MAX_SAFE_INTEGER throws an error', () => {
         expect(() => {
-            encoder.decode('BKTXHSOGHKKF')
+            encoder.decode('BKTXHSOGHKKF') // BKTXHSOGHKKE is what max safe integer encodes to under default dictionary
         }).toThrow(/maximum safe integer/)
     })
 

package.json

@@ -24,12 +24,13 @@
         "package-lock.json"
     ],
     "main": "index.js",
+    "types": "index.d.ts",
     "repository": {
         "type": "git",
         "url": "https://github.com/M-Scott-Lassiter/Alphanumeric-Encoder.git"
     },
     "scripts": {
-        "build": "npm run lint && npm run test && npm run docs && npm run tableofcontents && npm run format",
+        "build": "npm run lint && npm run test && npm run docs && npm run tableofcontents && npm run format && echo \"Build process complete.\" && exit 0",
         "cz": "cz",
         "docs": "documentation build index.js --format md --output API.md",
         "format": "npx prettier . --write",