@luquimbo/bi-superpowers 1.0.0

package/library/examples/udf-library/functions.dax

@@ -0,0 +1,571 @@
+// ============================================================================
+// DAX USER DEFINED FUNCTIONS LIBRARY
+// ============================================================================
+// A comprehensive collection of reusable UDFs for Power BI and Analysis Services
+// Status: Preview feature (September 2025)
+// ============================================================================
+
+
+// ----------------------------------------------------------------------------
+// FINANCIAL FUNCTIONS
+// ----------------------------------------------------------------------------
+
+DEFINE
+
+    /// Adds tax to an amount
+    /// @param amount - Base amount before tax
+    /// @param rate - Tax rate (e.g., 0.21 for 21%)
+    /// @returns Amount including tax
+    FUNCTION AddTax = (amount : NUMERIC, rate : NUMERIC) =>
+        amount * (1 + rate)
+
+    /// Removes tax from a gross amount
+    /// @param grossAmount - Amount including tax
+    /// @param rate - Tax rate (e.g., 0.21 for 21%)
+    /// @returns Amount excluding tax
+    FUNCTION RemoveTax = (grossAmount : NUMERIC, rate : NUMERIC) =>
+        grossAmount / (1 + rate)
+
+    /// Calculates Compound Annual Growth Rate
+    /// @param startValue - Initial value
+    /// @param endValue - Final value
+    /// @param years - Number of years
+    /// @returns Annual growth rate as decimal
+    FUNCTION CAGR = (startValue : NUMERIC, endValue : NUMERIC, years : NUMERIC) =>
+        IF(
+            startValue > 0 && years > 0,
+            POWER(endValue / startValue, 1 / years) - 1,
+            BLANK()
+        )
+
+    /// Calculates monthly loan payment (PMT equivalent)
+    /// @param principal - Loan amount
+    /// @param annualRate - Annual interest rate (e.g., 0.05 for 5%)
+    /// @param months - Number of monthly payments
+    /// @returns Monthly payment amount
+    FUNCTION MonthlyPayment = (principal : NUMERIC, annualRate : NUMERIC, months : INT64) =>
+        VAR _MonthlyRate = annualRate / 12
+        RETURN
+            IF(
+                _MonthlyRate = 0,
+                principal / months,
+                principal * _MonthlyRate * POWER(1 + _MonthlyRate, months) /
+                (POWER(1 + _MonthlyRate, months) - 1)
+            )
+
+    /// Calculates future value of an investment
+    /// @param presentValue - Current value
+    /// @param rate - Interest rate per period
+    /// @param periods - Number of periods
+    /// @returns Future value
+    FUNCTION FutureValue = (presentValue : NUMERIC, rate : NUMERIC, periods : NUMERIC) =>
+        presentValue * POWER(1 + rate, periods)
+
+    /// Calculates present value of a future amount
+    /// @param futureValue - Future value
+    /// @param rate - Discount rate per period
+    /// @param periods - Number of periods
+    /// @returns Present value
+    FUNCTION PresentValue = (futureValue : NUMERIC, rate : NUMERIC, periods : NUMERIC) =>
+        futureValue / POWER(1 + rate, periods)
+
+    /// Calculates simple interest
+    /// @param principal - Principal amount
+    /// @param rate - Annual interest rate
+    /// @param years - Time in years
+    /// @returns Interest amount
+    FUNCTION SimpleInterest = (principal : NUMERIC, rate : NUMERIC, years : NUMERIC) =>
+        principal * rate * years
+
+    /// Calculates compound interest (interest portion only)
+    /// @param principal - Principal amount
+    /// @param rate - Interest rate per period
+    /// @param periods - Number of compounding periods
+    /// @returns Interest earned
+    FUNCTION CompoundInterest = (principal : NUMERIC, rate : NUMERIC, periods : NUMERIC) =>
+        principal * (POWER(1 + rate, periods) - 1)
+
+    /// Converts nominal rate to effective annual rate
+    /// @param nominalRate - Nominal annual rate
+    /// @param periodsPerYear - Compounding periods per year
+    /// @returns Effective annual rate
+    FUNCTION EffectiveRate = (nominalRate : NUMERIC, periodsPerYear : INT64) =>
+        POWER(1 + nominalRate / periodsPerYear, periodsPerYear) - 1
+
+    /// Calculates profit margin percentage
+    /// @param revenue - Total revenue
+    /// @param cost - Total cost
+    /// @returns Margin as decimal
+    FUNCTION ProfitMargin = (revenue : NUMERIC, cost : NUMERIC) =>
+        IF(revenue <> 0, (revenue - cost) / revenue, BLANK())
+
+    /// Calculates markup percentage
+    /// @param sellingPrice - Selling price
+    /// @param cost - Cost price
+    /// @returns Markup as decimal
+    FUNCTION Markup = (sellingPrice : NUMERIC, cost : NUMERIC) =>
+        IF(cost <> 0, (sellingPrice - cost) / cost, BLANK())
+
+
+// ----------------------------------------------------------------------------
+// STATISTICAL FUNCTIONS
+// ----------------------------------------------------------------------------
+
+    /// Calculates z-score for a value
+    /// @param value - The value to standardize
+    /// @param mean - Population mean
+    /// @param stdDev - Population standard deviation
+    /// @returns Z-score
+    FUNCTION ZScore = (value : NUMERIC, mean : NUMERIC, stdDev : NUMERIC) =>
+        IF(stdDev <> 0, (value - mean) / stdDev, BLANK())
+
+    /// Normalizes a value to 0-1 range
+    /// @param value - Value to normalize
+    /// @param minVal - Minimum of range
+    /// @param maxVal - Maximum of range
+    /// @returns Normalized value (0-1)
+    FUNCTION Normalize = (value : NUMERIC, minVal : NUMERIC, maxVal : NUMERIC) =>
+        IF(maxVal <> minVal, (value - minVal) / (maxVal - minVal), BLANK())
+
+    /// Constrains a value to a specified range
+    /// @param value - Value to constrain
+    /// @param minVal - Minimum allowed value
+    /// @param maxVal - Maximum allowed value
+    /// @returns Clamped value
+    FUNCTION Clamp = (value : NUMERIC, minVal : NUMERIC, maxVal : NUMERIC) =>
+        MIN(MAX(value, minVal), maxVal)
+
+    /// Rounds value to nearest multiple
+    /// @param value - Value to round
+    /// @param multiple - Multiple to round to
+    /// @returns Rounded value
+    FUNCTION RoundToNearest = (value : NUMERIC, multiple : NUMERIC) =>
+        IF(multiple <> 0, ROUND(value / multiple, 0) * multiple, value)
+
+    /// Calculates percentage change
+    /// @param oldValue - Previous value
+    /// @param newValue - Current value
+    /// @returns Percentage change as decimal
+    FUNCTION PercentChange = (oldValue : NUMERIC, newValue : NUMERIC) =>
+        IF(oldValue <> 0, (newValue - oldValue) / ABS(oldValue), BLANK())
+
+    /// Calculates weighted value contribution
+    /// @param value - Individual value
+    /// @param weight - Weight for this value
+    /// @param totalWeight - Sum of all weights
+    /// @returns Weighted contribution
+    FUNCTION WeightedContribution = (value : NUMERIC, weight : NUMERIC, totalWeight : NUMERIC) =>
+        IF(totalWeight <> 0, value * weight / totalWeight, BLANK())
+
+    /// Calculates coefficient of variation
+    /// @param stdDev - Standard deviation
+    /// @param mean - Mean value
+    /// @returns CV as decimal
+    FUNCTION CoefficientOfVariation = (stdDev : NUMERIC, mean : NUMERIC) =>
+        IF(mean <> 0, stdDev / ABS(mean), BLANK())
+
+
+// ----------------------------------------------------------------------------
+// TEXT FUNCTIONS
+// ----------------------------------------------------------------------------
+
+    /// Formats name as "Last, First"
+    /// @param firstName - First name
+    /// @param lastName - Last name
+    /// @returns Formatted name
+    FUNCTION FormatName = (firstName : STRING, lastName : STRING) =>
+        TRIM(lastName) & ", " & TRIM(firstName)
+
+    /// Formats name as "First Last"
+    /// @param firstName - First name
+    /// @param lastName - Last name
+    /// @returns Formatted name
+    FUNCTION FormatFullName = (firstName : STRING, lastName : STRING) =>
+        TRIM(firstName) & " " & TRIM(lastName)
+
+    /// Extracts first initial from name
+    /// @param name - Full name or first name
+    /// @returns First character uppercased
+    FUNCTION GetInitial = (name : STRING) =>
+        UPPER(LEFT(TRIM(name), 1))
+
+    /// Null-safe trim operation
+    /// @param text - Text to trim
+    /// @returns Trimmed text or empty string
+    FUNCTION SafeTrim = (text : STRING) =>
+        IF(ISBLANK(text), "", TRIM(text))
+
+    /// Truncates text with ellipsis
+    /// @param text - Text to truncate
+    /// @param maxLength - Maximum length including ellipsis
+    /// @returns Truncated text
+    FUNCTION TruncateText = (text : STRING, maxLength : INT64) =>
+        IF(
+            LEN(text) <= maxLength,
+            text,
+            LEFT(text, maxLength - 3) & "..."
+        )
+
+    /// Left-pads a string to specified length
+    /// @param text - Text to pad
+    /// @param totalLength - Desired total length
+    /// @param padChar - Character to pad with
+    /// @returns Padded string
+    FUNCTION PadLeft = (text : STRING, totalLength : INT64, padChar : STRING) =>
+        IF(
+            LEN(text) >= totalLength,
+            text,
+            REPT(padChar, totalLength - LEN(text)) & text
+        )
+
+    /// Right-pads a string to specified length
+    /// @param text - Text to pad
+    /// @param totalLength - Desired total length
+    /// @param padChar - Character to pad with
+    /// @returns Padded string
+    FUNCTION PadRight = (text : STRING, totalLength : INT64, padChar : STRING) =>
+        IF(
+            LEN(text) >= totalLength,
+            text,
+            text & REPT(padChar, totalLength - LEN(text))
+        )
+
+    /// Repeats text n times with separator
+    /// @param text - Text to repeat
+    /// @param times - Number of repetitions
+    /// @param separator - Separator between repetitions
+    /// @returns Repeated text
+    FUNCTION RepeatWithSeparator = (text : STRING, times : INT64, separator : STRING) =>
+        IF(
+            times <= 0,
+            "",
+            text & REPT(separator & text, times - 1)
+        )
+
+    /// Extracts text between two delimiters
+    /// @param text - Source text
+    /// @param startDelim - Starting delimiter
+    /// @param endDelim - Ending delimiter
+    /// @returns Extracted text or blank
+    FUNCTION ExtractBetween = (text : STRING, startDelim : STRING, endDelim : STRING) =>
+        VAR _StartPos = FIND(startDelim, text, 1, 0)
+        VAR _EndPos = FIND(endDelim, text, _StartPos + LEN(startDelim), 0)
+        RETURN
+            IF(
+                _StartPos > 0 && _EndPos > 0,
+                MID(text, _StartPos + LEN(startDelim), _EndPos - _StartPos - LEN(startDelim)),
+                BLANK()
+            )
+
+
+// ----------------------------------------------------------------------------
+// DATE FUNCTIONS
+// ----------------------------------------------------------------------------
+
+    /// Calculates age in years from birth date
+    /// @param birthDate - Date of birth
+    /// @returns Age in complete years
+    FUNCTION CalculateAge = (birthDate : DATETIME) =>
+        DATEDIFF(birthDate, TODAY(), YEAR) -
+        IF(
+            DATE(YEAR(TODAY()), MONTH(birthDate), DAY(birthDate)) > TODAY(),
+            1,
+            0
+        )
+
+    /// Gets fiscal year (July 1 start)
+    /// @param dateValue - Date to evaluate
+    /// @returns Fiscal year number
+    FUNCTION FiscalYear = (dateValue : DATETIME) =>
+        IF(MONTH(dateValue) >= 7, YEAR(dateValue) + 1, YEAR(dateValue))
+
+    /// Gets fiscal quarter (July 1 start)
+    /// @param dateValue - Date to evaluate
+    /// @returns Fiscal quarter (1-4)
+    FUNCTION FiscalQuarter = (dateValue : DATETIME) =>
+        VAR _Month = MONTH(dateValue)
+        RETURN
+            SWITCH(
+                TRUE(),
+                _Month IN {7, 8, 9}, 1,
+                _Month IN {10, 11, 12}, 2,
+                _Month IN {1, 2, 3}, 3,
+                4
+            )
+
+    /// Checks if date is a weekend
+    /// @param dateValue - Date to check
+    /// @returns TRUE if Saturday or Sunday
+    FUNCTION IsWeekend = (dateValue : DATETIME) =>
+        WEEKDAY(dateValue, 2) >= 6
+
+    /// Checks if year is a leap year
+    /// @param year - Year to check
+    /// @returns TRUE if leap year
+    FUNCTION IsLeapYear = (year : INT64) =>
+        (MOD(year, 4) = 0 && MOD(year, 100) <> 0) || MOD(year, 400) = 0
+
+    /// Gets first day of quarter
+    /// @param dateValue - Any date in the quarter
+    /// @returns First day of that quarter
+    FUNCTION QuarterStart = (dateValue : DATETIME) =>
+        DATE(YEAR(dateValue), (QUARTER(dateValue) - 1) * 3 + 1, 1)
+
+    /// Gets last day of quarter
+    /// @param dateValue - Any date in the quarter
+    /// @returns Last day of that quarter
+    FUNCTION QuarterEnd = (dateValue : DATETIME) =>
+        EOMONTH(DATE(YEAR(dateValue), QUARTER(dateValue) * 3, 1), 0)
+
+    /// Gets first day of month
+    /// @param dateValue - Any date in the month
+    /// @returns First day of that month
+    FUNCTION MonthStart = (dateValue : DATETIME) =>
+        DATE(YEAR(dateValue), MONTH(dateValue), 1)
+
+    /// Gets days remaining in month
+    /// @param dateValue - Current date
+    /// @returns Number of days until month end
+    FUNCTION DaysRemainingInMonth = (dateValue : DATETIME) =>
+        DATEDIFF(dateValue, EOMONTH(dateValue, 0), DAY)
+
+    /// Gets days remaining in year
+    /// @param dateValue - Current date
+    /// @returns Number of days until year end
+    FUNCTION DaysRemainingInYear = (dateValue : DATETIME) =>
+        DATEDIFF(dateValue, DATE(YEAR(dateValue), 12, 31), DAY)
+
+    /// Calculates business days between dates (Mon-Fri)
+    /// @param startDate - Start date (exclusive)
+    /// @param endDate - End date (inclusive)
+    /// @returns Approximate business days
+    FUNCTION BusinessDays = (startDate : DATETIME, endDate : DATETIME) =>
+        VAR _TotalDays = DATEDIFF(startDate, endDate, DAY)
+        VAR _FullWeeks = INT(_TotalDays / 7)
+        VAR _RemainingDays = MOD(_TotalDays, 7)
+        VAR _StartDOW = WEEKDAY(startDate, 2)
+        VAR _ExtraWeekendDays =
+            SWITCH(
+                TRUE(),
+                _StartDOW + _RemainingDays <= 5, 0,
+                _StartDOW >= 6, MIN(2, _RemainingDays),
+                MIN(2, _StartDOW + _RemainingDays - 5)
+            )
+        RETURN
+            _TotalDays - (_FullWeeks * 2) - _ExtraWeekendDays
+
+
+// ----------------------------------------------------------------------------
+// VALIDATION FUNCTIONS
+// ----------------------------------------------------------------------------
+
+    /// Basic email format validation
+    /// @param email - Email address to validate
+    /// @returns TRUE if basic format is valid
+    FUNCTION IsValidEmail = (email : STRING) =>
+        VAR _Trimmed = TRIM(email)
+        VAR _AtPos = FIND("@", _Trimmed, 1, 0)
+        VAR _DotPos = FIND(".", _Trimmed, _AtPos + 1, 0)
+        VAR _HasSpace = FIND(" ", _Trimmed, 1, 0) > 0
+        RETURN
+            _AtPos > 1 &&
+            _DotPos > _AtPos + 1 &&
+            NOT _HasSpace &&
+            LEN(_Trimmed) >= 5
+
+    /// Checks if value is within a range (inclusive)
+    /// @param value - Value to check
+    /// @param minVal - Minimum allowed
+    /// @param maxVal - Maximum allowed
+    /// @returns TRUE if value is in range
+    FUNCTION InRange = (value : NUMERIC, minVal : NUMERIC, maxVal : NUMERIC) =>
+        value >= minVal && value <= maxVal
+
+    /// Null-safe equality comparison
+    /// @param val1 - First value
+    /// @param val2 - Second value
+    /// @returns TRUE if both null or both equal
+    FUNCTION NullSafeEquals = (val1 : ANYVAL, val2 : ANYVAL) =>
+        (ISBLANK(val1) && ISBLANK(val2)) ||
+        (NOT ISBLANK(val1) && NOT ISBLANK(val2) && val1 = val2)
+
+    /// Returns first non-blank value
+    /// @param value - Primary value
+    /// @param defaultValue - Fallback if primary is blank
+    /// @returns Non-blank value
+    FUNCTION Coalesce = (value : ANYVAL, defaultValue : ANYVAL) =>
+        IF(ISBLANK(value), defaultValue, value)
+
+    /// Safe division with zero handling
+    /// @param numerator - Dividend
+    /// @param denominator - Divisor
+    /// @returns Result or BLANK if division by zero
+    FUNCTION SafeDivide = (numerator : NUMERIC, denominator : NUMERIC) =>
+        IF(denominator = 0, BLANK(), numerator / denominator)
+
+    /// Safe division with custom default
+    /// @param numerator - Dividend
+    /// @param denominator - Divisor
+    /// @param defaultValue - Value to return if division fails
+    /// @returns Result or default value
+    FUNCTION SafeDivideDefault = (numerator : NUMERIC, denominator : NUMERIC, defaultValue : NUMERIC) =>
+        IF(denominator = 0, defaultValue, numerator / denominator)
+
+    /// Checks if string contains only digits
+    /// @param text - Text to check
+    /// @returns TRUE if only digits (0-9)
+    FUNCTION IsNumericString = (text : STRING) =>
+        VAR _Cleaned = TRIM(text)
+        VAR _Length = LEN(_Cleaned)
+        VAR _NumDigits =
+            LEN(_Cleaned) -
+            LEN(SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(
+            SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(
+                _Cleaned, "0", ""), "1", ""), "2", ""), "3", ""), "4", ""),
+                "5", ""), "6", ""), "7", ""), "8", ""), "9", ""))
+        RETURN
+            _Length > 0 && _Length = _NumDigits
+
+    /// Validates phone number format (basic - 10 digits)
+    /// @param phone - Phone number string
+    /// @returns TRUE if contains exactly 10 digits
+    FUNCTION IsValidPhone = (phone : STRING) =>
+        VAR _DigitsOnly =
+            SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(
+                phone, "-", ""), "(", ""), ")", ""), " ", "")
+        RETURN
+            IsNumericString(_DigitsOnly) && LEN(_DigitsOnly) = 10
+
+
+// ----------------------------------------------------------------------------
+// FORMATTING FUNCTIONS
+// ----------------------------------------------------------------------------
+
+    /// Formats number as currency
+    /// @param value - Numeric value
+    /// @param decimals - Decimal places
+    /// @returns Formatted string
+    FUNCTION FormatCurrency = (value : NUMERIC, decimals : INT64) =>
+        IF(
+            ISBLANK(value),
+            "",
+            "$" & FORMAT(value, REPT("0", 1) & "." & REPT("0", decimals))
+        )
+
+    /// Formats number as percentage
+    /// @param value - Decimal value (0.15 = 15%)
+    /// @param decimals - Decimal places
+    /// @returns Formatted string
+    FUNCTION FormatPercent = (value : NUMERIC, decimals : INT64) =>
+        IF(
+            ISBLANK(value),
+            "",
+            FORMAT(value * 100, "#,##0" & IF(decimals > 0, "." & REPT("0", decimals), "")) & "%"
+        )
+
+    /// Formats large numbers with K/M/B suffix
+    /// @param value - Numeric value
+    /// @returns Formatted string with suffix
+    FUNCTION FormatThousands = (value : NUMERIC) =>
+        SWITCH(
+            TRUE(),
+            ISBLANK(value), "",
+            ABS(value) >= 1000000000, FORMAT(value / 1000000000, "#,##0.0") & "B",
+            ABS(value) >= 1000000, FORMAT(value / 1000000, "#,##0.0") & "M",
+            ABS(value) >= 1000, FORMAT(value / 1000, "#,##0.0") & "K",
+            FORMAT(value, "#,##0")
+        )
+
+    /// Formats delta with +/- sign
+    /// @param value - Change value
+    /// @returns Formatted string with sign
+    FUNCTION FormatDelta = (value : NUMERIC) =>
+        IF(
+            ISBLANK(value),
+            "",
+            IF(value > 0, "+", "") & FORMAT(value, "#,##0.0")
+        )
+
+    /// Formats delta as percentage with +/- sign
+    /// @param value - Decimal value
+    /// @returns Formatted percentage with sign
+    FUNCTION FormatDeltaPercent = (value : NUMERIC) =>
+        IF(
+            ISBLANK(value),
+            "",
+            IF(value > 0, "+", "") & FORMAT(value * 100, "#,##0.0") & "%"
+        )
+
+    /// Returns status emoji based on value vs target
+    /// @param value - Actual value
+    /// @param target - Target value
+    /// @param tolerance - Acceptable variance (e.g., 0.05 for 5%)
+    /// @returns Status indicator text
+    FUNCTION StatusIndicator = (value : NUMERIC, target : NUMERIC, tolerance : NUMERIC) =>
+        VAR _Variance = SafeDivide(value - target, ABS(target))
+        RETURN
+            SWITCH(
+                TRUE(),
+                ISBLANK(_Variance), "?",
+                _Variance >= tolerance, "Above",
+                _Variance <= -tolerance, "Below",
+                "On Track"
+            )
+
+    /// Formats number with ordinal suffix (1st, 2nd, 3rd, etc.)
+    /// @param number - Integer value
+    /// @returns Number with ordinal suffix
+    FUNCTION FormatOrdinal = (number : INT64) =>
+        VAR _Suffix =
+            SWITCH(
+                TRUE(),
+                MOD(number, 100) IN {11, 12, 13}, "th",
+                MOD(number, 10) = 1, "st",
+                MOD(number, 10) = 2, "nd",
+                MOD(number, 10) = 3, "rd",
+                "th"
+            )
+        RETURN
+            FORMAT(number, "#,##0") & _Suffix
+
+
+// ----------------------------------------------------------------------------
+// EXAMPLE USAGE
+// ----------------------------------------------------------------------------
+
+// Uncomment any EVALUATE statement to test
+
+// Financial
+// EVALUATE { AddTax(100, 0.21) }                          -- 121
+// EVALUATE { CAGR(1000, 1500, 3) }                        -- 0.1447 (14.47%)
+// EVALUATE { MonthlyPayment(200000, 0.05, 360) }          -- 1073.64
+
+// Statistical
+// EVALUATE { ZScore(85, 75, 10) }                         -- 1.0
+// EVALUATE { Normalize(75, 50, 100) }                     -- 0.5
+// EVALUATE { Clamp(150, 0, 100) }                         -- 100
+
+// Text
+// EVALUATE { FormatName("John", "Smith") }                -- "Smith, John"
+// EVALUATE { TruncateText("Hello World", 8) }             -- "Hello..."
+
+// Date
+// EVALUATE { CalculateAge(DATE(1990, 5, 15)) }            -- depends on today
+// EVALUATE { FiscalYear(DATE(2024, 8, 1)) }               -- 2025
+// EVALUATE { IsWeekend(DATE(2024, 1, 6)) }                -- TRUE (Saturday)
+
+// Validation
+// EVALUATE { IsValidEmail("test@example.com") }           -- TRUE
+// EVALUATE { SafeDivide(100, 0) }                         -- BLANK
+// EVALUATE { Coalesce(BLANK(), "N/A") }                   -- "N/A"
+
+// Formatting
+// EVALUATE { FormatCurrency(1234.56, 2) }                 -- "$1234.56"
+// EVALUATE { FormatThousands(1500000) }                   -- "1.5M"
+// EVALUATE { FormatDeltaPercent(0.153) }                  -- "+15.3%"
+// EVALUATE { FormatOrdinal(23) }                          -- "23rd"
+
+
+// ============================================================================
+// END OF LIBRARY
+// ============================================================================