Query Operators

/**
 * Equality operator - matches values equal to specified value
 * @param params - Value to match against
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @returns EqualsOperation for equality testing
 */
function $eq(params: any, ownerQuery: Query<any>, options: Options): EqualsOperation;

import sift, { $eq, createQueryTester } from "sift";

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

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

// With custom operations
const customFilter = createQueryTester({ value: 5 }, { operations: { $eq } });

/**
 * Not equal operator - matches values not equal to specified value
 * @param params - Value to exclude
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $Ne operation for inequality testing
 */
function $ne(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Greater than operator - matches values greater than specified value
 * Automatically handles type coercion and null values
 * @param params - Threshold value
 * @param ownerQuery - Parent query object  
 * @param options - Operation options
 * @param name - Operation name
 * @returns Numerical operation for greater than comparison
 */
function $gt(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Greater than or equal operator - matches values >= specified value
 * @param params - Threshold value
 * @param ownerQuery - Parent query object
 * @param options - Operation options  
 * @param name - Operation name
 * @returns Numerical operation for >= comparison
 */
function $gte(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Less than operator - matches values less than specified value
 * @param params - Threshold value
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name  
 * @returns Numerical operation for less than comparison
 */
function $lt(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Less than or equal operator - matches values <= specified value
 * @param params - Threshold value
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns Numerical operation for <= comparison
 */
function $lte(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

import sift from "sift";

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

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

// With object properties
const products = [
  { name: "Book", price: 10 },
  { name: "Laptop", price: 1000 },
  { name: "Mouse", price: 25 }
];
const affordable = products.filter(sift({ price: { $lte: 50 } })); 
// [{ name: "Book", price: 10 }, { name: "Mouse", price: 25 }]

/**
 * Logical AND operator - matches when all conditions are true
 * @param params - Array of query conditions that must all match
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $And operation for logical AND
 */
function $and(
  params: Query<any>[],
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Logical OR operator - matches when any condition is true
 * @param params - Array of query conditions, at least one must match
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $Or operation for logical OR
 */
function $or(
  params: Query<any>[],
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Logical NOR operator - matches when no conditions are true
 * @param params - Array of query conditions that must all be false
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $Nor operation for logical NOR
 */
function $nor(
  params: Query<any>[],
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Logical NOT operator - inverts the result of the condition
 * @param params - Query condition to negate
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $Not operation for logical negation
 */
function $not(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

import sift from "sift";

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

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

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

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

// $nor - none of the conditions should be true
const notYoungOrSales = users.filter(sift({
  $nor: [
    { age: { $lt: 30 } },
    { department: "Sales" }
  ]
})); // [{ name: "Charlie", ... }]

/**
 * Array contains operator - matches values present in specified array
 * @param params - Array of values to match against
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $In operation for array membership testing
 */
function $in(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Not in array operator - matches values not present in specified array
 * @param params - Array of values to exclude
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $Nin operation for array non-membership testing
 */
function $nin(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Array contains all operator - matches arrays containing all specified values
 * @param params - Array of values that must all be present
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $All operation for complete array subset testing
 */
function $all(
  params: Query<any>[],
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Element match operator - matches arrays with at least one element matching criteria
 * @param params - Query object for matching array elements
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $ElemMatch operation for array element query matching
 */
function $elemMatch(
  params: any,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Array size operator - matches arrays with specified length
 * @param params - Required array length
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @returns $Size operation for array length testing
 */
function $size(
  params: number,
  ownerQuery: Query<any>,
  options: Options
): Operation<any>;

/**
 * $Size operation class - for direct use in custom operation development
 */
class $Size extends BaseOperation<number> {
  readonly propop = true;
  
  constructor(params: number, ownerQuery: any, options: Options, name: string);
  next(item: any): void;
}

import sift from "sift";

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

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

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

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

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

// Complex array queries
const orders = [
  { 
    id: 1, 
    items: [
      { product: "laptop", price: 1000, category: "electronics" },
      { product: "mouse", price: 25, category: "electronics" }
    ]
  },
  { 
    id: 2, 
    items: [
      { product: "book", price: 15, category: "education" },
      { product: "pen", price: 2, category: "stationery" }
    ]
  }
];

// Orders with expensive electronics
const expensiveElectronics = orders.filter(sift({
  items: { 
    $elemMatch: { 
      category: "electronics", 
      price: { $gt: 500 } 
    } 
  }
})); // [{ id: 1, ... }]

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

/**
 * Field exists operator - matches documents containing specified field
 * @param params - Boolean indicating if field should exist (true) or not exist (false)
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @param name - Operation name
 * @returns $Exists operation for field existence testing
 */
function $exists(
  params: boolean,
  ownerQuery: Query<any>,
  options: Options,
  name: string
): Operation<any>;

/**
 * Type check operator - matches values of specified type
 * @param clazz - Constructor function or type string ("number", "string", "bool", "array", "null", "timestamp")
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @returns EqualsOperation configured for type checking
 */
function $type(
  clazz: Function | string,
  ownerQuery: Query<any>,
  options: Options
): EqualsOperation;

import sift from "sift";

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

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

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

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

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

// Using constructor functions
const dateField = [
  { created: new Date(), name: "recent" },
  { created: "2023-01-01", name: "old" }
].filter(sift({ created: { $type: Date } })); 
// [{ created: Date, name: "recent" }]

/**
 * Regular expression operator - matches strings against regex pattern
 * @param pattern - Regular expression pattern string
 * @param ownerQuery - Parent query object (can contain $options)
 * @param options - Operation options  
 * @returns EqualsOperation configured with RegExp matching
 */
function $regex(
  pattern: string,
  ownerQuery: Query<any>,
  options: Options
): EqualsOperation;

/**
 * Modulo operator - matches values where value % divisor equals remainder
 * @param params - Tuple of [divisor, remainder]
 * @param ownerQuery - Parent query object
 * @param options - Operation options
 * @returns EqualsOperation configured for modulo testing
 */
function $mod(
  params: [number, number],
  ownerQuery: Query<any>,
  options: Options
): EqualsOperation;

/**
 * Custom function operator - matches values using JavaScript function/expression
 * @param params - Function or string expression for evaluation
 * @param ownerQuery - Parent query object  
 * @param options - Operation options
 * @returns EqualsOperation using custom function evaluation
 */
function $where(
  params: string | Function,
  ownerQuery: Query<any>,
  options: Options
): EqualsOperation;

/**
 * Regex options operator - provides flags for $regex operations
 * @returns null (this is a configuration operator)
 */
function $options(): null;

import sift from "sift";

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

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

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

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

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

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