Cleaner Node (cleaner-node)

Helpful utilities and scripts to make Node projects more legible and easier for the next developer to take over.

📦 TypeScript Version Now Available!

A new TypeScript-first version of this library has been created and is available on NPM as cleaner-node-ts.

Key points:

• The original JavaScript package (cleaner-node) and TypeScript package (cleaner-node-ts) are currently being maintained separately
• The TypeScript version (cleaner-node-ts) is fully backwards compatible with the original API
• Eventually, the TypeScript codebase will replace this JavaScript version

Installation:

• Original JavaScript version: npm install cleaner-node
• New TypeScript version: npm install cleaner-node-ts

The new TypeScript version offers the same functionality with the added benefits of full type safety, better IDE support, and modern JavaScript features while maintaining 100% API compatibility.

Background

There are several libraries out there designed to make life easier for developers (moment, lodash, underscore, etc.). However, for the most part, the goals of those utilities are to add on to what Node and JavaScript bring to the table. And, as Node and JavaScript mature, developers find them to be less of a necessity and end up removing them. While cleaner-node is also a helper package, and completely unnecessary, its goal is to abstract some of the more redundant and verbose syntaxes. The end result is a codebase that still functions as it would without cleaner-node but is easier to read and maintain. Unlike those other libraries, which shrink over time, I intend on growing cleaner-node for as long as Node exists so that I don't have to write the same code again, and again, and again, and again, and ag....

Requirements

• Node.js: >= 20.0.0
• Dependencies: jsonwebtoken, uuid, semver, rimraf

Installation

npm install cleaner-node

Quick Start

const _ = require('cleaner-node');

// String manipulation
const cleaned = _.cleanString('  Hello World!  '); // "Hello World!"
const isValid = _.isValidString(cleaned); // true
const email = _.getEmail('Contact us at [email protected] today'); // "[email protected]"

// Array operations  
const unique = _.unique([1, 2, 2, 3, 3, 3]); // [1, 2, 3]
const first = _.getFirst(['a', 'b', 'c']); // 'a'
const count = _.getArrayCount([1, 2, 3]); // 3

// Validation
const isEmail = _.isEmail('[email protected]'); // true
const isGuid = _.isGuidFormat('550e8400-e29b-41d4-a716-446655440000'); // true
const isCamel = _.isCamelCase('myVariableName'); // true

// File operations (synchronous)
const exists = _.isFile('./package.json'); // true
const content = _.readFile('./package.json'); // file contents as string
const files = _.getFiles('./src'); // array of file paths

// Object manipulation
const cleaned = _.cleanObject({ name: 'John', age: undefined, city: 'NYC' }); 
// Result: { name: 'John', city: 'NYC' } (undefined removed)

// Date utilities
const tomorrow = _.addDays(new Date(), 1); // adds 1 day to current date
const timestamp = _.toEpoch(new Date()); // converts to Unix timestamp

// ID generation
const guid = _.newGuid(); // "550e8400-e29b-41d4-a716-446655440000"
const uid = _.newUid(); // "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"

// HTTP requests
const response = await _.doGet('https://api.example.com/data');
const result = await _.doPost('https://api.example.com/users', { name: 'John' });

Documentation

📚 Comprehensive documentation is now available in the /docs directory!

Each function has its own detailed documentation file with:

• Clear purpose and description
• Complete parameter documentation
• Multiple usage examples
• Edge cases and error handling
• Related functions and cross-references

Quick Links:

• 📖 Full Documentation Index - Complete navigation to all functions
• 🔍 String Functions - String manipulation utilities
• 📊 Array Functions - Array processing utilities
• ✅ Validation Functions - Type checking and validation
• 🛠️ Utility Functions - General purpose utilities

For AI Tools: The documentation is specifically structured to help AI tools understand and generate code using the cleaner-node package. Each function includes comprehensive examples and clear parameter descriptions.

Popular Functions

Here are some of the most commonly used functions in cleaner-node:

Note: This is just a small selection of popular functions. The complete library includes 194 functions covering string manipulation, file operations, validation, HTTP requests, date handling, cryptography, and much more. See the complete function reference below or the full documentation for all available functions.

🔥 Most Popular

• isValidString(value) - Comprehensive string validation
• cleanString(value) - Clean and normalize strings
• isEmail(value) - Email address validation
• newGuid() - Generate UUID v4
• copyObject(obj) - Deep copy objects
• readFile(path) - Synchronous file reading
• isFile(path) / isFolder(path) - Path existence checking

⚡ String Utilities

• trimToNull(str) - Trim string or return null if empty
• getEmail(text) - Extract first email from text
• cleanAlphanumeric(str) - Keep only letters and numbers
• isCamelCase(str) / toCamelCase(str) - Case checking/conversion

📋 Array & Object Tools

• unique(array) - Remove duplicates intelligently
• getFirst(array) / getLast(array) - Safe array access
• removeProperty(obj, key) - Remove property recursively
• cleanObject(obj) - Remove undefined values

🛡️ Validation Suite

• isGuidFormat(str) - GUID format validation
• isValidArray(arr) - Array validation with options
• isNumber(value) - Flexible number checking
• isDefined(value) - Check if not undefined

Functions & Usage

String Manipulation

| Function | Description | |---|---| | cleanAlphaNumeric | Convenience alias for cleanAlphanumeric. | | cleanAlphanumeric | Removes all characters from a string except for letters and numbers. | | cleanDigits | Removes all non-digit characters from a string. | | cleanString | Cleans a string by keeping only specified valid characters and removing specified invalid characters. | | getBracket | Finds the matching bracket pair that encloses the given string value. | | getEmail | Extracts the first valid email address found in a string. | | getEmails | Extracts all valid email addresses found in a string using a regular expression. | | getInnerTokens | Extracts the innermost content enclosed by a specified pair of opening and closing brackets/tokens. | | getPadPrefix | Gets the leading whitespace (prefix padding) of a string. | | getPadSuffix | Gets the trailing whitespace (suffix padding) of a string. | | getPads | Calculates the length of leading (prefix) and trailing (suffix) whitespace in a string. | | getStringSize | Calculates the byte size of a string using the specified encoding. | | getSubstring | Finds the longest common starting substring among an array of strings. | | getTokenizedSegments | Extracts segments from a string that are enclosed by specified opening and closing brackets. | | hasString | Checks if a string contains a target substring, with optional case sensitivity. | | removePrefix | Removes a specified prefix from the beginning of a string, potentially multiple times. | | removeSuffix | Removes a specified suffix from the end of a string, potentially multiple times. | | splitFirst | Splits a string at the first occurrence of a specified separator. | | stringify | Converts a JavaScript value to a JSON string, safely handling circular references. | | toCamelCase | Converts a string to camelCase. | | toKebabCase | Converts a string to kebab-case. | | toPascalCase | Converts a string to PascalCase. | | toReq | Convenience alias for toRequest. | | toSnakeCase | Converts a string to snake_case. | | trimString | Trims leading and trailing whitespace from a string. | | trimToNull | Trims leading and trailing whitespace from a string, returning null if empty. | | trimToUndefined | Trims leading and trailing whitespace from a string, returning undefined if empty. | | undouble | Replaces consecutive occurrences of specified target characters within a string with a single instance. | | unQuote | Convenience alias for unquote. | | unquote | Removes leading and trailing quote characters (") from a string. |

File System Operations

| Function | Description | |---|---| | copyContents | Asynchronously copies the contents of a source file to a destination file, line by line. | | copyFile | Synchronously copies a file from a source path to a target path. | | createPath | Creates a directory path recursively if it doesn't already exist. | | deleteDirectory | Synchronously deletes a directory and its contents recursively. | | deleteFile | Synchronously deletes a file. | | getCommonPath | Finds the longest common base directory path from an array of file paths. | | getFileContents | Synchronously reads the contents of a file. | | getFileName | Extracts the file name from a file path, optionally including or excluding the extension. | | getFileSize | Gets the size of a file in bytes. | | getFiles | Synchronously reads the contents of a directory and returns an array of full paths for its direct children (files and subdirectories). | | getFolderContents | Convenience alias for getFiles. | | isFile | Checks if a given path points to an existing file. | | isFolder | Checks if a given path points to an existing directory. | | isDirectory | Convenience alias for isFolder. | | isValidPath | Checks if a string appears to be a valid file/folder path based on its basename. | | isValidPathIfSet | Checks if a value is not set or is a valid path. | | loadJson | Reads a file, parses its content as JSON, and returns the resulting object or array. | | makePath | Convenience alias for createPath. | | moveFile | Moves a file from a source path to a destination path. | | readFile | Convenience alias for getFileContents. | | readLines | Asynchronously reads a file line by line and returns an array of strings. | | saveJson | Converts an object or array to a JSON string and saves it to a file. | | walk | Walks a directory recursively and returns an object containing lists of all files and folders found. | | writeFile | Writes content to a file, creating the necessary directory structure if it doesn't exist. | | writeLines | Writes an array of strings to a file, joining them with the OS-specific end-of-line character. |

Date & Time

| Function | Description | |---|---| | addDays | Adds a specified number of days to a date. | | addMinutes | Adds a specified number of minutes to a date. | | addMonths | Adds a specified number of months to a date. | | addYears | Adds a specified number of years to a date. | | blockdate | Module containing blockdate utilities (fromBlockDate, isBlockDate, etc.). | | fromBlockDate | Converts a blockdate string to a JavaScript Date object. | | fromEpoch | Converts a Unix epoch timestamp (seconds) to a JavaScript Date object. | | fromIsoDate | Converts an ISO 8601 date string to a JavaScript Date object. | | fromShortDate | Converts a short date string (YYYY-MM-DD or YYYY/MM/DD) to a JavaScript Date object. | | getBlockDate | Formats a Date object into a blockdate string (e.g., YYYYMMDDHHmmssSSS). | | getDayName | Gets the full name of the day of the week for a given Date or ISO date string. | | getDuration | Calculates the duration between two timestamps (or Date objects) and formats it. | | maxDate | Finds the latest date from an array of Date objects. | | minDate | Finds the earliest date from an array of Date objects. | | now | Returns the current date and time. | | toEpoch | Converts a Date object to its Unix epoch timestamp (seconds). |

Object & Array Processing

| Function | Description | |---|---| | ascending | Sorts an array in ascending order (convenience function). | | cleanDto | Cleans DTOs by removing audit fields, handling ID/UID properties, removing nulls etc. Modifies input in place. | | cleanObject | Recursively cleans an object or array by removing properties with undefined values. | | copy | Convenience alias for copyObject. | | copyObject | Creates a deep copy of an object using JSON stringification and parsing. | | count | Convenience alias for getArrayCount. | | descending | Sorts an array in descending order (convenience function). | | findAllUids | Finds all unique UID strings within an object or array, including nested structures. | | first | Convenience alias for getFirst. | | fromDto | Converts string representations within DTOs to JS types (e.g., ISO strings to Dates). Modifies input in place. | | fromResult | Extracts the nested 'result' property from an object recursively. | | getArrayCount | Gets the length of an array, handling non-arrays gracefully. | | getEnum | Retrieves the enum value from an object. | | getEnums | Extracts enum values from a given object or array of objects. | | getFirst | Gets the first element of an array or the first character of a string. | | getId | Extracts an ID ('id' or '_id') from an object or returns the input if already an ID. | | getIds | Extracts IDs from an array of items or IDs, ensuring each item is processed by getId. | | getLast | Gets the last element of an array or the last character of a string. | | getMax | Finds the maximum numeric value in an array. | | getMin | Finds the minimum numeric value in an array. | | getSingle | Returns the first element of an array if it contains exactly one element, otherwise undefined. | | getUid | Extracts a UID/GUID from an item or returns the input if it's already valid. | | getUids | Extracts UIDs from an array of items, ensuring each item is processed by getUid. | | initArray | Ensures the input value is an array and filters out undefined elements. | | last | Convenience alias for getLast. | | max | Convenience alias for getMax. | | min | Convenience alias for getMin. | | print | Prints the key-value pairs of an object to the console in a formatted manner. | | removeAuditFields | Recursively removes standard audit fields from an object or array. | | removeDeleted | Recursively removes items marked as deleted (using a checker function) from a structure. | | removeProperty | Recursively removes a specified property from an object and nested structures. | | replaceValues | Recursively replaces values within an object or array structure based on source/target arrays. | | single | Convenience alias for getSingle. | | sort | Sorts an array containing numbers (or string representations), filtering non-numerics. | | toColumn | Formats an array of values into a single column of strings, padded to the width of the longest value. | | toRequest | Transforms a raw HTTP request object into a standardized format. | | toResponse | Formats a response based on the structure of the original input (object/array). | | toResult | Returns a single item or an array based on the sample array. | | toTable | Converts an array of delimited strings into a formatted text table with borders. | | trimArray | Trims leading/trailing non-valid-string elements from an array. | | unique | Creates a new array with unique values based on the predominant data type (numbers, objects, or strings). | | uniqueNumbers | Filters an array to contain only unique numbers or string representations of numbers. | | uniqueObjects | Filters an array to contain only unique objects (by strict equality or stringification). | | uniqueStrings | Filters an array to contain only unique strings (case-sensitive/trim options available). |

Validation & Type Checking

| Function | Description | |---|---| | isAlpha | Checks if a string contains only alphabetic characters. | | isAlphaNumeric | Convenience alias for isAlphanumeric. | | isAlphanumeric | Checks if a string contains only alphanumeric characters. | | isAsync | Checks if a value is an async function. | | isBlockDate | Checks if a value is a valid blockdate format. | | isBoolean | Checks if a value is strictly true or false. | | isBooleanIfSet | Checks if a value is not set (null/undefined) or is a boolean. | | isBracketted | Checks if a string starts and ends with corresponding brackets. | | isCamelCase | Checks if a string is in camelCase format. | | isCaps | Checks if a string is entirely uppercase. | | isDate | Checks if a value is a valid JavaScript Date object. | | isDefined | Checks if a value is defined (not undefined). | | isDeleted | Checks if an item is considered "deleted" based on a provided checking function. | | isDigits | Checks if a string contains only numeric digits. | | isEmptyArray | Checks if a value is an array that contains no elements. | | isEmail | Checks if a string is a valid email address format. | | isEqualDate | Checks if two values are valid Dates representing the exact same time. | | isFunction | Checks if a value is a function. | | isGuidFormat | Checks if a value conforms to the standard GUID format. | | isIpAddress | Checks if a string represents a valid IPv4 address (allows 'localhost', '0.0.0.0'). | | isIsoDate | Checks if a string represents a valid ISO 8601 date format. | | isJson | Checks if a string is valid JSON (either an object or array). | | isJsonArray | Checks if a string is a valid JSON array, including whitespace handling and validation. | | isJsonObject | Checks if a string is a valid JSON object, including whitespace handling and validation. | | isKebabCase | Checks if a string is in kebab-case format. | | isLowerCase | Checks if a string is entirely lowercase. | | isMatch | Compares two strings for equality with options for case sensitivity and whitespace. | | isNumber | Checks if a value can be interpreted as a finite number. | | isObject | Checks if a value is a plain JavaScript object (not null, not an array). | | isPascalCase | Checks if a string is in PascalCase format. | | isPhoneNumber | Checks if a string matches a common phone number format. | | isSameDate | Convenience alias for isEqualDate. | | isSemver | Checks if a string is a valid Semantic Versioning (SemVer) string. | | isSet | Checks if a value is neither null nor undefined. | | isShortDate | Checks if a string represents a valid date in YYYY/MM/DD or YYYY-MM-DD format. | | isSnakeCase | Checks if a string is in snake_case format. | | isUidFormat | Checks if a value is a valid UID format (32 alphanumeric chars). | | isUrl | Checks if a string is a valid URL (starts with http/https and is parseable). | | isValidArray | Checks if a value is an array and optionally if it's non-empty. | | isValidArrayIfSet | Checks if a value is not set or is a valid array. | | isValidChars | Checks if a string contains only characters from a specified set. | | isValidObject | Checks if a value is a non-empty plain JavaScript object. | | isValidString | Checks if a value is a string and optionally if it's non-empty after trimming. | | isValidStringIfSet | Checks if a value is not set or is a valid string. | | isZeroDate | Checks if a value represents the "zero date" (epoch or constant). |

Data Conversion & Formatting

| Function | Description | |---|---| | fromDto | Converts string representations within DTOs to JS types (e.g., ISO strings to Dates). Modifies input in place. | | getCircularReplacer | Creates a replacer function for JSON.stringify that handles circular references. | | parseJson | Safely parses a JSON string into a JavaScript object. | | stringify | Converts a JavaScript value to a JSON string, safely handling circular references. | | toBoolean | Converts various input types (boolean, string, number) into a boolean value. | | toCamelCase | Converts a string to camelCase. | | toColumn | Formats an array of values into a single column of strings, padded to the width of the longest value. | | toGuidFormat | Converts a UID or GUID string into the standard lowercase GUID format. | | toKebabCase | Converts a string to kebab-case. | | toPascalCase | Converts a string to PascalCase. | | toRequest | Transforms a raw HTTP request object into a standardized format. | | toSnakeCase | Converts a string to snake_case. | | toTable | Converts an array of delimited strings into a formatted text table with borders. | | toUidFormat | Converts a GUID or UID string into the standard 32-character uppercase UID format. |

Environment & Configuration

| Function | Description | |---|---| | getVars | Retrieves environment variables, optionally filtering and sorting. |

Hashing, Cryptography & JWT

| Function | Description | |---|---| | decode | Decodes a JWT token without verifying the signature. | | decryptString | Decrypts a string that was encrypted using encryptString function with the same password. | | encode | Encodes (signs) a payload into a JWT token. | | encryptString | Encrypts a string using AES-256-CBC encryption with a password. | | fromClaims | Converts a standard JWT claims object into an application-specific payload object. | | getHash | Calculates the MD5 hash of a given string value. | | hash | Computes an HMAC hash of a value using a salt. | | hashFile | Computes a hash of a file's contents synchronously. | | hashFileContents | Computes a hash of the file contents asynchronously. | | hashLines | Computes a hash of an array of lines. | | hashObject | Generates a hash value for a given object or array by converting it to a string representation and then computing its hash. | | hashString | Computes a hash (md5/hex by default) of a string. | | newSalt | Generates a cryptographically random salt string. | | parseJwt | Parses a JWT, returning details including claims, payload, validity, and expiration status. | | toClaims | Converts an application-specific payload object into a standard JWT claims object. | | verify | Verifies a JWT token using a secret or public key. |

Networking & HTTP

| Function | Description | |---|---| | doDelete | Performs a DELETE request. | | doGet | Performs a GET request. | | doPost | Performs a POST request. | | doPut | Performs a PUT request. | | getBody | Asynchronously extracts the request body from a request object (Node/Next.js). | | ping | Performs a GET request to the root path ('/') to check connectivity. |

Utility Modules & Framework Integration

| Function | Description | |---|---| | body | Experimental utility for extracting request body with auto-detection. | | comments | Module containing comment utilities (hasComments, removeComments). | | env | Module containing environment variable utilities. | | execute | Convenience alias for execution.execute. | | executePromise | Convenience alias for execution.executePromise. | | execution | Module containing command execution utilities. | | express | Module containing Express.js utilities and middleware. | | hasComments | Checks if code contains comments. | | jwt | Module containing JWT utilities (decode, encode, parseJwt, etc.). | | nextjs | Module containing Next.js utilities. | | removeComments | Removes comments from code. |

Hashing & Cryptography

| Function | Description | |---|---| | decryptString | Decrypts a string that was encrypted using encryptString function with the same password. | | encryptString | Encrypts a string using AES-256-CBC encryption with a password. | | getHash | Calculates the MD5 hash of a given string value. | | hash | Computes an HMAC hash of a value using a salt. | | hashFile | Computes a hash of a file's contents synchronously. | | hashFileContents | Computes a hash of the file contents asynchronously. | | hashLines | Computes a hash of an array of lines. | | hashObject | Generates a hash value for a given object or array by converting it to a string representation and then computing its hash. | | hashString | Computes a hash (md5/hex by default) of a string. | | newSalt | Generates a cryptographically random salt string. | | parseJwt | Parses a JWT, returning details including claims, payload, validity, and expiration status. |

Data Parsing & Conversion

| Function | Description | |---|---| | parseJson | Safely parses a JSON string into a JavaScript object. | | toBoolean | Converts various input types (boolean, string, number) into a boolean value. | | toGuidFormat | Converts a UID or GUID string into the standard lowercase GUID format. | | toUidFormat | Converts a GUID or UID string into the standard 32-character uppercase UID format. |

Environment & Variables

| Function | Description | |---|---| | getVars | Retrieves environment variables, optionally filtering and sorting. |

Unique ID & Code Generation

| Function | Description | |---|---| | newCode | Generates a random code string of a specified length using given characters. | | newGuid | Generates a new version 4 UUID (GUID). | | newUid | Generates a new 32-character uppercase alphanumeric UID string. |

Testing

Run the test suite to ensure everything works correctly:

# Run all tests
npm test

# Run linting
npm run lint

# Fix linting issues automatically
npm run lint:fix

Migration from Lodash/Underscore

If you're migrating from lodash or underscore, here are some common equivalents:

// Lodash/Underscore → cleaner-node
_.isString(value)     → _.isValidString(value)
_.isArray(value)      → _.isValidArray(value)  
_.isEmpty(array)      → _.isEmptyArray(array)
_.first(array)        → _.getFirst(array)
_.last(array)         → _.getLast(array)
_.uniq(array)         → _.unique(array)
_.clone(object)       → _.copyObject(object)
_.isEqual(a, b)       → _.isMatch(a, b)

// Plus many additional utilities not found in lodash:
_.isEmail(email)      → Email validation
_.isGuidFormat(guid)  → GUID format checking
_.cleanString(str)    → String cleaning
_.newGuid()           → GUID generation
_.readFile(path)      → Synchronous file reading

Performance Notes

• Most string and validation functions are highly optimized for performance
• File operations are synchronous by design for simplicity
• HTTP functions use native fetch API where available
• Object operations use JSON serialization for deep copying (suitable for most use cases)

API Stability

This package follows Semantic Versioning. The API is stable and backward-compatible changes are guaranteed within major versions.

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Run linting (npm run lint:fix)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Development Setup

git clone https://github.com/FredLackey/cleaner-node.git
cd cleaner-node
npm install
npm test

Changelog

See UPDATES.md for a detailed changelog of all versions.

License

Apache-2.0 - see LICENSE file for details.

Contact

If you have any questions, comments, or concerns, please feel free to reach out to me at...

Fred Lackey
[email protected]
http://fredlackey.com

Links:

• GitHub Repository
• NPM Package
• Issue Tracker
• Full Documentation