promise

Documentation

Overview

Package promise provides a generic, type-safe implementation of Promises, inspired by the JavaScript Promise API. It is designed to simplify the management of asynchronous operations and avoid complex callback chains ("callback hell").

Core Concepts

A Promise represents the eventual completion (or failure) of an asynchronous operation and its resulting value. A Promise is in one of three states:

• pending: the initial state; neither fulfilled nor rejected.
• fulfilled: the operation completed successfully, resulting in a value.
• rejected: the operation failed, resulting in an error.

Basic Usage

The primary way to create a promise is with the `New` function, which takes an `executor` function. The executor is run in a new goroutine and receives `resolve` and `reject` functions to control the promise's outcome.

Example:

// Create a promise that resolves after a delay.
p := promise.New(func(resolve func(string), reject func(error)) {
	time.Sleep(100 * time.Millisecond)
	resolve("Hello, World!")
})

// The Await method blocks until the promise is settled.
val, err := p.Await()
// val is "Hello, World!", err is nil.

Chaining

Promises can be chained together using methods like `Then`, `Catch`, and `Finally` to create a clean, linear asynchronous workflow.

resultPromise := promise.Async(func() (int, error) {
	// Simulate an API call
	return 42, nil
}).Then(func(val int) int {
	// Transform the result
	return val * 2
}).Catch(func(err error) (int, error) {
	// Handle any previous errors and potentially recover.
	fmt.Printf("An error occurred: %v\n", err)
	return 0, nil // Recover with a default value
})

finalResult, _ := resultPromise.Await() // finalResult is 84

Index

• func Await[T any](p *Promise[T]) (T, error)
• type Promise
  • func Async[T any](f func() (T, error)) *Promise[T]
  • func New[T any](executor func(resolve func(T), reject func(error))) *Promise[T]
  • func (p *Promise[T]) Await() (T, error)
  • func (p *Promise[T]) Catch(onRejected func(error) (T, error)) *Promise[T]
  • func (p *Promise[T]) Finally(onFinally func()) *Promise[T]
  • func (p *Promise[T]) Reject(err error)
  • func (p *Promise[T]) Resolve(value T)
  • func (p *Promise[T]) Then(onFulfilled func(T) T) *Promise[T]
  • func (p *Promise[T]) ThenWithPromise(onFulfilled func(T) *Promise[T]) *Promise[T]

Functions

func Await

func Await[T any](p *Promise[T]) (T, error)

Await is a standalone function that waits for a promise to be settled. It is a functional equivalent of the p.Await() method.

Types

type Promise

type Promise[T any] struct {
	// contains filtered or unexported fields
}

Promise represents the eventual completion (or failure) of an asynchronous operation and its resulting value. It is a generic, type-safe implementation inspired by the JavaScript Promise API.

func Async

func Async[T any](f func() (T, error)) *Promise[T]

Async is a helper function that wraps a function returning (T, error) into a new Promise. This is useful for converting existing functions into promise-based asynchronous operations.

func New

func New[T any](executor func(resolve func(T), reject func(error))) *Promise[T]

New creates a new Promise. The provided executor function is executed in a new goroutine. The executor receives `resolve` and `reject` functions to control the promise's outcome.

func (*Promise[T]) Await

func (p *Promise[T]) Await() (T, error)

Await blocks until the promise is settled and returns the resulting value and error. It is the primary way to get the result of a promise.

func (*Promise[T]) Catch

func (p *Promise[T]) Catch(onRejected func(error) (T, error)) *Promise[T]

Catch attaches a callback that executes when the promise is rejected. It allows for error handling and recovery. The onRejected callback can return a new value to fulfill the promise, or a new error to continue the rejection chain.

func (*Promise[T]) Finally

func (p *Promise[T]) Finally(onFinally func()) *Promise[T]

Finally attaches a callback that executes when the promise is settled (either fulfilled or rejected). It is useful for cleanup logic. The returned promise will be settled with the same value or error as the original promise, after onFinally has completed.

func (*Promise[T]) Reject

func (p *Promise[T]) Reject(err error)

Reject rejects the promise with an error. If the promise is already settled, this call is ignored.

func (*Promise[T]) Resolve

func (p *Promise[T]) Resolve(value T)

Resolve fulfills the promise with a value. If the promise is already settled, this call is ignored.

func (*Promise[T]) Then

func (p *Promise[T]) Then(onFulfilled func(T) T) *Promise[T]

Then attaches a callback that executes when the promise is fulfilled. It returns a new promise that resolves with the result of the onFulfilled callback. If the original promise is rejected, the new promise is rejected with the same error.

func (*Promise[T]) ThenWithPromise

func (p *Promise[T]) ThenWithPromise(onFulfilled func(T) *Promise[T]) *Promise[T]

ThenWithPromise is like Then, but the callback returns a new Promise. This allows for chaining of asynchronous operations.