Add containerKeyValues function (#31)

Author: mgdigital

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [0.2.2]
+
+- Add `containerKeyValues` function
+
 ## [0.2.1]
 
 - Change behaviour of `IContainerBuilder.define` so that already-defined services are not overwritten

README.md

@@ -173,38 +173,73 @@ const myCustomLoggingModule: ContainerModule<
   )
 ```
 
-We can also use decorators to achieve features that aren't explicitly implemented in this library, such as service tagging, which we can do by defining a service as an array:
+We can also use decorators to achieve features that aren't explicitly implemented in this library, such as service tagging, which we can do by defining a service as a key-value object (actually, a simple array might do for some cases but using key-values prevents accidental duplicates if modules are reused):
 
 ```typescript
-import type { ContainerModule } from '@mgdigital/tsinject'
+import type { ContainerKey, ContainerModule } from '@mgdigital/tsinject'
+import { containerKeyValues } from '@mgdigital/tsinject'
+
+// Assume a type of service that we wish to tag, along with a sevice that depends on the tagged services.
 
-type TaggedServiceType = { foo: string }
+class TaggedService {}
+
+class TaggedServiceConsumer {
+  constructor (
+    public readonly taggedServices: TaggedService[]
+  ) {}
+}
 
 const serviceTag = Symbol('serviceTag')
+const taggedServiceConsumer = Symbol('taggedServiceConsumer')
 
-type ServiceMap = {
-  [serviceTag]: TaggedServiceType[]
+type ParentModuleServiceMap = {
+  // `TaggedServiceConsumer` depends on an array, but using an object here prevents accidental duplicates.
+  [serviceTag]: Record<ContainerKey, TaggedService>
+  [taggedServiceConsumer]: TaggedServiceConsumer
 }
 
-const myModule: ContainerModule<
-  ServiceMap
+const parentModule: ContainerModule<
+  ParentModuleServiceMap
 > = builder => builder
+  // Define an empty object of tagged services
   .define(
     serviceTag,
-    () => []
+    () => ({})
   )
+  .define(
+    taggedServiceConsumer,
+    container => new TaggedServiceConsumer(
+      // This utility method converts the tagged service object to an array
+      containerKeyValues(
+        container.get(serviceTag)
+      )
+    )
+  )
+
+// Then define child modules that will provide tagged services
 
-const myOtherModule: ContainerModule<
-  ServiceMap
+const taggedService = Symbol('taggedService')
+
+type ChildModuleServiceMap = {
+  [taggedService]: TaggedService
+}
+
+const childModule: ContainerModule<
+  ParentModuleServiceMap &
+  ChildModuleServiceMap
 > = builder => builder
-  .use(myModule)
+  .use(parentModule)
+  .define(
+    taggedService,
+    () => new TaggedService()
+  )
   .decorate(
     serviceTag,
     // Add a service to the array of already tagged services
-    factory => container => [
+    factory => container => ({
       ...factory(container),
-      { foo: 'bar' }
-    ]
+      [taggedService]: container.get(taggedService)
+    })
   )
 ```