Merge pull request #7 from Coder-Spirit/dependency-groups

Dependency groups

Author: castarco

README.md

@@ -82,13 +82,26 @@ const container = createContainer()
   .register('fn', func(printNameAndAge, 'someName', 'someAge'))
   // And constructors too
   .register('Person', constructor(Person, 'someAge', 'someName'))
+  // We can "define groups" by using `:` as an infix, the group's name will be
+  // the first part of the string before `:`.
+  // Groups can be used in all "register" methods.
+  .registerValue('group1:a', 1) // group == 'group1'
+  .registerValue('group1:b', 2)
+  .registerValue('group2:a', 3) // group == 'group2'
+  .registerValue('group2:b', 4)
 ​
+// We can resolve registered functions
 const print = container.resolve('fn')
 print() // Prints "Timmy is aged 5"
 
+// We can resolve registered constructors
 const person = container.resolve('Person')
 console.print(person.age) // Prints "5"
 console.print(person.name) // Prints "Timmy"
+
+// We can resolve registered "groups"
+container.resolveGroup('group1') // ~ [1, 2], not necessarily in the same order
+container.resolveGroup('group2') // ~ [3, 4], not necessarily in the same order
 ```
 
 It is also possible to register and resolve asynchronous factories and
@@ -103,6 +116,9 @@ If you are curious, just try out:
 
 - First-class support for Deno.
 - First-class support for asynchronous dependency resolution.
+- Stricter types for dependencies re-registration.
+- Groups registration and resolution: very useful when we need to resolve all
+  dependencies belonging to a same category.
 - The container interface has been split into `ReaderContainer` and
   `WriterContainer`, making it easier to use precise types.
 - More extense documentation.

lambda-ioc/README.md

@@ -58,17 +58,67 @@ import { ... } from 'https://deno.land/x/lambda_ioc@[VERSION]/lambda-ioc/deno/in
 ## Example
 
 ```ts
-import { createContainer } from '@coderspirit/lambda-ioc'
+import {
+  constructor,
+  createContainer,
+  func
+} from '@coderspirit/lambda-ioc'
 
 function printNameAndAge(name: string, age: number) {
   console.log(`${name} is aged ${age}`)
 }
+
+class Person {
+  constructor(
+    public readonly age: number,
+    public readonly name: string
+  ) {}
+}
 ​
 const container = createContainer()
-  .register('someAge', value(5))
-  .register('someName', value('Timmy'))
+  .registerValue('someAge', 5)
+  .registerValue('someName', 'Timmy')
+  // We can register functions
   .register('fn', func(printNameAndAge, 'someName', 'someAge'))
+  // And constructors too
+  .register('Person', constructor(Person, 'someAge', 'someName'))
+  // We can "define groups" by using `:` as an infix, the group's name will be
+  // the first part of the string before `:`.
+  // Groups can be used in all "register" methods.
+  .registerValue('group1:a', 1) // group == 'group1'
+  .registerValue('group1:b', 2)
+  .registerValue('group2:a', 3) // group == 'group2'
+  .registerValue('group2:b', 4)
 ​
+// We can resolve registered functions
 const print = container.resolve('fn')
 print() // Prints "Timmy is aged 5"
+
+// We can resolve registered constructors
+const person = container.resolve('Person')
+console.print(person.age) // Prints "5"
+console.print(person.name) // Prints "Timmy"
+
+// We can resolve registered "groups"
+container.resolveGroup('group1') // ~ [1, 2], not necessarily in the same order
+container.resolveGroup('group2') // ~ [3, 4], not necessarily in the same order
 ```
+
+It is also possible to register and resolve asynchronous factories and
+dependencies. They are not documented yet because some "helpers" are missing,
+and therefore it's a bit more annoying to take advantage of that feature.
+
+If you are curious, just try out:
+- `registerAsync`
+- `resolveAsync`
+
+## Differences respect to Diddly
+
+- First-class support for Deno.
+- First-class support for asynchronous dependency resolution.
+- Stricter types for dependencies re-registration.
+- Groups registration and resolution: very useful when we need to resolve all
+  dependencies belonging to a same category.
+- The container interface has been split into `ReaderContainer` and
+  `WriterContainer`, making it easier to use precise types.
+- More extense documentation.

lambda-ioc/deno/container.ts

@@ -2,10 +2,14 @@
 
 export type ContainerKey = string | symbol
 
-/**
- * Represents a dependency factory: a function that, given an IoC container, it
- * is able to instantiate a specific dependency.
- */
+type ExtractPrefix<S extends ContainerKey> =
+  S extends `${infer Prefix}:${string}` ? Prefix : never
+
+type ExtractPrefixedValues<
+  Prefix extends string,
+  Struct extends Record<ContainerKey, unknown>,
+  BaseKeys extends keyof Struct = keyof Struct,
+> = BaseKeys extends `${Prefix}:${infer U}` ? Struct[`${Prefix}:${U}`] : never
 
 export interface SyncDependencyFactory<
   T,
@@ -21,12 +25,13 @@ export interface AsyncDependencyFactory<
     Record<ContainerKey, unknown>
   >,
 > {
-  // It might seem counterintuitive that we allow T as return type, but the
-  // factory might also "become async" because of its dependencies, not just
-  // because of its return type.
   (container: TContainer): Promise<T>
 }
 
+/**
+ * Represents a dependency factory: a function that, given an IoC container, it
+ * is able to instantiate a specific dependency.
+ */
 export interface DependencyFactory<
   T,
   TContainer extends ReadableContainer<
@@ -63,6 +68,33 @@ export interface ReadableContainer<
   ): Promise<TAsyncDependencies[TName]>
 }
 
+export interface RedableGroupContainer<
+  TSyncDependencies extends Record<ContainerKey, unknown>,
+  TAsyncDependencies extends Record<ContainerKey, unknown>,
+> {
+  resolveGroup<
+    GroupName extends keyof TSyncDependencies extends ContainerKey
+      ? ExtractPrefix<keyof TSyncDependencies>
+      : never,
+  >(
+    groupName: GroupName,
+  ): keyof TSyncDependencies extends ContainerKey
+    ? ExtractPrefixedValues<GroupName, TSyncDependencies>[]
+    : never
+
+  resolveGroupAsync<
+    GroupName extends keyof TAsyncDependencies extends ContainerKey
+      ? ExtractPrefix<keyof TAsyncDependencies>
+      : never,
+  >(
+    groupName: GroupName,
+  ): Promise<
+    keyof TAsyncDependencies extends ContainerKey
+      ? ExtractPrefixedValues<GroupName, TAsyncDependencies>[]
+      : never
+  >
+}
+
 /**
  * Represents a write-only version of a type-safe IoC container with
  * "auto-wired" dependencies resolution.
@@ -173,6 +205,7 @@ export interface Container<
   TSyncDependencies extends Record<ContainerKey, unknown>,
   TAsyncDependencies extends Record<ContainerKey, unknown>,
 > extends ReadableContainer<TSyncDependencies, TAsyncDependencies>,
+    RedableGroupContainer<TSyncDependencies, TAsyncDependencies>,
     WritableContainer<TSyncDependencies, TAsyncDependencies> {}
 
 /**
@@ -365,5 +398,45 @@ function __createContainer<
         ] as AsyncDependencyFactory<TAsyncDependencies[TName], typeof this>
       )(this)
     },
+
+    resolveGroup<GroupName extends string>(
+      groupName: GroupName,
+    ): keyof TSyncDependencies extends ContainerKey
+      ? ExtractPrefixedValues<GroupName, TSyncDependencies>[]
+      : never {
+      return (
+        Object.entries(syncDependencies)
+          .filter(([key]) => {
+            return key.startsWith(`${groupName}:`)
+          })
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          .map(([_key, value]) => {
+            return value(this)
+          }) as keyof TSyncDependencies extends ContainerKey
+          ? ExtractPrefixedValues<GroupName, TSyncDependencies>[]
+          : never
+      )
+    },
+
+    async resolveGroupAsync<GroupName extends string>(
+      groupName: GroupName,
+    ): Promise<
+      keyof TAsyncDependencies extends ContainerKey
+        ? ExtractPrefixedValues<GroupName, TAsyncDependencies>[]
+        : never
+    > {
+      return (await Promise.all(
+        Object.entries(asyncDependencies)
+          .filter(([key]) => {
+            return key.startsWith(`${groupName}:`)
+          })
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          .map(([_key, value]) => {
+            return value(this)
+          }),
+      )) as keyof TAsyncDependencies extends ContainerKey
+        ? ExtractPrefixedValues<GroupName, TAsyncDependencies>[]
+        : never
+    },
   }
 }

lambda-ioc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderspirit/lambda-ioc",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/cjs/index.d.ts",

lambda-ioc/src/__tests__/container.test.ts

@@ -79,6 +79,46 @@ describe('container', () => {
     expect(await c1.resolveAsync('ab')).toBe(15)
     expect(await c2.resolveAsync('ab')).toBe(21)
   })
+
+  it('can register groups by relying on prefixes', () => {
+    const container = createContainer()
+      .register('a', () => 10)
+      .register('b', () => 20)
+      .register('g1:a', () => 30)
+      .register('g1:b', () => 40)
+      .register('g2:a', () => 50)
+      .register('g2:b', () => 60)
+
+    const g1 = container.resolveGroup('g1')
+    expect(g1).toHaveLength(2)
+    expect(g1).toContain(30)
+    expect(g1).toContain(40)
+
+    const g2 = container.resolveGroup('g2')
+    expect(g2).toHaveLength(2)
+    expect(g2).toContain(50)
+    expect(g2).toContain(60)
+  })
+
+  it('can register asynchronous groups by relying on prefixes', async () => {
+    const container = createContainer()
+      .register('a', () => 10)
+      .register('b', () => 20)
+      .registerAsync('g1:a', () => Promise.resolve(30))
+      .registerAsync('g1:b', () => Promise.resolve(40))
+      .registerAsync('g2:a', () => Promise.resolve(50))
+      .registerAsync('g2:b', () => Promise.resolve(60))
+
+    const g1 = await container.resolveGroupAsync('g1')
+    expect(g1).toHaveLength(2)
+    expect(g1).toContain(30)
+    expect(g1).toContain(40)
+
+    const g2 = await container.resolveGroupAsync('g2')
+    expect(g2).toHaveLength(2)
+    expect(g2).toContain(50)
+    expect(g2).toContain(60)
+  })
 })
 
 // Type tests
@@ -195,4 +235,68 @@ describe('@types/container', () => {
     const c_can_only_resolve_b: C_resolveAsync_Parameters_is_b = true
     expect(c_can_only_resolve_b).toBe(true)
   })
+
+  it('only resolves the sync registered groups', () => {
+    type C = Container<
+      {
+        a: number
+        b: number
+        'g1:a': number
+        'g1:b': string
+        'g2:a': string
+        'g2:b': boolean
+      },
+      {}
+    >
+
+    type C_resolveGroup_Parameters = Parameters<C['resolveGroup']>
+    type C_resolveGroup_Parameters_extends_g1g2 =
+      C_resolveGroup_Parameters extends ['g1' | 'g2'] ? true : false
+    type g1g2_extends_C_resolveGroup_Parameters = [
+      'g1' | 'g2',
+    ] extends C_resolveGroup_Parameters
+      ? true
+      : false
+    type C_resolveGroup_Parameters_is_g1g2 =
+      C_resolveGroup_Parameters_extends_g1g2 extends true
+        ? g1g2_extends_C_resolveGroup_Parameters extends true
+          ? true
+          : false
+        : false
+    const c_can_only_resolveGroup_g1g2: C_resolveGroup_Parameters_is_g1g2 = true
+    expect(c_can_only_resolveGroup_g1g2).toBe(true)
+  })
+
+  it('only resolves the async registered groups', () => {
+    type C = Container<
+      {
+        a: number
+        b: number
+      },
+      {
+        'g1:a': number
+        'g1:b': string
+        'g2:a': string
+        'g2:b': boolean
+      }
+    >
+
+    type C_resolveGroupAsync_Parameters = Parameters<C['resolveGroupAsync']>
+    type C_resolveGroupAsync_Parameters_extends_g1g2 =
+      C_resolveGroupAsync_Parameters extends ['g1' | 'g2'] ? true : false
+    type g1g2_extends_C_resolveGroupAsync_Parameters = [
+      'g1' | 'g2',
+    ] extends C_resolveGroupAsync_Parameters
+      ? true
+      : false
+    type C_resolveGroupAsync_Parameters_is_g1g2 =
+      C_resolveGroupAsync_Parameters_extends_g1g2 extends true
+        ? g1g2_extends_C_resolveGroupAsync_Parameters extends true
+          ? true
+          : false
+        : false
+    const c_can_only_resolveGroupAsync_g1g2: C_resolveGroupAsync_Parameters_is_g1g2 =
+      true
+    expect(c_can_only_resolveGroupAsync_g1g2).toBe(true)
+  })
 })