@temporal-contract/worker

---

@temporal-contract/worker / worker

worker

Classes

TechnicalError

Defined in: packages/contract/dist/errors-impl-BxWuCbUU.d.mts:18

Error for technical/runtime failures that cannot be prevented by TypeScript — connection failures, missing runtime capabilities, worker bundling errors. These are unmodeled infrastructure faults, never anticipated domain failures, so they ride the Defect channel: the creation factories (TypedClient.create, TypedWorker.create) surface them as a Defect whose cause is a TechnicalError instance (inspect via match's defect handler, recoverDefect, or tapDefect) — this class never appears in a Result's modeled E channel.

The class is retained (and still exported) so the descriptive message and cause survive for logging; it is only ever used as a defect's cause.

Extends

• TechnicalError_base<{ cause?: unknown; }>

Constructors

Constructor

new TechnicalError(message, cause?): TechnicalError;

Defined in: packages/contract/dist/errors-impl-BxWuCbUU.d.mts:21

Parameters

Parameter	Type
message	string
cause?	unknown

Returns

TechnicalError

Overrides

TechnicalError_base<{
  cause?: unknown;
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
_tag	readonly	"@temporal-contract/TechnicalError"	TechnicalError_base._tag	node_modules/.pnpm/unthrown@5.7.0/node_modules/unthrown/dist/index.d.mts:2011
cause?	public	unknown	ActivityDefinitionNotFoundError.cause	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
message	public	string	TechnicalError_base.message	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
name	public	string	TechnicalError_base.name	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?	public	string	TechnicalError_base.stack	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

---

TypedWorker

Defined in: packages/worker/src/worker.ts:171

Contract-scoped root of the typed worker surface — the worker-side sibling of TypedClient.

Created with the static TypedWorker.create factory (the org's Typed*.create() shape), it owns the unthrown-disciplined lifecycle — run and shutdown — while everything else Temporal's runtime offers (runUntil, getState, tuning introspection) stays reachable through the raw escape hatch.

Properties

Property	Modifier	Type	Description	Defined in
raw	readonly	Worker	The underlying @temporalio/worker Worker — the escape hatch for anything the typed surface doesn't cover (e.g. raw.runUntil(...) in tests, raw.getState() for monitoring). Temporal's runtime owns the worker loop; this accessor is always available.	packages/worker/src/worker.ts:178

Methods

run()

run(): AsyncResult<void, never>;

Defined in: packages/worker/src/worker.ts:289

Start the worker loop — delegates to the underlying Worker.run().

Returns AsyncResult<void, never> that resolves Ok once the worker has drained and shut down (after shutdown or a shutdown signal). A worker that fails while running is a technical infrastructure fault, so it surfaces on the Defect channel (a TechnicalError instance as the defect's cause) — the returned AsyncResult never rejects, so it is safe to hold onto and inspect later. await worker.run().get() at the edge rethrows a defect's cause.

Returns

AsyncResult<void, never>

shutdown()

shutdown(): void;

Defined in: packages/worker/src/worker.ts:314

Initiate a graceful shutdown — delegates to the underlying Worker.shutdown(). The worker stops polling, finishes in-flight tasks, and the run result resolves once draining completes. Calling it on a worker that is not running throws Temporal's IllegalStateError — a programming defect, not a modeled error.

Returns

void

create()

static create<TContract>(options): AsyncResult<TypedWorker, never>;

Defined in: packages/worker/src/worker.ts:234

Create a typed Temporal worker with contract-based configuration.

This factory simplifies worker creation by:

• Using the contract's task queue automatically
• Providing type-safe configuration

Returns AsyncResult<TypedWorker, never> — worker bundling and connection failures are technical infrastructure faults, not anticipated domain errors, so they surface on the Defect channel (a TechnicalError instance as the defect's cause) rather than the modeled Err channel. The Err channel is empty (never), so .get() unwraps directly — a setup defect rethrows its cause. Alternatively, inspect defects via match's defect handler or recoverDefect / tapDefect.

Type Parameters

Type Parameter
TContract extends ContractDefinition

Parameters

Parameter	Type
options	CreateWorkerOptions<TContract>

Returns

AsyncResult<TypedWorker, never>

Example

import { NativeConnection } from '@temporalio/worker';
import { TypedWorker, workflowsPathFromURL } from '@temporal-contract/worker/worker';
import { activities } from './activities.js';
import myContract from './contract.js';

const connection = await NativeConnection.connect({
  address: 'localhost:7233',
});

const worker = await TypedWorker.create({
  contract: myContract,
  connection,
  workflowsPath: workflowsPathFromURL(import.meta.url, './workflows.js'),
  activities,
}).get();

await worker.run().get();

Remarks

The Err channel is empty (never): nothing about creating a worker is a modeled domain outcome, so a bad connection or an invalid contract is a technical fault on the defect channel. .get() therefore unwraps directly and rethrows a setup defect's cause; narrow with .isDefect() first only to report the failure before exiting. run() is never in the same way. See "Setup calls have an empty Err channel" in docs/explanation/the-result-model.md.

Type Aliases

CreateWorkerOptions

type CreateWorkerOptions<TContract> = Omit<WorkerOptions, "activities" | "taskQueue"> & object;

Defined in: packages/worker/src/worker.ts:21

Options for TypedWorker.create — the single options-object shape shared by the org's Typed*.create() factories.

Type Declaration

Name	Type	Description	Defined in
activities?	ActivitiesHandler<TContract>	Activities handler for this worker, built with declareActivitiesHandler. Optional — omit it for a workflow-only worker. When absent, no activities are registered with the underlying Temporal Worker, so it only polls for Workflow Tasks. This supports the split-deployment pattern where workflow code and activity code scale independently: one worker process runs the (deterministic, CPU-light) workflows while a separate worker process on the same task queue registers the activities.	packages/worker/src/worker.ts:41
contract	TContract	The contract definition for this worker	packages/worker/src/worker.ts:28
verifyWorkflowRegistration?	boolean	Best-effort startup check that the workflowsPath module registers every contract workflow under its declared name. Defaults to true. Activities already fail fast at declareActivitiesHandler time when an implementation is missing; workflows historically did not — a forgotten declareWorkflow export surfaced only when the first task for it was dispatched, and an export whose name differs from its workflowName registered under the wrong workflow type. With this check enabled, TypedWorker.create imports the workflowsPath module in the main thread, identifies declareWorkflow-produced exports via their brand marker, and fails creation (a TechnicalError-caused defect) when - a contract workflow has neither a declareWorkflow-produced export nor a plain function export under its name (raw @temporalio/workflow-style workflow functions exported under the correct name are accepted), or - a declared workflow is exported under a name that differs from its workflowName (Temporal registers workflows by export name, so the mismatch would register it as the wrong workflow type). Best-effort semantics: the check only runs when workflowsPath is provided (prebuilt workflowBundles are skipped), and a module that cannot be imported in the main thread is skipped silently — the subsequent Worker.create bundling step is the authority on whether the module loads at all. Note the module is evaluated in the main thread, so workflow modules should stay side-effect-free at module scope (they should be anyway — the sandbox re-evaluates them constantly). Set to false to opt out (e.g. when the workflows module intentionally exports helpers whose names shadow contract workflows, or module-scope evaluation outside the sandbox is undesirable).	packages/worker/src/worker.ts:76

Type Parameters

Type Parameter
TContract extends ContractDefinition

Functions

workflowsPathFromURL()

function workflowsPathFromURL(baseURL, relativePath): string;

Defined in: packages/worker/src/worker.ts:342

Helper to resolve a workflow file path relative to the current module's URL.

Useful when using ES modules (import.meta.url) to locate workflow files. The relativePath should include the file extension explicitly (e.g. ./workflows.js) to ensure the resolved path is unambiguous in both source and built contexts.

Parameters

Parameter	Type	Description
baseURL	string	The base URL to resolve from, typically import.meta.url
relativePath	string	Relative path to the workflows file, including extension

Returns

string

Example

import { TypedWorker, workflowsPathFromURL } from '@temporal-contract/worker/worker';

const worker = await TypedWorker.create({
  contract: myContract,
  connection,
  // Include the extension explicitly to work in both source (.ts) and build (.js) contexts
  workflowsPath: workflowsPathFromURL(import.meta.url, './workflows.js'),
  activities,
}).get();