@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
new TemporalApiKeyUnavailable(args): TemporalApiKeyUnavailable;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | void |
Returns
Inherited from
TaggedError("TemporalApiKeyUnavailable").constructor
Properties
| Property | Modifier | Type | Default value | Overrides | Inherited from | Defined in |
|---|---|---|---|---|---|---|
_tag | readonly | "TemporalApiKeyUnavailable" | undefined | - | TaggedError("TemporalApiKeyUnavailable")._tag | node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363 |
cause? | public | unknown | undefined | - | TaggedError("TemporalApiKeyUnavailable").cause | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24 |
message | public | string | "the Temporal API key is unavailable" | TaggedError("TemporalApiKeyUnavailable").message | - | packages/temporal-worker/src/connection-security.ts:52 |
name | public | string | undefined | - | TaggedError("TemporalApiKeyUnavailable").name | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074 |
stack? | public | string | undefined | - | TaggedError("TemporalApiKeyUnavailable").stack | node_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
PortInstance<"TemporalConfig",object&TemporalConnectionSecurity>
Constructors
Constructor
new TemporalConfig(): TemporalConfig;Defined in: packages/di/dist/index.d.mts:15
Returns
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
| Property | Modifier | Type | Inherited from | Defined in |
|---|---|---|---|---|
[ID] | readonly | "TemporalConfig" | Port("TemporalConfig").[ID] | packages/di/dist/index.d.mts:11 |
[SERVICE] | readonly | object & TemporalConnectionSecurity | Port("TemporalConfig").[SERVICE] | packages/di/dist/index.d.mts:12 |
portId | static readonly | "TemporalConfig" | Port("TemporalConfig").portId | packages/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
new TemporalConnection(): TemporalConnection;Defined in: packages/di/dist/index.d.mts:15
Returns
Inherited from
Port("TemporalConnection")<NativeConnection>.constructor
Properties
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
RuntimePort<Runtime<never,TemporalInfo>>
Constructors
Constructor
new TemporalRuntime(): TemporalRuntime;Defined in: packages/di/dist/index.d.mts:15
Returns
Inherited from
RuntimePort<Runtime<never, TemporalInfo>>.constructor
Properties
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
new TemporalUnreachable(args): TemporalUnreachable;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | object & object |
Returns
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.12.1/node_modules/unthrown/dist/index.d.mts:2363 |
address | readonly | string | - | TaggedError("TemporalUnreachable").address | packages/temporal-worker/src/temporal-runtime.ts:113 |
cause | public | unknown | - | TemporalApiKeyUnavailable.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:116 |
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:153
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:147
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: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
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
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
| Property | Modifier | Type | Defined in |
|---|---|---|---|
read | readonly | () => AsyncResult<string, TemporalApiKeyUnavailable> | packages/temporal-worker/src/connection-security.ts:47 |
TemporalConnectionSecurity
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
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
apiKey? | readonly | string | TEMPORAL_API_KEY: an API key sent as Authorization: Bearer. | packages/temporal-worker/src/connection-security.ts:38 |
apiKeyPath? | readonly | string | TEMPORAL_API_KEY_PATH: a file holding the API key, read again as it rotates. | packages/temporal-worker/src/connection-security.ts:40 |
clientCertPath? | readonly | string | TEMPORAL_TLS_CLIENT_CERT_PATH: the client certificate presented for mTLS, with its key. | packages/temporal-worker/src/connection-security.ts:34 |
clientKeyPath? | readonly | string | TEMPORAL_TLS_CLIENT_KEY_PATH: the client certificate's private key. | packages/temporal-worker/src/connection-security.ts:36 |
credentialsReloadMs? | readonly | number | TEMPORAL_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? | readonly | string | TEMPORAL_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? | readonly | string | TEMPORAL_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? | readonly | boolean | TEMPORAL_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
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
| Property | Modifier | Type | Defined in |
|---|---|---|---|
namespace | readonly | string | packages/temporal-worker/src/temporal-runtime.ts:64 |
taskQueue | readonly | string | packages/temporal-worker/src/temporal-runtime.ts:63 |
TemporalModuleOptions
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 Parameter | Default 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 DataConverterPort | never |
ApiKey extends PortClassOf<string, TemporalApiKeySource> | never |
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:122 |
contract | C | The temporal-contract contract; the task queue this worker polls is read off it. | packages/temporal-worker/src/temporal-module.ts:115 |
exports? | X | The 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? | 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:133 |
provides? | P | - | packages/temporal-worker/src/temporal-module.ts:126 |
TemporalOptions
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 Parameter | Default type |
|---|---|
C extends ContractDefinition | - |
Unit extends AnyUnitModule | undefined | undefined |
Converter extends DataConverterPort | never |
ApiKey extends PortClassOf<string, TemporalApiKeySource> | never |
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:230 |
WorkflowActivitiesPortOf
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
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()
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.
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
TemporalActivities()
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.
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, 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.
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, 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()
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
| Parameter | Type |
|---|---|
contract | C |
key | K |
Returns
<D, U, M>(options) => MintedActivities<C, K, InstanceType<D[keyof D]>, U, M>