fixes

fluence-js/2_basics.md

@@ -171,7 +171,7 @@ main();
 
 (3) A Fluence peer has to be started before running any application in Fluence Network. For the vast majority of use cases you should use `Fluence` facade to start and stop the peer. The `start` method accepts a parameters object which. The most common parameter is the address of the relay node the peer should connect to. In this example we are using the first node of the `krasnodar` network. If you do not specify the `connectTo` options will only be able to execute air on the local machine only. Please keep in mind that the init function is asynchronous.
 
-For every exported `service XXX` definition in aqua code, the compiler provides a `registerXXX` counterpart. These functions provide a type-safe way of registering callback handlers for the services. The callbacks are executed when the appropriate service is called in aqua on the current peer. The handlers take form of the object where keys are the name of functions and the values are async functions used as the corresponding callbacks. For example in (4) we are registering handlers for `HelloWorld` service functions which outputs it's parameter to the console. Please not that the handlers can be implemented in both: synchronous and asynchronous way. The handler can be made asynchronous like any other function in javascript: either has return a Promise or has to be mark it with async keyword to take advantage of async-await pattern
+For every exported `service XXX` definition in aqua code, the compiler provides a `registerXXX` counterpart. These functions provide a type-safe way of registering callback handlers for the services. The callbacks are executed when the appropriate service is called in aqua on the current peer. The handlers take form of the object where keys are the name of functions and the values are async functions used as the corresponding callbacks. For example in (4) we are registering handlers for `HelloWorld` service functions which outputs it's parameter to the console. Please not that the handlers can be implemented in both: synchronous and asynchronous way. The handler can be made asynchronous like any other function in javascript: either return a Promise or mark it with async keyword to take advantage of async-await pattern.
 
 For every exported `func XXX` definition in aqua code, the compiler provides an async function which can be directly called from typescript. In (5, 6) we are calling exported aqua function with no arguments. Note that every function is asynchronous.
 

fluence-js/3_in_depth.md

@@ -297,6 +297,42 @@ For the service definitions arguments are named (see calc example above)
 
 ### Using asynchronous code in callbacks
 
+Typescript code generated by Aqua compiler has two scenarios where a user should specify a callback function. These are services and callback arguments of function in aqua. If you look at the return type of the generated function you will see a union of callback return type and the promise with this type, e.g `string | Promise<string>`. Fluence-js supports both sync and async version of callback and figures out which one is used under the hood. The callback be made asynchronous like any other function in javascript: either return a Promise or mark it with async keyword to take advantage of async-await pattern.
+
+For example:
+
+```
+func withCallback(callback: string -> ()):
+  callback()
+
+service MyService:
+  callMe(string)
+```
+
+Here we returning a promise
+
+```typescript
+registerMyService({
+  callMe: (arg): Promise<void> => {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        console.log("I'm running 3 seconds after call");
+        resolve();
+      }, 3000);
+    });
+  },
+});
+```
+
+And here we are using async-await pattern
+
+```typescript
+await withCallback(async (arg) => {
+  const data = await getStuffFromDatabase(arg);
+  console.log("");
+});
+```
+
 ### Call params and tetraplets
 
 Each service call is accompanied by additional information specific to Fluence Protocol. Including `initPeerId` - the peer which initiated the particle execution, particle signature and most importantly security tetraplets. All this data is contained inside the last `callParams` argument in every generated function definition. These data is passed to the handler on each function call can be used in the application.