@zairakai/js-utils 1.0.0

package/src/datetime.ts

@@ -0,0 +1,103 @@
+/**
+ * Date and time utilities using Day.js
+ */
+
+import dayjsModule, { ConfigType, Dayjs } from 'dayjs'
+import isBetween from 'dayjs/plugin/isBetween'
+import isSameOrAfter from 'dayjs/plugin/isSameOrAfter'
+import isSameOrBefore from 'dayjs/plugin/isSameOrBefore'
+import relativeTime from 'dayjs/plugin/relativeTime'
+import utc from 'dayjs/plugin/utc'
+
+// Configure dayjs with commonly used plugins
+dayjsModule.extend(isBetween)
+dayjsModule.extend(isSameOrAfter)
+dayjsModule.extend(isSameOrBefore)
+dayjsModule.extend(relativeTime)
+dayjsModule.extend(utc)
+
+/**
+ * Configured Dayjs instance.
+ */
+export const dayjs = dayjsModule
+
+// Utility functions
+/**
+ * Get the current date and time as a Dayjs instance.
+ *
+ * @returns {Dayjs} Current date and time
+ */
+export const now = (): Dayjs => dayjs()
+
+/**
+ * Get today's date at the start of the day.
+ *
+ * @returns {Dayjs} Today's date
+ */
+export const today = (): Dayjs => dayjs().startOf('day')
+
+/**
+ * Get tomorrow's date at the start of the day.
+ *
+ * @returns {Dayjs} Tomorrow's date
+ */
+export const tomorrow = (): Dayjs => dayjs().add(1, 'day').startOf('day')
+
+/**
+ * Get yesterday's date at the start of the day.
+ *
+ * @returns {Dayjs} Yesterday's date
+ */
+export const yesterday = (): Dayjs => dayjs().subtract(1, 'day').startOf('day')
+
+/**
+ * Check if a date is between two other dates.
+ *
+ * @param {ConfigType} date Date to check
+ * @param {ConfigType} start Start date
+ * @param {ConfigType} end End date
+ * @param {dayjsModule.OpUnitType} [unit='day'] Unit of comparison (day, month, year, etc.)
+ * @param {'()' | '[]' | '[)' | '(]'} [inclusivity='[]'] Inclusivity
+ * @returns {boolean} True if the date is between start and end
+ */
+export const isBetweenDates = (
+  date: ConfigType,
+  start: ConfigType,
+  end: ConfigType,
+  unit: dayjsModule.OpUnitType = 'day',
+  inclusivity: '()' | '[]' | '[)' | '(]' = '[]'
+): boolean => {
+  return dayjs(date).isBetween(dayjs(start), dayjs(end), unit, inclusivity)
+}
+
+/**
+ * Format a date to a human-readable relative time.
+ *
+ * @param {ConfigType} date Date to format
+ * @returns {string} Relative time (e.g., "2 hours ago")
+ */
+export const fromNow = (date: ConfigType): string => dayjs(date).fromNow()
+
+/**
+ * Check if a date is today.
+ *
+ * @param {ConfigType} date Date to check
+ * @returns {boolean} True if the date is today
+ */
+export const isToday = (date: ConfigType): boolean => dayjs(date).isSame(dayjs(), 'day')
+
+/**
+ * Check if a date is in the past.
+ *
+ * @param {ConfigType} date Date to check
+ * @returns {boolean} True if the date is in the past
+ */
+export const isPast = (date: ConfigType): boolean => dayjs(date).isBefore(dayjs())
+
+/**
+ * Check if a date is in the future.
+ *
+ * @param {ConfigType} date Date to check
+ * @returns {boolean} True if the date is in the future
+ */
+export const isFuture = (date: ConfigType): boolean => dayjs(date).isAfter(dayjs())

package/src/equals.ts

@@ -0,0 +1,134 @@
+import { GenericRecord } from './types.js'
+
+/**
+ * Deep equality and comparison utilities
+ */
+
+/**
+ * Perform a deep comparison between two values to determine if they are equivalent.
+ *
+ * @param {unknown} a The first value to compare
+ * @param {unknown} b The second value to compare
+ * @returns {boolean} True if the values are equivalent, false otherwise
+ */
+export const isEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) {
+    return true
+  }
+
+  if (a && b && 'object' === typeof a && 'object' === typeof b) {
+    if (a.constructor !== b.constructor) {
+      return false
+    }
+
+    if (Array.isArray(a)) {
+      if (a.length !== (b as unknown[]).length) {
+        return false
+      }
+      for (let i = 0; i < a.length; i++) {
+        if (!isEqual(a[i], (b as unknown[])[i])) {
+          return false
+        }
+      }
+      return true
+    }
+
+    if (a instanceof Map && b instanceof Map) {
+      if (a.size !== b.size) {
+        return false
+      }
+      for (const [key, val] of a) {
+        if (!b.has(key) || !isEqual(val, b.get(key))) {
+          return false
+        }
+      }
+      return true
+    }
+
+    if (a instanceof Set && b instanceof Set) {
+      if (a.size !== b.size) {
+        return false
+      }
+      for (const val of a) {
+        if (!b.has(val)) {
+          return false
+        }
+      }
+      return true
+    }
+
+    if (a.constructor === RegExp) {
+      return (a as RegExp).source === (b as RegExp).source && (a as RegExp).flags === (b as RegExp).flags
+    }
+    if (a.valueOf !== Object.prototype.valueOf) {
+      return a.valueOf() === b.valueOf()
+    }
+    if (a.toString !== Object.prototype.toString) {
+      return a.toString() === b.toString()
+    }
+
+    const keys = Object.keys(a)
+    if (keys.length !== Object.keys(b).length) {
+      return false
+    }
+
+    const bObj = b as GenericRecord
+    const aObj = a as GenericRecord
+
+    for (const key of keys) {
+      if (!Object.prototype.hasOwnProperty.call(bObj, key)) {
+        return false
+      }
+      if (!isEqual(aObj[key], bObj[key])) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  return a !== a && b !== b // Handle NaN
+}
+
+/**
+ * Find the differences between two objects.
+ * Returns an object containing only the keys that differ.
+ *
+ * @param {unknown} original The original object
+ * @param {unknown} current The current object
+ * @returns {GenericRecord} An object containing the differences
+ */
+export const diff = (original: unknown, current: unknown): GenericRecord => {
+  const result: GenericRecord = {}
+
+  if (isEqual(original, current)) {
+    return result
+  }
+
+  if (!original || !current || 'object' !== typeof original || 'object' !== typeof current) {
+    return (current as GenericRecord) || {}
+  }
+
+  const originalObj = original as GenericRecord
+  const currentObj = current as GenericRecord
+
+  const keys = new Set([...Object.keys(originalObj), ...Object.keys(currentObj)])
+
+  for (const key of keys) {
+    if (!isEqual(originalObj[key], currentObj[key])) {
+      if (
+        originalObj[key] &&
+        currentObj[key] &&
+        'object' === typeof originalObj[key] &&
+        'object' === typeof currentObj[key] &&
+        !Array.isArray(originalObj[key])
+      ) {
+        result[key] = diff(originalObj[key], currentObj[key])
+      } else {
+        result[key] = currentObj[key]
+      }
+    }
+  }
+
+  return result
+}

package/src/formatters.ts

@@ -0,0 +1,342 @@
+/**
+ * String manipulation and formatting utilities
+ */
+
+/**
+ * Capitalize the first letter of a string and lowercase the rest.
+ *
+ * @param {unknown} value The value to capitalize
+ * @returns {string} The capitalized string
+ */
+export const capitalize = (value: unknown): string => {
+  if (value == null) {
+    return ''
+  }
+
+  const stringValue = String(value)
+  return stringValue.charAt(0).toUpperCase() + stringValue.slice(1).toLowerCase()
+}
+
+/**
+ * Convert a string into a URL-friendly "slug".
+ *
+ * @param {unknown} text The text to slugify
+ * @returns {string} The slugified string
+ */
+export const slugify = (text: unknown): string => {
+  if (!text) {
+    return ''
+  }
+
+  return text
+    .toString()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^\w-]+/g, '')
+    .replace(/--+/g, '-')
+}
+
+/**
+ * Limit the number of characters in a string.
+ *
+ * @param {unknown} value The string to limit
+ * @param {number} size The maximum number of characters
+ * @returns {string} The limited string
+ */
+export const strLimit = (value: unknown, size: number): string => {
+  if (!value) {
+    return ''
+  }
+
+  const stringValue = String(value)
+  return stringValue.length <= size ? stringValue : `${stringValue.slice(0, size)}…`
+}
+
+/**
+ * Normalize a string by trimming, lowercasing, and removing accents.
+ *
+ * @param {string | null | undefined} value The string to normalize
+ * @returns {string | null | undefined} The normalized string
+ */
+export const normalizeString = (value: string | null | undefined): string | null | undefined => {
+  if (!value) {
+    return value
+  }
+
+  return value
+    .trim()
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+}
+
+// String containment helpers
+/**
+ * Determine if a string contains all of the given values.
+ *
+ * @param {string} haystack The string to search in
+ * @param {string[]} needles The values to search for
+ * @returns {boolean} True if all values are found
+ */
+export const strContainsAll = (haystack: string, needles: string[]): boolean => {
+  if (!haystack || !Array.isArray(needles)) {
+    return false
+  }
+  return needles.every((needle) => haystack.includes(needle))
+}
+
+/**
+ * Determine if a string contains any of the given values.
+ *
+ * @param {string} haystack The string to search in
+ * @param {string[]} needles The values to search for
+ * @returns {boolean} True if any value is found
+ */
+export const strContainsAny = (haystack: string, needles: string[]): boolean => {
+  if (!haystack || !Array.isArray(needles)) {
+    return false
+  }
+  return needles.some((needle) => haystack.includes(needle))
+}
+
+// String padding helpers
+/**
+ * Cap a string with a single instance of a given value.
+ *
+ * @param {string} value The source string
+ * @param {string} cap The value to append if not present
+ * @returns {string} The capped string
+ */
+export const strFinish = (value: string, cap: string): string => {
+  if (!value) {
+    return cap
+  }
+  if (!cap) {
+    return value
+  }
+  return value.endsWith(cap) ? value : value + cap
+}
+
+/**
+ * Begin a string with a single instance of a given value.
+ *
+ * @param {string} value The source string
+ * @param {string} prefix The value to prepend if not present
+ * @returns {string} The prefixed string
+ */
+export const strStart = (value: string, prefix: string): string => {
+  if (!value) {
+    return prefix
+  }
+  if (!prefix) {
+    return value
+  }
+  return value.startsWith(prefix) ? value : prefix + value
+}
+
+/**
+ * Pad both sides of a string with another.
+ *
+ * @param {string} str The source string
+ * @param {number} length The desired length
+ * @param {string} [pad=' '] The value to pad with
+ * @returns {string} The padded string
+ */
+export const strPadBoth = (str: string, length: number, pad = ' '): string => {
+  if (str.length >= length) {
+    return str
+  }
+  const totalPad = length - str.length
+  const leftPad = Math.floor(totalPad / 2)
+  const rightPad = totalPad - leftPad
+  return pad.repeat(leftPad) + str + pad.repeat(rightPad)
+}
+
+/**
+ * Pad the left side of a string with another.
+ *
+ * @param {string} str The source string
+ * @param {number} length The desired length
+ * @param {string} [pad=' '] The value to pad with
+ * @returns {string} The padded string
+ */
+export const strPadLeft = (str: string, length: number, pad = ' '): string => {
+  return str.padStart(length, pad)
+}
+
+/**
+ * Pad the right side of a string with another.
+ *
+ * @param {string} str The source string
+ * @param {number} length The desired length
+ * @param {string} [pad=' '] The value to pad with
+ * @returns {string} The padded string
+ */
+export const strPadRight = (str: string, length: number, pad = ' '): string => {
+  return str.padEnd(length, pad)
+}
+
+// String manipulation helpers
+/**
+ * Reverse the given string.
+ *
+ * @param {string} value The string to reverse
+ * @returns {string} The reversed string
+ */
+export const strReverse = (value: string): string => {
+  return value.split('').reverse().join('')
+}
+
+/**
+ * Remove any occurrence of the given string in the subject.
+ *
+ * @param {string} search The string to remove
+ * @param {string} subject The source string
+ * @param {boolean} [caseSensitive=true] Whether to perform case-sensitive removal
+ * @returns {string} The resulting string
+ */
+export const strRemove = (search: string, subject: string, caseSensitive = true): string => {
+  if (!search || !subject) {
+    return subject
+  }
+  const flags = caseSensitive ? 'g' : 'gi'
+  return subject.replace(new RegExp(search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags), '')
+}
+
+/**
+ * Mask a portion of a string with a repeated character.
+ *
+ * @param {string} str The source string
+ * @param {string} character The character to use for masking
+ * @param {number} index The starting index
+ * @param {number} [length] The number of characters to mask
+ * @returns {string} The masked string
+ */
+export const strMask = (str: string, character: string, index: number, length?: number): string => {
+  if (!str) {
+    return str
+  }
+  const start = Math.max(0, index)
+  const end = length !== undefined ? start + length : str.length
+  return str.substring(0, start) + character.repeat(end - start) + str.substring(end)
+}
+
+// Word helpers
+/**
+ * Count the number of words in a string.
+ *
+ * @param {string} str The string to count words in
+ * @param {string} [characters] Optional characters to treat as word boundaries
+ * @returns {number} The word count
+ */
+export const strWordCount = (str: string, characters?: string): number => {
+  if (!str) {
+    return 0
+  }
+  const pattern = characters ? new RegExp(`[${characters}\\s]+`) : /\s+/
+  return str
+    .trim()
+    .split(pattern)
+    .filter((word) => 0 < word.length).length
+}
+
+/**
+ * Limit the number of words in a string.
+ *
+ * @param {string} value The string to limit
+ * @param {number} [words=100] The maximum number of words
+ * @param {string} [end='...'] The string to append if truncated
+ * @returns {string} The limited string
+ */
+export const strWords = (value: string, words = 100, end = '...'): string => {
+  if (!value) {
+    return ''
+  }
+  const wordArray = value.trim().split(/\s+/)
+  if (wordArray.length <= words) {
+    return value
+  }
+  return wordArray.slice(0, words).join(' ') + end
+}
+
+// Case transformation helpers
+/**
+ * Convert a string to camelCase.
+ *
+ * @param {string} value The string to convert
+ * @returns {string} The camelCased string
+ */
+export const camelCase = (value: string): string => {
+  const studly = studlyCase(value)
+  return studly.charAt(0).toLowerCase() + studly.slice(1)
+}
+
+/**
+ * Convert a string to snake_case.
+ *
+ * @param {string} value The string to convert
+ * @returns {string} The snake_cased string
+ */
+export const snakeCase = (value: string): string => {
+  return value
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/[\s-]+/g, '_')
+    .toLowerCase()
+}
+
+/**
+ * Convert a string to kebab-case.
+ *
+ * @param {string} value The string to convert
+ * @returns {string} The kebab-cased string
+ */
+export const kebabCase = (value: string): string => {
+  return value
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+}
+
+/**
+ * Convert a string to StudlyCase.
+ *
+ * @param {string} value The string to convert
+ * @returns {string} The studlyCased string
+ */
+export const studlyCase = (value: string): string => {
+  return value
+    .replace(/[_-]/g, ' ')
+    .replace(/\s+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, (_, c) => c.toUpperCase())
+    .replace(/\s+/g, '')
+}
+
+/**
+ * Convert a string to Title Case.
+ *
+ * @param {string} value The string to convert
+ * @returns {string} The titleCased string
+ */
+export const titleCase = (value: string): string => {
+  return value.replace(/\w\S*/g, (txt) => {
+    return txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase()
+  })
+}
+
+/**
+ * Format a number with grouped thousands and decimal point.
+ *
+ * @param {number} value The number to format
+ * @param {number} [decimals=2] The number of decimal points
+ * @param {string} [locale='en-US'] The locale to use for formatting
+ * @returns {string} The formatted number
+ */
+export const numberFormat = (value: number, decimals: number = 2, locale: string = 'en-US'): string => {
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value)
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @zairakai/npm-helpers
+ * Collection of JavaScript utility functions
+ */
+
+// Export all validators
+export * from './validators.js'
+
+// Export all formatters
+export * from './formatters.js'
+
+// Export all array helpers
+export * from './arrays.js'
+
+// Export enhanced collections
+export * from './collections.js'
+
+// Export PHP-like array functions
+export * from './php-arrays.js'
+
+// Export datetime utilities
+export * from './datetime.js'
+
+// Export runtime validation schemas
+export * from './schemas.js'
+
+// Export new runtime helpers
+export * from './equals.js'
+export * from './number.js'
+export * from './obj.js'
+export * from './runtime.js'
+export * from './str.js'
+export * from './types.js'
+export * from './validator.js'
+
+export * from './pipe.js'