Initial commit

libs/sl/sl.go

@@ -0,0 +1,166 @@
+// The [sl] package has two main concepts, the [ServiceLocator] itself is the
+// main object that one should pass around through the application. A
+// [ServiceLocator] has a list of slots that can be filled with
+// [InjectLazy] and [InjectValue] and retrieved with [Use]. Slots should
+// be unique by type and they can only be created with the [NewSlot] function.
+//
+// The usual way to use this module is to make slots for Go interfaces and
+// then pass implementations using the [InjectValue] and
+// [InjectLazy] functions.
+//
+// Services can be of various types:
+//   - a service with no dependencies can be directly injected inside a
+//     ServiceLocator using [InjectValue].
+//   - a service with dependencies on other service should use
+//     [InjectLazy]. This lets the service to initialize itself when needed
+//     and makes the developer not think about correctly ordering the
+//     initialization of its dependencies
+//   - a service can also be private, in this case the slot for a service
+//     should be a private field in the service package. This kind of
+//     services should also provide a way to inject them into a
+//     ServiceLocator.
+//   - a package can also just provide a slot with some value. This is useful
+//     for using the ServiceLocator to easily pass around values, effectively
+//     threating slots just as dynamically scoped variables.
+package sl
+
+import (
+	"fmt"
+	"log"
+	"os"
+)
+
+// Logger is the debug logger
+//
+// TODO: in the future this will be disabled and discard by default.
+//
+// As this is the service locator module it was meaning less to pass this
+// through the ServiceLocator itself (without making the whole module more
+// complex)
+var Logger *log.Logger = log.New(os.Stderr, "[service locator] ", log.Lmsgprefix)
+
+// slot is just a "typed" unique "symbol".
+type slot[T any] *struct{}
+
+// NewSlot is the only way to create instances of the slot type. Each instance
+// is unique.
+//
+// This then lets you attach a service instance of type "T" to a
+// [ServiceLocator] object.
+func NewSlot[T any]() slot[T] {
+	return slot[T](new(struct{}))
+}
+
+// slotEntry represents a service that can lazily initialized
+// (using "createFunc"). Once initialized the instance is kept in the "value"
+// field and "created" will always be "true". The field "typeName" just for
+// debugging purposes.
+type slotEntry struct {
+	typeName string
+
+	createFunc func(*ServiceLocator) (any, error)
+	created    bool
+
+	value any
+}
+
+func (s *slotEntry) checkInitialized(l *ServiceLocator) error {
+	if !s.created {
+		v, err := s.createFunc(l)
+		if err != nil {
+			return err
+		}
+
+		Logger.Printf(`[slot: %s] initialized value of type %T`, s.typeName, v)
+
+		s.created = true
+		s.value = v
+	}
+
+	return nil
+}
+
+// ServiceLocator is the main context passed around to retrive service
+// instances, the interface uses generics so to inject and retrive service
+// instances you should use the functions [InjectValue], [InjectLazy] and
+// [Use].
+type ServiceLocator struct {
+	providers map[any]*slotEntry
+}
+
+// New creates a new [ServiceLocator] context to pass around in the application.
+func New() *ServiceLocator {
+	return &ServiceLocator{
+		providers: map[any]*slotEntry{},
+	}
+}
+
+// InjectValue will inject a concrete instance inside the ServiceLocator "l"
+// for the given "slotKey". This should be used for injecting "static"
+// services, for instances whose construction depend on other services you
+// should use the [InjectLazy] function.
+//
+// This is generic over "T" to check that instances for the given slot type
+// check as "T" can also be an interface.
+func InjectValue[T any](l *ServiceLocator, slotKey slot[T], value T) T {
+	Logger.Printf(`[slot: %s] injected value of type %T`, getTypeName[T](), value)
+
+	l.providers[slotKey] = &slotEntry{
+		getTypeName[T](),
+		nil,
+		true,
+		value,
+	}
+	return value
+}
+
+// InjectLazy will inject an instance inside the given ServiceLocator
+// and "slotKey" that is created only when requested with a call to the
+// [Use] function.
+//
+// This is generic over "T" to check that instances for the given slot type
+// check as "T" can also be an interface.
+func InjectLazy[T any](l *ServiceLocator, slotKey slot[T], createFunc func(*ServiceLocator) (T, error)) {
+	Logger.Printf(`[slot: %s] injected lazy`, getTypeName[T]())
+
+	l.providers[slotKey] = &slotEntry{
+		createFunc: func(l *ServiceLocator) (any, error) {
+			return createFunc(l)
+		},
+		created:  false,
+		value:    nil,
+		typeName: getTypeName[T](),
+	}
+}
+
+// Use retrieves the value of type T associated with the given slot key from
+// the provided ServiceLocator instance.
+//
+// If the ServiceLocator does not have a value for the slot key, or if the
+// value wasn't correctly initialized (in the case of a lazy slot), an error
+// is returned.
+func Use[T any](l *ServiceLocator, slotKey slot[T]) (T, error) {
+	var zero T
+
+	slot, ok := l.providers[slotKey]
+	if !ok {
+		return zero, fmt.Errorf(`no injected value for type %s`, getTypeName[T]())
+	}
+
+	err := slot.checkInitialized(l)
+	if err != nil {
+		return zero, err
+	}
+
+	v := slot.value.(T)
+
+	Logger.Printf(`[slot: %s] using slot with value of type %T`, getTypeName[T](), v)
+	return v, nil
+}
+
+// getTypeName is a trick to get the name of a type (even if it is an
+// interface type)
+func getTypeName[T any]() string {
+	var zero T
+	return fmt.Sprintf(`%T`, &zero)[1:]
+}