* more playground updates for jsonata

*

Author: DevNamedZed

examples/showcase/18-js-operators.ts

@@ -1,37 +1,40 @@
 // JavaScript Operator & Method Mapping
 //
-// The same logic as 17-intrinsics.ts, but written using standard
-// JavaScript operators and methods. The compiler recognizes these
-// patterns and maps them to the exact same ASL intrinsic functions.
+// Write standard JavaScript — the compiler maps operators and methods
+// to the appropriate ASL representation for your chosen query language.
 //
-// Compare the generated ASL output — it's identical!
+// JSONata mode (default):
+//   a + b              → native JSONata addition
+//   `${a} text ${b}`   → JSONata string concatenation with &
+//   str.split(delim)   → $split(str, delim)
+//   JSON.parse(str)    → $eval(str)
+//   JSON.stringify(obj) → $string(obj)
+//   arr.includes(val)  → val in arr
 //
-// See also 34-37 for JSONata-only methods (string, math, array,
-// and higher-order functions like map/filter/reduce).
-//
-// Mapping table:
+// JSONPath mode (--query-language jsonpath):
 //   a + b              → States.MathAdd(a, b)
-//   a - 5              → States.MathAdd(a, -5)
 //   `${a} text ${b}`   → States.Format('{} text {}', a, b)
 //   str.split(delim)   → States.StringSplit(str, delim)
 //   JSON.parse(str)    → States.StringToJson(str)
 //   JSON.stringify(obj) → States.JsonToString(obj)
 //   arr.includes(val)  → States.ArrayContains(arr, val)
+//
+// The TypeScript source is identical — only the ASL output differs.
 
 import { Steps, SimpleStepContext } from '../../packages/core/src/runtime/index';
 
 export const jsOperators = Steps.createFunction(
   async (context: SimpleStepContext, input: { orderId: string; price: number; tax: number; metadata: string }) => {
-    // Arithmetic using the + operator (same as Steps.add)
+    // Arithmetic → JSONata: native +, JSONPath: States.MathAdd
     const total = input.price + input.tax;
 
-    // String formatting using template literals (compiles to States.Format)
+    // Template literal → JSONata: & concat, JSONPath: States.Format
     const message = `Order ${input.orderId} confirmed, total: ${total}`;
 
-    // Generate a unique ID (no JS equivalent — Steps.uuid() is the only way)
+    // UUID — always States.UUID() in both backends
     const trackingId = Steps.uuid();
 
-    // Parse a JSON string using JSON.parse (same as Steps.jsonParse)
+    // JSON.parse → JSONata: $eval(), JSONPath: States.StringToJson
     const meta = JSON.parse(input.metadata);
 
     return {

examples/showcase/20-string-interpolation.ts

@@ -1,9 +1,14 @@
 // String Interpolation with Template Literals
 //
-// Write natural template strings — the compiler maps them to
-// States.Format intrinsic functions automatically.
+// Write natural template strings — the compiler maps them to the
+// appropriate ASL representation for your chosen query language.
 //
-// Mapping:
+// JSONata mode (default):
+//   `Hello ${name}`        → "Hello " & $name
+//   `${a} and ${b}`        → $a & " and " & $b
+//   `Total: ${a + b}`      → "Total: " & ($a + $b)
+//
+// JSONPath mode (--query-language jsonpath):
 //   `Hello ${name}`        → States.Format('Hello {}', name)
 //   `${a} and ${b}`        → States.Format('{} and {}', a, b)
 //   `Total: ${a + b}`      → States.Format('Total: {}', States.MathAdd(a, b))

examples/showcase/22-js-patterns.ts

@@ -1,11 +1,22 @@
 // Complete JavaScript Pattern Reference
 //
 // Every JS pattern the compiler maps to ASL, in one place.
+// The TypeScript source is identical regardless of backend —
+// only the ASL output differs.
 //
-// See also 34-37 for JSONata-only methods (string, math, array,
-// and higher-order functions like map/filter/reduce).
+// JSONata mode (default):
+//   a + b (numbers)       → native JSONata addition
+//   a - 5                 → native JSONata subtraction
+//   a * b, a / b, a % b   → native JSONata operators (JSONata only)
+//   `${a} text ${b}`      → JSONata & concatenation
+//   str.split(delim)      → $split(str, delim)
+//   JSON.parse(str)       → $eval(str)
+//   JSON.stringify(obj)   → $string(obj)
+//   arr.includes(val)     → val in arr
+//   arr.length            → $count(arr)
+//   Steps.uuid()          → States.UUID() (intrinsic in both)
 //
-// Mapping table:
+// JSONPath mode (--query-language jsonpath):
 //   a + b (numbers)       → States.MathAdd(a, b)
 //   a - 5 (literal right) → States.MathAdd(a, -5)
 //   `${a} text ${b}`      → States.Format('{} text {}', a, b)
@@ -15,6 +26,9 @@
 //   arr.includes(val)     → States.ArrayContains(arr, val)
 //   arr.length            → States.ArrayLength(arr)
 //   Steps.uuid()          → States.UUID()
+//
+// See also 34-37 for JSONata-only methods (string, math, array,
+// and higher-order functions like map/filter/reduce).
 
 import { Steps, SimpleStepContext } from '../../packages/core/src/runtime/index';
 
@@ -23,31 +37,31 @@ export const jsPatterns = Steps.createFunction(
     items: string[]; csv: string; data: string;
     price: number; tax: number; name: string
   }) => {
-    // Arithmetic: + → States.MathAdd
+    // Arithmetic: JSONata: native +, JSONPath: States.MathAdd
     const total = input.price + input.tax;
 
-    // Subtraction: - literal → States.MathAdd(a, -literal)
+    // Subtraction: JSONata: native -, JSONPath: States.MathAdd(a, -literal)
     const discounted = input.price - 5;
 
-    // Template literals → States.Format
+    // Template literals: JSONata: & concat, JSONPath: States.Format
     const message = `Hello ${input.name}, your total is ${total}`;
 
-    // String split → States.StringSplit
+    // String split: JSONata: $split(), JSONPath: States.StringSplit
     const parts = input.csv.split(',');
 
-    // JSON.parse → States.StringToJson
+    // JSON.parse: JSONata: $eval(), JSONPath: States.StringToJson
     const parsed = JSON.parse(input.data);
 
-    // JSON.stringify → States.JsonToString
+    // JSON.stringify: JSONata: $string(), JSONPath: States.JsonToString
     const serialized = JSON.stringify(parsed);
 
-    // Array includes → States.ArrayContains
+    // Array includes: JSONata: `in` operator, JSONPath: States.ArrayContains
     const hasItem = input.items.includes('special');
 
-    // Array length → States.ArrayLength
+    // Array length: JSONata: $count(), JSONPath: States.ArrayLength
     const count = input.items.length;
 
-    // Steps.uuid → States.UUID
+    // Steps.uuid: States.UUID() in both backends
     const id = Steps.uuid();
 
     return { total, discounted, message, parts, parsed, serialized, hasItem, count, id };

examples/starters/cdk/lib/batch-processing-stack.ts

@@ -67,7 +67,7 @@ export class BatchProcessingStack extends cdk.Stack {
 
           const resultKey = Steps.format('results/{}/output.json', input.batchId);
 
-          // Body simplified — JSON.stringify() is not supported by the compiler
+          // Body simplified — full JSON.stringify() compiles to $string() in JSONata mode
           await bucket.putObject({
             Key: resultKey,
             Body: input.batchId,

packages/core/src/compiler/generation/pathDialect.ts

@@ -15,7 +15,8 @@
 export interface PathDialect {
   /**
    * The QueryLanguage value for the top-level ASL definition.
-   * undefined means the default (JSONPath — no field emitted).
+   * undefined means no explicit QueryLanguage field (JSONPath mode).
+   * Note: JSONata is the compiler default; JSONPath is used when explicitly requested.
    */
   readonly queryLanguage: 'JSONPath' | 'JSONata' | undefined;
 
@@ -146,7 +147,7 @@ export interface PathDialect {
 }
 
 // ---------------------------------------------------------------------------
-// JSONPath dialect (default)
+// JSONPath dialect (used when queryLanguage: 'JSONPath' is explicitly set)
 // ---------------------------------------------------------------------------
 
 export class JsonPathDialect implements PathDialect {
@@ -362,7 +363,7 @@ export class JsonataDialect implements PathDialect {
   }
 }
 
-/** Singleton instance for the default JSONPath dialect. */
+/** Singleton instance for the JSONPath dialect. */
 export const JSON_PATH_DIALECT: PathDialect = new JsonPathDialect();
 
 /** Singleton instance for the JSONata dialect. */