@temporalio/common 1.3.0 → 1.4.0

package/src/converter/payload-converter.ts

@@ -1,4 +1,7 @@
-import { Payload } from './types';
+import { decode, encode } from '../encoding';
+import { IllegalStateError, PayloadConverterError, ValueError } from '../errors';
+import { Payload } from '../interfaces';
+import { encodingKeys, encodingTypes, METADATA_ENCODING_KEY } from './types';
 
 /**
  * Used by the framework to serialize/deserialize data like parameters and return values.
@@ -93,3 +96,245 @@ export function mapFromPayloads<K extends string>(
     })
   ) as Record<K, unknown>;
 }
+
+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 class CompositePayloadConverter implements PayloadConverter {
+  readonly converters: PayloadConverterWithEncoding[];
+  readonly converterByEncoding: Map<string, PayloadConverterWithEncoding> = new Map();
+
+  constructor(...converters: PayloadConverterWithEncoding[]) {
+    if (converters.length === 0) {
+      throw new PayloadConverterError('Must provide at least one PayloadConverterWithEncoding');
+    }
+
+    this.converters = converters;
+    for (const converter of converters) {
+      this.converterByEncoding.set(converter.encodingType, converter);
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public toPayload<T>(value: T): Payload {
+    for (const converter of this.converters) {
+      const result = converter.toPayload(value);
+      if (result !== undefined) {
+        return result;
+      }
+    }
+
+    throw new ValueError(`Unable to convert ${value} to payload`);
+  }
+
+  /**
+   * Run {@link PayloadConverterWithEncoding.fromPayload} based on the `encoding` metadata of the {@link Payload}.
+   */
+  public fromPayload<T>(payload: Payload): T {
+    if (payload.metadata === undefined || payload.metadata === null) {
+      throw new ValueError('Missing payload metadata');
+    }
+    const encoding = decode(payload.metadata[METADATA_ENCODING_KEY]);
+    const converter = this.converterByEncoding.get(encoding);
+    if (converter === undefined) {
+      throw new ValueError(`Unknown encoding: ${encoding}`);
+    }
+    return converter.fromPayload(payload);
+  }
+}
+
+/**
+ * Converts between JS undefined and NULL Payload
+ */
+export class UndefinedPayloadConverter implements PayloadConverterWithEncoding {
+  public encodingType = encodingTypes.METADATA_ENCODING_NULL;
+
+  public toPayload(value: unknown): Payload | undefined {
+    if (value !== undefined) {
+      return undefined;
+    }
+
+    return {
+      metadata: {
+        [METADATA_ENCODING_KEY]: encodingKeys.METADATA_ENCODING_NULL,
+      },
+    };
+  }
+
+  public fromPayload<T>(_content: Payload): T {
+    return undefined as any; // Just return undefined
+  }
+}
+
+/**
+ * Converts between binary data types and RAW Payload
+ */
+export class BinaryPayloadConverter implements PayloadConverterWithEncoding {
+  public encodingType = encodingTypes.METADATA_ENCODING_RAW;
+
+  public toPayload(value: unknown): Payload | undefined {
+    if (!(value instanceof Uint8Array)) {
+      return undefined;
+    }
+
+    return {
+      metadata: {
+        [METADATA_ENCODING_KEY]: encodingKeys.METADATA_ENCODING_RAW,
+      },
+      data: value,
+    };
+  }
+
+  public fromPayload<T>(content: Payload): T {
+    return content.data as any;
+  }
+}
+
+/**
+ * Converts between non-undefined values and serialized JSON Payload
+ */
+export class JsonPayloadConverter implements PayloadConverterWithEncoding {
+  public encodingType = encodingTypes.METADATA_ENCODING_JSON;
+
+  public toPayload(value: unknown): Payload | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+
+    let json;
+    try {
+      json = JSON.stringify(value);
+    } catch (e) {
+      return undefined;
+    }
+
+    return {
+      metadata: {
+        [METADATA_ENCODING_KEY]: encodingKeys.METADATA_ENCODING_JSON,
+      },
+      data: encode(json),
+    };
+  }
+
+  public fromPayload<T>(content: Payload): T {
+    if (content.data === undefined || content.data === null) {
+      throw new ValueError('Got payload with no data');
+    }
+    return JSON.parse(decode(content.data));
+  }
+}
+
+/**
+ * Converts Search Attribute values using JsonPayloadConverter
+ */
+export class SearchAttributePayloadConverter implements PayloadConverter {
+  jsonConverter = new JsonPayloadConverter();
+  validNonDateTypes = ['string', 'number', 'boolean'];
+
+  public toPayload(values: unknown): Payload {
+    if (!(values instanceof Array)) {
+      throw new ValueError(`SearchAttribute value must be an array`);
+    }
+
+    if (values.length > 0) {
+      const firstValue = values[0];
+      const firstType = typeof firstValue;
+      if (firstType === 'object') {
+        for (const idx in values) {
+          const value = values[idx];
+          if (!(value instanceof Date)) {
+            throw new ValueError(
+              `SearchAttribute values must arrays of strings, numbers, booleans, or Dates. The value ${value} at index ${idx} is of type ${typeof value}`
+            );
+          }
+        }
+      } else {
+        if (!this.validNonDateTypes.includes(firstType)) {
+          throw new ValueError(`SearchAttribute array values must be: string | number | boolean | Date`);
+        }
+
+        for (const idx in values) {
+          const value = values[idx];
+          if (typeof value !== firstType) {
+            throw new ValueError(
+              `All SearchAttribute array values must be of the same type. The first value ${firstValue} of type ${firstType} doesn't match value ${value} of type ${typeof value} at index ${idx}`
+            );
+          }
+        }
+      }
+    }
+
+    // JSON.stringify takes care of converting Dates to ISO strings
+    const ret = this.jsonConverter.toPayload(values);
+    if (ret === undefined) {
+      throw new IllegalStateError('Could not convert search attributes to payloads');
+    }
+    return ret;
+  }
+
+  /**
+   * Datetime Search Attribute values are converted to `Date`s
+   */
+  public fromPayload<T>(payload: Payload): T {
+    if (payload.metadata === undefined || payload.metadata === null) {
+      throw new ValueError('Missing payload metadata');
+    }
+
+    const value = this.jsonConverter.fromPayload(payload);
+    let arrayWrappedValue = value instanceof Array ? value : [value];
+
+    const searchAttributeType = decode(payload.metadata.type);
+    if (searchAttributeType === 'Datetime') {
+      arrayWrappedValue = arrayWrappedValue.map((dateString) => new Date(dateString));
+    }
+    return arrayWrappedValue as unknown as T;
+  }
+}
+
+export const searchAttributePayloadConverter = new SearchAttributePayloadConverter();
+
+export class DefaultPayloadConverter extends CompositePayloadConverter {
+  // Match the order used in other SDKs, but exclude Protobuf converters so that the code, including
+  // `proto3-json-serializer`, doesn't take space in Workflow bundles that don't use Protobufs. To use Protobufs, use
+  // {@link DefaultPayloadConverterWithProtobufs}.
+  //
+  // Go SDK:
+  // https://github.com/temporalio/sdk-go/blob/5e5645f0c550dcf717c095ae32c76a7087d2e985/converter/default_data_converter.go#L28
+  constructor() {
+    super(new UndefinedPayloadConverter(), new BinaryPayloadConverter(), new JsonPayloadConverter());
+  }
+}
+
+/**
+ * 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 const defaultPayloadConverter = new DefaultPayloadConverter();

package/src/converter/protobuf-payload-converters.ts

@@ -1,33 +1,22 @@
-import {
-  errorMessage,
-  hasOwnProperties,
-  hasOwnProperty,
-  isRecord,
-  PayloadConverterError,
-  ValueError,
-} from '@temporalio/internal-workflow-common';
 import * as protoJsonSerializer from 'proto3-json-serializer';
 import type { Message, Namespace, Root, Type } from 'protobufjs';
-import { JsonPayloadConverter } from './json-payload-converter';
+import { decode, encode } from '../encoding';
+import { PayloadConverterError, ValueError } from '../errors';
+import { Payload } from '../interfaces';
+import { errorMessage, hasOwnProperties, hasOwnProperty, isRecord } from '../type-helpers';
 import {
   BinaryPayloadConverter,
   CompositePayloadConverter,
+  JsonPayloadConverter,
   PayloadConverterWithEncoding,
   UndefinedPayloadConverter,
-} from './payload-converters';
-import {
-  EncodingType,
-  encodingTypes,
-  METADATA_ENCODING_KEY,
-  METADATA_MESSAGE_TYPE_KEY,
-  Payload,
-  str,
-  u8,
-} from './types';
+} from './payload-converter';
+
+import { encodingTypes, METADATA_ENCODING_KEY, METADATA_MESSAGE_TYPE_KEY } from './types';
 
 abstract class ProtobufPayloadConverter implements PayloadConverterWithEncoding {
   protected readonly root: Root | undefined;
-  public abstract encodingType: EncodingType;
+  public abstract encodingType: string;
 
   public abstract toPayload<T>(value: T): Payload | undefined;
   public abstract fromPayload<T>(payload: Payload): T;
@@ -54,7 +43,7 @@ abstract class ProtobufPayloadConverter implements PayloadConverterWithEncoding
       throw new PayloadConverterError('Unable to deserialize protobuf message without `root` being provided');
     }
 
-    const messageTypeName = str(content.metadata[METADATA_MESSAGE_TYPE_KEY]);
+    const messageTypeName = decode(content.metadata[METADATA_MESSAGE_TYPE_KEY]);
     let messageType;
     try {
       messageType = this.root.lookupType(messageTypeName);
@@ -74,8 +63,8 @@ abstract class ProtobufPayloadConverter implements PayloadConverterWithEncoding
   protected constructPayload({ messageTypeName, message }: { messageTypeName: string; message: Uint8Array }): Payload {
     return {
       metadata: {
-        [METADATA_ENCODING_KEY]: u8(this.encodingType),
-        [METADATA_MESSAGE_TYPE_KEY]: u8(messageTypeName),
+        [METADATA_ENCODING_KEY]: encode(this.encodingType),
+        [METADATA_MESSAGE_TYPE_KEY]: encode(messageTypeName),
       },
       data: message,
     };
@@ -134,13 +123,13 @@ export class ProtobufJsonPayloadConverter extends ProtobufPayloadConverter {
 
     return this.constructPayload({
       messageTypeName: getNamespacedTypeName(value.$type),
-      message: u8(JSON.stringify(jsonValue)),
+      message: encode(JSON.stringify(jsonValue)),
     });
   }
 
   public fromPayload<T>(content: Payload): T {
     const { messageType, data } = this.validatePayload(content);
-    return protoJsonSerializer.fromProto3JSON(messageType, JSON.parse(str(data))) as unknown as T;
+    return protoJsonSerializer.fromProto3JSON(messageType, JSON.parse(decode(data))) as unknown as T;
   }
 }
 

package/src/converter/types.ts

@@ -1,17 +1,4 @@
-import { TextDecoder, TextEncoder } from './encoding';
-
-export { Payload } from '@temporalio/internal-workflow-common';
-
-/**
- * Transform an *ascii* string into a Uint8Array
- */
-export function u8(s: string): Uint8Array {
-  return new TextEncoder().encode(s);
-}
-
-export function str(a: Uint8Array): string {
-  return new TextDecoder().decode(a);
-}
+import { encode } from '../encoding';
 
 export const METADATA_ENCODING_KEY = 'encoding';
 export const encodingTypes = {
@@ -24,11 +11,11 @@ export const encodingTypes = {
 export type EncodingType = typeof encodingTypes[keyof typeof encodingTypes];
 
 export const encodingKeys = {
-  METADATA_ENCODING_NULL: u8(encodingTypes.METADATA_ENCODING_NULL),
-  METADATA_ENCODING_RAW: u8(encodingTypes.METADATA_ENCODING_RAW),
-  METADATA_ENCODING_JSON: u8(encodingTypes.METADATA_ENCODING_JSON),
-  METADATA_ENCODING_PROTOBUF_JSON: u8(encodingTypes.METADATA_ENCODING_PROTOBUF_JSON),
-  METADATA_ENCODING_PROTOBUF: u8(encodingTypes.METADATA_ENCODING_PROTOBUF),
+  METADATA_ENCODING_NULL: encode(encodingTypes.METADATA_ENCODING_NULL),
+  METADATA_ENCODING_RAW: encode(encodingTypes.METADATA_ENCODING_RAW),
+  METADATA_ENCODING_JSON: encode(encodingTypes.METADATA_ENCODING_JSON),
+  METADATA_ENCODING_PROTOBUF_JSON: encode(encodingTypes.METADATA_ENCODING_PROTOBUF_JSON),
+  METADATA_ENCODING_PROTOBUF: encode(encodingTypes.METADATA_ENCODING_PROTOBUF),
 } as const;
 
 export const METADATA_MESSAGE_TYPE_KEY = 'messageType';

package/src/deprecated-time.ts

@@ -0,0 +1,80 @@
+import * as time from './time';
+import { Timestamp } from './time';
+
+/**
+ * Lossy conversion function from Timestamp to number due to possible overflow.
+ * If ts is null or undefined returns undefined.
+ *
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function optionalTsToMs(ts: Timestamp | null | undefined): number | undefined {
+  return time.optionalTsToMs(ts);
+}
+
+/**
+ * Lossy conversion function from Timestamp to number due to possible overflow
+ *
+ * @hidden
+ * @deprecated - meant for internal use only
+ * @deprecated - meant for internal use only
+ */
+export function tsToMs(ts: Timestamp | null | undefined): number {
+  return time.tsToMs(ts);
+}
+
+/**
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function msNumberToTs(millis: number): Timestamp {
+  return time.msNumberToTs(millis);
+}
+
+/**
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function msToTs(str: string | number): Timestamp {
+  return time.msToTs(str);
+}
+
+/**
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function msOptionalToTs(str: string | number | undefined): Timestamp | undefined {
+  return time.msOptionalToTs(str);
+}
+
+/**
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function msOptionalToNumber(val: string | number | undefined): number | undefined {
+  return time.msOptionalToNumber(val);
+}
+
+/**
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function msToNumber(val: string | number): number {
+  return time.msToNumber(val);
+}
+
+/**
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function tsToDate(ts: Timestamp): Date {
+  return time.tsToDate(ts);
+}
+
+/**
+ * @hidden
+ * @deprecated - meant for internal use only
+ */
+export function optionalTsToDate(ts: Timestamp | null | undefined): Date | undefined {
+  return time.optionalTsToDate(ts);
+}

package/src/{converter/encoding.ts → encoding.ts}

@@ -310,3 +310,17 @@ export class TextEncoder {
     return { written: i, read: inputLength < read ? inputLength : read };
   }
 }
+
+/**
+ * Encode a UTF-8 string into a Uint8Array
+ */
+export function encode(s: string): Uint8Array {
+  return TextEncoder.prototype.encode(s);
+}
+
+/**
+ * Decode a Uint8Array into a UTF-8 string
+ */
+export function decode(a: Uint8Array): string {
+  return TextDecoder.prototype.decode(a);
+}

package/src/errors.ts

@@ -0,0 +1,55 @@
+/**
+ * Thrown from code that receives a value that is unexpected or that it's unable to handle.
+ */
+export class ValueError extends Error {
+  public readonly name: string = 'ValueError';
+
+  constructor(message: string | undefined, public readonly cause?: unknown) {
+    super(message ?? undefined);
+  }
+}
+
+/**
+ * Thrown when a Payload Converter is misconfigured.
+ */
+export class PayloadConverterError extends ValueError {
+  public readonly name: string = 'PayloadConverterError';
+}
+
+/**
+ * Used in different parts of the SDK to note that something unexpected has happened.
+ */
+export class IllegalStateError extends Error {
+  public readonly name: string = 'IllegalStateError';
+}
+
+/**
+ * This exception is thrown in the following cases:
+ *  - Workflow with the same Workflow Id is currently running
+ *  - There is a closed Workflow with the same Workflow Id and the {@link WorkflowOptions.workflowIdReusePolicy}
+ *    is `WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE`
+ *  - There is closed Workflow in the `Completed` state with the same Workflow Id and the {@link WorkflowOptions.workflowIdReusePolicy}
+ *    is `WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY`
+ */
+export class WorkflowExecutionAlreadyStartedError extends Error {
+  public readonly name: string = 'WorkflowExecutionAlreadyStartedError';
+
+  constructor(message: string, public readonly workflowId: string, public readonly workflowType: string) {
+    super(message);
+  }
+}
+
+/**
+ * Thrown when a Workflow with the given Id is not known to Temporal Server.
+ * It could be because:
+ * - Id passed is incorrect
+ * - Workflow is closed (for some calls, e.g. `terminate`)
+ * - Workflow was deleted from the Server after reaching its retention limit
+ */
+export class WorkflowNotFoundError extends Error {
+  public readonly name: string = 'WorkflowNotFoundError';
+
+  constructor(message: string, public readonly workflowId: string, public readonly runId: string | undefined) {
+    super(message);
+  }
+}