Add defer functionality to generator executor

[Wesley Wigham (weswigham)]

Add a defer function and support to the api.batch executor for it, allowing you to queue work to run within the current batching context without blocking execution of the current active generator - essentially the generator equivalent of an unawaited async function call in the async API.

cc Titian Cernicova-Dragomir (@dragomirtitian) who specifically requested built-in support for this, since it's cumbersome to wire up without owning the generator executor, but when you own it, it's comparably not bad to add.

[Copilot]

🟡 Changes recommended

Deferred failures can prematurely interrupt foreground work, and completed generators cause quadratic scanning.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds deferred generator work to synchronous API batching without returning deferred results.

Changes:

• Adds defer and deferred-work scheduling.
• Refactors request execution, deduplication, and result mapping.
• Adds runtime coverage for deferred execution and errors.

File summaries

File	Description
packages/typescript/src/api/sync/generatorSupport.ts	Implements deferred request execution.
packages/typescript/src/api/sync/api.ts	Exposes defer through synchronous batching.
packages/typescript/src/api/async/api.ts	Updates sync-generation directives.
packages/typescript/test/sync/api-generators.test.ts	Tests batching and deferred behavior.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Titian Cernicova-Dragomir (dragomirtitian)]

Can we expose UndeferredAPIRequestGenerator and APIRequestGenerator. If the generators are recursive they need a type. We could redefine some of these types on the usage side but they are now more complicated that a simple generator.

If we expose it, I'm not sure UndeferredAPIRequestGenerator is the best name for the common case of the generator, and this is the type that is needed as the return type since APIRequestGenerator is a union and does not work well as a generator return type:

function *testNotOk(n: number): sync.APIRequestGenerator<number> {
    if(n === 0) return 0;
    return yield * testNotOk(n-1)
}


function *testOk(n: number): sync.UndeferredAPIRequestGenerator<number> {
    if(n === 0) return 0;
    return yield * testOk(n-1)
}

[Wesley Wigham (weswigham)]

I've renamed 'em and exported 'em. AnyAPIRequestGenerator is the union, APIRequestGenerator is the undeferred one, and DeferredAPIRequestGenerator remains the deferred one.