@btravstack/temporal-worker 0.12.0 → 0.14.0

package/README.md

@@ -36,9 +36,9 @@ class DuplicateOrder extends TaggedError("DuplicateOrder")<{ readonly id: string
 class InvalidOrderId extends TaggedError("InvalidOrderId")<{ readonly id: string }> {}
 class InvalidQuantity extends TaggedError("InvalidQuantity")<{ readonly id: string }> {}
 declare const TenantId: (value: string) => string;
+class Tenant extends Port("Tenant")<string> {}
 class PlaceOrder extends Port("PlaceOrder")<{
   readonly execute: (
-    tenantId: string,
     id: string,
     quantity: number,
   ) => AsyncResult<
@@ -46,7 +46,9 @@ class PlaceOrder extends Port("PlaceOrder")<{
     DuplicateOrder | InvalidOrderId | InvalidQuantity
   >;
 }> {}
-declare const OrderApplicationModule: Module<PlaceOrder, never, never>;
+// The application's own vertical, composed INSIDE the unit: its use case is
+// bound to whichever tenant the attempt named.
+declare const OrderApplicationModule: Module<PlaceOrder, never, Tenant>;
 declare const OrderPersistenceModule: AnyModule;
 
 // The contract this README's worker serves — one workflow, one activity, one
@@ -57,7 +59,7 @@ const contract = defineContract({
     placeOrder: defineWorkflow({
       input: z.object({ tenantId: z.uuidv7(), orderId: z.uuidv7(), quantity: z.number() }),
       output: z.object({ id: z.uuidv7() }),
-      idempotency: "allow-duplicate",
+      startPolicy: "allow-duplicate",
       activities: {
         place: defineActivity({
           input: z.object({ tenantId: z.uuidv7(), orderId: z.uuidv7(), quantity: z.number() }),
@@ -75,30 +77,49 @@ const contract = defineContract({
 });
 
 const AppModule = Module("App")({
-  imports: [OrderApplicationModule, OrderPersistenceModule, observability(), otel()],
-  exports: [PlaceOrder, Logger],
+  imports: [OrderPersistenceModule, observability(), otel()],
+  exports: [Logger],
 });
 -->
 
 ```ts
 import { runMain, Logger } from "@btravstack/core";
+import { Provider } from "@btravstack/di";
 import {
+  ActivityInput,
   TemporalActivities,
   TemporalModule,
 } from "@btravstack/temporal-worker";
 import { P } from "unthrown";
 
-// The application's half: its activities, as a service built from the use
-// cases it declares — closures over them, no context read at call time — on
-// the starter's own activities port, typed by the contract (a worker serves
-// one activities record, so there is nothing to name).
+// The module forked around every activity attempt, SEEDED with the validated
+// input on `ActivityInput(contract)`. The tenant the contract carries is
+// claimed here once — not at each activity — and the application's vertical
+// is composed over it, so `PlaceOrder` is bound before any activity runs.
+const ActivityUnit = Module("ActivityUnit")({
+  needs: [ActivityInput(contract)],
+  imports: [OrderApplicationModule],
+  provides: [
+    Provider(Tenant)({
+      inject: { input: ActivityInput(contract) },
+      sync: ({ input }) => TenantId(input.tenantId),
+    }),
+  ],
+  exports: [Tenant, PlaceOrder],
+});
+
+// The application's half: its activities, on the starter's own activities
+// port, typed by the contract (a worker serves one activities record, so
+// there is nothing to name). What the leaves read off `context.unit` is
+// declared once, beside `inject`.
 const orderActivities = TemporalActivities(contract)({
-  inject: { place: PlaceOrder },
-  sync: ({ place }) => ({
+  inject: {},
+  unit: { place: PlaceOrder },
+  sync: () => ({
     placeOrder: {
-      place: ({ errors, input }) =>
-        place
-          .execute(TenantId(input.tenantId), input.orderId, input.quantity)
+      place: ({ errors, context, input }) =>
+        context.unit.place
+          .execute(input.orderId, input.quantity)
           .mapErrCases((matcher) =>
             matcher
               .with(P.tag("DuplicateOrder"), (error) =>
@@ -124,6 +145,7 @@ const OrderWorker = TemporalModule("OrderWorker")({
     workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
   },
   imports: [AppModule],
+  unit: { activity: ActivityUnit },
 });
 
 await runMain(OrderWorker);
@@ -140,7 +162,7 @@ startup `Err`, not a defect. `runtimeInfo()` reads `{ taskQueue, namespace }`
 back once the worker is polling.
 
 A worker polling for several workflows can be several slices instead of one
-record: `TemporalWorkflowActivities(contract, key)({ inject: { name: Dep }, ...arm })` mints a
+record: `TemporalWorkflowActivities(contract, key)({ inject: { name: Dep }, unit, sync })` mints a
 provider for ONE workflow's activities (or a contract-global activity),
 typed by the key alone, and `TemporalActivities(contract)([...])` composes an
 array of them into the same activities provider `TemporalModule` takes — the
@@ -153,6 +175,16 @@ di's duplicate-provider defect at build once **both** pieces are discharged as
 providers in one graph — wire in only one and the other's implementation is
 silently never registered.
 
+A piece's `unit` names the ports its activities read off `context.unit`,
+resolved out of the per-attempt fork of the module bound on `unit.activity` —
+which is seeded with the validated input on `ActivityInput(contract)`, so a unit
+module derives a tenant from the invocation rather than from an ambient record.
+The record arm above takes the same `unit:` — one record for every entry in it —
+so a worker that has not outgrown one function reaches `context.unit` without
+slicing first. The root is checked against what was declared either way: bind a
+module that does not export one of those ports and `TemporalModule` refuses it,
+naming the port.
+
 Its own test suite needs a **Docker daemon**: the specs run against the shared
 `temporalio/auto-setup` container `internal/test-infra` starts once per machine and every
 workspace reuses. Nothing else here does.
@@ -184,6 +216,7 @@ supplies it:
 | `namespace`   | pins the namespace instead of reading `TEMPORAL_NAMESPACE`                                                              |
 | `gracePeriod` | pins `TEMPORAL_GRACE_PERIOD_MS` — Temporal's `shutdownGraceTime`, a `Duration` (default `10_000` ms)                    |
 | `forceAfter`  | pins `TEMPORAL_FORCE_AFTER_MS` — Temporal's `shutdownForceTime` (default `15_000` ms); keep it under `DRAIN_TIMEOUT_MS` |
+| `unit`        | `{ activity }` — the module the worker forks around every activity it dispatches, seeded with the validated input       |
 
 The full table — required/optional, defaults, and the reasoning — lives on
 [the reference page](https://btravstack.github.io/btravstack/reference/temporal-worker),

package/dist/index.cjs

@@ -7,10 +7,123 @@ let _temporalio_common = require("@temporalio/common");
 let _temporalio_worker = require("@temporalio/worker");
 let unthrown = require("unthrown");
 let _temporalio_activity = require("@temporalio/activity");
+//#region src/unit.ts
+/**
+* Where `activityUnits` leaves the forked context for the piece wrappers to
+* read. A symbol rather than a name: the middleware merges it into the context
+* every activity sees, and a string key would appear on the record an activity
+* written against the `{ inject, sync }` arm destructures.
+*/
+const UNIT_SCOPE = Symbol("@btravstack/temporal-worker/unit-scope");
+/**
+* The declared record, as a getter per name resolved on read out of the fork.
+* Neither writable nor configurable — an activity reads what the fork holds, and
+* cannot reshape the record under the next attempt. With no `unit.activity`
+* bound there is nothing to resolve from, so the record is empty whatever was
+* declared.
+*/
+const unitRecordOf = (forked, record) => {
+	const unit = {};
+	if (forked === void 0) return unit;
+	for (const [name, port] of Object.entries(record)) Object.defineProperty(unit, name, {
+		enumerable: true,
+		get: () => forked.get(port)
+	});
+	return unit;
+};
+/**
+* One entry of the activities record — a contract-global activity's own
+* implementation, or the record of them a workflow key carries — with its
+* piece's declared record put on `context.unit`. Applied once per piece as di
+* constructs it, so an attempt costs one record and one context object.
+*/
+const withUnit = (record, entry) => {
+	const wrap = (implementation) => (helpers, input) => {
+		const { [UNIT_SCOPE]: forked, ...rest } = helpers.context ?? {};
+		return implementation({
+			...helpers,
+			context: {
+				...rest,
+				unit: unitRecordOf(forked, record)
+			}
+		}, input);
+	};
+	return typeof entry === "function" ? wrap(entry) : Object.fromEntries(Object.entries(entry).map(([name, implementation]) => [name, wrap(implementation)]));
+};
+//#endregion
+//#region src/workflow-activities.ts
+/** One id, declared once, so no contract instantiating it warns about a duplicate. */
+const ActivityInputPort = (0, _btravstack_di.Port)("ActivityInput");
+/**
+* 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.
+*/
+const ActivityInput = (contract) => {
+	return ActivityInputPort;
+};
+/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
+const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
+/**
+* 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.
+*/
+const TemporalWorkflowActivities = (contract, key) => {
+	const port = class extends (0, _btravstack_di.Port)(`${WORKFLOW_ACTIVITIES_PREFIX}${key}`) {};
+	return (options) => {
+		const record = options.unit ?? {};
+		return Object.assign((0, _btravstack_di.Provider)(port)({
+			inject: options.inject,
+			sync: (services) => withUnit(record, options.sync(services))
+		}), { unit: record });
+	};
+};
+//#endregion
 //#region src/activity-units.ts
 /**
-* Open one kernel unit per activity attempt. It injects nothing — `next()`
-* unchanged — so the ambient `currentUnit()` record is what an adapter reads.
+* Open one kernel unit per activity attempt, forking `unit` — when one is
+* bound — after the activity is invoked, before it runs; the fork is torn down
+* when the unit closes. It is seeded with the validated input on
+* `ActivityInput(contract)`, so a unit module derives a tenant from the
+* invocation rather than reading one off an ambient record. With no `unit`
+* bound, `next()` runs unchanged, so the ambient `currentUnit()` record is what
+* an adapter reads.
+*
+* The forked context rides the invocation's context under {@link UNIT_SCOPE},
+* where each piece's own wrapper turns it into the typed `context.unit` record
+* that piece declared — the records live with the pieces, so a hand-composed
+* `temporal()` gets them without threading a second option through the starter,
+* and the middleware never has to map Temporal's FLAT activity name back to the
+* workflow key its piece was minted under.
 *
 * **That includes the kernel's per-unit `AbortSignal`**, and it is the only
 * route to it: an activity has no parameter to receive one through. Temporal's
@@ -20,13 +133,13 @@ let _temporalio_activity = require("@temporalio/activity");
 * No `Result`-unwrapping boundary, deliberately: `declareActivitiesHandler` owns
 * the mapping from a settled `Result` to an activity failure.
 */
-const activityUnits = (host, observers) => (_invocation, next) => {
+const activityUnits = (host, observers, unit) => (invocation, next) => {
 	const settle = (0, _btravstack_core.observe)(observers, {
 		component: "temporal",
 		name: "attempt",
 		attributes: { activity: (0, _temporalio_activity.activityInfo)().activityType }
 	});
-	return host.run(metaFor(), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+	return host.run(metaFor(), (scope) => unit === void 0 ? next() : scope.fork(unit, [[ActivityInputPort, invocation.input]]).flatMap((forked) => next({ context: { [UNIT_SCOPE]: forked } }))).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
 		outcome: "error",
 		cause: failure.tag === "Err" ? failure.error : failure.cause
 	}));
@@ -164,7 +277,7 @@ const createWorker = (host, connection, config, activities, options, observers)
 	const { namespace } = config;
 	return (0, unthrown.fromThrowable)(() => (0, _temporal_contract_worker_activity.declareActivitiesHandler)({
 		contract: options.contract,
-		middleware: activityUnits(host, observers),
+		middleware: activityUnits(host, observers, options.unit?.activity),
 		activities
 	}), startFailed)().toAsync().flatMap((handler) => (0, unthrown.fromPromise)(_temporalio_worker.Worker.create({
 		connection,
@@ -200,30 +313,6 @@ const poll = (worker, taskQueue, namespace) => {
 	};
 };
 //#endregion
-//#region src/workflow-activities.ts
-/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
-const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
-/**
-* 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.
-*/
-const TemporalWorkflowActivities = (contract, key) => {
-	const port = class extends (0, _btravstack_di.Port)(`${WORKFLOW_ACTIVITIES_PREFIX}${key}`) {};
-	return (0, _btravstack_di.Provider)(port);
-};
-//#endregion
 //#region src/temporal-module.ts
 /**
 * `Module(name)({...})` for a Temporal worker deployment: everything a di module
@@ -263,12 +352,12 @@ const TemporalModule = (name) => (options) => {
 * TemporalActivities(orderContract)([fulfillOrder, chargeOrder])
 * ```
 *
-* The first is di's own `Provider(port)` on the starter's activities port
-* typed for the contract. 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.
+* 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.
 */
 const TemporalActivities = (contract) => {
 	const build = (0, _btravstack_di.Provider)(TemporalActivitiesPort);
@@ -276,9 +365,17 @@ const TemporalActivities = (contract) => {
 		inject: Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(27), piece.port])),
 		sync: (services) => services
 	});
-	return ((first) => Array.isArray(first) ? compose(first) : build(first));
+	const whole = (options) => {
+		const record = options.unit ?? {};
+		return build({
+			inject: options.inject,
+			sync: (services) => Object.fromEntries(Object.entries(options.sync(services)).map(([key, entry]) => [key, withUnit(record, entry)]))
+		});
+	};
+	return ((first) => Array.isArray(first) ? compose(first) : whole(first));
 };
 //#endregion
+exports.ActivityInput = ActivityInput;
 exports.TemporalActivities = TemporalActivities;
 exports.TemporalConfig = TemporalConfig;
 exports.TemporalConnection = TemporalConnection;