Skip to main content

Interface: DataConverter

common.DataConverter

When your data (arguments and return values) is sent over the wire and stored by Temporal Server, it is encoded in binary in a Payload Protobuf message.

The default DataConverter supports undefined, Uint8Array, and JSON serializables (so if JSON.stringify(yourArgOrRetval) works, the default data converter will work). Protobufs are supported via this API.

Use a custom DataConverter to control the contents of your Payloads. Common reasons for using a custom DataConverter are:

  • Converting values that are not supported by the default DataConverter (for example, JSON.stringify() doesn't handle BigInts, so if you want to return { total: 1000n } from a Workflow, Signal, or Activity, you need your own DataConverter).
  • Encrypting values that may contain private information that you don't want stored in plaintext in Temporal Server's database.
  • Compressing values to reduce disk or network usage.

To use your custom DataConverter, provide it to the WorkflowClient, Worker, and bundleWorkflowCode (if you use it):

  • new WorkflowClient({ ..., dataConverter })
  • Worker.create({ ..., dataConverter })
  • bundleWorkflowCode({ ..., payloadConverterPath })

Properties​

externalStorage​

• Optional externalStorage: ExternalStorage

Configuration for offloading Payloads to external storage instead of sending them inline to Temporal Server.

When set, Payloads whose size exceeds ExternalStorage.payloadSizeThreshold are written to one of the configured StorageDrivers and replaced on the wire by a small reference; they are transparently retrieved again on the receiving side.

failureConverterPath​

• Optional failureConverterPath: string

Path of a file that has a failureConverter named export. failureConverter should be an object that implements FailureConverter. If no path is provided, defaultFailureConverter is used.

payloadCodecs​

• Optional payloadCodecs: PayloadCodec[]

An array of PayloadCodec instances.

Payloads are encoded in the order of the array and decoded in the opposite order. For example, if you have a compression codec and an encryption codec, then you want data to be encoded with the compression codec first, so you'd do payloadCodecs: [compressionCodec, encryptionCodec].

payloadConverterPath​

• Optional payloadConverterPath: string

Path of a file that has a payloadConverter named export. payloadConverter should be an object that implements PayloadConverter. If no path is provided, defaultPayloadConverter is used.