docs: registry

internal/registry/conversion.go

@@ -6,19 +6,29 @@ import (
 	"git.maximhutz.com/max/lambda/pkg/codec"
 )
 
+// A Conversion is a type-erased transformation from one representation to
+// another. It operates on Expr values, hiding the underlying representation
+// types.
 type Conversion interface {
+	// InType returns the name of the source representation.
 	InType() string
+	// OutType returns the name of the target representation.
 	OutType() string
 
+	// Run applies the conversion to the given expression. Returns an error if
+	// the expression's data does not match the expected source type.
 	Run(Expr) (Expr, error)
 }
 
-type convertedConversion[T, U any] struct {
+// A registeredConversion adapts a typed codec.Conversion[T, U] into the
+// type-erased Conversion interface. It extracts the underlying T from an Expr,
+// applies the conversion, and wraps the result as a new Expr.
+type registeredConversion[T, U any] struct {
 	conversion      codec.Conversion[T, U]
 	inType, outType string
 }
 
-func (c convertedConversion[T, U]) Run(expr Expr) (Expr, error) {
+func (c registeredConversion[T, U]) Run(expr Expr) (Expr, error) {
 	t, ok := expr.Data().(T)
 	if !ok {
 		return nil, fmt.Errorf("could not parse '%v' as '%s'", t, c.inType)
@@ -32,12 +42,18 @@ func (c convertedConversion[T, U]) Run(expr Expr) (Expr, error) {
 	return NewExpr(c.outType, u), nil
 }
 
-func (c convertedConversion[T, U]) InType() string { return c.inType }
+func (c registeredConversion[T, U]) InType() string { return c.inType }
 
-func (c convertedConversion[T, U]) OutType() string { return c.outType }
+func (c registeredConversion[T, U]) OutType() string { return c.outType }
 
-func RegisterConversion[T, U any](registry *Registry, conversion func(T) (U, error), inType, outType string) error {
-	registry.converter.Add(convertedConversion[T, U]{conversion, inType, outType})
+// RegisterConversion registers a typed conversion function between two
+// representations.
+func RegisterConversion[T, U any](
+	registry *Registry,
+	conversion codec.Conversion[T, U],
+	inType, outType string,
+) error {
+	registry.converter.Add(registeredConversion[T, U]{conversion, inType, outType})
 
 	return nil
 }