0
# Query Operators
1

2
MongoDB-style query operators for filtering and matching data. All operators are available as both part of the main sift function and as individual exports for custom operation sets.
3

4
## Capabilities
5

6
### Comparison Operators
7

8
Operators for comparing values with standard mathematical comparisons.
9

10
#### Equality ($eq)
11

12
Matches values that are equal to the specified value.
13

14
```typescript { .api }
15
/**
16
 * Equality operator - matches values equal to specified value
17
 * @param params - Value to match against
18
 * @param ownerQuery - Parent query object
19
 * @param options - Operation options
20
 * @returns EqualsOperation for equality testing
21
 */
22
function $eq(params: any, ownerQuery: Query<any>, options: Options): EqualsOperation;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import sift, { $eq, createQueryTester } from "sift";
29

30
// Using in main sift function
31
const equalsFive = sift({ $eq: 5 });
32
console.log(equalsFive(5)); // true
33
console.log(equalsFive(4)); // false
34

35
// Object property matching
36
const users = [
37
  { name: "Alice", age: 25 },
38
  { name: "Bob", age: 30 }
39
];
40
const nameAlice = users.filter(sift({ name: { $eq: "Alice" } })); // [{ name: "Alice", age: 25 }]
41

42
// With custom operations
43
const customFilter = createQueryTester({ value: 5 }, { operations: { $eq } });
44
```
45

46
#### Not Equal ($ne)
47

48
Matches values that are not equal to the specified value.
49

50
```typescript { .api }
51
/**
52
 * Not equal operator - matches values not equal to specified value
53
 * @param params - Value to exclude
54
 * @param ownerQuery - Parent query object
55
 * @param options - Operation options
56
 * @param name - Operation name
57
 * @returns $Ne operation for inequality testing
58
 */
59
function $ne(
60
  params: any,
61
  ownerQuery: Query<any>,
62
  options: Options,
63
  name: string
64
): Operation<any>;
65
```
66

67
#### Greater Than ($gt)
68

69
Matches values that are greater than the specified value.
70

71
```typescript { .api }
72
/**
73
 * Greater than operator - matches values greater than specified value
74
 * Automatically handles type coercion and null values
75
 * @param params - Threshold value
76
 * @param ownerQuery - Parent query object  
77
 * @param options - Operation options
78
 * @param name - Operation name
79
 * @returns Numerical operation for greater than comparison
80
 */
81
function $gt(
82
  params: any,
83
  ownerQuery: Query<any>,
84
  options: Options,
85
  name: string
86
): Operation<any>;
87
```
88

89
#### Greater Than or Equal ($gte)
90

91
Matches values that are greater than or equal to the specified value.
92

93
```typescript { .api }
94
/**
95
 * Greater than or equal operator - matches values >= specified value
96
 * @param params - Threshold value
97
 * @param ownerQuery - Parent query object
98
 * @param options - Operation options  
99
 * @param name - Operation name
100
 * @returns Numerical operation for >= comparison
101
 */
102
function $gte(
103
  params: any,
104
  ownerQuery: Query<any>,
105
  options: Options,
106
  name: string
107
): Operation<any>;
108
```
109

110
#### Less Than ($lt)
111

112
Matches values that are less than the specified value.
113

114
```typescript { .api }
115
/**
116
 * Less than operator - matches values less than specified value
117
 * @param params - Threshold value
118
 * @param ownerQuery - Parent query object
119
 * @param options - Operation options
120
 * @param name - Operation name  
121
 * @returns Numerical operation for less than comparison
122
 */
123
function $lt(
124
  params: any,
125
  ownerQuery: Query<any>,
126
  options: Options,
127
  name: string
128
): Operation<any>;
129
```
130

131
#### Less Than or Equal ($lte)
132

133
Matches values that are less than or equal to the specified value.
134

135
```typescript { .api }
136
/**
137
 * Less than or equal operator - matches values <= specified value
138
 * @param params - Threshold value
139
 * @param ownerQuery - Parent query object
140
 * @param options - Operation options
141
 * @param name - Operation name
142
 * @returns Numerical operation for <= comparison
143
 */
144
function $lte(
145
  params: any,
146
  ownerQuery: Query<any>,
147
  options: Options,
148
  name: string
149
): Operation<any>;
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
import sift from "sift";
156

157
const numbers = [1, 5, 10, 15, 20, 25];
158

159
// Comparison operators
160
const greaterThan10 = numbers.filter(sift({ $gt: 10 })); // [15, 20, 25]
161
const lessThanOrEqual15 = numbers.filter(sift({ $lte: 15 })); // [1, 5, 10, 15]
162
const notEqual10 = numbers.filter(sift({ $ne: 10 })); // [1, 5, 15, 20, 25]
163

164
// With object properties
165
const products = [
166
  { name: "Book", price: 10 },
167
  { name: "Laptop", price: 1000 },
168
  { name: "Mouse", price: 25 }
169
];
170
const affordable = products.filter(sift({ price: { $lte: 50 } })); 
171
// [{ name: "Book", price: 10 }, { name: "Mouse", price: 25 }]
172
```
173

174
### Logical Operators
175

176
Operators for combining multiple conditions with Boolean logic.
177

178
#### Logical AND ($and)
179

180
Matches documents that satisfy all specified conditions.
181

182
```typescript { .api }
183
/**
184
 * Logical AND operator - matches when all conditions are true
185
 * @param params - Array of query conditions that must all match
186
 * @param ownerQuery - Parent query object
187
 * @param options - Operation options
188
 * @param name - Operation name
189
 * @returns $And operation for logical AND
190
 */
191
function $and(
192
  params: Query<any>[],
193
  ownerQuery: Query<any>,
194
  options: Options,
195
  name: string
196
): Operation<any>;
197
```
198

199
#### Logical OR ($or)
200

201
Matches documents that satisfy at least one of the specified conditions.
202

203
```typescript { .api }
204
/**
205
 * Logical OR operator - matches when any condition is true
206
 * @param params - Array of query conditions, at least one must match
207
 * @param ownerQuery - Parent query object
208
 * @param options - Operation options
209
 * @param name - Operation name
210
 * @returns $Or operation for logical OR
211
 */
212
function $or(
213
  params: Query<any>[],
214
  ownerQuery: Query<any>,
215
  options: Options,
216
  name: string
217
): Operation<any>;
218
```
219

220
#### Logical NOR ($nor)
221

222
Matches documents that fail all specified conditions.
223

224
```typescript { .api }
225
/**
226
 * Logical NOR operator - matches when no conditions are true
227
 * @param params - Array of query conditions that must all be false
228
 * @param ownerQuery - Parent query object
229
 * @param options - Operation options
230
 * @param name - Operation name
231
 * @returns $Nor operation for logical NOR
232
 */
233
function $nor(
234
  params: Query<any>[],
235
  ownerQuery: Query<any>,
236
  options: Options,
237
  name: string
238
): Operation<any>;
239
```
240

241
#### Logical NOT ($not)
242

243
Inverts the result of the specified condition.
244

245
```typescript { .api }
246
/**
247
 * Logical NOT operator - inverts the result of the condition
248
 * @param params - Query condition to negate
249
 * @param ownerQuery - Parent query object
250
 * @param options - Operation options
251
 * @param name - Operation name
252
 * @returns $Not operation for logical negation
253
 */
254
function $not(
255
  params: any,
256
  ownerQuery: Query<any>,
257
  options: Options,
258
  name: string
259
): Operation<any>;
260
```
261

262
**Usage Examples:**
263

264
```typescript
265
import sift from "sift";
266

267
const users = [
268
  { name: "Alice", age: 25, department: "Engineering", active: true },
269
  { name: "Bob", age: 30, department: "Sales", active: false },
270
  { name: "Charlie", age: 35, department: "Engineering", active: true },
271
  { name: "Diana", age: 28, department: "Marketing", active: true }
272
];
273

274
// $and - all conditions must be true
275
const activeEngineers = users.filter(sift({
276
  $and: [
277
    { department: "Engineering" },
278
    { active: true }
279
  ]
280
})); // [{ name: "Alice", ... }, { name: "Charlie", ... }]
281

282
// $or - at least one condition must be true  
283
const youngOrSales = users.filter(sift({
284
  $or: [
285
    { age: { $lt: 30 } },
286
    { department: "Sales" }
287
  ]
288
})); // [{ name: "Alice", ... }, { name: "Bob", ... }, { name: "Diana", ... }]
289

290
// $not - negates the condition
291
const notEngineering = users.filter(sift({
292
  department: { $not: "Engineering" }
293
})); // [{ name: "Bob", ... }, { name: "Diana", ... }]
294

295
// $nor - none of the conditions should be true
296
const notYoungOrSales = users.filter(sift({
297
  $nor: [
298
    { age: { $lt: 30 } },
299
    { department: "Sales" }
300
  ]
301
})); // [{ name: "Charlie", ... }]
302
```
303

304
### Array Operators
305

306
Operators specifically designed for working with array fields and values.
307

308
#### Array Contains ($in)
309

310
Matches values that are contained in the specified array.
311

312
```typescript { .api }
313
/**
314
 * Array contains operator - matches values present in specified array
315
 * @param params - Array of values to match against
316
 * @param ownerQuery - Parent query object
317
 * @param options - Operation options
318
 * @param name - Operation name
319
 * @returns $In operation for array membership testing
320
 */
321
function $in(
322
  params: any,
323
  ownerQuery: Query<any>,
324
  options: Options,
325
  name: string
326
): Operation<any>;
327
```
328

329
#### Not In Array ($nin)
330

331
Matches values that are not contained in the specified array.
332

333
```typescript { .api }
334
/**
335
 * Not in array operator - matches values not present in specified array
336
 * @param params - Array of values to exclude
337
 * @param ownerQuery - Parent query object
338
 * @param options - Operation options
339
 * @param name - Operation name
340
 * @returns $Nin operation for array non-membership testing
341
 */
342
function $nin(
343
  params: any,
344
  ownerQuery: Query<any>,
345
  options: Options,
346
  name: string
347
): Operation<any>;
348
```
349

350
#### Array Contains All ($all)
351

352
Matches arrays that contain all specified elements.
353

354
```typescript { .api }
355
/**
356
 * Array contains all operator - matches arrays containing all specified values
357
 * @param params - Array of values that must all be present
358
 * @param ownerQuery - Parent query object
359
 * @param options - Operation options
360
 * @param name - Operation name
361
 * @returns $All operation for complete array subset testing
362
 */
363
function $all(
364
  params: Query<any>[],
365
  ownerQuery: Query<any>,
366
  options: Options,
367
  name: string
368
): Operation<any>;
369
```
370

371
#### Element Match ($elemMatch)
372

373
Matches documents containing an array field with at least one element matching all specified criteria.
374

375
```typescript { .api }
376
/**
377
 * Element match operator - matches arrays with at least one element matching criteria
378
 * @param params - Query object for matching array elements
379
 * @param ownerQuery - Parent query object
380
 * @param options - Operation options
381
 * @param name - Operation name
382
 * @returns $ElemMatch operation for array element query matching
383
 */
384
function $elemMatch(
385
  params: any,
386
  ownerQuery: Query<any>,
387
  options: Options,
388
  name: string
389
): Operation<any>;
390
```
391

392
#### Array Size ($size)
393

394
Matches arrays with the specified number of elements.
395

396
```typescript { .api }
397
/**
398
 * Array size operator - matches arrays with specified length
399
 * @param params - Required array length
400
 * @param ownerQuery - Parent query object
401
 * @param options - Operation options
402
 * @returns $Size operation for array length testing
403
 */
404
function $size(
405
  params: number,
406
  ownerQuery: Query<any>,
407
  options: Options
408
): Operation<any>;
409

410
/**
411
 * $Size operation class - for direct use in custom operation development
412
 */
413
class $Size extends BaseOperation<number> {
414
  readonly propop = true;
415
  
416
  constructor(params: number, ownerQuery: any, options: Options, name: string);
417
  next(item: any): void;
418
}
419
```
420

421
**Usage Examples:**
422

423
```typescript
424
import sift from "sift";
425

426
// Simple array filtering
427
const colors = ["red", "blue", "green", "yellow", "purple"];
428
const primaryColors = colors.filter(sift({ $in: ["red", "blue", "yellow"] })); 
429
// ["red", "blue", "yellow"]
430

431
const notPrimary = colors.filter(sift({ $nin: ["red", "blue", "yellow"] })); 
432
// ["green", "purple"]
433

434
// Object with array properties
435
const users = [
436
  { name: "Alice", skills: ["JavaScript", "Python", "SQL"], projects: 3 },
437
  { name: "Bob", skills: ["Java", "Python"], projects: 2 },
438
  { name: "Charlie", skills: ["JavaScript", "Python", "Go", "SQL"], projects: 5 }
439
];
440

441
// Users with specific skills
442
const pythonUsers = users.filter(sift({ skills: { $in: ["Python"] } })); 
443
// All users (all have Python)
444

445
// Users with all specified skills  
446
const fullStackUsers = users.filter(sift({ 
447
  skills: { $all: ["JavaScript", "SQL"] } 
448
})); // [{ name: "Alice", ... }, { name: "Charlie", ... }]
449

450
// Complex array queries
451
const orders = [
452
  { 
453
    id: 1, 
454
    items: [
455
      { product: "laptop", price: 1000, category: "electronics" },
456
      { product: "mouse", price: 25, category: "electronics" }
457
    ]
458
  },
459
  { 
460
    id: 2, 
461
    items: [
462
      { product: "book", price: 15, category: "education" },
463
      { product: "pen", price: 2, category: "stationery" }
464
    ]
465
  }
466
];
467

468
// Orders with expensive electronics
469
const expensiveElectronics = orders.filter(sift({
470
  items: { 
471
    $elemMatch: { 
472
      category: "electronics", 
473
      price: { $gt: 500 } 
474
    } 
475
  }
476
})); // [{ id: 1, ... }]
477

478
// Arrays with exactly 2 items
479
const twoItemArrays = [[1, 2], [1, 2, 3], [4, 5]].filter(sift({ $size: 2 })); 
480
// [[1, 2], [4, 5]]
481
```
482

483
### Element Operators
484

485
Operators for testing the existence and type of fields.
486

487
#### Field Exists ($exists)
488

489
Matches documents that have the specified field.
490

491
```typescript { .api }
492
/**
493
 * Field exists operator - matches documents containing specified field
494
 * @param params - Boolean indicating if field should exist (true) or not exist (false)
495
 * @param ownerQuery - Parent query object
496
 * @param options - Operation options
497
 * @param name - Operation name
498
 * @returns $Exists operation for field existence testing
499
 */
500
function $exists(
501
  params: boolean,
502
  ownerQuery: Query<any>,
503
  options: Options,
504
  name: string
505
): Operation<any>;
506
```
507

508
#### Type Check ($type)
509

510
Matches documents where the field value is of the specified type.
511

512
```typescript { .api }
513
/**
514
 * Type check operator - matches values of specified type
515
 * @param clazz - Constructor function or type string ("number", "string", "bool", "array", "null", "timestamp")
516
 * @param ownerQuery - Parent query object
517
 * @param options - Operation options
518
 * @returns EqualsOperation configured for type checking
519
 */
520
function $type(
521
  clazz: Function | string,
522
  ownerQuery: Query<any>,
523
  options: Options
524
): EqualsOperation;
525
```
526

527
**Usage Examples:**
528

529
```typescript
530
import sift from "sift";
531

532
const documents = [
533
  { name: "Alice", age: 25, email: "alice@example.com" },
534
  { name: "Bob", age: 30 }, // no email field
535
  { name: "Charlie", email: null }, // email is null
536
  { name: "Diana", age: "28", email: "diana@example.com" } // age is string
537
];
538

539
// Documents with email field
540
const hasEmail = documents.filter(sift({ email: { $exists: true } })); 
541
// [{ name: "Alice", ... }, { name: "Charlie", ... }, { name: "Diana", ... }]
542

543
// Documents without email field
544
const noEmail = documents.filter(sift({ email: { $exists: false } })); 
545
// [{ name: "Bob", ... }]
546

547
// Documents where age is a number
548
const numericAge = documents.filter(sift({ age: { $type: "number" } })); 
549
// [{ name: "Alice", ... }, { name: "Bob", ... }]
550

551
// Documents where age is a string
552
const stringAge = documents.filter(sift({ age: { $type: "string" } })); 
553
// [{ name: "Diana", ... }]
554

555
// Using constructor functions
556
const dateField = [
557
  { created: new Date(), name: "recent" },
558
  { created: "2023-01-01", name: "old" }
559
].filter(sift({ created: { $type: Date } })); 
560
// [{ created: Date, name: "recent" }]
561
```
562

563
### Evaluation Operators
564

565
Operators for complex matching including regular expressions and custom functions.
566

567
#### Regular Expression ($regex)
568

569
Matches string values against a regular expression pattern.
570

571
```typescript { .api }
572
/**
573
 * Regular expression operator - matches strings against regex pattern
574
 * @param pattern - Regular expression pattern string
575
 * @param ownerQuery - Parent query object (can contain $options)
576
 * @param options - Operation options  
577
 * @returns EqualsOperation configured with RegExp matching
578
 */
579
function $regex(
580
  pattern: string,
581
  ownerQuery: Query<any>,
582
  options: Options
583
): EqualsOperation;
584
```
585

586
#### Modulo ($mod)
587

588
Matches numeric values where value % divisor equals remainder.
589

590
```typescript { .api }
591
/**
592
 * Modulo operator - matches values where value % divisor equals remainder
593
 * @param params - Tuple of [divisor, remainder]
594
 * @param ownerQuery - Parent query object
595
 * @param options - Operation options
596
 * @returns EqualsOperation configured for modulo testing
597
 */
598
function $mod(
599
  params: [number, number],
600
  ownerQuery: Query<any>,
601
  options: Options
602
): EqualsOperation;
603
```
604

605
#### Custom Function ($where)
606

607
Matches values using a custom JavaScript function or expression.
608

609
```typescript { .api }
610
/**
611
 * Custom function operator - matches values using JavaScript function/expression
612
 * @param params - Function or string expression for evaluation
613
 * @param ownerQuery - Parent query object  
614
 * @param options - Operation options
615
 * @returns EqualsOperation using custom function evaluation
616
 */
617
function $where(
618
  params: string | Function,
619
  ownerQuery: Query<any>,
620
  options: Options
621
): EqualsOperation;
622
```
623

624
#### Regex Options ($options)
625

626
Provides options for $regex operator (case insensitive, global, multiline, unicode).
627

628
```typescript { .api }
629
/**
630
 * Regex options operator - provides flags for $regex operations
631
 * @returns null (this is a configuration operator)
632
 */
633
function $options(): null;
634
```
635

636
**Usage Examples:**
637

638
```typescript
639
import sift from "sift";
640

641
const users = [
642
  { name: "Alice Johnson", email: "alice@example.com", score: 85 },
643
  { name: "Bob Smith", email: "bob@test.org", score: 92 },
644
  { name: "Charlie Brown", email: "charlie@example.com", score: 78 }
645
];
646

647
// Regular expression matching
648
const exampleEmails = users.filter(sift({ 
649
  email: { $regex: "example\\.com$" } 
650
})); // Users with example.com emails
651

652
// Case-insensitive regex
653
const johnNames = users.filter(sift({ 
654
  name: { $regex: "john", $options: "i" } 
655
})); // [{ name: "Alice Johnson", ... }]
656

657
// Modulo operation - even scores
658
const evenScores = users.filter(sift({ score: { $mod: [2, 0] } })); 
659
// [{ name: "Charlie Brown", score: 78 }]
660

661
// Custom function matching
662
const highScorers = users.filter(sift({ 
663
  $where: function() { return this.score > 80; } 
664
})); // [{ name: "Alice Johnson", ... }, { name: "Bob Smith", ... }]
665

666
// String expression (if CSP not enabled)
667
const longNames = users.filter(sift({ 
668
  $where: "this.name.length > 10" 
669
})); // [{ name: "Alice Johnson", ... }, { name: "Charlie Brown", ... }]
670
```