@btravstack/temporal-worker

@btravstack/temporal-worker

Classes

TemporalConfig

Defined in: packages/temporal-worker/src/temporal-runtime.ts:64

Where the Temporal service is, as a service: temporal() binds it from the environment — TEMPORAL_ADDRESS (default 127.0.0.1:7233), TEMPORAL_NAMESPACE (default default) and the shutdown budgets below — unless pinned, and anything else in the graph may read it.

Extends

PortInstance<"TemporalConfig", { address: string; forceAfterMs: number; gracePeriodMs: number; namespace: string; }>

Constructors

Constructor

new TemporalConfig(): TemporalConfig;

Defined in: packages/di/dist/index.d.mts:16

Returns

TemporalConfig

Inherited from

Port("TemporalConfig")<{
  readonly address: string;
  readonly namespace: string;
  / Temporal's shutdownGraceTime, in milliseconds. /
  readonly gracePeriodMs: number;
  / Temporal's shutdownForceTime, in milliseconds. /
  readonly forceAfterMs: number;
}>.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`[ID]`	`readonly`	`"TemporalConfig"`	-	`Port("TemporalConfig").[ID]`	packages/di/dist/index.d.mts:12
`[SERVICE]`	`readonly`	`object`	-	`Port("TemporalConfig").[SERVICE]`	packages/di/dist/index.d.mts:13
`[SERVICE].address`	`readonly`	`string`	-	-	packages/temporal-worker/src/temporal-runtime.ts:65
`[SERVICE].forceAfterMs`	`readonly`	`number`	Temporal's `shutdownForceTime`, in milliseconds.	-	packages/temporal-worker/src/temporal-runtime.ts:70
`[SERVICE].gracePeriodMs`	`readonly`	`number`	Temporal's `shutdownGraceTime`, in milliseconds.	-	packages/temporal-worker/src/temporal-runtime.ts:68
`[SERVICE].namespace`	`readonly`	`string`	-	-	packages/temporal-worker/src/temporal-runtime.ts:66
`portId`	`readonly`	`"TemporalConfig"`	-	`Port("TemporalConfig").portId`	packages/di/dist/index.d.mts:17

TemporalConnection

Defined in: packages/temporal-worker/src/temporal-runtime.ts:77

The connection, as a resource of the graph: di opens it with the scope and closes it on every exit path, startup failure included.

Extends

PortInstance<"TemporalConnection", NativeConnection>

Constructors

Constructor

new TemporalConnection(): TemporalConnection;

Defined in: packages/di/dist/index.d.mts:16

Returns

TemporalConnection

Inherited from

Port("TemporalConnection")<NativeConnection>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`[ID]`	`readonly`	`"TemporalConnection"`	`Port("TemporalConnection").[ID]`	packages/di/dist/index.d.mts:12
`[SERVICE]`	`readonly`	`NativeConnection`	`Port("TemporalConnection").[SERVICE]`	packages/di/dist/index.d.mts:13
`portId`	`readonly`	`"TemporalConnection"`	`Port("TemporalConnection").portId`	packages/di/dist/index.d.mts:17

TemporalRuntime

Defined in: packages/temporal-worker/src/temporal-runtime.ts:93

The runtime's port: what temporal() provides, and what the module start boots must export.

Extends

RuntimePort<Runtime<never, TemporalInfo>>

Constructors

Constructor

new TemporalRuntime(): TemporalRuntime;

Defined in: packages/di/dist/index.d.mts:16

Returns

TemporalRuntime

Inherited from

RuntimePort<Runtime<never, TemporalInfo>>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`[ID]`	`readonly`	`"Runtime"`	`RuntimePort.[ID]`	packages/di/dist/index.d.mts:12
`[SERVICE]`	`readonly`	`Runtime`	`RuntimePort.[SERVICE]`	packages/di/dist/index.d.mts:13
`portId`	`readonly`	`"Runtime"`	`RuntimePort.portId`	packages/di/dist/index.d.mts:17

TemporalUnreachable

Defined in: packages/temporal-worker/src/temporal-runtime.ts:85

The service at TemporalConfig.address did not answer. Modeled rather than left a defect because an operator can act on it — the address is wrong or the service is down, and neither is a bug in this code — so runMain exits 1, a startup Err, not the 70 a defect earns.

Extends

TaggedErrorInstance<"TemporalUnreachable", { address: string; cause: unknown; }>

Constructors

Constructor

new TemporalUnreachable(args): TemporalUnreachable;

Defined in: node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2034

Parameters

Parameter	Type
`args`	`object` & `object`

Returns

TemporalUnreachable

Inherited from

TaggedError("TemporalUnreachable")<{
  readonly address: string;
  readonly cause: unknown;
}>.constructor

Properties

Property	Modifier	Type	Overrides	Inherited from	Defined in
`_tag`	`readonly`	`"TemporalUnreachable"`	-	`TaggedError("TemporalUnreachable")._tag`	node_modules/.pnpm/unthrown@5.8.0/node_modules/unthrown/dist/index.d.mts:2011
`address`	`readonly`	`string`	-	`TaggedError("TemporalUnreachable").address`	packages/temporal-worker/src/temporal-runtime.ts:86
`cause`	`public`	`unknown`	-	`TaggedError("TemporalUnreachable").cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`message`	`public`	`string`	`TaggedError("TemporalUnreachable").message`	-	packages/temporal-worker/src/temporal-runtime.ts:89
`name`	`public`	`string`	-	`TaggedError("TemporalUnreachable").name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`stack?`	`public`	`string`	-	`TaggedError("TemporalUnreachable").stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Type Aliases

ActivitiesInstanceOf

type ActivitiesInstanceOf<C> = PortInstance<"TemporalActivities", ActivitiesOf<C>>;

Defined in: packages/temporal-worker/src/temporal-runtime.ts:142

The activities port's instance for C — the module's one need.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`

ActivitiesPortOf

type ActivitiesPortOf<C> = PortClassOf<"TemporalActivities", ActivitiesOf<C>>;

Defined in: packages/temporal-worker/src/temporal-runtime.ts:136

The activities port class, typed for C: what TemporalActivities(contract)(…).port is.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`

ActivityInputOf

type ActivityInputOf<C> = InputOfEntry<ActivitiesRecordOf<C>[ActivitiesKeyOf<C>]>;

Defined in: packages/temporal-worker/src/workflow-activities.ts:42

The validated activity input, typed by the contract: the union of every activity's own input.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`

ActivityInputPortOf

type ActivityInputPortOf<C> = PortClassOf<"ActivityInput", ActivityInputOf<C>>;

Defined in: packages/temporal-worker/src/workflow-activities.ts:47

The seeded port's class, typed for C: what ActivityInput(contract) answers.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`

TemporalInfo

type TemporalInfo = object;

Defined in: packages/temporal-worker/src/temporal-runtime.ts:43

What the worker publishes once it is polling, read back through RunningApp.runtimeInfo().

Properties

Property	Modifier	Type	Defined in
`namespace`	`readonly`	`string`	packages/temporal-worker/src/temporal-runtime.ts:45
`taskQueue`	`readonly`	`string`	packages/temporal-worker/src/temporal-runtime.ts:44

TemporalModuleOptions

type TemporalModuleOptions<C, ActivitiesError, ActivitiesNeeds, Declared, Unit, I, P, X, N> = TemporalTuning<Unit> & object & NeedsGate<Imports<I, C, Unit>, Provides<P, C, ActivitiesError, ActivitiesNeeds>, N> & UnitGate<Unit, Declared>;

Defined in: packages/temporal-worker/src/temporal-module.ts:59

Type Declaration

Name	Type	Description	Defined in
`activities`	`Provider`<`ActivitiesInstanceOf`<`C`>, `ActivitiesError`, `ActivitiesNeeds`> & `object`	The application's activity implementations — what `TemporalActivities(contract)(…)` returns. Its `_declaredUnit` phantom carries every port its pieces read off `context.unit`, which is what UnitGate checks `unit.activity` against.	packages/temporal-worker/src/temporal-module.ts:82
`contract`	`C`	The `temporal-contract` contract; the task queue this worker polls is read off it.	packages/temporal-worker/src/temporal-module.ts:74
`exports?`	`X`	The application's own exports; `TemporalRuntime` is added, since `start` resolves it.	packages/temporal-worker/src/temporal-module.ts:88
`imports?`	`I`	-	packages/temporal-worker/src/temporal-module.ts:85
`needs?`	`N`	What this root's OWN providers expect from outside. di's gate is re-stated over the augmented tuples below, so forgetting one is an error at THIS call.	packages/temporal-worker/src/temporal-module.ts:93
`provides?`	`P`	-	packages/temporal-worker/src/temporal-module.ts:86
`workflows`	`WorkflowSource`	-	packages/temporal-worker/src/temporal-module.ts:75

Type Parameters

Type Parameter
`C` extends `ContractDefinition`
`ActivitiesError`
`ActivitiesNeeds`
`Declared`
`Unit` extends `AnyUnitModule` \| `undefined`
`I` extends readonly `AnyModule`[]
`P` extends readonly `AnyProvider`[]
`X` extends readonly `Exportable`<`Imports`<`I`, `C`, `Unit`>, `Provides`<`P`, `C`, `ActivitiesError`, `ActivitiesNeeds`>>[]
`N` extends readonly `AnyPort`[]

TemporalOptions

type TemporalOptions<C, Unit> = TemporalTuning<Unit> & object;

Defined in: packages/temporal-worker/src/temporal-runtime.ts:181

Type Declaration

Name	Type	Description	Defined in
`contract`	`C`	The contract; the task queue this worker polls is read off it, and the activities port is typed by it. The starter calls `declareActivitiesHandler` itself, with its unit middleware in place.	packages/temporal-worker/src/temporal-runtime.ts:190
`workflows`	`WorkflowSource`	-	packages/temporal-worker/src/temporal-runtime.ts:191

Type Parameters

Type Parameter	Default type
`C` extends `ContractDefinition`	-
`Unit` extends `AnyUnitModule` \| `undefined`	`undefined`

WorkflowActivitiesPortOf

type WorkflowActivitiesPortOf<C, K> = PortClassOf<`${typeof WORKFLOW_ACTIVITIES_PREFIX}${K}`, ActivitiesRecordOf<C>[K]>;

Defined in: packages/temporal-worker/src/workflow-activities.ts:95

The port one piece targets. Its id carries the key, which is what makes two slices claiming one workflow di's duplicate-provider defect rather than a silent merge.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`
`K` extends `ActivitiesKeyOf`<`C`>

WorkflowSource

type WorkflowSource = 
  | {
  workflowsPath: string;
}
  | {
  workflowBundle: WorkflowBundleWithSourceMap;
};

Defined in: packages/temporal-worker/src/temporal-runtime.ts:54

Where the workflow sandbox's code comes from. Two arms because the two callers genuinely differ: a process points at the module and lets Temporal bundle it, while a spec hands over a bundle it built and memoised once — bundling per test is the most expensive thing a suite does.

Functions

ActivityInput()

function ActivityInput<C>(contract): ActivityInputPortOf<C>;

Defined in: packages/temporal-worker/src/workflow-activities.ts:80

The validated activity input as a port: the one thing the worker seeds the fork with, so a unit.activity module derives a tenant — or anything else — from the invocation rather than from an ambient record.

const Input = ActivityInput(orderContract);
const ActivityUnit = Module("ActivityUnit")({
  needs: [Input],
  provides: [Provider(Tenant)({ inject: { input: Input }, sync: ({ input }) => input.tenantId })],
  exports: [Tenant],
});

contract is read for its TYPE only. One Port(...) call fixed per contract at the type level, the move TemporalActivitiesPort makes, so a module built for one contract cannot read another's input.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`

Parameters

Parameter	Type
`contract`	`C`

Returns

ActivityInputPortOf<C>

temporal()

function temporal<C, Unit>(options): Module<Provided, ConfigInvalid | TemporalUnreachable, 
  | Env
  | Scope
  | ActivitiesInstanceOf<C>
  | UnitNeedsOf<Unit>>;

Defined in: packages/temporal-worker/src/temporal-runtime.ts:219

The Temporal starter: a module providing the runtime, its configuration (bound from the TEMPORAL_* variables unless pinned) and the connection (a resource opened with the scope and closed with it; a service that will not answer is a modeled TemporalUnreachable). Import it next to the application, export TemporalRuntime, provide the activities — the activities port is a need of this module.

Each configuration field is pinned on its own: a pinned field reads nothing from the environment, and a field left unpinned still does.

Type Parameters

Type Parameter	Default type
`C` extends `ContractDefinition`	-
`Unit` extends `AnyUnitModule` \| `undefined`	`undefined`

Parameters

Parameter	Type
`options`	`TemporalOptions`<`C`, `Unit`>

Returns

TemporalActivities()

function TemporalActivities<C>(contract): Whole<C> & Compose<C>;

Defined in: packages/temporal-worker/src/temporal-module.ts:274

The activities as a provider, from the contract. Two call forms, one port.

TemporalActivities(orderContract)({ inject: { place: PlaceOrder }, sync: ({ place }) => ({ fulfillOrder: { … } }) })
TemporalActivities(orderContract)([fulfillOrder, chargeOrder])

The first is { inject, unit?, sync }, whose sync hands back the whole activities record — one unit: record for every entry in it. The second takes the pieces TemporalWorkflowActivities(contract, key) builds: they are the provider's deps, keyed by the contract key each piece's port id carries, so the services record IS the activities record. Every key must be covered, and two slices claiming one key are di's duplicate-provider defect at build.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`

Parameters

Parameter	Type
`contract`	`C`

Returns

Whole<C> & Compose<C>

TemporalModule()

function TemporalModule<Name>(name): <C, ActivitiesError, ActivitiesNeeds, Declared, Unit, I, P, X, N>(options) => Module<ResolvedExports<readonly [typeof TemporalRuntime, X]>, 
  | ErrOf<readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P][number]>
  | ErrOfModule<readonly [I, TemporalStarter<C, Unit>][number]>, 
  | Exclude<NeedOf<readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P][number]>, Available<readonly [I, TemporalStarter<C, Unit>], readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P]>>
  | Exclude<NeedsOfModule<readonly [I, TemporalStarter<C, Unit>][number]>, Available<readonly [I, TemporalStarter<C, Unit>], readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P]>>>;

Defined in: packages/temporal-worker/src/temporal-module.ts:119

Module(name)({...}) for a Temporal worker deployment: everything a di module takes, plus the contract, the activities provider and the workflow source. The sugar imports the starter, provides the activities and exports TemporalRuntime, handing back exactly the module Module(...) would have declared over the augmented tuples.

export const OrderTemporalWorker = TemporalModule("OrderTemporalWorker")({
  contract: orderContract,
  activities: orderActivities,
  workflows: { workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js") },
  imports: [OrderApplicationModule, OrderPersistenceModule, FulfillmentModule],
});
await runMain(OrderTemporalWorker);

Type Parameters

Type Parameter
`Name` extends `string`

Parameters

Parameter	Type
`name`	`Name`

Returns

<C, ActivitiesError, ActivitiesNeeds, Declared, Unit, I, P, X, N>(options) => Module<ResolvedExports<readonly [typeof TemporalRuntime, X]>, | ErrOf<readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P][number]> | ErrOfModule<readonly [I, TemporalStarter<C, Unit>][number]>, | Exclude<NeedOf<readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P][number]>, Available<readonly [I, TemporalStarter<C, Unit>], readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P]>> | Exclude<NeedsOfModule<readonly [I, TemporalStarter<C, Unit>][number]>, Available<readonly [I, TemporalStarter<C, Unit>], readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, P]>>>

TemporalWorkflowActivities()

function TemporalWorkflowActivities<C, K>(contract, key): <D, U>(options) => MintedActivities<C, K, InstanceType<D[keyof D]>, U>;

Defined in: packages/temporal-worker/src/workflow-activities.ts:142

One workflow's activities, as a provider on a port of its own.

A worker that polls one queue for several workflows is several pieces, each declaring the services its own activities call; TemporalActivities(contract)([...]) composes them. contract is read for its TYPE only, and types both key and the record — so an activity the workflow does not declare is a compile error here rather than at startup.

key is any top-level key of the activities record, which includes a contract-global activity as well as a workflow; the name is imprecise in that one case deliberately, since narrowing it would lock such a contract out of the split.

There is no name to give: the key IS the port's name.

unit declares the ports the activities read off context.unit, resolved out of the fork the attempt opened; the root's unit.activity module must export every one of them.

Type Parameters

Type Parameter
`C` extends `ContractDefinition`
`K` extends `string`

Parameters

Parameter	Type
`contract`	`C`
`key`	`K`

Returns

<D, U>(options) => MintedActivities<C, K, InstanceType<D[keyof D]>, U>

@btravstack/temporal-worker ​

Classes ​

TemporalConfig ​

Extends ​

Constructors ​

Constructor ​

Returns ​

Inherited from ​

Properties ​

TemporalConnection ​

Extends ​

Constructors ​

Constructor ​

Returns ​

Inherited from ​

Properties ​

TemporalRuntime ​

Extends ​

Constructors ​

Constructor ​

Returns ​

Inherited from ​

Properties ​

TemporalUnreachable ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Inherited from ​

Properties ​

Type Aliases ​

ActivitiesInstanceOf ​

Type Parameters ​

ActivitiesPortOf ​

Type Parameters ​

ActivityInputOf ​

Type Parameters ​

ActivityInputPortOf ​

Type Parameters ​

TemporalInfo ​

Properties ​

TemporalModuleOptions ​

Type Declaration ​

Type Parameters ​

TemporalOptions ​

Type Declaration ​

Type Parameters ​

WorkflowActivitiesPortOf ​

Type Parameters ​

WorkflowSource ​

Functions ​

ActivityInput() ​

Type Parameters ​

Parameters ​

Returns ​

temporal() ​

Type Parameters ​

Parameters ​

Returns ​

TemporalActivities() ​

Type Parameters ​

Parameters ​

Returns ​

TemporalModule() ​

Type Parameters ​

Parameters ​

Returns ​

TemporalWorkflowActivities() ​

Type Parameters ​

Parameters ​

Returns ​

@btravstack/temporal-worker

Classes

TemporalConfig

Extends

Constructors

Constructor

Returns

Inherited from

Properties

TemporalConnection

Extends

Constructors

Constructor

Returns

Inherited from

Properties

TemporalRuntime

Extends

Constructors

Constructor

Returns

Inherited from

Properties

TemporalUnreachable

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

Type Aliases

ActivitiesInstanceOf

Type Parameters

ActivitiesPortOf

Type Parameters

ActivityInputOf

Type Parameters

ActivityInputPortOf

Type Parameters

TemporalInfo

Properties

TemporalModuleOptions

Type Declaration

Type Parameters

TemporalOptions

Type Declaration

Type Parameters

WorkflowActivitiesPortOf

Type Parameters

WorkflowSource

Functions

ActivityInput()

Type Parameters

Parameters

Returns

temporal()

Type Parameters

Parameters

Returns

TemporalActivities()

Type Parameters

Parameters

Returns

TemporalModule()

Type Parameters

Parameters

Returns

TemporalWorkflowActivities()

Type Parameters

Parameters

Returns