feat: add isInteger function for integer validation (#59)

* feat: add isInteger function for integer validation

- Implemented isInteger function to validate if a string represents an integer value.
- Updated metadata documentation to include isInteger with examples.
- Added isInteger to index exports and relevant types.
- Enhanced existing validation functions (isASCII, isAlphanumeric, isEmail, isHexColor, isUUID, isUrl) to trim leading and trailing whitespace.
- Created comprehensive tests for isInteger covering valid, invalid, and edge cases.
- Updated assertions and builders to support IntegerString branded type.

* refactor: use trimmed variable for string validation in multiple functions

* chore(release): bump version to 0.24.0 and update changelog with new features and enhancements

* chore: update version to 0.24.0 in package-lock.json

Author: Zheruel

CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] - 2025-11-07
+
+### Added
+
+- **New Function: `isInteger()`** - Validates if a string represents an integer value (whole number without decimals)
+  - Handles positive and negative integers (`42`, `-17`)
+  - Rejects decimal numbers (`3.14`, `42.0`) - key difference from `isNumeric`
+  - Automatic whitespace trimming
+  - Rejects empty strings, `Infinity`, and scientific notation
+  - Bundle size: 120 bytes gzipped
+  - 100% test coverage with 80+ test scenarios
+  - Use cases: age validation, pagination parameters, database ID validation, e-commerce quantities
+
+- **Branded Type Integration for IntegerString** - Full type-safe integer string handling
+  - New `IntegerString` branded type for compile-time safety
+  - Type guard: `isValidInteger()` for type narrowing
+  - Builder function: `toIntegerString()` returns `IntegerString | null` with validation
+  - Assertion function: `assertIntegerString()` throws `BrandedTypeError` on invalid input
+  - Unsafe cast: `unsafeIntegerString()` for trusted input (no validation)
+  - Zero runtime overhead - type safety enforced at compile time
+
+- **CLI Support** - `isInteger` available via `nano-string` command
+  - `nano-string isInteger "42"` - returns true/false with proper exit codes
+  - Pipe support for Unix-style command chaining
+
+### Enhanced
+
+- **Whitespace Handling** - Consistent trimming across validation functions
+  - Updated 6 existing validation functions to trim leading/trailing whitespace before validation
+  - Functions enhanced: `isASCII`, `isAlphanumeric`, `isEmail`, `isHexColor`, `isUUID`, `isUrl`
+  - Quality-of-life improvement that handles common user input patterns (e.g., `"  user@email.com  "`)
+  - All functions now document whitespace trimming behavior in JSDoc
+  - Additional test coverage for whitespace handling in each function
+
+### Improved
+
+- **Code Consistency** - Standardized variable naming patterns
+  - All validation functions now use consistent `const trimmed = str.trim()` pattern instead of reassignment
+  - More explicit code that avoids parameter mutation
+  - Better maintainability across the codebase
+  - Follows best practices established in `isInteger` and `isNumeric`
+
+### Documentation
+
+- Updated function count from 51 to 52 utilities
+- Added comprehensive JSDoc documentation for `isInteger` with real-world usage examples
+- Updated README with function descriptions, comparison table vs `isNumeric`, examples, and bundle sizes
+- Added metadata and playground examples to documentation site
+- Regenerated bundle size and performance benchmark data
+
 ## [0.23.0] - 2025-10-21
 
 ### Added

README.md

@@ -177,7 +177,7 @@ fuzzyMatch("usrctrl", "userController.js"); // { matched: true, score: 0.444 }
 fuzzyMatch("of", "openFile"); // { matched: true, score: 0.75 }
 ```
 
-> 📖 **See all 45 functions in the API Reference below**
+> 📖 **See all 52 functions in the API Reference below**
 
 ## CLI
 
@@ -269,6 +269,7 @@ nano-string isUrl "https://example.com"             # true
 nano-string isASCII "hello"                         # true
 nano-string isHexColor "#ff5733"                    # true
 nano-string isNumeric "42"                          # true
+nano-string isInteger "42"                          # true
 nano-string isAlphanumeric "user123"                # true
 nano-string isUUID "550e8400-e29b-41d4-a716-446655440000"  # true
 ```
@@ -297,7 +298,7 @@ nano-string slugify --help
 
 ## API Reference
 
-The library provides 51 string utility functions organized by category. Click on any category to explore the available functions.
+The library provides 52 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>
@@ -810,7 +811,7 @@ humanizeList([]);
 </details>
 
 <details>
-<summary><b>✅ Validation Functions (8 functions)</b></summary>
+<summary><b>✅ Validation Functions (9 functions)</b></summary>
 
 ### String Validation
 
@@ -879,6 +880,24 @@ isNumeric("Infinity"); // false
 isNumeric("1e5"); // false (scientific notation not supported)
 ```
 
+#### `isInteger(str: string): boolean`
+
+Validates if a string represents an integer value (whole number without decimals). Useful for validating age fields, quantities, IDs, pagination parameters, and other inputs that should only accept whole numbers.
+
+```javascript
+isInteger("42"); // true
+isInteger("-17"); // true
+isInteger("0"); // true
+isInteger("  42  "); // true (whitespace trimmed)
+isInteger("007"); // true (leading zeros allowed)
+isInteger("3.14"); // false (decimal number)
+isInteger("42.0"); // false (contains decimal point)
+isInteger("abc"); // false
+isInteger(""); // false
+isInteger("Infinity"); // false
+isInteger("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.
@@ -1567,6 +1586,7 @@ Each utility is optimized to be as small as possible:
 | isASCII               | 128 bytes      |
 | isHexColor            | 103 bytes      |
 | isNumeric             | 122 bytes      |
+| isInteger             | 120 bytes      |
 | isAlphanumeric        | 88 bytes       |
 | isUUID                | 89 bytes       |
 | toASCII               | 1.3 KB         |

benchmarks/bundle-sizes.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2025-10-21T22:00:10.658Z",
+  "generated": "2025-10-23T20:56:17.411Z",
   "totalFunctions": 52,
   "functions": [
     {
@@ -204,11 +204,11 @@
       "nano": {
         "bundled": {
           "raw": 1030,
-          "gzip": 573
+          "gzip": 572
         },
         "treeShaken": {
           "raw": 1030,
-          "gzip": 573
+          "gzip": 572
         }
       },
       "lodash": null,
@@ -451,11 +451,11 @@
       "nano": {
         "bundled": {
           "raw": 919,
-          "gzip": 473
+          "gzip": 472
         },
         "treeShaken": {
           "raw": 919,
-          "gzip": 473
+          "gzip": 472
         }
       },
       "lodash": null,
@@ -467,11 +467,11 @@
       "nano": {
         "bundled": {
           "raw": 555,
-          "gzip": 335
+          "gzip": 334
         },
         "treeShaken": {
           "raw": 555,
-          "gzip": 335
+          "gzip": 334
         }
       },
       "lodash": null,
@@ -817,11 +817,11 @@
       "nano": {
         "bundled": {
           "raw": 818,
-          "gzip": 502
+          "gzip": 501
         },
         "treeShaken": {
           "raw": 818,
-          "gzip": 502
+          "gzip": 501
         }
       },
       "lodash": null,