feat: add Until.

Author: ghosind

error.go

@@ -18,6 +18,8 @@ var (
 	// ErrUnmatchedParam indicates the function's parameter list does not match to the list from the
 	// caller.
 	ErrUnmatchedParam error = errors.New("parameters are unmatched")
+	// ErrInvalidTestFunc indicates the test function is invalid.
+	ErrInvalidTestFunc error = errors.New("invalid test function")
 )
 
 type ExecutionError interface {

until.go

@@ -0,0 +1,88 @@
+package async
+
+import (
+	"context"
+	"reflect"
+)
+
+// Until repeatedly calls the function until the test function returns true. A valid test function
+// must match the following requirements.
+//
+// - The first return value of the test function must be a boolean value.
+// - The parameters' number of the test function must be equal to the return values' number of the
+// execution function (exclude context).
+// - The parameters' types of the test function must be the same or convertible to the return
+// values' types of the execution function.
+//
+//	c := 0
+//	Until(func() bool {
+//	  return c == 5
+//	}, func() {
+//	  c++
+//	})
+func Until(testFn, fn AsyncFn) ([]any, error) {
+	return until(context.Background(), testFn, fn)
+}
+
+// UntilWithContext repeatedly calls the function with the specified context until the test
+// function returns true.
+func UntilWithContext(ctx context.Context, testFn, fn AsyncFn) ([]any, error) {
+	return until(ctx, testFn, fn)
+}
+
+// until repeatedly calls the function until the test function returns true.
+func until(parent context.Context, testFn, fn AsyncFn) ([]any, error) {
+	validateUntilFuncs(testFn, fn)
+
+	ctx := getContext(parent)
+
+	for {
+		out, err := invokeAsyncFn(fn, ctx, nil)
+
+		testOut, _ := invokeAsyncFn(testFn, ctx, out)
+		isDone := testOut[0].(bool)
+		if isDone {
+			return out, err
+		}
+	}
+}
+
+// validateUntilFuncs validates the test function and the execution function.
+func validateUntilFuncs(testFn, fn AsyncFn) {
+	if testFn == nil || fn == nil {
+		panic(ErrNotFunction)
+	}
+	tft := reflect.TypeOf(testFn) // reflect.Type of the test function
+	ft := reflect.TypeOf(fn)      // reflect.Type of the function
+	if tft.Kind() != reflect.Func || ft.Kind() != reflect.Func {
+		panic(ErrNotFunction)
+	}
+
+	if tft.NumOut() <= 0 || tft.Out(0).Kind() != reflect.Bool {
+		panic(ErrInvalidTestFunc)
+	}
+
+	ii := 0 // index of the test function input parameters list
+	oi := 0 // index of the function return values list
+	numIn := tft.NumIn()
+	isTakeContext := isFuncTakesContext(tft)
+	if isTakeContext {
+		numIn--
+		ii++
+	}
+	if numIn != ft.NumOut() {
+		panic(ErrInvalidTestFunc)
+	}
+
+	for oi < numIn {
+		it := tft.In(ii) // type of the value in the test function input parameters list
+		ot := ft.Out(oi) // type of the value in the function return values list
+
+		if it != ot && !it.ConvertibleTo(ot) {
+			panic(ErrInvalidTestFunc)
+		}
+
+		ii++
+		oi++
+	}
+}

until_test.go

@@ -0,0 +1,77 @@
+package async
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/ghosind/go-assert"
+)
+
+func TestUntil(t *testing.T) {
+	a := assert.New(t)
+	count := 0
+
+	out, err := Until(func(c int) bool {
+		return c == 5
+	}, func() int {
+		count++
+		return count
+	})
+	a.NilNow(err)
+	a.EqualNow(out, []any{5})
+}
+
+func TestUntilInvalidParameters(t *testing.T) {
+	a := assert.New(t)
+
+	a.PanicOfNow(func() {
+		Until(nil, func() {})
+	}, ErrNotFunction)
+	a.PanicOfNow(func() {
+		Until(func() {}, nil)
+	}, ErrNotFunction)
+	a.PanicOfNow(func() {
+		Until(1, "hello")
+	}, ErrNotFunction)
+	a.PanicOfNow(func() {
+		Until(func() {}, func() {})
+	}, ErrInvalidTestFunc)
+	a.NotPanicNow(func() {
+		Until(func() bool { return true }, func() {})
+	})
+	a.NotPanicNow(func() {
+		Until(func(err error) bool { return true }, func() error { return nil })
+	})
+	a.NotPanicNow(func() {
+		Until(func(ctx context.Context, err error) bool { return true }, func() error { return nil })
+	})
+	a.PanicOfNow(func() {
+		Until(func(ctx context.Context, i int) bool { return true }, func() error { return nil })
+	}, ErrInvalidTestFunc)
+	a.PanicOfNow(func() {
+		Until(func(ctx context.Context, i int) bool { return true }, func() {})
+	}, ErrInvalidTestFunc)
+}
+
+func TestUntilWithContext(t *testing.T) {
+	a := assert.New(t)
+	ctx, canFunc := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer canFunc()
+
+	start := time.Now()
+	out, err := UntilWithContext(ctx, func(ctx context.Context) bool {
+		select {
+		case <-ctx.Done():
+			return true
+		default:
+			return false
+		}
+	}, func() {
+	})
+	a.NilNow(err)
+	a.EqualNow(out, []any{})
+	dur := time.Since(start)
+	a.GteNow(dur, 100*time.Millisecond)
+	a.LteNow(dur, 150*time.Millisecond)
+}