@temporalio/common 1.11.7 → 1.12.0-rc.0

package/src/search-attributes.ts

@@ -0,0 +1,292 @@
+import type { temporal } from '@temporalio/proto';
+import { makeProtoEnumConverters } from './internal-workflow';
+
+/** @deprecated: Use {@link TypedSearchAttributes} instead */
+export type SearchAttributeValueOrReadonly = SearchAttributeValue | Readonly<SearchAttributeValue> | undefined; // eslint-disable-line deprecation/deprecation
+/** @deprecated: Use {@link TypedSearchAttributes} instead */
+export type SearchAttributes = Record<string, SearchAttributeValueOrReadonly>; // eslint-disable-line deprecation/deprecation
+/** @deprecated: Use {@link TypedSearchAttributes} instead */
+export type SearchAttributeValue = string[] | number[] | boolean[] | Date[]; // eslint-disable-line deprecation/deprecation
+
+export const SearchAttributeType = {
+  TEXT: 'TEXT',
+  KEYWORD: 'KEYWORD',
+  INT: 'INT',
+  DOUBLE: 'DOUBLE',
+  BOOL: 'BOOL',
+  DATETIME: 'DATETIME',
+  KEYWORD_LIST: 'KEYWORD_LIST',
+} as const;
+
+export type SearchAttributeType = (typeof SearchAttributeType)[keyof typeof SearchAttributeType];
+
+// Note: encodeSearchAttributeIndexedValueType exported for use in tests to register search attributes
+// ts-prune-ignore-next
+export const [encodeSearchAttributeIndexedValueType, _] = makeProtoEnumConverters<
+  temporal.api.enums.v1.IndexedValueType,
+  typeof temporal.api.enums.v1.IndexedValueType,
+  keyof typeof temporal.api.enums.v1.IndexedValueType,
+  typeof SearchAttributeType,
+  'INDEXED_VALUE_TYPE_'
+>(
+  {
+    [SearchAttributeType.TEXT]: 1,
+    [SearchAttributeType.KEYWORD]: 2,
+    [SearchAttributeType.INT]: 3,
+    [SearchAttributeType.DOUBLE]: 4,
+    [SearchAttributeType.BOOL]: 5,
+    [SearchAttributeType.DATETIME]: 6,
+    [SearchAttributeType.KEYWORD_LIST]: 7,
+    UNSPECIFIED: 0,
+  } as const,
+  'INDEXED_VALUE_TYPE_'
+);
+
+interface IndexedValueTypeMapping {
+  TEXT: string;
+  KEYWORD: string;
+  INT: number;
+  DOUBLE: number;
+  BOOL: boolean;
+  DATETIME: Date;
+  KEYWORD_LIST: string[];
+}
+
+export function isValidValueForType<T extends SearchAttributeType>(
+  type: T,
+  value: unknown
+): value is IndexedValueTypeMapping[T] {
+  switch (type) {
+    case SearchAttributeType.TEXT:
+    case SearchAttributeType.KEYWORD:
+      return typeof value === 'string';
+    case SearchAttributeType.INT:
+      return Number.isInteger(value);
+    case SearchAttributeType.DOUBLE:
+      return typeof value === 'number';
+    case SearchAttributeType.BOOL:
+      return typeof value === 'boolean';
+    case SearchAttributeType.DATETIME:
+      return value instanceof Date;
+    case SearchAttributeType.KEYWORD_LIST:
+      return Array.isArray(value) && value.every((item) => typeof item === 'string');
+    default:
+      return false;
+  }
+}
+
+export interface SearchAttributeKey<T extends SearchAttributeType> {
+  name: string;
+  type: T;
+}
+
+export function defineSearchAttributeKey<T extends SearchAttributeType>(name: string, type: T): SearchAttributeKey<T> {
+  return { name, type };
+}
+
+class BaseSearchAttributeValue<T extends SearchAttributeType, V = IndexedValueTypeMapping[T]> {
+  private readonly _type: T;
+  private readonly _value: V;
+
+  constructor(type: T, value: V) {
+    this._type = type;
+    this._value = value;
+  }
+
+  get type(): T {
+    return this._type;
+  }
+
+  get value(): V {
+    return this._value;
+  }
+}
+
+// Internal type for class private data.
+// Exported for use in payload conversion.
+export class TypedSearchAttributeValue<T extends SearchAttributeType> extends BaseSearchAttributeValue<T> {}
+// ts-prune-ignore-next
+export class TypedSearchAttributeUpdateValue<T extends SearchAttributeType> extends BaseSearchAttributeValue<
+  T,
+  IndexedValueTypeMapping[T] | null
+> {}
+
+export type SearchAttributePair = {
+  [T in SearchAttributeType]: { key: SearchAttributeKey<T>; value: IndexedValueTypeMapping[T] };
+}[SearchAttributeType];
+
+export type SearchAttributeUpdatePair = {
+  [T in SearchAttributeType]: { key: SearchAttributeKey<T>; value: IndexedValueTypeMapping[T] | null };
+}[SearchAttributeType];
+
+export class TypedSearchAttributes {
+  private searchAttributes: Record<string, TypedSearchAttributeValue<SearchAttributeType>> = {};
+
+  constructor(initialAttributes?: SearchAttributePair[]) {
+    if (initialAttributes === undefined) return;
+    for (const pair of initialAttributes) {
+      if (pair.key.name in this.searchAttributes) {
+        throw new Error(`Duplicate search attribute key: ${pair.key.name}`);
+      }
+      this.searchAttributes[pair.key.name] = new TypedSearchAttributeValue(pair.key.type, pair.value);
+    }
+  }
+
+  get<T extends SearchAttributeType>(key: SearchAttributeKey<T>): IndexedValueTypeMapping[T] | undefined {
+    const attr = this.searchAttributes[key.name];
+    // Key not found or type mismatch.
+    if (attr === undefined || !isValidValueForType(key.type, attr.value)) {
+      return undefined;
+    }
+    return attr.value;
+  }
+
+  /** Returns a deep copy of the given TypedSearchAttributes instance */
+  copy(): TypedSearchAttributes {
+    const state: Record<string, TypedSearchAttributeValue<SearchAttributeType>> = {};
+
+    for (const [key, attr] of Object.entries(this.searchAttributes)) {
+      // Create a new instance with the same properties
+      let value = attr.value;
+      // For non-primitive types, create a deep copy
+      if (attr.value instanceof Date) {
+        value = new Date(attr.value);
+      } else if (Array.isArray(attr.value)) {
+        value = [...attr.value];
+      }
+      state[key] = new TypedSearchAttributeValue(attr.type, value);
+    }
+
+    // Create return value with manually assigned state.
+    const res = new TypedSearchAttributes();
+    res.searchAttributes = state;
+    return res;
+  }
+
+  /**
+   * @hidden
+   * Return JSON representation of this class as SearchAttributePair[]
+   * Default toJSON method is not used because it's JSON representation includes private state.
+   */
+  toJSON(): SearchAttributePair[] {
+    return this.getAll();
+  }
+
+  /** Returns a copy of the current TypedSearchAttributes instance with the updated attributes. */
+  updateCopy(updates: SearchAttributeUpdatePair[]): TypedSearchAttributes {
+    // Create a deep copy of the current instance.
+    const res = this.copy();
+    // Apply updates.
+    res.update(updates);
+    return res;
+  }
+
+  // Performs direct mutation on the current instance.
+  private update(updates: SearchAttributeUpdatePair[]) {
+    // Apply updates.
+    for (const pair of updates) {
+      // Delete attribute.
+      if (pair.value === null) {
+        // Delete only if the update matches a key and type.
+        const attrVal = this.searchAttributes[pair.key.name];
+        if (attrVal && attrVal.type === pair.key.type) {
+          delete this.searchAttributes[pair.key.name];
+        }
+        continue;
+      }
+      // Add or update attribute.
+      this.searchAttributes[pair.key.name] = new TypedSearchAttributeValue(pair.key.type, pair.value);
+    }
+  }
+
+  getAll(): SearchAttributePair[] {
+    const res: SearchAttributePair[] = [];
+    for (const [key, attr] of Object.entries(this.searchAttributes)) {
+      const attrKey = { name: key, type: attr.type };
+      // Sanity check, should always be legal.
+      if (isValidValueForType(attrKey.type, attr.value)) {
+        res.push({ key: attrKey, value: attr.value } as SearchAttributePair);
+      }
+    }
+    return res;
+  }
+
+  static getKeyFromUntyped(
+    key: string,
+    value: SearchAttributeValueOrReadonly // eslint-disable-line deprecation/deprecation
+  ): SearchAttributeKey<SearchAttributeType> | undefined {
+    if (value == null) {
+      return;
+    }
+
+    // Unpack single-element arrays.
+    const val = value.length === 1 ? value[0] : value;
+    switch (typeof val) {
+      case 'string':
+        // Check if val is an ISO string, if so, return a DATETIME key.
+        if (!isNaN(Date.parse(val)) && Date.parse(val) === new Date(val).getTime()) {
+          return { name: key, type: SearchAttributeType.DATETIME };
+        }
+        return { name: key, type: SearchAttributeType.TEXT };
+      case 'number':
+        return {
+          name: key,
+          type: Number.isInteger(val) ? SearchAttributeType.INT : SearchAttributeType.DOUBLE,
+        };
+      case 'boolean':
+        return { name: key, type: SearchAttributeType.BOOL };
+      case 'object':
+        if (val instanceof Date) {
+          return { name: key, type: SearchAttributeType.DATETIME };
+        }
+        if (Array.isArray(val) && val.every((item) => typeof item === 'string')) {
+          return { name: key, type: SearchAttributeType.KEYWORD_LIST };
+        }
+        return;
+      default:
+        return;
+    }
+  }
+
+  static toMetadataType(type: SearchAttributeType): string {
+    switch (type) {
+      case SearchAttributeType.TEXT:
+        return 'Text';
+      case SearchAttributeType.KEYWORD:
+        return 'Keyword';
+      case SearchAttributeType.INT:
+        return 'Int';
+      case SearchAttributeType.DOUBLE:
+        return 'Double';
+      case SearchAttributeType.BOOL:
+        return 'Bool';
+      case SearchAttributeType.DATETIME:
+        return 'Datetime';
+      case SearchAttributeType.KEYWORD_LIST:
+        return 'KeywordList';
+      default:
+        throw new Error(`Unknown search attribute type: ${type}`);
+    }
+  }
+
+  static toSearchAttributeType(type: string): SearchAttributeType | undefined {
+    switch (type) {
+      case 'Text':
+        return SearchAttributeType.TEXT;
+      case 'Keyword':
+        return SearchAttributeType.KEYWORD;
+      case 'Int':
+        return SearchAttributeType.INT;
+      case 'Double':
+        return SearchAttributeType.DOUBLE;
+      case 'Bool':
+        return SearchAttributeType.BOOL;
+      case 'Datetime':
+        return SearchAttributeType.DATETIME;
+      case 'KeywordList':
+        return SearchAttributeType.KEYWORD_LIST;
+      default:
+        return;
+    }
+  }
+}

package/src/type-helpers.ts

@@ -1,9 +1,20 @@
+export type NonNullableObject<T> = { [P in keyof T]-?: NonNullable<T[P]> };
+
 /** Shorthand alias */
 export type AnyFunc = (...args: any[]) => any;
+
 /** A tuple without its last element */
 export type OmitLast<T> = T extends [...infer REST, any] ? REST : never;
+
 /** F with all arguments but the last */
 export type OmitLastParam<F extends AnyFunc> = (...args: OmitLast<Parameters<F>>) => ReturnType<F>;
+
+export type OmitFirst<T> = T extends [any, ...infer REST] ? REST : never;
+
+export type OmitFirstParam<T> = T extends (...args: any[]) => any
+  ? (...args: OmitFirst<Parameters<T>>) => ReturnType<T>
+  : never;
+
 /** Require that T has at least one of the provided properties defined */
 export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> &
   {
@@ -218,26 +229,3 @@ export function SymbolBasedInstanceOfError<E extends Error>(markerName: string):
     });
   };
 }
-
-// Thanks MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze
-export function deepFreeze<T>(object: T): T {
-  // Retrieve the property names defined on object
-  const propNames = Object.getOwnPropertyNames(object);
-
-  // Freeze properties before freezing self
-  for (const name of propNames) {
-    const value = (object as any)[name];
-
-    if (value && typeof value === 'object') {
-      try {
-        deepFreeze(value);
-      } catch (_err) {
-        // This is okay, there are some typed arrays that cannot be frozen (encodingKeys)
-      }
-    } else if (typeof value === 'function') {
-      Object.freeze(value);
-    }
-  }
-
-  return Object.freeze(object);
-}

package/src/versioning-intent-enum.ts

@@ -7,7 +7,7 @@ import { assertNever, checkExtends } from './type-helpers';
 /**
  * Protobuf enum representation of {@link VersioningIntentString}.
  *
- * @experimental
+ * @experimental The Worker Versioning API is still being designed. Major changes are expected.
  */
 export enum VersioningIntent {
   UNSPECIFIED = 0,

package/src/versioning-intent.ts

@@ -11,6 +11,6 @@
  * current worker. The default behavior for starting Workflows is `DEFAULT`. The default behavior for Workflows starting
  * Activities, starting Child Workflows, or Continuing As New is `COMPATIBLE`.
  *
- * @experimental
+ * @experimental The Worker Versioning API is still being designed. Major changes are expected.
  */
 export type VersioningIntent = 'COMPATIBLE' | 'DEFAULT';

package/src/worker-deployments.ts

@@ -0,0 +1,70 @@
+import type { temporal } from '@temporalio/proto';
+import { makeProtoEnumConverters } from './internal-workflow';
+
+/**
+ * Represents the version of a specific worker deployment.
+ *
+ * @experimental Deployment based versioning is experimental and may change in the future.
+ */
+export interface WorkerDeploymentVersion {
+  readonly buildId: string;
+  readonly deploymentName: string;
+}
+
+/**
+ * @returns The canonical representation of a deployment version, which is a string in the format
+ * `deploymentName.buildId`.
+ */
+export function toCanonicalString(version: WorkerDeploymentVersion): string {
+  return `${version.deploymentName}.${version.buildId}`;
+}
+
+/**
+ * Specifies when a workflow might move from a worker of one Build Id to another.
+ *
+ * * 'PINNED' - The workflow will be pinned to the current Build ID unless manually moved.
+ * * 'AUTO_UPGRADE' - The workflow will automatically move to the latest version (default Build ID
+ *    of the task queue) when the next task is dispatched.
+ *
+ * @experimental Deployment based versioning is experimental and may change in the future.
+ */
+export const VersioningBehavior = {
+  PINNED: 'PINNED',
+  AUTO_UPGRADE: 'AUTO_UPGRADE',
+} as const;
+export type VersioningBehavior = (typeof VersioningBehavior)[keyof typeof VersioningBehavior];
+
+export const [encodeVersioningBehavior, decodeVersioningBehavior] = makeProtoEnumConverters<
+  temporal.api.enums.v1.VersioningBehavior,
+  typeof temporal.api.enums.v1.VersioningBehavior,
+  keyof typeof temporal.api.enums.v1.VersioningBehavior,
+  typeof VersioningBehavior,
+  'VERSIONING_BEHAVIOR_'
+>(
+  {
+    [VersioningBehavior.PINNED]: 1,
+    [VersioningBehavior.AUTO_UPGRADE]: 2,
+    UNSPECIFIED: 0,
+  } as const,
+  'VERSIONING_BEHAVIOR_'
+);
+
+/**
+ * Represents versioning overrides. For example, when starting workflows.
+ */
+export type VersioningOverride = PinnedVersioningOverride | 'AUTO_UPGRADE';
+
+/**
+ * Workflow will be pinned to a specific deployment version.
+ */
+export interface PinnedVersioningOverride {
+  /**
+   * The worker deployment version to pin the workflow to.
+   */
+  pinnedTo: WorkerDeploymentVersion;
+}
+
+/**
+ * The workflow will auto-upgrade to the current deployment version on the next workflow task.
+ */
+export type AutoUpgradeVersioningOverride = 'AUTO_UPGRADE';

package/src/workflow-definition-options.ts

@@ -0,0 +1,20 @@
+import { VersioningBehavior } from './worker-deployments';
+
+/**
+ * Options that can be used when defining a workflow via {@link setWorkflowOptions}.
+ */
+export interface WorkflowDefinitionOptions {
+  versioningBehavior?: VersioningBehavior;
+}
+
+type AsyncFunction<Args extends any[], ReturnType> = (...args: Args) => Promise<ReturnType>;
+export type WorkflowDefinitionOptionsOrGetter = WorkflowDefinitionOptions | (() => WorkflowDefinitionOptions);
+
+/**
+ * @internal
+ * @hidden
+ * A workflow function that has been defined with options from {@link WorkflowDefinitionOptions}.
+ */
+export interface WorkflowFunctionWithOptions<Args extends any[], ReturnType> extends AsyncFunction<Args, ReturnType> {
+  workflowDefinitionOptions: WorkflowDefinitionOptionsOrGetter;
+}

package/src/workflow-options.ts

@@ -1,8 +1,11 @@
 import type { temporal } from '@temporalio/proto';
-import { SearchAttributes, Workflow } from './interfaces';
+import { Workflow } from './interfaces';
 import { RetryPolicy } from './retry-policy';
 import { Duration } from './time';
 import { makeProtoEnumConverters } from './internal-workflow';
+import { SearchAttributePair, SearchAttributes, TypedSearchAttributes } from './search-attributes';
+import { Priority } from './priority';
+import { WorkflowFunctionWithOptions } from './workflow-definition-options';
 
 /**
  * Defines what happens when trying to start a Workflow with the same ID as a *Closed* Workflow.
@@ -173,8 +176,27 @@ export interface BaseWorkflowOptions {
    * https://docs.temporal.io/docs/typescript/search-attributes
    *
    * Values are always converted using {@link JsonPayloadConverter}, even when a custom data converter is provided.
+   *
+   * @deprecated Use {@link typedSearchAttributes} instead.
+   */
+  searchAttributes?: SearchAttributes; // eslint-disable-line deprecation/deprecation
+
+  /**
+   * Specifies additional indexed information to attach to the Workflow Execution. More info:
+   * https://docs.temporal.io/docs/typescript/search-attributes
+   *
+   * Values are always converted using {@link JsonPayloadConverter}, even when a custom data converter is provided.
+   * Note that search attributes are not encoded, as such, do not include any sensitive information.
+   *
+   * If both {@link searchAttributes} and {@link typedSearchAttributes} are provided, conflicting keys will be overwritten
+   * by {@link typedSearchAttributes}.
+   */
+  typedSearchAttributes?: SearchAttributePair[] | TypedSearchAttributes;
+
+  /**
+   * Priority of a workflow
    */
-  searchAttributes?: SearchAttributes;
+  priority?: Priority;
 }
 
 export type WithWorkflowArgs<W extends Workflow, T> = T &
@@ -222,7 +244,9 @@ export interface WorkflowDurationOptions {
 
 export type CommonWorkflowOptions = BaseWorkflowOptions & WorkflowDurationOptions;
 
-export function extractWorkflowType<T extends Workflow>(workflowTypeOrFunc: string | T): string {
+export function extractWorkflowType<T extends Workflow>(
+  workflowTypeOrFunc: string | T | WorkflowFunctionWithOptions<any[], any>
+): string {
   if (typeof workflowTypeOrFunc === 'string') return workflowTypeOrFunc as string;
   if (typeof workflowTypeOrFunc === 'function') {
     if (workflowTypeOrFunc?.name) return workflowTypeOrFunc.name;

package/lib/internal-non-workflow/utils.d.ts

@@ -1,4 +0,0 @@
-/**
- * Helper to prevent undefined and null values overriding defaults when merging maps
- */
-export declare function filterNullAndUndefined<T extends Record<string, any>>(obj: T): T;

package/lib/internal-non-workflow/utils.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.filterNullAndUndefined = filterNullAndUndefined;
-/**
- * Helper to prevent undefined and null values overriding defaults when merging maps
- */
-function filterNullAndUndefined(obj) {
-    return Object.fromEntries(Object.entries(obj).filter(([_k, v]) => v != null));
-}
-//# sourceMappingURL=utils.js.map

package/lib/internal-non-workflow/utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/internal-non-workflow/utils.ts"],"names":[],"mappings":";;AAGA,wDAEC;AALD;;GAEG;AACH,SAAgB,sBAAsB,CAAgC,GAAM;IAC1E,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAQ,CAAC;AACvF,CAAC"}

package/src/internal-non-workflow/utils.ts

@@ -1,6 +0,0 @@
-/**
- * Helper to prevent undefined and null values overriding defaults when merging maps
- */
-export function filterNullAndUndefined<T extends Record<string, any>>(obj: T): T {
-  return Object.fromEntries(Object.entries(obj).filter(([_k, v]) => v != null)) as any;
-}