Qumra Utils

A collection of utility tools and helpers for Qumra platform developers. Simple and efficient utilities to enhance development experience both within Qumra ecosystem and for external developers.

Installation

npm install qumra-utils

Available Functions

Date and Time Utilities

import { 
  formatDate,
  getTimeAgo,
  addDays,
  toUTC,
  isValidDate
} from 'qumra-utils';

// Format a date with custom format
formatDate(date: Date | string | number, format?: string): string
// Example: formatDate(new Date(), 'DD-MM-YYYY HH:mm:ss')

// Get relative time (e.g., "2 hours ago")
getTimeAgo(date: Date | string | number, locale?: 'en' | 'ar'): string
// Example: getTimeAgo(new Date(), 'ar')

// Add days to a date
addDays(date: Date | string | number, days: number): Date | null
// Example: addDays(new Date(), 7)

// Convert date to UTC
toUTC(date: Date | string | number): Date | null
// Example: toUTC(new Date())

// Check if a value is a valid date
isValidDate(date: any): boolean
// Example: isValidDate('2024-03-20')

Phone Number Utilities

import { 
  isValidPhoneNumber,
  formatPhoneNumber
} from 'qumra-utils';

// Validate phone number
isValidPhoneNumber(phoneNumber: string, countryCode?: string): boolean
// Example: isValidPhoneNumber('+201234567890', 'EG')

// Format phone number to international format
formatPhoneNumber(phoneNumber: string, countryCode?: string): string | null
// Example: formatPhoneNumber('01234567890', 'EG')

Email Utilities

import { isValidEmail } from 'qumra-utils';

// Validate email address
isValidEmail(email: string): boolean
// Example: isValidEmail('[email protected]')

String Utilities

import { slugify } from 'qumra-utils';

// Convert text to URL-friendly slug
slugify(text: string): string
// Example: slugify('Hello World!') // returns 'hello-world'

Object Utilities

import { 
  deepClone,
  deepMerge,
  groupBy
} from 'qumra-utils';

// Create a deep copy of an object
deepClone<T>(value: T): T
// Example: deepClone({ nested: { value: 1 } })

// Deep merge two objects
deepMerge<T>(target: T, source: Partial<T>): T
// Example: deepMerge({ a: 1 }, { b: 2 })

// Group array items by key
groupBy<T>(array: T[], key: keyof T): Record<string, T[]>
// Example: groupBy(users, 'role')

MongoDB Utilities

import { 
  isValidMongoId,
  isValidId
} from 'qumra-utils';

// Validate MongoDB ObjectId
isValidMongoId(id: string): boolean
// Example: isValidMongoId('507f1f77bcf86cd799439011')

// Validate ID (MongoDB ObjectId or numeric ID)
isValidId(id: string): boolean
// Example: isValidId('507f1f77bcf86cd799439011') // MongoDB ID
// Example: isValidId('12345') // Numeric ID

Domain Utilities

import { 
  parseDomain,
  getSubdomain
} from 'qumra-utils';

// Parse domain information
parseDomain(url: string): TldtsResult
// Example: parseDomain('https://sub.example.com')

// Get subdomain from URL
getSubdomain(url: string): string | null
// Example: getSubdomain('https://sub.example.com')

Network Utilities

import { getLocalIP } from 'qumra-utils';

// Get the local IP address of the current device
getLocalIP(): string | null
// Example: getLocalIP() // returns "192.168.1.100"

Usage Examples

import { 
  formatDate,
  isValidPhoneNumber,
  slugify,
  deepClone,
  getLocalIP
} from 'qumra-utils';

// Format date
const formattedDate = formatDate(new Date(), 'DD-MM-YYYY');
console.log(formattedDate); // "20-03-2024"

// Validate phone number
const isValid = isValidPhoneNumber('+201234567890', 'EG');
console.log(isValid); // true

// Create URL slug
const slug = slugify('Hello World!');
console.log(slug); // "hello-world"

// Deep clone object
const original = { nested: { value: 1 } };
const cloned = deepClone(original);

// Get local IP address
const localIP = getLocalIP();
console.log(localIP); // "192.168.1.100"

License

ISC