Skip to content

Commit 472918f

Browse files
Document JavaScript top-level await support
Add documentation for new top-level await feature in JavaScript contexts: - No IIFE wrapper needed for async code - Last expression automatically returned as result - Seamless support for multiple await expressions Updated: - API reference (interpreter.mdx) with top-level await example - How-to guide (code-execution.mdx) with comprehensive examples Related to cloudflare/sandbox-sdk#261 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 00c38c0 commit 472918f

File tree

2 files changed

+53
-0
lines changed

2 files changed

+53
-0
lines changed

src/content/docs/sandbox/api/interpreter.mdx

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ import { TypeScriptExample } from "~/components";
99

1010
Execute Python, JavaScript, and TypeScript code with support for data visualizations, tables, and rich output formats. Contexts maintain state (variables, imports, functions) across executions.
1111

12+
JavaScript contexts support top-level `await` - no need to wrap async code in IIFE. The last expression is automatically returned as the result.
13+
1214
## Methods
1315

1416
### `createCodeContext()`
@@ -91,6 +93,23 @@ console.log(result.results[0].text); // "78.53981633974483"
9193
```
9294
</TypeScriptExample>
9395

96+
**JavaScript with top-level await**:
97+
98+
<TypeScriptExample>
99+
```
100+
const ctx = await sandbox.createCodeContext({ language: 'javascript' });
101+
102+
// Top-level await - no IIFE needed!
103+
const result = await sandbox.runCode(`
104+
const response = await fetch('https://api.example.com/data');
105+
const data = await response.json();
106+
data.result
107+
`, { context: ctx });
108+
109+
console.log(result.results[0]); // Last expression is automatically returned
110+
```
111+
</TypeScriptExample>
112+
94113
:::note[Default context behavior]
95114
If no `context` is provided, a default context is automatically created/reused for the specified `language`. While convenient for quick tests, **explicitly creating contexts is recommended** for production use to maintain predictable state.
96115

src/content/docs/sandbox/guides/code-execution.mdx

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,10 @@ const jsContext = await sandbox.createCodeContext({
5151
```
5252
</TypeScriptExample>
5353

54+
:::note[JavaScript top-level await]
55+
JavaScript contexts automatically support top-level `await` without wrapping code in async IIFE. The last expression value is returned as the result.
56+
:::
57+
5458
## Execute code
5559

5660
### Simple execution
@@ -133,6 +137,36 @@ console.log(result.output); // "Mean: 3.0"
133137
Context state is lost if the container restarts due to inactivity. For critical data, store results outside the sandbox or design your code to reinitialize as needed.
134138
:::
135139

140+
### Top-level await (JavaScript)
141+
142+
JavaScript contexts support top-level `await` without IIFE wrappers. The last expression is automatically returned:
143+
144+
<TypeScriptExample>
145+
```
146+
const jsContext = await sandbox.createCodeContext({
147+
language: 'javascript'
148+
});
149+
150+
// No IIFE needed - await works at top level
151+
const result = await sandbox.runCode(`
152+
const data = await Promise.resolve([1, 2, 3, 4, 5]);
153+
const sum = data.reduce((a, b) => a + b, 0);
154+
sum
155+
`, { context: jsContext.id });
156+
157+
console.log(result.results[0].text); // "15"
158+
159+
// Multiple awaits work seamlessly
160+
const result2 = await sandbox.runCode(`
161+
const a = await Promise.resolve(10);
162+
const b = await Promise.resolve(20);
163+
a + b
164+
`, { context: jsContext.id });
165+
166+
console.log(result2.results[0].text); // "30"
167+
```
168+
</TypeScriptExample>
169+
136170
## Handle rich outputs
137171

138172
The code interpreter returns multiple output formats:

0 commit comments

Comments
 (0)