Generator-based control flow for Go — a functionally equivalent port of tj/co v4.6.0.
co lets you write asynchronous code that reads sequentially. You yield
"yieldables" — promises, thunks, generators, arrays, objects — and get their
results back as plain values. The library resolves them and resumes you.
package main
import (
"fmt"
"time"
co "github.com/tj/co-go"
)
func main() {
p := co.Co(func(y *co.Yielder) (any, error) {
result, err := y.Yield(co.Thunk(func(done func(error, ...any)) {
time.AfterFunc(10*time.Millisecond, func() { done(nil, "hello") })
}))
if err != nil {
return nil, err
}
return result.(string) + " world", nil
})
value, err := p.Await()
fmt.Println(value, err) // hello world <nil>
}go get github.com/tj/co-goRuns gen and returns a promise for its return value. gen may be a generator
function, a live generator, or a plain function. Extra arguments are forwarded.
Equivalent to co(gen, ...args).
Same, with an explicit receiver. ctx is what y.Ctx() returns inside the body
and what context-aware thunks receive. Equivalent to co.call(this, gen, ...).
Converts a generator function into a reusable, callable unit.
run := co.Wrap(func(y *co.Yielder, id int) (any, error) {
return y.Yield(fetch(id))
})
value, err := run.Call(42).Await()Wrapped.Call(args...), Wrapped.CallCtx(ctx, args...) and
Wrapped.GeneratorFunction() port fn(...), fn.call(this, ...) and
fn.__generatorFunction__.
Creates a live generator you can drive yourself with Next / Throw, or yield
into another co body.
| Kind | Go type | Behaviour |
|---|---|---|
| Promise | *co.Promise, any co.Thenable |
awaited |
| Thunk | co.Thunk, co.CtxThunk |
called with a completion callback |
| Generator function | func(*co.Yielder) (any, error) and typed variants |
run with co |
| Generator | co.Generator |
run with co |
| Wrapped | *co.Wrapped |
called, its promise adopted |
| Array | []any and any slice/array except []byte |
resolved in parallel, order preserved |
| Object | *co.Object, any string-keyed map |
values resolved in parallel, keys preserved |
[]byte is excluded on purpose: the original rejects a Buffer, and silently
resolving one element-wise would turn an error into garbage. Yield a []any if
that is what you meant.
Anything else raises a *co.TypeError inside the generator, so it is
recoverable:
_, err := y.Yield(42)
// err: You may only yield a function, promise, generator, array, or object,
// but the following object was passed: "42"A thunk is a function taking a completion callback:
func read(name string) co.Thunk {
return func(done func(err error, res ...any)) {
data, err := os.ReadFile(name)
done(err, string(data))
}
}Result arity matches the original: no results yield nil, one result yields the
value, two or more yield a []any.
res, err := y.Yield([]any{read("a.txt"), read("b.txt")})
// res.([]any) -> ["...", "..."]
obj, err := y.Yield(co.ObjectOf(
"a", read("a.txt"),
"b", read("b.txt"),
))
// obj.(*co.Object) -> {a: "...", b: "..."} with key order preservedBoth nest arbitrarily.
Yield returns (value, error). Handle it, or ignore it and return it — that is
the port of try/catch around yield:
value, err := y.Yield(mightFail())
if err != nil {
return "fallback", nil // recovered, the generator continues
}y.MustYield(v) throws instead of returning an error, ending the generator and
rejecting the promise.
co.Promise follows the Promises/A+ state machine: single settlement, thenable
adoption, and reactions delivered serially on a microtask queue.
p.Then(onFulfilled, onRejected)
p.Catch(onRejected)
p.Finally(fn)
p.Await() // (any, error) — blocks
<-p.Done() // settle signal
p.State() // Pending | Fulfilled | RejectedNever call Await from inside a generator body or a Then / Catch /
Finally handler. Both run on goroutines the queue depends on, so blocking
one stalls every promise in the program. Await detects this and panics with an
explanation rather than hanging silently; yield the promise with y.Yield(p),
or return it from the handler and let it be adopted. Awaiting a promise that has
already settled is always fine.
Everything observable is preserved. These are the mechanical consequences of the target language and are documented in full in MIGRATION.md:
- Generators are goroutines.
cocloses the ones it abandons, but a generator you drive yourself and drop while suspended holds its goroutine until you callClose(). thisbecomes an explicitctx anyparameter. It is unrelated tocontext.Context.- Rejection reasons are
error. A non-error reason travels inside*co.Rejection, reachable witherrors.As. *co.Objectprovides the ordered string-keyed map that JavaScript objects give for free.
One behaviour is deliberately not reproduced: yield co.wrap(fn) hangs
forever in the original, because the wrapper is mistaken for a thunk. Here it is
called and its promise adopted.
go test -race ./...The suite is a case-for-case port of the original Mocha suite — one top-level
Test function per it() — plus tests pinning the semantics that Go could
otherwise drift on. The runnable examples in example_test.go are checked
against their // Output: comments by the same command.
MIT — see LICENSE. Original work copyright (c) 2014 TJ Holowaychuk.