Merge pull request #36 from M-Scott-Lassiter/next

Allow instantiating parameters using object in constructor

API.md

@@ -3,41 +3,65 @@
 ### Table of Contents
 
 -   [AlphanumericEncoder][1]
-    -   [Examples][2]
-    -   [dictionary][3]
-        -   [Parameters][4]
-        -   [Examples][5]
-    -   [allowLowerCaseDictionary][6]
-        -   [Parameters][7]
-        -   [Examples][8]
-    -   [resetDefaultDictionary][9]
-        -   [Examples][10]
-    -   [encode][11]
-        -   [Parameters][12]
-        -   [Examples][13]
-    -   [decode][14]
-        -   [Parameters][15]
-        -   [Examples][16]
+    -   [Parameters][2]
+    -   [Examples][3]
+    -   [dictionary][4]
+        -   [Parameters][5]
+        -   [Examples][6]
+    -   [allowLowerCaseDictionary][7]
+        -   [Parameters][8]
+        -   [Examples][9]
+    -   [resetDefaultDictionary][10]
+        -   [Examples][11]
+    -   [encode][12]
+        -   [Parameters][13]
+        -   [Examples][14]
+    -   [decode][15]
+        -   [Parameters][16]
+        -   [Examples][17]
 
 ## AlphanumericEncoder
 
 A class for encoding and decoding base 10 integers to a custom alphanumeric base representation.
 
+### Parameters
+
+-   `configOptions` **[object][18]?** Optional object defining initial settings for the class (optional, default `{}`)
+
+    -   `configOptions.allowLowerCaseDictionary` **[boolean][19]?** Whether or not to allow lower case letters in the dictionary
+    -   `configOptions.dictionary` **[string][20]?** Starting dictionary to use
+
 ### Examples
 
 ```javascript
 // Import into a project
 const AlphanumericEncoder = require('alphanumeric-encoder')
+
 const encoder = new AlphanumericEncoder()
 ```
 
+```javascript
+// Import into a project
+const AlphanumericEncoder = require('alphanumeric-encoder')
+
+const encoder = new AlphanumericEncoder({ allowLowerCaseDictionary: true, dictionary: 'abcdEFGH' })
+```
+
+```javascript
+// Import into a project
+const AlphanumericEncoder = require('alphanumeric-encoder')
+
+const configOptions = { allowLowerCaseDictionary: true, dictionary: 'abcdEFGH' }
+const encoder = new AlphanumericEncoder(configOptions)
+```
+
 ### dictionary
 
 Returns or sets the current dictionary.
 
 #### Parameters
 
--   `newDictionary` **[string][17]** (If setting) String of unique letters and numbers, in order, for the new dictionary
+-   `newDictionary` **[string][20]** (If setting) String of unique letters and numbers, in order, for the new dictionary
 
 #### Examples
 
@@ -52,11 +76,11 @@ console.log(encoder.dictionary) // 'ABCD'
 encoder.dictionary = 'ABCDA' // Throws error because the letter 'A' is repeated
 ```
 
--   Throws **[RangeError][18]** if setting dictionary to `null`, `undefined` or empty string (i.e. `''`)
--   Throws **[RangeError][18]** if `newDictionary` contains a non-alphanumeric character
--   Throws **[RangeError][18]** if `newDictionary` has a repeating character
+-   Throws **[RangeError][21]** if setting dictionary to `null`, `undefined` or empty string (i.e. `''`)
+-   Throws **[RangeError][21]** if `newDictionary` contains a non-alphanumeric character
+-   Throws **[RangeError][21]** if `newDictionary` has a repeating character
 
-Returns **[string][17]** (If used as getter) The current dictionary in use
+Returns **[string][20]** (If used as getter) The current dictionary in use
 
 ### allowLowerCaseDictionary
 
@@ -106,7 +130,7 @@ Takes any number and converts it into a base (dictionary length) letter combo.
 
 #### Parameters
 
--   `integerToEncode` **[number][20]** Base 10 integer. If passed a non-integer number, decimal values are truncated.
+-   `integerToEncode` **[number][22]** Base 10 integer. If passed a non-integer number, decimal values are truncated.
     Passing zero, negative numbers, or non-numbers will return `undefined`.
 
 #### Examples
@@ -145,17 +169,17 @@ console.log(encoder.encode(null)) // undefined
 console.log(encoder.encode(undefined)) // undefined
 ```
 
--   Throws **[RangeError][18]** if `integerToEncode` exceeds the maximum safe integer for Javascript (`2^53 - 1 = 9007199254740991`).
+-   Throws **[RangeError][21]** if `integerToEncode` exceeds the maximum safe integer for Javascript (`2^53 - 1 = 9007199254740991`).
 
-Returns **[string][17]** Dictionary encoded value
+Returns **[string][20]** Dictionary encoded value
 
 ### decode
 
 Takes any string and converts it into a base 10 integer based on the defined dictionary.
 
 #### Parameters
 
--   `stringToDecode` **[string][17]** If passed a non-integer number, decimal values are truncated.
+-   `stringToDecode` **[string][20]** If passed a non-integer number, decimal values are truncated.
     Passing an empty string, `null`, or `undefined` will return `undefined`.
 
 #### Examples
@@ -183,27 +207,29 @@ console.log(encoder.decode('ADBAC')) // 551
 console.log(encoder.decode('ANE')) // undefined
 ```
 
--   Throws **[RangeError][18]** if the decoded integer exceeds the maximum safe integer for Javascript (`2^53 - 1 = 9007199254740991`).
+-   Throws **[RangeError][21]** if the decoded integer exceeds the maximum safe integer for Javascript (`2^53 - 1 = 9007199254740991`).
 
-Returns **[number][20]** Positive integer representation. If one of the characters is not present in the dictionary, it will return `undefined`.
+Returns **[number][22]** Positive integer representation. If one of the characters is not present in the dictionary, it will return `undefined`.
 
 [1]: #alphanumericencoder
-[2]: #examples
-[3]: #dictionary
-[4]: #parameters
-[5]: #examples-1
-[6]: #allowlowercasedictionary
-[7]: #parameters-1
-[8]: #examples-2
-[9]: #resetdefaultdictionary
-[10]: #examples-3
-[11]: #encode
-[12]: #parameters-2
-[13]: #examples-4
-[14]: #decode
-[15]: #parameters-3
-[16]: #examples-5
-[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
-[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RangeError
+[2]: #parameters
+[3]: #examples
+[4]: #dictionary
+[5]: #parameters-1
+[6]: #examples-1
+[7]: #allowlowercasedictionary
+[8]: #parameters-2
+[9]: #examples-2
+[10]: #resetdefaultdictionary
+[11]: #examples-3
+[12]: #encode
+[13]: #parameters-3
+[14]: #examples-4
+[15]: #decode
+[16]: #parameters-4
+[17]: #examples-5
+[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 [19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
-[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RangeError
+[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![Alphanumeric Encoder](logo.gif)
+[![Alphanumeric Encoder](logo.gif)](https://www.npmjs.com/package/alphanumeric-encoder)
 
 [![NPM Version](https://img.shields.io/npm/v/alphanumeric-encoder)](https://www.npmjs.com/package/alphanumeric-encoder)
 [![NPM Package Size](https://img.shields.io/bundlephobia/min/alphanumeric-encoder)](https://www.npmjs.com/package/alphanumeric-encoder)
@@ -53,7 +53,7 @@
 This is useful for converting letter indexes (used by people) to numbers (used by computers). Examples include:
 
 -   Spreadsheet columns (e.g. Microsoft Excel's end column is "XFD" which corresponds to 16384)
--   Chess boards use letters and numbers to identify the grid
+-   Game boards (e.g. Chess, Battleship) use letters and numbers to identify the grid
 -   Geographic grid reference systems
 
 ### Install as an NPM Package

index.js

@@ -2,13 +2,30 @@
 
 /**
  * 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
  * @example
  * // Import into a project
  * const AlphanumericEncoder = require('alphanumeric-encoder')
+ *
  * const encoder = new AlphanumericEncoder()
+ *
+ * @example
+ * // Import into a project
+ * const AlphanumericEncoder = require('alphanumeric-encoder')
+ *
+ * const encoder = new AlphanumericEncoder({allowLowerCaseDictionary: true, dictionary: "abcdEFGH"})
+ *
+ * @example
+ * // Import into a project
+ * const AlphanumericEncoder = require('alphanumeric-encoder')
+ *
+ * const configOptions = {allowLowerCaseDictionary: true, dictionary: "abcdEFGH"}
+ * const encoder = new AlphanumericEncoder(configOptions)
  */
 class AlphanumericEncoder {
-    constructor() {
+    constructor(configOptions = {}) {
         /**
          * @private
          * @type {string} Internal value used to initialize and reset the dictionary
@@ -27,6 +44,15 @@ class AlphanumericEncoder {
         this._allowLowerCaseDictionary = false
 
         this.resetDefaultDictionary()
+
+        // Process the options. If the user included any, then the if statements will evaluate truthy and try to
+        //  set the appropriate values.
+        if (configOptions.allowLowerCaseDictionary) {
+            this.allowLowerCaseDictionary = configOptions.allowLowerCaseDictionary
+        }
+        if (configOptions.dictionary) {
+            this.dictionary = configOptions.dictionary
+        }
     }
 
     /**

index.test.js

@@ -81,6 +81,11 @@ describe('Allow Lower Case Dictionaries', () => {
             expect(encoder.allowLowerCaseDictionary).toBeFalsy()
         }
     )
+
+    test('Allow lower case dictionaries by using a config object', () => {
+        encoder = new AlphanumericEncoder({ allowLowerCaseDictionary: true })
+        expect(encoder.allowLowerCaseDictionary).toBeTruthy()
+    })
 })
 
 describe('Dictionary Validation', () => {
@@ -128,6 +133,11 @@ describe('Dictionary Validation', () => {
             encoder.dictionary = 'abcd'
             expect(encoder.dictionary).toBe('ABCD')
         })
+
+        test('Allow setting dictionaries by using a config object', () => {
+            encoder = new AlphanumericEncoder({ dictionary: 'abcd' })
+            expect(encoder.dictionary).toBe('ABCD')
+        })
     })
 
     describe('Valid Dictionaries (allow lower case)', () => {
@@ -148,6 +158,20 @@ describe('Dictionary Validation', () => {
             encoder.dictionary = complexDictionary
             expect(encoder.dictionary).toBe('ABCD123abcd')
         })
+
+        test('Allow setting lower case dictionaries by using a config object', () => {
+            encoder = new AlphanumericEncoder({
+                allowLowerCaseDictionary: true,
+                dictionary: 'abcd'
+            })
+            expect(encoder.dictionary).toBe('abcd')
+        })
+
+        test('Class should be configurable using externally defined object', () => {
+            const configOptions = { allowLowerCaseDictionary: true, dictionary: 'abcd' }
+            encoder = new AlphanumericEncoder(configOptions)
+            expect(encoder.dictionary).toBe('abcd')
+        })
     })
 
     describe('Invalid Dictionaries', () => {
@@ -170,6 +194,12 @@ describe('Dictionary Validation', () => {
                 }).toThrow(/must be alphanumeric/)
             }
         )
+
+        test('Passing invalid dictionary in options should throw error', () => {
+            expect(() => {
+                encoder = new AlphanumericEncoder({ dictionary: 'ABC@#$' })
+            }).toThrow(/must be alphanumeric/)
+        })
     })
 })