small doc and local runner fixes

Author: DevNamedZed

README.md

@@ -229,7 +229,7 @@ npx simplesteps compile workflow.ts -o output/ --query-language jsonpath
 | [CLI Reference](docs/cli.md) | `simplesteps compile` flags |
 | [Services](docs/services.md) | AWS service bindings + `Steps.awsSdk()` |
 | [Error Handling](docs/error-handling.md) | try/catch, retry, custom errors |
-| [Intrinsic Functions](docs/intrinsic-functions.md) | All 18 ASL intrinsics |
+| [Intrinsic Functions](docs/intrinsic-functions.md) | All 19 ASL intrinsics |
 | [Language Reference](docs/language-reference.md) | Every TypeScript construct mapped |
 | [Constants](docs/constants.md) | Compile-time constant folding |
 | [Limitations](docs/limitations.md) | Unsupported patterns and workarounds |

docs/intrinsic-functions.md

@@ -1,6 +1,6 @@
 # Intrinsic Functions
 
-SimpleSteps maps all 18 ASL intrinsic functions to TypeScript. **Write natural JavaScript** — the compiler handles the mapping. `Steps.*` methods are also available for direct access (useful in JSONPath mode or when no JS equivalent exists).
+SimpleSteps maps all 18 standard ASL intrinsic functions (plus the `States.ArraySlice` AWS extension) to TypeScript. **Write natural JavaScript** — the compiler handles the mapping. `Steps.*` methods are also available for direct access (useful in JSONPath mode or when no JS equivalent exists).
 
 ## Summary
 
@@ -22,6 +22,7 @@ SimpleSteps maps all 18 ASL intrinsic functions to TypeScript. **Write natural J
 | -- | `States.ArrayPartition` | `Steps.arrayPartition(arr, n)` |
 | -- | `States.ArrayRange` | `Steps.arrayRange(start, end, step)` |
 | -- | `States.ArrayUnique` | `Steps.arrayUnique(arr)` |
+| -- | `States.ArraySlice` | `Steps.arraySlice(arr, start, end)` |
 | -- | `States.Hash` | `Steps.hash(data, algorithm)` |
 | -- | `States.MathRandom` | `Steps.random(start, end)` |
 
@@ -75,9 +76,10 @@ const count = items.length;                 // States.ArrayLength($.items)
 const parts = csvLine.split(',');           // States.StringSplit($.csvLine, ',')
 
 // Steps.* only (no JS equivalent)
-const chunks = Steps.partition(items, 4);   // States.ArrayPartition($.items, 4)
-const indices = Steps.range(0, 100, 10);    // States.ArrayRange(0, 100, 10)
-const deduped = Steps.unique(items);        // States.ArrayUnique($.items)
+const chunks = Steps.arrayPartition(items, 4);   // States.ArrayPartition($.items, 4)
+const indices = Steps.arrayRange(0, 100, 10);    // States.ArrayRange(0, 100, 10)
+const deduped = Steps.arrayUnique(items);        // States.ArrayUnique($.items)
+const page = Steps.arraySlice(items, 0, 10); // States.ArraySlice($.items, 0, 10)
 ```
 
 ## Encoding

docs/language-reference.md

@@ -480,7 +480,7 @@ The context object is optional — if your workflow doesn't need execution metad
 
 ## Intrinsic Functions
 
-See [Intrinsic Functions](./intrinsic-functions.md) for all 18 ASL intrinsics and their JS mappings.
+See [Intrinsic Functions](./intrinsic-functions.md) for all 19 ASL intrinsics and their JS mappings.
 
 ## Error Handling
 

docs/limitations.md

@@ -418,11 +418,11 @@ For AWS services not covered by the built-in bindings:
 
 ```typescript
 const obj = await Steps.awsSdk<{ Bucket: string; Key: string }, { Body: string }>(
-  'S3', 'GetObject', { Bucket: 'my-bucket', Key: input.key }
+  's3', 'getObject', { Bucket: 'my-bucket', Key: input.key }
 );
 ```
 
-Compiles to `Resource: "arn:aws:states:::aws-sdk:s3:GetObject"`.
+Compiles to `Resource: "arn:aws:states:::aws-sdk:s3:getObject"`.
 
 ## Query Language Modes
 

docs/services.md

@@ -368,7 +368,7 @@ await Steps.awsSdk('ses', 'sendEmail', {
 });
 
 // Bedrock
-const response = await Steps.awsSdk<BedrockResponse>('bedrock', 'invokeModel', {
+const response = await Steps.awsSdk<BedrockParams, BedrockResponse>('bedrock', 'invokeModel', {
   ModelId: 'anthropic.claude-3-sonnet-20240229-v1:0',
   Body: JSON.stringify({ prompt: input.prompt }),
 });
@@ -502,26 +502,4 @@ export const workflow = Steps.createFunction(
 
 The activity ARN is used directly as the Task state `Resource`. Retry, timeout, and heartbeat options are supported.
 
----
-
-## Steps.awsSdk() — Direct SDK Integration
-
-For any AWS service not covered by typed bindings, use `Steps.awsSdk()`:
-
-```typescript
-const result = await Steps.awsSdk('s3', 'listObjectsV2', {
-  Bucket: input.bucket,
-  Prefix: 'data/',
-});
-
-// SNS example
-await Steps.awsSdk('sns', 'publish', {
-  TopicArn: 'arn:aws:sns:us-east-1:123:MyTopic',
-  Message: input.message,
-});
-```
-
-This compiles to `Resource: "arn:aws:states:::aws-sdk:s3:listObjectsV2"` with the parameters as Task `Arguments` (JSONata) or `Parameters` (JSONPath).
-
-The service and action arguments must be string literals (not variables) so the compiler can construct the ARN at compile time.
 

packages/cdk/src/index.ts

@@ -183,7 +183,7 @@ export class SimpleStepsStateMachine extends sfn.StateMachine {
       throw new Error(
         'Inline workflows require the SimpleSteps TypeScript transformer. ' +
         'Add the transformer to your build pipeline. ' +
-        'See: https://github.com/DevNamedZed/simplesteps#transformer-setup',
+        'See: https://github.com/DevNamedZed/simplesteps/blob/main/docs/cdk-integration.md',
       );
     }
 

packages/core/src/compiler/analysis/variableResolver.ts

@@ -661,6 +661,9 @@ const STEPS_TO_INTRINSIC: Record<string, string> = {
   arrayLength: 'States.ArrayLength',
   arrayUnique: 'States.ArrayUnique',
   arraySlice: 'States.ArraySlice',
+  partition: 'States.ArrayPartition',
+  unique: 'States.ArrayUnique',
+  range: 'States.ArrayRange',
   jsonParse: 'States.StringToJson',
   jsonStringify: 'States.JsonToString',
   merge: 'States.JsonMerge',
@@ -1079,6 +1082,9 @@ function resolveCallExpression(
             // JS replace() with string pattern replaces first occurrence only; $replace limit=1
             return { kind: 'intrinsic', path: `$replace(${baseStr}, ${patStr}, ${repStr}, 1)` };
           }
+          // Pattern or replacement couldn't be resolved (e.g. regex literal)
+          context.addError(expr, 'str.replace() requires string arguments. RegExp patterns are not supported.', ErrorCodes.Expr.UncompilableExpression.code);
+          return { kind: 'unknown' };
         }
         return jsonataOnlyError(context, expr, 'str.replace()');
       }
@@ -1257,6 +1263,12 @@ function resolveCallExpression(
         }
       }
 
+      // arr.reduce(fn) without initial value — specific error
+      if (methodName === 'reduce' && expr.arguments.length === 1) {
+        context.addError(expr, 'Array.reduce() requires an initial value in SimpleSteps. Use arr.reduce(fn, initialValue).', ErrorCodes.Expr.UncompilableExpression.code);
+        return { kind: 'unknown' };
+      }
+
       // arr.reduce(fn, init) → $reduce(arr, function($prev, $v) { expr }, init)
       if (methodName === 'reduce' && expr.arguments.length === 2) {
         const cbArg = expr.arguments[0];
@@ -1529,7 +1541,7 @@ function resolveJsonataStepsCall(
       if (serialized.length === 2) return { kind: 'intrinsic', path: `${serialized[0]} + ${serialized[1]}` };
       break;
     case 'random':
-      if (serialized.length === 2) return { kind: 'intrinsic', path: `$floor($random() * (${serialized[1]} - ${serialized[0]})) + ${serialized[0]}` };
+      if (serialized.length === 2) return { kind: 'intrinsic', path: `$floor($random() * (${serialized[1]} - ${serialized[0]} + 1)) + ${serialized[0]}` };
       break;
     case 'base64Encode':
       if (serialized.length === 1) return { kind: 'intrinsic', path: `$base64encode(${serialized[0]})` };
@@ -1549,6 +1561,7 @@ function resolveJsonataStepsCall(
       if (serialized.length === 1) return { kind: 'intrinsic', path: `$count(${serialized[0]})` };
       break;
     case 'arrayUnique':
+    case 'unique':
       if (serialized.length === 1) return { kind: 'intrinsic', path: `$distinct(${serialized[0]})` };
       break;
     case 'jsonParse':
@@ -1568,7 +1581,9 @@ function resolveJsonataStepsCall(
     // Keep as States.* intrinsics (no clean JSONata equivalent)
     case 'hash':
     case 'arrayPartition':
+    case 'partition':
     case 'arrayRange':
+    case 'range':
     case 'arraySlice': {
       const intrinsicName = STEPS_TO_INTRINSIC[methodName];
       if (intrinsicName) {
@@ -1652,6 +1667,7 @@ function resolveObjectLiteral(
     if (ts.isSpreadAssignment(prop)) {
       spreadArgs.push(resolveExpression(context, prop.expression, variables, dialect));
     } else {
+      context.addError(prop, 'Cannot mix spread and non-spread properties. Use either {...a, ...b} or {x: 1, y: 2}.', ErrorCodes.Expr.UncompilableExpression.code);
       return { kind: 'unknown' };
     }
   }

packages/local/src/choiceEvaluator.ts

@@ -111,8 +111,12 @@ function evaluateComparisonRule(
  * '*' matches zero or more characters. NOT a regex.
  */
 function stringMatches(value: string, pattern: string): boolean {
-  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
-  const regex = new RegExp('^' + escaped.replace(/\*/g, '.*') + '$');
+  // Handle \* escape sequences (literal asterisk) before general regex escaping
+  const PLACEHOLDER = '\x00STAR\x00';
+  const withPlaceholder = pattern.replace(/\\\*/g, PLACEHOLDER);
+  const escaped = withPlaceholder.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  const regexStr = escaped.replace(/\*/g, '.*').split(PLACEHOLDER).join('\\*');
+  const regex = new RegExp('^' + regexStr + '$');
   return regex.test(value);
 }
 

packages/local/src/interpreter.ts

@@ -99,6 +99,7 @@ export async function interpret(
     // Update per-state context
     context.State.Name = currentStateName;
     context.State.EnteredTime = new Date().toISOString();
+    context.State.RetryCount = 0;
 
     const start = Date.now();
     let result: StepResult;

packages/local/src/intrinsics.ts

@@ -83,6 +83,7 @@ type IntrinsicArg =
   | { type: 'string'; value: string }
   | { type: 'number'; value: number }
   | { type: 'boolean'; value: boolean }
+  | { type: 'null'; value: null }
   | { type: 'call'; value: IntrinsicCall };
 
 function parseIntrinsicCall(expr: string): IntrinsicCall {
@@ -185,11 +186,14 @@ function parseArgList(str: string, start: number): { args: IntrinsicArg[]; end:
     } else if (ch === 'f' && str.startsWith('false', i)) {
       args.push({ type: 'boolean', value: false });
       i += 5;
+    } else if (ch === 'n' && str.startsWith('null', i)) {
+      args.push({ type: 'null', value: null });
+      i += 4;
     } else if (ch === '-' || ch === '+' || (ch >= '0' && ch <= '9')) {
       // Number literal
       let j = i;
       if (ch === '-' || ch === '+') j++;
-      while (j < str.length && ((str[j] >= '0' && str[j] <= '9') || str[j] === '.')) j++;
+      while (j < str.length && ((str[j] >= '0' && str[j] <= '9') || str[j] === '.' || str[j] === 'e' || str[j] === 'E' || ((str[j] === '+' || str[j] === '-') && (str[j-1] === 'e' || str[j-1] === 'E')))) j++;
       args.push({ type: 'number', value: parseFloat(str.slice(i, j)) });
       i = j;
     } else if (ch === ',') {
@@ -217,6 +221,7 @@ function resolveArg(arg: IntrinsicArg, stateData: any, context: ContextObject):
     case 'string': return arg.value;
     case 'number': return arg.value;
     case 'boolean': return arg.value;
+    case 'null': return null;
     case 'path': return resolveReference(arg.value, stateData, context);
     case 'call': return evaluateCall(arg.value, stateData, context);
   }
@@ -236,11 +241,12 @@ function evaluateCall(call: IntrinsicCall, stateData: any, context: ContextObjec
     case 'States.ArrayGetItem': return args[0][args[1]];
     case 'States.ArrayLength': return args[0].length;
     case 'States.ArrayUnique': return statesArrayUnique(args[0]);
+    case 'States.ArraySlice': return (args[0] as any[]).slice(args[1] as number, args[2] as number);
     case 'States.Base64Encode': return base64Encode(args[0]);
     case 'States.Base64Decode': return base64Decode(args[0]);
     case 'States.Hash': return computeHash(args[1], args[0]);
     case 'States.JsonMerge': return statesJsonMerge(args[0], args[1], args[2]);
-    case 'States.MathRandom': return Math.floor(Math.random() * (args[1] - args[0])) + args[0];
+    case 'States.MathRandom': return Math.floor(Math.random() * (args[1] - args[0] + 1)) + args[0];
     case 'States.MathAdd': return args[0] + args[1];
     case 'States.StringSplit': return args[1] === '' ? [...args[0]] : args[0].split(args[1]);
     case 'States.UUID': return getRandomUUID();
@@ -256,10 +262,19 @@ function evaluateCall(call: IntrinsicCall, stateData: any, context: ContextObjec
 function statesFormat(args: any[]): string {
   const template = args[0] as string;
   let argIndex = 1;
-  return template.replace(/\{}/g, () => {
-    const val = args[argIndex++];
-    return val === undefined ? '' : String(val);
-  });
+  let result = '';
+  for (let i = 0; i < template.length; i++) {
+    if (template[i] === '\\' && i + 1 < template.length && (template[i + 1] === '{' || template[i + 1] === '}')) {
+      result += template[++i];
+    } else if (template[i] === '{' && i + 1 < template.length && template[i + 1] === '}') {
+      const val = args[argIndex++];
+      result += val === undefined ? '' : String(val);
+      i++; // skip }
+    } else {
+      result += template[i];
+    }
+  }
+  return result;
 }
 
 function statesJsonMerge(a: any, b: any, deep?: boolean): any {
@@ -298,6 +313,7 @@ function statesArrayContains(arr: any[], value: any): boolean {
 }
 
 function statesArrayRange(start: number, end: number, step: number): number[] {
+  if (step === 0) throw new Error('States.ArrayRange: step must not be zero');
   const result: number[] = [];
   if (step > 0) {
     for (let i = start; i <= end; i += step) result.push(i);