@temporalio/common 0.18.0 → 0.19.0

package/src/errors.ts

@@ -1,60 +0,0 @@
-export class ValueError extends Error {
-  public readonly name: string = 'ValueError';
-}
-
-export class DataConverterError extends Error {
-  public readonly name: string = 'DataConverterError';
-}
-
-/**
- * Used in different parts of the project to signal 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 WorkflowId is currently running
- *  - There is a closed workflow with the same ID and the {@link WorkflowOptions.workflowIdReusePolicy}
- *    is `WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE`
- *  - There is successfully closed workflow with the same ID and the {@link WorkflowOptions.workflowIdReusePolicy}
- *    is `WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY`
- *  - {@link Workflow.execute} is called *more than once* on a handle created through {@link createChildWorkflowHandle} and the
- *    {@link WorkflowOptions.workflowIdReusePolicy} is `WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE`
- */
-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 workflow with the given id is not known to the Temporal service.
- * It could be because:
- * - ID passed is incorrect
- * - Workflow execution is complete (for some calls e.g. terminate),
- * - workflow was purged from the service 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);
-  }
-}
-
-/**
- * Get error message from an Error or string or return undefined
- */
-export function errorMessage(err: unknown): string | undefined {
-  if (typeof err === 'string') {
-    return err;
-  }
-  if (err instanceof Error) {
-    return err.message;
-  }
-  return undefined;
-}

package/src/interceptors.ts

@@ -1,32 +0,0 @@
-import type { coresdk } from '@temporalio/proto/lib/coresdk';
-import { AnyFunc, OmitLastParam } from './type-helpers';
-
-/**
- * Type of the next function for a given interceptor function
- *
- * Called from an interceptor to continue the interception chain
- */
-export type Next<IF, FN extends keyof IF> = Required<IF>[FN] extends AnyFunc ? OmitLastParam<Required<IF>[FN]> : never;
-
-/** Headers are just a mapping of header name to Payload */
-export type Headers = Record<string, coresdk.common.IPayload>;
-
-/**
- * Composes all interceptor methods into a single function
- *
- * @param interceptors a list of interceptors
- * @param method the name of the interceptor method to compose
- * @param next the original function to be executed at the end of the interception chain
- */
-export function composeInterceptors<I, M extends keyof I>(interceptors: I[], method: M, next: Next<I, M>): Next<I, M> {
-  for (let i = interceptors.length - 1; i >= 0; --i) {
-    const interceptor = interceptors[i];
-    if (interceptor[method] !== undefined) {
-      const prev = next;
-      // We loose type safety here because Typescript can't deduce that interceptor[method] is a function that returns
-      // the same type as Next<I, M>
-      next = ((input: any) => (interceptor[method] as any)(input, prev)) as any;
-    }
-  }
-  return next;
-}

package/src/interfaces.ts

@@ -1,37 +0,0 @@
-/** Type that can be returned from a Workflow `execute` function */
-export type WorkflowReturnType = Promise<any>;
-export type WorkflowSignalType = (...args: any[]) => Promise<void> | void;
-export type WorkflowQueryType = (...args: any[]) => any;
-
-/**
- * Broad Workflow function definition, specific Workflows will typically use a narrower type definition, e.g:
- * ```ts
- * export async function myWorkflow(arg1: number, arg2: string): Promise<string>;
- * ```
- */
-export type Workflow = (...args: any[]) => WorkflowReturnType;
-
-/**
- * An interface representing a Workflow signal definition, as returned from {@link defineSignal}
- *
- * @remarks `_Args` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export interface SignalDefinition<_Args extends any[] = []> {
-  type: 'signal';
-  name: string;
-}
-
-/**
- * An interface representing a Workflow query definition as returned from {@link defineQuery}
- *
- * @remarks `_Args` and `_Ret` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export interface QueryDefinition<_Ret, _Args extends any[] = []> {
-  type: 'query';
-  name: string;
-}
-
-/** Get the "unwrapped" return type (without Promise) of the execute handler from Workflow type `W` */
-export type WorkflowResultType<W extends Workflow> = ReturnType<W> extends Promise<infer R> ? R : never;

package/src/otel.ts

@@ -1,61 +0,0 @@
-import * as otel from '@opentelemetry/api';
-import { defaultDataConverter } from './converter/data-converter';
-import { Headers } from './interceptors';
-
-/** Default trace header for opentelemetry interceptors */
-export const TRACE_HEADER = '_tracer-data';
-/** As in workflow run id */
-export const RUN_ID_ATTR_KEY = 'run_id';
-/** For a workflow or activity task */
-export const TASK_TOKEN_ATTR_KEY = 'task_token';
-/** Number of jobs in a workflow activation */
-export const NUM_JOBS_ATTR_KEY = 'num_jobs';
-
-/**
- * If found, return an otel Context deserialized from the provided headers
- */
-export async function extractContextFromHeaders(headers: Headers): Promise<otel.Context | undefined> {
-  const encodedSpanContext = headers[TRACE_HEADER];
-  if (encodedSpanContext === undefined) {
-    return undefined;
-  }
-  const textMap: Record<string, string> = await defaultDataConverter.fromPayload(encodedSpanContext);
-  return otel.propagation.extract(otel.context.active(), textMap, otel.defaultTextMapGetter);
-}
-
-/**
- * If found, return an otel SpanContext deserialized from the provided headers
- */
-export async function extractSpanContextFromHeaders(headers: Headers): Promise<otel.SpanContext | undefined> {
-  const context = await extractContextFromHeaders(headers);
-  if (context === undefined) {
-    return undefined;
-  }
-
-  return otel.trace.getSpanContext(context);
-}
-
-/**
- * Given headers, return new headers with the current otel context inserted
- */
-export async function headersWithContext(headers: Headers): Promise<Headers> {
-  const carrier = {};
-  otel.propagation.inject(otel.context.active(), carrier, otel.defaultTextMapSetter);
-  return { ...headers, [TRACE_HEADER]: await defaultDataConverter.toPayload(carrier) };
-}
-
-/**
- * Link a span to an maybe-existing span context
- */
-export function linkSpans(fromSpan: otel.Span, toContext?: otel.SpanContext): void {
-  if (toContext !== undefined) {
-    // TODO: I have to go around typescript because otel api 😢
-    //  See https://github.com/open-telemetry/opentelemetry-js-api/issues/124
-    const links = (fromSpan as any).links;
-    if (links === undefined) {
-      (fromSpan as any).links = [{ context: toContext }];
-    } else {
-      links.push({ context: toContext });
-    }
-  }
-}

package/src/retry-policy.ts

@@ -1,73 +0,0 @@
-import type { temporal } from '@temporalio/proto';
-import { ValueError } from '.';
-import { msOptionalToNumber, msOptionalToTs, msToNumber, msToTs } from './time';
-
-/**
- * Options for retrying Workflows and Activities
- */
-export interface RetryPolicy {
-  /**
-   * Coefficient used to calculate the next retry interval.
-   * The next retry interval is previous interval multiplied by this coefficient.
-   * @minimum 1
-   * @default 2
-   */
-  backoffCoefficient?: number;
-  /**
-   * Interval of the first retry.
-   * If coefficient is 1 then it is used for all retries
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
-   * @default 1 second
-   */
-  initialInterval?: string | number;
-  /**
-   * Maximum number of attempts. When exceeded the retries stop even if not expired yet.
-   * @minimum 1
-   * @default Infinity
-   */
-  maximumAttempts?: number;
-  /**
-   * Maximum interval between retries.
-   * Exponential backoff leads to interval increase.
-   * This value is the cap of the increase.
-   *
-   * @default 100x of {@link initialInterval}
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
-   */
-  maximumInterval?: string | number;
-
-  /**
-   * List of application failures types to not retry.
-   */
-  nonRetryableErrorTypes?: string[];
-}
-
-/**
- * Turns a TS RetryPolicy into a proto compatible RetryPolicy
- */
-export function compileRetryPolicy(retryPolicy: RetryPolicy): temporal.api.common.v1.IRetryPolicy {
-  if (retryPolicy.backoffCoefficient != null && retryPolicy.backoffCoefficient <= 0) {
-    throw new ValueError('RetryPolicy.backoffCoefficient must be greater than 0');
-  }
-  if (retryPolicy.maximumAttempts != null && retryPolicy.maximumAttempts <= 0) {
-    throw new ValueError('RetryPolicy.maximumAttempts must be greater than 0');
-  }
-  const maximumInterval = msOptionalToNumber(retryPolicy.maximumInterval);
-  const initialInterval = msToNumber(retryPolicy.initialInterval ?? 1000);
-  if (maximumInterval === 0) {
-    throw new ValueError('RetryPolicy.maximumInterval cannot be 0');
-  }
-  if (initialInterval === 0) {
-    throw new ValueError('RetryPolicy.initialInterval cannot be 0');
-  }
-  if (maximumInterval != null && maximumInterval < initialInterval) {
-    throw new ValueError('RetryPolicy.maximumInterval cannot be less than its initialInterval');
-  }
-  return {
-    maximumAttempts: retryPolicy.maximumAttempts,
-    initialInterval: msToTs(initialInterval),
-    maximumInterval: msOptionalToTs(maximumInterval),
-    backoffCoefficient: retryPolicy.backoffCoefficient,
-    nonRetryableErrorTypes: retryPolicy.nonRetryableErrorTypes,
-  };
-}

package/src/time.ts

@@ -1,76 +0,0 @@
-import Long from 'long';
-import ms from 'ms';
-import type * as iface from '@temporalio/proto/lib/coresdk';
-import { ValueError } from './errors';
-
-// NOTE: these are the same interface in JS
-// iface.google.protobuf.IDuration;
-// iface.google.protobuf.ITimestamp;
-// The conversion functions below should work for both
-
-export type Timestamp = iface.google.protobuf.ITimestamp;
-
-/**
- * Lossy conversion function from Timestamp to number due to possible overflow.
- * If ts is null or undefined returns undefined.
- */
-export function optionalTsToMs(ts: Timestamp | null | undefined): number | undefined {
-  if (ts === undefined || ts === null) {
-    return undefined;
-  }
-  return tsToMs(ts);
-}
-
-/**
- * Lossy conversion function from Timestamp to number due to possible overflow
- */
-export function tsToMs(ts: Timestamp | null | undefined): number {
-  if (ts === undefined || ts === null) {
-    throw new Error(`Expected timestamp, got ${ts}`);
-  }
-  const { seconds, nanos } = ts;
-  return (seconds || Long.UZERO)
-    .mul(1000)
-    .add(Math.floor((nanos || 0) / 1000000))
-    .toNumber();
-}
-
-export function msNumberToTs(millis: number): Timestamp {
-  const seconds = Math.floor(millis / 1000);
-  const nanos = (millis % 1000) * 1000000;
-  if (Number.isNaN(seconds) || Number.isNaN(nanos)) {
-    throw new ValueError(`Invalid millis ${millis}`);
-  }
-  return { seconds: Long.fromNumber(seconds), nanos };
-}
-
-export function falsyMsToTs(str: string | number | undefined): Timestamp | undefined {
-  return str ? msToTs(str) : undefined;
-}
-
-export function msToTs(str: string | number): Timestamp {
-  if (typeof str === 'number') {
-    return msNumberToTs(str);
-  }
-  return msNumberToTs(ms(str));
-}
-
-export function msOptionalToTs(str: string | number | undefined): Timestamp | undefined {
-  if (str === undefined) return undefined;
-  if (typeof str === 'number') {
-    return msNumberToTs(str);
-  }
-  return msNumberToTs(ms(str));
-}
-
-export function msOptionalToNumber(val: string | number | undefined): number | undefined {
-  if (val === undefined) return undefined;
-  return msToNumber(val);
-}
-
-export function msToNumber(val: string | number): number {
-  if (typeof val === 'number') {
-    return val;
-  }
-  return ms(val);
-}

package/src/tls-config.ts

@@ -1,35 +0,0 @@
-/** TLS configuration options. */
-export interface TLSConfig {
-  /**
-   * Overrides the target name used for SSL host name checking.
-   * If this attribute is not specified, the name used for SSL host name checking will be the host from {@link ServerOptions.url}.
-   * This _should_ be used for testing only.
-   */
-  serverNameOverride?: string;
-  /**
-   * Root CA certificate used by the server. If not set, and the server's
-   * cert is issued by someone the operating system trusts, verification will still work (ex: Cloud offering).
-   */
-  serverRootCACertificate?: Buffer;
-  /** Sets the client certificate and key for connecting with mTLS */
-  clientCertPair?: {
-    /** The certificate for this client */
-    crt: Buffer;
-    /** The private key for this client */
-    key: Buffer;
-  };
-}
-
-/**
- * TLS configuration.
- * Pass a falsy value to use a non-encrypted connection or `true` or `{}` to
- * connect with TLS without any customization.
- */
-export type TLSConfigOption = TLSConfig | boolean | null;
-
-/**
- * Normalize {@link TLSConfigOption} by turning false and null to undefined and true to and empty object
- */
-export function normalizeTlsConfig(tls?: TLSConfigOption): TLSConfig | undefined {
-  return typeof tls === 'object' ? (tls === null ? undefined : tls) : tls ? {} : undefined;
-}

package/src/type-helpers.ts

@@ -1,26 +0,0 @@
-/** 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>;
-
-/** Verify that an type _Copy extends _Orig */
-export function checkExtends<_Orig, _Copy extends _Orig>(): void {
-  // noop, just type check
-}
-
-export type Replace<Base, New> = Omit<Base, keyof New> & New;
-
-export type MakeOptional<Base, Keys extends keyof Base> = Omit<Base, Keys> & Partial<Pick<Base, Keys>>;
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
-}
-
-export function hasOwnProperties<X extends Record<string, unknown>, Y extends PropertyKey>(
-  record: X,
-  props: Y[]
-): record is X & Record<Y, unknown> {
-  return props.every((prop) => prop in record);
-}

package/src/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;
-}

package/src/workflow-handle.ts

@@ -1,30 +0,0 @@
-import { Workflow, WorkflowResultType, SignalDefinition } from './interfaces';
-
-/**
- * Base WorkflowHandle interface, extended in workflow and client libs.
- *
- * Transforms a workflow interface `T` into a client interface.
- */
-export interface BaseWorkflowHandle<T extends Workflow> {
-  /**
-   * Promise that resolves when Workflow execution completes
-   */
-  result(): Promise<WorkflowResultType<T>>;
-
-  /**
-   * Signal a running Workflow.
-   *
-   * @param def a signal definition as returned from {@link defineSignal}
-   *
-   * @example
-   * ```ts
-   * await handle.signal(incrementSignal, 3);
-   * ```
-   */
-  signal<Args extends any[] = []>(def: SignalDefinition<Args> | string, ...args: Args): Promise<void>;
-
-  /**
-   * The workflowId of the current Workflow
-   */
-  readonly workflowId: string;
-}

package/src/workflow-options.ts

@@ -1,128 +0,0 @@
-import type { coresdk, google } from '@temporalio/proto/lib/coresdk';
-import { Workflow } from './interfaces';
-import { falsyMsToTs } from './time';
-import { Replace } from './type-helpers';
-import { RetryPolicy } from './retry-policy';
-import { checkExtends } from './type-helpers';
-
-// Avoid importing the proto implementation to reduce workflow bundle size
-// Copied from coresdk.common.WorkflowIdReusePolicy
-export enum WorkflowIdReusePolicy {
-  WORKFLOW_ID_REUSE_POLICY_UNSPECIFIED = 0,
-  WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1,
-  WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2,
-  WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE = 3,
-}
-
-checkExtends<coresdk.common.WorkflowIdReusePolicy, WorkflowIdReusePolicy>();
-
-export interface BaseWorkflowOptions {
-  /**
-   * Specifies server behavior if a completed workflow with the same id exists. Note that under no
-   * conditions Temporal allows two workflows with the same namespace and workflow id run
-   * simultaneously.
-   *   ALLOW_DUPLICATE_FAILED_ONLY is a default value. It means that workflow can start if
-   *   previous run failed or was canceled or terminated.
-   *   ALLOW_DUPLICATE allows new run independently of the previous run closure status.
-   *   REJECT_DUPLICATE doesn't allow new run independently of the previous run closure status.
-   */
-  workflowIdReusePolicy?: WorkflowIdReusePolicy;
-
-  /**
-   * Controls how a Workflow is retried.
-   *
-   * Workflows should typically use the system default, do not set this unless
-   * you know what you're doing.
-   */
-  retry?: RetryPolicy;
-
-  /**
-   * Optional cron schedule for Workflow. If a cron schedule is specified, the Workflow will run
-   * as a cron based on the schedule. The scheduling will be based on UTC time. The schedule for the next run only happens
-   * after the current run is completed/failed/timeout. If a RetryPolicy is also supplied, and the Workflow failed
-   * or timed out, the Workflow will be retried based on the retry policy. While the Workflow is retrying, it won't
-   * schedule its next run. If the next schedule is due while the Workflow is running (or retrying), then it will skip that
-   * schedule. Cron Workflow will not stop until it is terminated or cancelled (by returning temporal.CanceledError).
-   * https://crontab.guru/ is useful for testing your cron expressions.
-   */
-  cronSchedule?: string;
-
-  /**
-   * Specifies additional non-indexed information in result of list workflow. The type of value
-   * can be any object that are serializable by `DataConverter`.
-   */
-  memo?: Record<string, any>;
-
-  /**
-   * Specifies additional indexed information in result of list workflow. The type of value should
-   * be a primitive (e.g. string, number, boolean), for dates use Date.toISOString();
-   */
-  searchAttributes?: Record<string, string | number | boolean>;
-}
-
-export type WithWorkflowArgs<W extends Workflow, T> = T &
-  (Parameters<W> extends [any, ...any[]]
-    ? {
-        /**
-         * Arguments to pass to the Workflow
-         */
-        args: Parameters<W>;
-      }
-    : {
-        /**
-         * Arguments to pass to the Workflow
-         */
-        args?: Parameters<W>;
-      });
-
-export interface WorkflowDurationOptions {
-  /**
-   * The time after which workflow run is automatically terminated by Temporal service. Do not
-   * rely on run timeout for business level timeouts. It is preferred to use in workflow timers
-   * for this purpose.
-   *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
-   */
-  workflowRunTimeout?: string | number;
-
-  /**
-   *
-   * The time after which workflow execution (which includes run retries and continue as new) is
-   * automatically terminated by Temporal service. Do not rely on execution timeout for business
-   * level timeouts. It is preferred to use in workflow timers for this purpose.
-   *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
-   */
-  workflowExecutionTimeout?: string | number;
-
-  /**
-   * Maximum execution time of a single workflow task. Default is 10 seconds.
-   *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
-   */
-  workflowTaskTimeout?: string | number;
-}
-
-export type CommonWorkflowOptions = BaseWorkflowOptions & WorkflowDurationOptions;
-
-export type WithCompiledWorkflowDurationOptions<T extends WorkflowDurationOptions> = Replace<
-  T,
-  {
-    workflowExecutionTimeout?: google.protobuf.IDuration;
-    workflowRunTimeout?: google.protobuf.IDuration;
-    workflowTaskTimeout?: google.protobuf.IDuration;
-  }
->;
-
-export function compileWorkflowOptions<T extends WorkflowDurationOptions>(
-  options: T
-): WithCompiledWorkflowDurationOptions<T> {
-  const { workflowExecutionTimeout, workflowRunTimeout, workflowTaskTimeout, ...rest } = options;
-
-  return {
-    ...rest,
-    workflowExecutionTimeout: falsyMsToTs(workflowExecutionTimeout),
-    workflowRunTimeout: falsyMsToTs(workflowRunTimeout),
-    workflowTaskTimeout: falsyMsToTs(workflowTaskTimeout),
-  };
-}