aws_stepfunction_tasks: BatchSubmitJob task doesn't support JSONata expression for arraySize

[shatgupt]

Describe the bug

I want to define the arraySize, which is currently of type number, using a field in the task input. It is possible to use a JsonPath expression while still satisfying type-check by using JsonPath.numberAt()

arraySize: JsonPath.numberAt('$.fspArrayBatchSize'),

But there doesn't seem to be a way to do the same when using a JSONata expression.

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Version

No response

Expected Behavior

A JSONata expression equivalent to above JsonPath expression should also work.

arraySize: '{% $states.input.fspArrayBatchSize %}'),

Current Behavior

The following code throws compilation error since the JSONata expression is of type string whereas the construct is expecting a number for arraySize.

arraySize: '{% $states.input.fspArrayBatchSize %}'),

Reproduction Steps

Try creating a Batch job task like below

aws_stepfunctions_tasks.BatchSubmitJob.jsonata(this, 'FSPBatchJob', {
      jobName: props.fsp.batchJobName,
      jobDefinitionArn: props.fsp.batchJobName,
      jobQueueArn: props.fspBatchJobQueue.jobQueueArn,
      arraySize: '{% $states.input.fspArrayBatchSize %}',
    });

Possible Solution

Quick options I can think of:

1. Convert arraySize to string but lose type check
2. Add a static method similar to JsonPath which satisfies type-check, Jsonata.number('$states.input.fspArrayBatchSize')

Additional Information/Context

Workaround is to suppress type-check for that line. Verified by building, deploying and running a statemachine with below task.

aws_stepfunctions_tasks.BatchSubmitJob.jsonata(this, 'FSPBatchJob', {
      jobName: props.fsp.batchJobName,
      jobDefinitionArn: props.fsp.batchJobName,
      jobQueueArn: props.fspBatchJobQueue.jobQueueArn,
      // @ts-expect-error: CDK arraySize type is currently number
      arraySize: '{% $states.input.fspArrayBatchSize %}',
    });

CDK CLI Version

2.176.0 (build 899965d)

Framework Version

No response

Node.js Version

v20.17.0

OS

Mac Sequoia 15.4

Language

TypeScript

Language Version

5.0.4

Other information

No response

[pahud]

Hi @shatgupt,

Thanks for raising this issue and providing clear details and reproduction steps.

You're correct that there's an inconsistency in how dynamic values can be provided for the arraySize property in the BatchSubmitJob task when using JsonPath versus JSONata.

Summary:
The arraySize property in BatchSubmitJobProps is strictly typed as number. While JsonPath.numberAt() provides a way to satisfy this type check while using a JsonPath expression, there is no equivalent helper function for JSONata expressions. This leads to a TypeScript compilation error when you try to assign a JSONata string directly to arraySize.

Root Cause:
The core issue stems from the type definition in the BatchSubmitJobOptions interface, specifically readonly arraySize?: number;. This type is inherited by BatchSubmitJobJsonataProps. The lack of a Jsonata.numberAt() equivalent means there's no standard way to pass a JSONata expression for a numeric field without triggering a type error. You can find the relevant code in the BatchSubmitJob class definition and its associated interfaces.

Possible Solution:
As you suggested, introducing a helper function similar to JsonPath.numberAt(), perhaps named Jsonata.numberAt() or similar, seems like the best approach. This would provide parity with JsonPath and allow type-safe usage of JSONata expressions for numeric properties.

// Example of potential usage 
const batchJob = new tasks.BatchSubmitJob(this, 'FSPBatchJob', { 
  // … other props 
 // Proposed solution: 
arraySize: sfn.Jsonata.numberAt('$states.input.fspArrayBatchSize'), 
// Or similar syntax 
// This would require adding the 'numberAt' static method to the Jsonata helpers
});

We appreciate you identifying this gap! Contributions are always welcome.