Getting Started

This page is a quick guide to undersand and use Synk. Further information is provided in next pages.

Anatomy of a Synk Function

A Synk function is a standard generator function. The only difference is its content and the way you should call it.

To define a Synk function, just create a generator function:

function* MySynkFunction (...args) {
    ...
}

One of the abilities of a Synk function is to yield a Snippet.

A snippet is an object which can do some work and return the value to our current Synk function. The function will stay suspended until the snippet returns a value. A snippet can be synchronous or asynchronous, depending on its implementation and work.

Any generator function will be suspended when an yield statament is found. In our case, we can yield a new Snippet:

function* MyDelayedSynk(){
    yield new Snippet.Delay(1000);
}

The above code runs the function, awaits 1000 milliseconds and return.

A snippet can return some value by setting a property in the this pseudo-object. Most of snippets will set the property this.return to the expected value. It is the case of the snippet ReadKey.

function* OldReadKey(){
    yield new Snippet.ReadKey();
    alert('You pressed: '+this.result);
}

A snippet can even receive a parameter when needed. The snippet of DomEvents, for example, will expect you to tell what is the event to expect and what is the element or selector to use:

function* WaitClick(){
    yield new Snippet.DomEvent('click', '#myButton1');
    console.log('Event:',this.result);
}

Yielding a value other than a Snippet, will have no effect.

Calling the function

To call a Synk function, create a new Synk instance:

new Synk(MySynkFunction);

You can pass arguments to the function through an array in the second parameter:

new Synk(MySynkFunction, [arg1, arg2, arg3]);

Remember: the function will be a synchronous call while it does synchronous call, and it will be asynchronous when yielding an asynchronous call.

It is important to mention that calling a Synk function in a standard way (myFunction();) without the Synk object will only create a standard passive generator. Nothing will happen at all.

A function inside a function

When you are inside a Synk function, there are two types of call another Synk function.

Creating a new Synk object and making a default call can be different than expected, once the called function will not block the code if there is some asynchronous content.

For that, we have a Snippet which allows to call another Synk function and wait for it to return before continuing our code:

function* myFunction1(n1, n2, n3){
}

function* myFunction2(){
    yield new Snippet.Call(myFunction1, [1,2,3]);
}

In the example above, we are also passing three parameters. It is optional, as Synk function does not need to exepect any parameter and a call does not need to pass supply parameters (non supplied parameters will stay as undefined).

Whether waiting the function is not a behavior you want, you can just call it in the standard way:

function* myFunction2(){
    new Synk(myFunction1, [1,2,3]);
}

Note that pure synchronous calls can be made as in any other code:

function* myFunction(){
    alert('Hello');
    var x = Math.floor(5.3);
}

Returning values from Synk functions

This behavior is planned, but not implemented yet.

It should be done through a Promise-like way (but simpler). Once there is some implementation, this text will be updated and a new page will be created explaining how it will work.

What is next?

Here you should have learn that:

a synk function is just a standard generator of ECMA 6;
our secret is only the yield and the snippets;
there is a specific way to call the synk function.

The next sections will explain about synchrony and asynchrony. This will be important to understand the behavior of Synk. Also, there is some performance gaps out of our control.

In the right panel you can find information about what Snippets are available and their behaviors.

Enjoy the library!