@luquimbo/bi-superpowers 3.1.0 → 3.2.0

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

@@ -1,228 +0,0 @@
-# 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)