Skip to content

Conversation

@TooTallNate
Copy link
Member

@TooTallNate TooTallNate commented Jan 26, 2026

Added automatic discovery for custom classes with workflow serialization, allowing serialization classes to be defined in separate files without requiring explicit directives.

What changed?

  • Added detection for files containing custom class serialization patterns:
    • Files importing from @workflow/serde
    • Files using Symbol.for('workflow-serialize') or Symbol.for('workflow-deserialize')
  • Created shared utilities in transform-utils.ts for consistent pattern detection across all build tools
  • Updated Next.js, Nitro, Rollup, and Vite plugins to use the new detection patterns
  • Added exclusion logic to prevent re-processing of generated workflow files
  • Added tests to verify the pattern detection works correctly
  • Updated documentation in the SWC plugin spec to explain the new discovery mechanism

How to test?

  1. Create a class with custom serialization in a separate file:
// models/point.js
export class Point {
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }

  static [Symbol.for('workflow-serialize')](instance) {
    return { x: instance.x, y: instance.y };
  }

  static [Symbol.for('workflow-deserialize')](data) {
    return new Point(data.x, data.y);
  }
}
  1. Import and use this class in a workflow or step file:
'use workflow';
import { Point } from '../models/point';

export function myWorkflow() {
  const point = new Point(10, 20);
  return point;
}
  1. Verify the class is properly serialized when passed between client and server

Why make this change?

Previously, files containing custom serialization classes needed to include a 'use step' directive to be discovered and transformed, even if they weren't actual step functions. This was unintuitive and could lead to confusion.

This change allows for a more natural code organization pattern where model classes with serialization can be defined in their own files without requiring directives. The build system will automatically discover and transform these files to ensure the serialization works correctly when the classes are used in workflows or steps.

@changeset-bot
Copy link

changeset-bot bot commented Jan 26, 2026

🦋 Changeset detected

Latest commit: 14a46e1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 18 packages
Name Type
@workflow/swc-plugin Patch
@workflow/builders Patch
@workflow/rollup Patch
@workflow/next Patch
@workflow/astro Patch
@workflow/cli Patch
@workflow/nest Patch
@workflow/nitro Patch
@workflow/sveltekit Patch
@workflow/vite Patch
workflow Patch
@workflow/docs-typecheck Patch
@workflow/world-testing Patch
@workflow/example-nest Patch
@workflow/nuxt Patch
@workflow/ai Patch
@workflow/core Patch
@workflow/web-shared Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions
Copy link
Contributor

github-actions bot commented Jan 26, 2026

📊 Benchmark Results

📈 Comparing against baseline from main branch. Green 🟢 = faster, Red 🔺 = slower.

workflow with no steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 0.042s (-4.7%) 1.007s (~) 0.965s 10 1.00x
🐘 Postgres Express 0.315s (+9.2% 🔺) 1.013s (~) 0.698s 10 7.47x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 0.649s (-16.1% 🟢) 1.534s (-5.8% 🟢) 0.884s 10 1.00x

🔍 Observability: Express

workflow with 1 step

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 1.115s (~) 2.007s (~) 0.892s 10 1.00x
🐘 Postgres Express 2.171s (+2.4%) 3.014s (~) 0.843s 10 1.95x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 3.035s (+3.7%) 3.767s (+2.7%) 0.732s 10 1.00x

🔍 Observability: Express

workflow with 10 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 10.835s (~) 11.016s (~) 0.181s 5 1.00x
🐘 Postgres Express 20.411s (~) 21.033s (~) 0.622s 5 1.88x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 23.095s (-3.8%) 24.115s (-2.4%) 1.020s 5 1.00x

🔍 Observability: Express

Promise.all with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 5.179s (-5.3% 🟢) 5.432s (-15.7% 🟢) 0.253s 6 1.00x
🐘 Postgres Express 28.910s (+3.3%) 29.662s (+5.1% 🔺) 0.752s 2 5.58x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 3.296s (-8.0% 🟢) 3.764s (-5.3% 🟢) 0.468s 8 1.00x

🔍 Observability: Express

Promise.all with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 5.155s (-2.9%) 6.012s (-4.3%) 0.857s 6 1.00x
🐘 Postgres Express 31.548s (-6.2% 🟢) 32.098s (-5.9% 🟢) 0.550s 1 6.12x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 3.223s (-3.4%) 3.802s (-4.9%) 0.579s 8 1.00x

🔍 Observability: Express

Promise.race with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 5.284s (-6.8% 🟢) 6.266s (-4.9%) 0.981s 5 1.00x
🐘 Postgres Express 34.150s (-1.4%) 35.096s (~) 0.946s 1 6.46x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 3.122s (-5.7% 🟢) 3.682s (-7.4% 🟢) 0.560s 9 1.00x

🔍 Observability: Express

Promise.race with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 5.305s (-5.8% 🟢) 6.306s (-4.1%) 1.002s 5 1.00x
🐘 Postgres Express 34.477s (+13.8% 🔺) 35.152s (+12.1% 🔺) 0.675s 1 6.50x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 3.443s (+4.4%) 4.067s (+4.5%) 0.624s 8 1.00x

🔍 Observability: Express

Stream Benchmarks (includes TTFB metrics)
workflow with stream

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 0.183s (-3.4%) 0.993s (~) 0.014s (-4.7%) 1.021s (~) 0.838s 10 1.00x
🐘 Postgres Express 2.341s (+6.4% 🔺) 2.702s (-5.0%) 0.000s (~) 3.014s (~) 0.673s 10 12.80x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 2.976s (-14.3% 🟢) 3.206s (-8.9% 🟢) 1.096s (-6.6% 🟢) 4.826s (-10.7% 🟢) 1.850s 10 1.00x

🔍 Observability: Express

Summary

Fastest Framework by World

Winner determined by most benchmark wins

World 🥇 Fastest Framework Wins
💻 Local Express 8/8
🐘 Postgres Express 8/8
▲ Vercel Express 8/8
Fastest World by Framework

Winner determined by most benchmark wins

Framework 🥇 Fastest World Wins
Express 💻 Local 4/8
Column Definitions
  • Workflow Time: Runtime reported by workflow (completedAt - createdAt) - primary metric
  • TTFB: Time to First Byte - time from workflow start until first stream byte received (stream benchmarks only)
  • Slurp: Time from first byte to complete stream consumption (stream benchmarks only)
  • Wall Time: Total testbench time (trigger workflow + poll for result)
  • Overhead: Testbench overhead (Wall Time - Workflow Time)
  • Samples: Number of benchmark iterations run
  • vs Fastest: How much slower compared to the fastest configuration for this benchmark

Worlds:

  • 💻 Local: In-memory filesystem world (local development)
  • 🐘 Postgres: PostgreSQL database world (local development)
  • ▲ Vercel: Vercel production/preview deployment
  • 🌐 Starter: Community world (local development)
  • 🌐 Turso: Community world (local development)
  • 🌐 MongoDB: Community world (local development)
  • 🌐 Redis: Community world (local development)
  • 🌐 Jazz: Community world (local development)

📋 View full workflow run

@github-actions
Copy link
Contributor

github-actions bot commented Jan 26, 2026

🧪 E2E Test Results

Some tests failed

Summary

Passed Failed Skipped Total
✅ ▲ Vercel Production 457 0 38 495
✅ 💻 Local Development 418 0 32 450
✅ 📦 Local Production 418 0 32 450
✅ 🐘 Local Postgres 418 0 32 450
✅ 🪟 Windows 45 0 0 45
❌ 🌍 Community Worlds 31 161 0 192
✅ 📋 Other 123 0 12 135
Total 1910 161 146 2217

❌ Failed Tests

🌍 Community Worlds (161 failed)

mongodb (40 failed):

  • addTenWorkflow
  • addTenWorkflow
  • should work with react rendering in step
  • promiseAllWorkflow
  • promiseRaceWorkflow
  • promiseAnyWorkflow
  • readableStreamWorkflow
  • hookWorkflow
  • webhookWorkflow
  • sleepingWorkflow
  • nullByteWorkflow
  • workflowAndStepMetadataWorkflow
  • outputStreamWorkflow
  • outputStreamInsideStepWorkflow - getWritable() called inside step functions
  • fetchWorkflow
  • promiseRaceStressTestWorkflow
  • error handling error propagation workflow errors nested function calls preserve message and stack trace
  • error handling error propagation workflow errors cross-file imports preserve message and stack trace
  • error handling error propagation step errors basic step error preserves message and stack trace
  • error handling error propagation step errors cross-file step error preserves message and function names in stack
  • error handling retry behavior regular Error retries until success
  • error handling retry behavior FatalError fails immediately without retries
  • error handling retry behavior RetryableError respects custom retryAfter delay
  • error handling retry behavior maxRetries=0 disables retries
  • error handling catchability FatalError can be caught and detected with FatalError.is()
  • hookCleanupTestWorkflow - hook token reuse after workflow completion
  • concurrent hook token conflict - two workflows cannot use the same hook token simultaneously
  • stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
  • stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
  • closureVariableWorkflow - nested step functions with closure variables
  • spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
  • pathsAliasWorkflow - TypeScript path aliases resolve correctly
  • Calculator.calculate - static workflow method using static step methods from another class
  • AllInOneService.processNumber - static workflow method using sibling static step methods
  • ChainableService.processWithThis - static step methods using this to reference the class
  • thisSerializationWorkflow - step function invoked with .call() and .apply()
  • customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE
  • pages router addTenWorkflow via pages router
  • pages router promiseAllWorkflow via pages router
  • pages router sleepingWorkflow via pages router

redis (40 failed):

  • addTenWorkflow
  • addTenWorkflow
  • should work with react rendering in step
  • promiseAllWorkflow
  • promiseRaceWorkflow
  • promiseAnyWorkflow
  • readableStreamWorkflow
  • hookWorkflow
  • webhookWorkflow
  • sleepingWorkflow
  • nullByteWorkflow
  • workflowAndStepMetadataWorkflow
  • outputStreamWorkflow
  • outputStreamInsideStepWorkflow - getWritable() called inside step functions
  • fetchWorkflow
  • promiseRaceStressTestWorkflow
  • error handling error propagation workflow errors nested function calls preserve message and stack trace
  • error handling error propagation workflow errors cross-file imports preserve message and stack trace
  • error handling error propagation step errors basic step error preserves message and stack trace
  • error handling error propagation step errors cross-file step error preserves message and function names in stack
  • error handling retry behavior regular Error retries until success
  • error handling retry behavior FatalError fails immediately without retries
  • error handling retry behavior RetryableError respects custom retryAfter delay
  • error handling retry behavior maxRetries=0 disables retries
  • error handling catchability FatalError can be caught and detected with FatalError.is()
  • hookCleanupTestWorkflow - hook token reuse after workflow completion
  • concurrent hook token conflict - two workflows cannot use the same hook token simultaneously
  • stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
  • stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
  • closureVariableWorkflow - nested step functions with closure variables
  • spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
  • pathsAliasWorkflow - TypeScript path aliases resolve correctly
  • Calculator.calculate - static workflow method using static step methods from another class
  • AllInOneService.processNumber - static workflow method using sibling static step methods
  • ChainableService.processWithThis - static step methods using this to reference the class
  • thisSerializationWorkflow - step function invoked with .call() and .apply()
  • customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE
  • pages router addTenWorkflow via pages router
  • pages router promiseAllWorkflow via pages router
  • pages router sleepingWorkflow via pages router

starter (41 failed):

  • addTenWorkflow
  • addTenWorkflow
  • should work with react rendering in step
  • promiseAllWorkflow
  • promiseRaceWorkflow
  • promiseAnyWorkflow
  • readableStreamWorkflow
  • hookWorkflow
  • webhookWorkflow
  • sleepingWorkflow
  • nullByteWorkflow
  • workflowAndStepMetadataWorkflow
  • outputStreamWorkflow
  • outputStreamInsideStepWorkflow - getWritable() called inside step functions
  • fetchWorkflow
  • promiseRaceStressTestWorkflow
  • error handling error propagation workflow errors nested function calls preserve message and stack trace
  • error handling error propagation workflow errors cross-file imports preserve message and stack trace
  • error handling error propagation step errors basic step error preserves message and stack trace
  • error handling error propagation step errors cross-file step error preserves message and function names in stack
  • error handling retry behavior regular Error retries until success
  • error handling retry behavior FatalError fails immediately without retries
  • error handling retry behavior RetryableError respects custom retryAfter delay
  • error handling retry behavior maxRetries=0 disables retries
  • error handling catchability FatalError can be caught and detected with FatalError.is()
  • hookCleanupTestWorkflow - hook token reuse after workflow completion
  • concurrent hook token conflict - two workflows cannot use the same hook token simultaneously
  • stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
  • stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
  • closureVariableWorkflow - nested step functions with closure variables
  • spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
  • health check (CLI) - workflow health command reports healthy endpoints
  • pathsAliasWorkflow - TypeScript path aliases resolve correctly
  • Calculator.calculate - static workflow method using static step methods from another class
  • AllInOneService.processNumber - static workflow method using sibling static step methods
  • ChainableService.processWithThis - static step methods using this to reference the class
  • thisSerializationWorkflow - step function invoked with .call() and .apply()
  • customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE
  • pages router addTenWorkflow via pages router
  • pages router promiseAllWorkflow via pages router
  • pages router sleepingWorkflow via pages router

turso (40 failed):

  • addTenWorkflow
  • addTenWorkflow
  • should work with react rendering in step
  • promiseAllWorkflow
  • promiseRaceWorkflow
  • promiseAnyWorkflow
  • readableStreamWorkflow
  • hookWorkflow
  • webhookWorkflow
  • sleepingWorkflow
  • nullByteWorkflow
  • workflowAndStepMetadataWorkflow
  • outputStreamWorkflow
  • outputStreamInsideStepWorkflow - getWritable() called inside step functions
  • fetchWorkflow
  • promiseRaceStressTestWorkflow
  • error handling error propagation workflow errors nested function calls preserve message and stack trace
  • error handling error propagation workflow errors cross-file imports preserve message and stack trace
  • error handling error propagation step errors basic step error preserves message and stack trace
  • error handling error propagation step errors cross-file step error preserves message and function names in stack
  • error handling retry behavior regular Error retries until success
  • error handling retry behavior FatalError fails immediately without retries
  • error handling retry behavior RetryableError respects custom retryAfter delay
  • error handling retry behavior maxRetries=0 disables retries
  • error handling catchability FatalError can be caught and detected with FatalError.is()
  • hookCleanupTestWorkflow - hook token reuse after workflow completion
  • concurrent hook token conflict - two workflows cannot use the same hook token simultaneously
  • stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
  • stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
  • closureVariableWorkflow - nested step functions with closure variables
  • spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
  • pathsAliasWorkflow - TypeScript path aliases resolve correctly
  • Calculator.calculate - static workflow method using static step methods from another class
  • AllInOneService.processNumber - static workflow method using sibling static step methods
  • ChainableService.processWithThis - static step methods using this to reference the class
  • thisSerializationWorkflow - step function invoked with .call() and .apply()
  • customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE
  • pages router addTenWorkflow via pages router
  • pages router promiseAllWorkflow via pages router
  • pages router sleepingWorkflow via pages router

Details by Category

✅ ▲ Vercel Production
App Passed Failed Skipped
✅ astro 41 0 4
✅ example 41 0 4
✅ express 41 0 4
✅ fastify 41 0 4
✅ hono 41 0 4
✅ nextjs-turbopack 44 0 1
✅ nextjs-webpack 44 0 1
✅ nitro 41 0 4
✅ nuxt 41 0 4
✅ sveltekit 41 0 4
✅ vite 41 0 4
✅ 💻 Local Development
App Passed Failed Skipped
✅ astro-stable 41 0 4
✅ express-stable 41 0 4
✅ fastify-stable 41 0 4
✅ hono-stable 41 0 4
✅ nextjs-turbopack-stable 45 0 0
✅ nextjs-webpack-stable 45 0 0
✅ nitro-stable 41 0 4
✅ nuxt-stable 41 0 4
✅ sveltekit-stable 41 0 4
✅ vite-stable 41 0 4
✅ 📦 Local Production
App Passed Failed Skipped
✅ astro-stable 41 0 4
✅ express-stable 41 0 4
✅ fastify-stable 41 0 4
✅ hono-stable 41 0 4
✅ nextjs-turbopack-stable 45 0 0
✅ nextjs-webpack-stable 45 0 0
✅ nitro-stable 41 0 4
✅ nuxt-stable 41 0 4
✅ sveltekit-stable 41 0 4
✅ vite-stable 41 0 4
✅ 🐘 Local Postgres
App Passed Failed Skipped
✅ astro-stable 41 0 4
✅ express-stable 41 0 4
✅ fastify-stable 41 0 4
✅ hono-stable 41 0 4
✅ nextjs-turbopack-stable 45 0 0
✅ nextjs-webpack-stable 45 0 0
✅ nitro-stable 41 0 4
✅ nuxt-stable 41 0 4
✅ sveltekit-stable 41 0 4
✅ vite-stable 41 0 4
✅ 🪟 Windows
App Passed Failed Skipped
✅ nextjs-turbopack 45 0 0
❌ 🌍 Community Worlds
App Passed Failed Skipped
✅ mongodb-dev 3 0 0
❌ mongodb 5 40 0
✅ redis-dev 3 0 0
❌ redis 5 40 0
✅ starter-dev 3 0 0
❌ starter 4 41 0
✅ turso-dev 3 0 0
❌ turso 5 40 0
✅ 📋 Other
App Passed Failed Skipped
✅ e2e-local-dev-nest-stable 41 0 4
✅ e2e-local-postgres-nest-stable 41 0 4
✅ e2e-local-prod-nest-stable 41 0 4

📋 View full workflow run

@vercel
Copy link
Contributor

vercel bot commented Jan 26, 2026

Create shared transform-utils.ts in @workflow/builders with:
- Pattern detection (directives, serde imports, Symbol.for)
- Path exclusion checks (generated files, SDK files)
- Combined shouldTransformFile logic

Update rollup, next, and vite packages to use shared utilities
instead of duplicated regex patterns.
@TooTallNate TooTallNate force-pushed the 01-26-add_discovery_for_custom_classes_with_workflow_serialization branch from 42cb29f to 14a46e1 Compare January 30, 2026 20:33
Copy link
Member

@VaguelySerious VaguelySerious left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM but would love @ijjk 's input

Copy link
Member Author

TooTallNate commented Feb 3, 2026

Merge activity

  • Feb 3, 7:18 AM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Feb 3, 7:19 AM UTC: @TooTallNate merged this pull request with Graphite.

@TooTallNate TooTallNate merged commit 8114792 into main Feb 3, 2026
100 checks passed
@TooTallNate TooTallNate deleted the 01-26-add_discovery_for_custom_classes_with_workflow_serialization branch February 3, 2026 07:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants