iAPI: Introduce AsyncAction and TypeYield type helpers (#70422)

* Introduce AsyncAction and TypeYield helpers

* Use the helpers on the other tests

* Update docs for AsyncAction

* Update docs for TypeYield

* Export the helpers

* Replace manual typing with satisfies on TypeYield return

* Improve docs

* Update changelog

---------

Co-authored-by: luisherranz <[email protected]>
Co-authored-by: DAreRodz <[email protected]>

Author: 3 people

docs/reference-guides/interactivity-api/core-concepts/using-typescript.md

@@ -471,39 +471,84 @@ type Store = {
 };
 ```
 
-There's something to keep in mind when when using asynchronous actions. Just like with the derived state, if the asynchronous action needs to return a value and this value directly depends on some part of the global state, TypeScript will not be able to infer the type due to a circular reference.
+There's something to keep in mind when using asynchronous actions. Just like with the derived state, if an asynchronous action uses `state` within a `yield` expression (for example, by passing `state` to an async function that is then yielded) or if its return value depends on `state`, TypeScript might not be able to infer the types correctly due to a potential circular reference.
 
     ```ts
     const { state, actions } = store( 'myCounterPlugin', {
     	state: {
     		counter: 0,
     	},
     	actions: {
-    		*delayedReturn() {
-    			yield new Promise( ( r ) => setTimeout( r, 1000 ) );
-    			return state.counter; // TypeScript can't infer this return type.
+    		*delayedOperation() {
+    			// Example: state.counter is used as part of the yielded logic.
+    			yield fetchCounterData( state.counter );
+
+    			// And/or the final return value depends on state.
+    			return state.counter + 1;
     		},
     	},
     } );
     ```
 
-    In this case, just as we did with the derived state, we must manually type the return value of the generator.
+In such cases, TypeScript might issue a warning about a circular reference or default to `any`. To solve this, you need to manually type the generator function. The Interactivity API provides a helper type, `AsyncAction<ReturnType>`, for this purpose.
 
     ```ts
+    import { store, type AsyncAction } from '@wordpress/interactivity';
+
     const { state, actions } = store( 'myCounterPlugin', {
     	state: {
     		counter: 0,
     	},
     	actions: {
-    		*delayedReturn(): Generator< unknown, number, unknown > {
-    			yield new Promise( ( r ) => setTimeout( r, 1000 ) );
-    			return state.counter; // Now this is correctly inferred.
+    		*delayedOperation(): AsyncAction< number > {
+    			// Now, this doesn't cause a circular reference.
+    			yield fetchCounterData( state.counter );
+
+    			// Now, this is correctly typed.
+    			return state.counter + 1;
+    		},
+    	},
+    } );
+    ```
+
+That's it! The `AsyncAction<ReturnType>` helper is defined as `Generator<any, ReturnType, unknown>`. By using `any` for the type of values yielded by the generator, it helps break the circular reference, allowing TypeScript to correctly infer the types when `state` is involved in `yield` expressions or in the final return value. You only need to specify the final `ReturnType` of your asynchronous action.
+
+### Typing yielded values in asynchronous actions
+
+While `AsyncAction<ReturnType>` types the overall generator and its final return value, the value resolved by an individual `yield` expression within that generator might still be typed as `any`.
+
+If you need to ensure the correct type for a value that a `yield` expression resolves to (e.g., the result of a `fetch` call or another async operation), you can use the `TypeYield<T>` helper. This helper takes the type of the asynchronous function/operation being yielded (`T`) and resolves to the type of the value that the promise fulfills with.
+
+Suppose `fetchCounterData` returns a promise that resolves to an object:
+
+    ```ts
+    import { store, type AsyncAction, type TypeYield } from '@wordpress/interactivity';
+
+    // Assume this function is defined elsewhere and fetches specific data.
+    const fetchCounterData = async ( counterValue: number ): Promise< { current: number, next: number } > => {
+        // internal logic...
+    };
+
+    const { state, actions } = store( 'myCounterPlugin', {
+    	state: {
+    		counter: 0,
+    	},
+    	actions: {
+    		*loadCounterData(): AsyncAction< void > {
+    			// Use TypeYield to correctly type the resolved value of the yield.
+    			const data = ( yield fetchCounterData( state.counter ) ) as TypeYield< typeof fetchCounterData >;
+
+    			// Now, `data` is correctly typed as { current: number, next: number }.
+    			console.log( data.current, data.next );
+
+    			// Update state based on the fetched data.
+    			state.counter = data.next;
     		},
     	},
     } );
     ```
 
-    That's it! Remember that the return type of a Generator is the second generic argument: `Generator< unknown, ReturnType, unknown >`.
+In this example, `( yield fetchCounterData( state.counter ) ) as TypeYield< typeof fetchCounterData >` ensures that the `data` constant is correctly typed as `{ current: number, next: number }`, matching the return type of `fetchCounterData`. This allows you to confidently access properties like `data.current` and `data.next` with type safety.
 
 ## Typing stores that are divided into multiple parts
 

packages/interactivity-router/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 -   Export `NavigateOptions` and `PrefetchOptions` types. ([#70315](https://github.com/WordPress/gutenberg/pull/70315))
 -   Support new styles and script modules on client-side navigation, including a new full-page client-side navigation mode. ([#70353](https://github.com/WordPress/gutenberg/pull/70353))
+-   Introduce `AsyncAction` and `TypeYield` type helpers. ([#70422](https://github.com/WordPress/gutenberg/pull/70422))
 
 ### Bug Fixes
 

packages/interactivity/src/index.ts

@@ -16,7 +16,13 @@ import { getNamespace } from './namespaces';
 import { parseServerData, populateServerData } from './store';
 import { proxifyState } from './proxies';
 
-export { store, getConfig, getServerState } from './store';
+export {
+	store,
+	getConfig,
+	getServerState,
+	type AsyncAction,
+	type TypeYield,
+} from './store';
 export { getContext, getServerContext, getElement } from './scopes';
 export {
 	withScope,

packages/interactivity/src/store.ts

@@ -84,6 +84,9 @@ interface StoreOptions {
 	lock?: boolean | string;
 }
 
+export type AsyncAction< T > = Generator< any, T, unknown >;
+export type TypeYield< T extends ( ...args: any[] ) => Promise< any > > =
+	Awaited< ReturnType< T > >;
 type Prettify< T > = { [ K in keyof T ]: T[ K ] } & {};
 type DeepPartial< T > = T extends object
 	? { [ P in keyof T ]?: DeepPartial< T[ P ] > }

packages/interactivity/src/test/store.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { store } from '../store';
+import { store, type AsyncAction, type TypeYield } from '../store';
 
 describe( 'Interactivity API', () => {
 	describe( 'store', () => {
@@ -74,7 +74,7 @@ describe( 'Interactivity API', () => {
 							sync( n ) {
 								return n;
 							},
-							*async( n ): Generator< unknown, number, unknown > {
+							*async( n ): AsyncAction< number > {
 								const n1 = myStore.actions.sync( n );
 								return myStore.state.derived + n1 + n;
 							},
@@ -114,13 +114,17 @@ describe( 'Interactivity API', () => {
 							sync( n: number ) {
 								return n;
 							},
-							*async(
-								n: number
-							): Generator< unknown, number, number > {
-								const n1: number =
-									yield myStore.actions.sync( n );
+							*async( n: number ): AsyncAction< number > {
+								const n1 = ( yield myStore.actions.async2(
+									n
+								) ) as TypeYield<
+									typeof myStore.actions.async2
+								> satisfies number;
 								return myStore.state.derived + n1 + n;
 							},
+							*async2( n: number ) {
+								return n;
+							},
 						},
 					};
 
@@ -161,13 +165,17 @@ describe( 'Interactivity API', () => {
 							sync( n: number ) {
 								return n;
 							},
-							*async(
-								n: number
-							): Generator< unknown, number, number > {
-								const n1: number =
-									yield myStore.actions.sync( n );
+							*async( n: number ): AsyncAction< number > {
+								const n1 = ( yield myStore.actions.async2(
+									n
+								) ) as TypeYield<
+									typeof myStore.actions.async2
+								> satisfies number;
 								return myStore.state.derived + n1 + n;
 							},
+							*async2( n: number ) {
+								return n;
+							},
 						},
 					} );
 
@@ -191,6 +199,7 @@ describe( 'Interactivity API', () => {
 						actions: {
 							sync: ( n: number ) => number;
 							async: ( n: number ) => Promise< number >;
+							async2: ( n: number ) => AsyncAction< number >;
 						};
 						callbacks: {
 							existent: number;
@@ -202,11 +211,17 @@ describe( 'Interactivity API', () => {
 							sync( n ) {
 								return n;
 							},
-							*async( n ): Generator< unknown, number, number > {
-								const n1: number =
-									yield myStore.actions.sync( n );
+							*async( n ): AsyncAction< number > {
+								const n1 = ( yield myStore.actions.async2(
+									n
+								) ) as TypeYield<
+									typeof myStore.actions.async2
+								> satisfies number;
 								return n1 + n;
 							},
+							*async2( n: number ) {
+								return n;
+							},
 						},
 						callbacks: {
 							existent: 1,
@@ -317,6 +332,42 @@ describe( 'Interactivity API', () => {
 
 				actions2.incrementValue( 1 ) satisfies void;
 			} );
+
+			describe( 'async actions can pass state to yields and type the yield returns', () => {
+				// eslint-disable-next-line no-unused-expressions
+				async () => {
+					type Store = {
+						state: {
+							someValue: string;
+						};
+						actions: {
+							asyncAction: () => Promise< number >;
+						};
+					};
+
+					const asyncFunction = async (
+						someValue: string
+					): Promise< string > => {
+						return someValue;
+					};
+
+					const { state, actions } = store< Store >( 'test', {
+						actions: {
+							*asyncAction(): AsyncAction< number > {
+								( yield asyncFunction(
+									state.someValue
+								) ) as TypeYield<
+									typeof asyncFunction
+								> satisfies string;
+
+								return 1;
+							},
+						},
+					} );
+
+					( await actions.asyncAction() ) satisfies number;
+				};
+			} );
 		} );
 	} );
 } );