From 12f42a0ff95b04d7172e97c33fa3309ac78cc622 Mon Sep 17 00:00:00 2001
From: Steven Ontong <steven@journeyapps.com>
Date: Thu, 18 Jul 2024 10:10:18 +0200
Subject: [PATCH] added comments

---
 libs/lib-services/src/container.ts | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/libs/lib-services/src/container.ts b/libs/lib-services/src/container.ts
index 66d23cb..4e01528 100644
--- a/libs/lib-services/src/container.ts
+++ b/libs/lib-services/src/container.ts
@@ -23,10 +23,20 @@ export type ContainerImplementationDefaultGenerators = {
   [type in ContainerImplementation]: () => ContainerImplementationTypes[type];
 };
 
+/**
+ * Helper for identifying constructors
+ */
 export interface Abstract<T> {
   prototype: T;
 }
+/**
+ * A basic class constructor
+ */
 export type Newable<T> = new (...args: never[]) => T;
+
+/**
+ * Identifier used to get and register implementations
+ */
 export type ServiceIdentifier<T = unknown> = string | symbol | Newable<T> | Abstract<T> | ContainerImplementation;
 
 const DEFAULT_GENERATORS: ContainerImplementationDefaultGenerators = {
@@ -35,6 +45,10 @@ const DEFAULT_GENERATORS: ContainerImplementationDefaultGenerators = {
   [ContainerImplementation.TERMINATION_HANDLER]: () => createTerminationHandler()
 };
 
+/**
+ * A container which provides means for registering and getting various
+ * function implementations.
+ */
 export class Container {
   protected implementations: Map<ServiceIdentifier<any>, any>;
 
@@ -63,6 +77,12 @@ export class Container {
     this.implementations = new Map();
   }
 
+  /**
+   * Gets an implementation given an identifier.
+   * An exception is thrown if the implementation has not been registered.
+   * Core [ContainerImplementation] identifiers are mapped to their respective implementation types.
+   * This also allows for getting generic implementations (unknown to the core framework) which have been registered.
+   */
   getImplementation<T>(identifier: Newable<T> | Abstract<T>): T;
   getImplementation<T extends ContainerImplementation>(identifier: T): ContainerImplementationTypes[T];
   getImplementation<T>(identifier: ServiceIdentifier<T>): T;
@@ -74,6 +94,12 @@ export class Container {
     return implementation;
   }
 
+  /**
+   * Gets an implementation given an identifier.
+   * Null is returned if the implementation has not been registered yet.
+   * Core [ContainerImplementation] identifiers are mapped to their respective implementation types.
+   * This also allows for getting generic implementations (unknown to the core framework) which have been registered.
+   */
   getOptional<T>(identifier: Newable<T> | Abstract<T>): T | null;
   getOptional<T extends ContainerImplementation>(identifier: T): ContainerImplementationTypes[T] | null;
   getOptional<T>(identifier: ServiceIdentifier<T>): T | null;
@@ -96,7 +122,7 @@ export class Container {
   }
 
   /**
-   * Allows for overriding a default implementation
+   * Allows for registering core and generic implementations of services/helpers.
    */
   register<T>(identifier: ServiceIdentifier<T>, implementation: T) {
     this.implementations.set(identifier, implementation);