From a76db95cda0db815f0d6c631345c556eabaa24c6 Mon Sep 17 00:00:00 2001 From: M-Scott-Lassiter Date: Thu, 28 Apr 2022 15:18:53 -0700 Subject: [PATCH] docs(api): add JSDoc annotation for all major accessors and functions in the class Additionally, updates the API.md file --- API.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++------- README.md | 6 +-- index.js | 97 +++++++++++++++++++++++++++++++++++++-------- 3 files changed, 185 insertions(+), 34 deletions(-) diff --git a/API.md b/API.md index e55bff6..ee44fd3 100644 --- a/API.md +++ b/API.md @@ -4,10 +4,14 @@ - [AlphanumericEncoder][1] - [dictionary][2] - - [dictionary][3] - - [Parameters][4] + - [Parameters][3] + - [Examples][4] - [encode][5] - [Parameters][6] + - [Examples][7] + - [decode][8] + - [Parameters][9] + - [Examples][10] ## AlphanumericEncoder @@ -15,32 +19,116 @@ A class for encoding and decoding base 10 integers to a custom alphanumeric base ### dictionary -Returns the current dictionary. Default is the English alphabet in order: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' +Set or get the current dictionary. -Returns **[string][7]** The current dictionary in use - -### dictionary +Default is the English alphabet in order: `ABCDEFGHIJKLMNOPQRSTUVWXYZ` #### Parameters -- `newDictionary` **[string][7]** String of unique characters in order for the new dictionary +- `newDictionary` **[string][11]** (If setting) String of unique letters and numbers, in order, for the new dictionary + +#### Examples + +```javascript +console.log(AlphanumericEncoder.dictionary) // 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' + +AlphanumericEncoder.dictionary = 'ABCD' +console.log(AlphanumericEncoder.dictionary) // 'ABCD' + +AlphanumericEncoder.dictionary = 'ABCDA' // Throws error because the letter 'A' is repeated +``` + +Returns **[string][11]** (If used as getter) The current dictionary in use ### encode Takes any number and converts it into a base (dictionary length) letter combo. -It converts any numerical entry into a positive integer. #### Parameters -- `number` **[number][8]** Base 10 number. Must be positive and non-zero. Decimals values are truncated. +- `integerToEncode` **[number][12]** Base 10 integer. If passed a non-integer number, decimal values are truncated. + Passing zero, negative numbers, or non-numbers will return `undefined`. + +#### Examples + +```javascript +const encoder = new AlphanumericEncoder() +console.log(encoder.encode(5)) // 'E' +console.log(encoder.encode(48)) // 'AV' +console.log(encoder.encode(733)) // 'ABE' +``` + +```javascript +const encoder = new AlphanumericEncoder() +encoder.dictionary = 'ABCD' +console.log(encoder.encode(5)) // 'AA' +console.log(encoder.encode(48)) // 'BCD' +console.log(encoder.encode(733)) // 'BCACA' +``` + +```javascript +const encoder = new AlphanumericEncoder() +encoder.dictionary = 'DCBA' +console.log(encoder.encode(5)) // 'DD' +console.log(encoder.encode(48)) // 'CBA' +console.log(encoder.encode(733)) // 'CBDBD' +``` + +```javascript +const encoder = new AlphanumericEncoder() +encoder.dictionary = 'ABC123' +console.log(encoder.encode(5)) // '2' +console.log(encoder.encode(48)) // 'AA3' +console.log(encoder.encode(733)) // 'CBBA' +``` + +Returns **[string][11]** Dictionary encoded value + +### decode + +Takes any string and converts it into a base 10 integer based on the defined dictionary. + +#### Parameters + +- `stringToDecode` **[string][11]** If passed a non-integer number, decimal values are truncated. + Passing an empty string, `null`, or `undefined` will return `undefined`. + +#### Examples + +```javascript +const encoder = new AlphanumericEncoder() +console.log(encoder.decode('A')) // 1 +console.log(encoder.decode('AC')) // 29 +console.log(encoder.decode('ANE')) // 1045 +``` + +```javascript +const encoder = new AlphanumericEncoder() +console.log(encoder.decode('a')) // undefined +console.log(encoder.decode(123)) // undefined +console.log(encoder.decode('A?')) // undefined +``` + +```javascript +const encoder = new AlphanumericEncoder() +encoder.dictionary = 'ABCD' +console.log(encoder.decode('A')) // 1 +console.log(encoder.decode('AC')) // 7 +console.log(encoder.decode('ADBAC')) // 551 +console.log(encoder.decode('ANE')) // undefined +``` -Returns **[string][7]** Dictionary encoded value +Returns **[number][12]** Positive integer representation. If one of the characters is not present in the dictionary, it will return `undefined`. [1]: #alphanumericencoder [2]: #dictionary -[3]: #dictionary-1 -[4]: #parameters +[3]: #parameters +[4]: #examples [5]: #encode [6]: #parameters-1 -[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[7]: #examples-1 +[8]: #decode +[9]: #parameters-2 +[10]: #examples-2 +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number diff --git a/README.md b/README.md index ab2dd55..6c721c2 100644 --- a/README.md +++ b/README.md @@ -63,9 +63,9 @@ npm install alphanumeric-encoder ### Use in Javascript ```javascript -const alphanumericEncoder = require('alphanumeric-encoder') +const AlphanumericEncoder = require('alphanumeric-encoder') -const encoder = new alphanumericEncoder() +const encoder = new AlphanumericEncoder() console.log(encoder.encode(5)) // 'E' console.log(encoder.encode(48)) // 'AV' @@ -80,7 +80,7 @@ console.log(encoder.decode('ANE')) // 1045 ## :gear: API Documentation -See the [API](/../../blob/main/API.md) for more specific use information. +See the [API](/../../blob/main/API.md) for more specific information on how to use the class. ## :hammer_and_wrench: Node and Operating System Support Policy diff --git a/index.js b/index.js index 9b03f8c..0e58df9 100644 --- a/index.js +++ b/index.js @@ -1,24 +1,30 @@ /** * A class for encoding and decoding base 10 integers to a custom alphanumeric base representation. - * */ class AlphanumericEncoder { constructor() { + /** + * @private + * @type {string} + */ this._dictionary = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' // Default dictionary is the English alphabet, all capitalized, in order } /** - * Returns the current dictionary. Default is the English alphabet in order: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' + * Set or get the current dictionary. * - * @returns {string} The current dictionary in use - */ - get dictionary() { - return this._dictionary - } - - /** + * Default is the English alphabet in order: `ABCDEFGHIJKLMNOPQRSTUVWXYZ` * - * @param {string} newDictionary String of unique characters in order for the new dictionary + * @param {string} newDictionary (If setting) String of unique letters and numbers, in order, for the new dictionary + * @returns {string} (If used as getter) The current dictionary in use + * + * @example + * console.log(AlphanumericEncoder.dictionary) // 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' + * + * AlphanumericEncoder.dictionary = 'ABCD' + * console.log(AlphanumericEncoder.dictionary) // 'ABCD' + * + * AlphanumericEncoder.dictionary = 'ABCDA' // Throws error because the letter 'A' is repeated */ set dictionary(newDictionary) { // Check for empty dictionaries @@ -50,15 +56,46 @@ class AlphanumericEncoder { this._dictionary = uppercaseDictionary } + get dictionary() { + return this._dictionary + } + /** * Takes any number and converts it into a base (dictionary length) letter combo. - * It converts any numerical entry into a positive integer. * - * @param {number} number Base 10 number. Must be positive and non-zero. Decimals values are truncated. + * @param {number} integerToEncode Base 10 integer. If passed a non-integer number, decimal values are truncated. + * Passing zero, negative numbers, or non-numbers will return `undefined`. * @returns {string} Dictionary encoded value + * + * @example + * const encoder = new AlphanumericEncoder() + * console.log(encoder.encode(5)) // 'E' + * console.log(encoder.encode(48)) // 'AV' + * console.log(encoder.encode(733)) // 'ABE' + * + * @example + * const encoder = new AlphanumericEncoder() + * encoder.dictionary = 'ABCD' + * console.log(encoder.encode(5)) // 'AA' + * console.log(encoder.encode(48)) // 'BCD' + * console.log(encoder.encode(733)) // 'BCACA' + * + * @example + * const encoder = new AlphanumericEncoder() + * encoder.dictionary = 'DCBA' + * console.log(encoder.encode(5)) // 'DD' + * console.log(encoder.encode(48)) // 'CBA' + * console.log(encoder.encode(733)) // 'CBDBD' + * + * @example + * const encoder = new AlphanumericEncoder() + * encoder.dictionary = 'ABC123' + * console.log(encoder.encode(5)) // '2' + * console.log(encoder.encode(48)) // 'AA3' + * console.log(encoder.encode(733)) // 'CBBA' */ - encode(number) { - if (Number.isNaN(number) || number < 0) { + encode(integerToEncode) { + if (Number.isNaN(integerToEncode) || integerToEncode < 0) { return undefined } //! Number.isInteger(number) @@ -70,7 +107,7 @@ class AlphanumericEncoder { return dictionary.slice(num - 1, num) } - const baseNumber = Math.abs(Math.floor(number)) + const baseNumber = Math.abs(Math.floor(integerToEncode)) let index = baseNumber % this.dictionary.length let quotient = baseNumber / this.dictionary.length @@ -93,10 +130,36 @@ class AlphanumericEncoder { return result + numToLetter(index, this.dictionary) } - decode(encoded) { + /** + * Takes any string and converts it into a base 10 integer based on the defined dictionary. + * + * @param {string} stringToDecode If passed a non-integer number, decimal values are truncated. + * Passing an empty string, `null`, or `undefined` will return `undefined`. + * @returns {number} Positive integer representation. If one of the characters is not present in the dictionary, it will return `undefined`. + * @example + * const encoder = new AlphanumericEncoder() + * console.log(encoder.decode('A')) // 1 + * console.log(encoder.decode('AC')) // 29 + * console.log(encoder.decode('ANE')) // 1045 + * + * @example + * const encoder = new AlphanumericEncoder() + * console.log(encoder.decode('a')) // undefined + * console.log(encoder.decode(123)) // undefined + * console.log(encoder.decode('A?')) // undefined + * + * @example + * const encoder = new AlphanumericEncoder() + * encoder.dictionary = 'ABCD' + * console.log(encoder.decode('A')) // 1 + * console.log(encoder.decode('AC')) // 7 + * console.log(encoder.decode('ADBAC')) // 551 + * console.log(encoder.decode('ANE')) // undefined + */ + decode(stringToDecode) { // Takes any number encoded with the provided encode dictionary - const safeEncoded = String(encoded) // += '' // Force any numbers passed into a string format to get proper behavior below + const safeEncoded = String(stringToDecode) // += '' // Force any numbers passed into a string format to get proper behavior below if (safeEncoded === '' || safeEncoded === null || safeEncoded === undefined) { return undefined