@temporal-contract/contract

---

@temporal-contract/contract

Type Aliases

ActivityDefinition

type ActivityDefinition<TInput, TOutput> = object;

Defined in: types.ts:13

Definition of an activity

Type Parameters

Type Parameter	Default type
TInput extends AnySchema	AnySchema
TOutput extends AnySchema	AnySchema

Properties

Property	Modifier	Type	Defined in
input	readonly	TInput	types.ts:17
output	readonly	TOutput	types.ts:18

---

AnySchema

type AnySchema = StandardSchemaV1;

Defined in: types.ts:8

Base types for validation schemas Any schema that implements the Standard Schema specification This includes Zod, Valibot, ArkType, and other compatible libraries

---

AnyWorkflowDefinition

type AnyWorkflowDefinition = WorkflowDefinition<AnySchema, AnySchema, Record<string, ActivityDefinition>, Record<string, SignalDefinition>, Record<string, QueryDefinition>, Record<string, UpdateDefinition>, Record<string, SearchAttributeDefinition>>;

Defined in: types.ts:132

Widened constraint variant of WorkflowDefinition.

WorkflowDefinition (no args) resolves the empty-record generics to Record<string, never>, which is the right default for fresh callers but too narrow as a constraint — a Record-of-WorkflowDefinition constraint built from it would reject any literal whose activities, signals, queries, or updates block is non-empty. AnyWorkflowDefinition widens those generics back to their permissive bounds so it can act as the value of Record<string, …> in ContractDefinition without preventing real workflow definitions from satisfying the constraint.

---

ContractDefinition

type ContractDefinition<TWorkflows, TActivities> = object;

Defined in: types.ts:192

Contract definition containing workflows and optional global activities

Type Parameters

Type Parameter	Default type
TWorkflows extends Record<string, AnyWorkflowDefinition>	Record<string, AnyWorkflowDefinition>
TActivities extends Record<string, ActivityDefinition>	Record<string, ActivityDefinition>

Properties

Property	Modifier	Type	Defined in
activities?	readonly	TActivities	types.ts:198
taskQueue	readonly	string	types.ts:196
workflows	readonly	TWorkflows	types.ts:197

---

InferActivityNames

type InferActivityNames<TContract> = TContract["activities"] extends Record<string, ActivityDefinition> ? keyof TContract["activities"] & string : never;

Defined in: types.ts:226

Extract activity names from a contract (global activities) as a union type

Type Parameters

Type Parameter
TContract extends ContractDefinition

Example

type MyActivityNames = InferActivityNames<typeof myContract>;
// "log" | "sendEmail"

---

InferContractWorkflows

type InferContractWorkflows<TContract> = TContract["workflows"];

Defined in: types.ts:239

Extract all workflows from a contract with their definitions

Type Parameters

Type Parameter
TContract extends ContractDefinition

Example

type MyWorkflows = InferContractWorkflows<typeof myContract>;

---

InferWorkflowNames

type InferWorkflowNames<TContract> = keyof TContract["workflows"] & string;

Defined in: types.ts:214

Extract workflow names from a contract as a union type

Type Parameters

Type Parameter
TContract extends ContractDefinition

Example

type MyWorkflowNames = InferWorkflowNames<typeof myContract>;
// "processOrder" | "sendNotification"

---

QueryDefinition

type QueryDefinition<TInput, TOutput> = object;

Defined in: types.ts:31

Definition of a query

Type Parameters

Type Parameter	Default type
TInput extends AnySchema	AnySchema
TOutput extends AnySchema	AnySchema

Properties

Property	Modifier	Type	Defined in
input	readonly	TInput	types.ts:35
output	readonly	TOutput	types.ts:36

---

QueryNamesOf

type QueryNamesOf<W> = W extends object ? Q extends Record<string, QueryDefinition> ? keyof Q & string : never : never;

Defined in: types.ts:168

Extract query names declared on a workflow as a string union, or never if the workflow declares no queries. See SignalNamesOf for the rationale behind the distributive infer-based shape.

Type Parameters

Type Parameter
W extends AnyWorkflowDefinition

---

SearchAttributeDefinition

type SearchAttributeDefinition<TKind> = object;

Defined in: types.ts:87

Definition of a typed search attribute on a workflow.

Type Parameters

Type Parameter	Default type
TKind extends SearchAttributeKind	SearchAttributeKind

Properties

Property	Modifier	Type	Defined in
kind	readonly	TKind	types.ts:88

---

SearchAttributeKind

type SearchAttributeKind = 
  | "TEXT"
  | "KEYWORD"
  | "INT"
  | "DOUBLE"
  | "BOOL"
  | "DATETIME"
  | "KEYWORD_LIST";

Defined in: types.ts:56

The seven Temporal search attribute kinds.

Mirrors @temporalio/common's SearchAttributeType so values flow into Temporal's typedSearchAttributes API unchanged.

---

SearchAttributeKindToType

type SearchAttributeKindToType<T> = object[T];

Defined in: types.ts:74

Map each SearchAttributeKind to its TypeScript representation.

• TEXT / KEYWORD → string
• INT / DOUBLE → number
• BOOL → boolean
• DATETIME → Date
• KEYWORD_LIST → string[]

Type Parameters

Type Parameter
T extends SearchAttributeKind

---

SignalDefinition

type SignalDefinition<TInput> = object;

Defined in: types.ts:24

Definition of a signal

Type Parameters

Type Parameter	Default type
TInput extends AnySchema	AnySchema

Properties

Property	Modifier	Type	Defined in
input	readonly	TInput	types.ts:25

---

SignalNamesOf

type SignalNamesOf<W> = W extends object ? S extends Record<string, SignalDefinition> ? keyof S & string : never : never;

Defined in: types.ts:155

Extract signal names declared on a workflow as a string union, or never if the workflow declares no signals. Used to constrain signalName call sites so typos surface at compile time instead of runtime.

The conditional is intentionally distributive over W (rather than indexing W["signals"] directly) so that union workflow types — e.g. discriminated unions of workflow definitions — yield the union of their signal names rather than the intersection (keyof (A | B) is the intersection of keys, which usually collapses to never). Destructuring signals via infer S also tolerates the property being absent or undefined under exactOptionalPropertyTypes.

Type Parameters

Type Parameter
W extends AnyWorkflowDefinition

---

UpdateDefinition

type UpdateDefinition<TInput, TOutput> = object;

Defined in: types.ts:42

Definition of an update

Type Parameters

Type Parameter	Default type
TInput extends AnySchema	AnySchema
TOutput extends AnySchema	AnySchema

Properties

Property	Modifier	Type	Defined in
input	readonly	TInput	types.ts:46
output	readonly	TOutput	types.ts:47

---

UpdateNamesOf

type UpdateNamesOf<W> = W extends object ? U extends Record<string, UpdateDefinition> ? keyof U & string : never : never;

Defined in: types.ts:181

Extract update names declared on a workflow as a string union, or never if the workflow declares no updates. See SignalNamesOf for the rationale behind the distributive infer-based shape.

Type Parameters

Type Parameter
W extends AnyWorkflowDefinition

---

WorkflowDefinition

type WorkflowDefinition<TInput, TOutput, TActivities, TSignals, TQueries, TUpdates, TSearchAttributes> = object;

Defined in: types.ts:102

Definition of a workflow.

Generic parameters preserve the schema literal types of input/output and the declared shape of activities/signals/queries/updates/search attributes through defineWorkflow so client and worker call sites can infer typed payloads. Empty-collection generics default to Record<string, never> so that, when no signals/queries/updates/etc. are declared, keyof resolves to never rather than string — turning typos in signalName/queryName/updateName into compile-time errors.

Type Parameters

Type Parameter	Default type
TInput extends AnySchema	AnySchema
TOutput extends AnySchema	AnySchema
TActivities extends Record<string, ActivityDefinition>	Record<string, never>
TSignals extends Record<string, SignalDefinition>	Record<string, never>
TQueries extends Record<string, QueryDefinition>	Record<string, never>
TUpdates extends Record<string, UpdateDefinition>	Record<string, never>
TSearchAttributes extends Record<string, SearchAttributeDefinition>	Record<string, never>

Properties

Property	Modifier	Type	Defined in
activities?	readonly	TActivities	types.ts:113
input	readonly	TInput	types.ts:111
output	readonly	TOutput	types.ts:112
queries?	readonly	TQueries	types.ts:115
searchAttributes?	readonly	TSearchAttributes	types.ts:117
signals?	readonly	TSignals	types.ts:114
updates?	readonly	TUpdates	types.ts:116

Functions

defineActivity()

function defineActivity<TActivity>(definition): TActivity;

Defined in: builder.ts:45

Define a Temporal activity with type-safe input and output schemas.

Activities are the building blocks of Temporal workflows that execute business logic and interact with external services. This function preserves TypeScript types while providing a consistent structure for activity definitions.

Type Parameters

Type Parameter	Description
TActivity extends ActivityDefinition	The activity definition type with input/output schemas

Parameters

Parameter	Type	Description
definition	TActivity	The activity definition containing input and output schemas

Returns

TActivity

The same definition with preserved types for type inference

Example

import { defineActivity } from '@temporal-contract/contract';
import { z } from 'zod';

export const sendEmail = defineActivity({
  input: z.object({
    to: z.string().email(),
    subject: z.string(),
    body: z.string(),
  }),
  output: z.object({
    messageId: z.string(),
    sentAt: z.date(),
  }),
});

---

defineContract()

function defineContract<TContract>(definition): TContract;

Defined in: builder.ts:278

Define a complete Temporal contract with type-safe workflows and activities.

A contract is the central definition that ties together your Temporal application's workflows and activities. It provides:

• Type safety across client, worker, and workflow code
• Automatic validation at runtime
• Compile-time verification of implementations
• Clear API boundaries and documentation

The contract validates the structure and ensures:

• Task queue is specified
• At least one workflow is defined
• Valid JavaScript identifiers are used
• No conflicts between global and workflow-specific activities
• All schemas implement the Standard Schema specification

Type Parameters

Type Parameter	Description
TContract extends ContractDefinition	The contract definition type

Parameters

Parameter	Type	Description
definition	TContract	The complete contract definition

Returns

TContract

The same definition with preserved types for type inference

Throws

If the contract structure is invalid

Example

import { defineContract } from '@temporal-contract/contract';
import { z } from 'zod';

export const myContract = defineContract({
  taskQueue: 'orders',
  workflows: {
    processOrder: {
      input: z.object({ orderId: z.string() }),
      output: z.object({ success: z.boolean() }),
      activities: {
        chargePayment: {
          input: z.object({ amount: z.number() }),
          output: z.object({ transactionId: z.string() }),
        },
      },
    },
  },
  // Optional global activities shared across workflows
  activities: {
    logEvent: {
      input: z.object({ message: z.string() }),
      output: z.void(),
    },
  },
});

---

defineQuery()

function defineQuery<TQuery>(definition): TQuery;

Defined in: builder.ts:110

Define a Temporal query with type-safe input and output schemas.

Queries allow you to read the current state of a running workflow without modifying it. They are synchronous and should not perform any mutations.

Synchronous validation required. Temporal query handlers must complete synchronously, so the input and output schemas you pass here must validate synchronously. In practice this rules out async refinements (e.g. Zod's .refine(async (x) => …)). Standard Schema doesn't expose the sync/async distinction at the type level, so the worker checks at runtime and throws if it ever receives a Promise from ~standard.validate. Use plain Zod / Valibot / ArkType object schemas without async refinements.

Type Parameters

Type Parameter	Description
TQuery extends QueryDefinition	The query definition type with input/output schemas

Parameters

Parameter	Type	Description
definition	TQuery	The query definition containing input and output schemas

Returns

TQuery

The same definition with preserved types for type inference

Example

import { defineQuery } from '@temporal-contract/contract';
import { z } from 'zod';

export const getOrderStatus = defineQuery({
  input: z.object({ orderId: z.string() }),
  output: z.object({
    status: z.enum(['pending', 'processing', 'completed', 'failed']),
    updatedAt: z.date(),
  }),
});

---

defineSearchAttribute()

function defineSearchAttribute<TKind>(definition): SearchAttributeDefinition<TKind>;

Defined in: builder.ts:182

Define a typed search attribute on a workflow.

Search attributes are indexed on Temporal's visibility store and let you query / filter workflow executions by domain attributes. Declaring them on the contract means the client's workflow-start options and (eventually) the worker's search-attribute reader are constrained to declared keys with the right value types.

Type Parameters

Type Parameter
TKind extends SearchAttributeKind

Parameters

Parameter	Type
definition	SearchAttributeDefinition<TKind>

Returns

SearchAttributeDefinition<TKind>

Example

import { defineSearchAttribute } from '@temporal-contract/contract';

defineWorkflow({
  input: z.object({ orderId: z.string() }),
  output: z.object({ status: z.string() }),
  searchAttributes: {
    customerId: defineSearchAttribute({ kind: 'KEYWORD' }),
    priority: defineSearchAttribute({ kind: 'INT' }),
    placedAt: defineSearchAttribute({ kind: 'DATETIME' }),
  },
});

The seven Temporal kinds map to TypeScript types like so:

kind	TS type
TEXT	string
KEYWORD	string
INT	number
DOUBLE	number
BOOL	boolean
DATETIME	Date
KEYWORD_LIST	string[]

---

defineSignal()

function defineSignal<TSignal>(definition): TSignal;

Defined in: builder.ts:74

Define a Temporal signal with type-safe input schema.

Signals are asynchronous messages sent to running workflows to update their state or trigger certain behaviors. This function ensures type safety for signal payloads.

Type Parameters

Type Parameter	Description
TSignal extends SignalDefinition	The signal definition type with input schema

Parameters

Parameter	Type	Description
definition	TSignal	The signal definition containing input schema

Returns

TSignal

The same definition with preserved types for type inference

Example

import { defineSignal } from '@temporal-contract/contract';
import { z } from 'zod';

export const approveOrder = defineSignal({
  input: z.object({
    orderId: z.string(),
    approvedBy: z.string(),
  }),
});

---

defineUpdate()

function defineUpdate<TUpdate>(definition): TUpdate;

Defined in: builder.ts:142

Define a Temporal update with type-safe input and output schemas.

Updates are similar to signals but return a value and wait for the workflow to process them before completing. They provide a synchronous way to modify workflow state and get immediate feedback.

Type Parameters

Type Parameter	Description
TUpdate extends UpdateDefinition	The update definition type with input/output schemas

Parameters

Parameter	Type	Description
definition	TUpdate	The update definition containing input and output schemas

Returns

TUpdate

The same definition with preserved types for type inference

Example

import { defineUpdate } from '@temporal-contract/contract';
import { z } from 'zod';

export const updateOrderQuantity = defineUpdate({
  input: z.object({
    orderId: z.string(),
    newQuantity: z.number().positive(),
  }),
  output: z.object({
    success: z.boolean(),
    totalPrice: z.number(),
  }),
});

---

defineWorkflow()

function defineWorkflow<TWorkflow>(definition): TWorkflow;

Defined in: builder.ts:221

Define a Temporal workflow with type-safe input, output, and associated operations.

Workflows are durable functions that orchestrate activities, handle timeouts, and manage long-running processes. This function provides type safety for the entire workflow definition including activities, signals, queries, and updates.

Type Parameters

Type Parameter	Description
TWorkflow extends AnyWorkflowDefinition	The workflow definition type with all associated schemas

Parameters

Parameter	Type	Description
definition	TWorkflow	The workflow definition containing input, output, and operations

Returns

TWorkflow

The same definition with preserved types for type inference

Example

import { defineWorkflow, defineActivity, defineSignal } from '@temporal-contract/contract';
import { z } from 'zod';

export const processOrder = defineWorkflow({
  input: z.object({ orderId: z.string() }),
  output: z.object({ success: z.boolean() }),
  activities: {
    validatePayment: defineActivity({
      input: z.object({ orderId: z.string() }),
      output: z.object({ valid: z.boolean() }),
    }),
  },
  signals: {
    cancel: defineSignal({
      input: z.object({ reason: z.string() }),
    }),
  },
});

---

formatIssue()

function formatIssue(issue): string;

Defined in: format.ts:40

Render a Standard Schema StandardSchemaV1.Issue into a human-readable string that includes the failing field's path.

Example output:

• at items[0].quantity: Expected number, received undefined
• at customerId: Expected string, received undefined
• at user["first name"]: Expected string, received undefined
• Validation error (no path)

Path segments come either as bare PropertyKey values or as { key: PropertyKey } objects (per the spec); both are normalized.

• Numeric keys → [N]
• String keys that are valid JS identifiers → bare (first) or .key
• String keys that aren't valid identifiers → ["..."] with JSON-style escaping (handles dots, spaces, leading digits, the empty string, the literal string "0", embedded quotes, etc.)
• Symbol / other PropertyKey → [Symbol(name)]

Parameters

Parameter	Type
issue	Issue

Returns

string

---

summarizeIssues()

function summarizeIssues(issues): string;

Defined in: format.ts:66

Join a list of validation issues into a single message, with each issue rendered via formatIssue so field paths surface in the error text.

Parameters

Parameter	Type
issues	readonly Issue[]

Returns

string