A collection of essential helper functions for JavaScript and TypeScript projects.
npm install essential-helperbash
npm install essential-helper
`
Usage
`typescript
import {
toCamelCase,
encodeToBase64,
delay,
hashPassword,
createResponse,
paginate,
logger
} from 'essential-helper';
// String manipulation
const result = toCamelCase('hello-world'); // 'helloWorld'
// Encoding
const encoded = encodeToBase64('Hello World'); // 'SGVsbG8gV29ybGQ='
// Async operations
await delay(1000); // Wait for 1 second
// Password hashing
const hashedPassword = await hashPassword('myPassword123!');
// API Response
const response = createResponse({ id: 1, name: 'John' }, 'User found', 200);
// Pagination
const paginatedData = paginate([1,2,3,4,5], 1, 2);
// Logging
logger('Application started', 'info');
`
API Reference
$3
#### toCamelCase(str: string): string
Converts a string to camelCase format.
`typescript
import { toCamelCase } from 'essential-helper';
toCamelCase('hello-world'); // 'helloWorld'
toCamelCase('hello_world'); // 'helloWorld'
toCamelCase('Hello World'); // 'helloWorld'
toCamelCase('HELLO-WORLD'); // 'helloWorld'
`
#### toKebabCase(str: string): string
Converts a string to kebab-case format.
`typescript
import { toKebabCase } from 'essential-helper';
toKebabCase('helloWorld'); // 'hello-world'
toKebabCase('hello_world'); // 'hello-world'
toKebabCase('Hello World'); // 'hello-world'
toKebabCase('HelloWorld'); // 'hello-world'
`
#### toSnakeCase(str: string): string
Converts a string to snake_case format.
`typescript
import { toSnakeCase } from 'essential-helper';
toSnakeCase('helloWorld'); // 'hello_world'
toSnakeCase('hello-world'); // 'hello_world'
toSnakeCase('Hello World'); // 'hello_world'
toSnakeCase('HelloWorld'); // 'hello_world'
`
#### toPascalCase(str: string): string
Converts a string to PascalCase format.
`typescript
import { toPascalCase } from 'essential-helper';
toPascalCase('hello-world'); // 'HelloWorld'
toPascalCase('hello_world'); // 'HelloWorld'
toPascalCase('hello world'); // 'HelloWorld'
toPascalCase('helloWorld'); // 'HelloWorld'
`
#### capitalizeWords(str: string): string
Capitalizes the first letter of each word in a string.
`typescript
import { capitalizeWords } from 'essential-helper';
capitalizeWords('hello world'); // 'Hello World'
capitalizeWords('hello-world'); // 'Hello World'
capitalizeWords('hello_world'); // 'Hello World'
`
#### reverseString(str: string): string
Reverses the characters in a string.
`typescript
import { reverseString } from 'essential-helper';
reverseString('hello'); // 'olleh'
reverseString('hello-world'); // 'dlrow olleh'
reverseString('hello_world'); // 'dlrow olleh'
`
$3
#### encodeToBase64(str: string): string
Encodes a string to Base64 format.
`typescript
import { encodeToBase64 } from 'essential-helper';
encodeToBase64('Hello World'); // 'SGVsbG8gV29ybGQ='
encodeToBase64('test@example.com'); // 'dGVzdEBleGFtcGxlLmNvbQ=='
`
#### decodeFromBase64(str: string): string
Decodes a Base64-encoded string.
`typescript
import { decodeFromBase64 } from 'essential-helper';
decodeFromBase64('SGVsbG8gV29ybGQ='); // 'Hello World'
decodeFromBase64('dGVzdEBleGFtcGxlLmNvbQ=='); // 'test@example.com'
`
#### encodeToUrl(str: string): string
Encodes a string to URL-encoded format.
`typescript
import { encodeToUrl } from 'essential-helper';
encodeToUrl('hello world'); // 'hello%20world'
encodeToUrl('test@example.com'); // 'test%40example.com'
encodeToUrl('café'); // 'caf%C3%A9'
`
#### decodeFromUrl(str: string): string
Decodes a URL-encoded string.
`typescript
import { decodeFromUrl } from 'essential-helper';
decodeFromUrl('hello%20world'); // 'hello world'
decodeFromUrl('test%40example.com'); // 'test@example.com'
decodeFromUrl('caf%C3%A9'); // 'café'
`
$3
#### delay(ms: number): Promise
Delays the execution for a specified number of milliseconds.
`typescript
import { delay } from 'essential-helper';
// Wait for 1 second
await delay(1000);
// Wait for 500 milliseconds
await delay(500);
`
#### retry
Retries an asynchronous function a specified number of times with an optional delay between attempts.
`typescript
import { retry } from 'essential-helper';
// Retry a function up to 3 times with 1 second delay
const result = await retry(async () => {
const response = await fetch('/api/data');
if (!response.ok) throw new Error('Request failed');
return response.json();
}, 3, 1000);
// Retry without delay
const result2 = await retry(someAsyncFunction, 5, 0);
`
#### tryWrap
Wraps a promise and returns a tuple containing either the resolved value or an error.
`typescript
import { tryWrap } from 'essential-helper';
const [error, data] = await tryWrap(fetch('/api/data'));
if (error) {
console.error('Request failed:', error.message);
} else {
console.log('Request succeeded:', data);
}
`
$3
#### hashPassword(password: string): Promise
Hashes a plain text password using bcrypt.
`typescript
import { hashPassword } from 'essential-helper';
const hashedPassword = await hashPassword('mySecurePassword123!');
console.log(hashedPassword); // $2b$10$...
`
#### comparePassword(password: string, hashedPassword: string): Promise
Compares a plain text password with a hashed password to check if they match.
`typescript
import { comparePassword } from 'essential-helper';
const isValid = await comparePassword('mySecurePassword123!', hashedPassword);
console.log(isValid); // true or false
`
#### generateRandomPassword(length?: number): Promise
Generates a random password of specified length (default is 12).
`typescript
import { generateRandomPassword } from 'essential-helper';
const password = await generateRandomPassword(); // 12 characters
const longPassword = await generateRandomPassword(20); // 20 characters
`
#### validatePasswordStrength(password: string): Promise
Validates the strength of a password based on criteria such as length, uppercase, lowercase, number, and special character.
`typescript
import { validatePasswordStrength } from 'essential-helper';
const isStrong = await validatePasswordStrength('MyStr0ng!Pass');
console.log(isStrong); // true
const isWeak = await validatePasswordStrength('password');
console.log(isWeak); // false
`
$3
#### createResponse
Creates a standardized response object for APIs.
`typescript
import { createResponse } from 'essential-helper';
// Default response
const response = createResponse({ id: 1, name: 'John' });
// { status: 200, message: 'OK', data: { id: 1, name: 'John' } }
// Custom response
const errorResponse = createResponse(null, 'User not found', 404);
// { status: 404, message: 'User not found', data: null }
`
#### requiredEnv(varName: string): string
Retrieves the value of an environment variable, throwing an error if it is not set.
`typescript
import { requiredEnv } from 'essential-helper';
// Will throw error if DATABASE_URL is not set
const databaseUrl = requiredEnv('DATABASE_URL');
// Usage in configuration
const config = {
port: process.env.PORT || 3000,
databaseUrl: requiredEnv('DATABASE_URL'), // Required
apiKey: requiredEnv('API_KEY') // Required
};
`
#### paginate
Paginates an array of items with metadata.
`typescript
import { paginate } from 'essential-helper';
const items = Array.from({ length: 100 }, (_, i) => ({ id: i + 1 }));
// Default pagination (page 1, 20 items per page)
const result = paginate(items);
console.log(result);
// {
// data: [{ id: 1 }, { id: 2 }, ...], // First 20 items
// meta: {
// total: 100,
// page: 1,
// perPage: 20,
// totalPages: 5
// }
// }
// Custom pagination
const customResult = paginate(items, 2, 10);
// Page 2 with 10 items per page
`
#### logger(message: string, level?: 'info' | 'warn' | 'error')
Logs a message with a timestamp and specified log level using colored output.
`typescript
import { logger } from 'essential-helper';
logger('Application started'); // Default: info level
logger('Warning: API rate limit approaching', 'warn');
logger('Database connection failed', 'error');
`
#### singleInstance
Ensures a function is only executed once and returns the same instance on subsequent calls (Singleton pattern).
`typescript
import { singleInstance } from 'essential-helper';
class DatabaseConnection {
constructor() {
console.log('Creating database connection...');
}
}
const getDbConnection = singleInstance(() => new DatabaseConnection());
const db1 = getDbConnection(); // Creates new instance
const db2 = getDbConnection(); // Returns same instance
console.log(db1 === db2); // true
`
#### properDate(date: Date, locale?: string, options?: Intl.DateTimeFormatOptions): string
Formats a Date object into a readable string based on locale and options.
`typescript
import { properDate } from 'essential-helper';
const date = new Date('2024-01-15T10:30:00Z');
// Default formatting (en-US)
console.log(properDate(date)); // "1/15/2024"
// Custom locale
console.log(properDate(date, 'de-DE')); // "15.1.2024"
// Custom options
console.log(properDate(date, 'en-US', {
year: 'numeric',
month: 'long',
day: 'numeric',
hour: '2-digit',
minute: '2-digit'
})); // "January 15, 2024 at 10:30 AM"
`
Examples
$3
`typescript
import { createResponse, logger } from 'essential-helper';
async function getUserById(id: string) {
try {
logger(Fetching user with ID: ${id}, 'info');
const user = await database.findUser(id);
if (!user) {
return createResponse(null, 'User not found', 404);
}
return createResponse(user, 'User retrieved successfully', 200);
} catch (error) {
logger(Error fetching user: ${error.message}, 'error');
return createResponse(null, 'Internal server error', 500);
}
}
`
$3
`typescript
import { requiredEnv, logger } from 'essential-helper';
function loadConfiguration() {
try {
const config = {
port: process.env.PORT || 3000,
databaseUrl: requiredEnv('DATABASE_URL'),
jwtSecret: requiredEnv('JWT_SECRET'),
apiKey: requiredEnv('API_KEY')
};
logger('Configuration loaded successfully', 'info');
return config;
} catch (error) {
logger(Configuration error: ${error.message}, 'error');
process.exit(1);
}
}
`
$3
`typescript
import { paginate, tryWrap, logger } from 'essential-helper';
async function getUsers(page = 1, limit = 10) {
const [error, users] = await tryWrap(database.getAllUsers());
if (error) {
logger(Database error: ${error.message}, 'error');
return { error: 'Failed to fetch users' };
}
const paginatedData = paginate(users, page, limit);
logger(Retrieved ${paginatedData.data.length} users (page ${page}), 'info');
return paginatedData;
}
`
$3
`typescript
import { singleInstance, logger, requiredEnv } from 'essential-helper';
class DatabaseManager {
private connection: any;
constructor() {
const dbUrl = requiredEnv('DATABASE_URL');
logger('Initializing database connection...', 'info');
this.connection = this.createConnection(dbUrl);
}
private createConnection(url: string) {
// Database connection logic
return { url, connected: true };
}
}
// Ensure only one database instance
const getDatabase = singleInstance(() => new DatabaseManager());
// Usage across your application
const db1 = getDatabase(); // Creates instance
const db2 = getDatabase(); // Returns same instance
`
$3
`typescript
import { toCamelCase, toKebabCase, toSnakeCase, toPascalCase } from 'essential-helper';
const originalString = 'user-profile-settings';
const camelCase = toCamelCase(originalString); // 'userProfileSettings'
const kebabCase = toKebabCase(camelCase); // 'user-profile-settings'
const snakeCase = toSnakeCase(originalString); // 'user_profile_settings'
const pascalCase = toPascalCase(originalString); // 'UserProfileSettings'
`
$3
`typescript
import { encodeToBase64, encodeToUrl, decodeFromBase64, decodeFromUrl } from 'essential-helper';
const sensitiveData = 'user:password@domain.com';
// Encode for transmission
const base64Encoded = encodeToBase64(sensitiveData);
const urlSafe = encodeToUrl(base64Encoded);
// Decode received data
const base64Data = decodeFromUrl(urlSafe);
const originalData = decodeFromBase64(base64Data);
console.log(originalData === sensitiveData); // true
`
$3
`typescript
import { retry, delay, tryWrap } from 'essential-helper';
async function fetchWithRetry() {
return retry(async () => {
const response = await fetch('/api/unreliable-endpoint');
if (!response.ok) {
throw new Error(HTTP ${response.status}: ${response.statusText});
}
return response.json();
}, 3, 1000); // 3 attempts with 1 second delay
}
async function safeAsyncOperation() {
const [error, result] = await tryWrap(fetchWithRetry());
if (error) {
logger(Operation failed: ${error.message}, 'error');
return null;
}
return result;
}
`
$3
`typescript
import { hashPassword, comparePassword, generateRandomPassword, validatePasswordStrength } from 'essential-helper';
async function userRegistration(plainTextPassword: string) {
// Validate password strength
const isStrong = await validatePasswordStrength(plainTextPassword);
if (!isStrong) {
throw new Error('Password does not meet strength requirements');
}
// Hash the password for storage
const hashedPassword = await hashPassword(plainTextPassword);
// Store hashedPassword in database
return { hashedPassword };
}
async function userLogin(plainTextPassword: string, storedHashedPassword: string) {
const isValid = await comparePassword(plainTextPassword, storedHashedPassword);
return isValid;
}
async function generateSecurePassword() {
const password = await generateRandomPassword(16);
const isStrong = await validatePasswordStrength(password);
console.log(Generated password: ${password}, Is strong: ${isStrong});
}
`
TypeScript Support
This package includes TypeScript declarations out of the box. No additional @types packages are required.
`typescript
import type { } from 'essential-helper'; // Types are included
// All functions have full type safety
const result: string = toCamelCase('hello-world');
const hashedPassword: Promise = hashPassword('myPassword');
const response = createResponse(userData, 'Success', 200);
`
Requirements
- Node.js 14 or higher
- TypeScript 4.0 or higher (if using TypeScript)
Development
$3
`bash
git clone https://github.com/DhakalYukesh/essential-helper.git
cd essential-helper
npm install
`
$3
`bash
npm run build # Build the project
npm run test # Run tests
npm run test:watch # Run tests in watch mode
npm run test:coverage # Run tests with coverage
npm run lint # Lint the code
npm run format # Format the code
`
$3
The project uses Jest for testing. All functions are thoroughly tested with comprehensive test coverage.
`bash
npm test
`
Contributing
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request
License
MIT © Yukesh Dhakal
Repository
- GitHub
- Issues
Changelog
$3
- Updated picocolors dependency to version 1.1.1
- Minor bug fixes and improvements
- All existing functionality remains unchanged
$3
- NEW: Core utilities (createResponse, requiredEnv, paginate, logger, singleInstance, properDate)
- NEW: Enhanced async utilities (tryWrap function added)
- Async utilities (delay, retry)
- Password management functions (hashPassword, comparePassword, generateRandomPassword, validatePasswordStrength)
- String manipulation functions (camelCase, kebab-case, snake_case, PascalCase)
- Text transformation utilities (capitalizeWords, reverseString)
- Base64 encoding/decoding
- URL encoding/decoding
- Full TypeScript support
- Comprehensive test coverage
$3
- NEW: Async utilities (delay, retry`)