@workflow/core 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/how-it-works/understanding-directives.mdx

@@ -21,7 +21,7 @@ This page explores how directives enable this execution model and the design pri
 
 To understand how directives work, let's first understand what workflows and steps are in the Workflow SDK.
 
-## Workflows and Steps Primer
+## Workflows and steps primer
 
 The Workflow SDK has two types of functions:
 
@@ -58,7 +58,7 @@ export async function onboardUser(userId: string) {
 **The key insight:** Workflows resume from suspension by replaying their code using cached step results from the [event log](/docs/how-it-works/event-sourcing). When a step like `await fetchUserData(userId)` is called:
 
 - **If already executed:** Returns the cached result immediately from the event log
-- **If not yet executed:** Suspends the workflow, enqueues the step for background execution, and resumes later with the result
+- **If not yet executed:** Suspends the workflow, executes the step (usually inline in the same invocation, or through the queue when the invocation runs out of inline budget or nears its timeout), then resumes with the result
 
 This replay mechanism requires deterministic code. If `Math.random()` weren't seeded, the first execution might return `0.7` (sending the email) but replay might return `0.3` (skipping it), thus breaking resumption. The Workflow SDK sandbox provides seeded `Math.random()` and `Date` to ensure consistent behavior across replays.
 
@@ -66,9 +66,9 @@ This replay mechanism requires deterministic code. If `Math.random()` weren't se
 For a deeper dive into workflows and steps, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 </Callout>
 
-## The Core Challenge
+## The core challenge
 
-This execution model enables powerful durability features - workflows can suspend for days, survive restarts, and resume from any point. However, it also requires a semantic boundary in the code that tells **the compiler, runtime, and developer** that execution semantics have changed.
+This execution model provides durability: workflows can suspend for days, survive restarts, and resume from any point. However, it also requires a semantic boundary in the code that tells **the compiler, runtime, and developer** that execution semantics have changed.
 
 The challenge: how do we mark this boundary in a way that:
 
@@ -77,7 +77,7 @@ The challenge: how do we mark this boundary in a way that:
 3. Allows static analysis of workflow structure
 4. Feels natural to JavaScript developers
 
-Let's look at where directives have been used before, and the alternatives we considered:
+Directives have prior uses, and we considered several alternatives:
 
 ## Prior art on directives
 
@@ -104,11 +104,11 @@ The `"use workflow"` directive is also used by the Language Server Plugin shippe
 
 But we didn't get here immediately. This took some discovery to arrive at:
 
-## Alternatives We Explored
+## Alternatives we explored
 
-Before settling on directives, we prototyped several other approaches. Each had significant limitations that made them unsuitable for production use.
+Before settling on directives, we prototyped several other approaches. Each had limitations that made them unsuitable for production use.
 
-### Runtime-Only "Suspense" API
+### Runtime-only "Suspense" API
 
 Our first proof of concept used a wrapper-based API without a build step:
 
@@ -140,7 +140,7 @@ export const myWorkflow = workflow(async () => {
 });
 ```
 
-This was verbose and easy to forget. Moreover, if a developer forgot to wrap something innocent like using `Date.now()`, it led to unstable runtime behavior.
+This was verbose and developers could forget it. If a developer forgot to wrap something like `Date.now()`, it led to unstable runtime behavior.
 
 For example:
 
@@ -200,7 +200,7 @@ export const myWorkflow = workflow(async () => {
 });
 ```
 
-### Generator-Based API
+### Generator-based API
 
 We explored using generators for explicit suspension points, inspired by libraries like Effect.ts:
 
@@ -220,7 +220,7 @@ We're big fans of [Effect.ts](https://effect.website/) and the power of generato
 
 **1. Syntax felt more like a DSL than JavaScript**
 
-Generators require a custom mental model that differs significantly from familiar async/await patterns. The `yield*` syntax and generator delegation were unfamiliar to many developers:
+Generators require a custom mental model that differs from familiar async/await patterns. The `yield*` syntax and generator delegation were unfamiliar to many developers:
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -267,7 +267,7 @@ export const myWorkflow = workflow(function*() {
 
 The generator syntax addressed suspension but didn't solve the fundamental sandboxing problem.
 
-### File System-Based Conventions
+### File system-based conventions
 
 We explored using file system conventions to identify workflows and steps, similar to how modern frameworks handle routing (Next.js, Hono, Nitro, SvelteKit):
 
@@ -282,7 +282,7 @@ We explored using file system conventions to identify workflows and steps, simil
   </Folder>
 </Files>
 
-With this approach, any function in the `workflows/` directory would be transformed as a workflow, and any function in `steps/` would be a step. No directives needed, just file locations.
+With this approach, any function in the `workflows/` directory would be transformed as a workflow, and any function in `steps/` would be a step. File locations would replace directives.
 
 **Why this could work:**
 
@@ -308,9 +308,9 @@ The directive approach solved all these issues: it works in any project structur
 
 ### Decorators
 
-We considered decorators, but they presented significant challenges both technical and ergonomic.
+We considered decorators, but they presented technical and ergonomic challenges.
 
-**Decorators are non-yet-standard and class-focused**
+**Decorators are not-yet-standard and class-focused**
 
 Decorators are not yet a standard syntax ([TC39 proposal](https://github.com/tc39/proposal-decorators)) and they currently only work with classes. A class decorator approach could look like this:
 
@@ -349,7 +349,7 @@ While decorators can be handled at compile-time with build tool support, they pr
 See the [Macro Wrapper](#macro-wrapper-approach) section below for a deeper dive into why this approach breaks down with concrete examples.
 </Callout>
 
-### Macro Wrapper Approach
+### Macro wrapper approach
 
 We also explored compile-time macro approaches - using a compiler to transform wrapper functions or decorators into directive-based code:
 
@@ -385,7 +385,7 @@ export const processOrder = async (orderId: string) => {
 };
 ```
 
-The benefit is that macros could enforce types and provide "Go To Definition" or other LSP features out of the box.
+The benefit is that macros could enforce types and provide "Go To Definition" or other LSP features without additional configuration.
 
 However, **the core problem remains: Workflows aren't runtime values**
 
@@ -431,7 +431,7 @@ To detect that `processOrder` is actually a workflow, the compiler would need wh
 
 This level of cross-function analysis is impractical for build tools - it would require analyzing every function call chain in your entire codebase and all dependencies. The compiler can only reliably detect direct `useWorkflow` calls, not calls hidden behind abstractions.
 
-## How Directives Solve These Problems
+## How directives solve these problems
 
 Directives address all the issues we encountered with previous approaches:
 
@@ -527,7 +527,7 @@ export async function processOrder(orderId: string) {
 
 The `"use step"` directive maintains consistency. While steps run in the full Node.js runtime and *could* work without a directive, they need some way to signal to the workflow runtime that they're steps.
 
-We could have used a function wrapper just for steps:
+We could have used a function wrapper for steps:
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -584,7 +584,7 @@ By requiring explicit `"use step"` directives, developers have fine-grained cont
 To understand how directives are transformed at compile time, see [How the Code Transform Works](/docs/how-it-works/code-transform).
 </Callout>
 
-## What Directives Enable
+## What directives enable
 
 Because `"use workflow"` defines a compile-time semantic boundary, we can provide:
 
@@ -603,7 +603,7 @@ Because `"use workflow"` defines a compile-time semantic boundary, we can provid
   </Card>
 </Cards>
 
-## Directives as a JavaScript Pattern
+## Directives as a JavaScript pattern
 
 Directives in JavaScript have always been contracts between the developer and the execution environment. `"use strict"` made this pattern familiar - it's a string literal that changes how code is interpreted.
 
@@ -611,7 +611,7 @@ While JavaScript doesn't yet have first-class support for custom directives (lik
 
 As TC39 members, we at Vercel are actively working with the standards body and broader ecosystem to explore formal specifications for pragma-like syntax or macro annotations that can express execution semantics.
 
-## Closing Thoughts
+## Closing thoughts
 
 Directives aren't about syntax preference, they're about expressing semantic boundaries. `"use workflow"` tells the compiler, developer, and runtime that this code is deterministic, resumable, and sandboxed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow/core",
-  "version": "5.0.0-beta.5",
+  "version": "5.0.0-beta.50",
   "description": "Core runtime and engine for Workflow SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -44,6 +44,10 @@
       "types": "./dist/runtime/helpers.d.ts",
       "default": "./dist/runtime/helpers.js"
     },
+    "./logger": {
+      "types": "./dist/logger.d.ts",
+      "default": "./dist/logger.js"
+    },
     "./runtime/resume-hook": {
       "types": "./dist/runtime/resume-hook.d.ts",
       "default": "./dist/runtime/resume-hook.js"
@@ -76,35 +80,40 @@
     "./_workflow": "./dist/workflow/index.js"
   },
   "dependencies": {
-    "@aws-sdk/credential-provider-web-identity": "3.972.13",
+    "@aws-sdk/credential-provider-web-identity": "3.972.49",
     "@jridgewell/trace-mapping": "0.3.31",
     "@standard-schema/spec": "1.0.0",
     "@types/ms": "2.1.0",
-    "@vercel/functions": "^3.4.3",
+    "@vercel/functions": "^3.8.0",
+    "@workflow/errors": "5.0.0-beta.21",
+    "@workflow/serde": "5.0.0-beta.2",
+    "@workflow/utils": "5.0.0-beta.10",
+    "@workflow/world": "5.0.0-beta.34",
+    "@workflow/world-local": "5.0.0-beta.43",
+    "@workflow/world-vercel": "5.0.0-beta.45",
     "debug": "4.4.3",
-    "devalue": "5.6.3",
+    "devalue": "5.9.0",
     "ms": "2.1.3",
     "nanoid": "5.1.6",
+    "quickjs-wasi": "3.4.0",
     "seedrandom": "3.0.5",
     "semver": "7.7.4",
     "ulid": "~3.0.1",
-    "zod": "4.3.6",
-    "@workflow/errors": "5.0.0-beta.2",
-    "@workflow/serde": "5.0.0-beta.1",
-    "@workflow/utils": "5.0.0-beta.2",
-    "@workflow/world": "5.0.0-beta.2",
-    "@workflow/world-local": "5.0.0-beta.4",
-    "@workflow/world-vercel": "5.0.0-beta.4"
+    "zod": "~4.3.6"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",
+    "@opentelemetry/context-async-hooks": "1.30.1",
+    "@opentelemetry/core": "1.30.1",
+    "@opentelemetry/sdk-trace-base": "1.30.1",
     "@types/debug": "4.1.12",
-    "@types/semver": "7.7.1",
     "@types/node": "22.19.0",
     "@types/seedrandom": "3.0.8",
+    "@types/semver": "7.7.1",
+    "@workflow/tsconfig": "5.0.0-beta.0",
     "cross-env": "10.1.0",
     "genversion": "3.2.0",
-    "@workflow/tsconfig": "5.0.0-beta.0"
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": "1"
@@ -115,10 +124,10 @@
     }
   },
   "scripts": {
-    "build": "genversion --es6 src/version.ts && tsc",
+    "build": "genversion --es6 src/version.ts && node scripts/build-quickjs-assets.js && tsc",
     "dev": "genversion --es6 src/version.ts && tsc --watch",
     "clean": "tsc --build --clean && rm -rf dist src/version.ts docs ||:",
-    "test": "cross-env WORKFLOW_TARGET_WORLD=local vitest run src",
+    "test": "cross-env WORKFLOW_TARGET_WORLD=local vitest run src e2e/utils.test.ts",
     "test:e2e": "vitest run e2e",
     "typecheck": "genversion --es6 src/version.ts && tsc --noEmit"
   }

package/dist/runtime/step-handler.d.ts

@@ -1,2 +0,0 @@
-export declare const stepEntrypoint: (req: Request) => Promise<Response>;
-//# sourceMappingURL=step-handler.d.ts.map

package/dist/runtime/step-handler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"step-handler.d.ts","sourceRoot":"","sources":["../../src/runtime/step-handler.ts"],"names":[],"mappings":"AAygCA,eAAO,MAAM,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAM3D,CAAC"}