fable 3.1.51 → 3.1.53

package/docs/services/expression-parser-functions/dateyeardifference.md

@@ -0,0 +1,64 @@
+# dateyeardifference
+
+Calculates the difference between two dates in years.
+
+## Syntax
+
+```
+dateyeardifference(startDate, endDate)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `startDate` | String | Start date (ISO 8601 format) |
+| `endDate` | String | End date (ISO 8601 format) |
+
+## Returns
+
+String - The number of years between the two dates.
+
+## Description
+
+The `dateyeardifference` function calculates how many years have elapsed between two dates. The result is positive when endDate is after startDate, and negative otherwise.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = DATEYEARDIFFERENCE("2020-01-01T00:00:00.000Z", "2025-01-01T00:00:00.000Z")
+// Result: "5"
+```
+
+### Age Calculation
+
+```expression
+Age = DATEYEARDIFFERENCE(BirthDate, Today)
+```
+
+### Contract Duration
+
+```expression
+ContractYears = DATEYEARDIFFERENCE(StartDate, EndDate)
+```
+
+## Use Cases
+
+- **Age calculation**: Calculate age in years
+- **Anniversary**: Years since event
+- **Contracts**: Multi-year contract terms
+- **Experience**: Years of service
+
+## Related Functions
+
+- [datedaydifference](./datedaydifference.md) - Difference in days
+- [datemonthdifference](./datemonthdifference.md) - Difference in months
+- [dateaddyears](./dateaddyears.md) - Add years to a date
+
+## Notes
+
+- Uses ISO 8601 date format
+- Result can be negative
+- Uses the Dates service internally

package/docs/services/expression-parser-functions/distributionhistogram.md

@@ -0,0 +1,96 @@
+# distributionhistogram
+
+Generates a histogram counting occurrences of each unique value.
+
+## Syntax
+
+```
+distributionhistogram(dataPath, keyProperty)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dataPath` | String | Path to the data array (quoted string) |
+| `keyProperty` | String | Property name to count occurrences of |
+
+## Returns
+
+Object - A histogram object with unique values and their counts.
+
+## Description
+
+The `distributionhistogram` function creates a histogram by counting how many times each unique value appears in a dataset. This is useful for understanding the distribution of categorical data.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given city data with a 'state' property
+DistributionResult = distributionhistogram("AppData.Cities", "state")
+
+// Result: {
+//   'Alabama': 12,
+//   'Colorado': 21,
+//   'Florida': 73,
+//   'Georgia': 18,
+//   // ... etc
+// }
+```
+
+### Counting Categories
+
+```expression
+// Count orders by status
+StatusCounts = distributionhistogram("AppData.Orders", "status")
+// Result: { 'pending': 45, 'shipped': 123, 'delivered': 89 }
+```
+
+### With Verification
+
+```expression
+// Verify distribution counts match data
+DistributionResult = distributionhistogram("AppData.Cities", "state")
+// DistributionResult.Alabama should equal 12
+// DistributionResult.Colorado should equal 21
+```
+
+## Use Cases
+
+- **Demographic analysis**: Count people by category
+- **Survey results**: Tally responses
+- **Quality metrics**: Distribution of defect types
+- **Inventory**: Count items by category
+- **Geographic analysis**: Records per region
+
+## Difference from aggregationhistogram
+
+| distributionhistogram | aggregationhistogram |
+|----------------------|---------------------|
+| Counts occurrences | Sums values |
+| One property (key) | Two properties (key, value) |
+| Result: counts | Result: sums |
+
+```expression
+// Distribution: How many cities per state?
+distributionhistogram("AppData.Cities", "state")
+// { 'California': 73, 'Texas': 51, ... }
+
+// Aggregation: Total population per state?
+aggregationhistogram("AppData.Cities", "state", "population")
+// { 'California': '39538223', 'Texas': '29145505', ... }
+```
+
+## Related Functions
+
+- [distributionhistogrambyobject](./distributionhistogrambyobject.md) - Takes object directly
+- [aggregationhistogram](./aggregationhistogram.md) - Sum values instead of count
+- [count](./count.md) - Simple count of elements
+
+## Notes
+
+- The data path must be a quoted string
+- Returns integer counts for each unique value
+- Works with the Math service's `histogramDistributionByExactValueFromInternalState` method

package/docs/services/expression-parser-functions/distributionhistogrambyobject.md

@@ -0,0 +1,64 @@
+# distributionhistogrambyobject
+
+Generates a distribution histogram from an object directly.
+
+## Syntax
+
+```
+distributionhistogrambyobject(object, keyProperty)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `object` | Array | Array of objects to count |
+| `keyProperty` | String | Property name to count occurrences of |
+
+## Returns
+
+Object - A histogram object with unique values and their counts.
+
+## Description
+
+The `distributionhistogrambyobject` function is similar to `distributionhistogram` but takes an object/array directly instead of a data path string. This is useful when working with data that's already in a variable.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given array of order data
+Orders = [
+  { id: 1, status: 'pending' },
+  { id: 2, status: 'shipped' },
+  { id: 3, status: 'pending' },
+  { id: 4, status: 'delivered' }
+]
+
+Result = DISTRIBUTIONHISTOGRAMBYOBJECT(Orders, "status")
+// Result: { 'pending': 2, 'shipped': 1, 'delivered': 1 }
+```
+
+### With Filtered Data
+
+```expression
+CategoryCounts = DISTRIBUTIONHISTOGRAMBYOBJECT(FilteredProducts, "category")
+```
+
+## Use Cases
+
+- **Dynamic data**: Count data already in variables
+- **Filtered data**: Count after filtering
+- **Chained operations**: Use in expression chains
+
+## Related Functions
+
+- [distributionhistogram](./distributionhistogram.md) - Uses data path string
+- [aggregationhistogrambyobject](./aggregationhistogrambyobject.md) - Sum by object
+- [count](./count.md) - Simple count
+
+## Notes
+
+- Takes array directly, not path string
+- Uses the Math service's `histogramDistributionByExactValue` method

package/docs/services/expression-parser-functions/entryinset.md

@@ -0,0 +1,72 @@
+# entryinset
+
+Checks if a value exists in a set/array.
+
+## Syntax
+
+```
+entryinset(value, set)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | Any | The value to search for |
+| `set` | Array | The array to search in |
+
+## Returns
+
+Boolean - True if the value exists in the set, false otherwise.
+
+## Description
+
+The `entryinset` function checks whether a specific value exists within an array or set. This is useful for membership testing and validation.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = ENTRYINSET(3, [1, 2, 3, 4, 5])
+// Result: true
+```
+
+### Not Found
+
+```expression
+Result = ENTRYINSET(10, [1, 2, 3, 4, 5])
+// Result: false
+```
+
+### With Variables
+
+```expression
+IsValidStatus = ENTRYINSET(OrderStatus, ["pending", "shipped", "delivered"])
+```
+
+### Validation
+
+```expression
+IsAllowedCategory = ENTRYINSET(Category, AllowedCategories)
+```
+
+## Use Cases
+
+- **Validation**: Check if value is allowed
+- **Filtering**: Conditional processing
+- **Membership**: Check set membership
+- **Logic**: Conditional branching
+
+## Related Functions
+
+- [findfirstvaluebyexactmatch](./findfirstvaluebyexactmatch.md) - Find value in array
+- [if](./if.md) - Use with conditional logic
+- [when](./when.md) - Conditional expression
+
+## Notes
+
+- Returns boolean (true/false)
+- Uses exact matching
+- Case-sensitive for strings
+- Uses the Math service's `entryInSet` method

package/docs/services/expression-parser-functions/euler.md

@@ -0,0 +1,77 @@
+# euler
+
+Returns Euler's number (e) with high precision.
+
+## Syntax
+
+```
+euler()
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+String - Euler's number (e) to 100 decimal places.
+
+## Description
+
+The `euler` function returns Euler's number (e ≈ 2.71828...), which is the base of natural logarithms. It's one of the most important constants in mathematics and appears in many areas including calculus, probability, and physics.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = euler()
+// Result: "2.7182818284590452353602874713526624977572470936999595749669676277240766303535475945713821785251664274..."
+```
+
+### Exponential Growth
+
+```expression
+// Compound interest with continuous compounding
+// A = P * e^(rt)
+FinalAmount = Principal * euler()^(Rate * Time)
+```
+
+### Natural Logarithm Calculations
+
+```expression
+// e^x where x = 1
+Result = euler()^1
+// Result: e ≈ 2.71828...
+
+// From unit tests:
+Result = 2.71828182845905 ^ -0.282444
+```
+
+### In Complex Formulas
+
+```expression
+// Environmental calculation from unit tests
+EGS = ROUND(ROUND(0.0172834*2.71828182845905^(-0.0117685*Temp),5)*SQRT(ROUND(16.294-0.163*HR,1)/60),4)
+```
+
+## Use Cases
+
+- **Exponential growth/decay**: Population growth, radioactive decay
+- **Finance**: Continuous compound interest
+- **Probability**: Normal distribution calculations
+- **Calculus**: Natural logarithm and exponential functions
+- **Physics**: Decay processes, thermodynamics
+
+## Related Functions
+
+- [pi](./pi.md) - Pi constant
+- [exp](./exp.md) - e raised to a power
+- [log](./log.md) - Logarithm
+
+## Notes
+
+- Returns the full precision value stored in the Math service
+- Uses arbitrary precision arithmetic
+- Also known as Napier's constant
+- Approximately equal to 2.71828182845904523536...

package/docs/services/expression-parser-functions/exp.md

@@ -0,0 +1,74 @@
+# exp
+
+Calculates e raised to the power of a number.
+
+## Syntax
+
+```
+exp(exponent)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `exponent` | Number | The power to raise e to |
+
+## Returns
+
+Number - The value of e^exponent.
+
+## Description
+
+The `exp` function calculates e (Euler's number, approximately 2.71828) raised to the specified power. This is the inverse of the natural logarithm function.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = EXP(1)
+// Result: 2.718281828459045 (e)
+```
+
+### Exponential of Zero
+
+```expression
+Result = EXP(0)
+// Result: 1
+```
+
+### With Variables
+
+```expression
+GrowthFactor = EXP(Rate * Time)
+```
+
+### Inverse of log
+
+```expression
+// EXP and LOG are inverse functions
+Original = 2.5
+Transformed = EXP(LOG(Original))
+// Transformed ≈ 2.5
+```
+
+## Use Cases
+
+- **Growth models**: Exponential growth calculations
+- **Statistics**: Normal distribution calculations
+- **Finance**: Continuous compound interest
+- **Physics**: Decay and growth functions
+
+## Related Functions
+
+- [log](./log.md) - Inverse function (natural logarithm)
+- [euler](./euler.md) - Euler's number constant
+- [sqrt](./sqrt.md) - Square root
+
+## Notes
+
+- EXP(0) = 1
+- EXP(1) = e ≈ 2.71828
+- Uses JavaScript's `Math.exp` internally
+- Useful for exponential growth/decay calculations

package/docs/services/expression-parser-functions/findfirstvaluebyexactmatch.md

@@ -0,0 +1,67 @@
+# findfirstvaluebyexactmatch
+
+Finds the first object in an array where a property exactly matches a value.
+
+## Syntax
+
+```
+findfirstvaluebyexactmatch(array, property, value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | Array of objects to search |
+| `property` | String | Property name to match against |
+| `value` | Any | Value to match |
+
+## Returns
+
+Object - The first matching object, or undefined if not found.
+
+## Description
+
+The `findfirstvaluebyexactmatch` function searches through an array of objects and returns the first object where the specified property exactly matches the given value.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given array: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
+Result = FINDFIRSTVALUEBYEXACTMATCH(Users, "name", "Bob")
+// Result: { id: 2, name: "Bob" }
+```
+
+### Find by ID
+
+```expression
+User = FINDFIRSTVALUEBYEXACTMATCH(AppData.Users, "id", "U123")
+```
+
+### Product Lookup
+
+```expression
+Product = FINDFIRSTVALUEBYEXACTMATCH(Products, "sku", "WIDGET-001")
+```
+
+## Use Cases
+
+- **Lookups**: Find record by unique property
+- **Data retrieval**: Get specific object
+- **Validation**: Check if record exists
+- **Search**: Simple exact-match search
+
+## Related Functions
+
+- [findfirstvaluebystringincludes](./findfirstvaluebystringincludes.md) - Partial string match
+- [match](./match.md) - Regex pattern matching
+- [entryinset](./entryinset.md) - Check if value exists in set
+
+## Notes
+
+- Returns first match only
+- Case-sensitive matching
+- Returns undefined if not found
+- Uses the Utility service's `findFirstValueByExactMatch` method

package/docs/services/expression-parser-functions/findfirstvaluebystringincludes.md

@@ -0,0 +1,67 @@
+# findfirstvaluebystringincludes
+
+Finds the first object where a property contains a substring.
+
+## Syntax
+
+```
+findfirstvaluebystringincludes(array, property, substring)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | Array of objects to search |
+| `property` | String | Property name to search in |
+| `substring` | String | Substring to search for |
+
+## Returns
+
+Object - The first matching object, or undefined if not found.
+
+## Description
+
+The `findfirstvaluebystringincludes` function searches through an array of objects and returns the first object where the specified property contains the given substring.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given: [{ name: "Alice Smith" }, { name: "Bob Jones" }]
+Result = FINDFIRSTVALUEBYSTRINGINCLUDES(Users, "name", "Smith")
+// Result: { name: "Alice Smith" }
+```
+
+### Email Search
+
+```expression
+User = FINDFIRSTVALUEBYSTRINGINCLUDES(Users, "email", "@company.com")
+```
+
+### Description Search
+
+```expression
+Product = FINDFIRSTVALUEBYSTRINGINCLUDES(Products, "description", "wireless")
+```
+
+## Use Cases
+
+- **Fuzzy search**: Find by partial match
+- **Text search**: Search in text fields
+- **Filtering**: Find containing substring
+- **Lookups**: Partial name/ID matching
+
+## Related Functions
+
+- [findfirstvaluebyexactmatch](./findfirstvaluebyexactmatch.md) - Exact match
+- [match](./match.md) - Regex pattern matching
+- [entryinset](./entryinset.md) - Check membership
+
+## Notes
+
+- Case-sensitive by default
+- Returns first match only
+- Partial string matching
+- Uses the Utility service's `findFirstValueByStringIncludes` method

package/docs/services/expression-parser-functions/flatten.md

@@ -0,0 +1,76 @@
+# flatten
+
+Flattens a nested array or extracts property values from an array of objects.
+
+## Syntax
+
+```
+flatten(array)
+flatten(arrayOfObjects.property)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to flatten or property path to extract |
+
+## Returns
+
+Array - A flattened array of values.
+
+## Description
+
+The `flatten` function can flatten nested arrays into a single-level array, or extract all values of a specific property from an array of objects. This is essential for preparing data for aggregate functions.
+
+## Examples
+
+### Flatten Nested Arrays
+
+```expression
+Result = FLATTEN([[1, 2], [3, 4], [5]])
+// Result: [1, 2, 3, 4, 5]
+```
+
+### Extract Property Values
+
+```expression
+// Given AppData.Cities with objects containing 'population' property
+Populations = FLATTEN(AppData.Cities.population)
+// Result: [39538223, 29145505, 21538187, ...]
+```
+
+### With Aggregate Functions
+
+```expression
+// Sum all populations
+TotalPopulation = SUM(FLATTEN(AppData.Cities.population))
+```
+
+### Chain Operations
+
+```expression
+// Get average of extracted values
+AverageScore = AVG(FLATTEN(AppData.Students.score))
+```
+
+## Use Cases
+
+- **Data extraction**: Get property values from object arrays
+- **Array processing**: Flatten nested structures
+- **Aggregation prep**: Prepare data for SUM, AVG, etc.
+- **Data transformation**: Restructure array data
+
+## Related Functions
+
+- [sum](./sum.md) - Sum flattened values
+- [avg](./avg.md) - Average flattened values
+- [objectkeystoarray](./objectkeystoarray.md) - Extract object keys
+- [objectvaluestoarray](./objectvaluestoarray.md) - Extract object values
+
+## Notes
+
+- Critical for preparing data for aggregate functions
+- Works with both nested arrays and object arrays
+- Uses the Math service's `flatten` method
+- Commonly used in data pipelines