@temporalio/common 0.22.0 → 1.0.0-rc.1

package/src/converter/payload-converter.ts

@@ -1,24 +1,22 @@
-import { PayloadConverterError, ValueError } from '@temporalio/internal-workflow-common';
-import {
-  BinaryPayloadConverter,
-  JsonPayloadConverter,
-  PayloadConverterWithEncoding,
-  UndefinedPayloadConverter,
-} from './payload-converters';
-import { METADATA_ENCODING_KEY, Payload, str } from './types';
+import { Payload } from './types';
 
 /**
- * Used by the framework to serialize/deserialize parameters and return values.
+ * Used by the framework to serialize/deserialize data like parameters and return values.
  *
- * This is called inside the [Workflow isolate](https://docs.temporal.io/docs/typescript/determinism).
+ * This is called inside the {@link https://docs.temporal.io/typescript/determinism | Workflow isolate}.
  * To write async code or use Node APIs (or use packages that use Node APIs), use a {@link PayloadCodec}.
  */
 export interface PayloadConverter {
   /**
    * Converts a value to a {@link Payload}.
-   * @param value The value to convert. Example values include the Workflow args sent by the client and the values returned by a Workflow or Activity.
+   *
+   * @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}.
+   *
+   * Should throw {@link ValueError} if unable to convert.
    */
-  toPayload<T>(value: T): Payload | undefined;
+  toPayload<T>(value: T): Payload;
 
   /**
    * Converts a {@link Payload} back to a value.
@@ -26,69 +24,13 @@ export interface PayloadConverter {
   fromPayload<T>(payload: Payload): T;
 }
 
-export class CompositePayloadConverter implements PayloadConverter {
-  readonly converters: PayloadConverterWithEncoding[];
-  readonly converterByEncoding: Map<string, PayloadConverterWithEncoding> = new Map();
-
-  constructor(...converters: 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, or `undefined` if there is no converter that can handle the value.
-   *
-   * @throws UnsupportedJsonTypeError
-   */
-  public toPayload<T>(value: T): Payload | undefined {
-    for (const converter of this.converters) {
-      const result = converter.toPayload(value);
-      if (result !== undefined) {
-        return result;
-      }
-    }
-    return undefined;
-  }
-
-  /**
-   * Run {@link PayloadConverterWithEncoding.fromPayload} based on the {@link encodingTypes | encoding type} 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 = str(payload.metadata[METADATA_ENCODING_KEY]);
-    const converter = this.converterByEncoding.get(encoding);
-    if (converter === undefined) {
-      throw new ValueError(`Unknown encoding: ${encoding}`);
-    }
-    return converter.fromPayload(payload);
-  }
-}
-
-/**
- * Tries to convert `value` to a {@link Payload}. Throws if conversion fails.
- *
- * @throws {@link PayloadConverterError}
- */
-export function toPayload(converter: PayloadConverter, value: unknown): Payload {
-  const payload = converter.toPayload(value);
-  if (payload === undefined) {
-    throw new PayloadConverterError(`Failed to convert value: ${value}`);
-  }
-  return payload;
-}
-
 /**
  * Implements conversion of a list of values.
  *
  * @param converter
  * @param values JS values to convert to Payloads
- * @return converted values
- * @throws PayloadConverterError if conversion of the value passed as parameter failed for any
+ * @return list of {@link Payload}s
+ * @throws {@link ValueError} if conversion of the value passed as parameter failed for any
  *     reason.
  */
 export function toPayloads(converter: PayloadConverter, ...values: unknown[]): Payload[] | undefined {
@@ -96,17 +38,17 @@ export function toPayloads(converter: PayloadConverter, ...values: unknown[]): P
     return undefined;
   }
 
-  return values.map((value) => toPayload(converter, value));
+  return values.map((value) => converter.toPayload(value));
 }
 
 /**
  * Run {@link PayloadConverter.toPayload} on each value in the map.
  *
- * @throws {@link PayloadConverterError} if conversion of any value in the map fails
+ * @throws {@link ValueError} if conversion of any value in the map fails
  */
 export function mapToPayloads<K extends string>(converter: PayloadConverter, map: Record<K, any>): Record<K, Payload> {
   return Object.fromEntries(
-    Object.entries(map).map(([k, v]): [K, Payload] => [k as K, toPayload(converter, v)])
+    Object.entries(map).map(([k, v]): [K, Payload] => [k as K, converter.toPayload(v)])
   ) as Record<K, Payload>;
 }
 
@@ -142,8 +84,8 @@ export function arrayFromPayloads(converter: PayloadConverter, payloads?: Payloa
 export function mapFromPayloads<K extends string>(
   converter: PayloadConverter,
   map?: Record<K, Payload> | null | undefined
-): Record<K, unknown> | undefined {
-  if (map === undefined || map === null) return undefined;
+): Record<K, unknown> | undefined | null {
+  if (map == null) return map;
   return Object.fromEntries(
     Object.entries(map).map(([k, payload]): [K, unknown] => {
       const value = converter.fromPayload(payload as Payload);
@@ -151,27 +93,3 @@ export function mapFromPayloads<K extends string>(
     })
   ) as Record<K, unknown>;
 }
-
-export const searchAttributePayloadConverter = new JsonPayloadConverter();
-
-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 [`JSON.stringify(yourArgOrRetval)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) 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/payload-converters.ts

@@ -1,67 +1,98 @@
-import { errorMessage, UnsupportedJsonTypeError, ValueError } from '@temporalio/internal-workflow-common';
+import { PayloadConverterError, ValueError } from '@temporalio/internal-workflow-common';
+import { JsonPayloadConverter } from './json-payload-converter';
 import { PayloadConverter } from './payload-converter';
-import { encodingKeys, encodingTypes, METADATA_ENCODING_KEY, Payload, str, u8 } from './types';
+import { SearchAttributePayloadConverter } from './search-attribute-payload-converter';
+import { encodingKeys, encodingTypes, METADATA_ENCODING_KEY, Payload, str } from './types';
+
+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;
 
-export interface PayloadConverterWithEncoding extends PayloadConverter {
   readonly encodingType: string;
 }
 
 /**
- * Converts between JS undefined and NULL Payload
+ * 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 UndefinedPayloadConverter implements PayloadConverterWithEncoding {
-  public encodingType = encodingTypes.METADATA_ENCODING_NULL;
+export class CompositePayloadConverter implements PayloadConverter {
+  readonly converters: PayloadConverterWithEncoding[];
+  readonly converterByEncoding: Map<string, PayloadConverterWithEncoding> = new Map();
 
-  public toPayload(value: unknown): Payload | undefined {
-    if (value !== undefined) return undefined; // Can't encode
-    return {
-      metadata: {
-        [METADATA_ENCODING_KEY]: encodingKeys.METADATA_ENCODING_NULL,
-      },
-    };
+  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);
+    }
   }
 
-  public fromPayload<T>(_content: Payload): T {
-    return undefined as any; // Just return undefined
+  /**
+   * 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 {@link encodingTypes | encoding type} 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 = str(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 non-undefined values and serialized JSON Payload
- *
- * @throws UnsupportedJsonTypeError
+ * Converts between JS undefined and NULL Payload
  */
-export class JsonPayloadConverter implements PayloadConverterWithEncoding {
-  public encodingType = encodingTypes.METADATA_ENCODING_JSON;
+export class UndefinedPayloadConverter implements PayloadConverterWithEncoding {
+  public encodingType = encodingTypes.METADATA_ENCODING_NULL;
 
   public toPayload(value: unknown): Payload | undefined {
-    if (value === undefined) return undefined;
-
-    let json;
-    try {
-      json = JSON.stringify(value);
-    } catch (e) {
-      throw new UnsupportedJsonTypeError(
-        `Can't run JSON.stringify on this value: ${value}. Either convert it (or its properties) to JSON-serializable values (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description ), or use a custom data converter: https://docs.temporal.io/docs/typescript/data-converters . JSON.stringify error message: ${errorMessage(
-          e
-        )}`,
-        e as Error
-      );
+    if (value !== undefined) {
+      return undefined;
     }
 
     return {
       metadata: {
-        [METADATA_ENCODING_KEY]: encodingKeys.METADATA_ENCODING_JSON,
+        [METADATA_ENCODING_KEY]: encodingKeys.METADATA_ENCODING_NULL,
       },
-      data: u8(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(str(content.data));
+  public fromPayload<T>(_content: Payload): T {
+    return undefined as any; // Just return undefined
   }
 }
 
@@ -73,7 +104,10 @@ export class BinaryPayloadConverter implements PayloadConverterWithEncoding {
 
   public toPayload(value: unknown): Payload | undefined {
     // TODO: support any DataView or ArrayBuffer?
-    if (!(value instanceof Uint8Array)) return undefined;
+    if (!(value instanceof Uint8Array)) {
+      return undefined;
+    }
+
     return {
       metadata: {
         [METADATA_ENCODING_KEY]: encodingKeys.METADATA_ENCODING_RAW,
@@ -87,3 +121,28 @@ export class BinaryPayloadConverter implements PayloadConverterWithEncoding {
     return content.data as any;
   }
 }
+
+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

@@ -8,10 +8,10 @@ import {
 } from '@temporalio/internal-workflow-common';
 import * as protoJsonSerializer from 'proto3-json-serializer';
 import type { Message, Namespace, Root, Type } from 'protobufjs';
-import { CompositePayloadConverter } from './payload-converter';
+import { JsonPayloadConverter } from './json-payload-converter';
 import {
   BinaryPayloadConverter,
-  JsonPayloadConverter,
+  CompositePayloadConverter,
   PayloadConverterWithEncoding,
   UndefinedPayloadConverter,
 } from './payload-converters';
@@ -96,7 +96,9 @@ export class ProtobufBinaryPayloadConverter extends ProtobufPayloadConverter {
   }
 
   public toPayload(value: unknown): Payload | undefined {
-    if (!isProtobufMessage(value)) return undefined;
+    if (!isProtobufMessage(value)) {
+      return undefined;
+    }
 
     return this.constructPayload({
       messageTypeName: getNamespacedTypeName(value.$type),
@@ -124,7 +126,9 @@ export class ProtobufJsonPayloadConverter extends ProtobufPayloadConverter {
   }
 
   public toPayload(value: unknown): Payload | undefined {
-    if (!isProtobufMessage(value)) return undefined;
+    if (!isProtobufMessage(value)) {
+      return undefined;
+    }
 
     const jsonValue = protoJsonSerializer.toProto3JSON(value);
 

package/src/converter/search-attribute-payload-converter.ts

@@ -0,0 +1,71 @@
+import { IllegalStateError, ValueError } from '@temporalio/internal-workflow-common';
+import { PayloadConverter } from './payload-converter';
+import { JsonPayloadConverter } from './json-payload-converter';
+import { Payload, str } from './types';
+
+const jsonConverter = new JsonPayloadConverter();
+const validNonDateTypes = ['string', 'number', 'boolean'];
+
+/**
+ * Converts Search Attribute values using JsonPayloadConverter
+ */
+export class SearchAttributePayloadConverter implements PayloadConverter {
+  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 (!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 = 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 = jsonConverter.fromPayload(payload);
+    let arrayWrappedValue = value instanceof Array ? value : [value];
+
+    const searchAttributeType = str(payload.metadata.type);
+    if (searchAttributeType === 'Datetime') {
+      arrayWrappedValue = arrayWrappedValue.map((dateString) => new Date(dateString));
+    }
+    return arrayWrappedValue as unknown as T;
+  }
+}

package/src/converter/types.ts

@@ -1,7 +1,6 @@
-import type { coresdk } from '@temporalio/proto';
 import { TextDecoder, TextEncoder } from './encoding';
 
-export type Payload = coresdk.common.IPayload;
+export { Payload } from '@temporalio/internal-workflow-common';
 
 /**
  * Transform an *ascii* string into a Uint8Array