mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
## Summary
- add the new `@mastra/temporal` package with Temporal worker/plugin
integration and package build tooling
- transform Mastra workflow sources into Temporal workflow/activity
modules, including deterministic workflow exports and webpack entry
rewriting
- add fixture-based transform tests, runtime tests, integration
coverage, docs, and changesets for the adapter
## Test plan
- pnpm --filter ./workflows/temporal exec eslint .
- pnpm --filter ./workflows/temporal exec vitest run
- pnpm --filter ./workflows/temporal exec tsc --noEmit
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds a new package that lets Mastra workflows run on Temporal by
transforming Mastra workflow code into Temporal-compatible workflow and
activity modules, bundling them, and wiring a plugin to start Temporal
workers—so you can keep writing Mastra workflows and run them on
Temporal without manual rewrites.
## Summary
Adds @mastra/temporal: an adapter package providing build-time AST
transforms, runtime helpers, and a Worker plugin to run Mastra workflows
on Temporal. It converts Mastra workflows/steps into deterministic
Temporal workflow modules and activity modules, produces runtime wiring
(TemporalExecutionEngine, TemporalRun, TemporalWorkflow), and supplies
MastraPlugin to prebuild bundles and configure Temporal Workers. The
change includes build tooling, tests (unit, transform, runtime,
integration), docs, fixtures, and packaging.
### Core API
- init(temporalParams): returns bound createWorkflow/createStep
factories (client + taskQueue).
- createWorkflow / createStep: factories returned by init().
- TemporalWorkflow: Workflow subclass that creates Temporal-backed runs.
- TemporalRun: Run implementation integrated with Temporal client;
supports start() and startAsync().
- Utility: toWorkflowType(id: string) and TemporalEngineType type alias.
### Plugin & Worker Integration
- MastraPlugin implements WorkerPlugin:
- prebuild: bundles Mastra entry (via BuildBundler/mastra-deployer),
runs transforms, emits workflow.mjs, activities.mjs, and
activity-bindings.json into node_modules/.mastra, and caches output
path.
- getTemporalWorkerOptions / configureWorker: return/merge
WorkerOptions.workflowsPath and activities map (handlers keyed by step
id) which lazy-import compiled activities and forward calls.
- Debug support: emits transformed modules/bundles into .mastra/temporal
for inspection.
- worker.ts re-exports MastraPlugin.
### Transforms & Runtime
- Workflows transform (buildTemporalWorkflowModule):
- Rewrites createWorkflow(...).*.commit() chains into deterministic
exported workflow functions backed by the injected Temporal runtime.
- Requires static workflow id strings; emits workflow registry metadata;
strips Mastra/Temporal helper imports; prunes unused top-level bindings.
- Returns transformed code and workflow export metadata.
- Activities transform (buildTemporalActivitiesModule,
collectTemporalActivityBindings):
- Collects activity bindings (exportName ↔ stepId) from hoisted and
inline createStep calls.
- Produces activity modules exporting step handlers and injects a local
createStep helper that forwards to args.execute with a local mastra
binding.
- Preserves required declarations (schemas/helpers) while removing
workflow bootstrap artifacts.
- Shared utilities (shared.ts):
- Babel/AST helpers: parsing, identifier/reference collection,
getStepId/name, generate exported step statements, collect inline steps,
and prune unused top-level bindings.
- Runtime:
- TemporalExecutionEngine (mjs + d.ts): executes serialized workflow
graphs (step/activity calls, child workflows, sleep/sleepUntil,
parallel, conditional, loop/dowhile/dountil, foreach with concurrency)
and returns per-step outputs.
- createWorkflow runtime factory used by transformed modules.
### Build, Tooling & Packaging
- New package manifest (workflows/temporal/package.json) with
conditional ESM/CJS exports (., ./worker), Node >=22.13 engine.
- tsup config builds index and worker (EM/CJS), copies
temporal-workflow-runtime.mjs into dist.
- tsconfig/tsconfig.build, tsup.config.ts, vitest.config.ts,
eslint.flat-config and lint-staged, Docker Compose for local Temporal
dev.
- mastra-deployer BuildBundler: bundler subclass forcing externals &
sourcemap for Temporal builds.
### Tests, Fixtures & Docs
- Extensive tests:
- Fixture-based transform tests (workflows/activities) asserting
byte-for-byte or exact output shapes.
- Runtime tests for TemporalExecutionEngine behavior.
- Integration tests for MastraPlugin.prebuild/configureWorker that
validate emitted bundles, activity-bindings.json, dynamic import
behavior, and runtime invocation using generated modules.
- index.test.ts covers transform behaviors and
MastraPlugin.configureWorker wiring.
- Fixtures: before/after inputs and outputs for workflows and
activities; integration fixtures for complex workflows and steps.
- README + CHANGELOG, usage examples showing init({ client, taskQueue
}), createStep/createWorkflow, and MastraPlugin wiring; notes about
static workflow ids and entry-file constraints.
- Changeset added for initial minor bump.
### Notable implementation details & review points
- Activity handlers lazy-import compiled activities with a cache-busting
query and map step id → handler function which validates exported member
is a function.
- MastraPlugin writes activity-bindings.json under node_modules/.mastra
to map step ids to exports.
- Workflows transform enforces static workflow id forms and injects
deterministic names for exported workflows/steps.
- High-review-signal areas: correctness of AST transforms
(shared/workflows/activities), liveness/pruning logic, MastraPlugin
prebuild/caching/runtime wiring, TemporalRun/TemporalWorkflow semantics,
and packaging/exports (ESM/CJS conditional mappings).
- Large test suites are included to assert transform fidelity; reviewers
should run the package tests and integration prebuild tests.
### Files added/changed (high-level)
- New package dir: workflows/temporal/ with package.json,
tsup.config.ts, tsconfig(s), vitest.config.ts, eslint/lint-staged,
README.md, CHANGELOG.md, docker-compose.yaml.
- Source: src/{index.ts, workflow.ts, run.ts, plugin.ts, worker.ts,
mastra-deployer.ts, types.ts, utils.ts}
- Transforms: src/transforms/{workflows.ts, activities.ts, shared.ts,
temporal-workflow-runtime.mjs/.d.ts, plus fixtures and transform
outputs}
- Tests & fixtures: many files under src/__tests__/ and __fixtures__;
e2e-tests adjustment to skip temporal package export test.
- Changeset: .changeset/cool-windows-search.md
## Impact & Notes for Review
- This introduces a substantial new package combining compile-time AST
transforms and runtime integration with Temporal; expect deeper review
of transform algorithms (AST detection/pruning/renaming), MastraPlugin
lifecycle/caching, and runtime semantics for starting & awaiting
Temporal workflows. Validate packaging exports (ESM/CJS), node engine
constraint, and that the test fixtures cover edge cases of inline vs
hoisted createStep usage.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (openai/gpt-5.4) <noreply@mastra.ai>
12 lines
268 B
12 lines
268 B