utilitify-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utilitify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# Utilitify
+
+> Comprehensive validation & utility SDK for JavaScript/TypeScript applications
+
+[![npm version](https://img.shields.io/npm/v/utilitify-core.svg)](https://www.npmjs.com/package/utilitify-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
+
+## Features
+
+- **Security** - Password strength, hashing, secure tokens
+- **Validators** - Email, phone, username, URL, credit card, IBAN, VAT, IP
+- **Country Data** - Countries, timezones, currencies, dialing codes
+- **String Utils** - Case conversion, slugs, masking, truncation
+- **Date Utils** - Age calculation, formatting, validation
+- **Transform** - Deep merge, flatten, sanitization
+- **Form Validation** - Field validators, conditional rules
+- **Tree-Shakable** - Import only what you need
+- **Zero Dependencies** - Lightweight core
+- **TypeScript Native** - Full type safety
+
+## Installation
+
+```bash
+npm install utilitify-core
+```
+
+Optional (for bcrypt hashing):
+```bash
+npm install bcryptjs
+```
+
+## Quick Start
+
+```typescript
+import { validateEmail } from 'utilitify-core/validators';
+import { checkPasswordStrength } from 'utilitify-core/security';
+import { slugify } from 'utilitify-core/string';
+
+// Email validation
+const email = validateEmail('user@example.com');
+console.log(email.isValid); // true
+
+// Password strength
+const password = checkPasswordStrength('MyP@ssw0rd123');
+console.log(password.score); // 0-4
+console.log(password.crackTime); // "Centuries"
+
+// String utilities
+const slug = slugify('Hello World!'); // "hello-world"
+```
+
+## API Reference
+
+### Validators (`utilitify-core/validators`)
+
+```typescript
+// Email
+validateEmail(email, options?)
+isValidEmail(email)
+isDisposableEmail(email)
+normalizeEmail(email)
+
+// Phone
+validatePhone(phone, country?)
+formatPhone(phone, country?)
+
+// Username
+validateUsername(username, options?)
+suggestUsernames(base)
+
+// URL
+validateUrl(url, options?)
+isDangerousUrl(url)
+
+// Credit Card
+validateCreditCard(number)
+detectCardType(number)
+
+// Financial
+validateIBAN(iban)
+validateVAT(vat, country)
+
+// IP Address
+validateIp(ip, options?)
+isPrivateIp(ip)
+```
+
+### Security (`utilitify-core/security`)
+
+```typescript
+// Password
+checkPasswordStrength(password, options?)
+isStrongPassword(password, minScore?)
+getPasswordFeedback(password)
+
+// Hashing
+hashSHA256(data)
+hashSHA512(data)
+hashBcrypt(password, rounds?)
+verifyBcrypt(password, hash)
+hmacSHA256(data, key)
+
+// Tokens
+generateUUID()
+generateUUIDv7()
+generateToken(length)
+generateSecureToken(length)
+generateNanoId(length?)
+```
+
+### String (`utilitify-core/string`)
+
+```typescript
+// Case conversion
+toCamelCase(str)
+toPascalCase(str)
+toSnakeCase(str)
+toKebabCase(str)
+toTitleCase(str)
+
+// Slugs
+slugify(str, options?)
+uniqueSlug(str, existing)
+
+// Masking
+maskEmail(email)
+maskPhone(phone)
+maskCreditCard(number)
+
+// Random
+generatePassword(options?)
+generateOTP(length?)
+
+// Truncation
+truncate(str, length, options?)
+truncateWords(str, words)
+```
+
+### Country (`utilitify-core/country`)
+
+```typescript
+// Country lookup
+getCountry(code)
+getAllCountries()
+searchCountries(query)
+
+// Timezone
+getTimezonesByCountry(country)
+getCurrentTimeInCountry(country)
+
+// Currency
+getCurrencyByCountry(country)
+formatCurrency(amount, currency)
+
+// Flags & Dialing
+getFlagEmoji(country)
+getDialingCode(country)
+```
+
+### Date (`utilitify-core/date`)
+
+```typescript
+// Age
+calculateAge(birthDate)
+isAdult(birthDate, minAge?)
+getAgeBracket(age)
+
+// Formatting
+formatRelativeTime(date)
+formatDate(date, format)
+
+// Validation
+isValidDate(date)
+isInPast(date)
+isWeekend(date)
+
+// Time difference
+getTimeDiff(date1, date2)
+addTime(date, amount, unit)
+```
+
+### Transform (`utilitify-core/transform`)
+
+```typescript
+// Objects
+deepMerge(obj1, obj2)
+cloneDeep(obj)
+flattenObject(obj)
+pick(obj, keys)
+omit(obj, keys)
+
+// Sanitization
+sanitizeString(str)
+stripHtml(html)
+escapeHtml(str)
+```
+
+### Form (`utilitify-core/form`)
+
+```typescript
+// Validators
+required(value)
+minLength(value, min)
+maxLength(value, max)
+matchesPattern(value, pattern)
+
+// Conditional
+requiredIf(value, condition)
+mustMatch(value, other)
+```
+
+### Schema (`utilitify-core/schema`)
+
+```typescript
+import { z } from 'utilitify-core/schema';
+
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().min(18).max(120),
+  name: z.string().min(2)
+});
+
+const result = schema.safeParse(data);
+if (result.success) {
+  console.log(result.data);
+}
+```
+
+## Usage Examples
+
+### Form Validation
+
+```typescript
+import { validateEmail, validatePhone, checkPasswordStrength } from 'utilitify-core';
+
+function validateForm(data) {
+  const errors = {};
+
+  const email = validateEmail(data.email, { checkDisposable: true });
+  if (!email.isValid) {
+    errors.email = email.errors[0].message;
+  }
+
+  const phone = validatePhone(data.phone, 'US');
+  if (!phone.isValid) {
+    errors.phone = 'Invalid phone number';
+  }
+
+  const password = checkPasswordStrength(data.password);
+  if (password.score < 3) {
+    errors.password = password.suggestions.join(', ');
+  }
+
+  return { isValid: Object.keys(errors).length === 0, errors };
+}
+```
+
+### Secure Token Generation
+
+```typescript
+import { generateUUID, generateSecureToken } from 'utilitify-core/security';
+
+const userId = generateUUID();
+const apiKey = generateSecureToken(32);
+const sessionToken = generateSecureToken(64);
+```
+
+### International Phone Formatting
+
+```typescript
+import { formatPhone, getDialingCode } from 'utilitify-core/country';
+
+const formatted = formatPhone('2025551234', 'US');
+// "+1 (202) 555-1234"
+
+const code = getDialingCode('GB');
+// "+44"
+```
+
+### String Manipulation
+
+```typescript
+import { slugify, maskEmail, truncate } from 'utilitify-core/string';
+
+slugify('Hello World! 123'); // "hello-world-123"
+maskEmail('user@example.com'); // "u***@example.com"
+truncate('Long text...', 10); // "Long te..."
+```
+
+## Tree-Shaking
+
+Import from specific paths to reduce bundle size:
+
+```typescript
+// Recommended - Only imports what you need
+import { validateEmail } from 'utilitify-core/validators';
+import { generateUUID } from 'utilitify-core/security';
+
+// Avoid - Imports entire package
+import { validateEmail, generateUUID } from 'utilitify-core';
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions:
+
+```typescript
+import type { 
+  EmailValidationResult, 
+  PasswordStrength,
+  Country 
+} from 'utilitify-core';
+
+const result: EmailValidationResult = validateEmail('test@example.com');
+```
+
+## Browser & Node.js Support
+
+- **Node.js**: >= 18.0.0
+- **Browsers**: All modern browsers (ES2022+)
+- **TypeScript**: >= 5.0
+
+## Bundle Size
+
+- Core validators: ~5 KB (gzipped)
+- Full package: ~10 KB (gzipped)
+- Tree-shakable modules
+
+## License
+
+MIT © [Fahad](https://github.com/muhammadfahaddev)
+
+## Links
+
+- [GitHub](https://github.com/muhammadfahaddev/utilitify-core)
+- [Issues](https://github.com/muhammadfahaddev/utilitify-core/issues)
+- [npm](https://www.npmjs.com/package/utilitify-core)

package/dist/async.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+var chunkPB6SKSJN_cjs = require('./chunk-PB6SKSJN.cjs');
+require('./chunk-CZLDE2OZ.cjs');
+
+
+
+Object.defineProperty(exports, "composeValidators", {
+  enumerable: true,
+  get: function () { return chunkPB6SKSJN_cjs.composeValidators; }
+});
+Object.defineProperty(exports, "createDebouncedValidator", {
+  enumerable: true,
+  get: function () { return chunkPB6SKSJN_cjs.createDebouncedValidator; }
+});
+Object.defineProperty(exports, "validateAllAsync", {
+  enumerable: true,
+  get: function () { return chunkPB6SKSJN_cjs.validateAllAsync; }
+});
+Object.defineProperty(exports, "validateAsync", {
+  enumerable: true,
+  get: function () { return chunkPB6SKSJN_cjs.validateAsync; }
+});
+//# sourceMappingURL=async.cjs.map
+//# sourceMappingURL=async.cjs.map

package/dist/async.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"async.cjs"}

package/dist/async.d.cts

@@ -0,0 +1,104 @@
+import { I as IValidationError } from './common-CBDYNJeh.cjs';
+
+/**
+ * Async validation module for Utilitify
+ * Provides async validators for scenarios requiring external API calls
+ *
+ * @packageDocumentation
+ * @since 1.0.0
+ */
+
+/**
+ * Async validation result
+ */
+interface AsyncValidationResult {
+    isValid: boolean;
+    errors: IValidationError[];
+    /** Time taken for validation in milliseconds */
+    duration?: number;
+}
+/**
+ * Async validator function type
+ */
+type AsyncValidator<T> = (value: T) => Promise<AsyncValidationResult>;
+/**
+ * Async validation options
+ */
+interface AsyncValidationOptions {
+    /** Timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Whether to abort on first error (default: false) */
+    abortEarly?: boolean;
+    /** Custom error messages */
+    messages?: Record<string, string>;
+}
+/**
+ * Run async validation with timeout
+ *
+ * @param value - Value to validate
+ * @param validator - Async validator function
+ * @param options - Validation options
+ * @returns Validation result
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await validateAsync(email, async (email) => {
+ *   const exists = await checkEmailExists(email);
+ *   return {
+ *     isValid: !exists,
+ *     errors: exists ? [{ field: 'email', code: 'EXISTS', message: 'Email already registered' }] : []
+ *   };
+ * });
+ * ```
+ */
+declare function validateAsync<T>(value: T, validator: AsyncValidator<T>, options?: AsyncValidationOptions): Promise<AsyncValidationResult>;
+/**
+ * Run multiple async validators in parallel
+ *
+ * @param validators - Array of validator configs
+ * @param options - Validation options
+ * @returns Combined validation result
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await validateAllAsync([
+ *   { value: email, validator: emailExistsCheck, field: 'email' },
+ *   { value: username, validator: usernameAvailableCheck, field: 'username' }
+ * ]);
+ * ```
+ */
+declare function validateAllAsync<T>(validators: Array<{
+    value: T;
+    validator: AsyncValidator<T>;
+    field: string;
+}>, options?: AsyncValidationOptions): Promise<AsyncValidationResult>;
+/**
+ * Create a debounced async validator
+ * Useful for real-time validation in forms
+ *
+ * @param validator - Async validator function
+ * @param delay - Debounce delay in milliseconds
+ * @returns Debounced validator
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const debouncedEmailCheck = createDebouncedValidator(
+ *   async (email) => ({ isValid: !(await checkExists(email)), errors: [] }),
+ *   300
+ * );
+ * ```
+ */
+declare function createDebouncedValidator<T>(validator: AsyncValidator<T>, delay?: number): (value: T) => Promise<AsyncValidationResult>;
+/**
+ * Compose multiple validators into one
+ *
+ * @param validators - Validators to compose
+ * @returns Composed validator
+ * @since 1.0.0
+ */
+declare function composeValidators<T>(...validators: AsyncValidator<T>[]): AsyncValidator<T>;
+
+export { type AsyncValidationOptions, type AsyncValidationResult, type AsyncValidator, composeValidators, createDebouncedValidator, validateAllAsync, validateAsync };

package/dist/async.d.ts

@@ -0,0 +1,104 @@
+import { I as IValidationError } from './common-CBDYNJeh.js';
+
+/**
+ * Async validation module for Utilitify
+ * Provides async validators for scenarios requiring external API calls
+ *
+ * @packageDocumentation
+ * @since 1.0.0
+ */
+
+/**
+ * Async validation result
+ */
+interface AsyncValidationResult {
+    isValid: boolean;
+    errors: IValidationError[];
+    /** Time taken for validation in milliseconds */
+    duration?: number;
+}
+/**
+ * Async validator function type
+ */
+type AsyncValidator<T> = (value: T) => Promise<AsyncValidationResult>;
+/**
+ * Async validation options
+ */
+interface AsyncValidationOptions {
+    /** Timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Whether to abort on first error (default: false) */
+    abortEarly?: boolean;
+    /** Custom error messages */
+    messages?: Record<string, string>;
+}
+/**
+ * Run async validation with timeout
+ *
+ * @param value - Value to validate
+ * @param validator - Async validator function
+ * @param options - Validation options
+ * @returns Validation result
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await validateAsync(email, async (email) => {
+ *   const exists = await checkEmailExists(email);
+ *   return {
+ *     isValid: !exists,
+ *     errors: exists ? [{ field: 'email', code: 'EXISTS', message: 'Email already registered' }] : []
+ *   };
+ * });
+ * ```
+ */
+declare function validateAsync<T>(value: T, validator: AsyncValidator<T>, options?: AsyncValidationOptions): Promise<AsyncValidationResult>;
+/**
+ * Run multiple async validators in parallel
+ *
+ * @param validators - Array of validator configs
+ * @param options - Validation options
+ * @returns Combined validation result
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const result = await validateAllAsync([
+ *   { value: email, validator: emailExistsCheck, field: 'email' },
+ *   { value: username, validator: usernameAvailableCheck, field: 'username' }
+ * ]);
+ * ```
+ */
+declare function validateAllAsync<T>(validators: Array<{
+    value: T;
+    validator: AsyncValidator<T>;
+    field: string;
+}>, options?: AsyncValidationOptions): Promise<AsyncValidationResult>;
+/**
+ * Create a debounced async validator
+ * Useful for real-time validation in forms
+ *
+ * @param validator - Async validator function
+ * @param delay - Debounce delay in milliseconds
+ * @returns Debounced validator
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const debouncedEmailCheck = createDebouncedValidator(
+ *   async (email) => ({ isValid: !(await checkExists(email)), errors: [] }),
+ *   300
+ * );
+ * ```
+ */
+declare function createDebouncedValidator<T>(validator: AsyncValidator<T>, delay?: number): (value: T) => Promise<AsyncValidationResult>;
+/**
+ * Compose multiple validators into one
+ *
+ * @param validators - Validators to compose
+ * @returns Composed validator
+ * @since 1.0.0
+ */
+declare function composeValidators<T>(...validators: AsyncValidator<T>[]): AsyncValidator<T>;
+
+export { type AsyncValidationOptions, type AsyncValidationResult, type AsyncValidator, composeValidators, createDebouncedValidator, validateAllAsync, validateAsync };

package/dist/async.js

@@ -0,0 +1,4 @@
+export { composeValidators, createDebouncedValidator, validateAllAsync, validateAsync } from './chunk-P3NUK46X.js';
+import './chunk-4CV4JOE5.js';
+//# sourceMappingURL=async.js.map
+//# sourceMappingURL=async.js.map

package/dist/async.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"async.js"}