feat: export relevant "symbols" through index

Author: castarco

lambda-ioc/deno/combinators.ts

@@ -2,7 +2,8 @@ import { Container, ContainerKey, DependencyFactory } from './container.ts';
 import { ParamsToResolverKeys, TupleO, Zip } from './util.ts';
 
 /**
- *
+ * Given a dependency factory, returns a new factory that will always resolve
+ * the same instance of the dependency.
  */
 export function singleton<
   TVal,
@@ -20,14 +21,11 @@ export function singleton<
   }
 }
 
-type FuncContainer<
-  TParams extends readonly unknown[],
-  TDependencies extends ParamsToResolverKeys<TParams>,
-> = Container<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TupleO<Extract<Zip<TDependencies, TParams>, readonly [ContainerKey, any][]>>
->
-
+/**
+ * Given a function, and a list of named dependencies, creates a new dependency
+ * factory that will resolve a parameterless function wrapping the original
+ * function and its resolved dependencies.
+ */
 export function func<
   TParams extends readonly unknown[],
   TReturn,
@@ -51,6 +49,10 @@ export function func<
   }
 }
 
+/**
+ * Given a class constructor, and a list of named dependencies, creates a new
+ * dependency factory that will resolve a new instance of the class.
+ */
 export function constructor<
   TParams extends readonly unknown[],
   TClass,
@@ -73,3 +75,14 @@ export function constructor<
     return new constructor(...resolvedArgs)
   }
 }
+
+// -----------------------------------------------------------------------------
+// Private Types
+// -----------------------------------------------------------------------------
+type FuncContainer<
+  TParams extends readonly unknown[],
+  TDependencies extends ParamsToResolverKeys<TParams>,
+> = Container<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TupleO<Extract<Zip<TDependencies, TParams>, readonly [ContainerKey, any][]>>
+>

lambda-ioc/deno/container.ts

@@ -3,28 +3,50 @@
 export type ContainerKey = string | symbol
 
 /**
- *
+ * Represents a dependency factory: a function that, given an IoC container, it
+ * is able to instantiate a specific dependency.
  */
 export type DependencyFactory<
   T,
-  TContainer extends Container<Record<ContainerKey, unknown>>,
+  TContainer extends ReadableContainer<Record<ContainerKey, unknown>>,
 > = (container: TContainer) => T | Promise<T>
 
 /**
- *
+ * Represents a read-only version of a type-safe IoC container with "auto-wired"
+ * dependencies resolution.
  */
-export interface Container<
+export interface ReadableContainer<
   TDependencies extends Record<ContainerKey, unknown>,
 > {
   /**
-   * Register a new dependency.
+   * Resolve a dependency from the container.
+   *
+   * @param name The "name" of the dependency (can be a symbol).
+   */
+  resolve<TName extends keyof TDependencies>(
+    name: TName,
+  ): Promise<TDependencies[TName]>
+}
+
+/**
+ * Represents a write-only version of a type-safe IoC container with
+ * "auto-wired" dependencies resolution.
+ */
+export interface WritableContainer<
+  TDependencies extends Record<ContainerKey, unknown>,
+> {
+  /**
+   * Register a new dependency factory.
    *
    * @param name The "name" of the dependency (can be a symbol).
    * @param dependency A dependency factory.
    */
   register<TName extends ContainerKey, TDependency>(
     name: TName,
-    dependency: DependencyFactory<TDependency, Container<TDependencies>>,
+    dependency: DependencyFactory<
+      TDependency,
+      ReadableContainer<TDependencies>
+    >,
   ): Container<{
     [TK in keyof TDependencies | TName]: TK extends keyof TDependencies
       ? TName extends TK
@@ -33,6 +55,12 @@ export interface Container<
       : TDependency
   }>
 
+  /**
+   * Register an already instantiated dependency.
+   *
+   * @param name The "name" of the dependency (can be a symbol).
+   * @param dependency An already instantiated value.
+   */
   registerValue<TName extends ContainerKey, TDependency>(
     name: TName,
     dependency: TDependency,
@@ -43,19 +71,18 @@ export interface Container<
         : TDependencies[TK]
       : TDependency
   }>
-
-  /**
-   * Resolve a dependency from the container.
-   *
-   * @param name The "name" of the dependency (can be a symbol).
-   */
-  resolve<TName extends keyof TDependencies>(
-    name: TName,
-  ): Promise<TDependencies[TName]>
 }
 
 /**
- *
+ * Represents a type-safe IoC container with "auto-wired" dependencies
+ * resolution
+ */
+export interface Container<TDependencies extends Record<ContainerKey, unknown>>
+  extends ReadableContainer<TDependencies>,
+    WritableContainer<TDependencies> {}
+
+/**
+ * Creates a new type-safe IoC container.
  */
 export function createContainer(): Container<{}> {
   return __createContainer({})

lambda-ioc/deno/index.ts

@@ -0,0 +1,8 @@
+export {
+  type Container,
+  type DependencyFactory,
+  type ReadableContainer,
+  type WritableContainer,
+  createContainer,
+} from './container.ts';
+export { constructor, func, singleton } from './combinators.ts';

lambda-ioc/src/combinators.ts

@@ -2,7 +2,8 @@ import { Container, ContainerKey, DependencyFactory } from './container'
 import { ParamsToResolverKeys, TupleO, Zip } from './util'
 
 /**
- *
+ * Given a dependency factory, returns a new factory that will always resolve
+ * the same instance of the dependency.
  */
 export function singleton<
   TVal,
@@ -20,14 +21,11 @@ export function singleton<
   }
 }
 
-type FuncContainer<
-  TParams extends readonly unknown[],
-  TDependencies extends ParamsToResolverKeys<TParams>,
-> = Container<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  TupleO<Extract<Zip<TDependencies, TParams>, readonly [ContainerKey, any][]>>
->
-
+/**
+ * Given a function, and a list of named dependencies, creates a new dependency
+ * factory that will resolve a parameterless function wrapping the original
+ * function and its resolved dependencies.
+ */
 export function func<
   TParams extends readonly unknown[],
   TReturn,
@@ -51,6 +49,10 @@ export function func<
   }
 }
 
+/**
+ * Given a class constructor, and a list of named dependencies, creates a new
+ * dependency factory that will resolve a new instance of the class.
+ */
 export function constructor<
   TParams extends readonly unknown[],
   TClass,
@@ -73,3 +75,14 @@ export function constructor<
     return new constructor(...resolvedArgs)
   }
 }
+
+// -----------------------------------------------------------------------------
+// Private Types
+// -----------------------------------------------------------------------------
+type FuncContainer<
+  TParams extends readonly unknown[],
+  TDependencies extends ParamsToResolverKeys<TParams>,
+> = Container<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TupleO<Extract<Zip<TDependencies, TParams>, readonly [ContainerKey, any][]>>
+>

lambda-ioc/src/container.ts

@@ -3,28 +3,50 @@
 export type ContainerKey = string | symbol
 
 /**
- *
+ * Represents a dependency factory: a function that, given an IoC container, it
+ * is able to instantiate a specific dependency.
  */
 export type DependencyFactory<
   T,
-  TContainer extends Container<Record<ContainerKey, unknown>>,
+  TContainer extends ReadableContainer<Record<ContainerKey, unknown>>,
 > = (container: TContainer) => T | Promise<T>
 
 /**
- *
+ * Represents a read-only version of a type-safe IoC container with "auto-wired"
+ * dependencies resolution.
  */
-export interface Container<
+export interface ReadableContainer<
   TDependencies extends Record<ContainerKey, unknown>,
 > {
   /**
-   * Register a new dependency.
+   * Resolve a dependency from the container.
+   *
+   * @param name The "name" of the dependency (can be a symbol).
+   */
+  resolve<TName extends keyof TDependencies>(
+    name: TName,
+  ): Promise<TDependencies[TName]>
+}
+
+/**
+ * Represents a write-only version of a type-safe IoC container with
+ * "auto-wired" dependencies resolution.
+ */
+export interface WritableContainer<
+  TDependencies extends Record<ContainerKey, unknown>,
+> {
+  /**
+   * Register a new dependency factory.
    *
    * @param name The "name" of the dependency (can be a symbol).
    * @param dependency A dependency factory.
    */
   register<TName extends ContainerKey, TDependency>(
     name: TName,
-    dependency: DependencyFactory<TDependency, Container<TDependencies>>,
+    dependency: DependencyFactory<
+      TDependency,
+      ReadableContainer<TDependencies>
+    >,
   ): Container<{
     [TK in keyof TDependencies | TName]: TK extends keyof TDependencies
       ? TName extends TK
@@ -33,6 +55,12 @@ export interface Container<
       : TDependency
   }>
 
+  /**
+   * Register an already instantiated dependency.
+   *
+   * @param name The "name" of the dependency (can be a symbol).
+   * @param dependency An already instantiated value.
+   */
   registerValue<TName extends ContainerKey, TDependency>(
     name: TName,
     dependency: TDependency,
@@ -43,19 +71,18 @@ export interface Container<
         : TDependencies[TK]
       : TDependency
   }>
-
-  /**
-   * Resolve a dependency from the container.
-   *
-   * @param name The "name" of the dependency (can be a symbol).
-   */
-  resolve<TName extends keyof TDependencies>(
-    name: TName,
-  ): Promise<TDependencies[TName]>
 }
 
 /**
- *
+ * Represents a type-safe IoC container with "auto-wired" dependencies
+ * resolution
+ */
+export interface Container<TDependencies extends Record<ContainerKey, unknown>>
+  extends ReadableContainer<TDependencies>,
+    WritableContainer<TDependencies> {}
+
+/**
+ * Creates a new type-safe IoC container.
  */
 export function createContainer(): Container<{}> {
   return __createContainer({})

lambda-ioc/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  type Container,
+  type DependencyFactory,
+  type ReadableContainer,
+  type WritableContainer,
+  createContainer,
+} from './container'
+export { constructor, func, singleton } from './combinators'