Getting Started

$3

``bash
npm i airsync -S


or


yarn add airsync
`

$3

You can use any of these methods to use airsync in your application

`javascript
// using modules
import { convertFn, resolve } from "airsync";

// or using package
import airsync from "airsync";

// using require

const { convertFn, resolve } = require("airsync");

const airsync = require("airsync");
`

Introduction


AirSync is a powerful javascript library that you can use when using async.

The easiest way to see the power of this library is to checkout performance.js file.

AirSync helps you:

* Create JSON from promises without extracting functions or multiple await
* Convert your existing functions that take promises as parameters, you do not need to wait for promises to fulfil in order to pass them to the function. You can just pass them in as is.

The best part is that AirSync makes your code readable while using full power of non-blocking event based I/O that Node.js is known for.

1. JSON

$3

`javascript
const calcAge = async () => 65; // note the async

// this will not result in correct age
const props = {
age: calcAge(),
}

// output:
// {age: Promise}
// Promise {: undefined}
`


$3


Either you can write await for each one of the promises, like:
`javascript
const props = {
age: await calcAge(),
}
`

#### Problems with this solution

* This is going to blow out very soon, meaning, as you introduce new calls or fields in this JSON, it will become very unreadable
* The biggest problem with this is performance. This is becoming blocking calls as we are going to await for the results from functions

$3

You can use AirSync to solve this issue
`javascript
const { resolve } = require("airsync");

const props = resolve({
age: calcAge(),
})
`

Spread Operator

$3

Lets say you have a code

`js
const encodeKey = async () => {
return { keyId: 123 }
}
`

and you want to create JSON like:
`js
{
keyId: 123
}
`

the following WILL NOT create desired result
`js
const result = await resolve({
keyId: encodeKey(),
})
`

what about this?

`js
const result = await resolve({
...encodeKey(),
})
`
This is also not going to work because encodeKey() is an async function.

$3


We have a solution
`js
const result = await resolve({
...await encodeKey(),
})
`

#### Problems with this solution
All of a sudden, our code has to wait for encodeKey to finish, and if the JSON being produced is long with a lot of await like this, this is going to be very slow.

$3


Luckily, we have spread()

`js
const { spread, resolve } = require('airsync');

const result = await resolve({
[spread()]: encodeKey(),
})
`

This will result in correct JSON + this code will run asynchronously no matter how many objects are "spreaded".

Try it on RunKit

Max depth

Default object depth supported by airsync is 64.

2. Async Function

Problem

`javascript
const getAge = async () => 123;
const getDetail = async (age) => The age is ${age};
`

`javascript
await getDetail(getAge());

// output:
// The age is [object Promise]
// Promise {: undefined}
`

Existing Solution


Either you can wait for the getAge() to be resolved first and then pass it to getDetail() like this:
`javascript
await getDetail(await getAge());
`

or you can extract out it to variable.

$3

* This is going to blow out very soon, meaning, as you introduce new calls, it will become very unreadable
* The biggest problem with this is performance. This is becoming blocking calls as we are going to await for the results from functions

AirSync Solution

`javascript
const { convertFn } = require("airsync");
// or you can import using
// const airsync = require('airsync')
// and use airsync.convertFn(...)

const getAge = async () => 123;
const getDetail = convertFn(async (age) => The age is ${age}); // notice the wrap around "convertFn"

const result = await getDetail(getAge());
`

Try it on RunKit

Misc Features

Options

If the first parameter is an object for the convertFn(), that object is used for setting up the options.

For example:

`javascript
const getNumb = convertFn(() => 123, {
startTime: res.startTime,
endTime: res.endTime,
});
`

You can also override the options for a crafted function later.

`javascript
getNumb.setOptions({
// hint: server-timing
startTime: res.startTime,
endTime: res.endTime,

name: "getNumb",
description: "Get number",

debug: false, // to enable airsync debugging
});
`

Following are the possible options

| Option | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | An identity for the function. Defaults to .name - IT MUST NOT CONTAIN SPACE |
| description | A description for the function |
| startTime | Function for server timing - (name, description) => {} - the name and description is passed back to this function |
| endTime | Function for server timing - (name) => {} - the name is passed back to this function |
| debug | Boolean value to tell airsync whether debug logging is enabled or not. It will use a global logger.debug() object. If no such object exists, it will use console.debug() |

Bulk Export (Advanced)

Converting existing exports to crafted functions is easy, either using convertFn for each function which can be cumbersome depending on number of functions; or you can simply convert the whole object using a helper function exportFns.

Let's say you have:

`javascript
const function1 = () => {};
const function2 = () => {};

module.exports = {
function1,
function2,
};
`

Just use exportFns when exporting

`javascript
const { exportFns } = require("airsync");

const function1 = () => {};
const function2 = () => {};

module.exports = exportFns({
function1,
function2,
});
`

Alternatively, you can do it when importing like in example of /examples/resolve.js. Doing it multiple times does not harm.

Get Object Value

If you have a function that returns an object, and you want to grab just one specific value from the object, you can use following get function to do that.

This function used to be part of library. Since 1.0.4, the get() function is removed (see CHANGELOG). However, if you need it, you can add it as utility in your project.

`js
const { get } = require('airsync/get');
`

This function has peer dependency of lodash.get

`javascript

const getProfile = async (uid) => ({
name: "John",
age: 45,
father: {
name: "Peter",
},
});

(async () => {
console.log(await get(getProfile(), "father.name")); // output: Peter
console.log(await get(getProfile(), "mother.name", "Steph")); // output: Steph
console.log(await get(getProfile(), "brother.name")); // output: undefined
})();
`

License

`
Copyright (c) 2020-present @abumq (Majid Q.)

https://github.com/abumq/airsync

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
``