README
¶
PROMISE
About
Promises library for Golang. Inspired by JS Promises
Supports:
• Automatic panic recovery
• Nested promise flattening
• Promise cancellation
Note that the library will be updated as soon as generics arrive in Go 2.0 to allow for greater type safety, less boilerplate and better performance
Install
$ go get -u github.com/chebyrash/promise
Quick Start
var p = promise.New(func(resolve func(interface{}), reject func(interface{})) {
// Do something asynchronously.
const sum = 2 + 2
// If your work was successful call resolve() passing the result.
if sum == 4 {
resolve(sum)
return
}
// If you encountered an error call reject() passing the error.
if sum != 4 {
reject(errors.New("2 + 2 doesnt't equal 4"))
return
}
// If you forgot to check for errors and your function panics the promise will
// automatically reject.
// panic() == reject()
}).
// You may continue working with the result of
// a previous async operation.
Then(func(data interface{}) interface{} {
fmt.Println("The result is:", data)
return data.(int) + 1
}).
// Handlers can be added even after the success or failure of the asynchronous operation.
// Multiple handlers may be added by calling .Then or .Catch several times,
// to be executed independently in insertion order.
Then(func(data interface{}) interface{} {
fmt.Println("The new result is:", data)
return nil
}).
Catch(func(error error) error {
fmt.Println("Error during execution:", error.Error())
return nil
})
// Since handlers are executed asynchronously you can wait for them.
p.Await()
Methods
All
Wait for all promises to be resolved, or for any to be rejected. If the returned promise resolves, it is resolved with an aggregating array of the values from the resolved promises in the same order as defined in the iterable of multiple promises. If it rejects, it is rejected with the reason from the first promise in the iterable that was rejected.
Example:
var p1 = promise.Resolve(123)
var p2 = promise.Resolve("Hello, World")
var p3 = promise.Resolve([]string{"one", "two", "three"})
results, _ := promise.All(p1, p2, p3).Await()
fmt.Println(results)
// [123 Hello, World [one two three]]
AllSettled
Wait until all promises have settled (each may resolve, or reject). Returns a promise that resolves after all of the given promises have either resolved or rejected, with an array of objects that each describe the outcome of each promise.
Example:
var p1 = promise.Resolve(123)
var p2 = promise.Reject(errors.New("something wrong"))
results, _ := promise.AllSettled(p1, p2).Await()
for _, result := range results.([]interface{}) {
switch value := result.(type) {
case error:
fmt.Printf("Bad error occurred: %s", value.Error())
default:
fmt.Printf("Other result type: %d", value.(int))
}
}
// Other result type: 123
// Bad error occurred: something wrong
Race
Wait until any of the promises is resolved or rejected. If the returned promise resolves, it is resolved with the value of the first promise in the iterable that resolved. If it rejects, it is rejected with the reason from the first promise that was rejected.
Example:
var p1 = promise.Resolve("Promise 1")
var p2 = promise.Resolve("Promise 2")
fastestResult, _ := promise.Race(p1, p2).Await()
fmt.Printf("Both resolve, but %s is faster", fastestResult)
// Both resolve, but Promise 1 is faster
// OR
// Both resolve, but Promise 2 is faster
Resolve
Returns a new Promise that is resolved with the given value. If the value is a thenable (i.e. has a then method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value.
Example:
var p1 = promise.Resolve("Hello, World")
result, _ := p1.Await()
fmt.Println(result)
// Hello, World
Reject
Returns a new Promise that is rejected with the given reason.
Example:
var p1 = promise.Reject(errors.New("bad error"))
_, err := p1.Await()
fmt.Println(err)
// bad error
Examples
HTTP Request
var requestPromise = promise.New(func(resolve func(interface{}), reject func(interface{})) {
resp, err := http.Get("https://httpbin.org/ip")
defer resp.Body.Close()
if err != nil {
reject(err)
return
}
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
reject(err)
return
}
resolve(body)
})
// Parse JSON body in async manner
parsed, err := requestPromise.
Then(func(data interface{}) interface{} {
// This can be a promise, it will automatically flatten
return parseJSON(data.([]byte))
}).Await()
if err != nil {
fmt.Printf("Error: %s\n", err.Error())
return
}
origin := parsed.(map[string]string)["origin"]
fmt.Printf("Origin: %s\n", origin)
Finding Factorial
func findFactorial(n int) int {
if n == 1 {
return 1
}
return n * findFactorial(n-1)
}
func findFactorialPromise(n int) *promise.Promise {
return promise.Resolve(findFactorial(n))
}
func main() {
var factorial1 = findFactorialPromise(5)
var factorial2 = findFactorialPromise(10)
var factorial3 = findFactorialPromise(15)
// Results calculated asynchronously
results, _ := promise.All(factorial1, factorial2, factorial3).Await()
values := results.([]interface{})
fmt.Println("Result of 5! is", values[0])
fmt.Println("Result of 10! is", values[1])
fmt.Println("Result of 15! is", values[2])
}
Chaining
var p = promise.Resolve(nil).
Then(func(data interface{}) interface{} {
fmt.Println("I will execute first")
return nil
}).
Then(func(data interface{}) interface{} {
fmt.Println("And I will execute second!")
return nil
}).
Then(func(data interface{}) interface{} {
fmt.Println("Oh I'm last :(")
return nil
})
p.Await()
Documentation
¶
Index ¶
- func Await(p *Promise) (interface{}, error)
- type Interval
- type Promise
- func All(promises ...*Promise) *Promise
- func AllSettled(promises ...*Promise) *Promise
- func Async(executor func(resolve func(interface{}), reject func(interface{}))) *Promise
- func Each(promises ...*Promise) *Promise
- func Race(promises ...*Promise) *Promise
- func Reject(err error) *Promise
- func Resolve(resolution interface{}) *Promise
- func (promise *Promise) AsCallback(f func(interface{}, error))
- func (promise *Promise) Await() (interface{}, error)
- func (promise *Promise) CalTime() *Promise
- func (promise *Promise) Catch(rejection func(err error) interface{}) *Promise
- func (promise *Promise) Elapse() time.Duration
- func (promise *Promise) Reject(err interface{})
- func (promise *Promise) Resolve(resolution interface{})
- func (promise *Promise) Then(fulfillment func(data interface{}) interface{}) *Promise
- type Timeout
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Interval ¶
type Interval struct {
// contains filtered or unexported fields
}
func SetInterval ¶
type Promise ¶
type Promise struct {
// contains filtered or unexported fields
}
A Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point in the future.
func All ¶
All waits for all promises to be resolved, or for any to be rejected. If the returned promise resolves, it is resolved with an aggregating array of the values from the resolved promises in the same order as defined in the iterable of multiple promises. If it rejects, it is rejected with the reason from the first promise in the iterable that was rejected.
func AllSettled ¶
AllSettled waits until all promises have settled (each may Resolve, or reject). Returns a promise that resolves after all of the given promises have either resolved or rejected, with an array of objects that each describe the outcome of each promise.
func Async ¶
func Async(executor func(resolve func(interface{}), reject func(interface{}))) *Promise
Async instantiates and returns a pointer to a new Promise.
func Race ¶
Race waits until any of the promises is resolved or rejected. If the returned promise resolves, it is resolved with the value of the first promise in the iterable that resolved. If it rejects, it is rejected with the reason from the first promise that was rejected.
func Resolve ¶
func Resolve(resolution interface{}) *Promise
Resolve returns a Promise that has been resolved with a given value.
func (*Promise) AsCallback ¶
func (*Promise) Await ¶
Await is a blocking function that waits for all callbacks to be executed. Returns value and error. Call on an already resolved Promise to get its result and error
Source Files
Directories