monguito

Create custom MongoDB repositories fast and easily

Main Contents

• What is monguito?
• Getting Started
• Supported Database Operations
• Examples
• Write Your Own Repository Interfaces
• Extra Utilities
• Comparison to other Alternatives
• Contributors

What is monguito?

monguito is a lightweight and type-safe MongoDB handling library for Node.js applications that implements both the abstract repository and the polymorphic patterns.

It allows you (dear developer) to define any custom MongoDB repository in a fast, easy, and structured manner, releasing you from having to write all the boilerplate code for basic CRUD operations, and also decoupling your domain layer from the persistence logic. Moreover, despite its small size, it includes several optional features such as seamless audit data handling support.

Last but not least, monguito wraps Mongoose, a very popular and solid MongoDB ODM for Node.js applications. monguito enables you to use any Mongoose feature such as aggregation pipelines or middleware functions. Furthermore, it leverages Mongoose schemas to enable developers focus on their own persistance models, leaving everything else to the library.

Getting Started

Installation

You can install monguito with npm:

npm install monguito

Or yarn:

yarn add monguito

Usage

Creating your repository with custom database operations is very straight forward. Say you want to create a custom repository to handle database operations over instances of a Book and any of its subtypes (e.g., PaperBook and AudioBook). Here's the implementation of a custom repository that deals with persistable instances of Book:

class MongooseBookRepository extends MongooseRepository<Book> {
  constructor() {
    super({
      Default: { type: Book, schema: BookSchema },
      PaperBook: { type: PaperBook, schema: PaperBookSchema },
      AudioBook: { type: AudioBook, schema: AudioBookSchema },
    });
  }

  async findByIsbn<T extends Book>(isbn: string): Promise<Optional<T>> {
    if (!isbn)
      throw new IllegalArgumentException('The given ISBN must be valid');
    return this.entityModel
      .findOne({ isbn: isbn })
      .exec()
      .then((book) =>
        Optional.ofNullable(this.instantiateFrom(book) as unknown as T),
      );
  }
}

That's it! MongooseBookRepository is a custom repository that inherits a series of CRUD operations and adds its own e.g., findByIsbn. It extends MongooseRepository, a generic template that specifies several basic CRUD operations i.e., findById, findOne, findAll, save, and deleteById. Besides, you can use the protected entityModel defined at MongooseRepository to execute any Mongoose operation you wish, as it happens at the definition of findByIsbn.

Here is an example on how to create and use an instance of the custom MongooseBookRepository:

const bookRepository = new MongooseBookRepository();
const books: Book[] = bookRepository.findAll();

No more leaking of the persistence logic into your domain/application logic! 🤩

Polymorphic Domain Model Specification

MongooseBookRepository handles database operations over a polymorphic domain model that defines Book as supertype and PaperBook and AudioBook as subtypes. Code complexity to support polymorphic domain models is hidden at MongooseRepository; all that is required is that MongooseRepository receives a map describing the domain model. Each map entry key relates to a domain object type, and the related entry value is a reference to the constructor and the database schema of such domain object. The Default key is mandatory and relates to the supertype, while the rest of the keys relate to the subtypes.

Beware that subtype keys are named after the type name. If it so happens that you do not have any subtype in your domain model, no problem! Just specify the domain object that your custom repository is to handle as the sole map key-value, and you are done.

Supported Database Operations

The library supports two kinds of CRUD operations: basic and transactional. Both kinds specify atomic operations; however, while most of the former are inherently atomic (all but save), the latter require some transactional logic to ensure atomicity. Moreover, basic CRUD operations can be safely executed on a MongoDB standalone instance, but transactional CRUD operations are only atomic when run as part of a larger cluster e.g., a sharded cluster or a replica set. Using a MongoDB cluster in your production environment is, by the way, the official recommendation.

Let's now explore these two kinds of operations in detail.

Basic CRUD Operations

Repository is the generic interface implemented by MongooseRepository. Its definition is as follows:

type PartialEntityWithId<T> = { id: string } & Partial<T>;

interface Repository<T extends Entity> {
  findById: <S extends T>(
    id: string,
    options?: FindByIdOptions,
  ) => Promise<Optional<S>>;
  findOne: <S extends T>(
    filters: any, // Deprecated since v5.0.1, use options.filters instead
    options?: FindOneOptions,
  ) => Promise<Optional<S>>;
  findAll: <S extends T>(options?: FindAllOptions) => Promise<S[]>;
  save: <S extends T>(
    entity: S | PartialEntityWithId<S>,
    options?: SaveOptions,
  ) => Promise<S>;
  deleteById: (id: string, options?: DeleteByIdOptions) => Promise<boolean>;
}

T refers to a domain object type that implements Entity (e.g., Book), and S refers to a subtype of such a domain object type (e.g., PaperBook or AudioBook). This way, you can be sure that the resulting values of the CRUD operations are of the type you expect.

[!NOTE] Keep in mind that the current semantics for these operations are those provided at MongooseRepository. If you want any of these operations to behave differently then you must override it at your custom repository implementation.

[!NOTE] All CRUD operations include an options parameter as part of their signature. This parameter specifies some optional configuration options. There are two types of options: behavioural and transactional. The former dictate the behaviour of the operation, thus influencing the operation result, while the later are required to execute the operation within a MongoDB transaction. You may read more about transactional options in the following section. This section focuses on behavioural options only.

findById

Returns an Optional entity matching the given id. This value wraps an actual entity or null in case that no entity matches the given id.

[!NOTE] The Optional type is meant to create awareness about the nullable nature of the operation result on the custom repository clients. This type helps client code developers to easily reason about all possible result types without having to handle slippery null values or exceptions (i.e., the alternatives to Optional), as mentioned by Joshua Bloch in his book Effective Java. Furthermore, the Optional API is quite complete and includes many elegant solutions to handle all use cases. Check it out!

findOne

Returns an Optional 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.

findAll

Returns an array including all the persisted entities, or an empty array otherwise.

This operation accepts some optional behavioural options:

• filters: a MongoDB search criteria to filter results
• sortBy: a MongoDB sort criteria to return results in some sorted order
• pageable: pagination data (i.e., pageNumber and offset) required to return a particular set of results. Both values must be a whole positive number to achieve the desired outcome

save

Persists the given entity by either inserting or updating it and returns the persisted entity. If the entity specifies an id field, this function updates it, unless it does not exist in the pertaining collection, in which case this operation results in an exception being thrown. Otherwise, if the entity does not specify an id field, it inserts it into the collection. Beware that trying to persist a new entity that includes a developer specified id is considered a system invariant violation; only Mongoose is able to produce MongoDB identifiers to prevent id collisions and undesired entity updates.

This operation accepts userId as an optional behavioural option to enable user audit data handling (read this section for further details on this topic).

[!WARNING] The version of save specified at MongooseRepository is not atomic. If you are to execute it in a concurrent environment, make sure that your custom repository extends MongooseTransactionalRepository instead.

deleteById

Deletes an entity which id field value matches the given id. When it does, the function returns true. Otherwise, it returns false.

Transactional CRUD Operations

Let's now explore the definition of TransactionalRepository, an interface that defines transactional CRUD operations. This interface is an extension of Repository, thus includes all the basic CRUD operations. Futhermore, MongooseTransactionalRepository is the class that implements TransactionalRepository.

export interface TransactionalRepository<T extends Entity>
  extends Repository<T> {
  saveAll: <S extends T>(
    entities: (S | PartialEntityWithId<S>)[],
    options?: SaveAllOptions,
  ) => Promise<S[]>;

  deleteAll: (options?: DeleteAllOptions) => Promise<number>;
}

[!NOTE] To ensure operation atomicity you must use a MongoDB cluster (e.g., a replica set) and make your custom repository extend MongooseTransactionalRepository. All the inherited default CRUD operations (i.e., the operations specified at Repository and TransactionalRepository) will be then guranteed to be atomic when a client of your custom repository invokes them. If you want to add a custom transactional operation that composes any other default or custom operation to your repository, then use the runInTransaction utility function. You may want to check the implementation of a soft deletion-based version of deleteAll here as an example of a custom transactional composite operation.

saveAll

Persists the given list of entities by either inserting or updating them and returns the list of persisted entities. As with the save operation, saveAll inserts or updates each entity of the list based on the existence of the id field. In the event of any error, this operation rollbacks all its changes. In other words, it does not save any given entity, thus guaranteeing operation atomicity.

This operation accepts userId as an optional behavioural option to enable user audit data handling (read this section for further details on this topic).

deleteAll

Deletes all the entities that match the MongoDB a given search criteria specified as options.filters behavioural option and returns the total amount of deleted entities. Beware that if no search criteria is provided, then deleteAll deletes all the stored entities. In the event of any error, this operation rollbacks all its changes. In other words, it does not delete any stored entity, thus guaranteeing operation atomicity.

Examples

You may find an example of how to instantiate and use a repository that performs basic CRUD operations over instances of Book and its aforementioned subtypes at book.repository.test.ts. You may also find an example on monguito's transactional CRUD operations at book.transactional-repository.test.ts.

Moreover, if you are interested in knowing how to inject and use a custom repository in a NestJS application, visit nestjs-mongoose-book-manager. But before jumping to that link, I recommend reading the following section.

Write Your Own Repository Interfaces

If you are to inject your newly created repository into an application that uses a Node.js-based framework (e.g., NestJS or Express) then you may want to do some extra effort and follow the Dependency Inversion principle to depend on abstractions, not implementations. Simply need to add one extra artefact to your code:

interface BookRepository extends Repository<Book> {
  findByIsbn: <T extends Book>(isbn: string) => Promise<Optional<T>>;
}

This interface allows you to create instances of BookRepository, and seamlessly switch between implementations for your repository (e.g., Mongoose-based or MongoDB Node Driver -based, Postgres, MySQL, etc.) Then, make your custom repository implement BookRepository as follows:

class MongooseBookRepository
  extends MongooseRepository<Book>
  implements BookRepository {
  // The rest of the code remains the same as before
}

If you are not willing to add any new operation at your custom repository, then you could make your repository implementation class implement Repository<T>, where T is your domain model supertype. Here is an alternative for the custom book repository example:

class MongooseBookRepository
  extends MongooseRepository<Book>
  implements Repository<Book> {
  // Simply add a constructor setting your domain model map as before
}

Extra Utilities

The Entity Interface

Here is a possible definition for the aforementioned polymorphic book domain model:

class Book implements Entity {
  readonly id?: string;
  readonly title: string;
  readonly description: string;
  readonly isbn: string;

  constructor(book: Book) {
    this.id = book.id;
    this.title = book.title;
    this.description = book.description;
    this.isbn = book.isbn;
  }
}

class PaperBook extends Book {
  readonly edition: number;

  constructor(paperBook: PaperBook) {
    super(paperBook);
    this.edition = paperBook.edition;
  }
}

The one thing that may catch your attention is the interface Entity that Book implements. Inspired in the Entity concept from Domain-Driven Design, Entity models any persistable domain object type. The interface defines an optional id field that all persistable domain object types must define. The optional nature of the field is due to the fact that its value is internally set by Mongoose. Thus, its value can safely be undefined until the pertaining domain object instance is inserted (i.e., stored for the first time) in the database.

The fact that Entity is an interface instead of an abstract class is not a coincidence; JavaScript is a single inheritance-based programming language, and I strongly believe that you are entitled to design the domain model at your will, with no dependencies to other libraries. But all that being said, you may decide not to use it at all, and that would be just fine. All you need to do is ensure that your domain objects specify an optional id field.

Define Your Custom Schemas

I believe that writing your own database schemas is a good practice, as opposed of using decorators at your domain model. This is mainly to avoid marrying the underlying infrastructure, thus enabling you to easily get rid of this repository logic if something better comes in. It also allows you to have more control on the persistence properties of your domain objects. After all, database definition is a thing that Mongoose is really rock-solid about.

The extendSchema function eases the specification of the Mongoose schemas of your domain model and let monguito to handle the required implementation details. This function is specially convenient when defining schemas for polymorphic data structures. The following example depicts the definition of BookSchema, PaperBookSchema, and AudioBookSchema:

const BookSchema = extendSchema(
  BaseSchema,
  {
    title: { type: String, required: true },
    description: { type: String, required: false },
    isbn: { type: String, required: true, unique: true },
  },
  { timestamps: true },
);

const PaperBookSchema = extendSchema(BookSchema, {
  edition: { type: Number, required: true, min: 1 },
});

const AudioBookSchema = extendSchema(BookSchema, {
  hostingPlatforms: { type: [{ type: String }], required: true },
});

Make sure that the schema for your supertype domain object extends from BaseSchema. It is required by MongooseRepository to properly deserialise your domain objects.

Built-in Audit Data Support

You can enable monguito's out-of-the-box audit data handling by just making your domain objects implement the Auditable interface. It specifies the data to audit i.e., creation and last update time and (optionally) user. Any domain object can implement this interface and add audit data as part of its constructor arguments. This approach is particularly useful for those domain objects that inherit the members of a superclass. Here is an example of the use of Auditable:

class AuditableBook implements Entity, Auditable {
  readonly id?: string;
  readonly title: string;
  readonly description: string;
  readonly isbn: string;
  readonly createdAt?: Date;
  readonly createdBy?: string;
  readonly updatedAt?: Date;
  readonly updatedBy?: string;

  constructor(book: AuditableBook) {
    this.id = book.id;
    this.title = book.title;
    this.description = book.description;
    this.isbn = book.isbn;
    this.createdAt = book.createdAt;
    this.createdBy = book.createdBy;
    this.updatedAt = book.updatedAt;
    this.updatedBy = book.updatedBy;
  }
}

If you would rather avoid all this boilerplate and you are not planning to make your domain object extend from any other class, you can make it inherit from AuditableClass. This is an abstract class included in monguito that implements Auditable and both declares and instantiates all the audit data for you. You may then use AuditableClass as follows:

class AuditableBook extends AuditableClass implements Entity {
  readonly id?: string;
  readonly title: string;
  readonly description: string;
  readonly isbn: string;

  constructor(book: AuditableBook) {
    super(book);
    this.id = book.id;
    this.title = book.title;
    this.description = book.description;
    this.isbn = book.isbn;
  }
}

monguito will produce and save the audit data for any domain object implementing Auditable or extending AuditableClass that is to be stored in MongoDB invoking the repository save operation. The user audit data is optional; if you want monguito to handle it for you, simply invoke save with a value for the userId input parameter as options parameter.

Custom Transactional Operations

[!WARNING] Custom transactional operations are only guaranteed to be atomic when executed on a MongoDB cluster.

Mongoose provides the means to write transactional operations i.e., database operations that compose other operations that are to run within one single transaction. For each transactional operation, the procedure consists of (1) creating a transaction session, (2) invoking a callback function specifying the actual database operation logic at hand, (3) if success commiting the transaction, (4) aborting the transaction under operation failure, and finally (5) ending the session.

This is a pretty cumbersome procedure to follow. monguito includes runInTransaction, a utility function that removes all this procedural boilerplate and lets you focus on defining your operations actual logic. This function receives a callback function implementing such logic and some transactional options parameter. You can use this parameter to specify a MongoDB connection to create a new transaction session from, or a reference to an existing transaction session.

You may want to check the implementation of a soft deletion-based version of deleteAll here as an example of a custom transactional operation.

Comparison to other Alternatives

First and foremost, monguito is simpler and more lightweight than other existing database integration alternatives (e.g., TypeORM or Typegoose). Additionally, TypeORM has mainly been developed for relational databases and presents several limitations compared to Mongoose. Typegoose, on another hand, is yet another Mongoose wrapper that provides TypeScript typing to Mongoose schemas and models, but it implements the Data Mapper pattern instead of the Repository pattern, which in complex domain model scenarios results in query logic duplication. Moreover, monguito is also type-safe.

Considering that Mongoose is currently the most mature MongoDB handling utility, I decided to keep it as monguito's foundation.

Project Validation

The application runs an in-memory instance of MongoDB. Its implementation is provided by the mongodb-memory-server NPM dependency.

# run integration tests
$ yarn install & yarn test

# run integration tests with coverage
$ yarn install & yarn test:cov

Contributors

Thanks to Alexander Peiker, Sergi Torres, and Aral Roca for all the insightful conversations on this topic.

Stay in touch

Author - Josu Martinez

License

This project is MIT licensed.