Add Three New Validation Functions (#51)

* add isNumeric, isAlphaNumeric and isUUID

* remove stray "s"

* package lock fix

* bump version

Author: Zheruel

CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2025-10-21
+
+### Added
+
+- **New Function: `isNumeric()`** - Validates if a string represents a numeric value (integer or decimal)
+
+  - Handles positive and negative integers (`42`, `-17`)
+  - Supports decimal numbers (`3.14`, `-0.5`)
+  - Automatic whitespace trimming
+  - Rejects empty strings, `Infinity`, and scientific notation
+  - Bundle size: 122 bytes gzipped
+  - 100% test coverage
+  - Use cases: form validation, CSV parsing, API input validation
+
+- **New Function: `isAlphanumeric()`** - Validates if a string contains only alphanumeric characters (a-z, A-Z, 0-9)
+
+  - Strict ASCII validation (no Unicode, special characters, or whitespace)
+  - Perfect for username validation, identifiers, and tokens
+  - Bundle size: 88 bytes gzipped
+  - 100% test coverage
+  - Use cases: username validation, identifier validation, input sanitization
+
+- **New Function: `isUUID()`** - Validates if a string is a valid UUID in standard 8-4-4-4-12 format
+
+  - Supports all UUID versions (v1-v5)
+  - Accepts NIL UUID (`00000000-0000-0000-0000-000000000000`)
+  - Case-insensitive validation
+  - Bundle size: 89 bytes gzipped
+  - 100% test coverage
+  - Use cases: API identifier validation, session token validation, database ID validation
+
+- **Branded Type Integration** - Full type-safe handling for all three validation functions
+
+  - New branded types: `NumericString`, `AlphanumericString`, `UUID`
+  - Type guards: `isValidNumeric()`, `isValidAlphanumeric()`, `isValidUUID()`
+  - Builder functions: `toNumericString()`, `toAlphanumericString()`, `toUUID()`
+  - Assertion functions: `assertNumericString()`, `assertAlphanumericString()`, `assertUUID()`
+  - Unsafe casts: `unsafeNumericString()`, `unsafeAlphanumericString()`, `unsafeUUID()`
+  - Zero runtime overhead - type safety enforced at compile time
+
+- **CLI Support** - All three functions available via `nano-string` command
+  - `nano-string isNumeric "42"` - returns true/false with proper exit codes
+  - `nano-string isAlphanumeric "user123"` - validates alphanumeric strings
+  - `nano-string isUUID "550e8400-e29b-41d4-a716-446655440000"` - validates UUIDs
+  - Pipe support for Unix-style command chaining
+
+### Documentation
+
+- Updated function count from 48 to 51 utilities
+- Added comprehensive JSDoc documentation with real-world usage examples
+- Updated README with function descriptions, examples, and bundle sizes
+- Added metadata and playground examples to documentation site
+- Regenerated bundle size and performance benchmark data
+- Updated CLI help with new validation functions
+
 ## [0.22.0] - 2025-10-16
 
 ### Improved

README.md

@@ -264,9 +264,13 @@ nano-string humanizeList "apple,banana,orange" --conjunction "or"  # apple, bana
 #### Validation functions
 
 ```bash
-nano-string isEmail "[email protected]"       # true
-nano-string isUrl "https://example.com"      # true
-nano-string isASCII "hello"                  # true
+nano-string isEmail "[email protected]"              # true
+nano-string isUrl "https://example.com"             # true
+nano-string isASCII "hello"                         # true
+nano-string isHexColor "#ff5733"                    # true
+nano-string isNumeric "42"                          # true
+nano-string isAlphanumeric "user123"                # true
+nano-string isUUID "550e8400-e29b-41d4-a716-446655440000"  # true
 ```
 
 #### Analysis functions
@@ -293,7 +297,7 @@ nano-string slugify --help
 
 ## API Reference
 
-The library provides 48 string utility functions organized by category. Click on any category to explore the available functions.
+The library provides 51 string utility functions organized by category. Click on any category to explore the available functions.
 
 <details>
 <summary><b>🔤 Case Conversion Functions (10 functions)</b></summary>
@@ -806,7 +810,7 @@ humanizeList([]);
 </details>
 
 <details>
-<summary><b>✅ Validation Functions (4 functions)</b></summary>
+<summary><b>✅ Validation Functions (8 functions)</b></summary>
 
 ### String Validation
 
@@ -845,6 +849,68 @@ isASCII("abc123!@#"); // true
 isASCII(""); // true
 ```
 
+#### `isHexColor(str: string): boolean`
+
+Validates if a string is a valid hexadecimal color code.
+
+```javascript
+isHexColor("#fff"); // true (3-digit)
+isHexColor("#ffffff"); // true (6-digit)
+isHexColor("#fff8"); // true (4-digit with alpha)
+isHexColor("#ffffff80"); // true (8-digit with alpha)
+isHexColor("#FFF"); // true (case-insensitive)
+isHexColor("fff"); // false (missing #)
+isHexColor("#gggggg"); // false (invalid characters)
+```
+
+#### `isNumeric(str: string): boolean`
+
+Validates if a string represents a numeric value (integer or decimal).
+
+```javascript
+isNumeric("42"); // true
+isNumeric("-17"); // true
+isNumeric("3.14"); // true
+isNumeric("-0.5"); // true
+isNumeric("  42  "); // true (whitespace trimmed)
+isNumeric("abc"); // false
+isNumeric(""); // false
+isNumeric("Infinity"); // false
+isNumeric("1e5"); // false (scientific notation not supported)
+```
+
+#### `isAlphanumeric(str: string): boolean`
+
+Validates if a string contains only alphanumeric characters (a-z, A-Z, 0-9). Useful for validating usernames, identifiers, and other inputs that should not contain special characters or whitespace.
+
+```javascript
+isAlphanumeric("user123"); // true
+isAlphanumeric("HelloWorld"); // true
+isAlphanumeric("ABC123XYZ"); // true
+isAlphanumeric("test"); // true
+isAlphanumeric("123"); // true
+isAlphanumeric("hello_world"); // false (underscore not allowed)
+isAlphanumeric("hello world"); // false (whitespace not allowed)
+isAlphanumeric("test-123"); // false (hyphen not allowed)
+isAlphanumeric("café"); // false (Unicode not allowed)
+isAlphanumeric(""); // false (empty string)
+```
+
+#### `isUUID(str: string): boolean`
+
+Validates if a string is a valid UUID (Universally Unique Identifier) in the standard 8-4-4-4-12 format. Accepts all UUID versions (v1-v5), the NIL UUID, and is case-insensitive. Perfect for validating API identifiers, session tokens, and database IDs.
+
+```javascript
+isUUID("550e8400-e29b-41d4-a716-446655440000"); // true (v4)
+isUUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8"); // true (v1)
+isUUID("00000000-0000-0000-0000-000000000000"); // true (NIL UUID)
+isUUID("550E8400-E29B-41D4-A716-446655440000"); // true (uppercase)
+isUUID("550e8400e29b41d4a716446655440000"); // false (no hyphens)
+isUUID("550e8400-e29b-41d4-a716"); // false (too short)
+isUUID("not-a-uuid"); // false (invalid format)
+isUUID(""); // false (empty string)
+```
+
 #### `detectScript(str: string): 'latin' | 'cjk' | 'arabic' | 'cyrillic' | 'hebrew' | 'devanagari' | 'greek' | 'thai' | 'unknown'`
 
 Detects the dominant writing system (script) in a text string.
@@ -1499,6 +1565,10 @@ Each utility is optimized to be as small as possible:
 | isEmail               | 148 bytes      |
 | isUrl                 | 155 bytes      |
 | isASCII               | 128 bytes      |
+| isHexColor            | 103 bytes      |
+| isNumeric             | 122 bytes      |
+| isAlphanumeric        | 88 bytes       |
+| isUUID                | 89 bytes       |
 | toASCII               | 1.3 KB         |
 | wordCount             | 123 bytes      |
 | normalizeWhitespace   | 268 bytes      |

benchmarks/all-functions.json

@@ -1,4 +1,7 @@
 [
+  "assertAlphanumericString",
+  "assertNumericString",
+  "assertUUID",
   "camelCase",
   "capitalize",
   "classifyText",
@@ -17,9 +20,15 @@
   "highlight",
   "humanizeList",
   "isASCII",
+  "isAlphanumeric",
   "isEmail",
   "isHexColor",
+  "isNumeric",
+  "isUUID",
   "isUrl",
+  "isValidAlphanumeric",
+  "isValidNumeric",
+  "isValidUUID",
   "kebabCase",
   "levenshtein",
   "levenshteinNormalized",
@@ -46,6 +55,12 @@
   "templateSafe",
   "titleCase",
   "toASCII",
+  "toAlphanumericString",
+  "toNumericString",
+  "toUUID",
   "truncate",
+  "unsafeAlphanumericString",
+  "unsafeNumericString",
+  "unsafeUUID",
   "wordCount"
 ]