An ODM (Object Document Mapper) library aiming to replicate as much as is necessary, functionality in NodeJS's mongoose. For those who may not know, mongoose is a JavaScript ODM wrapper library around the native MongoDB library that simplifies data access by simplifying the API surface. meerkat is a wrapper over the official MongoDB client library and aims to simplify common data access logic. This library also adds support for the DateOnly
and TimeOnly
introduced in .NET 6.
This library was named meerkat
as a homage to mongoose
because a meerkat is a mongoose. I know, I am hilarious like that. Please be sure to star ⭐️ this project if you think it's cool or useful.
There is a lot still to be done, feel free to open new issues to suggest features or report bugs and feel free to open PRs with updates.
If you are hardcore and want to go the manual route. Then add the following to your csproj
file:
<PackageReference Include="meerkat" Version="1.0.17"/>
If you're using the Visual Studio package manager console, then run the following:
Install-Package meerkat
If you are making use of the dotnet CLI, then run the following in your terminal:
dotnet add package meerkat
Before making use of any of meerkat's functions. Initialization must be done. This only needs to happen once.
using meerkat;
...
Meerkat.Connect("<any valid full mongodb connection string>"); // e.g mongodb://user:password@server-address:port/database-name?other-options
Ensure you have declared the necessary namespace at the head of your class file wherever you want to access meerkat functionality.
NOTE: All async methods support CancellationToken
s for cancelling the operations.
All models must inherit from the abstract Schema
class. The Schema
class has a virtual
Id
property that can be overridden in model. By default the Id
is an ObjectId
type.
class Student : Schema
{
public override object Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public Student()
{
// this is just an example, you'd probably get your entity ids in a saner manner
Id = (new Random()).Next();
}
}
If you want to specify the collection name to be used or track timestamps for the entity
[Collection(Name = "Persons", TrackTimestamps = true)]
public class Student : Schema
{
...
}
meerkat aims to save developer time by rolling the create and update parts of CRUD into one simple API. If an entity doesn't exist in the database, the entity is inserted into the collection, and if the entity already exists, it is simply updated
var student = new Student
{
FirstName = "Olubakinde",
LastName = "Chukumerije"
};
await student.SaveAsync(); // or student.Save(); if you prefer synchronous calls
It's that simple.
To find an entity by id
var student = await Meerkat.FindByIdAsync<Student>(1234); // or Meerkat.FindById<Student>(1234); if you like sync calls
To find an entity by a predictae
var student = await Meerkat.FindOneAsync<Student>(x => x.FirstName == "John"); // or Meerkat.FindOne(x => x.LastName == "Jane");
If you want to create complex queries and need access to the underlying IMongoQueryable
then this helps
var queryable = Meerkat.Query<Student>();
// do something with your queryable
var students = queryable
.Where(x => x.FirstName == "Olubakinde")
.ToListAsync();
To remove an entity by id
await Meerkat.RemoveByIdAsync<Student>(1234); // or Meerkat.RemoveById<Student>(1234); if you like sync calls
To remove an entity by a predicate
await Meerkat.RemoveOneAsync<Student>(x => x.FirstName == "John"); // or Meerkat.RemoveOne(x => x.LastName == "Jane");
To remove all entities that match a predicate
await Meerkat.RemoveAsync<Student>(x => x.FirstName == "John"); // or Meerkat.Remove(x => x.LastName == "Jane");
To check if any entities exist in a collection
var exists = await Meerkat.ExistsAsync<Student>(); // or Meerkat.Exists<Student>(); if you like sync calls
To check if any entities exits for a predicate
var exists = await Meerkat.ExistsAsync<Student>(x => x.FirstName.StartsWith("Ja")); // or Meerkat.Exists<Student>(x => x.FirstName.StartsWith("Ja")); if you like sync calls
To count all the entities in a collection
var count = await Meerkat.CountAsync<Student>(); // or Meerkat.Count<Student>(); if you like sync calls
To count all entities exits that match a predicate
var count = await Meerkat.CountAsync<Student>(x => x.FirstName.StartsWith("Ja")); // or Meerkat.Count<Student>(x => x.FirstName.StartsWith("Ja")); if you like sync calls
Meerkat allows for collections of entities to be upserted both synchronously and asynchronously
var peter = new Student();
var paul = new Student();
var students = new [] {peter, paul};
await students.SaveAllAsync(); // or students.SaveAll();