|
| 1 | +# Queries & Operators |
| 2 | + |
| 3 | +Monarch ORM provides a powerful, type-safe API for querying your MongoDB collections. By using the query builders and exported operators, you can construct complex filters without losing type safety. |
| 4 | + |
| 5 | +## Query Modifiers |
| 6 | + |
| 7 | +When you use `.find()` or `.findOne()`, Monarch returns a lazy query builder. The query is not executed until you `await` it. This allows you to chain modifiers to shape your results. |
| 8 | + |
| 9 | +### Selecting & Omitting Fields |
| 10 | + |
| 11 | +You can control exactly which fields are returned from the database using `.select()` and `.omit()`. |
| 12 | + |
| 13 | +```typescript |
| 14 | +// Only return the name and email fields |
| 15 | +const users = await db.collections.users |
| 16 | + .find() |
| 17 | + .select({ name: true, email: true }); |
| 18 | + |
| 19 | +// Return everything EXCEPT the age and password fields |
| 20 | +const publicUsers = await db.collections.users |
| 21 | + .find() |
| 22 | + .omit({ age: true, password: true }); |
| 23 | +``` |
| 24 | + |
| 25 | +### Sorting, Limiting, and Skipping |
| 26 | + |
| 27 | +Use these modifiers to paginate and order your results. |
| 28 | + |
| 29 | +```typescript |
| 30 | +const latestUsers = await db.collections.users |
| 31 | + .find({ isVerified: true }) |
| 32 | + .sort({ createdAt: -1 }) // Sort descending by createdAt |
| 33 | + .limit(10) // Return max 10 documents |
| 34 | + .skip(20); // Skip the first 20 documents |
| 35 | +``` |
| 36 | + |
| 37 | +### Cursors |
| 38 | + |
| 39 | +For large datasets where you don't want to load everything into memory at once, you can use `.cursor()` to iterate over documents one by one. |
| 40 | + |
| 41 | +```typescript |
| 42 | +const cursor = await db.collections.users.find({ isVerified: true }).cursor(); |
| 43 | + |
| 44 | +for await (const user of cursor) { |
| 45 | + console.log(user.name); |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +## Operators |
| 50 | + |
| 51 | +Monarch provides typed wrapper functions for standard MongoDB query operators. These functions enforce type safety and ensure your queries align with your schema. |
| 52 | + |
| 53 | +You can import them from `monarch-orm/operators`. |
| 54 | + |
| 55 | +```typescript |
| 56 | +import { eq, gt, or, inArray } from "monarch-orm/operators"; |
| 57 | +``` |
| 58 | + |
| 59 | +### Comparison Operators |
| 60 | + |
| 61 | +- **`eq(value)`**: Matches values equal to the specified value. |
| 62 | +- **`neq(value)`**: Matches values not equal to the specified value. |
| 63 | +- **`gt(value)`**: Matches values greater than the specified value. |
| 64 | +- **`lt(value)`**: Matches values less than the specified value. |
| 65 | +- **`gte(value)`**: Matches values greater than or equal to the specified value. |
| 66 | +- **`lte(value)`**: Matches values less than or equal to the specified value. |
| 67 | + |
| 68 | +```typescript |
| 69 | +const adults = await db.collections.users.find({ |
| 70 | + age: gte(18) |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +### Logical Operators |
| 75 | + |
| 76 | +- **`and(...expressions)`**: Matches documents that satisfy all expressions. |
| 77 | +- **`or(...expressions)`**: Matches documents that satisfy at least one expression. |
| 78 | +- **`nor(...expressions)`**: Matches documents that fail all expressions. |
| 79 | +- **`not(expression)`**: Inverts the effect of a filter expression. |
| 80 | + |
| 81 | +```typescript |
| 82 | +const specificUsers = await db.collections.users.find( |
| 83 | + or( |
| 84 | + { age: lt(18) }, |
| 85 | + { isVerified: false } |
| 86 | + ) |
| 87 | +); |
| 88 | +``` |
| 89 | + |
| 90 | +### Array Operators |
| 91 | + |
| 92 | +- **`inArray(values)`**: Matches values that exist in the specified array. |
| 93 | +- **`notInArray(values)`**: Matches values that do not exist in the specified array. |
| 94 | +- **`size(value)`**: Matches arrays with the specified number of elements. |
| 95 | + |
| 96 | +```typescript |
| 97 | +const targetedUsers = await db.collections.users.find({ |
| 98 | + role: inArray(["admin", "moderator"]) |
| 99 | +}); |
| 100 | +``` |
| 101 | + |
| 102 | +### Element Operators |
| 103 | + |
| 104 | +- **`exists()`**: Matches documents where the field exists. |
| 105 | +- **`notExists()`**: Matches documents where the field does not exist. |
| 106 | + |
| 107 | +```typescript |
| 108 | +const usersWithPhone = await db.collections.users.find({ |
| 109 | + phoneNumber: exists() |
| 110 | +}); |
| 111 | +``` |
| 112 | + |
| 113 | +## Native MongoDB Syntax |
| 114 | + |
| 115 | +Because Monarch wraps the underlying MongoDB Node.js driver, you are still free to use native MongoDB query syntax if you prefer. The fields and operators are fully typed based on your schema. |
| 116 | + |
| 117 | +```typescript |
| 118 | +const activeUsers = await db.collections.users.find({ |
| 119 | + age: { $gte: 18 }, |
| 120 | + role: { $in: ["admin", "moderator"] } |
| 121 | +}); |
| 122 | +``` |
0 commit comments