monguito

library6.1.3jsnpmunverified

Monguito v6.1.3 is a lightweight, type-safe MongoDB repository library for Node.js that implements the repository and polymorphic patterns on top of Mongoose (v8+). It reduces boilerplate by providing a generic MongooseRepository class with basic CRUD operations (findById, findOne, findAll, save, deleteById) and supports polymorphic schemas via subtype configuration. It ships with TypeScript types and requires Node.js >= 18.18.0. Unlike raw Mongoose or other ODM wrappers, Monguito enforces a structured repository pattern and optional audit data tracking.

database

npm install monguito

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGUITO

monguito

databasejavascriptv6.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MongooseRepository

✓ import { MongooseRepository } from 'monguito'

✗ const { MongooseRepository } = require('monguito')

ESM-only; CommonJS require() will not work. Use dynamic import if needed.

MongooseEntity

✓ import { MongooseEntity } from 'monguito'

✗ import MongooseEntity from 'monguito'

Named export, not default. MongooseEntity is a base class for your domain models.

Optional

✓ import { Optional } from 'monguito'

✗ import { Optional } from 'mongoose'

Monguito re-exports its own Optional utility type (not Mongoose's).

Demonstrates defining a MongooseEntity, creating a custom repository with a finder method, and using the Optional utility.

import { MongooseRepository, MongooseEntity, Optional } from 'monguito'; import { Schema, Model, model } from 'mongoose'; class Book extends MongooseEntity { isbn!: string; title!: string; } const BookSchema = new Schema({ isbn: { type: String, required: true }, title: { type: String, required: true }, }); class BookRepository extends MongooseRepository<Book> { constructor() { super({ type: Book, schema: BookSchema }); } async findByIsbn(isbn: string): Promise<Optional<Book>> { if (!isbn) throw new Error('Invalid ISBN'); const doc = await this.entityModel.findOne({ isbn }).exec(); return Optional.ofNullable(this.instantiateFrom(doc) as Book); } } // Usage const repo = new BookRepository(); const book = await repo.findByIsbn('978-3-16-148410-0'); console.log(book.isPresent()); // true or false

Debug

Known issues

breakingMonguito v6 requires Node.js >= 18.18.0 and Mongoose >= 8.0.0. Older Node.js or Mongoose 7 will cause runtime errors.

fix

Upgrade Node.js to 18.18.0+ and Mongoose to 8.0.0+.

affects: >=6.0.0

deprecatedMonguito v5 and below used CommonJS and had different import paths. If migrating from v5, note that the repository class constructor signature changed (options object vs positional args).

fix

Update constructor to use options object: super({ type, schema, subtypes? }).

affects: <5.0.0

breakingThe `save` method now returns the saved entity (as MongooseEntity) instead of a plain object. This may break code assuming a plain object return.

fix

Adjust callers to handle MongooseEntity instance instead of plain object.

affects: >=6.0.0

gotchaPolymorphic subtypes must be registered in constructor options. If you omit them, querying for subtype instances will not instantiate the correct subclass.

fix

Ensure the `subtypes` array is provided in super() options when using polymorphic schemas.

affects: >=6.0.0

gotchaThe `entityModel` property is protected. Do not access it externally; use the provided repository methods or extend the class.

fix

If you need custom queries, add a method inside the repository subclass.

affects: >=6.0.0

Errors

Common errors & fixes

Cannot find module 'monguito'

Missing npm install or wrong Node.js version (v6 requires Node >= 18.18.0)

fix

Run `npm install monguito` and ensure Node.js version is 18.18.0 or higher.

TypeError: MongooseRepository is not a constructor

Using CommonJS require() instead of ESM import

fix

Use `import { MongooseRepository } from 'monguito'` in an ESM module or use dynamic import.

TypeError: Optional.ofNullable is not a function

Importing Optional incorrectly (e.g., default import instead of named)

fix

Use `import { Optional } from 'monguito'` (curly braces).

ValidationError: Path `isbn` is required

Schema defines required field but data missing; or using MongooseRepository without proper validation

fix

Check that the data passed to save() matches schema requirements.

Upgrade

Version history

6.1.3latest on npm

Audit

Dependencies

mongooserequiredpeer dependency (v8+) - Monguito wraps Mongoose for schema and ODM operations

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/josuto/monguito ↗

packagemonguito ↗

homepagehttps://github.com/josuto/monguito#readme ↗