iAPI: Introduce AsyncAction and TypeYield type helpers
#15
Conversation
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
docs/reference-guides/interactivity-api/core-concepts/using-typescript.md
Outdated
Show resolved
Hide resolved
docs/reference-guides/interactivity-api/core-concepts/using-typescript.md
Outdated
Show resolved
Hide resolved
My initial idea was to use a function. /**
* Creates a generator that yields a promise and returns its resolved value.
*
* This utility function is used to convert promises into generators, which
* can be useful when working with asynchronous actions.
*
* @since 6.7.0
*
* @param promise The promise to be converted into a generator.
*
* @return A generator that yields the promise and returns its resolved value.
*/
export function typed< T >(
promise: Promise< T >
): Generator< Promise< T >, T, T > {
return ( function* () {
return yield promise;
} )();
}*asyncAction( n: number ) {
const n1 = yield* typed( myPromise( n ) );
const n2: number = n1;
return n2;
}
// as opposed to
*asyncAction( n: number ) {
const n1 = ( yield myPromise( n ) ) as TypeYield< typeof myPromise >;
const n2: number = n1;
return n2;
}But Jon didn't like the idea of using a JavaScript function simply to cast some types, so he deleted it from the original PR. In my opinion, the final syntax was a bit cleaner, but I kind of agree it was not ideal (especially the need for the extra |
What?
This PR introduces two new TypeScript helper types,
AsyncAction<ReturnType>andTypeYield<T>, to the Interactivity API.It also adds documentation for both helpers in the "Using TypeScript" guide, explaining their purpose and how to use them to solve common typing issues with asynchronous actions (generators).
Why?
When working with asynchronous actions (defined as generators) in the Interactivity API and TypeScript, developers can encounter two main issues:
stateis used within ayieldexpression or if the generator's return value depends onstate, TypeScript can struggle to infer types, leading to circular reference errors or types defaulting toany.yieldexpression (e.g., the result of a fetched promise) is not accurately typed within the generator's scope, defaulting toany.How?
AsyncAction<ReturnType>: Defined asGenerator<any, ReturnType, unknown>.This helper allows developers to explicitly type the return value of an asynchronous action (generator). By using
anyfor the yielded values, it helps break circular type dependencies whenstateis used withinyieldexpressions or in the final return value.TypeYield<T extends (...args: any[]) => Promise<any>>: Defined asAwaited<ReturnType<T>>.This helper allows developers to explicitly type the value that a
yieldexpression resolves to, by providing the type of the async function/operation being yielded.