docs: add exception documentation

Also publish InstantiationException in Monguito API.

src/index.ts

@@ -7,6 +7,7 @@ import { DomainModel } from './util/domain-model';
 import { Entity } from './util/entity';
 import {
   IllegalArgumentException,
+  InstantiationException,
   UndefinedConstructorException,
   ValidationException,
 } from './util/exceptions';
@@ -43,6 +44,7 @@ export {
   FindByIdOptions,
   FindOneOptions,
   IllegalArgumentException,
+  InstantiationException,
   isAuditable,
   MongooseRepository,
   MongooseTransactionalRepository,

src/mongoose.repository.ts

@@ -143,6 +143,9 @@ export abstract class MongooseRepository<T extends Entity & UpdateQuery<T>>
    * @param {SaveOptions} options (optional) insert operation options.
    * @returns {Promise<S>} the inserted entity.
    * @throws {IllegalArgumentException} if the given entity is `undefined` or `null`.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
+   * @throws {ValidationException} if the given entity specifies a field with some invalid value.
    */
   protected async insert<S extends T>(
     entity: S,
@@ -211,6 +214,9 @@ export abstract class MongooseRepository<T extends Entity & UpdateQuery<T>>
    * @param {SaveOptions} options (optional) update operation options.
    * @returns {Promise<S>} the updated entity.
    * @throws {IllegalArgumentException} if the given entity is `undefined` or `null` or specifies an `id` not matching any existing entity.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
+   * @throws {ValidationException} if the given entity specifies a field with some invalid value.
    */
   protected async update<S extends T>(
     entity: PartialEntityWithId<S>,
@@ -267,7 +273,8 @@ export abstract class MongooseRepository<T extends Entity & UpdateQuery<T>>
    * Instantiates a persistable domain object from the given Mongoose Document.
    * @param {HydratedDocument<S> | null} document the given Mongoose Document.
    * @returns {S | null} the resulting persistable domain object instance.
-   * @throws {UndefinedConstructorException} if there is no constructor available.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
    */
   protected instantiateFrom<S extends T>(
     document: HydratedDocument<S> | null,

src/repository.ts

@@ -27,6 +27,8 @@ export interface Repository<T extends Entity> {
    * @param {FindByIdOptions} options (optional) search operation options.
    * @returns {Promise<Optional<S>>} the entity or `null`.
    * @throws {IllegalArgumentException} if the given `id` is `undefined` or `null`.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
    * @see {@link FindByIdOptions}
    */
   findById: <S extends T>(
@@ -39,6 +41,8 @@ export interface Repository<T extends Entity> {
    * @param {FindOneOptions} options (optional) search operation options.
    * @returns {Promise<Optional<S>>} the entity or `null`. If no `option.filters` is specified,
    * an arbitrary entity is returned.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
    * @see {@link FindOneOptions}
    */
   findOne: <S extends T>(options?: FindOneOptions<S>) => Promise<Optional<S>>;
@@ -48,6 +52,8 @@ export interface Repository<T extends Entity> {
    * @param {FindAllOptions} options (optional) search operation options.
    * @returns {Promise<S[]>} all entities.
    * @throws {IllegalArgumentException} if the given `options` specifies an invalid parameter.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
    * @see {@link FindAllOptions}
    */
   findAll: <S extends T>(options?: FindAllOptions<S>) => Promise<S[]>;
@@ -59,6 +65,8 @@ export interface Repository<T extends Entity> {
    * @returns {Promise<S>} the saved entity.
    * @throws {IllegalArgumentException} if the given entity is `undefined` or `null` or
    * (when update) specifies an `id` not matching any existing entity.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
    * @throws {ValidationException} if the given entity specifies a field with some invalid value.
    * @see {@link SaveOptions}
    */

src/transactional-repository.ts

@@ -14,6 +14,8 @@ export interface TransactionalRepository<T extends Entity>
    * @returns {Promise<S[]>} the list of saved entities.
    * @throws {IllegalArgumentException} if any of the given entities is `undefined` or `null` or
    * (when update) specifies an `id` not matching any existing entity.
+   * @throws {InstantiationException} if the entity constructor throws an exception.
+   * @throws {UndefinedConstructorException} if there is no available entity constructor.
    * @throws {ValidationException} if any of the given entities specifies a field with some invalid value.
    * @see {@link SaveAllOptions}
    */