refactor: change Singleton to Map (#1305)

And change its purpose slightly such that it is used to map FTL resource
handles to another type.

Rationale: the main goal of introducing the Singleton type was to allow
custom transformation of FTL resources, and this more closely reflects
that goal. I didn't thin of doing it in this way until later.

go-runtime/ftl/map.go

@@ -0,0 +1,29 @@
+package ftl
+
+import (
+	"context"
+	"sync"
+)
+
+type MapHandle[T, U any] struct {
+	fn     func(context.Context, T) (U, error)
+	getter Handle[T]
+	out    U
+	once   *sync.Once
+}
+
+func (sh *MapHandle[T, U]) Get(ctx context.Context) U {
+	sh.once.Do(func() {
+		t, err := sh.fn(ctx, sh.getter.Get(ctx))
+		if err != nil {
+			panic(err)
+		}
+		sh.out = t
+	})
+	return sh.out
+}
+
+// Map an FTL resource type to a new type.
+func Map[T, U any](getter Handle[T], fn func(context.Context, T) (U, error)) MapHandle[T, U] {
+	return MapHandle[T, U]{fn: fn, getter: getter, once: &sync.Once{}}
+}

go-runtime/ftl/map_test.go

@@ -0,0 +1,39 @@
+package ftl
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/alecthomas/assert/v2"
+)
+
+type intHandle int
+
+func (s intHandle) Get(ctx context.Context) int { return int(s) }
+
+func TestMapBaseCase(t *testing.T) {
+	incrementer := 0
+
+	h := intHandle(123)
+	ctx := context.Background()
+	once := Map(h, func(ctx context.Context, n int) (string, error) {
+		incrementer++
+		return fmt.Sprintf("handle: %d", n), nil
+	})
+
+	assert.Equal(t, once.Get(ctx), "handle: 123")
+	assert.Equal(t, once.Get(ctx), "handle: 123")
+	assert.Equal(t, incrementer, 1)
+}
+
+func TestMapPanic(t *testing.T) {
+	ctx := context.Background()
+	n := intHandle(1)
+	once := Map(n, func(ctx context.Context, n int) (string, error) {
+		return "", fmt.Errorf("test error %d", n)
+	})
+	assert.Panics(t, func() {
+		once.Get(ctx)
+	})
+}

go-runtime/ftl/types.go

@@ -8,6 +8,11 @@ import (
 	schemapb "github.com/TBD54566975/ftl/backend/protos/xyz/block/ftl/v1/schema"
 )
 
+// Handle represents a resource that can be retrieved such as a database connection, secret, etc.
+type Handle[T any] interface {
+	Get(ctx context.Context) T
+}
+
 // Unit is a type that has no value.
 //
 // It can be used as a parameter or return value to indicate that a function