meerkat 1.0.18

dotnet add package meerkat --version 1.0.18                
NuGet\Install-Package meerkat -Version 1.0.18                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="meerkat" Version="1.0.18" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add meerkat --version 1.0.18                
#r "nuget: meerkat, 1.0.18"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install meerkat as a Cake Addin
#addin nuget:?package=meerkat&version=1.0.18

// Install meerkat as a Cake Tool
#tool nuget:?package=meerkat&version=1.0.18                

meerkat

License: MIT NuGet Badge Build Status

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.

Contributing

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.

Installation

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

Setup

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

Usage

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 CancellationTokens for cancelling the operations.

Modelling

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
{
  ...
}

Persistence

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.

Querying

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();

Removal

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");

Exists

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

Counting

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

Collections

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();
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.18 126 8/17/2024
1.0.17 262 11/5/2023
1.0.16 128 11/5/2023
1.0.13 4,531 6/8/2022
1.0.12 528 2/4/2022
1.0.11 440 2/4/2022
1.0.10 258 1/3/2022
1.0.9 357 10/27/2021
1.0.8 314 10/27/2021
1.0.7 319 10/26/2021
1.0.6 320 10/25/2021
1.0.5 302 10/23/2021
1.0.4 299 10/11/2021
1.0.3 328 10/8/2021
1.0.2 331 10/8/2021
1.0.1 313 10/7/2021
1.0.0 321 10/6/2021
1.0.0-beta.2 183 10/6/2021
1.0.0-beta.1 133 10/6/2021
1.0.0-alpha.2 169 10/6/2021
1.0.0-alpha.1 181 10/5/2021

- update underlying mongo client to address vulnerability