mongez-collection-querying

name

mongez-collection-querying

description

Tutorial-style guide to filtering and lookup on an `ImmutableCollection` — `where`, `whereIn`, `whereBetween`, `whereNotBetween`, `whereNot`, `whereNull`, `whereNotNull`, `whereEmpty`, `whereNotEmpty`, `whereExists`, `whereNotExists`, `filter`, `reject`, `except`, `not`, `find`, `first`, `last`, `firstWhere`, `lastWhere`. Covers RegExp shorthand, dot-notation paths, AND-chaining vs OR via `filter`, and item `.get(key)` integration with model classes. TRIGGER when: user asks "how do I filter / search / look up an item in a collection", "how to chain multiple where clauses", "how to do AND / OR filters", "how to find the first / last match", "what's the difference between filter and reject"; code combines several `whereXxx` calls. SKIP: the exhaustive 50+ operator reference table — use `mongez-collection-where` instead; predicate-only `filter` / `every` / `some` without operators — use `mongez-collection-builtins`; projection after filtering — chain into `mongez-collection-transforming`; one-shot filtering without a wrapper — `mongez-reinforcements-arrays` has no operator engine, so this skill is the right choice when operators are needed.

Querying a Collection

When to use

• Filtering a collection by a field value, comparison, pattern, or type check.
• Finding the first or last item that matches a condition.
• Checking existence, null/undefined status, set membership, or range.

How to use

where — operator engine

Three call signatures:

// 1. Key + value (implicit "=" equality)
c.where("active", true);

// 2. Key + operator + value
c.where("age", ">", 18);
c.where("name", "like", "ada");       // case-insensitive substring
c.where("name", "starts with", "A");
c.where("name", "ends with", "a");
c.where("role", "in", ["admin", "mod"]);
c.where("age", "between", [20, 30]);  // inclusive
c.where("score", "between", [0, 100]);

// 3. Operator only (no key — tests the item itself for primitives)
c.where(">=", 18);                    // items that are numbers >= 18

RegExp shorthand

Pass a RegExp as the value and the key check becomes a regex test:

c.where("name", /^A/);

Existence vs null vs undefined

Operator	Matches
"exists" / "not exists"	key is present / absent on the item object
"null" / "is null"	value is strictly null
"undefined" / "is undefined"	value is strictly undefined
"empty" / "is empty"	value is empty (via @mongez/supportive-is)

c.where("nickname", "exists");
c.where("deletedAt", "is null");
c.where("config", "is not empty");

Type checks

c.where("age", "is", "number");            // typeof itemValue === "number"
c.where("handler", "instanceof", MyClass); // itemValue instanceof MyClass
c.where("flag", "is true");
c.where("flag", "is false");

Convenience where* shorthand methods

c.whereIn("status", ["active", "pending"]);
c.whereBetween("age", [20, 30]);
c.whereNotBetween("score", [0, 50]);
c.whereNot("status", "banned");
c.whereNull("deletedAt");
c.whereNotNull("email");
c.whereEmpty("tags");
c.whereNotEmpty("tags");
c.whereExists("metadata");
c.whereNotExists("legacyId");

filter — callback-based

c.filter(item => item.score > 90 && item.verified);

reject / except

Returns items for which the callback returns false (inverse of filter):

c.reject(item => item.banned);
c.except(item => item.role === "guest"); // alias

not — exclude a specific primitive value

collect([1, 2, 3, null]).not(null); // [1, 2, 3]

find — single item by callback

const user = c.find(u => u.id === 42); // returns item or undefined

first / last

c.first(); // first item or undefined
c.last();  // last item or undefined

firstWhere / lastWhere

Same signature as where, but returns the single matched item instead of a collection:

const admin = c.firstWhere("role", "admin");
const newest = c.lastWhere("status", "active");
const over25 = c.firstWhere("age", ">", 25);

Key details / Pitfalls

• where always returns a new collection — it never mutates. Chain as many as needed.
• All operators are string literals defined in src/types.ts. Passing an unrecognised operator returns an empty collection (falls through to default: return false).
• Chained where calls are AND logic — each narrows the previous result. For OR logic, use filter with || or union two where results.
• Keys support dot notation: c.where("address.city", "London").
• If items have a .get(key) method it is used for all keyed lookups — collection integrates seamlessly with model classes.
• whereIn with a single array argument (no key) tests the item itself: c.whereIn([1, 2, 3]) keeps primitive items whose value is in the list.