hassanzohdy/collection/where

where(...) — operator-based filtering

where(...) is the workhorse filter. It supports three argument shapes and ~50 operators.

Signatures

// 1. Equality on a keyed value:
c.where(key: string, value: any): ImmutableCollection<T>
// 2. Operator on a keyed value:
c.where(key: string, operator: ComparisonOperator, value: any): ImmutableCollection<T>
// 3. Operator on primitive items (key omitted):
c.where(operator: ComparisonOperator, value: any): ImmutableCollection<T>
// e.g. collect([1, 2, 3, 4]).where(">", 2) → [3, 4]

The wrapper looks at args.length and at whether the first arg is a known operator (Operators is a constant as const tuple of every string the switch handles).

Operators

like / not like treat a string value as a literal substring — it is regex-escaped

before matching, so ., *, (a+)+ match those characters rather than acting as a

pattern. (Before v1.4.0 the value was compiled as a raw regex, which was a ReDoS risk when

it came from a search box.) Pass an actual RegExp as the value when you want a pattern.

Examples

// Equality
collect(users).where("active", true);
// Comparison
collect(users).where("age", ">", 25);
collect(users).where("age", "between", [20, 30]);
// String matching
collect(users).where("name", "like", "ada");          // case-insensitive LITERAL substring
collect(users).where("name", "starts with", "A");
collect(users).where("name", "regex", /^A/);
collect(users).where("name", /^A/);                    // RegExp as value also works
// Set membership
collect(users).where("name", "in", ["Ada", "Bob"]);
collect(users).where("status", "!in", ["banned"]);
// Existence / null / undefined
collect(users).where("nickname", "exists");
collect(users).where("nickname", "is null");
// Type checks
collect(values).where("age", "is", "number");
collect(values).where("payload", "instanceof", ImmutableCollection);

Shorthand helpers

For common operators, there are dedicated methods that read more naturally:

firstWhere / lastWhere

c.firstWhere(key, value): T | undefined
c.firstWhere(key, operator, value): T | undefined
c.lastWhere(key, value): T | undefined
c.lastWhere(key, operator, value): T | undefined

Equivalent to c.where(...).first() / c.where(...).last().

Behaviors worth knowing

• `getItemValue(item, key)` prefers item.get(key) when it exists (lets you pass model classes), otherwise checks for a direct own property on the item, then falls back to dot-notation get(item, key).
• Comparing arrays / objects uses areEqual from @mongez/reinforcements, which is a deep equality check.
• Date comparison (Date instance vs Date instance) uses +itemValue === +value (numeric time).
• Empty uses @mongez/supportive-is' isEmpty — true for null, undefined, "", [], {}, etc.
• `is undefined` vs `not exists`: own-but-explicitly-undefined keys match where(key, "is undefined"); truly-missing keys (key absent on the object) match where(key, "not exists"). The two are distinguishable thanks to an own-property check in getItemValue before falling back to the dotted get() helper.