docs: break getWorld into per-entity World SDK pages#1456
Open
docs: break getWorld into per-entity World SDK pages#1456
Conversation
Split monolithic get-world.mdx into 8 pages under world/: - index.mdx (overview + cards) - runs.mdx, steps.mdx, hooks.mdx, events.mdx, streams.mdx, queue.mdx - observability.mdx (hydration, name parsing, encryption) Also: - Slim get-world.mdx to overview + links - Add World SDK card to workflow-api/index.mdx - Add workflow/observability path mapping to docs-typecheck - Add world/step/run ID globals to docs-globals.d.ts - Add observability + error handling sections to SKILL.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix 16 event types to match source (run_created, step_retrying, hook_received, hook_disposed, hook_conflict, wait_created) - Fix Streamer method signatures (name + runId params) - Use string literals in inline code snippets to avoid global name conflict Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
Contributor
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests🌍 Community Worlds (56 failed)mongodb (3 failed):
redis (2 failed):
turso (51 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
|
MDX doesn't support `<!-- -->`, must use `{/* */}` syntax. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Breaks the monolithic
get-world.mdxpage into 8 per-entity World SDK pages for better discoverability, greppability, and navigation.Linear: DSE-2334 (child of DSE-2322)
Depends on: PR #1453 (adds
workflow/observabilityexport — encryption examples use@expect-errorcomments until that merges)Before / After: End-to-End User Impact
If you install the workflow skill (skills.sh →
skills/workflow/SKILL.md)Before: The skill had zero mention of observability, the World SDK, or how to inspect workflow data. If you asked your agent "how do I list workflow runs?" or "how do I hydrate step data?", it had no grep hints pointing to the right docs and no example patterns to follow. Error handling was also undocumented — no guidance on
FatalErrorvsRetryableErrorvsPromise.allSettled.After: Two new sections in the skill:
grep -r "world.runs" node_modules/workflow/docs/), shows the key imports (getWorldfromworkflow/runtime,hydrateResourceIOfromworkflow/observability), and gives a quick hydration code snippet.FatalErrorvsRetryableErrorvsPromise.allSettled, with code examples.The doc structure listing now includes
api-reference/workflow-api/world/so the agent knows those files exist to grep into.If you visit useworkflow.dev
Before: There was ONE page for all World SDK content —
getWorld. It had the function signature, a TSDoc block, and a handful of examples crammed together. If you wanted to understandworld.eventsorworld.streams, you'd scroll through that single page. Examples were sparse, type information was missing, and method signatures weren't documented.After: That one page is now 9 pages:
getWorldis slimmed to just the function signature + links to entity pagesNew data that didn't exist before
The entity pages contain real API documentation that wasn't documented anywhere on the site:
world.events.listByCorrelationId({ correlationId, cursor })with typed paramsresolveData: 'none' | 'all'performance pattern documented for the first timeThis information was derived from the actual TypeScript types in
@workflow/world— it wasn't documented on the site before in any user-facing way.What Changed
New Pages (8 files in
docs/content/docs/api-reference/workflow-api/world/)index.mdxruns.mdxworld.runs— get/list/cancel methods, WorkflowRun type table, 5 examplessteps.mdxworld.steps— get/list methods, Step type table, hydration + duration exampleshooks.mdxworld.hooks— get/getByToken/list methods, Hook type table, webhook resume exampleevents.mdxworld.events— create/get/list/listByCorrelationId, 16 event types in 4 grouped tablesstreams.mdxworld.streams(Streamer interface) — writeToStream/readFromStream/closeStream/listStreamsByRunIdqueue.mdxworld.queue(Queue interface) — getDeploymentId/queue/createQueueHandlerobservability.mdxworkflow/observabilityimports — hydrateResourceIO, parseStepName, parseWorkflowName, encryptionModified Pages
get-world.mdxworkflow-api/index.mdxfoundations/streaming.mdxworld/streamsin Related DocumentationSkill Changes
skills/workflow/SKILL.mdworld/doc structure listing,workflow/observabilityimport, "Observability & Data Hydration" section with grep hints, "Error Handling Patterns" section (FatalError/RetryableError/Promise.allSettled)Typecheck Infrastructure
packages/docs-typecheck/src/type-checker.tsworkflow/observability,@workflow/core/serialization-format,@workflow/utilspackages/docs-typecheck/src/docs-globals.d.tsDesign Decisions
resolveData: 'none' | 'all'pattern highlighted in runs + steps for performance{/* @expect-error:2305,2724 */}until PR feat: re-export parseName + hydrators for observability DX #1453 merges theworkflow/observabilityexportScreenshots
World SDK Overview
world.runs
world.steps
world.hooks
world.events
world.streams
world.queue
Observability Utilities
getWorld (slimmed)
workflow/api index (new World SDK card)
Streaming cross-link (new world.streams link)
Test plan
@workflow/aifailures on main)pnpm devin docs/)@expect-errorcomments fromobservability.mdxafter PR feat: re-export parseName + hydrators for observability DX #1453 merges🤖 Generated with Claude Code