docs: Update JSDoc, types, README, CHANGELOG

CHANGELOG.md

@@ -2,9 +2,13 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [5.2.0] - 2024-05-01
+### Added
+- `validate` method to check shortIds for simple or "complete" validity
+
 ## [5.1.0] - 2024-04-30
 ### Added
-- Added `uuid25Base36` constant to support uuid25 style
+- `uuid25Base36` constant to support uuid25 style
 
 ## [5.0.1] - 2024-04-30
 ### Changed

README.md

@@ -6,7 +6,8 @@
 
 Generate and translate standard UUIDs into shorter - or just *different* - formats and back.
 
-## v5.1.0
+## v5.2.0
+5.2.0 adds `validate` method to check short IDs. Requested by [@U-4-E-A](https://github.com/U-4-E-A)
 5.1.0 adds translation support for the [uuid25](https://github.com/uuid25/javascript) (Base36) format
 with the `uuid25Base36` constant.
 
@@ -19,14 +20,15 @@ with the `uuid25Base36` constant.
 const short = require('short-uuid');
 
 // Quick start with flickrBase58 format
-short.generate(); // 73WakrfVbNJBaAmhQtEeDv
+short.generate(); // '73WakrfVbNJBaAmhQtEeDv'
 ```
 
 ### Details
 
 short-uuid starts with RFC4122 v4-compliant UUIDs and translates them
 into other, usually shorter formats. It also provides translators
-to convert back and forth from RFC compliant UUIDs to the shorter formats.
+to convert back and forth from RFC compliant UUIDs to the shorter formats,
+and validate the IDs.
 
 As of 4.0.0, formats return consistent-length values unless specifically requested.
 This is done by padding the start with the first (`[0]`) character in the alphabet.
@@ -35,6 +37,9 @@ Previous versions can translate padded formats back to UUID.
 ```javascript
 const short = require('short-uuid');
 
+// Generate a flickrBase58 short ID from without creating a translator
+const shortId = short.generate();
+
 const translator = short(); // Defaults to flickrBase58
 const decimalTranslator = short("0123456789"); // Provide a specific alphabet for translation
 const cookieTranslator = short(short.constants.cookieBase90); // Use a constant for translation
@@ -47,11 +52,12 @@ translator.generate(); // An alias for new.
 translator.toUUID(shortId); // a44521d0-0fb8-4ade-8002-3385545c3318
 translator.fromUUID(regularUUID); // mhvXdrZT4jP5T8vBxuvm75
 
-// Generate plain UUIDs
-// - From the library without creating a translator
-short.uuid(); // fd5c084c-ff7c-4651-9a52-37096242d81c
-// - Each translator provides the uuid.v4() function, too
-translator.uuid(); // 3023b0f5-ec55-4e75-9cd8-104700698052
+// Check if a string is a valid ID (length and alphabet)
+translator.validate(shortId); // true
+
+// Check if a string is valid *AND* translates to a valid UUID
+translator.validate(shortId, true); // true
+translator.validate('0000000000000000000000', true) // false
 
 // See the alphabet used by a translator
 translator.alphabet;
@@ -64,6 +70,12 @@ translator.maxLength;
 short.constants.cookieBase90; // Safe for HTTP cookies values for smaller IDs.
 short.constants.flickrBase58; // Avoids similar characters (0/O, 1/I/l, etc.)
 short.constants.uuid25Base36; // The uuid25 (string length 25) format
+
+// Generate plain UUIDs
+// - From the library without creating a translator
+short.uuid(); // fd5c084c-ff7c-4651-9a52-37096242d81c
+// - Each translator provides the uuid.v4() function, too
+translator.uuid(); // 3023b0f5-ec55-4e75-9cd8-104700698052
 ```
 
 ### Options
@@ -87,7 +99,7 @@ translator.new(); // mhvXdrZT4jP5T8vBxuvm75
 
 ## Support
 
-short-uuid [5.x](https://github.com/oculus42/short-uuid/blob/v5.1.0/README.md)
+short-uuid [5.x](https://github.com/oculus42/short-uuid/blob/v5.2.0/README.md)
 and later is tested on Node 14.x and later.
 
 short-uuid [4.x](https://github.com/oculus42/short-uuid/blob/v3.2.2/README.md)

index.d.ts

@@ -41,6 +41,9 @@ declare module 'short-uuid' {
 
       /** long -> short */
       fromUUID(regularUUID: string | UUID): SUUID;
+
+      /** validate short */
+      validate(shortId: string | SUUID, rigorous?: boolean): boolean;
     }
   }
 

index.js

@@ -22,7 +22,7 @@ let toFlickr;
 /**
  * Takes a UUID, strips the dashes, and translates.
  * @param {string} longId
- * @param {function(string)} translator
+ * @param {function(string):string} translator
  * @param {Object} [paddingParams]
  * @returns {string}
  */
@@ -53,20 +53,27 @@ const enlargeUUID = (shortId, translator) => {
   return [m[1], m[2], m[3], m[4], m[5]].join('-');
 };
 
-// Calculate length for the shortened ID
+/**
+ * Calculate length for the shortened ID
+ * @param {number} alphabetLength
+ * @returns {number}
+ */
 const getShortIdLength = (alphabetLength) => (
   Math.ceil(Math.log(2 ** 128) / Math.log(alphabetLength)));
 
 module.exports = (() => {
   /**
-   * @param {string} toAlphabet - Defaults to flickrBase58 if not provided
-   * @param {Object} [options]
-   *
-   * @returns {{new: (function()),
-   *  uuid: (function()),
-   *  fromUUID: (function(string)),
-   *  toUUID: (function(string)),
-   *  alphabet: (string)}}
+   * @param {string} toAlphabet
+   * @param {{ consistentLength: boolean }} [options]
+   * @returns {{
+   *  alphabet: string,
+   *  fromUUID: (function(*): string),
+   *  generate: (function(): string),
+   *  maxLength: number,
+   *  new: (function(): string),
+   *  toUUID: (function(*): string),
+   *  uuid: ((function(*, *, *): (*))|*),
+   *  validate: ((function(*, boolean=false): (boolean))|*)}}
    */
   const makeConvertor = (toAlphabet, options) => {
     // Default to Flickr 58
@@ -92,15 +99,26 @@ module.exports = (() => {
     // UUIDs are in hex, so we translate to and from.
     const fromHex = anyBase(anyBase.HEX, useAlphabet);
     const toHex = anyBase(useAlphabet, anyBase.HEX);
+    /**
+     * @returns {string} - short id
+     */
     const generate = () => shortenUUID(uuidV4(), fromHex, paddingParams);
 
-    const validate = (shortId, checkUuid = false) => {
+    /**
+     * Confirm if string is a valid id. Checks length and alphabet.
+     * If the second parameter is true it will translate to standard UUID
+     *  and check the result for UUID validity.
+     * @param {string} shortId - The string to check for validity
+     * @param {boolean} [rigorous=false] - If true, also check for a valid UUID
+     * @returns {boolean}
+     */
+    const validate = (shortId, rigorous = false) => {
       if (!shortId || typeof shortId !== 'string') return false;
       const isCorrectLength = selectedOptions.consistentLength
         ? shortId.length === shortIdLength
         : shortId.length <= shortIdLength;
-      const onlyAlphabet = shortId?.split('').every((letter) => useAlphabet.includes(letter));
-      if (checkUuid === false) return isCorrectLength && onlyAlphabet;
+      const onlyAlphabet = shortId.split('').every((letter) => useAlphabet.includes(letter));
+      if (rigorous === false) return isCorrectLength && onlyAlphabet;
       return isCorrectLength && onlyAlphabet && uuidValidate(enlargeUUID(shortId, toHex));
     };