Merge pull request #246 from Josuto/update_api_and_docs

Update API and docs

README.md

@@ -161,10 +161,7 @@ This value wraps an actual entity or `null` in case that no entity matches the g
 
 ### `findOne`
 
-Returns an [`Optional`](https://github.com/bromne/typescript-optional#readme) entity matching the given `filters` parameter values. In case there are more than one matching entities, `findOne` returns the first entity satisfying the condition. The result value wraps an actual entity or `null` in case that no entity matches the given conditions.
-
-> [!WARNING]
-> Since v5.0.1 the `filters` parameter is now deprecated. Use the new behavioural `options.filters` option instead.
+Returns an [`Optional`](https://github.com/bromne/typescript-optional#readme) entity matching the given `filters` parameter value. If no value is provided, then an arbitrary stored (if any) entity is returned. In case there are more than one matching entities, `findOne` returns the first entity satisfying the condition. The result value wraps an actual entity or `null` if no entity matches the given conditions.
 
 ### `findAll`
 

src/index.ts

@@ -3,7 +3,7 @@ import { MongooseTransactionalRepository } from './mongoose.transactional-reposi
 import { PartialEntityWithId, Repository } from './repository';
 import { TransactionalRepository } from './transactional-repository';
 import { Auditable, AuditableClass, isAuditable } from './util/audit';
-import { DomainModel, DomainTree } from './util/domain-model';
+import { DomainModel } from './util/domain-model';
 import { Entity } from './util/entity';
 import {
   IllegalArgumentException,
@@ -18,6 +18,7 @@ import {
   FindOneOptions,
   SaveAllOptions,
   SaveOptions,
+  SortOrder,
 } from './util/operation-options';
 import {
   AuditableSchema,
@@ -36,7 +37,6 @@ export {
   DeleteAllOptions,
   DeleteByIdOptions,
   DomainModel,
-  DomainTree,
   Entity,
   extendSchema,
   FindAllOptions,
@@ -53,6 +53,7 @@ export {
   SaveOptions,
   SchemaOptions,
   SchemaPlugin,
+  SortOrder,
   TransactionalRepository,
   TransactionOptions,
   UndefinedConstructorException,

src/mongoose.repository.ts

@@ -35,7 +35,7 @@ export abstract class MongooseRepository<T extends Entity & UpdateQuery<T>>
   /**
    * Sets up the underlying configuration to enable database operation execution.
    * @param {DomainModel<T>} domainModel the domain model supported by this repository.
-   * @param {Connection=} connection (optional) a MongoDB instance connection.
+   * @param {Connection} connection (optional) a MongoDB instance connection.
    */
   protected constructor(
     domainModel: DomainModel<T>,
@@ -152,7 +152,7 @@ export abstract class MongooseRepository<T extends Entity & UpdateQuery<T>>
   /**
    * Inserts an entity.
    * @param {S} entity the entity to insert.
-   * @param {SaveOptions=} options (optional) insert operation options.
+   * @param {SaveOptions} options (optional) insert operation options.
    * @returns {Promise<S>} the inserted entity.
    * @throws {IllegalArgumentException} if the given entity is `undefined` or `null`.
    */
@@ -211,7 +211,7 @@ export abstract class MongooseRepository<T extends Entity & UpdateQuery<T>>
   /**
    * Updates an entity.
    * @param {S} entity the entity to update.
-   * @param {SaveOptions=} options (optional) update operation options.
+   * @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.
    */

src/mongoose.transactional-repository.ts

@@ -23,7 +23,7 @@ export abstract class MongooseTransactionalRepository<
   /**
    * Sets up the underlying configuration to enable database operation execution.
    * @param {DomainModel<T>} domainModel the domain model supported by this repository.
-   * @param {Connection=} connection (optional) a MongoDB instance connection.
+   * @param {Connection} connection (optional) a MongoDB instance connection.
    */
   protected constructor(domainModel: DomainModel<T>, connection?: Connection) {
     super(domainModel, connection);

src/repository.ts

@@ -24,8 +24,8 @@ export interface Repository<T extends Entity> {
   /**
    * Finds an entity by ID.
    * @param {string} id the ID of the entity.
-   * @param {FindByIdOptions=} options (optional) search operation options.
-   * @returns {Promise<Optional<S>>} the entity or null.
+   * @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`.
    */
   findById: <S extends T>(
@@ -35,15 +35,15 @@ export interface Repository<T extends Entity> {
 
   /**
    * Finds an entity by some filters.
-   * @param {FindOneOptions=} options (optional) search operation options.
-   * @returns {Promise<Optional<S>>} the entity or null.
+   * @param {FindOneOptions} options (optional) search operation options.
+   * @returns {Promise<Optional<S>>} the entity or `null`.
    * @throws {IllegalArgumentException} if the given `filters` parameter is `undefined` or `null`.
    */
   findOne: <S extends T>(options?: FindOneOptions<S>) => Promise<Optional<S>>;
 
   /**
    * Finds all entities.
-   * @param {FindAllOptions=} options (optional) search operation options.
+   * @param {FindAllOptions} options (optional) search operation options.
    * @returns {Promise<S[]>} all entities.
    * @throws {IllegalArgumentException} if the given `options` specifies an invalid parameter.
    */
@@ -52,7 +52,7 @@ export interface Repository<T extends Entity> {
   /**
    * Saves (insert or update) an entity.
    * @param {S | PartialEntityWithId<S>} entity the entity to save.
-   * @param {SaveOptions=} options (optional) save operation options.
+   * @param {SaveOptions} options (optional) save operation options.
    * @returns {Promise<S>} the saved entity.
    * @throws {IllegalArgumentException} if the given entity is `undefined` or `null` or
    * specifies an `id` not matching any existing entity.
@@ -66,7 +66,7 @@ export interface Repository<T extends Entity> {
   /**
    * Deletes an entity by ID.
    * @param {string} id the ID of the entity.
-   * @param {DeleteByIdOptions=} options (optional) delete operation options.
+   * @param {DeleteByIdOptions} options (optional) delete operation options.
    * @returns {Promise<boolean>} `true` if the entity was deleted, `false` otherwise.
    * @throws {IllegalArgumentException} if the given `id` is `undefined` or `null`.
    */

src/transactional-repository.ts

@@ -10,7 +10,7 @@ export interface TransactionalRepository<T extends Entity>
   /**
    * Saves (insert or update) a list of entities.
    * @param {S[] | PartialEntityWithId<S>[]} entities the list of entities to save.
-   * @param {SaveAllOptions=} options (optional) save operation options.
+   * @param {SaveAllOptions} options (optional) save operation options.
    * @returns {Promise<S[]>} the list of saved entities.
    * @throws {IllegalArgumentException} if any of the given entities is `undefined` or `null` or
    * specifies an `id` not matching any existing entity.
@@ -24,7 +24,7 @@ export interface TransactionalRepository<T extends Entity>
   /**
    * Deletes all the entities that match the given filter, if any. No filter specification will
    * result in the deletion of all entities.
-   * @param {DeleteAllOptions=} options (optional) delete operation options.
+   * @param {DeleteAllOptions} options (optional) delete operation options.
    * @returns {number} the number of deleted entities.
    * @see {@link DeleteAllOptions}
    */

src/util/audit.ts

@@ -1,5 +1,10 @@
 /**
  * Models an auditable persistable domain object.
+ * @property {Date} createdAt - the date and time when the entity was created.
+ * @property {string} createdBy - the user who created the entity.
+ * @property {Date} updatedAt - the date and time when the entity was last updated.
+ * @property {string} updatedBy - the user who last updated the entity.
+ * @property {number} version - the version of the entity.
  */
 export interface Auditable {
   createdAt?: Date;

src/util/exceptions.ts

@@ -14,7 +14,7 @@ export class IllegalArgumentException extends Exception {
   /**
    * Creates an `IllegalArgumentException`, optionally wrapping an error.
    * @param {string} message the message of the exception.
-   * @param {Error=} error (optional) the wrapped error.
+   * @param {Error} error (optional) the wrapped error.
    */
   constructor(message: string, error?: Error) {
     super(message, error);
@@ -28,7 +28,7 @@ export class UndefinedConstructorException extends Exception {
   /**
    * Creates an `UndefinedConstructorException`, optionally wrapping an error.
    * @param {string} message the message of the exception.
-   * @param {Error=} error (optional) the wrapped error.
+   * @param {Error} error (optional) the wrapped error.
    */
   constructor(message: string, error?: Error) {
     super(message, error);
@@ -42,7 +42,7 @@ export class ValidationException extends Exception {
   /**
    * Creates an `ValidationException`, optionally wrapping an error.
    * @param {string} message the message of the exception.
-   * @param {Error=} error (optional) the wrapped error.
+   * @param {Error} error (optional) the wrapped error.
    */
   constructor(message: string, error?: Error) {
     super(message, error);

src/util/operation-options.ts

@@ -4,25 +4,23 @@ import { TransactionOptions } from './transaction';
 
 /**
  * Specifies options required to perform audit on side effect operation execution.
- * @property {string=} userId (optional) the id of the user performing the operation.
+ * @property {string} userId (optional) - the id of the user performing the operation.
  */
-export type AuditOptions = {
+export interface AuditOptions {
   userId?: string;
-};
+}
 
 /**
  * Specifies paging configuration for search operations.
  */
 export class Pageable {
   /**
    * The page number to retrieve.
-   * @type {number}
    */
   readonly pageNumber: number;
 
   /**
    * The number of entities composing the result.
-   * @type {number}
    */
   readonly offset: number;
 
@@ -45,53 +43,66 @@ export class Pageable {
   }
 }
 
-export type SortOrder = {
+/**
+ * Specifies the sorting criteria for search operations. The allowed values are: 'asc', 'ascending', 'desc', 'descending', 1, -1.
+ */
+export interface SortOrder {
   [key: string]: 'asc' | 'desc' | 'ascending' | 'descending' | 1 | -1;
-};
+}
 
 /**
  * Specifies options for the `findAll` operation.
- * @property {FilterQuery=} filters (optional) some filters for the search.
- * @property {string | SortOrder=} sortBy (optional) the sorting criteria for the search.
- * @property {Pageable=} pageable (optional) paging configuration.
+ * @property {FilterQuery} filters (optional) - MongoDB search filters.
+ * @property {string|SortOrder} sortBy (optional) - the sorting criteria for the search.
+ * @property {Pageable} pageable (optional) - paging configuration.
+ * @see {@link TransactionOptions}
  */
-export type FindAllOptions<T> = {
+export interface FindAllOptions<T> extends TransactionOptions {
   filters?: FilterQuery<T>;
   sortBy?: string | SortOrder;
   pageable?: Pageable;
-} & TransactionOptions;
+}
 
 /**
  * Specifies options for the `findById` operation;
+ * @see {@link TransactionOptions}
  */
-export type FindByIdOptions = TransactionOptions;
+export interface FindByIdOptions extends TransactionOptions {}
 
 /**
  * Specifies options for the `findOne` operation;
+ * @property {FilterQuery} filters (optional) - MongoDB search filters.
+ * @see {@link TransactionOptions}
  */
-export type FindOneOptions<T> = {
+export interface FindOneOptions<T> extends TransactionOptions {
   filters?: FilterQuery<T>;
-} & TransactionOptions;
+}
 
 /**
  * Specifies options for the `save` operation.
+ * @see {@link AuditOptions}
+ * @see {@link TransactionOptions}
  */
-export type SaveOptions = AuditOptions & TransactionOptions;
+export interface SaveOptions extends AuditOptions, TransactionOptions {}
 
 /**
  * Specifies options for the `saveAll` operation.
+ * @see {@link AuditOptions}
+ * @see {@link TransactionOptions}
  */
-export type SaveAllOptions = AuditOptions & TransactionOptions;
+export interface SaveAllOptions extends AuditOptions, TransactionOptions {}
 
 /**
  * Specifies options for the `deleteAll` operation.
- * @property {FilterQuery=} filters (optional) a MongoDB query object to select the entities to be deleted.
+ * @property {FilterQuery} filters (optional) - MongoDB search filters.
+ * @see {@link TransactionOptions}
  */
-export type DeleteAllOptions<T> = {
+export interface DeleteAllOptions<T> extends TransactionOptions {
   filters?: FilterQuery<T>;
-} & TransactionOptions;
+}
 
 /**
- * Specifies options for the `deleteById` operation;
+ * Specifies options for the `deleteById` operation.
+ * @see {@link TransactionOptions}
  */
-export type DeleteByIdOptions = TransactionOptions;
+export interface DeleteByIdOptions extends TransactionOptions {}

src/util/schema.ts

@@ -77,7 +77,7 @@ export function extendSchema<T = object, S = object>(
  * Creates a new schema from the given data.
  * @param {Schema<T>} baseSchema the base schema.
  * @param {SchemaDefinition<S>} extension the schema definition to extend from.
- * @param {SchemaOptions=} options (optional) some schema options.
+ * @param {SchemaOptions} options (optional) some schema options.
  * @returns {Schema<T & S>} a new schema that integrates the contents of the given parameters.
  */
 export function extendSchema<T = object, S = object>(

src/util/transaction.ts

@@ -7,8 +7,7 @@ type DbCallback<T> = (session: ClientSession) => Promise<T>;
 
 /**
  * Specifies transaction options.
- * @property {Connection=} connection (optional) a MongoDB connection, required to create a new transaction session.
- * @property {ClientSession=} session (optional) a transaction session, required to run the operation within an existing transaction.
+ * @property {ClientSession} session (optional) - a transaction session, required to run the operation within an existing transaction.
  */
 export type TransactionOptions = {
   session?: ClientSession;
@@ -21,7 +20,7 @@ const MAX_RETRIES = 3;
  * iff it has run successfully.
  *
  * @param {DbCallback<T>} callback a callback function that writes to and reads from the database using a session.
- * @param {TransactionOptions=} options (optional) some options about the transaction.
+ * @param {TransactionOptions} options (optional) some options about the transaction.
  */
 export async function runInTransaction<T>(
   callback: DbCallback<T>,