public interface StatePath

A path expression identifying a value in a nested Object such as Process.state, used both to read a value (as a getter) and to specify where and how a value is written (as a setter).

A StatePath is a dot-delimited list of segments, where each segment is a property name, optionally followed by an operator:

When the path is used as a getter, any segment may end in [<index>] to extract that element of an Array.
When the path is used as a setter, the last segment may end in one of:
- [] – append to an Array (creates the Array if missing)
- {} – shallow merge into an Object, overwriting existing keys
- {?} – shallow merge into an Object, preserving existing keys (non-clobbering)
Array indexes are not supported in setter paths: "a[0].b" sets a property literally named "a[0]".

This syntax is used in Task.setState()/Process.setStateVariable() and Task.getState()/Task.getInputRecord()/Process.getStateVariable().

Missing intermediate objects are created as needed unless strictPaths is set, either in the specific API call or on the task or process involved. When strictPaths is enabled, a missing intermediate segment throws an error instead, as does a missing target for an [], {} or {?} operator. The final segment of a plain setter path is always created or replaced.

Examples

Assume process.state starts as:

  {
      currentDS: {
          fields: [ { name:"orderId", type:"integer" } ],
          defaults: { timezone:"UTC" }
      }
  }

Append
"currentDS.fields[]": { name:"orderDate", type:"date" }
Result: fields gains a new element at the end.
Merge (clobber)
"currentDS.defaults{}": { timezone:"PST", dateFormat:"YYYY-MM-DD" }
Result: timezone is overwritten to "PST"; dateFormat is added.
Merge (non-clobber)
"currentDS.defaults{?}": { timezone:"PST", locale:"en-US" }
Result: existing timezone:"UTC" is preserved; locale is added.
Get default timezone
"currentDS.defaults.timezone"
Result: "UTC"
Get first field type
"currentDS.fields[0].type"
Result: "integer"

Interface StatePath

Examples