- TypeScript-to-ASL compiler now supports JSONata as the default query language

- Standard JS methods compile directly: string manipulation, math, type conversion, object utilities
- Higher-order array functions (map, filter, reduce, find, some, every) with pure callbacks compile to JSONat lambdas
- Full arithmetic support: *, /, %, - work natively (previously JSONPath-only limitation)
- JSONPath still fully supported via --query-language jsonpath flag, no regressions
- Clear error messages when JSONata-only features are used in JSONPath mode
- All documentation and examples updated for dual-mode support

Author: DevNamedZed

README.md

@@ -3,15 +3,15 @@
 [![CI](https://github.com/DevNamedZed/simplesteps/actions/workflows/ci.yml/badge.svg)](https://github.com/DevNamedZed/simplesteps/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-TypeScript-to-ASL compiler for AWS Step Functions. Define workflows as typed async functions, compile to Amazon States Language with full data flow inference, and deploy with CDK or the CLI.
+TypeScript-to-ASL compiler for AWS Step Functions. Define workflows as typed async functions, compile to Amazon States Language with full data flow inference, and deploy with CDK or the CLI. Supports both JSONata (default) and JSONPath query languages.
 
 [Playground](https://devnamedzed.github.io/simplesteps/) | [Getting Started](docs/getting-started.md) | [CDK Integration](docs/cdk-integration.md) | [Language Reference](docs/language-reference.md)
 
 ## Motivation
 
 At my previous company we had dozens of Step Functions deployed with CDK. They were incredibly hard to read and maintain. The CDK approach defines a program by stringing together a tree of construct objects — `.next().next().next()` chains with raw JSONPath and `sfn.CustomState` workarounds. That's exactly the kind of work a compiler should handle.
 
-SimpleSteps compiles typed async functions to ASL state machines. The compiler performs whole-program data flow analysis and derives all JSONPath expressions (`Parameters`, `ResultPath`, `InputPath`, `ResultSelector`) from variable usage. Service bindings are resolved at compile time, with CDK token substitution at synth time.
+SimpleSteps compiles typed async functions to ASL state machines. The compiler performs whole-program data flow analysis and derives all data flow fields from variable usage — you never write path expressions. In JSONata mode (the default), standard JavaScript methods like `Math.round()`, `str.toUpperCase()`, and `arr.filter()` compile directly to JSONata built-ins. Service bindings are resolved at compile time, with CDK token substitution at synth time.
 
 **Input:**
 
@@ -31,7 +31,31 @@ export const helloWorld = Steps.createFunction(
 );
 ```
 
-**Output:**
+**Output (JSONata — default):**
+
+```json
+{
+  "QueryLanguage": "JSONata",
+  "StartAt": "Invoke_helloFn",
+  "States": {
+    "Invoke_helloFn": {
+      "Type": "Task",
+      "Resource": "arn:aws:lambda:us-east-1:123456789:function:Hello",
+      "Arguments": { "name": "{% $states.input.name %}" },
+      "Assign": { "result": "{% $states.result %}" },
+      "Next": "Return_Result"
+    },
+    "Return_Result": {
+      "Type": "Pass",
+      "Arguments": { "greeting": "{% $result.greeting %}" },
+      "End": true
+    }
+  }
+}
+```
+
+<details>
+<summary>JSONPath output (--query-language jsonpath)</summary>
 
 ```json
 {
@@ -53,6 +77,8 @@ export const helloWorld = Steps.createFunction(
 }
 ```
 
+</details>
+
 ## Quick Start
 
 ### CDK
@@ -125,6 +151,9 @@ Workflows can also be defined in [separate files](docs/cdk-integration.md) using
 ```bash
 npm install @simplesteps/core
 npx simplesteps compile workflow.ts -o output/
+
+# Use JSONPath mode instead of JSONata (default)
+npx simplesteps compile workflow.ts -o output/ --query-language jsonpath
 ```
 
 ## Language Support
@@ -145,14 +174,34 @@ npx simplesteps compile workflow.ts -o output/
 | `return value` | Succeed / End state |
 | `try { ... } catch (e) { ... }` | Catch rules |
 | `.call(input, { retry, timeoutSeconds, heartbeatSeconds })` | Retry / Timeout / Heartbeat |
-| `` `Hello ${name}` `` | `States.Format` |
-| `a + b` (numbers) | `States.MathAdd` |
-| `str.split(',')` | `States.StringSplit` |
-| `JSON.parse(str)` | `States.StringToJson` |
-| `Steps.uuid()` / `crypto.randomUUID()` | `States.UUID` |
+| `` `Hello ${name}` `` | `States.Format` / string concatenation |
+| `a + b`, `a * b`, `a - b`, `a / b`, `a % b` | Native arithmetic (JSONata) / `States.MathAdd` (JSONPath) |
+| `str.split(',')` | `$split()` / `States.StringSplit` |
+| `JSON.parse(str)` | `$eval()` / `States.StringToJson` |
+| `Steps.uuid()` / `crypto.randomUUID()` | `$uuid()` / `States.UUID` |
+
+### JSONata-Only Methods (default mode)
+
+| TypeScript | JSONata |
+|---|---|
+| `str.toUpperCase()`, `.toLowerCase()`, `.trim()` | `$uppercase`, `$lowercase`, `$trim` |
+| `str.substring()`, `.replace()`, `.charAt()`, `.repeat()` | `$substring`, `$replace`, `$pad` |
+| `str.startsWith()`, `.endsWith()`, `.padStart()`, `.padEnd()` | Composed expressions |
+| `Math.floor/ceil/round/abs/pow/sqrt/min/max/random` | `$floor`, `$ceil`, `$round`, `$abs`, `$power`, `$sqrt`, `$min`, `$max`, `$random` |
+| `Number()`, `String()`, `Boolean()`, `typeof` | `$number`, `$string`, `$boolean`, `$type` |
+| `Object.keys()`, `Object.values()` | `$keys`, `$lookup` |
+| `Date.now()`, `Array.isArray()` | `$millis`, `$type(x) = 'array'` |
+| `arr.join()`, `.reverse()`, `.sort()`, `.concat()` | `$join`, `$reverse`, `$sort`, `$append` |
+| `arr.map(v => expr)` | `$map(arr, function($v) { expr })` |
+| `arr.filter(v => pred)` | `$filter(arr, function($v) { pred })` |
+| `arr.reduce((a, v) => e, init)` | `$reduce(arr, function($a, $v) { e }, init)` |
+| `arr.find()`, `.some()`, `.every()` | Composed from `$filter` + `$count` |
 
 ## Compiler Features
 
+- **Dual query language support** — JSONata (default) and JSONPath, switchable via `--query-language`
+- **55+ JS method → JSONata mappings** — string, math, array, type conversion, and higher-order functions compile directly
+- **Lambda expression analysis** — pure callbacks in `.map()`, `.filter()`, `.reduce()` auto-compile to JSONata higher-order functions
 - **Whole-program data flow analysis** with constant propagation lattice across modules
 - **Cross-file import resolution** with demand-driven analysis and cycle detection
 - **Pure function inlining** for compile-time constant derivation
@@ -180,7 +229,7 @@ npx simplesteps compile workflow.ts -o output/
 ## Examples
 
 - [Starter projects](examples/starters/) — CLI, library API, and CDK templates
-- [Showcase](examples/showcase/) — 30+ examples covering every language feature
+- [Showcase](examples/showcase/) — 38 examples covering every language feature, including JSONata methods
 
 ## License
 

docs/cli.md

@@ -15,6 +15,7 @@ simplesteps compile <file-or-tsconfig> [options]
 | Flag | Description | Default |
 |---|---|---|
 | `-o, --output <dir>` | Write `.asl.json` files to this directory | stdout |
+| `--query-language <jsonata\|jsonpath>` | ASL query language | `jsonata` |
 | `--indent <N>` | JSON indentation spaces | `2` |
 | `-v, --verbose` | Verbose output | off |
 | `-h, --help` | Show help | |
@@ -33,6 +34,9 @@ npx simplesteps compile tsconfig.json -o dist/
 
 # Custom indentation
 npx simplesteps compile src/workflow.ts --indent 4
+
+# Compile with JSONPath instead of JSONata (default)
+npx simplesteps compile src/workflow.ts --query-language jsonpath
 ```
 
 ## Input Detection

docs/getting-started.md

@@ -123,9 +123,12 @@ export const orderWorkflow = Steps.createFunction(
 
 ```bash
 npx simplesteps compile workflows/order.ts -o output/
+
+# Use JSONPath instead of JSONata (the default)
+npx simplesteps compile workflows/order.ts -o output/ --query-language jsonpath
 ```
 
-This produces `output/orderWorkflow.asl.json` — useful for reviewing the generated state machine before deploying.
+This produces `output/orderWorkflow.asl.json` — useful for reviewing the generated state machine before deploying. The default query language is JSONata, which supports richer expressions (arithmetic, string methods, Math functions, higher-order array functions). Use `--query-language jsonpath` if you need the original ASL query language.
 
 ## Next Steps
 

docs/intrinsic-functions.md

@@ -53,7 +53,7 @@ count += 5;                   // States.MathAdd($.count, 5)
 count -= 3;                   // States.MathAdd($.count, -3)
 ```
 
-Multiplication, division, and modulo are **not supported** -- ASL only provides `States.MathAdd`.
+In **JSONPath mode**, multiplication, division, and modulo are not supported — ASL only provides `States.MathAdd`. In **JSONata mode** (the default), all arithmetic operators work natively: `*`, `/`, `%`, `-`, `+`.
 
 ## JSON (`States.StringToJson` / `States.JsonToString`)
 

docs/language-reference.md

@@ -23,6 +23,62 @@ Every TypeScript construct supported by SimpleSteps and its ASL mapping.
 | `if (e instanceof TimeoutError)` | Typed error matching |
 | `.call(input, { retry, timeoutSeconds, heartbeatSeconds })` | Retry / Timeout / Heartbeat |
 
+## Query Language
+
+SimpleSteps supports two ASL query languages. JSONata is the default and recommended mode.
+
+### JSONata (default)
+
+JSONata provides native arithmetic, string manipulation, type conversion, higher-order array functions, and more — most JavaScript patterns compile directly:
+
+```typescript
+// Arithmetic — all operators work
+const total = price * quantity;
+const tax = total * 0.08;
+const discounted = total - discount;
+
+// String methods → $uppercase, $lowercase, $trim, $substring, $pad, $replace
+const upper = name.toUpperCase();
+const trimmed = raw.trim();
+const first5 = text.substring(0, 5);
+const padded = id.padStart(10, '0');
+
+// Math functions → $floor, $ceil, $round, $abs, $power, $sqrt, $min, $max, $random
+const rounded = Math.round(amount);
+const clamped = Math.min(value, 100);
+
+// Type conversion → $number, $string, $boolean, $type, $millis
+const num = Number(input.text);
+const keys = Object.keys(config);
+const priceType = typeof input.price;
+const now = Date.now();
+const isArr = Array.isArray(input.items);
+
+// Array methods → $join, $reverse, $sort, $append
+const sorted = items.sort();
+const csv = items.join(', ');
+
+// Higher-order functions → $map, $filter, $reduce
+const names = items.map(item => item.name);
+const active = items.filter(item => item.active);
+const total = items.reduce((sum, item) => sum + item.price, 0);
+const found = items.find(item => item.id === targetId);
+const hasActive = items.some(item => item.active);
+const allValid = items.every(item => item.valid);
+```
+
+Higher-order functions require pure expression callbacks (no `await`). For callbacks with service calls, use `Steps.map()` instead (see below).
+
+### JSONPath
+
+The original ASL query language. Use `queryLanguage: 'JSONPath'` to opt in:
+
+```typescript
+compile({ sourceFiles: ['workflow.ts'], queryLanguage: 'JSONPath' });
+```
+
+JSONPath mode has more restrictions — no arithmetic beyond addition, no string/Math methods. See [Limitations](./limitations.md) for details.
+
 ## Entry Points
 
 ### `Steps.createFunction()`
@@ -257,17 +313,16 @@ Substeps can contain any supported control flow: `if/else`, `try/catch`, loops,
 
 See [Limitations](./limitations.md#substeps) for constraints.
 
-## Automatic Data Flow (No JSONPath)
+## Automatic Data Flow
 
-One of SimpleSteps' key design goals: **you never write JSONPath or data flow fields**. The compiler derives all of them from your variable usage.
+One of SimpleSteps' key design goals: **you never write path expressions or data flow fields**. The compiler derives all of them from your variable usage.
 
-| ASL Field | Derived From |
-|---|---|
-| `Parameters` | Service call arguments — the compiler maps each argument to a `"field.$": "$.variable"` reference |
-| `ResultPath` | Variable assignment — `const x = await svc.call(...)` stores the result at `$.x` |
-| `InputPath` | Variable references in service call arguments — the compiler determines what data the state needs |
-| `ResultSelector` | Automatic `.Payload` extraction for Lambda results (so you access `result.field`, not `result.Payload.field`) |
-| `OutputPath` | *Not yet implemented* — planned optimization for payload size reduction via variable liveness analysis |
+In **JSONata mode** (default), the compiler emits `Arguments` with `{% %}` expressions. In **JSONPath mode**, it emits `Parameters` with `"field.$": "$.variable"` references. Either way, you write plain TypeScript:
+
+| Your Code | JSONata ASL | JSONPath ASL |
+|---|---|---|
+| `await svc.call({ id: x.id })` | `Arguments: { id: "{% $x.id %}" }` | `Parameters: { "id.$": "$.x.id" }` |
+| `const x = await svc.call(...)` | `Assign: { x: "{% $states.result %}" }` | `ResultPath: "$.x"` |
 
 In CDK, you'd write `sfn.JsonPath.stringAt('$.order.total')` and manually set `outputPath: '$.Payload'`. In SimpleSteps, you write `order.total` and the compiler handles the rest.
 

docs/library-api.md

@@ -39,6 +39,7 @@ interface CompileOptions {
   sourceFiles?: string[];      // Specific files to compile
   cwd?: string;                // Working directory (default: process.cwd())
   substitutions?: Record<string, unknown>;  // Deploy-time value overrides
+  queryLanguage?: 'JSONata' | 'JSONPath';   // ASL query language (default: 'JSONata')
 }
 ```