document meteor methods callAsync promises

v3-docs/docs/api/meteor.md

@@ -401,7 +401,71 @@ Use `Meteor.call` only to call methods that do not have a stub, or have a sync s
 
 <ApiBox name="Meteor.callAsync" />
 
-`Meteor.callAsync` is just like `Meteor.call`, except that it'll return a promise that you need to solve to get the result.
+`Meteor.callAsync` is just like `Meteor.call`, except that it'll return a promise that you need to solve to get the server result. Along with the promise returned by `callAsync`, you can also handle `stubPromise` and `serverPromise` for managing client-side simulation and server response.
+
+The following sections guide you in understanding these promises and how to manage them effectively.
+
+#### serverPromise
+
+```javascript
+try {
+	await Meteor.callAsync('greetUser', 'John');
+	// 🟢 Server ended with success
+} catch(e) {
+	console.error("Error:", error.reason); // 🔴 Server ended with error
+}
+
+Greetings.findOne({ name: 'John' }); // 🗑️ Data is NOT available
+```
+
+#### stubPromise
+
+```javascript
+await Meteor.callAsync('greetUser', 'John').stubPromise;
+
+// 🔵 Client simulation
+Greetings.findOne({ name: 'John' }); // 🧾 Data is available (Optimistic-UI)
+```
+
+#### stubPromise and serverPromise
+
+```javascript
+const { stubPromise, serverPromise } = Meteor.callAsync('greetUser', 'John');
+
+await stubPromise;
+
+// 🔵 Client simulation
+Greetings.findOne({ name: 'John' }); // 🧾 Data is available (Optimistic-UI)
+
+try {
+  await serverPromise;
+  // 🟢 Server ended with success
+} catch(e) {
+  console.error("Error:", error.reason); // 🔴 Server ended with error
+}
+
+Greetings.findOne({ name: 'John' }); // 🗑️ Data is NOT available
+```
+
+#### Meteor 2.x contrast
+
+For those familiar with legacy Meteor 2.x, the handling of client simulation and server response was managed using fibers, as explained in the following section. This comparison illustrates how async inclusion with standard promises has transformed the way Meteor operates in modern versions.
+
+``` javascript
+Meteor.call('greetUser', 'John', function(error, result) {
+  if (error) {
+    console.error("Error:", error.reason); // 🔴 Server ended with error
+  } else {
+    console.log("Result:", result); // 🟢 Server ended with success
+  }
+
+  Greetings.findOne({ name: 'John' }); // 🗑️ Data is NOT available
+});
+
+// 🔵 Client simulation
+Greetings.findOne({ name: 'John' }); // 🧾 Data is available (Optimistic-UI)
+```
+
 
 <ApiBox name="Meteor.apply" />