cxtms 1.9.21 → 1.9.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cxtms",
-  "version": "1.9.21",
+  "version": "1.9.22",
   "description": "Schema validation package for CXTMS YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/cxtms-workflow-builder/ref-expressions-ncalc.md

@@ -4,8 +4,8 @@
 - NCalc expression syntax `[variable]` (in conditions and expression directives)
 - Operators (comparison, logical, arithmetic, ternary, membership)
 - Iterator variables (`[each.*]` and `[item.*]`)
-- Collection functions (any, all, count, sum, first, last, distinct, groupBy, join, etc.)
-- String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, etc.)
+- Collection functions (any, all, count, sum, first, last, distinct, select, zip, groupBy, join, etc.)
+- String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, coalesce, etc.)
 - Date functions (now, parseDate, addDays, formatDate, dateFromUnix, etc.)
 - Math functions (Abs, Ceiling, Floor, Round, Min, Max, etc.)
 - Domain functions (convertWeight, convertDimension)
@@ -28,6 +28,7 @@ conditions:
 - Numeric strings are auto-converted to `decimal` when needed (e.g., `[price] > 100` works even if price is the string `"150"`)
 - Dot paths resolve deep: `[Activity.Step.output.nested.field]`
 - Optional suffix `?` prevents errors: `[order.customer?.name?]`
+- Wildcard traversal continues through POCOs, dictionaries, and `JObject` values, for example `[items[*].customValues.chapter_en?]`
 
 ### Operators
 
@@ -42,14 +43,14 @@ conditions:
 ### Iterator Variables
 
 Functions use two iterator variable names:
-- **`[each.*]`** -- used by: `any`, `all`, `sum`, `join` (3-arg)
+- **`[each.*]`** -- used by: `any`, `all`, `sum`, `select`, `join` (3-arg), and projections over `zip(...)` output
 - **`[item.*]`** -- used by: `first`, `last`, `groupBy`
 
 ### Collection Functions
 
 | Function | Description |
 |----------|-------------|
-| `any([items], [each.prop] = 'val')` | True if any item matches expression. Without expression: checks if collection contains the value |
+| `any([items], [each.prop] = 'val')` | True if any item matches expression. Without expression: checks if collection contains the value. Returns `false` for empty collections |
 | `all([items], [each.prop] > 0)` | True if all items match. Returns `false` for null/empty collections |
 | `count([items])` | Count items in list or JToken. Returns `0` for non-collections |
 | `sum([items], [each.amount])` | Sum values as `decimal`. Optional `[each.*]` accessor. Skips nulls |
@@ -63,6 +64,8 @@ Functions use two iterator variable names:
 | `groupBy([items], [item.cat])` | Group by one or more key expressions. Returns `[{key, items}]`. Multi-key: keys joined with `\|` |
 | `join([items], [each.name], ',')` | Join collection with `[each.*]` accessor and separator (3-arg) |
 | `join([items], ',')` | Join collection directly with separator (2-arg) |
+| `select([items], [each.field])` | Project each item via `[each.*]` accessor. Returns flat `List<object>` of projected values. Empty input → empty list |
+| `zip([a], [b])` | Pair elements from two or more lists into `[{item1, item2}, ...]`. Custom keys: `zip([a], [b], 'name', 'code')`. Variadic: accepts N lists. Truncates to shortest list. Returns empty list if any input is empty/null. Falls back to `item1`, `item2`, ... when custom key count does not match list count |
 | `split([str], ' ')` | Split string by first character of separator. Returns `List<string>` |
 | `elementAt([items], 0)` | Get element at index (zero-based) from list |
 
@@ -82,6 +85,8 @@ Functions use two iterator variable names:
 | `bool([value])` | Convert to boolean: null->`false`, empty string->`false`, "true"/"false"->parsed, non-zero number->`true`, any object->`true` |
 | `transliterate([value])` | Unicode to ASCII (Unidecode). Returns `""` for null |
 | `transliterateUa([value])` | Ukrainian-specific transliteration. Returns `""` for null |
+| `coalesce([a], [b], 'default')` | First non-null, non-empty/whitespace argument. Variadic. `0` and `false` are kept (not skipped). Returns `null` if all args are null/empty |
+| `prop([obj], 'path.to.field')` | Drill into an object by a runtime-computed string path. Supports dotted paths and `?` optional suffix, same as `[obj.path]` but the path is a string argument |
 | `parseAddress([address])` | Parse address -> `{StreetNumber, StreetName}`. Handles US and EU formats |
 
 ### Date Functions

package/skills/cxtms-workflow-builder/ref-expressions-template.md

@@ -152,6 +152,7 @@ Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
 | `list[0]` | Array index | `items[0]` |
 | `list[^1]` | Index from end (last item) | `items[^1]` |
 | `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
+| `list[*].dictKey` | Wildcard traversal into Dictionary/JObject keys | `items[*].customValues.chapter_en` |
 | `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
 | `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
 | `list[condition]` | Filter by condition | `items[status=Active]` |
@@ -159,3 +160,7 @@ Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
 | `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
 | `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
 | `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |
+
+**Wildcard traversal into Dictionary/JObject**: After `[*]`, subsequent path segments drill into Dictionary keys and JObject properties on each item. Dictionary-like values are preserved intact (not flattened) so multi-hop paths work: `items[*].customValues.chapter_en` extracts the `chapter_en` key from each item's `customValues` dictionary. This also works with nested dictionaries (`items[*].meta.locale.name`) and JObject items from JSON payloads.
+
+**JArray primitive unwrapping**: When `GetPropertyValue` encounters a JArray where every element is a JValue (primitive), it automatically unwraps the array into a `List<object>` of plain .NET values. This ensures downstream iteration (e.g., `select()`, `zip()`, `foreach`) works with primitives rather than JValue wrappers.