h3ravel-monorepo 0.1.1

package/packages/support/src/Helpers/Number.ts

@@ -0,0 +1,194 @@
+/**
+ * Abbreviates large numbers using SI symbols (K, M, B...) 
+ * and formats the output according to the given locale.
+ *
+ * @param value - The number to abbreviate
+ * @param locale - Optional locale string (default: "en-US")
+ * @returns A localized, abbreviated number string
+ */
+export const abbreviate = (value?: number, locale: string = 'en-US'): string => {
+    if (!value) return '0'
+
+    // Numbers less than 1000 don't need abbreviation
+    if (value < 1000) {
+        return new Intl.NumberFormat(locale).format(value)
+    }
+
+    const si = [
+        { v: 1e18, s: 'E' },
+        { v: 1e15, s: 'P' },
+        { v: 1e12, s: 'T' },
+        { v: 1e9, s: 'B' },
+        { v: 1e6, s: 'M' },
+        { v: 1e3, s: 'K' },
+    ]
+
+    const match = si.find(scale => value >= scale.v)
+    if (!match) return new Intl.NumberFormat(locale).format(value)
+
+    const formatted = value / match.v
+
+    return (
+        new Intl.NumberFormat(locale, {
+            minimumFractionDigits: 0,
+            maximumFractionDigits: 2,
+        }).format(formatted) + match.s
+    )
+}
+
+/**
+ * Concverts a number into human readable string
+ *
+ * @param num The number to convert
+ * @param slugify convert the ouput into a slug using this as a separator
+ * @returns
+ */
+export const humanize = (num: number, slugify?: '-' | '_'): string => {
+    if (!num) {
+        return ''
+    }
+
+    if (slugify === '-' || slugify === '_') {
+        const h = humanize(num)
+        return typeof h === 'string' ? h.replace(' ', slugify).toLowerCase() : h
+    }
+
+    const ones = [
+        '',
+        'one',
+        'two',
+        'three',
+        'four',
+        'five',
+        'six',
+        'seven',
+        'eight',
+        'nine',
+        'ten',
+        'eleven',
+        'twelve',
+        'thirteen',
+        'fourteen',
+        'fifteen',
+        'sixteen',
+        'seventeen',
+        'eighteen',
+        'nineteen',
+    ]
+    const tens = [
+        '',
+        '',
+        'twenty',
+        'thirty',
+        'forty',
+        'fifty',
+        'sixty',
+        'seventy',
+        'eighty',
+        'ninety',
+    ]
+
+    const numString: string = num.toString()
+
+    if (num < 0) throw new Error('Negative numbers are not supported.')
+
+    if (num === 0) return 'zero'
+
+    //the case of 1 - 20
+    if (num < 20) {
+        return ones[num] ?? ''
+    }
+
+    if (numString.length === 2) {
+        return tens[numString[0] as unknown as number] + ' ' + ones[numString[1] as unknown as number]
+    }
+
+    //100 and more
+    if (numString.length == 3) {
+        if (numString[1] === '0' && numString[2] === '0')
+            return ones[numString[0] as unknown as number] + ' hundred'
+        else
+            return (
+                ones[numString[0] as unknown as number] +
+                ' hundred and ' +
+                humanize(+((numString[1] || '') + numString[2]), slugify)
+            )
+    }
+
+    if (numString.length === 4) {
+        const end = +((numString[1] || '') + numString[2] + numString[3])
+        if (end === 0) return ones[numString[0] as unknown as number] + ' thousand'
+        if (end < 100)
+            return ones[numString[0] as unknown as number] + ' thousand and ' + humanize(end, slugify)
+        return ones[numString[0] as unknown as number] + ' thousand ' + humanize(end, slugify)
+    }
+
+    return num as unknown as string
+}
+
+/**
+ * Converts a number of bytes into a human-readable string.
+ *
+ * @param bytes - The size in bytes to convert
+ * @param decimals - Number of decimal places to display (default: 2)
+ * @param bits - If true, uses 1000-based (SI) units (B, KB, MB...); 
+ *               otherwise uses 1024-based binary units (Bytes, KiB...)
+ * @returns A formatted string with the appropriate unit
+ */
+export const toBytes = (
+    bytes?: number,
+    decimals: number = 2,
+    bits: boolean = false
+): string => {
+    if (!bytes || isNaN(bytes)) {
+        return bits ? '0 B' : '0 Bytes'
+    }
+
+    const base = bits ? 1000 : 1024
+    const dm = decimals < 0 ? 0 : decimals
+    const sizes = bits
+        ? ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'] // SI units
+        : ['Bytes', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'] // Binary units
+
+    const index = Math.floor(Math.log(bytes) / Math.log(base))
+
+    const value = parseFloat((bytes / Math.pow(base, index)).toFixed(dm))
+    return `${value} ${sizes[index]}`
+}
+
+/**
+ * Formats a duration (in seconds) into a human-readable string.
+ *
+ * @param seconds - Duration in seconds
+ * @param worded - If true, outputs worded format (e.g., "1hr 2min 3sec"),
+ *                 otherwise HH:MM:SS (e.g., "01:02:03")
+ * @returns A formatted time string
+ */
+export const toHumanTime = (
+    seconds: number = 0,
+    worded: boolean = false
+): string => {
+    // Ensure seconds is a number and not negative
+    if (isNaN(seconds) || seconds < 0) seconds = 0
+
+    const hours = Math.floor(seconds / 3600)
+    const minutes = Math.floor((seconds % 3600) / 60)
+    const secs = Math.floor(seconds % 60)
+
+    // Worded format → "1hr 2min 3sec"
+    if (worded) {
+        const parts = []
+        if (hours) parts.push(`${hours}hr`)
+        if (minutes) parts.push(`${minutes}min`)
+        if (secs || (!hours && !minutes)) parts.push(`${secs}sec`)
+        return parts.join(' ')
+    }
+
+    // HH:MM:SS format → zero-padded
+    const hh = hours > 0 ? `${hours}:` : ''
+    const mm = (hours > 0 && minutes < 10 ? `0${minutes}` : minutes) + ':'
+    const ss = secs < 10 ? `0${secs}` : secs
+
+    return `${hh}${mm}${ss}`
+}
+

package/packages/support/src/Helpers/Obj.ts

@@ -0,0 +1,220 @@
+import { DotFlatten, DotNestedKeys, DotNestedValue, KeysToSnakeCase } from "../Contracts/ObjContract"
+
+/**
+ * Flattens a nested object into a single-level object
+ * with dot-separated keys.
+ *
+ * Example:
+ * doter({
+ *   user: { name: "John", address: { city: "NY" } },
+ *   active: true
+ * })
+ * 
+ * Output:
+ * {
+ *   "user.name": "John",
+ *   "user.address.city": "NY",
+ *   "active": true
+ * }
+ *
+ * @template T - The type of the input object
+ * @param obj - The nested object to flatten
+ * @returns A flattened object with dotted keys and inferred types
+ */
+export const dot = <T extends Record<string, any>> (obj: T): DotFlatten<T> => {
+    const result = {} as Record<string, unknown>
+
+    /**
+     * Internal recursive function to traverse and flatten the object.
+     * 
+     * @param o - Current object to flatten
+     * @param prefix - Key path accumulated so far
+     */
+    const recurse = (o: Record<string, any>, prefix = ''): void => {
+        for (const [key, value] of Object.entries(o)) {
+            const newKey = prefix ? `${prefix}.${key}` : key
+
+            /**
+             * Recurse if the value is a plain object
+             */
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                recurse(value, newKey)
+            } else {
+                /**
+                 * Otherwise, assign directly
+                 */
+                result[newKey] = value
+            }
+        }
+    }
+
+    recurse(obj)
+    return result as DotFlatten<T>
+}
+
+/**
+ * Extracts a subset of properties from an object.
+ *
+ * @template T - Type of the source object
+ * @template K - Keys of T to extract
+ * @param obj - The source object
+ * @param keys - Array of keys to extract
+ * @returns A new object with only the specified keys
+ */
+export const extractProperties = <T extends object, K extends keyof T> (
+    obj: T,
+    keys: readonly K[] = []
+): Pick<T, K> => {
+    return Object.fromEntries(
+        keys.map(key => [key, obj[key]])
+    ) as Pick<T, K>
+}
+
+/**
+ * Safely retrieves a value from an object by key or nested keys.
+ *
+ * @template T - Type of the source object
+ * @param key - Single key or tuple [parentKey, childKey]
+ * @param item - The source object
+ * @returns The found value as a string or the key itself if not found
+ */
+export const getValue = <
+    T extends Record<string, any> // Allow nested objects
+> (
+    key: string | [keyof T, keyof T[string]],
+    item: T
+): string => {
+    if (Array.isArray(key)) {
+        const [parent, child] = key
+
+        if (child !== undefined) {
+            // Access nested property: item[parent][child]
+            return (
+                String(item?.[parent]?.[child] ??
+                    item?.[parent] ??
+                    `${String(parent)}.${String(child)}`)
+            )
+        }
+
+        // Only top-level key
+        return String(item?.[parent] ?? parent)
+    }
+
+    // Single key access
+    return String(item?.[key] ?? key)
+}
+
+/**
+ * Maps over an object's entries and returns a new object 
+ * with transformed keys and/or values.
+ *
+ * @template T - Type of the input object
+ * @template R - Type of the new values
+ * @param obj - The object to transform
+ * @param callback - Function that receives [key, value] and returns [newKey, newValue]
+ * @returns A new object with transformed entries
+ */
+export const modObj = <T extends object, R> (
+    obj: T,
+    callback: (entry: [keyof T & string, T[keyof T]]) => [string, R]
+): Record<string, R> => {
+    return Object.fromEntries(
+        Object.entries(obj).map(([key, value]) =>
+            callback([key as keyof T & string, value as T[keyof T]])
+        )
+    ) as Record<string, R>
+}
+
+
+export function safeDot<T extends Record<string, any>> (data: T): T
+export function safeDot<
+    T extends Record<string, any>,
+    K extends DotNestedKeys<T>
+> (data: T, key?: K): DotNestedValue<T, K>
+export function safeDot<
+    T extends Record<string, any>,
+    K extends DotNestedKeys<T>
+> (data: T, key?: K): any {
+    if (!key) return data
+    return key.split('.').reduce((acc: any, k) => acc?.[k], data)
+}
+
+/**
+ * Sets a nested property on an object using dot notation.
+ * 
+ * @example
+ * const obj = {}
+ * setNested(obj, 'app.user.name', 'Legacy')
+ * console.log(obj)
+ * // Output: { app: { user: { name: 'Legacy' } } }
+ * 
+ * @param obj - The target object to modify.
+ * @param key - The dot-separated key (e.g., 'app.user.name').
+ * @param value - The value to set at the specified path.
+ */
+export const setNested = (
+    obj: Record<string, any>,
+    key: string,
+    value: any
+): void => {
+    if (!key.includes('.')) {
+        obj[key] = value
+        return
+    }
+
+    const parts = key.split('.')
+    let current = obj
+
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i]
+
+        /**
+         * If we're at the last key, assign the value
+         */
+        if (i === parts.length - 1) {
+            current[part] = value
+        } else {
+            /**
+             * If the key doesn't exist or isn't an object, create it
+             */
+            if (typeof current[part] !== 'object' || current[part] === null) {
+                current[part] = {}
+            }
+            current = current[part]
+        }
+    }
+}
+
+/**
+ * Converts object keys to a slugified format (e.g., snake_case).
+ *
+ * @template T - Type of the input object
+ * @param obj - The object whose keys will be slugified
+ * @param only - Optional array of keys to slugify (others remain unchanged)
+ * @param separator - Separator for slugified keys (default: "_")
+ * @returns A new object with slugified keys
+ */
+export const slugifyKeys = <T extends object> (
+    obj: T,
+    only: string[] = [],
+    separator: string = '_'
+): KeysToSnakeCase<T> => {
+    const slugify = (key: string): string =>
+        key
+            .replace(/([a-z])([A-Z])/g, `$1${separator}$2`) // Handle camelCase
+            .replace(/[\s\W]+/g, separator)                 // Replace spaces/symbols
+            .replace(new RegExp(`${separator}{2,}`, 'g'), separator) // Remove duplicate separators
+            .replace(new RegExp(`^${separator}|${separator}$`, 'g'), '') // Trim edges
+            .toLowerCase()
+
+    let entries = Object.entries(obj)
+
+    // Filter if `only` is provided
+    if (only.length) {
+        entries = entries.filter(([key]) => only.includes(key))
+    }
+
+    return Object.fromEntries(
+        entries.map(([key, value]) => [slugify(key), value])
+    ) as KeysToSnakeCase<T>
+}

package/packages/support/src/Helpers/Str.ts

@@ -0,0 +1,256 @@
+import { dot } from "./Obj"
+
+/**
+ * Get the portion of the string after the first occurrence of the given value.
+ * 
+ * @param value 
+ * @param search 
+ * @returns 
+ */
+export const after = (value: string, search: string): string => {
+    if (!search) return value
+    const index = value.indexOf(search)
+    return index !== -1 ? value.slice(index + search.length) : value
+}
+
+/**
+ * Get the portion of the string after the last occurrence of the given value.
+ * 
+ * @param value 
+ * @param search 
+ * @returns 
+ */
+export const afterLast = (value: string, search: string): string => {
+    if (!search) return value
+    const lastIndex = value.lastIndexOf(search)
+    return lastIndex !== -1 ? value.slice(lastIndex + search.length) : value
+}
+
+/**
+ * Get the portion of the string before the first occurrence of the given value.
+ * 
+ * @param value 
+ * @param search 
+ * @returns 
+ */
+export const before = (value: string, search: string): string => {
+    if (!search) return value
+    const index = value.indexOf(search)
+    return index !== -1 ? value.slice(0, index) : value
+}
+
+/**
+ * Get the portion of the string before the last occurrence of the given value.
+ * 
+ * @param value 
+ * @param search 
+ * @returns 
+ */
+export const beforeLast = (value: string, search: string): string => {
+    if (!search) return value
+    const lastIndex = value.lastIndexOf(search)
+    return lastIndex !== -1 ? value.slice(0, lastIndex) : value
+}
+
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The input string
+ * @returns The string with the first character capitalized
+ */
+export function capitalize (str: string): string {
+    if (!str) return '' // Handle empty or undefined strings safely
+    return str[0].toUpperCase() + str.slice(1)
+}
+
+
+/**
+ * Returns the pluralized form of a word based on the given number.
+ *
+ * @param word - The word to pluralize
+ * @param count - The number determining pluralization
+ * @returns Singular if count === 1, otherwise plural form
+ */
+export const pluralize = (word: string, count: number): string => {
+    // If count is exactly 1 → singular
+    if (count === 1) return word
+
+    // Irregular plurals map
+    const irregularPlurals: Record<string, string> = {
+        foot: 'feet',
+        child: 'children',
+        mouse: 'mice',
+        goose: 'geese',
+        person: 'people',
+        man: 'men',
+        woman: 'women',
+    }
+
+    // Handle irregular cases first
+    if (word in irregularPlurals) {
+        return irregularPlurals[word]
+    }
+
+    // If word ends with consonant + "y" → replace "y" with "ies"
+    if (
+        word.endsWith('y') &&
+        !['a', 'e', 'i', 'o', 'u'].includes(word[word.length - 2]?.toLowerCase() ?? '')
+    ) {
+        return word.slice(0, -1) + 'ies'
+    }
+
+    // If word ends in "s", "ss", "sh", "ch", "x", or "z" → add "es"
+    if (/(s|ss|sh|ch|x|z)$/i.test(word)) {
+        return word + 'es'
+    }
+
+    // Default: just add "s"
+    return word + 's'
+}
+
+/**
+ * Converts a plural English word into its singular form.
+ *
+ * @param word - The word to singularize
+ * @returns The singular form of the word
+ */
+export const singularize = (word: string): string => {
+    // Irregular plurals map (reverse of pluralize)
+    const irregulars: Record<string, string> = {
+        feet: 'foot',
+        children: 'child',
+        mice: 'mouse',
+        geese: 'goose',
+        people: 'person',
+        men: 'man',
+        women: 'woman',
+    }
+
+    // Handle irregular cases
+    if (word in irregulars) return irregulars[word]
+
+    // Words ending in "ies" → change to "y" (e.g., "bodies" → "body")
+    if (/ies$/i.test(word) && word.length > 3) {
+        return word.replace(/ies$/i, 'y')
+    }
+
+    // Words ending in "es" after certain consonants → remove "es"
+    if (/(ches|shes|sses|xes|zes)$/i.test(word)) {
+        return word.replace(/es$/i, '')
+    }
+
+    // Generic case: remove trailing "s"
+    if (/s$/i.test(word) && word.length > 1) {
+        return word.replace(/s$/i, '')
+    }
+
+    return word
+}
+
+/**
+ * Converts a string into a slug format.
+ * Handles camelCase, spaces, and non-alphanumeric characters.
+ *
+ * @param str - The input string to slugify
+ * @param joiner - The character used to join words (default: "_")
+ * @returns A slugified string
+ */
+export const slugify = (str: string, joiner = '_'): string => {
+    return str
+        // Handle camelCase by adding joiner between lowercase → uppercase
+        .replace(/([a-z])([A-Z])/g, `$1${joiner}$2`)
+        // Replace spaces and non-alphanumeric characters with joiner
+        .replace(/[\s\W]+/g, joiner)
+        // Remove duplicate joiners
+        .replace(new RegExp(`${joiner}{2,}`, 'g'), joiner)
+        // Trim joiners from start/end
+        .replace(new RegExp(`^${joiner}|${joiner}$`, 'g'), '')
+        .toLowerCase()
+}
+
+/**
+ * Truncates a string to a specified length and appends an ellipsis if needed.
+ *
+ * @param str - The input string
+ * @param len - Maximum length of the result (including ellipsis)
+ * @param ellipsis - String to append if truncated (default: "...")
+ * @returns The truncated string
+ */
+export const subString = (
+    str: string,
+    len: number,
+    ellipsis: string = '...'
+): string => {
+    if (!str) return ''
+    if (len <= ellipsis.length) return ellipsis // Avoid negative slicing
+
+    return str.length > len
+        ? str.substring(0, len - ellipsis.length).trimEnd() + ellipsis
+        : str
+}
+
+/**
+ * Replaces placeholders in a string with corresponding values from a data object.
+ * 
+ * Example:
+ * substitute("Hello { user.name }!", { user: { name: "John" } })
+ * // "Hello John!"
+ *
+ * @param str - The string containing placeholders wrapped in { } braces.
+ * @param data - Object containing values to substitute. Supports nested keys via dot notation.
+ * @param def - Default value to use if a key is missing. (Optional)
+ * @returns The substituted string or undefined if the input string or data is invalid.
+ */
+export const substitute = (
+    str: string,
+    data: Record<string, unknown> = {},
+    def?: string
+): string | undefined => {
+    if (!str || !data) return undefined
+
+    // Matches { key } or { nested.key } placeholders
+    const regex = /{\s*([a-zA-Z0-9_.]+)\s*}/g
+
+    // Flatten the data so we can directly access dot notation keys
+    const flattened = dot(data)
+
+    // Replace each placeholder with its value or the default
+    const out = str.replace(regex, (_, key: string) => {
+        const value = flattened[key]
+        return value !== undefined ? String(value) : def ?? ''
+    })
+
+    return out
+}
+
+/**
+ * Truncates a string to a specified length, removing HTML tags and 
+ * appending a suffix if the string exceeds the length.
+ *
+ * @param str - The string to truncate
+ * @param len - Maximum length (default: 20)
+ * @param suffix - Suffix to append if truncated (default: "...")
+ * @returns The truncated string
+ */
+export const truncate = (
+    str: string,
+    len: number = 20,
+    suffix: string = '...'
+): string => {
+    if (!str) return ''
+
+    // Remove any HTML tags
+    const clean = str.replace(/<[^>]+>/g, '')
+
+    // Determine if we need to truncate
+    const truncated =
+        clean.length > len
+            ? clean.substring(0, len - suffix.length) + suffix
+            : clean
+
+    // Normalize spaces and line breaks
+    return truncated
+        .replace(/\n/g, ' ') // Replace all line breaks
+        .replace(new RegExp(`\\s+${suffix.replace(/\./g, '\\.')}$`), suffix) // Avoid extra space before suffix
+}
+

package/packages/support/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @file Automatically generated by barrelsby.
+ */
+
+export * from './Contracts/ObjContract';
+export * from './Contracts/StrContract';
+export * from './Helpers/Arr';
+export * from './Helpers/Number';
+export * from './Helpers/Obj';
+export * from './Helpers/Str';

package/packages/support/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"]
+}

package/packages/support/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    dts: true,
+    sourcemap: true,
+    clean: true
+})