EXAMPLES.md

Temporal samples, mirrored

The coverage matrix: every sample in temporalio/samples-typescript mapped to how it is expressed with this package. A sample is marked supported only when a test in this package exercises the same mechanism.

Legend: ✅ supported (tested) · 🟢 works unchanged (this package does not touch that layer) · ➖ not applicable (infra/app scaffolding with no workflow-semantics content).

Basics

Sample	Status	With this package
hello-world	✅	Workflow.toLayer + Activity.make + callRawActivity. Test: primitives.test.ts (happy path).
activities-examples	🟢	Activity implementations, retries, and timeouts are plain Temporal — configured on proxyActivities in the bundle, untouched by the shim.
activities-dependency-injection	🟢	Activity-side pattern; makeEffectWorkflowActivities is itself an instance of it.
activities-cancellation-heartbeating	✅	Workflow-side cancellation reaches in-flight activities through callRawActivity scopes; heartbeating is activity-side and untouched. Test: primitives.test.ts (in-flight cancellation).
standalone-activity	➖	No workflow involved.
worker-specific-task-queues	🟢	Multiple proxyActivities({ taskQueue }) proxies in one bundle work unchanged.

Signals, queries, updates

Sample	Status	With this package
signals-queries	✅	DurableDeferred.await (signal) + deferredState (query) + interrupt (cancellation); custom state reads via StateCell. Tests: primitives.test.ts, mailbox.test.ts.
state	✅	Both halves: DurableMailbox for the repeated update signals, StateCell (setStateCell / readStateCell) for the query — read mid-flight and after completion. Test: mailbox.test.ts.
mutex	✅	Lock workflow loops on takeMailbox, granting and collecting releases via workflow-to-workflow offerMailbox; the test asserts serialized critical sections across three contenders. Test: mutex.test.ts.
message-passing	✅	DurableUpdate (make + takeUpdate + executeUpdate): request/response with typed success AND typed failure riding the update result. Test: message-passing.test.ts.
query-subscriptions	✅	DurableMailbox feeds the state, StateCell reads observe it evolving across repeated queries. Test: mailbox.test.ts.
expense (async activity completion)	🟢	Async completion is activity-side (CompleteAsyncError + client), untouched by the shim.

Timers

Sample	Status	With this package
timer-progress	✅	DurableClock.sleep. Test: primitives.test.ts (delay skipped by the time-skipping server).
sleep-for-days	✅	Same mechanism; a Temporal timer's duration is unbounded. Test: primitives.test.ts pins a 2-minute durable delay under time skipping — the same mechanism at any duration.
timer-examples	✅	The order-timeout race is Effect.raceFirst(activity, DurableClock.sleep) — pinned by the timeout-activity fixture mode and the primitives.test.ts test "cancels the server-side activity when the calling FIBER is interrupted", which asserts the timed-out activity is cancelled server-side, not abandoned. The UpdatableTimer half races takeMailbox against the timer. Test: mailbox.test.ts.

Workflow composition

Sample	Status	With this package
child-workflows	✅	MyChild.execute in a workflow body; typed results/failures compose, cancellation cascades, discard = fire-and-forget, taken ids attach. Tests: child.test.ts.
saga	✅	Workflow.withCompensation, firing on typed failure and on interrupt. Tests: primitives.test.ts, child.test.ts.
continue-as-new	✅	continueAsNew(workflow, payload) (engine-sandbox): ends the run and starts a fresh one with the same workflow id. Test: continue-as-new.test.ts — asserts the fresh history, not just the looped result.
batch-sliding-window	✅	Sliding window of discarded children reporting completion via workflow-to-workflow mailbox; the orchestrator continues-as-new mid-batch, draining reports with pollMailbox into the carried in-flight set. Test: batch.test.ts.
dsl-interpreter	✅	The payload carries a declarative program (sequential steps of single or parallel activity calls) and Effect interprets it in-workflow. Test: dsl.test.ts.
early-return	✅	A forked fiber serves the confirmation DurableUpdate once authorization lands, while the main flow continues to the final result. Test: early-return.test.ts.
polling	✅	The infrequent variant: the poll interval IS the activity retry policy, so the workflow is one callRawActivity. Test: polling.test.ts. Frequent polling inside one activity is activity-side; unbounded polling adds continueAsNew.
patching-api	✅	Versioning.match: an ordered version chain per code site with typed version literals and union-typed channels; fresh runs take the newest case, replays their own. Tests: versioning-chain.test.ts (three generations, append-safety, negative control).

Scheduling and client features

Sample	Status	With this package
schedules	✅	createWorkflowSchedule (engine-client) wires the wire-encoded payload into the schedule's action; fired runs are addressed by their schedule-generated ids through the ordinary poll path. Test: schedules.test.ts.
cron-workflows	➖	Deprecated upstream in favor of schedules.
search-attributes	🟢	upsertSearchAttributes is one Effect.sync in a workflow body — the shim contributes nothing to pin, so no shim test.
eager-workflow-start	🟢	A client start option; compatible, untested.
grpc-calls	➖	Raw client queries; no workflow-semantics content.

Payload converters

Sample	Status	With this package
encryption	✅	Byte-level PayloadCodecs (encryption, compression) pass through untouched — installed on client and worker. The test pins the round-trip for args, results, update request/response, state-cell queries, deferred-done signals, and typed-failure details; mailboxes ride the same signal machinery, though the mailbox surface itself is not directly exercised. Test: payload-codec.test.ts, which also asserts the raw wire was actually transformed.
protobufs, ejson	🟢	Format-level converters compose as long as they keep JSON handling (the standard composite pattern): every shim payload is schema-encoded JSON, so a JSON-capable converter passes them through while converting the application's other workflows' payloads however it likes. A JSON-less converter (protobuf-only) cannot carry shim workflows.

Nexus

Sample	Status	With this package
nexus-hello	✅	Both directions: sync operations are plain workflow-API promises via callRawActivity; workflow-backed operations serve a shim workflow through effectWorkflowRunOperation (nexus module) and are called with callNexusWorkflowOperation, typed success and typed failure decoding across the boundary. Test: nexus.test.ts (local dev server — the time-skipping server has no Nexus support).
nexus-cancellation	✅	Interrupting the caller cancels the in-flight operation AND its backing shim workflow; the interrupted run waits (bounded) for cancelled calls to settle so the cancellation handshake completes before the caller closes. Test: nexus.test.ts.
nexus-standalone-operations	➖	Client-side operation calls without a caller workflow; no shim involvement.

Infra / app scaffolding (no workflow-semantics content)

fetch-esm, hello-world-js, hello-world-mtls, monorepo-folders, production, env-config, custom-logger, sinks, interceptors-opentelemetry, worker-versioning, vscode-debugger, lambda-worker, nestjs-exchange-rates, nextjs-ecommerce-oneclick, food-delivery, ai-sdk, openai-agents, langsmith, strands-agents, workflow-streams — worker/build/deployment configuration or app integrations that compose with the shim rather than interact with it. sinks and interceptors-opentelemetry are worth a smoke test once the package is adopted in a real worker.

Coverage

Every sample with workflow-semantics content is supported (tested) or works unchanged; the remainder is infrastructure with no package involvement. Where a sample needed a primitive the upstream Effect API does not define, the package provides one: DurableMailbox (repeated signals, long-lived state), DurableUpdate (request/response with typed channels), StateCell (queryable state), continueAsNew (unbounded workflows), schedule and Nexus bridges, and patch-marker versioning.

New capabilities land with a test mirroring the corresponding sample, in this package's suite.