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"