docs: add code comments to commonly used types and decorators (#183)

Author: AlexBksiad

src/mikro-orm.common.ts

@@ -6,14 +6,49 @@ export const MIKRO_ORM_MODULE_OPTIONS = Symbol('mikro-orm-module-options');
 export const CONTEXT_NAMES: string[] = [];
 export const logger = new Logger(MikroORM.name);
 
+/**
+ * Gets the injection token based on context name for the relevant MikroORM provider.
+ * @param name The context name of the database connection.
+ * @returns The MikroORM provider injection token for the supplied context name.
+ */
 export const getMikroORMToken = (name: string) => `${name}_MikroORM`;
+/**
+ * Injects a MikroORM provider based on the supplied context name.
+ *
+ * @param name The context name of the database connection.
+ * @returns A parameter decorator which will cause NestJS to inject the relevant MikroORM provider.
+ */
 export const InjectMikroORM = (name: string) => Inject(getMikroORMToken(name));
 
+/**
+ * Gets the injection token based on context name for the relevant EntityManager provider.
+ * @param name The context name of the database connection.
+ * @returns The EntityManager provider injection token for the supplied context name.
+ */
 export const getEntityManagerToken = (name: string) => `${name}_EntityManager`;
+/**
+ * Injects an EntityManager provider based on the supplied context name.
+ *
+ * @param name The context name of the database connection.
+ * @returns A parameter decorator which will cause NestJS to inject the relevant EntityManager provider.
+ */
 export const InjectEntityManager = (name: string) => Inject(getEntityManagerToken(name));
 
+/**
+ * Gets the injection token based on class and optionally based on context name.
+ * @param entity The class of the Entity to use for the injected repository provider.
+ * @param name An optional context name - required for multiple database connections. See: [Multiple Database Connections](https://mikro-orm.io/docs/usage-with-nestjs#multiple-database-connections)
+ * @returns The EntityRepository provider injection token based on the supplied entity and context name.
+ */
 export const getRepositoryToken = <T extends object> (entity: EntityName<T>, name?: string) => {
   const suffix = name ? `_${name}` : '';
   return `${Utils.className(entity)}Repository${suffix}`;
 };
+/**
+ * Injects an EntityRepository provider.
+ *
+ * @param entity The class of the Entity to use for the injected repository provider.
+ * @param name An optional context name - required for multiple database connections. See: [Multiple Database Connections](https://mikro-orm.io/docs/usage-with-nestjs#multiple-database-connections)
+ * @returns A parameter decorator which will cause NestJS to inject the relevant EntityRepository provider.
+ */
 export const InjectRepository = <T extends object> (entity: EntityName<T>, name?: string) => Inject(getRepositoryToken(entity, name));

src/typings.ts

@@ -7,6 +7,13 @@ export interface NestMiddlewareConsumer extends MiddlewareConsumer {
 }
 
 type MikroOrmNestScopeOptions = {
+  /**
+   * The NestJS provider scope to use for the EntityManager (and any subsequent downstream records).
+   *
+   * This scope will also impact the scope of Entity Repositories as they depend on the EntityManager.
+   *
+   * @see [NestJS Scope Hierarchy](https://docs.nestjs.com/fundamentals/injection-scopes#scope-hierarchy)
+   */
   scope?: Scope;
 };
 
@@ -23,11 +30,28 @@ export type MikroOrmMiddlewareModuleOptions = {
 
 export type MikroOrmModuleOptions<D extends IDatabaseDriver = IDatabaseDriver> = {
   registerRequestContext?: boolean;
+  /**
+   * Specifies whether or not to automatically load the entities based on MikroOrmModule.forFeature invocations.
+   *
+   * @see [MikroOrm - NestJS - Load Entities Automatically](https://mikro-orm.io/docs/usage-with-nestjs#load-entities-automatically)
+   *
+   * @default false
+   */
   autoLoadEntities?: boolean;
 } & Options<D> & MikroOrmMiddlewareModuleOptions;
 
 export interface MikroOrmModuleFeatureOptions {
+  /**
+   * The entities to provide an EntityRepository for.
+   *
+   * @see [MikroOrm - NestJS - Repositories](https://mikro-orm.io/docs/usage-with-nestjs#repositories)
+   */
   entities?: EntityName<AnyEntity>[];
+  /**
+   * The context (database connection) to use for the entity repository.
+   *
+   * @see [MikroOrm - NestJS - Multiple Database Connections](https://mikro-orm.io/docs/usage-with-nestjs#multiple-database-connections)
+   */
   contextName?: string;
 }
 
@@ -38,6 +62,13 @@ export interface MikroOrmOptionsFactory<D extends IDatabaseDriver = IDatabaseDri
 export interface MikroOrmModuleSyncOptions extends MikroOrmModuleOptions, MikroOrmNestScopeOptions { }
 
 export interface MikroOrmModuleAsyncOptions<D extends IDatabaseDriver = IDatabaseDriver> extends Pick<ModuleMetadata, 'imports' | 'providers'>, MikroOrmNestScopeOptions {
+  /**
+   * The context name (database connection) to specify for this instance.
+   *
+   * When injecting repositories or entity manager instances, this context name will need to be specified where there are multiple datbaase connections.
+   *
+   * @see [MikroOrm - NestJS - Multiple Database Connections](https://mikro-orm.io/docs/usage-with-nestjs#multiple-database-connections)
+   */
   contextName?: string;
   useExisting?: Type<MikroOrmOptionsFactory<D>>;
   useClass?: Type<MikroOrmOptionsFactory<D>>;