collection

Tutorial-style "when to use which math method" guide for `@mongez/collection` — totaling, averaging, finding min/max/median, counting by predicate or by key, applying per-item arithmetic (`plus`/`minus`/`multiply`/`divide`/`modulus`/`increment`/`decrement`/`double`/`half`), parity filters (`even`/`odd`/`evenIndexes`/`oddIndexes`). TRIGGER when: user asks "how do I total / aggregate / sum up / average a field across items", "how to apply a markup / discount to every item", "how to count items matching a condition", "what's the difference between count / countValue / countBy"; user explores math methods without a specific method name in mind; code shapes look like aggregating monetary or analytic fields with `collect(...)`. SKIP: lookup-style "what does method X do" — use `mongez-collection-math` for the exact reference; one-shot aggregation without a chain — use `mongez-reinforcements-arrays`' standalone `sum`/`average`/`min`/`max`/`median`/`count`/`countBy` instead; filtering or sorting downstream of math — s

Aggregate reducers (`sum`, `min`, `max`, `average`, `avg`, `median`), per-element arithmetic (`plus`, `minus`, `multiply`, `divide`, `modulus`, `increment`, `decrement`, `double`, `half`), parity filters (`even`, `odd`, `evenIndexes`, `oddIndexes`), and counting (`count`, `countValue`, `countBy`). Covers the reinforcements quirks (`min`/`max`-of-empty = 0, `average`-of-empty = NaN, divide-by-zero throws) and the keyed-form source-mutation gotcha. TRIGGER when: code calls `c.sum`, `c.min`, `c.max`, `c.average`, `c.avg`, `c.median`, `c.plus`, `c.minus`, `c.multiply`, `c.divide`, `c.modulus`, `c.increment`, `c.decrement`, `c.double`, `c.half`, `c.even`, `c.odd`, `c.evenIndexes`, `c.oddIndexes`, `c.count`, `c.countValue`, or `c.countBy` on an `ImmutableCollection`; user asks "how do I sum / average / total / max / min on a collection field", "why does min return 0", "how to bump every item by 1", "why does divide throw". SKIP: math without a fluent chain or operator filter — use `mongez-reinforcements-arrays` (li

How to paginate, chunk, skip, and take items from an `ImmutableCollection` — `take`, `limit`, `takeLast`, `takeUntil`, `takeWhile`, `skip`, `skipTo`, `skipLast`, `skipUntil`, `skipLastUntil`, `skipLastWhile`, `skipWhile`, `slice`, `splice`, `chunk`, `random`, `shuffle` — plus the `(page-1)*perPage` recipe and the fact that there's no built-in `paginate` with totals. TRIGGER when: code calls `c.take`, `c.limit`, `c.takeLast`, `c.takeUntil`, `c.takeWhile`, `c.skip`, `c.skipTo`, `c.skipLast`, `c.skipUntil`, `c.skipLastUntil`, `c.skipLastWhile`, `c.skipWhile`, `c.slice`, `c.splice`, `c.chunk`, `c.random`, or `c.shuffle` on an `ImmutableCollection`; user asks "how do I paginate a collection", "how to take the first N / last N / page N", "how to batch into chunks of 100", "how to grab a random sample / shuffle". SKIP: page metadata (total / hasNext / totalPages) — not built-in, manually compute from `.length`; chunk a plain array without a wrapper — use `chunk` from `mongez-reinforcements-arrays`; sorting before pa

Idiomatic multi-method pipelines for `@mongez/collection` — top-N (`where` + `sortByDesc` + `take` + `pluck`), pagination (`skip` + `take`), bucket-then-aggregate (`groupBy` + `map` + `sum`), partition for dual pipelines, dedupe-and-project (`uniqueList` + `pluck`), `tap` for side-effects mid-chain, safe sort via `clone`, chunk-based batch processing, Map → collection conversion, lookup index via `reduce`, and intentional queue draining via `shift`. TRIGGER when: user asks "show me a worked example with @mongez/collection", "how do I do top-10 customers", "how to compute totals per group", "how to safely sort without mutating", "how to batch upload in chunks", "how to convert a Map into a collection", "how to drain a queue"; user wants a full chained pipeline rather than a single method. SKIP: single-method lookup — use the focused skill (`mongez-collection-where`, `mongez-collection-math`, `mongez-collection-sort-group`, `mongez-collection-pagination`, `mongez-collection-transforming`, `mongez-collection-mut

Tutorial-style guide to reshaping collection items — `map`, `pluck`, `select`, `groupBy`, `unique`, `uniqueList`, `flat`, `flatMap`, `collectFrom`, `collectFromKey`, `partition`. Covers column projection, dot-notation paths, flattening nested fields, splitting into two pipelines, and the `groupBy` → `items` sub-array convention. TRIGGER when: code calls `c.pluck`, `c.select`, `c.collectFrom`, `c.collectFromKey`, `c.partition`, `c.uniqueList` on an `ImmutableCollection`; user asks "how do I extract one field from every item", "how to project to a new shape / DTO", "how to keep only some keys per object", "how to flatten line items", "how to split into matching / not-matching"; chained pipelines that combine map + group + dedupe. SKIP: simple `map` / `filter` / `flat` / `flatMap` reference — use `mongez-collection-builtins`; operator filtering before transforming — chain via `mongez-collection-where` or `mongez-collection-querying`; the sort + group + unique reference matrix — use `mongez-collection-sort-group`

Explains what `@mongez/collection` is, when to prefer it over plain arrays or `@mongez/reinforcements`, and how the `ImmutableCollection` immutability model works. TRIGGER when: code imports `collect` or `ImmutableCollection` from `@mongez/collection`; user asks "what is @mongez/collection", "should I use collect or reinforcements", "how does the immutability work", "when do I reach for a fluent chain"; file is about to wrap an array in `collect(...)` or chain 3+ array ops. SKIP: deep dives into a specific method group — use `mongez-collection-querying` / `mongez-collection-math` / `mongez-collection-sort-group` / `mongez-collection-pagination` / `mongez-collection-transforming` / `mongez-collection-strings` / `mongez-collection-mutation` instead; `@mongez/reinforcements` has lighter array helpers (`chunk`, `unique`, `sum`, etc.) — point users to `mongez-reinforcements-arrays` for those; React state / atoms — use `@mongez/atom`'s `atomCollection`.

`Array.prototype` parity methods on `ImmutableCollection` — `map`, `filter`, `flat`, `flatMap`, `reduce`, `reduceRight`, `find`, `findIndex`, `indexOf`, `lastIndexOf`, `includes`, `contains`, `every`, `some`, `join`, `implode`, `forEach`, `each`, `keys`, `values`, `entries`, `indexes`, `toArray`, `all`, `toJson`, `toString`, `takeWhile`, `removeAll`. Documents the `reduce(cb)` NaN pitfall and the live-array `toArray()` reference quirk. TRIGGER when: code calls any of `c.map`, `c.filter`, `c.flat`, `c.flatMap`, `c.reduce`, `c.reduceRight`, `c.find`, `c.findIndex`, `c.indexOf`, `c.lastIndexOf`, `c.includes`, `c.contains`, `c.every`, `c.some`, `c.join`, `c.implode`, `c.forEach`, `c.each`, `c.keys`, `c.values`, `c.entries`, `c.indexes`, `c.toArray`, `c.all`, `c.toJson`, `c.toString`, `c.takeWhile`, `c.removeAll` on an `ImmutableCollection`; user asks "how do I map / filter / reduce a collection", "why is reduce returning NaN", "how do I unwrap to a plain array", "is toArray a copy"; file iterates / spreads / `Arr

Definitive matrix of which `ImmutableCollection` methods mutate in place — `sort`, `reverse` / `flip`, `sortByDesc`, `shift`, `pop` — versus which return a new collection. Covers `clone` / `copy` workarounds and the `toArray()` / `all()` live-reference hazard. TRIGGER when: code calls `c.sort`, `c.reverse`, `c.flip`, `c.sortByDesc`, `c.shift`, `c.pop`, `c.clone`, or `c.copy` on an `ImmutableCollection`; user asks "is sort/reverse/shift/pop safe", "why is my original collection changing", "do I need to clone before sorting", "which methods mutate in @mongez/collection", "is toArray a copy"; debugging an unexpected mutation bug on a shared collection. SKIP: non-mutating sort by key (`sortBy(key)` and `sortBy({...})`) — use `mongez-collection-sort-group`; insert / remove / replace operations that always return new — use `mongez-collection-overview` for the global picture; understanding what `@mongez/reinforcements` does on its own — that package has no wrapper to mutate.

How to sort, group, partition, deduplicate, and reorder items in an `ImmutableCollection` — `sort`, `sortBy`, `sortByDesc`, `groupBy`, `partition`, `unique`, `uniqueList`, `swap`, `move`, `reorder`, `reverse`, `flip`. Covers stability, multi-key `sortBy({...})`, the `unique` vs `uniqueList` shape difference, and which sort variants mutate. TRIGGER when: code calls `c.sort`, `c.sortBy`, `c.sortByDesc`, `c.groupBy`, `c.partition`, `c.unique`, `c.uniqueList`, `c.swap`, `c.move`, `c.reorder`, `c.reverse`, or `c.flip` on an `ImmutableCollection`; user asks "how do I sort by a field / multiple keys", "ascending vs descending", "how to group by role / category", "how to split active vs inactive", "how to dedupe by email", "how to swap two positions / reorder a list". SKIP: mutation safety details for `sort` / `reverse` / `sortByDesc` — use `mongez-collection-mutation` for the in-depth matrix; column projection after grouping — see `mongez-collection-transforming` for `pluck` / `select`; standalone `groupBy` / `uniqu

Per-element string transforms on an `ImmutableCollection` — `appendString`, `prependString`, `concatString`, `replaceString`, `replaceAllString`, `removeString`, `removeAllString`, `trim` — plus type casting (`string`, `number`, `boolean`). Documents the keyed-form source mutation, the `replaceAllString` "always global regex" trap, and when to reach for `.map` instead. TRIGGER when: code calls `c.appendString`, `c.prependString`, `c.concatString`, `c.replaceString`, `c.replaceAllString`, `c.removeString`, `c.removeAllString`, `c.trim`, `c.string`, `c.number`, or `c.boolean` on an `ImmutableCollection`; user asks "how do I append / prepend / replace / strip / trim text on every item", "how to cast a collection of strings to numbers / booleans", "how to apply a string transform to one field of every object". SKIP: ad-hoc string mapping where `c.map(item => ...)` is clearer — use `mongez-collection-builtins`; single-string formatting helpers — those live in `@mongez/reinforcements` (string slugify / kebab / came

Full reference for the `where(...)` operator-based filter (50+ operators: `=`, `>`, `like`, `between`, `in`, `is`, `instanceof`, `exists`, `empty`, `null`, `regex`, ...) plus shorthand helpers (`whereIn`, `whereNot`, `whereBetween`, `whereNotBetween`, `whereEmpty`, `whereNotEmpty`, `heavy`, `whereNull`, `whereNotNull`, `whereUndefined`, `whereNotUndefined`, `whereExists`, `whereNotExists`) and `firstWhere` / `lastWhere`. Documents the broken primitive-mode and `is undefined` quirks plus the `Operators` constant. TRIGGER when: code calls `c.where`, `c.whereIn`, `c.whereNot`, `c.whereBetween`, `c.whereNotBetween`, `c.whereEmpty`, `c.whereNotEmpty`, `c.heavy`, `c.whereNull`, `c.whereNotNull`, `c.whereUndefined`, `c.whereNotUndefined`, `c.whereExists`, `c.whereNotExists`, `c.firstWhere`, `c.lastWhere`, or imports `Operators` / `ComparisonOperator` from `@mongez/collection`; user asks "how do I filter by `>` / `like` / `between` / `in` / `null`", "what operators does where support", "how to use a RegExp with where

How to create an `ImmutableCollection` using `collect()`, `new ImmutableCollection()`, `collect.create()`, and `collect.fromIterator()` — including iterable inputs (Set, Map, generator) and seeded-length factories. TRIGGER when: code imports `collect`, `ImmutableCollection`, `collect.create`, `collect.fromIterator`, or `ImmutableCollection.fromIterator` / `ImmutableCollection.create` from `@mongez/collection`; user asks "how do I create a collection", "how to wrap an array / Set / Map / generator", "how to seed N items", "how to make a collection from an iterable"; `import { collect, ImmutableCollection } from "@mongez/collection"`. SKIP: operating on an already-built collection (filter / map / sort / aggregate) — use the operation-specific skills (`mongez-collection-querying`, `mongez-collection-transforming`, etc.); `@mongez/reinforcements` standalone helpers — use `mongez-reinforcements-arrays` for one-shot helpers without a wrapper.

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 with