# mingo

**Repository Path**: kingecg/mingo

## Basic Information

- **Project Name**: mingo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mingo

[![build](https://github.com/kofrasa/mingo/actions/workflows/ci.yml/badge.svg)](https://github.com/kofrasa/mingo/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/mingo)](https://www.npmjs.com/package/mingo)
[![npm](https://img.shields.io/npm/dm/mingo)](https://www.npmjs.com/package/mingo)
[![Coverage Status](https://coveralls.io/repos/github/kofrasa/mingo/badge.svg?branch=master)](https://coveralls.io/github/kofrasa/mingo?branch=master)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

> JavaScript implementation of MongoDB query language supporting advanced queries, aggregation and custom operators.

## Features

- Supports Dot Notation, JSON Schema validation and MongoDB operators
- Support for [aggregation pipeline](https://docs.mongodb.com/manual/reference/operator/aggregation/) operations
- Support for [projection](https://docs.mongodb.com/manual/reference/method/db.collection.find/# projections) operations
- Support for [update](https://docs.mongodb.com/manual/reference/operator/update/) operations
- Support for custom operators and query context
- Support for streaming with iterators
- Query and update operations on trees and graphs via operators; `$graphLookup`
- Support for client-side operations on any JavaScript array or object
- Zero dependency, and fully compatible with all modern JS environments
- Clean and focused API that is easy to use with great performance

## Installation

```bash
npm install mingo
```

## Usage

### Node.js

```js
// es6 import
import { Query } from "mingo";

// commonjs require
const { Query } = require("mingo");

// create a Query with a criteria and optional projection
const query = new Query({ name: "John" }, { dob: 0 });

// filter collection with find()
const people = [
  { name: "Francis", age: 25, dob: "1992-09-20" },
  { name: "John", age: 20, dob: "1997-02-14" },
  { name: "Olive", age: 31, dob: "1986-07-01" }
];

// return matching items
query.find(people).all();

// return matching items (streaming)
query.stream(people).value();

// return a single matching item
query.find(people).first();

// check if collection has at least one match
query.test(people);
```

### Browser

```html
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/mingo/dist/mingo.min.js"></script>

<script>
  // initialize query object
  const query = new mingo.Query({ name: "John" }, { dob: 0 });

  // filter collection with find()
  const people = [
    { name: "Francis", age: 25, dob: "1992-09-20" },
    { name: "John", age: 20, dob: "1997-02-14" },
    { name: "Olive", age: 31, dob: "1986-07-01" }
  ];

  // return matching items
  query.find(people).all();

  // return matching items (streaming)
  query.stream(people).value();
</script>
```

### ES6

ES6 modules are also available.

```js
import { Query } from "mingo/esm/query";
import { Aggregator } from "mingo/esm/aggregator";
import { useOperators, OperatorType } from "mingo/esm/core";
import { $match, $group } from "mingo/esm/operators/pipeline";

// register the operators for the aggregation pipeline
useOperators(OperatorType.PIPELINE, { $match, $group });
```

### Streaming Support

Mingo supports streaming data through iterators for both queries and aggregations. This allows you to process large datasets efficiently without loading everything into memory at once.

```js
// Create a generator function for test data
function* generateData() {
  for (let i = 0; i < 1000000; i++) {
    yield { _id: i, name: `User${i}`, score: Math.random() * 100 };
  }
}

// Query streaming
const query = new Query({ score: { $gt: 80 } });
const queryStream = query.stream(generateData());
// Process results one by one without loading all into memory
for (const result of queryStream) {
  console.log(result);
}

// Aggregation streaming
const aggregator = new Aggregator([
  { $match: { score: { $gt: 50 } } },
  { $group: { _id: null, average: { $avg: "$score" } } }
]);
const aggStream = aggregator.stream(generateData());
const aggResults = aggStream.value(); // Get all results as an array
```

### TypeScript

```ts
import { Query } from "mingo";
import { Aggregator } from "mingo/aggregator";
import { useOperators, OperatorType } from "mingo/core";
// ensure the operators needed by your project are imported and registered.
import { $match, $group, $project } from "mingo/operators/pipeline";

// register the operators for the aggregation pipeline
useOperators(OperatorType.PIPELINE, { $match, $group, $project });

interface Person {
  _id: string;
  name: string;
  age: number;
}

const people: Person[] = [
  { _id: "1", name: "Francis", age: 25 },
  { _id: "2", name: "John", age: 20 },
  { _id: "3", name: "Olive", age: 31 }
];

const query = new Query<Person>({ name: "John" });
const result = query.find(people).all();

// aggregation
const aggregator = new Aggregator([
  { $match: { age: { $gte: 21 } } },
  { $project: { name: 1, age: 1 } },
  { $sort: { age: 1 } }
]);

const cursor = aggregator.stream(people);
const aggregated = cursor.value();
```

## Documentation

- [API Reference](https://kofrasa.github.io/mingo/)
- [Query Operators](https://docs.mongodb.com/manual/reference/operator/query/)
- [Aggregation Pipeline](https://docs.mongodb.com/manual/reference/operator/aggregation/)
- [Update Operators](https://docs.mongodb.com/manual/reference/operator/update/)

## Why Mingo?

MongoDB is the most popular NoSQL database today. A lot of front-end applications use it in their backend systems to store and retrieve data. During development, there is often a need to work with the data directly on the client-side, which is where this library comes in handy.

- **No backend?** Process data directly in the browser
- **Testing?** Simulate MongoDB queries in your test suite
- **Prototyping?** Quickly validate your MongoDB queries
- **Learning?** Experiment with MongoDB features without setting up a database

## Contributing

Mingo is an open-source project and contributions are welcome. Please read our [contributing guide](https://github.com/kofrasa/mingo/blob/master/CONTRIBUTING.md) for more information.

## License

[MIT](https://github.com/kofrasa/mingo/blob/master/LICENSE)