Skip to content

@btravstack/temporal-worker


@btravstack/temporal-worker ​

Classes ​

TemporalApiKeyUnavailable ​

Defined in: packages/temporal-worker/src/connection-security.ts:51

A renewable credential could not be obtained; its value is never diagnostic data.

Extends ​

  • TaggedErrorInstance<"TemporalApiKeyUnavailable", { }>

Constructors ​

Constructor ​
ts
new TemporalApiKeyUnavailable(args): TemporalApiKeyUnavailable;

Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386

Parameters ​
ParameterType
argsvoid
Returns ​

TemporalApiKeyUnavailable

Inherited from ​

TaggedError("TemporalApiKeyUnavailable").constructor

Properties ​

PropertyModifierTypeDefault valueOverridesInherited fromDefined in
_tagreadonly"TemporalApiKeyUnavailable"undefined-TaggedError("TemporalApiKeyUnavailable")._tagnode_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363
cause?publicunknownundefined-TaggedError("TemporalApiKeyUnavailable").causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstring"the Temporal API key is unavailable"TaggedError("TemporalApiKeyUnavailable").message-packages/temporal-worker/src/connection-security.ts:52
namepublicstringundefined-TaggedError("TemporalApiKeyUnavailable").namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstringundefined-TaggedError("TemporalApiKeyUnavailable").stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

TemporalConfig ​

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

Where the Temporal service is, as a service: the starter 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. The connection's security is read from TEMPORAL_TLS, TEMPORAL_TLS_*, TEMPORAL_API_KEY, TEMPORAL_API_KEY_PATH and TEMPORAL_CREDENTIALS_RELOAD_MS, and is never pinned. @btravstack/temporal-client's temporalConnection accepts this port as its settings, so a client in the worker's process connects alike.

Extends ​

Constructors ​

Constructor ​
ts
new TemporalConfig(): TemporalConfig;

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

Returns ​

TemporalConfig

Inherited from ​

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

Properties ​

PropertyModifierTypeInherited fromDefined in
[ID]readonly"TemporalConfig"Port("TemporalConfig").[ID]packages/di/dist/index.d.mts:11
[SERVICE]readonlyobject & TemporalConnectionSecurityPort("TemporalConfig").[SERVICE]packages/di/dist/index.d.mts:12
portIdstatic readonly"TemporalConfig"Port("TemporalConfig").portIdpackages/di/dist/index.d.mts:16

TemporalConnection ​

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

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 ​
ts
new TemporalConnection(): TemporalConnection;

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

Returns ​

TemporalConnection

Inherited from ​

Port("TemporalConnection")<NativeConnection>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
[ID]readonly"TemporalConnection"Port("TemporalConnection").[ID]packages/di/dist/index.d.mts:11
[SERVICE]readonlyNativeConnectionPort("TemporalConnection").[SERVICE]packages/di/dist/index.d.mts:12
portIdstatic readonly"TemporalConnection"Port("TemporalConnection").portIdpackages/di/dist/index.d.mts:16

TemporalRuntime ​

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

The runtime's port: what the starter provides, and what TemporalModule exports for start to boot.

Extends ​

Constructors ​

Constructor ​
ts
new TemporalRuntime(): TemporalRuntime;

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

Returns ​

TemporalRuntime

Inherited from ​

RuntimePort<Runtime<never, TemporalInfo>>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
[ID]readonly"Runtime"RuntimePort.[ID]packages/di/dist/index.d.mts:11
[SERVICE]readonlyRuntimeRuntimePort.[SERVICE]packages/di/dist/index.d.mts:12
portIdstatic readonly"Runtime"RuntimePort.portIdpackages/di/dist/index.d.mts:16

TemporalUnreachable ​

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

The service at TemporalConfig.address did not answer — or refused the connection's TLS or credentials. 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 ​
ts
new TemporalUnreachable(args): TemporalUnreachable;

Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386

Parameters ​
ParameterType
argsobject & object
Returns ​

TemporalUnreachable

Inherited from ​

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

Properties ​

PropertyModifierTypeOverridesInherited fromDefined in
_tagreadonly"TemporalUnreachable"-TaggedError("TemporalUnreachable")._tagnode_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363
addressreadonlystring-TaggedError("TemporalUnreachable").addresspackages/temporal-worker/src/temporal-runtime.ts:113
causepublicunknown-TemporalApiKeyUnavailable.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError("TemporalUnreachable").message-packages/temporal-worker/src/temporal-runtime.ts:116
namepublicstring-TaggedError("TemporalUnreachable").namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstring-TaggedError("TemporalUnreachable").stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Type Aliases ​

ActivitiesInstanceOf ​

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

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

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

Type Parameters ​

Type Parameter
C extends ContractDefinition

ActivitiesPortOf ​

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

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

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

Type Parameters ​

Type Parameter
C extends ContractDefinition

ActivityInputOf ​

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

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

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

Type Parameters ​

Type Parameter
C extends ContractDefinition

ActivityInputPortOf ​

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

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

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

Type Parameters ​

Type Parameter
C extends ContractDefinition

TemporalApiKeySource ​

ts
type TemporalApiKeySource = object;

Defined in: packages/temporal-worker/src/connection-security.ts:46

An application-owned source of renewable bearer credentials; it owns caching and expiry.

Properties ​

PropertyModifierTypeDefined in
readreadonly() => AsyncResult<string, TemporalApiKeyUnavailable>packages/temporal-worker/src/connection-security.ts:47

TemporalConnectionSecurity ​

ts
type TemporalConnectionSecurity = object;

Defined in: packages/temporal-worker/src/connection-security.ts:22

How the worker's connection to Temporal is secured, as the starter binds it from the environment. Every field may be absent, which is today's plaintext connection with no key.

Properties ​

PropertyModifierTypeDescriptionDefined in
apiKey?readonlystringTEMPORAL_API_KEY: an API key sent as Authorization: Bearer.packages/temporal-worker/src/connection-security.ts:38
apiKeyPath?readonlystringTEMPORAL_API_KEY_PATH: a file holding the API key, read again as it rotates.packages/temporal-worker/src/connection-security.ts:40
clientCertPath?readonlystringTEMPORAL_TLS_CLIENT_CERT_PATH: the client certificate presented for mTLS, with its key.packages/temporal-worker/src/connection-security.ts:34
clientKeyPath?readonlystringTEMPORAL_TLS_CLIENT_KEY_PATH: the client certificate's private key.packages/temporal-worker/src/connection-security.ts:36
credentialsReloadMs?readonlynumberTEMPORAL_CREDENTIALS_RELOAD_MS (default 60000): how often the files above and a composed credential source are read again.packages/temporal-worker/src/connection-security.ts:42
serverCaCertPath?readonlystringTEMPORAL_TLS_SERVER_CA_CERT_PATH: the PEM bundle the server's certificate is verified against, instead of the system's roots.packages/temporal-worker/src/connection-security.ts:30
serverName?readonlystringTEMPORAL_TLS_SERVER_NAME: the name the server's certificate is verified for, and sent as SNI.packages/temporal-worker/src/connection-security.ts:32
tls?readonlybooleanTEMPORAL_TLS: TLS on or off. Unset, it is on exactly when an API key is set, as Temporal's own clients do. The server and client certificate fields require it on.packages/temporal-worker/src/connection-security.ts:28

TemporalInfo ​

ts
type TemporalInfo = object;

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

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

Properties ​

PropertyModifierTypeDefined in
namespacereadonlystringpackages/temporal-worker/src/temporal-runtime.ts:64
taskQueuereadonlystringpackages/temporal-worker/src/temporal-runtime.ts:63

TemporalModuleOptions ​

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

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

Type Parameters ​

Type ParameterDefault type
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, Converter, ApiKey>, Provides<P, C, ActivitiesError, ActivitiesNeeds>>[]-
N extends readonly AnyPort[] | undefined-
Converter extends DataConverterPortnever
ApiKey extends PortClassOf<string, TemporalApiKeySource>never

Type Declaration ​

NameTypeDescriptionDefined in
activitiesProvider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds> & objectThe 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:122
contractCThe temporal-contract contract; the task queue this worker polls is read off it.packages/temporal-worker/src/temporal-module.ts:115
exports?XThe application's own exports; TemporalRuntime and visible kernel infrastructure are added.packages/temporal-worker/src/temporal-module.ts:128
imports?I-packages/temporal-worker/src/temporal-module.ts:125
needs?NWhat 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:133
provides?P-packages/temporal-worker/src/temporal-module.ts:126

TemporalOptions ​

ts
type TemporalOptions<C, Unit, Converter, ApiKey> = TemporalTuning<Unit, Converter, ApiKey> & object & WorkflowsOption<C>;

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

Type Parameters ​

Type ParameterDefault type
C extends ContractDefinition-
Unit extends AnyUnitModule | undefinedundefined
Converter extends DataConverterPortnever
ApiKey extends PortClassOf<string, TemporalApiKeySource>never

Type Declaration ​

NameTypeDescriptionDefined in
contractCThe 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:230

WorkflowActivitiesPortOf ​

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

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

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 ​

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

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

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() ​

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

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

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.

ts
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 ​

ParameterType
contractC

Returns ​

ActivityInputPortOf<C>


TemporalActivities() ​

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

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

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

ts
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 ​

ParameterType
contractC

Returns ​

Whole<C> & Compose<C>


TemporalModule() ​

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

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

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.

ts
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 ​

ParameterType
nameName

Returns ​

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


TemporalWorkflowActivities() ​

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

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

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. The contract types both key and the record and supplies the task queue that namespaces the port. An undeclared activity is a compile error rather than a startup failure.

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.

The contract's task queue and the key identify the port; wire activity names stay unchanged.

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.

fork names the unit module THESE activities fork per attempt instead of the root's unit.activity — seeded with the validated input on ActivityInput(contract) the same way — for a worker whose activities do not all carry the same scope: a listing activity with no tenant in its input beside a fan-out whose activities each act for one. The ports unit declares are then checked against this module, here.

Type Parameters ​

Type Parameter
C extends ContractDefinition
K extends string

Parameters ​

ParameterType
contractC
keyK

Returns ​

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

Released under the MIT License.