go_promise

README

JS Promise in Golang

This library introduces the Promise feature from JavaScript in Go. It relies on generics and requires minimal version of Go to be 1.18.

Features

The library supports following features.

Wide Promise creation

By using standard creation method with resolve and reject functions as arguments:

import (
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.New(func(resolve go_promise.ResolveFunc[int], reject go_promise.RejectFunc) {
        resolve(10)
    })

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 10, nil
}

By using simple function:

import (
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.Function(func() (int, error) {
        return 10, nil
    })

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 10, nil
}

By using resolve function directly:

import (
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.Resolve(10)

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 10, nil
}

By using reject function directly:

import (
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.Resolve(10)

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 10, nil
}

Chaining

Chaining with then and catch methods is also supported:

import (
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.Function(func() (int, error) {
        return 10, nil
    }).With(go_promise.Then(func(value int) (float64, error) {
        return 0, errors.New("error")
    })).With(go_promise.Catch(func(err error) float64 {
        return 11.1
    })).With(go_promise.Then(func(value float64) (bool, error) {
        return value > 11, nil
    }))

    value, err := go_promise.Await[bool](promise)
    fmt.Println(value, err)
    // Output: true, nil
}

Wrappers

We can wrap a promise with timeout:

import (
	"time"
	
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.Timeout[int](go_promise.Function(func() (int, error) {
        time.Sleep(time.Second)
        return 10, nil
    }), 500 * time.Milisecond)

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 0, promise.timeout
}

We can wrap a promise with retrial policy:

import (
	"github.com/ompluscator/go-promise"
)


func main() {
	try := 0
	
    promise := go_promise.WithRetry[int](go_promise.Function(func() (int, error) {
        if try < 3 {
            try++
            return 0, errors.New("error")
        }
        return 10, nil
    }), 3)

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 10, nil
}

We can wrap a promise with pre-execution policy:

import (
	"time"
	
	"github.com/ompluscator/go-promise"
)


func main() {
	promise := go_promise.AsPreExecuted[int](go_promise.Function(func() (int, error) {
        time.Sleep(time.Second)
        return 10, nil
    }))

    time.Sleep(time.Second)
	// promise is already executed, so there is no additional waiting time

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 10, nil
}

Resolvers

Waiting for results of all promises with method all:

import (
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.All[int](go_promise.Promises{
        go_promise.Function(func() (int, error) {
            return 10, nil
        }),
        go_promise.Function(func() (int, error) {
            return 11, nil
        }),
        go_promise.Function(func() (int, error) {
            return 12, nil
        }),
    })

    value, err := go_promise.Await[[]int](promise)
    fmt.Println(value, err)
    // Output: [11, 10, 12], nil
}

Waiting for results of all promises with method allSettled:

import (
	"errors"
	
    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.AllSettled[int](go_promise.Promises{
        go_promise.Function(func() (int, error) {
            return 10, nil
        }),
        go_promise.Function(func() (int, error) {
            return 0, errors.New("error")
        }),
        go_promise.Function(func() (int, error) {
            return 12, nil
        }),
    })

    settled, err := go_promise.Await[go_promise.SettledResults[int]](promise)
    fmt.Println(settled.Values(), settled.Errors())
    // Output: [10, 12], [error]
}

Waiting for results of all promises with method any:

import (
    "errors"

    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.Any[int](go_promise.Promises{
        go_promise.Function(func() (int, error) {
            return 0, errors.New("error")
        }),
        go_promise.Function(func() (int, error) {
            return 11, nil
        }),
        go_promise.Function(func() (int, error) {
            return 0, errors.New("error")
        }),
    })

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 11, nil
}

Waiting for results of all promises with method race:

import (
    "errors"

    "github.com/ompluscator/go-promise"
)


func main() {
    promise := go_promise.Race[int](go_promise.Promises{
        go_promise.Function(func() (int, error) {
            return 10, nil
        }),
        go_promise.Function(func() (int, error) {
            return 11, nil
        }),
        go_promise.Function(func() (int, error) {
            return 12, nil
        }),
    })

    value, err := go_promise.Await[int](promise)
    fmt.Println(value, err)
    // Output: 11, nil
}

Documentation

Index

• Variables
• func Await[V any](promise Promise) (V, error)
• type CatchFunc
• type ChainFunc
  • func Catch[V any](catch CatchFunc[V]) ChainFunc
  • func Then[V, W any](then ThenFunc[V, W]) ChainFunc
• type Errors
  • func (es Errors) Combine() error
  • func (es Errors) Error() string
• type ExecuteFunc
• type Promise
  • func All[V any](ps Promises) Promise
  • func AllSettled[V any](ps Promises) Promise
  • func Any[V any](ps Promises) Promise
  • func AsPreExecuted[V any](promise Promise) Promise
  • func Function[V any](fn PromiseFunc[V]) Promise
  • func New[V any](executeFunc ExecuteFunc[V]) Promise
  • func Race[V any](ps Promises) Promise
  • func Reject(err error) Promise
  • func Resolve[V any](value V) Promise
  • func WithRetry[V any](promise Promise, maxRetries int) Promise
  • func WithTimeout[V any](promise Promise, duration time.Duration) Promise
• type PromiseFunc
• type Promises
• type RejectFunc
• type ResolveFunc
• type SettledResult
  • func (r SettledResult[V]) IsRejected() bool
  • func (r SettledResult[V]) IsResolved() bool
• type SettledResults
  • func (rs SettledResults[V]) Errors() Errors
  • func (rs SettledResults[V]) Values() []V
• type ThenFunc

Variables

var InvalidTypeErr = errors.New("promise.invalidType")

var MaxRetriesErr = errors.New("promise.maxRetries")

var TimeoutErr = errors.New("promise.timeout")

Functions

func Await

func Await[V any](promise Promise) (V, error)

Types

type CatchFunc

type CatchFunc[V any] func(err error) V

type ChainFunc

type ChainFunc func(promise Promise) Promise

func Catch

func Catch[V any](catch CatchFunc[V]) ChainFunc

func Then

func Then[V, W any](then ThenFunc[V, W]) ChainFunc

type Errors

type Errors []error

func (Errors) Combine

func (es Errors) Combine() error

func (Errors) Error

func (es Errors) Error() string

type ExecuteFunc

type ExecuteFunc[V any] func(resolve ResolveFunc[V], reject RejectFunc)

type Promise

type Promise interface {
	With(chainFunc ChainFunc) Promise
	Reset()
	// contains filtered or unexported methods
}

func All

func All[V any](ps Promises) Promise

func AllSettled

func AllSettled[V any](ps Promises) Promise

func Any

func Any[V any](ps Promises) Promise

func AsPreExecuted

func AsPreExecuted[V any](promise Promise) Promise

func Function

func Function[V any](fn PromiseFunc[V]) Promise

func New

func New[V any](executeFunc ExecuteFunc[V]) Promise

func Race

func Race[V any](ps Promises) Promise

func Reject

func Reject(err error) Promise

func Resolve

func Resolve[V any](value V) Promise

func WithRetry

func WithRetry[V any](promise Promise, maxRetries int) Promise

func WithTimeout

func WithTimeout[V any](promise Promise, duration time.Duration) Promise

type PromiseFunc

type PromiseFunc[V any] func() (V, error)

type Promises

type Promises []Promise

type RejectFunc

type RejectFunc func(err error)

type ResolveFunc

type ResolveFunc[V any] func(value V)

type SettledResult

type SettledResult[V any] struct {
	Value V
	Error error
}

func (SettledResult[V]) IsRejected

func (r SettledResult[V]) IsRejected() bool

func (SettledResult[V]) IsResolved

func (r SettledResult[V]) IsResolved() bool

type SettledResults

type SettledResults[V any] []SettledResult[V]

func (SettledResults[V]) Errors

func (rs SettledResults[V]) Errors() Errors

func (SettledResults[V]) Values

func (rs SettledResults[V]) Values() []V

type ThenFunc

type ThenFunc[V, W any] func(value V) (W, error)