anchor.diff:  `resolve` and `reject`. So you can use one or other to resolve or reject the promise
   respectively.
   
  -[source, clojure]
  -----
  -;; Create a promise from callback
  +.Example creating promise instance using a factory.
  +[source, clojure]
  +----
   (p/promise (fn [resolve reject]
  -             ;; Do things, maybe async...
                (resolve 1)))
   ----
   
   [NOTE]
   ====
  -On JVM platform the function is executed asynchronously in an other thread and
  -in JS platform is determined by *bluebird* default behavior.
  +In both platforms the promise factory function is executed synchrously and
  +making it blocking or not blocking is user responsability.
   ====
   
   
  -=== Simple chaining
  -
  -It there different ways to compose/chain computations using promises. We will start
  -with the basic: lineal way of chaining computations.
  -
  -That can be done using `then` functions exposed in `promesa.core` namespace:
  -
  -[source, clojure]
  -----
  -(def pr (-> (p/promise 1)
  -            (p/then inc)
  -            (p/then inc)
  -            (p/then inc)))
  -
  -(p/then pr (fn [v]
  -             (println v)))
  -;; => Stdout: 4
  -----
  -
  -The same example can be written in this shorter way:
  -
  -[source, clojure]
  -----
  -(def pr (-> (p/promise 1)
  -            (p/chain inc inc inc))
  -(p/then pr (fn [v]
  -             (println v)))
  -
  -;; => Stdout: 4
  -----
  -
  -
  -=== Advanced chaining
  -
  -Until now, we have seen a very simple promise compositions that does not depends
  -on previous results. The `alet` macro allows us build more complex and more
  -powerfull promise compositions using ES7 async/await like syntax.
  -
  -For demostration purposes, imagine that you have this function that emulates async
  -operation and return a promise:
  -
  +=== Promise Chaining
  +
  +The most common way to apply a function to a promise value (or in other word chain
  +its execution) is using the well known `map` function:
  +
  +[source, clojure]
  +----
  +(def result (->> (p/promise 1)
  +                 (p/map inc)))
  +
  +@result     ; only on the jvm
  +;; => 2
  +----
  +
  +For people more coming from js world, it there are also `then` function that
  +works in the same way as `map` but with parameters inverted:
  +
  +[source, clojure]
  +----
  +(def result (-> (p/promise 1)
  +                (p/then inc)))
  +
  +@result     ; only on the jvm
  +;; => 2
  +----
  +
  +If you want to apply multiple functions, instead of using multiple times `then` or 
  +`map`, you can just use `chain`:
  +
  +[source, clojure]
  +----
  +(def result (-> (p/promise 1)
  +                (p/chain inc inc inc))
  +
  +@result     ; only on the jvm
  +;; => 4
  +----
  +
  +It there also `mapcat` function that allows remove one neesting level of promises,
  +and is pretty useful if the function that you want to apply to promise also return
  +a promise instance instead of value:
  +
  +[source, clojure]
  +----
  +(def incp #(p/resolved (inc %)))
  +
  +(def result (->> (p/promise 1)
  +                 (p/mapcat incp)))
  +
  +@result     ; only on the jvm
  +;; => 2
  +----
  +
  +The `mapcat` function is only useful in the JVM platform. In JS platform the `map`
  +function already flattens the result magically (because the underlying
  +implementation does that).
  +
  +
  +=== Async/Await Syntax
  +
  +The _promesa_ library comes with convenient sugar syntax that allows you create
  +a compositions that looks like synchronous code with very clojure familiar
  +`let` syntax:
  +
  +.Example using async/await syntax.
   [source, clojure]
   ----
   (require '[promesa.core :as p])
  
positive.code: === Introduction
  
  The promise is the abstraction that represents the result of an asynchronous
  operation that will be eventually available.
  
  It can be on this states:
  
  - `resolved`: means that the promise contains a value.
  - `rejected`: means thet the promise contains an error.
  - `pending`: means that the promise does not have value.
  
  
  === Creating a promise
  
  It there several different ways to create a promise in _promesa_ library. You can
  create it already resolved with initial value or already rejected with an exception.
  
  Let start creating a promise from a plain value:
  
  [source, clojure]
  ----
  (require '[promesa.core :as p])
  
negative.code: 
  [source,clojure]
  ----
  [funcool/promesa "1.0.0"]
  ----
  
  This package requires JDK8 if you are using it on the JVM platform and
  