@getdashfy/utils 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,594 @@
+import * as dateFns from 'date-fns';
+export { dateFns };
+
+/**
+ * Type guard and utility functions for safe error message extraction.
+ *
+ * TypeScript's catch blocks receive `unknown` types, not `Error` types.
+ * These utilities provide type-safe ways to extract error messages from any thrown value.
+ *
+ * @link https://kentcdodds.com/blog/get-a-catch-block-error-message-with-typescript
+ */
+/**
+ * Safely extracts an error message from any thrown value.
+ *
+ * Use this in catch blocks to get a string message regardless of what was thrown.
+ *
+ * @param error - The caught error (of type unknown)
+ * @returns A string error message
+ *
+ * @example
+ * ```ts
+ * try {
+ *   // some code that might throw
+ * } catch (error) {
+ *   const message = getErrorMessage(error)
+ *   console.error(message)
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
+
+/**
+ * Base options shared across all format functions.
+ */
+interface BaseFormatOptions {
+    /** BCP 47 locale(s) for formatting (e.g. 'en-US', 'pt-BR') */
+    locale?: string | string[];
+    /** Custom output when value is 0 */
+    zeroFormat?: string;
+    /** Custom output when value is null or undefined */
+    nullFormat?: string;
+}
+/**
+ * Options for number formatting.
+ */
+interface NumberFormatOptions extends BaseFormatOptions {
+    /** Minimum number of decimal places */
+    minimumFractionDigits?: number;
+    /** Maximum number of decimal places */
+    maximumFractionDigits?: number;
+    /** Use compact notation (1K, 1.2M) */
+    notation?: 'standard' | 'scientific' | 'engineering' | 'compact';
+    /** Compact display: 'short' (1K) or 'long' (1 thousand) */
+    compactDisplay?: 'short' | 'long';
+}
+/**
+ * Options for currency formatting.
+ */
+interface CurrencyFormatOptions extends BaseFormatOptions {
+    /** ISO 4217 currency code (e.g. 'USD', 'EUR') */
+    currency?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/**
+ * Options for bytes formatting.
+ */
+interface BytesFormatOptions extends BaseFormatOptions {
+    /** Use binary units (KiB, MiB) instead of decimal (KB, MB) */
+    binary?: boolean;
+    /** Format as bits instead of bytes */
+    bits?: boolean;
+    /** Include +/- for positive/negative */
+    signed?: boolean;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/**
+ * Options for percentage formatting.
+ */
+interface PercentFormatOptions extends BaseFormatOptions {
+    /** Scale value by 100 (0.5 → 50%). Default: true */
+    scaleBy100?: boolean;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/**
+ * Options for time/duration formatting.
+ */
+interface TimeFormatOptions extends BaseFormatOptions {
+    /** Include seconds in output */
+    includeSeconds?: boolean;
+    /** Format style: 'short' (2h 30m) or 'long' (2 hours 30 minutes) */
+    style?: 'short' | 'long';
+}
+/**
+ * Options for temperature formatting.
+ */
+interface TemperatureFormatOptions extends BaseFormatOptions {
+    /** Temperature unit */
+    unit?: 'celsius' | 'fahrenheit' | 'kelvin';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/**
+ * Options for date formatting.
+ */
+interface DateFormatOptions extends BaseFormatOptions {
+    /** Date format pattern (date-fns tokens) */
+    format?: string;
+    /** For relative time: add "ago" / "in" suffix */
+    addSuffix?: boolean;
+}
+/**
+ * Options for list formatting.
+ */
+interface ListFormatOptions extends BaseFormatOptions {
+    /** Conjunction style: 'conjunction' (A, B, and C) or 'disjunction' (A, B, or C) */
+    type?: 'conjunction' | 'disjunction' | 'unit';
+    /** Style: 'long', 'short', or 'narrow' */
+    style?: 'long' | 'short' | 'narrow';
+}
+/**
+ * Options for ordinal formatting.
+ */
+interface OrdinalFormatOptions extends BaseFormatOptions {
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/**
+ * Options for exponential/scientific formatting.
+ */
+interface ExponentialFormatOptions extends BaseFormatOptions {
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+
+/**
+ * Format a byte count into a human-readable string.
+ *
+ * @param value - The byte count to format
+ * @param options - Optional formatting options
+ * @returns A human-readable string representing the byte count
+ *
+ * @example
+ * ```ts
+ * formatBytes(1024)                      // '1.02 kB'
+ * formatBytes(1024, { binary: true })    // '1 KiB'
+ * formatBytes(8192, { bits: true })      // '8.19 kbit'
+ * formatBytes(1024, { locale: 'de-DE' }) // '1,02 kB'
+ * ```
+ */
+declare function formatBytes(value: number | bigint, options?: BytesFormatOptions): string;
+/**
+ * Format a byte-rate value into a human-readable per-second string.
+ *
+ * @param value - The throughput in bytes per second
+ * @param options - Optional formatting options (same as {@link formatBytes})
+ * @returns A human-readable string representing the throughput
+ *
+ * @example
+ * ```ts
+ * formatBytesPerSecond(1024)                   // '1.02 kB/s'
+ * formatBytesPerSecond(1024, { binary: true }) // '1 KiB/s'
+ * formatBytesPerSecond(0)                      // '0 B/s'
+ * ```
+ */
+declare function formatBytesPerSecond(value: number | bigint, options?: BytesFormatOptions): string;
+
+/**
+ * Core utilities shared across format modules.
+ */
+/**
+ * Set the default locale for all format functions.
+ *
+ * When a format is called without `locale` in its options, it uses this value.
+ * Call at app startup or in tests for consistent output (e.g. `setDefaultLocale('en-US')`).
+ *
+ * @param locale - BCP 47 locale (e.g. 'en-US'), an array of fallbacks, or `undefined` to use runtime default
+ */
+declare function setDefaultLocale(locale: string | string[] | undefined): void;
+/**
+ * Get the current default locale.
+ *
+ * @returns The default locale, or `undefined` if none is set
+ */
+declare function getDefaultLocale(): string | string[] | undefined;
+
+/**
+ * Format a number as currency with the correct symbol and locale-specific formatting.
+ *
+ * @param value - The numeric value to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the currency value
+ *
+ * @example
+ * ```ts
+ * formatCurrency(1234.56)                      // '$1,234.56'
+ * formatCurrency(99.99, { currency: 'EUR' })   // '€99.99'
+ * formatCurrency(0, { zeroFormat: 'Free' })    // 'Free'
+ * formatCurrency(1234.56, { locale: 'de-DE' }) // '1.234,56 €'
+ * ```
+ */
+declare function formatCurrency(value: number, options?: CurrencyFormatOptions): string;
+
+/**
+ * Format a date (Date, string, or Unix timestamp in seconds).
+ *
+ * @param value - Date instance, ISO string, or Unix seconds
+ * @param options - Optional formatting options
+ * @returns Formatted string per the pattern
+ *
+ * @example
+ * ```ts
+ * formatDate(new Date('2025-03-13'))                 // 'Mar 13, 2025'
+ * formatDate('2025-03-13', { format: 'yyyy-MM-dd' }) // '2025-03-13'
+ * ```
+ */
+declare function formatDate(value: Date | string | number, options?: DateFormatOptions): string;
+/**
+ * Format a date as human-readable relative time.
+ *
+ * @param value - Date instance, ISO string, or Unix seconds
+ * @param options - Optional formatting options
+ * @returns Relative string such as "about 2 hours ago" or "in 3 days"
+ *
+ * @example
+ * ```ts
+ * formatRelativeTime(Date.now() / 1000 - 3600)        // 'about 1 hour ago'
+ * formatRelativeTime(new Date(), { addSuffix: false }) // 'less than a minute'
+ * ```
+ */
+declare function formatRelativeTime(value: Date | string | number, options?: DateFormatOptions): string;
+
+/**
+ * Format a number in exponential/scientific notation.
+ *
+ * @param value - The number to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the exponential value
+ *
+ * @example
+ * ```ts
+ * formatExponential(1234.56)                               // '1.23E3'
+ * formatExponential(1234.56, { maximumFractionDigits: 0 }) // '1E3'
+ * formatExponential(0.00123)                               // '1.23E-3'
+ * formatExponential(1234.56, { locale: 'de-DE' })          // '1,23E3'
+ * formatExponential(0, { zeroFormat: '0' })                // '0'
+ * ```
+ */
+declare function formatExponential(value: number, options?: ExponentialFormatOptions): string;
+
+/**
+ * Main format function - parses format strings and delegates to the appropriate formatter.
+ *
+ * @param value - The value to format
+ * @param formatString - The format string
+ * @param options - Optional formatting options
+ * @returns The formatted value
+ *
+ * @example
+ * ```ts
+ * format(1000, '0,0')
+ * // => '1,000'
+ *
+ * format(1500000, '0.0a')
+ * // => '1.5M'
+ *
+ * format(new Date(), 'relative')
+ * // => 'less than a minute ago'
+ * ```
+ */
+declare function format(value: number | bigint | Date | string | string[] | null | undefined, formatString: string, options?: BaseFormatOptions): string;
+
+/**
+ * Format a list of strings.
+ *
+ * @param items - The list of strings to format
+ * @param options - Optional formatting options
+ * @returns The formatted list
+ *
+ * @example
+ * ```ts
+ * formatList(['A', 'B', 'C'])
+ * // => 'A, B, and C'
+ *
+ * formatList(['A', 'B', 'C'], { type: 'disjunction' })
+ * // => 'A, B, or C'
+ *
+ * formatList(['A', 'B', 'C'], { style: 'short' })
+ * // => 'A, B, & C'
+ *
+ * formatList(['A', 'B', 'C'], { style: 'narrow' })
+ * // => 'A, B, C'
+ * ```
+ */
+declare function formatList(items: string[], options?: ListFormatOptions): string;
+
+/**
+ * Format a number with locale-aware thousands separators and optional decimals.
+ *
+ * @param value - The number to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the number
+ *
+ * @example
+ * ```ts
+ * formatNumber(1234.56)
+ * // => '1,234.56'
+ *
+ * formatNumber(1234.56, { maximumFractionDigits: 2 })
+ * // => '1,234.56'
+ *
+ * formatNumber(1234.56, { notation: 'compact' })
+ * // => '1.2K'
+ *
+ * formatNumber(1234.56, { notation: 'compact', compactDisplay: 'long' })
+ * // => '1.2 thousand'
+ * ```
+ */
+declare function formatNumber(value: number, options?: NumberFormatOptions): string;
+
+/**
+ * Format a number with ordinal suffix.
+ *
+ * @param value - The number to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the ordinal value
+ *
+ * @example
+ * ```ts
+ * formatOrdinal(1) // '1st'
+ * formatOrdinal(2) // '2nd'
+ * formatOrdinal(3) // '3rd'
+ * ```
+ */
+declare function formatOrdinal(value: number, options?: OrdinalFormatOptions): string;
+
+/**
+ * Format a number as a percentage.
+ *
+ * @param value - The number to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the percentage value
+ *
+ * @example
+ * ```ts
+ * formatPercent(0.5)
+ * // => '50%'
+ *
+ * formatPercent(0.5, { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+ * // => '50.00%'
+ *
+ * formatPercent(50, { scaleBy100: false })
+ * // => '50%' (value already 0–100)
+ * ```
+ */
+declare function formatPercent(value: number, options?: PercentFormatOptions): string;
+
+/**
+ * Format a temperature value.
+ *
+ * @param value - The temperature value to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the temperature value
+ *
+ * @example
+ * ```ts
+ * formatTemperature(25)                         // '25°C'
+ * formatTemperature(77, { unit: 'fahrenheit' }) // '77°F'
+ * formatTemperature(273.15, { unit: 'kelvin' }) // '273.15 K'
+ * ```
+ */
+declare function formatTemperature(value: number, options?: TemperatureFormatOptions): string;
+
+/**
+ * Format a duration in seconds to HH:MM:SS or human-readable string.
+ *
+ * @param seconds - The duration in seconds to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the time value
+ *
+ * @example
+ * ```ts
+ * formatTime(3661, { style: 'short' })
+ * // => '01:01:01'
+ *
+ * formatTime(65, { style: 'long' })
+ * // => '1 minute 5 seconds'
+ *
+ * formatTime(3661, { style: 'long', includeSeconds: false })
+ * // => '1 hour 1 minute'
+ * ```
+ */
+declare function formatTime(seconds: number, options?: TimeFormatOptions): string;
+/**
+ * Format a duration in seconds into a compact, multi-day-aware string.
+ *
+ * Drops zero units and joins the remainder with spaces. Useful for uptime
+ * fields where space is tight and the long-form `formatTime` is too verbose.
+ *
+ * @param seconds - The duration in seconds to format
+ * @param options - Optional formatting options
+ * @returns Formatted string representing the duration
+ *
+ * @example
+ * ```ts
+ * formatTimeCompact(3 * 86400 + 5 * 3600 + 12 * 60)
+ * // => '3d 5h 12m'
+ *
+ * formatTimeCompact(45 * 60)
+ * // => '45m'
+ *
+ * formatTimeCompact(0)
+ * // => '0m'
+ * ```
+ */
+declare function formatTimeCompact(seconds: number, options?: TimeFormatOptions): string;
+
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait` milliseconds.
+ *
+ * @template T - The type of the function to debounce
+ * @param func - The function to debounce
+ * @param wait - The number of milliseconds to delay execution
+ * @returns A new debounced version of the provided function
+ *
+ * @example
+ * ```ts
+ * // Debounce a search function
+ * const debouncedSearch = debounce((query: string) => {
+ *   fetchSearchResults(query)
+ * }, 300)
+ *
+ * // User types "hello"
+ * debouncedSearch('h')    // Waits...
+ * debouncedSearch('he')   // Cancels previous, waits...
+ * debouncedSearch('hel')  // Cancels previous, waits...
+ * // After 300ms of no calls, executes with 'hel'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Debounce window resize handler
+ * const debouncedResize = debounce(() => {
+ *   recalculateLayout()
+ * }, 150)
+ *
+ * window.addEventListener('resize', debouncedResize)
+ * ```
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
+
+/**
+ * Safely retrieves a nested property value from an object using a dot-notation path.
+ *
+ * This function provides a safe way to access deeply nested properties without
+ * worrying about undefined intermediate values. Similar to lodash's `_.get()`.
+ * Returns `undefined` if any part of the path doesn't exist.
+ *
+ * @param obj - The object to query
+ * @param path - The dot-notation path to the property (e.g., 'user.address.city')
+ * @returns The value at the path, or `undefined` if not found
+ *
+ * @example
+ * ```ts
+ * const user = { name: 'John', address: { city: 'NYC', zip: '10001' } }
+ *
+ * get(user, 'name')
+ * // => 'John'
+ * ```
+ *
+ * @example
+ * ```ts
+ * get(user, 'address.city')
+ * // => 'NYC'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Safe access - returns undefined instead of throwing
+ * get(user, 'address.country')
+ * // => undefined
+ * ```
+ */
+declare function get(obj: Record<string, unknown>, path: string): unknown;
+
+/** Check if the code is running in development mode. */
+declare const isDevelopment: boolean;
+/** Check if the code is running in production mode. */
+declare const isProduction: boolean;
+/** Check if the code is running in test mode. */
+declare const isTest: boolean;
+
+/**
+ * Check if the current platform is macOS.
+ */
+declare const isMac: boolean;
+/**
+ * Get the modifier key symbol based on the current platform.
+ *
+ * @returns '⌘' for macOS, 'Ctrl' for other platforms
+ *
+ * @example
+ * ```ts
+ * // On macOS
+ * `Press ${modKey}+S to save` // => 'Press ⌘+S to save'
+ *
+ * // On Windows/Linux
+ * `Press ${modKey}+S to save` // => 'Press Ctrl+S to save'
+ * ```
+ */
+declare const modKey: string;
+
+/** Check if the code is running on the client. */
+declare const isClient: boolean;
+/** Check if the code is running on the server. */
+declare const isServer: boolean;
+
+/**
+ * Converts any value to a string representation (primitives as-is, objects as JSON).
+ *
+ * @param value - The value to convert to a string
+ * @returns A string representation of the value
+ *
+ * @example
+ * ```ts
+ * stringifyValue(null)
+ * // => ''
+ *
+ * stringifyValue(undefined)
+ * // => ''
+ *
+ * stringifyValue('hello')
+ * // => 'hello'
+ *
+ * stringifyValue(42)
+ * // => '42'
+ *
+ * stringifyValue(true)
+ * // => 'true'
+ *
+ * stringifyValue({ name: 'John', age: 30 })
+ * // => '{"name":"John","age":30}'
+ *
+ * stringifyValue([1, 2, 3])
+ * // => '[1,2,3]'
+ * ```
+ */
+declare function stringifyValue(value: unknown): string;
+
+/**
+ * Truncates a string to a specified length and adds an ellipsis if needed.
+ *
+ * @param str - The string to truncate
+ * @param length - The maximum length before truncation (excluding ellipsis)
+ * @returns The truncated string with '...' appended, or the original if short enough
+ *
+ * @example
+ * ```ts
+ * truncate('Hello, World!', 5)
+ * // => 'Hello...'
+ *
+ * truncate('Short', 10)
+ * // => 'Short'
+ *
+ * // Perfect for long descriptions in UI
+ * const description = 'This is a very long description that needs truncation'
+ * truncate(description, 20)
+ * // => 'This is a very long ...'
+ * ```
+ */
+declare function truncate(str: string, length: number): string;
+
+/**
+ * Formats a value into a human-readable display string.
+ *
+ * @param value - The value to format
+ * @returns Formatted string representation for display
+ *
+ * @example
+ * ```ts
+ * valueToDisplayString(null)           // 'null'
+ * valueToDisplayString(undefined)       // 'undefined'
+ * valueToDisplayString(true)           // 'true'
+ * valueToDisplayString('hello')        // 'hello'
+ * valueToDisplayString(42)             // '42'
+ * valueToDisplayString([1, 2, 3])      // 'Array(3)'
+ * valueToDisplayString({ a: 1, b: 2 }) // 'Object(2)'
+ * ```
+ */
+declare function valueToDisplayString(value: unknown): string;
+
+export { type BaseFormatOptions, debounce, format, formatBytes, formatBytesPerSecond, formatCurrency, formatDate, formatExponential, formatList, formatNumber, formatOrdinal, formatPercent, formatRelativeTime, formatTemperature, formatTime, formatTimeCompact, get, getDefaultLocale, getErrorMessage, isClient, isDevelopment, isMac, isProduction, isServer, isTest, modKey, setDefaultLocale, stringifyValue, truncate, valueToDisplayString };