@temporalio/common 1.1.0 → 1.4.0

package/lib/activity-options.d.ts

@@ -0,0 +1,138 @@
+import type { coresdk } from '@temporalio/proto';
+import { RetryPolicy } from './retry-policy';
+export declare enum ActivityCancellationType {
+    TRY_CANCEL = 0,
+    WAIT_CANCELLATION_COMPLETED = 1,
+    ABANDON = 2
+}
+/**
+ * Options for remote activity invocation
+ */
+export interface ActivityOptions {
+    /**
+     * Identifier to use for tracking the activity in Workflow history.
+     * The `activityId` can be accessed by the activity function.
+     * Does not need to be unique.
+     *
+     * @default an incremental sequence number
+     */
+    activityId?: string;
+    /**
+     * Task queue name.
+     *
+     * @default current worker task queue
+     */
+    taskQueue?: string;
+    /**
+     * Heartbeat interval. Activity must heartbeat before this interval passes after a last heartbeat or activity start.
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    heartbeatTimeout?: string | number;
+    /**
+     * RetryPolicy that define how activity is retried in case of failure. If this is not set, then the server-defined default activity retry policy will be used. To ensure zero retries, set maximum attempts to 1.
+     */
+    retry?: RetryPolicy;
+    /**
+     * Maximum time of a single Activity execution attempt.
+  Note that the Temporal Server doesn't detect Worker process failures directly. It relies on this timeout to detect that an Activity that didn't complete on time. So this timeout should be as short as the longest possible execution of the Activity body. Potentially long running Activities must specify {@link heartbeatTimeout} and call {@link activity.Context.heartbeat} periodically for timely failure detection.
+  
+     * Either this option or {@link scheduleToCloseTimeout} is required.
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    startToCloseTimeout?: string | number;
+    /**
+     * Time that the Activity Task can stay in the Task Queue before it is picked up by a Worker. Do not specify this timeout unless using host specific Task Queues for Activity Tasks are being used for routing.
+     * `scheduleToStartTimeout` is always non-retryable. Retrying after this timeout doesn't make sense as it would just put the Activity Task back into the same Task Queue.
+     * @default unlimited
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    scheduleToStartTimeout?: string | number;
+    /**
+     * Total time that a workflow is willing to wait for Activity to complete.
+     * `scheduleToCloseTimeout` limits the total time of an Activity's execution including retries (use {@link startToCloseTimeout} to limit the time of a single attempt).
+     *
+     * Either this option or {@link startToCloseTimeout} is required
+     * @default unlimited
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    scheduleToCloseTimeout?: string | number;
+    /**
+     * Determines what the SDK does when the Activity is cancelled.
+     * - `TRY_CANCEL` - Initiate a cancellation request and immediately report cancellation to the workflow.
+     * - `WAIT_CANCELLATION_COMPLETED` - Wait for activity cancellation completion. Note that activity must heartbeat to receive a
+     *   cancellation notification. This can block the cancellation for a long time if activity doesn't
+     *   heartbeat or chooses to ignore the cancellation request.
+     * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
+     */
+    cancellationType?: ActivityCancellationType;
+    /**
+     * Eager dispatch is an optimization that improves the throughput and load on the server for scheduling Activities.
+     * When used, the server will hand out Activity tasks back to the Worker when it completes a Workflow task.
+     * It is available from server version 1.17 behind the `system.enableActivityEagerExecution` feature flag.
+     *
+     * Eager dispatch will only be used if `allowEagerDispatch` is enabled (the default) and {@link taskQueue} is either
+     * omitted or the same as the current Workflow.
+     *
+     * @default true
+     */
+    allowEagerDispatch?: boolean;
+}
+/**
+ * Options for local activity invocation
+ */
+export interface LocalActivityOptions {
+    /**
+     * RetryPolicy that defines how an activity is retried in case of failure. If this is not set, then the SDK-defined default activity retry policy will be used.
+     * Note that local activities are always executed at least once, even if maximum attempts is set to 1 due to Workflow task retries.
+     */
+    retry?: RetryPolicy;
+    /**
+     * Maximum time the local activity is allowed to execute after the task is dispatched. This
+     * timeout is always retryable.
+     *
+     * Either this option or {@link scheduleToCloseTimeout} is required.
+     * If set, this must be <= {@link scheduleToCloseTimeout}, otherwise, it will be clamped down.
+     *
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    startToCloseTimeout?: string | number;
+    /**
+     * Limits time the local activity can idle internally before being executed. That can happen if
+     * the worker is currently at max concurrent local activity executions. This timeout is always
+     * non retryable as all a retry would achieve is to put it back into the same queue. Defaults
+     * to {@link scheduleToCloseTimeout} if not specified and that is set. Must be <=
+     * {@link scheduleToCloseTimeout} when set, otherwise, it will be clamped down.
+     *
+     * @default unlimited
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    scheduleToStartTimeout?: string | number;
+    /**
+     * Indicates how long the caller is willing to wait for local activity completion. Limits how
+     * long retries will be attempted. When not specified defaults to the workflow execution
+     * timeout (which may be unset).
+     *
+     * Either this option or {@link startToCloseTimeout} is required.
+     *
+     * @default unlimited
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     */
+    scheduleToCloseTimeout?: string | number;
+    /**
+     * If the activity is retrying and backoff would exceed this value, a server side timer will be scheduled for the next attempt.
+     * Otherwise, backoff will happen internally in the SDK.
+     *
+     * @default 1 minute
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     **/
+    localRetryThreshold?: string | number;
+    /**
+     * Determines what the SDK does when the Activity is cancelled.
+     * - `TRY_CANCEL` - Initiate a cancellation request and immediately report cancellation to the workflow.
+     * - `WAIT_CANCELLATION_COMPLETED` - Wait for activity cancellation completion. Note that activity must heartbeat to receive a
+     *   cancellation notification. This can block the cancellation for a long time if activity doesn't
+     *   heartbeat or chooses to ignore the cancellation request.
+     * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
+     */
+    cancellationType?: coresdk.workflow_commands.ActivityCancellationType;
+}

package/lib/activity-options.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityCancellationType = void 0;
+const type_helpers_1 = require("./type-helpers");
+// Avoid importing the proto implementation to reduce workflow bundle size
+// Copied from coresdk.workflow_commands.ActivityCancellationType
+var ActivityCancellationType;
+(function (ActivityCancellationType) {
+    ActivityCancellationType[ActivityCancellationType["TRY_CANCEL"] = 0] = "TRY_CANCEL";
+    ActivityCancellationType[ActivityCancellationType["WAIT_CANCELLATION_COMPLETED"] = 1] = "WAIT_CANCELLATION_COMPLETED";
+    ActivityCancellationType[ActivityCancellationType["ABANDON"] = 2] = "ABANDON";
+})(ActivityCancellationType = exports.ActivityCancellationType || (exports.ActivityCancellationType = {}));
+(0, type_helpers_1.checkExtends)();
+(0, type_helpers_1.checkExtends)();
+//# sourceMappingURL=activity-options.js.map

package/lib/activity-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-options.js","sourceRoot":"","sources":["../src/activity-options.ts"],"names":[],"mappings":";;;AAEA,iDAA8C;AAE9C,0EAA0E;AAC1E,iEAAiE;AACjE,IAAY,wBAIX;AAJD,WAAY,wBAAwB;IAClC,mFAAc,CAAA;IACd,qHAA+B,CAAA;IAC/B,6EAAW,CAAA;AACb,CAAC,EAJW,wBAAwB,GAAxB,gCAAwB,KAAxB,gCAAwB,QAInC;AAED,IAAA,2BAAY,GAAgF,CAAC;AAC7F,IAAA,2BAAY,GAAgF,CAAC"}

package/lib/converter/data-converter.d.ts

@@ -1,3 +1,4 @@
+import { FailureConverter } from './failure-converter';
 import { PayloadCodec } from './payload-codec';
 import { PayloadConverter } from './payload-converter';
 /**
@@ -27,10 +28,18 @@ import { PayloadConverter } from './payload-converter';
 export interface DataConverter {
     /**
      * Path of a file that has a `payloadConverter` named export.
-     * `payloadConverter` should be an instance of a class that implements {@link PayloadConverter}.
+     * `payloadConverter` should be an object that implements {@link PayloadConverter}.
      * If no path is provided, {@link defaultPayloadConverter} is used.
      */
     payloadConverterPath?: string;
+    /**
+     * Path of a file that has a `failureConverter` named export.
+     * `failureConverter` should be an object that implements {@link FailureConverter}.
+     * If no path is provided, {@link defaultFailureConverter} is used.
+     *
+     * @experimental
+     */
+    failureConverterPath?: string;
     /**
      * An array of {@link PayloadCodec} instances.
      *
@@ -45,6 +54,16 @@ export interface DataConverter {
  */
 export interface LoadedDataConverter {
     payloadConverter: PayloadConverter;
+    failureConverter: FailureConverter;
     payloadCodecs: PayloadCodec[];
 }
+/**
+ * The default {@link FailureConverter} used by the SDK.
+ *
+ * Error messages and stack traces are serizalized as plain text.
+ */
+export declare const defaultFailureConverter: FailureConverter;
+/**
+ * A "loaded" data converter that uses the default set of failure and payload converters.
+ */
 export declare const defaultDataConverter: LoadedDataConverter;

package/lib/converter/data-converter.js

@@ -1,9 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultDataConverter = void 0;
-const payload_converters_1 = require("./payload-converters");
+exports.defaultDataConverter = exports.defaultFailureConverter = void 0;
+const failure_converter_1 = require("./failure-converter");
+const payload_converter_1 = require("./payload-converter");
+/**
+ * The default {@link FailureConverter} used by the SDK.
+ *
+ * Error messages and stack traces are serizalized as plain text.
+ */
+exports.defaultFailureConverter = new failure_converter_1.DefaultFailureConverter();
+/**
+ * A "loaded" data converter that uses the default set of failure and payload converters.
+ */
 exports.defaultDataConverter = {
-    payloadConverter: payload_converters_1.defaultPayloadConverter,
+    payloadConverter: payload_converter_1.defaultPayloadConverter,
+    failureConverter: exports.defaultFailureConverter,
     payloadCodecs: [],
 };
 //# sourceMappingURL=data-converter.js.map

package/lib/converter/data-converter.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-converter.js","sourceRoot":"","sources":["../../src/converter/data-converter.ts"],"names":[],"mappings":";;;AAEA,6DAA+D;AAoDlD,QAAA,oBAAoB,GAAwB;IACvD,gBAAgB,EAAE,4CAAuB;IACzC,aAAa,EAAE,EAAE;CAClB,CAAC"}
+{"version":3,"file":"data-converter.js","sourceRoot":"","sources":["../../src/converter/data-converter.ts"],"names":[],"mappings":";;;AAAA,2DAAgF;AAEhF,2DAAgF;AA8DhF;;;;GAIG;AACU,QAAA,uBAAuB,GAAqB,IAAI,2CAAuB,EAAE,CAAC;AAEvF;;GAEG;AACU,QAAA,oBAAoB,GAAwB;IACvD,gBAAgB,EAAE,2CAAuB;IACzC,gBAAgB,EAAE,+BAAuB;IACzC,aAAa,EAAE,EAAE;CAClB,CAAC"}

package/lib/converter/failure-converter.d.ts

@@ -0,0 +1,75 @@
+import { ProtoFailure, TemporalFailure } from '../failure';
+import { PayloadConverter } from './payload-converter';
+/**
+ * Cuts out the framework part of a stack trace, leaving only user code entries
+ */
+export declare function cutoffStackTrace(stack?: string): string;
+/**
+ * A `FailureConverter` is responsible to convert from proto `Failure` instances to JS `Errors` and back.
+ *
+ * It is recommended to use the {@link DefaultFailureConverter} and not attempt to customize the default implementation
+ * in order to maintain cross language failure serialization compatibility.
+ *
+ * @experimental
+ */
+export interface FailureConverter {
+    /**
+     * Converts a caught error to a Failure proto message.
+     */
+    errorToFailure(err: unknown): ProtoFailure;
+    /**
+     * Converts a Failure proto message to a JS Error object.
+     */
+    failureToError(err: ProtoFailure): TemporalFailure;
+}
+/**
+ * The "shape" of the attributes set as the {@link ProtoFailure.encodedAttributes} payload in case
+ * {@link DefaultEncodedFailureAttributes.encodeCommonAttributes} is set to `true`.
+ */
+export interface DefaultEncodedFailureAttributes {
+    message: string;
+    stack_trace: string;
+}
+/**
+ * Options for the {@link DefaultFailureConverter} constructor.
+ */
+export interface DefaultFailureConverterOptions {
+    /**
+     * The {@link PayloadConverter} to use for converting failure attributes.
+     */
+    payloadConverter: PayloadConverter;
+    /**
+     * Whether to encode error messages and stack traces (for encrypting these attributes use a {@link PayloadCodec}).
+     */
+    encodeCommonAttributes: boolean;
+}
+/**
+ * Default cross language compatible failure converter.
+ *
+ * By default, it will leave error messages and stack traces as plain text. In order to encrypt those, set
+ * `encodeCommonAttributes` to `true` in the constructor options and make sure to use a {@link PayloadCodec} that can
+ * encrypt / decrypt payloads in your Worker and Client options.
+ *
+ * @experimental
+ */
+export declare class DefaultFailureConverter implements FailureConverter {
+    readonly options: DefaultFailureConverterOptions;
+    constructor(options?: Partial<DefaultFailureConverterOptions>);
+    /**
+     * Converts a Failure proto message to a JS Error object.
+     *
+     * Does not set common properties, that is done in {@link failureToError}.
+     */
+    failureToErrorInner(failure: ProtoFailure): TemporalFailure;
+    failureToError(failure: ProtoFailure): TemporalFailure;
+    errorToFailure(err: unknown): ProtoFailure;
+    errorToFailureInner(err: unknown): ProtoFailure;
+    /**
+     * Converts a Failure proto message to a JS Error object if defined or returns undefined.
+     */
+    optionalFailureToOptionalError(failure: ProtoFailure | undefined | null): TemporalFailure | undefined;
+    /**
+     * Converts an error to a Failure proto message if defined or returns undefined
+     */
+    optionalErrorToOptionalFailure(err: unknown): ProtoFailure | undefined;
+}

package/lib/converter/failure-converter.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultFailureConverter = exports.cutoffStackTrace = void 0;
+const failure_1 = require("../failure");
+const type_helpers_1 = require("../type-helpers");
+const payload_converter_1 = require("./payload-converter");
+/**
+ * Stack traces will be cutoff when on of these patterns is matched
+ */
+const CUTOFF_STACK_PATTERNS = [
+    /** Activity execution */
+    /\s+at Activity\.execute \(.*[\\/]worker[\\/](?:src|lib)[\\/]activity\.[jt]s:\d+:\d+\)/,
+    /** Workflow activation */
+    /\s+at Activator\.\S+NextHandler \(.*[\\/]workflow[\\/](?:src|lib)[\\/]internals\.[jt]s:\d+:\d+\)/,
+    /** Workflow run anything in context */
+    /\s+at Script\.runInContext \((?:node:vm|vm\.js):\d+:\d+\)/,
+];
+/**
+ * Cuts out the framework part of a stack trace, leaving only user code entries
+ */
+function cutoffStackTrace(stack) {
+    const lines = (stack ?? '').split(/\r?\n/);
+    const acc = Array();
+    lineLoop: for (const line of lines) {
+        for (const pattern of CUTOFF_STACK_PATTERNS) {
+            if (pattern.test(line))
+                break lineLoop;
+        }
+        acc.push(line);
+    }
+    return acc.join('\n');
+}
+exports.cutoffStackTrace = cutoffStackTrace;
+/**
+ * Default cross language compatible failure converter.
+ *
+ * By default, it will leave error messages and stack traces as plain text. In order to encrypt those, set
+ * `encodeCommonAttributes` to `true` in the constructor options and make sure to use a {@link PayloadCodec} that can
+ * encrypt / decrypt payloads in your Worker and Client options.
+ *
+ * @experimental
+ */
+class DefaultFailureConverter {
+    constructor(options) {
+        const { encodeCommonAttributes, payloadConverter } = options ?? {};
+        this.options = {
+            encodeCommonAttributes: encodeCommonAttributes ?? false,
+            payloadConverter: payloadConverter ?? payload_converter_1.defaultPayloadConverter,
+        };
+    }
+    /**
+     * Converts a Failure proto message to a JS Error object.
+     *
+     * Does not set common properties, that is done in {@link failureToError}.
+     */
+    failureToErrorInner(failure) {
+        if (failure.applicationFailureInfo) {
+            return new failure_1.ApplicationFailure(failure.message ?? undefined, failure.applicationFailureInfo.type, Boolean(failure.applicationFailureInfo.nonRetryable), (0, payload_converter_1.arrayFromPayloads)(this.options.payloadConverter, failure.applicationFailureInfo.details?.payloads), this.optionalFailureToOptionalError(failure.cause));
+        }
+        if (failure.serverFailureInfo) {
+            return new failure_1.ServerFailure(failure.message ?? undefined, Boolean(failure.serverFailureInfo.nonRetryable), this.optionalFailureToOptionalError(failure.cause));
+        }
+        if (failure.timeoutFailureInfo) {
+            return new failure_1.TimeoutFailure(failure.message ?? undefined, (0, payload_converter_1.fromPayloadsAtIndex)(this.options.payloadConverter, 0, failure.timeoutFailureInfo.lastHeartbeatDetails?.payloads), failure.timeoutFailureInfo.timeoutType ?? failure_1.TimeoutType.TIMEOUT_TYPE_UNSPECIFIED);
+        }
+        if (failure.terminatedFailureInfo) {
+            return new failure_1.TerminatedFailure(failure.message ?? undefined, this.optionalFailureToOptionalError(failure.cause));
+        }
+        if (failure.canceledFailureInfo) {
+            return new failure_1.CancelledFailure(failure.message ?? undefined, (0, payload_converter_1.arrayFromPayloads)(this.options.payloadConverter, failure.canceledFailureInfo.details?.payloads), this.optionalFailureToOptionalError(failure.cause));
+        }
+        if (failure.resetWorkflowFailureInfo) {
+            return new failure_1.ApplicationFailure(failure.message ?? undefined, 'ResetWorkflow', false, (0, payload_converter_1.arrayFromPayloads)(this.options.payloadConverter, failure.resetWorkflowFailureInfo.lastHeartbeatDetails?.payloads), this.optionalFailureToOptionalError(failure.cause));
+        }
+        if (failure.childWorkflowExecutionFailureInfo) {
+            const { namespace, workflowType, workflowExecution, retryState } = failure.childWorkflowExecutionFailureInfo;
+            if (!(workflowType?.name && workflowExecution)) {
+                throw new TypeError('Missing attributes on childWorkflowExecutionFailureInfo');
+            }
+            return new failure_1.ChildWorkflowFailure(namespace ?? undefined, workflowExecution, workflowType.name, retryState ?? failure_1.RetryState.RETRY_STATE_UNSPECIFIED, this.optionalFailureToOptionalError(failure.cause));
+        }
+        if (failure.activityFailureInfo) {
+            if (!failure.activityFailureInfo.activityType?.name) {
+                throw new TypeError('Missing activityType?.name on activityFailureInfo');
+            }
+            return new failure_1.ActivityFailure(failure.activityFailureInfo.activityType.name, failure.activityFailureInfo.activityId ?? undefined, failure.activityFailureInfo.retryState ?? failure_1.RetryState.RETRY_STATE_UNSPECIFIED, failure.activityFailureInfo.identity ?? undefined, this.optionalFailureToOptionalError(failure.cause));
+        }
+        return new failure_1.TemporalFailure(failure.message ?? undefined, this.optionalFailureToOptionalError(failure.cause));
+    }
+    failureToError(failure) {
+        if (failure.encodedAttributes) {
+            const attrs = this.options.payloadConverter.fromPayload(failure.encodedAttributes);
+            // Don't apply encodedAttributes unless they conform to an expected schema
+            if (typeof attrs === 'object' && attrs !== null) {
+                const { message, stack_trace } = attrs;
+                // Avoid mutating the argument
+                failure = { ...failure };
+                if (typeof message === 'string') {
+                    failure.message = message;
+                }
+                if (typeof stack_trace === 'string') {
+                    failure.stackTrace = stack_trace;
+                }
+            }
+        }
+        const err = this.failureToErrorInner(failure);
+        err.stack = failure.stackTrace ?? '';
+        err.failure = failure;
+        return err;
+    }
+    errorToFailure(err) {
+        const failure = this.errorToFailureInner(err);
+        if (this.options.encodeCommonAttributes) {
+            const { message, stackTrace } = failure;
+            failure.message = 'Encoded failure';
+            failure.stackTrace = '';
+            failure.encodedAttributes = this.options.payloadConverter.toPayload({ message, stack_trace: stackTrace });
+        }
+        return failure;
+    }
+    errorToFailureInner(err) {
+        if (err instanceof failure_1.TemporalFailure) {
+            if (err.failure)
+                return err.failure;
+            const base = {
+                message: err.message,
+                stackTrace: cutoffStackTrace(err.stack),
+                cause: this.optionalErrorToOptionalFailure(err.cause),
+                source: failure_1.FAILURE_SOURCE,
+            };
+            if (err instanceof failure_1.ActivityFailure) {
+                return {
+                    ...base,
+                    activityFailureInfo: {
+                        ...err,
+                        activityType: { name: err.activityType },
+                    },
+                };
+            }
+            if (err instanceof failure_1.ChildWorkflowFailure) {
+                return {
+                    ...base,
+                    childWorkflowExecutionFailureInfo: {
+                        ...err,
+                        workflowExecution: err.execution,
+                        workflowType: { name: err.workflowType },
+                    },
+                };
+            }
+            if (err instanceof failure_1.ApplicationFailure) {
+                return {
+                    ...base,
+                    applicationFailureInfo: {
+                        type: err.type,
+                        nonRetryable: err.nonRetryable,
+                        details: err.details && err.details.length
+                            ? { payloads: (0, payload_converter_1.toPayloads)(this.options.payloadConverter, ...err.details) }
+                            : undefined,
+                    },
+                };
+            }
+            if (err instanceof failure_1.CancelledFailure) {
+                return {
+                    ...base,
+                    canceledFailureInfo: {
+                        details: err.details && err.details.length
+                            ? { payloads: (0, payload_converter_1.toPayloads)(this.options.payloadConverter, ...err.details) }
+                            : undefined,
+                    },
+                };
+            }
+            if (err instanceof failure_1.TimeoutFailure) {
+                return {
+                    ...base,
+                    timeoutFailureInfo: {
+                        timeoutType: err.timeoutType,
+                        lastHeartbeatDetails: err.lastHeartbeatDetails
+                            ? { payloads: (0, payload_converter_1.toPayloads)(this.options.payloadConverter, err.lastHeartbeatDetails) }
+                            : undefined,
+                    },
+                };
+            }
+            if (err instanceof failure_1.TerminatedFailure) {
+                return {
+                    ...base,
+                    terminatedFailureInfo: {},
+                };
+            }
+            if (err instanceof failure_1.ServerFailure) {
+                return {
+                    ...base,
+                    serverFailureInfo: { nonRetryable: err.nonRetryable },
+                };
+            }
+            // Just a TemporalFailure
+            return base;
+        }
+        const base = {
+            source: failure_1.FAILURE_SOURCE,
+        };
+        if ((0, type_helpers_1.isRecord)(err) && (0, type_helpers_1.hasOwnProperties)(err, ['message', 'stack'])) {
+            return {
+                ...base,
+                message: String(err.message) ?? '',
+                stackTrace: cutoffStackTrace(String(err.stack)),
+                cause: this.optionalErrorToOptionalFailure(err.cause),
+            };
+        }
+        const recommendation = ` [A non-Error value was thrown from your code. We recommend throwing Error objects so that we can provide a stack trace]`;
+        if (typeof err === 'string') {
+            return { ...base, message: err + recommendation };
+        }
+        if (typeof err === 'object') {
+            let message = '';
+            try {
+                message = JSON.stringify(err);
+            }
+            catch (_err) {
+                message = String(err);
+            }
+            return { ...base, message: message + recommendation };
+        }
+        return { ...base, message: String(err) + recommendation };
+    }
+    /**
+     * Converts a Failure proto message to a JS Error object if defined or returns undefined.
+     */
+    optionalFailureToOptionalError(failure) {
+        return failure ? this.failureToError(failure) : undefined;
+    }
+    /**
+     * Converts an error to a Failure proto message if defined or returns undefined
+     */
+    optionalErrorToOptionalFailure(err) {
+        return err ? this.errorToFailure(err) : undefined;
+    }
+}
+exports.DefaultFailureConverter = DefaultFailureConverter;
+//# sourceMappingURL=failure-converter.js.map

package/lib/converter/failure-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-converter.js","sourceRoot":"","sources":["../../src/converter/failure-converter.ts"],"names":[],"mappings":"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"}

package/lib/converter/payload-codec.d.ts

@@ -1,4 +1,4 @@
-import { Payload } from './types';
+import { Payload } from '../interfaces';
 /**
  * `PayloadCodec` is an optional step that happens between the wire and the {@link PayloadConverter}:
  *

package/lib/converter/payload-converter.d.ts

@@ -1,4 +1,4 @@
-import { Payload } from './types';
+import { Payload } from '../interfaces';
 /**
  * Used by the framework to serialize/deserialize data like parameters and return values.
  *
@@ -54,3 +54,87 @@ export declare function fromPayloadsAtIndex<T>(converter: PayloadConverter, inde
  */
 export declare function arrayFromPayloads(converter: PayloadConverter, payloads?: Payload[] | null): unknown[];
 export declare function mapFromPayloads<K extends string>(converter: PayloadConverter, map?: Record<K, Payload> | null | undefined): Record<K, unknown> | undefined | null;
+export interface PayloadConverterWithEncoding {
+    /**
+     * Converts a value to a {@link Payload}.
+     *
+     * @param value The value to convert. Example values include the Workflow args sent from the Client and the values returned by a Workflow or Activity.
+     * @returns The {@link Payload}, or `undefined` if unable to convert.
+     */
+    toPayload<T>(value: T): Payload | undefined;
+    /**
+     * Converts a {@link Payload} back to a value.
+     */
+    fromPayload<T>(payload: Payload): T;
+    readonly encodingType: string;
+}
+/**
+ * Tries to convert values to {@link Payload}s using the {@link PayloadConverterWithEncoding}s provided to the constructor, in the order provided.
+ *
+ * Converts Payloads to values based on the `Payload.metadata.encoding` field, which matches the {@link PayloadConverterWithEncoding.encodingType}
+ * of the converter that created the Payload.
+ */
+export declare class CompositePayloadConverter implements PayloadConverter {
+    readonly converters: PayloadConverterWithEncoding[];
+    readonly converterByEncoding: Map<string, PayloadConverterWithEncoding>;
+    constructor(...converters: PayloadConverterWithEncoding[]);
+    /**
+     * Tries to run `.toPayload(value)` on each converter in the order provided at construction.
+     * Returns the first successful result, throws {@link ValueError} if there is no converter that can handle the value.
+     */
+    toPayload<T>(value: T): Payload;
+    /**
+     * Run {@link PayloadConverterWithEncoding.fromPayload} based on the `encoding` metadata of the {@link Payload}.
+     */
+    fromPayload<T>(payload: Payload): T;
+}
+/**
+ * Converts between JS undefined and NULL Payload
+ */
+export declare class UndefinedPayloadConverter implements PayloadConverterWithEncoding {
+    encodingType: "binary/null";
+    toPayload(value: unknown): Payload | undefined;
+    fromPayload<T>(_content: Payload): T;
+}
+/**
+ * Converts between binary data types and RAW Payload
+ */
+export declare class BinaryPayloadConverter implements PayloadConverterWithEncoding {
+    encodingType: "binary/plain";
+    toPayload(value: unknown): Payload | undefined;
+    fromPayload<T>(content: Payload): T;
+}
+/**
+ * Converts between non-undefined values and serialized JSON Payload
+ */
+export declare class JsonPayloadConverter implements PayloadConverterWithEncoding {
+    encodingType: "json/plain";
+    toPayload(value: unknown): Payload | undefined;
+    fromPayload<T>(content: Payload): T;
+}
+/**
+ * Converts Search Attribute values using JsonPayloadConverter
+ */
+export declare class SearchAttributePayloadConverter implements PayloadConverter {
+    jsonConverter: JsonPayloadConverter;
+    validNonDateTypes: string[];
+    toPayload(values: unknown): Payload;
+    /**
+     * Datetime Search Attribute values are converted to `Date`s
+     */
+    fromPayload<T>(payload: Payload): T;
+}
+export declare const searchAttributePayloadConverter: SearchAttributePayloadConverter;
+export declare class DefaultPayloadConverter extends CompositePayloadConverter {
+    constructor();
+}
+/**
+ * The default {@link PayloadConverter} used by the SDK. Supports `Uint8Array` and JSON serializables (so if
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description | `JSON.stringify(yourArgOrRetval)`}
+ * works, the default payload converter will work).
+ *
+ * To also support Protobufs, create a custom payload converter with {@link DefaultPayloadConverter}:
+ *
+ * `const myConverter = new DefaultPayloadConverter({ protobufRoot })`
+ */
+export declare const defaultPayloadConverter: DefaultPayloadConverter;