@luquimbo/bi-superpowers 1.0.0

package/library/examples/udf-library/README.md

@@ -0,0 +1,228 @@
+# DAX User Defined Functions Library
+
+A curated collection of reusable DAX User Defined Functions (UDFs) for common analytical patterns.
+
+> **Status:** UDFs are a preview feature released September 2025. Syntax may change.
+
+---
+
+## Overview
+
+This library provides ready-to-use functions for:
+- Financial calculations (NPV, IRR, CAGR, loan payments)
+- Statistical analysis (standard deviation, percentiles, z-scores)
+- Text manipulation (formatting, validation, extraction)
+- Date utilities (business days, fiscal periods, age calculation)
+- Data validation (null handling, range checks, type validation)
+- Formatting helpers (currency, percentages, conditional formatting)
+
+---
+
+## How to Use
+
+### 1. Copy Functions to Your Query
+
+Copy the `DEFINE` block from `functions.dax` into your DAX query:
+
+```dax
+DEFINE
+    FUNCTION AddTax = (amount : NUMERIC, rate : NUMERIC) =>
+        amount * (1 + rate)
+
+EVALUATE { AddTax(100, 0.21) }
+```
+
+### 2. Use in DAX Studio
+
+1. Open DAX Studio connected to your model
+2. Paste the function definitions
+3. Write your EVALUATE statement using the functions
+
+### 3. Combine Multiple Functions
+
+```dax
+DEFINE
+    FUNCTION Round2 = (value : NUMERIC) => ROUND(value, 2)
+    FUNCTION AddTax = (amount : NUMERIC, rate : NUMERIC) => amount * (1 + rate)
+    FUNCTION FinalPrice = (price : NUMERIC, taxRate : NUMERIC) =>
+        Round2(AddTax(price, taxRate))
+
+EVALUATE
+ADDCOLUMNS(
+    Products,
+    "Price With Tax", FinalPrice([BasePrice], 0.21)
+)
+```
+
+---
+
+## Function Catalog
+
+### Financial Functions
+
+| Function | Description | Parameters |
+|----------|-------------|------------|
+| `AddTax` | Add tax to amount | `amount`, `rate` |
+| `CAGR` | Compound annual growth rate | `startValue`, `endValue`, `years` |
+| `MonthlyPayment` | Loan payment calculation | `principal`, `annualRate`, `months` |
+| `FutureValue` | Future value of investment | `presentValue`, `rate`, `periods` |
+| `PresentValue` | Present value calculation | `futureValue`, `rate`, `periods` |
+| `SimpleInterest` | Simple interest amount | `principal`, `rate`, `time` |
+| `CompoundInterest` | Compound interest amount | `principal`, `rate`, `periods` |
+| `EffectiveRate` | Effective annual rate | `nominalRate`, `periodsPerYear` |
+
+### Statistical Functions
+
+| Function | Description | Parameters |
+|----------|-------------|------------|
+| `ZScore` | Calculate z-score | `value`, `mean`, `stdDev` |
+| `Normalize` | Normalize to 0-1 range | `value`, `min`, `max` |
+| `Clamp` | Constrain value to range | `value`, `min`, `max` |
+| `RoundToNearest` | Round to nearest multiple | `value`, `multiple` |
+| `MovingAverage` | Simple moving average | (requires table context) |
+
+### Text Functions
+
+| Function | Description | Parameters |
+|----------|-------------|------------|
+| `FormatName` | "Last, First" format | `firstName`, `lastName` |
+| `GetInitials` | Extract initials | `fullName` |
+| `SafeTrim` | Null-safe trim | `text` |
+| `TruncateText` | Truncate with ellipsis | `text`, `maxLength` |
+| `PadLeft` | Left-pad string | `text`, `length`, `padChar` |
+| `PadRight` | Right-pad string | `text`, `length`, `padChar` |
+
+### Date Functions
+
+| Function | Description | Parameters |
+|----------|-------------|------------|
+| `CalculateAge` | Age in years | `birthDate` |
+| `FiscalYear` | Fiscal year (July start) | `dateValue` |
+| `FiscalQuarter` | Fiscal quarter | `dateValue` |
+| `IsWeekend` | Check if weekend | `dateValue` |
+| `IsLeapYear` | Check for leap year | `year` |
+| `QuarterStart` | First day of quarter | `dateValue` |
+| `QuarterEnd` | Last day of quarter | `dateValue` |
+
+### Validation Functions
+
+| Function | Description | Parameters |
+|----------|-------------|------------|
+| `IsValidEmail` | Basic email validation | `email` |
+| `InRange` | Check if value in range | `value`, `min`, `max` |
+| `NullSafeEquals` | Null-safe comparison | `val1`, `val2` |
+| `Coalesce` | Return first non-blank | `value`, `defaultValue` |
+| `SafeDivide` | Division with zero handling | `numerator`, `denominator` |
+| `IsNumericString` | Check if string is numeric | `text` |
+
+### Formatting Functions
+
+| Function | Description | Parameters |
+|----------|-------------|------------|
+| `FormatCurrency` | Format as currency | `value`, `decimals` |
+| `FormatPercent` | Format as percentage | `value`, `decimals` |
+| `FormatThousands` | Format with K/M/B suffix | `value` |
+| `FormatDelta` | Format with +/- sign | `value` |
+| `ConditionalFormat` | Value-based formatting | `value`, `thresholds` |
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `README.md` | This documentation |
+| `functions.dax` | Complete function library with examples |
+
+---
+
+## Usage Examples
+
+### Financial Analysis
+
+```dax
+DEFINE
+    FUNCTION CAGR = (startValue : NUMERIC, endValue : NUMERIC, years : NUMERIC) =>
+        IF(startValue > 0 && years > 0,
+            POWER(endValue / startValue, 1 / years) - 1,
+            BLANK()
+        )
+
+EVALUATE
+SUMMARIZE(
+    Sales,
+    [Year],
+    "Revenue", SUM(Sales[Amount]),
+    "Growth Rate", CAGR(
+        CALCULATE(SUM(Sales[Amount]), PREVIOUSYEAR('Date'[Date])),
+        SUM(Sales[Amount]),
+        1
+    )
+)
+```
+
+### Data Validation
+
+```dax
+DEFINE
+    FUNCTION IsValidEmail = (email : STRING) =>
+        VAR _HasAt = FIND("@", email, 1, 0) > 0
+        VAR _HasDot = FIND(".", email, FIND("@", email, 1, 0) + 1, 0) > 0
+        VAR _NoSpaces = FIND(" ", email, 1, 0) = 0
+        RETURN _HasAt && _HasDot && _NoSpaces && LEN(email) >= 5
+
+EVALUATE
+FILTER(
+    Customers,
+    NOT IsValidEmail([Email])
+)
+```
+
+### Reporting
+
+```dax
+DEFINE
+    FUNCTION FormatThousands = (value : NUMERIC) =>
+        SWITCH(
+            TRUE(),
+            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")
+        )
+
+EVALUATE
+ADDCOLUMNS(
+    SUMMARIZE(Sales, [Region]),
+    "Revenue Display", FormatThousands(SUM(Sales[Amount]))
+)
+```
+
+---
+
+## Best Practices
+
+1. **Copy only what you need** - Don't include unused functions
+2. **Document modifications** - Add comments when customizing
+3. **Test thoroughly** - UDFs are in preview, validate results
+4. **Consider performance** - Complex functions may impact query time
+5. **Use specific types** - Avoid AnyVal when a specific type works
+
+---
+
+## Contributing
+
+To add functions to this library:
+1. Follow the naming conventions (PascalCase)
+2. Include documentation comments (///)
+3. Add to the appropriate category
+4. Include example usage
+5. Test with edge cases (nulls, zeros, negatives)
+
+---
+
+## References
+
+- [Microsoft Learn: DAX User Defined Functions](https://learn.microsoft.com/en-us/dax/dax-queries#user-defined-functions)
+- [SQLBI: DAX UDFs](https://www.sqlbi.com/articles/user-defined-functions-in-dax/)
+- [BI Agent Superpowers DAX Snippets](../../snippets/dax/user-defined-functions.md)