@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.7

package/docs/collections.md

@@ -0,0 +1,2270 @@
+# Collections
+
+A collection wraps a list of items with Laravel's collection methods: filter it, map it, group it, sort it and sum
+it, one chained call after another.
+
+## Introduction
+
+`Collection` wraps an array. Here `collect()` makes a collection of the array, uppercases each name, and drops the
+empty one:
+
+```ts
+const collection = collect(['Taylor', 'Abigail', null])
+  .map((name) => name?.toUpperCase())
+  .reject((name) => !name)
+
+collection.all()
+// ['TAYLOR', 'ABIGAIL']
+```
+
+Methods that change the items, such as `map()` and `reject()`, return a new collection and leave the one you called
+them on as it was. A few methods change the collection itself, and say so: `push()`, `pop()`, `put()`, `transform()`
+and the others listed under [Changing a collection in place](#changing-a-collection-in-place).
+
+Collections are iterable, so `for...of` and the spread operator work on them, and `JSON.stringify()` writes their items
+as an array. Your queries return collections too: a query's models come back in an `EloquentCollection`, which has every
+method here and a few for models, covered on [Eloquent collections](eloquent-collections.md).
+
+### Creating collections
+
+`collect()` makes a collection from an array, or from anything iterable, such as a `Set`:
+
+```ts
+const collection = collect([1, 2, 3])
+```
+
+`Collection.make()` does the same, and [`times()`](#times), [`range()`](#range), [`wrap()`](#wrap) and
+[`fromJson()`](#fromjson) build one in other ways. A collection's type comes from its items: `collect([1, 2, 3])` is
+a `Collection<number>`, and the callbacks you give its methods are typed with it.
+
+### A collection is a list
+
+A Laravel collection is a PHP array, whose items have keys: numbers, as in a list, or strings, as in a dictionary.
+An Oriel collection is a list. Its items are always numbered from 0, in order, with no gaps:
+
+- methods that keep some of the items, such as `filter()`, `unique()` and `sortBy()`, number them again from 0. You
+  never need `values()` to reset the keys, as you do in Laravel;
+- Laravel's methods that take a key take an index: `get(1)`, `has(0)`, `only(0, 2)`, `except(1)`, `put(1, value)`,
+  `pull(1)`, `forget(1)`, `replace({ 1: value })` and `splice()`. `search()` returns an index, and `keys()` the
+  indexes;
+- removing an item, with `forget()` or `pull()`, moves the later items up;
+- `put()` and `replace()` with an index past the end add the item at the end. A negative or fractional index throws a
+  `RangeError`: "Invalid collection index [-1].";
+- methods that build a dictionary return a plain object, not a collection: [`keyBy()`](#keyby),
+  [`groupBy()`](#groupby), [`mapWithKeys()`](#mapwithkeys), [`countBy()`](#countby), [`flip()`](#flip),
+  [`combine()`](#combine), [`mapToDictionary()`](#maptodictionary) and [`mapToGroups()`](#maptogroups).
+
+```ts
+const collection = collect(['a', 'b', 'c'])
+
+collection.forget(0)
+
+collection.all()
+// ['b', 'c']
+
+collection.get(0)
+// 'b'
+```
+
+Laravel's methods that only make sense for keys aren't in Oriel; [Methods left out](#methods-left-out) lists them.
+
+### Strict and loose comparisons
+
+Laravel compares values loosely in most methods, so the string `'1'` equals the number `1`, and offers a strict twin
+for some of them. Oriel compares loosely, with JavaScript's `==`, only in these:
+
+- `where(key, value)`, `firstWhere(key, value)`, `every(key, value)`, `sole(key, value)`, `firstOrFail(key, value)`,
+  and every form that takes an operator, such as `where('price', '>', 100)` and `contains('price', '=', 100)`;
+- `search()`, `before()` and `after()`, unless you pass `true` as their last argument;
+- `duplicates()`, whose strict twin is `duplicatesStrict()`.
+
+Everything else compares strictly, with `===`: `contains(value)`, `contains(key, value)`, `some()` and
+`doesntContain()` with a value, `unique()`, `whereIn()`, `whereNotIn()`, `diff()`, `intersect()`, `takeUntil()` and
+the others. Their `Strict` names, such as `containsStrict()` and `uniqueStrict()`, are the same methods under
+Laravel's other name.
+
+```ts
+const products = collect([{ product: 'Desk', price: 200 }])
+
+products.where('price', '200').count()
+// 1
+
+products.contains('price', '200')
+// false
+```
+
+> [!NOTE]
+> In Laravel, `contains('price', '200')` is true and `where('price', '200')` finds the desk, both loosely. In Oriel,
+> `contains()`, `some()` and `doesntContain()` with a key and a value are strict, while `where()`, `every()`,
+> `sole()` and `firstOrFail()` with a key and a value are loose. Pass the value with the type you stored, and the
+> difference never shows.
+
+### Keys and callbacks
+
+Many methods read a value from each item: give them the name of a property, as `sortBy('price')`, or a function
+that returns the value, as `sortBy((product) => product.price)`. TypeScript checks a name against the items' type. A
+callback receives the item and its index.
+
+Where Laravel's callback returns `null` to mean "no value", Oriel's methods return `undefined`: `first()` on an
+empty collection, `avg()` with no numbers, `get()` past the end.
+
+### Extending collections
+
+Laravel adds methods to every collection with `Collection::macro()`. Oriel has no macros: methods added while your
+app runs are invisible to TypeScript. Extend `Collection` instead:
+
+```ts title="app/Support/ProductCollection.ts"
+import { Collection } from '@orieljs/framework'
+
+interface Product {
+  name: string
+  price: number
+}
+
+export class ProductCollection extends Collection<Product> {
+  total(): number {
+    return this.sum('price')
+  }
+}
+```
+
+Methods that keep the same kind of items, such as `filter()`, `sortBy()`, `where()` and `take()`, return your
+class, so `new ProductCollection(products).where('price', '>', 100).total()` works. Methods that make other items,
+such as `map()` and `pluck()`, return a plain `Collection`. A subclass whose constructor takes other arguments must
+override the protected `newInstance(items)`, which the methods use to make their result.
+
+## Available methods
+
+Each method below has a short entry, in alphabetical order. Static methods, called on `Collection`, are marked so.
+
+[add](#add), [after](#after), [all](#all), [average](#average), [avg](#avg), [before](#before), [chunk](#chunk),
+[chunkWhile](#chunkwhile), [collapse](#collapse), [collect](#collect), [combine](#combine), [concat](#concat),
+[contains](#contains), [containsOneItem](#containsoneitem), [containsStrict](#containsstrict), [count](#count),
+[countBy](#countby), [crossJoin](#crossjoin), [diff](#diff), [diffUsing](#diffusing), [doesntContain](#doesntcontain),
+[doesntContainStrict](#doesntcontainstrict), [dump](#dump), [duplicates](#duplicates),
+[duplicatesStrict](#duplicatesstrict), [each](#each), [eachSpread](#eachspread), [empty](#empty), [ensure](#ensure),
+[every](#every), [except](#except), [filter](#filter), [first](#first), [firstOrFail](#firstorfail),
+[firstWhere](#firstwhere), [flatMap](#flatmap), [flatten](#flatten), [flip](#flip), [forget](#forget),
+[forPage](#forpage), [fromJson](#fromjson), [get](#get), [groupBy](#groupby), [has](#has), [hasAny](#hasany),
+[implode](#implode), [intersect](#intersect), [intersectUsing](#intersectusing), [isEmpty](#isempty),
+[isNotEmpty](#isnotempty), [join](#join), [keyBy](#keyby), [keys](#keys), [last](#last), [lazy](#lazy), [make](#make),
+[map](#map), [mapInto](#mapinto), [mapSpread](#mapspread), [mapToDictionary](#maptodictionary),
+[mapToGroups](#maptogroups), [mapWithKeys](#mapwithkeys), [max](#max), [median](#median), [merge](#merge), [min](#min),
+[mode](#mode), [multiply](#multiply), [nth](#nth), [only](#only), [pad](#pad), [partition](#partition),
+[percentage](#percentage), [pipe](#pipe), [pipeInto](#pipeinto), [pipeThrough](#pipethrough), [pluck](#pluck),
+[pop](#pop), [prepend](#prepend), [pull](#pull), [push](#push), [put](#put), [random](#random), [range](#range),
+[reduce](#reduce), [reduceSpread](#reducespread), [reject](#reject), [replace](#replace), [reverse](#reverse),
+[search](#search), [select](#select), [shift](#shift), [shuffle](#shuffle), [skip](#skip), [skipUntil](#skipuntil),
+[skipWhile](#skipwhile), [slice](#slice), [sliding](#sliding), [sole](#sole), [some](#some), [sort](#sort),
+[sortBy](#sortby), [sortByDesc](#sortbydesc), [sortDesc](#sortdesc), [splice](#splice), [split](#split),
+[splitIn](#splitin), [sum](#sum), [take](#take), [takeUntil](#takeuntil), [takeWhile](#takewhile), [tap](#tap),
+[times](#times), [toArray](#toarray), [toJson](#tojson), [transform](#transform), [unique](#unique),
+[uniqueStrict](#uniquestrict), [unless](#unless), [unlessEmpty](#unlessempty), [unlessNotEmpty](#unlessnotempty),
+[unshift](#unshift), [unwrap](#unwrap), [value](#value), [values](#values), [when](#when), [whenEmpty](#whenempty),
+[whenNotEmpty](#whennotempty), [where](#where), [whereBetween](#wherebetween), [whereIn](#wherein),
+[whereInstanceOf](#whereinstanceof), [whereInStrict](#whereinstrict), [whereNotBetween](#wherenotbetween),
+[whereNotIn](#wherenotin), [whereNotInStrict](#wherenotinstrict), [whereNotNull](#wherenotnull),
+[whereNull](#wherenull), [whereStrict](#wherestrict), [wrap](#wrap), [zip](#zip)
+
+### Changing a collection in place
+
+These methods change the collection you call them on: [`add()`](#add), [`forget()`](#forget), [`pop()`](#pop),
+[`prepend()`](#prepend), [`pull()`](#pull), [`push()`](#push), [`put()`](#put), [`shift()`](#shift),
+[`splice()`](#splice), [`transform()`](#transform) and [`unshift()`](#unshift). Every other method leaves it as it
+is.
+
+### Methods left out
+
+Laravel's methods for a collection's keys aren't in Oriel, because a collection is a list, whose keys are its
+indexes: `diffAssoc()`, `diffAssocUsing()`, `diffKeys()`, `intersectAssoc()`, `intersectAssocUsing()`,
+`intersectByKeys()`, `union()`, `mergeRecursive()`, `replaceRecursive()`, `sortKeys()`, `sortKeysDesc()`,
+`sortKeysUsing()`, `collapseWithKeys()`, `dot()` and `undot()`. For keyed data, use an object or a `Map`, or build
+one with [`keyBy()`](#keyby) or [`mapWithKeys()`](#mapwithkeys).
+
+These aren't in Oriel either:
+
+- `macro()`: see [Extending collections](#extending-collections);
+- `dd()`: JavaScript can't stop the program where you call it. [`dump()`](#dump) logs the items;
+- `hasMany()`: compare [`count()`](#count) with 1;
+- `hasSole()`: Oriel names it [`containsOneItem()`](#containsoneitem);
+- higher order messages, such as `$users->each->markAsVip()`: pass a function,
+  `users.each((user) => user.markAsVip())`;
+- dot notation in keys, such as `pluck('user.name')`: give the method a function where it takes one, or `map()` the
+  value out first: `map((item) => item.user.name)`.
+
+## Method listing
+
+#### `add()`
+
+`add()` adds one item at the end of the collection, changing it, and returns the collection:
+
+```ts
+const collection = collect([1, 2])
+
+collection.add(3)
+
+collection.all()
+// [1, 2, 3]
+```
+
+#### `after()`
+
+`after()` returns the item after the given one, or `undefined` when the item is the last one or isn't there:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.after(3)
+// 4
+
+collection.after(5)
+// undefined
+```
+
+It compares loosely, so `'4'` finds `4`. Pass `true` to compare strictly:
+
+```ts
+collect<number | string>([2, 4, 6, 8]).after('4', true)
+// undefined
+```
+
+It also takes a function, and returns the item after the first one that passes it:
+
+```ts
+collect([2, 4, 6, 8]).after((item) => item > 5)
+// 8
+```
+
+#### `all()`
+
+`all()` returns the items, as a new array:
+
+```ts
+collect([1, 2, 3]).all()
+// [1, 2, 3]
+```
+
+#### `average()`
+
+Another name for [`avg()`](#avg).
+
+#### `avg()`
+
+`avg()` returns the average of the items, or of a key's values:
+
+```ts
+collect([{ foo: 10 }, { foo: 10 }, { foo: 20 }, { foo: 40 }]).avg('foo')
+// 20
+
+collect([1, 1, 2, 4]).avg()
+// 2
+```
+
+Only numbers count: a string such as `'1'`, `null` and other values are left out, and a collection with no numbers
+gives `undefined`. Laravel counts numeric strings, and gives `null`.
+
+#### `before()`
+
+`before()` is the opposite of [`after()`](#after): it returns the item before the given one, or `undefined`:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.before(3)
+// 2
+
+collection.before(1)
+// undefined
+
+collect([2, 4, 6, 8]).before((item) => item > 5)
+// 4
+```
+
+#### `chunk()`
+
+`chunk()` splits the collection into collections of the given size, the last one smaller when the items run out:
+
+```ts
+const chunks = collect([1, 2, 3, 4, 5, 6, 7]).chunk(4)
+
+chunks.toArray()
+// [[1, 2, 3, 4], [5, 6, 7]]
+```
+
+#### `chunkWhile()`
+
+`chunkWhile()` splits the collection where the callback returns false. The callback receives the item, its index and
+the chunk so far:
+
+```ts
+const chunks = collect('AABBCCCD'.split('')).chunkWhile((value, index, chunk) => value === chunk.last())
+
+chunks.toArray()
+// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]
+```
+
+#### `collapse()`
+
+`collapse()` merges a collection of arrays, or of collections, into one flat collection. Other items are dropped:
+
+```ts
+const collapsed = collect([
+  [1, 2, 3],
+  [4, 5, 6],
+  [7, 8, 9],
+]).collapse()
+
+collapsed.all()
+// [1, 2, 3, 4, 5, 6, 7, 8, 9]
+```
+
+#### `collect()`
+
+`collect()` returns a plain `Collection` with the same items. On a subclass, such as the `EloquentCollection` your
+queries return, it gives you a base collection:
+
+```ts
+const collection = collect([1, 2, 3]).collect()
+```
+
+#### `combine()`
+
+`combine()` uses the items as keys for the values you give, and returns a plain object. Both must have the same
+number of items, or it throws a `RangeError`:
+
+```ts
+collect(['name', 'age']).combine(['George', 29])
+// { name: 'George', age: 29 }
+```
+
+#### `concat()`
+
+`concat()` returns the items followed by the ones you give:
+
+```ts
+const concatenated = collect(['John Doe']).concat(['Jane Doe']).concat(['Johnny Doe'])
+
+concatenated.all()
+// ['John Doe', 'Jane Doe', 'Johnny Doe']
+```
+
+#### `contains()`
+
+`contains()` tells you whether the collection has an item. Given a function, it tells you whether an item passes it:
+
+```ts
+collect([1, 2, 3, 4, 5]).contains((value) => value > 5)
+// false
+```
+
+Given a value, it tells you whether an item is that value:
+
+```ts
+const collection = collect(['Desk', 'Chair'])
+
+collection.contains('Desk')
+// true
+
+collection.contains('New York')
+// false
+```
+
+Given a key and a value, it tells you whether an item has that value:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Chair', price: 100 },
+])
+
+collection.contains('product', 'Bookcase')
+// false
+```
+
+A value, and a key and a value, are compared strictly, where Laravel compares them loosely:
+`collect([1, 2]).contains('1')` is `false`. Given a key, an operator and a value, it compares as [`where()`](#where)
+does, loosely: `collection.contains('price', '>', 150)`.
+
+#### `containsOneItem()`
+
+`containsOneItem()` tells you whether the collection has exactly one item, or exactly one that passes the callback.
+It is Laravel's `hasSole()`:
+
+```ts
+collect([]).containsOneItem()
+// false
+
+collect(['1']).containsOneItem()
+// true
+
+collect([1, 2, 3]).containsOneItem((item) => item === 2)
+// true
+```
+
+#### `containsStrict()`
+
+The same as [`contains()`](#contains), which already compares strictly.
+
+#### `count()`
+
+`count()` returns the number of items:
+
+```ts
+collect([1, 2, 3, 4]).count()
+// 4
+```
+
+#### `countBy()`
+
+`countBy()` counts how many times each value appears, and returns a plain object:
+
+```ts
+collect([1, 2, 2, 2, 3]).countBy()
+// { 1: 1, 2: 3, 3: 1 }
+```
+
+Given a key or a function, it counts what that gives for each item:
+
+```ts
+collect(['alice@gmail.com', 'bob@yahoo.com', 'carlos@gmail.com']).countBy((email) => email.split('@')[1])
+// { 'gmail.com': 2, 'yahoo.com': 1 }
+```
+
+#### `crossJoin()`
+
+`crossJoin()` returns every combination of the items with the items of the lists you give:
+
+```ts
+collect([1, 2]).crossJoin(['a', 'b']).all()
+// [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+
+collect([1, 2]).crossJoin(['a', 'b'], ['I', 'II']).all()
+// [[1, 'a', 'I'], [1, 'a', 'II'], [1, 'b', 'I'], [1, 'b', 'II'],
+//  [2, 'a', 'I'], [2, 'a', 'II'], [2, 'b', 'I'], [2, 'b', 'II']]
+```
+
+#### `diff()`
+
+`diff()` returns the items that aren't in the list you give, compared strictly:
+
+```ts
+const diff = collect([1, 2, 3, 4, 5]).diff([2, 4, 6, 8])
+
+diff.all()
+// [1, 3, 5]
+```
+
+Laravel compares the items as strings, so `1` and `'1'` match there and not here.
+
+#### `diffUsing()`
+
+`diffUsing()` is [`diff()`](#diff) with your own comparison: a function that returns `0` for two items that are the
+same:
+
+```ts
+const diff = collect(['a', 'B', 'c']).diffUsing(['A', 'b'], (a, b) => a.toLowerCase().localeCompare(b.toLowerCase()))
+
+diff.all()
+// ['c']
+```
+
+#### `doesntContain()`
+
+`doesntContain()` is the opposite of [`contains()`](#contains), and takes the same arguments, compared the same way:
+
+```ts
+collect([1, 2, 3, 4, 5]).doesntContain((value) => value < 5)
+// false
+
+collect(['Desk', 'Chair']).doesntContain('Table')
+// true
+
+collect([{ product: 'Desk', price: 200 }]).doesntContain('product', 'Bookcase')
+// true
+```
+
+#### `doesntContainStrict()`
+
+The same as [`doesntContain()`](#doesntcontain), which already compares strictly.
+
+#### `dump()`
+
+`dump()` logs the items with `console.log()`, and any values you pass after them, and returns the collection, so
+you can call it in the middle of a chain:
+
+```ts
+collect(['John Doe', 'Jane Doe']).dump()
+```
+
+#### `duplicates()`
+
+`duplicates()` returns the values that appear more than once, each time after the first, compared loosely:
+
+```ts
+collect(['a', 'b', 'a', 'c', 'b']).duplicates().all()
+// ['a', 'b']
+```
+
+Given a key or a function, it looks for repeated values of it:
+
+```ts
+const employees = collect([
+  { email: 'abigail@example.com', position: 'Developer' },
+  { email: 'james@example.com', position: 'Designer' },
+  { email: 'victoria@example.com', position: 'Developer' },
+])
+
+employees.duplicates('position').all()
+// ['Developer']
+```
+
+Laravel's result keeps each duplicate's position as its key; Oriel's is a list of the values.
+
+#### `duplicatesStrict()`
+
+[`duplicates()`](#duplicates), compared strictly: `collect([1, '1']).duplicatesStrict()` is empty.
+
+#### `each()`
+
+`each()` calls the function with each item and its index. Return `false` to stop:
+
+```ts
+collect([1, 2, 3, 4]).each((item) => {
+  if (item > 2) {
+    return false
+  }
+
+  console.log(item)
+})
+```
+
+#### `eachSpread()`
+
+`eachSpread()` is [`each()`](#each) for a collection of lists: each list's items are the function's arguments,
+followed by the index:
+
+```ts
+collect([
+  ['John Doe', 35],
+  ['Jane Doe', 33],
+]).eachSpread((name, age) => {
+  // ...
+})
+```
+
+#### `empty()`
+
+Static. `Collection.empty()` returns a collection with no items.
+
+#### `ensure()`
+
+`ensure()` checks that every item is of a type, or of one of a list of types, and throws a `TypeError` when one isn't:
+"Collection should only include [number] items, but 'string' found at position 1.". A type is a class, or one of
+JavaScript's type names: `'string'`, `'number'`, `'bigint'`, `'boolean'`, `'symbol'`, `'undefined'`, `'function'`,
+`'object'`, and `'null'` and `'array'`. It returns the collection, typed with those items:
+
+```ts
+declare const items: Collection<unknown>
+// ---cut---
+const users = items.ensure(User)
+
+const numbers = items.ensure(['number', 'string'])
+```
+
+Laravel's type names are PHP's (`'int'`, `'float'`, `'bool'`); Oriel's are JavaScript's. `ensure()` doesn't stop
+other items from being added later.
+
+#### `every()`
+
+`every()` tells you whether every item passes the function:
+
+```ts
+collect([1, 2, 3, 4]).every((value) => value > 2)
+// false
+```
+
+An empty collection gives `true`. Given a key, a key and a value, or a key, an operator and a value, it checks each
+item as [`where()`](#where) does, loosely.
+
+#### `except()`
+
+`except()` returns every item but those at the indexes you give. Laravel's takes keys:
+
+```ts
+collect(['a', 'b', 'c', 'd']).except(0, 2).all()
+// ['b', 'd']
+```
+
+#### `filter()`
+
+`filter()` keeps the items that pass the function:
+
+```ts
+const filtered = collect([1, 2, 3, 4]).filter((value) => value > 2)
+
+filtered.all()
+// [3, 4]
+```
+
+Without a function, it keeps the items that are truthy in JavaScript, so an empty array stays, where PHP drops it:
+
+```ts
+collect([1, 2, 3, null, false, '', 0, []]).filter().all()
+// [1, 2, 3, []]
+```
+
+The result is numbered from 0. For the opposite, see [`reject()`](#reject).
+
+#### `first()`
+
+`first()` returns the first item that passes the function, or the first item when you give none:
+
+```ts
+collect([1, 2, 3, 4]).first((value) => value > 2)
+// 3
+
+collect([1, 2, 3, 4]).first()
+// 1
+```
+
+When no item passes, it returns `undefined`, or the default you give as its second argument:
+`collect([1]).first((value) => value > 5, 'none')` is `'none'`.
+
+#### `firstOrFail()`
+
+`firstOrFail()` is [`first()`](#first), but throws an `ItemNotFoundError`, "Item not found.", when no item passes:
+
+```ts
+collect([1, 2, 3, 4]).firstOrFail((value) => value > 5)
+// throws ItemNotFoundError
+```
+
+It also takes a key and a value, or a key, an operator and a value, compared as [`where()`](#where) does.
+
+#### `firstWhere()`
+
+`firstWhere()` returns the first item whose key has the value, compared loosely, or `undefined`:
+
+```ts
+const users = collect([
+  { name: 'Regena', age: null },
+  { name: 'Linda', age: 14 },
+  { name: 'Diego', age: 23 },
+  { name: 'Linda', age: 84 },
+])
+
+users.firstWhere('name', 'Linda')
+// { name: 'Linda', age: 14 }
+```
+
+It takes an operator too, and with a key alone it finds the first item whose key is truthy:
+
+```ts
+declare const users: Collection<{ name: string; age: number | null }>
+// ---cut---
+users.firstWhere('age', '>=', 18)
+// { name: 'Diego', age: 23 }
+
+users.firstWhere('age')
+// { name: 'Linda', age: 14 }
+```
+
+#### `flatMap()`
+
+`flatMap()` maps each item, and flattens the results one level:
+
+```ts
+const collection = collect([{ name: 'Sally' }, { school: 'Arkansas' }, { age: 28 }])
+
+const flattened = collection.flatMap((values) => Object.values(values).map((value) => String(value).toUpperCase()))
+
+flattened.all()
+// ['SALLY', 'ARKANSAS', '28']
+```
+
+#### `flatten()`
+
+`flatten()` opens up nested arrays and collections, to every depth:
+
+```ts
+const flattened = collect([
+  ['PHP', 'JavaScript'],
+  [['Ruby'], 'Go'],
+]).flatten()
+
+flattened.all()
+// ['PHP', 'JavaScript', 'Ruby', 'Go']
+```
+
+Give it a depth to open fewer levels:
+
+```ts
+declare const collection: Collection<(string | string[])[]>
+// ---cut---
+collection.flatten(1).all()
+// ['PHP', 'JavaScript', ['Ruby'], 'Go']
+```
+
+Plain objects stay as they are. Laravel flattens an associative array's values too.
+
+#### `flip()`
+
+`flip()` returns a plain object with each item as a key, and its index as the value:
+
+```ts
+collect(['taylor', 'laravel']).flip()
+// { taylor: 0, laravel: 1 }
+```
+
+#### `forget()`
+
+`forget()` removes the items at the indexes you give, changing the collection, and the later items move up:
+
+```ts
+const collection = collect(['a', 'b', 'c'])
+
+collection.forget(1)
+
+collection.all()
+// ['a', 'c']
+```
+
+#### `forPage()`
+
+`forPage()` returns the items of one page, given the page number and the number of items per page:
+
+```ts
+const chunk = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]).forPage(2, 3)
+
+chunk.all()
+// [4, 5, 6]
+```
+
+#### `fromJson()`
+
+Static. `Collection.fromJson()` decodes a JSON string: an array gives its items, `null` an empty collection, and any
+other value a collection of that one value:
+
+```ts
+Collection.fromJson('[1, 2, 3]').all()
+// [1, 2, 3]
+
+Collection.fromJson('{"name": "Taylor"}').all()
+// [{ name: 'Taylor' }]
+```
+
+Laravel makes a JSON object into a collection keyed by its properties.
+
+#### `get()`
+
+`get()` returns the item at an index, or `undefined`. Laravel's takes a key:
+
+```ts
+const collection = collect(['taylor', 'abigail'])
+
+collection.get(1)
+// 'abigail'
+```
+
+A second argument is the default, returned when there is no item at the index. A function default is called:
+
+```ts
+const collection = collect(['taylor'])
+
+collection.get(5, 'default')
+// 'default'
+
+collection.get(5, () => 'computed')
+// 'computed'
+```
+
+#### `groupBy()`
+
+`groupBy()` groups the items by a key's value, and returns a plain object of collections:
+
+```ts
+const collection = collect([
+  { account_id: 'account-x10', product: 'Chair' },
+  { account_id: 'account-x10', product: 'Bookcase' },
+  { account_id: 'account-x11', product: 'Desk' },
+])
+
+const grouped = collection.groupBy('account_id')
+// {
+//   'account-x10': [{ account_id: 'account-x10', product: 'Chair' }, { account_id: 'account-x10', product: 'Bookcase' }],
+//   'account-x11': [{ account_id: 'account-x11', product: 'Desk' }],
+// }
+
+grouped['account-x11']?.count()
+// 1
+```
+
+Given a function, it groups by what the function returns:
+
+```ts
+declare const collection: Collection<{ account_id: string; product: string }>
+// ---cut---
+const grouped = collection.groupBy((item) => item.account_id.slice(-3))
+// { x10: [...], x11: [...] }
+```
+
+Laravel's `groupBy()` also takes several keys, for nested groups, and can keep the items' keys. Oriel's takes one
+key or function: group each group again for nested groups.
+
+#### `has()`
+
+`has()` tells you whether there is an item at every index you give. Laravel's takes keys:
+
+```ts
+const collection = collect(['Desk', 'Chair', 'Bookcase'])
+
+collection.has(1)
+// true
+
+collection.has(0, 5)
+// false
+```
+
+#### `hasAny()`
+
+`hasAny()` tells you whether there is an item at any of the indexes you give:
+
+```ts
+collect(['Desk']).hasAny(0, 5)
+// true
+```
+
+#### `implode()`
+
+`implode()` joins the items into a string, with the glue between them:
+
+```ts
+collect([1, 2, 3, 4, 5]).implode('-')
+// '1-2-3-4-5'
+```
+
+For items that are objects, give the key first, or a function:
+
+```ts
+const collection = collect([
+  { account_id: 1, product: 'Desk' },
+  { account_id: 2, product: 'Chair' },
+])
+
+collection.implode('product', ', ')
+// 'Desk, Chair'
+
+collection.implode((item) => item.product.toUpperCase(), ', ')
+// 'DESK, CHAIR'
+```
+
+#### `intersect()`
+
+`intersect()` keeps the items that are also in the list you give, compared strictly:
+
+```ts
+const intersect = collect(['Desk', 'Sofa', 'Chair']).intersect(['Desk', 'Chair', 'Bookcase'])
+
+intersect.all()
+// ['Desk', 'Chair']
+```
+
+#### `intersectUsing()`
+
+`intersectUsing()` is [`intersect()`](#intersect) with your own comparison, a function that returns `0` for two items
+that are the same:
+
+```ts
+const intersect = collect(['Desk', 'Sofa', 'Chair']).intersectUsing(['desk', 'chair', 'bookcase'], (a, b) =>
+  a.toLowerCase().localeCompare(b.toLowerCase()),
+)
+
+intersect.all()
+// ['Desk', 'Chair']
+```
+
+#### `isEmpty()`
+
+`isEmpty()` tells you whether the collection has no items:
+
+```ts
+collect([]).isEmpty()
+// true
+```
+
+#### `isNotEmpty()`
+
+`isNotEmpty()` tells you whether the collection has items:
+
+```ts
+collect([]).isNotEmpty()
+// false
+```
+
+#### `join()`
+
+`join()` joins the items into a string, with the glue between them, and another glue before the last one if you give
+it:
+
+```ts
+collect(['a', 'b', 'c']).join(', ')
+// 'a, b, c'
+
+collect(['a', 'b', 'c']).join(', ', ', and ')
+// 'a, b, and c'
+
+collect(['a', 'b']).join(', ', ' and ')
+// 'a and b'
+
+collect(['a']).join(', ', ' and ')
+// 'a'
+```
+
+#### `keyBy()`
+
+`keyBy()` returns a plain object of the items, under a key's value. When two items have the same value, the last one
+stays:
+
+```ts
+const collection = collect([
+  { product_id: 'prod-100', name: 'Desk' },
+  { product_id: 'prod-200', name: 'Chair' },
+])
+
+collection.keyBy('product_id')
+// {
+//   'prod-100': { product_id: 'prod-100', name: 'Desk' },
+//   'prod-200': { product_id: 'prod-200', name: 'Chair' },
+// }
+```
+
+It takes a function too: `collection.keyBy((item) => item.product_id.toUpperCase())`.
+
+#### `keys()`
+
+`keys()` returns the indexes, from 0:
+
+```ts
+collect(['a', 'b', 'c']).keys().all()
+// [0, 1, 2]
+```
+
+#### `last()`
+
+`last()` returns the last item that passes the function, or the last item when you give none, or `undefined`:
+
+```ts
+collect([1, 2, 3, 4]).last((value) => value < 3)
+// 2
+
+collect([1, 2, 3, 4]).last()
+// 4
+```
+
+Like [`first()`](#first), it takes a default as its second argument.
+
+#### `lazy()`
+
+`lazy()` returns a [lazy collection](#lazy-collections) of a copy of the items, so later changes to this collection
+don't reach it:
+
+```ts
+const lazyCollection = collect([1, 2, 3, 4]).lazy()
+
+const evens = await lazyCollection.filter((value) => value % 2 === 0).collect()
+```
+
+#### `make()`
+
+Static. `Collection.make()` makes a collection, as `collect()` does.
+
+#### `map()`
+
+`map()` calls the function with each item and its index, and returns a collection of the results:
+
+```ts
+const multiplied = collect([1, 2, 3, 4, 5]).map((item) => item * 2)
+
+multiplied.all()
+// [2, 4, 6, 8, 10]
+```
+
+To change the collection itself, use [`transform()`](#transform).
+
+#### `mapInto()`
+
+`mapInto()` makes an instance of a class for each item, with `new` and the item, then the index:
+
+```ts
+class Currency {
+  constructor(public code: string) {}
+}
+
+const currencies = collect(['USD', 'EUR', 'GBP']).mapInto(Currency)
+
+currencies.all()
+// [Currency { code: 'USD' }, Currency { code: 'EUR' }, Currency { code: 'GBP' }]
+```
+
+#### `mapSpread()`
+
+`mapSpread()` is [`map()`](#map) for a collection of lists: each list's items are the function's arguments, followed
+by the index:
+
+```ts
+const sequence = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+  .chunk(2)
+  .mapSpread((even, odd) => even + odd)
+
+sequence.all()
+// [1, 5, 9, 13, 17]
+```
+
+#### `mapToDictionary()`
+
+`mapToDictionary()` is [`mapToGroups()`](#maptogroups) with arrays for the groups in place of collections:
+
+```ts
+const collection = collect([
+  { name: 'John Doe', department: 'Sales' },
+  { name: 'Jane Doe', department: 'Sales' },
+])
+
+collection.mapToDictionary((item) => [item.department, item.name])
+// { Sales: ['John Doe', 'Jane Doe'] }
+```
+
+#### `mapToGroups()`
+
+`mapToGroups()` groups the items by the function's results. The function returns a `[key, value]` pair, and the
+result is a plain object of collections:
+
+```ts
+const collection = collect([
+  { name: 'John Doe', department: 'Sales' },
+  { name: 'Jane Doe', department: 'Sales' },
+  { name: 'Johnny Doe', department: 'Marketing' },
+])
+
+const grouped = collection.mapToGroups((item) => [item.department, item.name])
+// { Sales: ['John Doe', 'Jane Doe'], Marketing: ['Johnny Doe'] }
+
+grouped.Sales?.all()
+// ['John Doe', 'Jane Doe']
+```
+
+Laravel's function returns a one-entry array, `[$key => $value]`.
+
+#### `mapWithKeys()`
+
+`mapWithKeys()` builds a plain object from the function's results, each a `[key, value]` pair:
+
+```ts
+const collection = collect([
+  { name: 'John', department: 'Sales', email: 'john@example.com' },
+  { name: 'Jane', department: 'Marketing', email: 'jane@example.com' },
+])
+
+collection.mapWithKeys((item) => [item.email, item.name])
+// { 'john@example.com': 'John', 'jane@example.com': 'Jane' }
+```
+
+Laravel's function returns a one-entry array, and the result is a collection.
+
+#### `max()`
+
+`max()` returns the largest number among the items, or a key's values, or `undefined` when there is none:
+
+```ts
+collect([{ foo: 10 }, { foo: 20 }]).max('foo')
+// 20
+
+collect([1, 2, 3, 4, 5]).max()
+// 5
+```
+
+Only numbers count. Laravel's `max()` compares other values too.
+
+#### `median()`
+
+`median()` returns the middle number, or the average of the two middle ones, of the items or a key's values:
+
+```ts
+collect([{ foo: 10 }, { foo: 10 }, { foo: 20 }, { foo: 40 }]).median('foo')
+// 15
+
+collect([1, 1, 2, 4]).median()
+// 1.5
+```
+
+Only numbers count, and a collection with none gives `undefined`.
+
+#### `merge()`
+
+`merge()` returns the items followed by the ones you give, as [`concat()`](#concat) does:
+
+```ts
+const merged = collect(['Desk', 'Chair']).merge(['Bookcase', 'Door'])
+
+merged.all()
+// ['Desk', 'Chair', 'Bookcase', 'Door']
+```
+
+Laravel's `merge()` overwrites the items of string keys; a list has none.
+
+#### `min()`
+
+`min()` returns the smallest number among the items, or a key's values, or `undefined` when there is none:
+
+```ts
+collect([{ foo: 10 }, { foo: 20 }]).min('foo')
+// 10
+
+collect([1, 2, 3, 4, 5]).min()
+// 1
+```
+
+#### `mode()`
+
+`mode()` returns the most frequent values, in an array, in the order they first appear, or `undefined` for an empty
+collection:
+
+```ts
+collect([{ foo: 10 }, { foo: 10 }, { foo: 20 }, { foo: 40 }]).mode('foo')
+// [10]
+
+collect([1, 1, 2, 4]).mode()
+// [1]
+
+collect([1, 1, 2, 2]).mode()
+// [1, 2]
+```
+
+#### `multiply()`
+
+`multiply()` repeats the items the given number of times:
+
+```ts
+const users = collect([
+  { name: 'User #1', email: 'user1@example.com' },
+  { name: 'User #2', email: 'user2@example.com' },
+]).multiply(3)
+
+users.count()
+// 6
+```
+
+#### `nth()`
+
+`nth()` returns every nth item, from the first, or from the offset you give:
+
+```ts
+const collection = collect(['a', 'b', 'c', 'd', 'e', 'f'])
+
+collection.nth(4).all()
+// ['a', 'e']
+
+collection.nth(4, 1).all()
+// ['b', 'f']
+```
+
+#### `only()`
+
+`only()` returns the items at the indexes you give, in the collection's order. Laravel's takes keys:
+
+```ts
+collect(['a', 'b', 'c', 'd']).only(0, 2).all()
+// ['a', 'c']
+```
+
+#### `pad()`
+
+`pad()` fills the collection with the value up to the given size. A negative size pads at the start, and a size no
+larger than the collection changes nothing:
+
+```ts
+const collection = collect(['A', 'B', 'C'])
+
+collection.pad(5, 0).all()
+// ['A', 'B', 'C', 0, 0]
+
+collection.pad(-5, 0).all()
+// [0, 0, 'A', 'B', 'C']
+```
+
+#### `partition()`
+
+`partition()` returns two collections: the items that pass the function, and the ones that don't:
+
+```ts
+const [underThree, equalOrAboveThree] = collect([1, 2, 3, 4, 5, 6]).partition((item) => item < 3)
+
+underThree.all()
+// [1, 2]
+
+equalOrAboveThree.all()
+// [3, 4, 5, 6]
+```
+
+#### `percentage()`
+
+`percentage()` returns the share of the items that pass the function, as a percentage, rounded to two decimal places
+or the number you give, or `undefined` for an empty collection:
+
+```ts
+const collection = collect([1, 1, 2, 2, 2, 3])
+
+collection.percentage((value) => value === 1)
+// 33.33
+
+collection.percentage((value) => value === 1, 3)
+// 33.333
+```
+
+#### `pipe()`
+
+`pipe()` passes the collection to the function, and returns what it returns:
+
+```ts
+collect([1, 2, 3]).pipe((collection) => collection.sum())
+// 6
+```
+
+#### `pipeInto()`
+
+`pipeInto()` makes an instance of a class with the collection, `new` and the collection:
+
+```ts
+class ResourceCollection {
+  constructor(public collection: Collection<number>) {}
+}
+
+const resource = collect([1, 2, 3]).pipeInto(ResourceCollection)
+
+resource.collection.all()
+// [1, 2, 3]
+```
+
+#### `pipeThrough()`
+
+`pipeThrough()` passes the collection to the first function, its result to the next, and so on, and returns the last
+result:
+
+```ts
+const result = collect([1, 2, 3]).pipeThrough([
+  (collection) => collection.merge([4, 5]),
+  (collection) => collection.sum(),
+])
+// 15
+```
+
+#### `pluck()`
+
+`pluck()` returns a key's values:
+
+```ts
+const collection = collect([
+  { product_id: 'prod-100', name: 'Desk' },
+  { product_id: 'prod-200', name: 'Chair' },
+])
+
+collection.pluck('name').all()
+// ['Desk', 'Chair']
+```
+
+Laravel's `pluck()` also takes a second key, for the result's keys, and dot notation for nested values. Oriel's takes
+one key: for a dictionary of values, use [`mapWithKeys()`](#mapwithkeys), and for a nested value, `map()`.
+
+#### `pop()`
+
+`pop()` removes the last item and returns it, changing the collection:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.pop()
+// 5
+
+collection.all()
+// [1, 2, 3, 4]
+```
+
+Given a number, it removes that many from the end and returns them in a collection, the last first:
+
+```ts
+collect([1, 2, 3, 4, 5]).pop(3).all()
+// [5, 4, 3]
+```
+
+Laravel's `pop(1)` returns the item; Oriel's returns a collection whenever you give a number.
+
+#### `prepend()`
+
+`prepend()` adds an item at the start, changing the collection:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.prepend(0)
+
+collection.all()
+// [0, 1, 2, 3, 4, 5]
+```
+
+Laravel's takes a key as its second argument; a list has none.
+
+#### `pull()`
+
+`pull()` removes the item at an index and returns it, changing the collection, and the later items move up:
+
+```ts
+const collection = collect(['prod-100', 'Desk'])
+
+collection.pull(1)
+// 'Desk'
+
+collection.all()
+// ['prod-100']
+```
+
+When there is no item at the index, it returns `undefined`, or the default you give.
+
+#### `push()`
+
+`push()` adds items at the end, changing the collection:
+
+```ts
+const collection = collect([1, 2, 3, 4])
+
+collection.push(5)
+
+collection.all()
+// [1, 2, 3, 4, 5]
+```
+
+It takes several items: `collection.push(6, 7)`.
+
+#### `put()`
+
+`put()` sets the item at an index, changing the collection. An index past the end adds the item at the end, and a
+negative or fractional index throws a `RangeError`:
+
+```ts
+const collection = collect(['Desk', 'Chair'])
+
+collection.put(1, 'Sofa')
+
+collection.all()
+// ['Desk', 'Sofa']
+```
+
+#### `random()`
+
+`random()` returns a random item:
+
+```ts
+collect([1, 2, 3, 4, 5]).random()
+// 4 (retrieved randomly)
+```
+
+Given a number, it returns a collection of that many items, picked at random and kept in their order. A function
+receives the collection and returns the number. Asking for more items than the collection has throws a `RangeError`:
+"You requested 3 items, but there are only 2 items available.".
+
+```ts
+collect([1, 2, 3, 4, 5]).random(3).all()
+// [2, 4, 5] (retrieved randomly)
+```
+
+#### `range()`
+
+Static. `Collection.range()` returns the numbers from the first to the last, both included, counting by 1 or by the
+step you give:
+
+```ts
+Collection.range(3, 6).all()
+// [3, 4, 5, 6]
+
+Collection.range(10, 0, 5).all()
+// [10, 5, 0]
+```
+
+It takes numbers only, where PHP's `range()` also counts letters.
+
+#### `reduce()`
+
+`reduce()` reduces the collection to one value, passing the result of each step to the next. The function receives
+the result so far, the item and its index, and the second argument is the first result:
+
+```ts
+collect([1, 2, 3]).reduce((carry, item) => carry + item, 0)
+// 6
+```
+
+Laravel's starting value is optional, and `null` when you leave it out; Oriel's is required.
+
+#### `reduceSpread()`
+
+`reduceSpread()` reduces the collection to several values at once. The function receives them, then the item and
+its index, and returns them in an array; the arguments after the function are their starting values:
+
+```ts
+const [creditsLeft, prices] = collect([{ price: 3 }, { price: 6 }]).reduceSpread(
+  (credits: number, batch: number[], item) => [credits - item.price, [...batch, item.price]],
+  10,
+  [] as number[],
+)
+// creditsLeft: 1, prices: [3, 6]
+```
+
+A function that doesn't return an array throws a `TypeError`.
+
+#### `reject()`
+
+`reject()` drops the items that pass the function, the opposite of [`filter()`](#filter):
+
+```ts
+const filtered = collect([1, 2, 3, 4]).reject((value) => value > 2)
+
+filtered.all()
+// [1, 2]
+```
+
+#### `replace()`
+
+`replace()` returns a copy with the items at some indexes replaced. Give it an object of indexes and values, or an
+array, which replaces from index 0. An index past the end adds the item at the end, and a negative or fractional
+index throws a `RangeError`:
+
+```ts
+const collection = collect(['Taylor', 'Abigail', 'James'])
+
+collection.replace({ 1: 'Victoria', 3: 'Finn' }).all()
+// ['Taylor', 'Victoria', 'James', 'Finn']
+
+collection.replace(['Victoria']).all()
+// ['Victoria', 'Abigail', 'James']
+```
+
+#### `reverse()`
+
+`reverse()` returns the items in the reverse order:
+
+```ts
+collect(['a', 'b', 'c', 'd', 'e']).reverse().all()
+// ['e', 'd', 'c', 'b', 'a']
+```
+
+Laravel's keeps each item's key; Oriel's numbers them from 0.
+
+#### `search()`
+
+`search()` returns the index of the first item that is the value, compared loosely, or `false` when there is none:
+
+```ts
+const collection = collect([2, 4, 6, 8])
+
+collection.search(4)
+// 1
+```
+
+Pass `true` to compare strictly, or give a function:
+
+```ts
+declare const collection: Collection<number | string>
+// ---cut---
+collection.search('4', true)
+// false
+
+collection.search((item) => Number(item) > 5)
+// 2
+```
+
+#### `select()`
+
+`select()` keeps only the keys you give of each item, as a SQL `SELECT` does:
+
+```ts
+const users = collect([
+  { name: 'Taylor Otwell', role: 'Developer', status: 'active' },
+  { name: 'Victoria Faith', role: 'Researcher', status: 'active' },
+])
+
+users.select(['name', 'role']).all()
+// [{ name: 'Taylor Otwell', role: 'Developer' }, { name: 'Victoria Faith', role: 'Researcher' }]
+```
+
+#### `shift()`
+
+`shift()` removes the first item and returns it, changing the collection:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.shift()
+// 1
+
+collection.all()
+// [2, 3, 4, 5]
+```
+
+Given a number, it removes that many from the start and returns them in a collection. A negative number throws a
+`RangeError`. As with [`pop()`](#pop), `shift(1)` returns a collection.
+
+#### `shuffle()`
+
+`shuffle()` returns the items in a random order:
+
+```ts
+collect([1, 2, 3, 4, 5]).shuffle().all()
+// [3, 2, 5, 1, 4] (generated randomly)
+```
+
+#### `skip()`
+
+`skip()` returns the items after the given number of them:
+
+```ts
+collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).skip(4).all()
+// [5, 6, 7, 8, 9, 10]
+```
+
+#### `skipUntil()`
+
+`skipUntil()` skips items until one passes the function, or is the value, compared strictly, and returns the rest,
+that one included. When none does, the result is empty:
+
+```ts
+collect([1, 2, 3, 4]).skipUntil((item) => item >= 3).all()
+// [3, 4]
+
+collect([1, 2, 3, 4]).skipUntil(3).all()
+// [3, 4]
+```
+
+#### `skipWhile()`
+
+`skipWhile()` skips items while they pass the function, or are the value, and returns the rest:
+
+```ts
+collect([1, 2, 3, 4]).skipWhile((item) => item <= 3).all()
+// [4]
+```
+
+#### `slice()`
+
+`slice()` returns the items from an index on, or as many as you give:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+
+collection.slice(4).all()
+// [5, 6, 7, 8, 9, 10]
+
+collection.slice(4, 2).all()
+// [5, 6]
+```
+
+It counts as PHP's `array_slice()` does, which Laravel's uses: a negative start counts from the end, and a negative
+length leaves that many items off the end:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.slice(-2).all()
+// [4, 5]
+
+collection.slice(1, -1).all()
+// [2, 3, 4]
+```
+
+JavaScript's `Array.slice()` takes an end index instead of a length.
+
+#### `sliding()`
+
+`sliding()` returns overlapping windows of the items, two at a time or as many as you give, each starting one item, or
+the step you give, after the last:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.sliding(2).toArray()
+// [[1, 2], [2, 3], [3, 4], [4, 5]]
+
+collection.sliding(3, 2).toArray()
+// [[1, 2, 3], [3, 4, 5]]
+```
+
+#### `sole()`
+
+`sole()` returns the only item that passes the function, and throws when there isn't exactly one:
+
+```ts
+collect([1, 2, 3, 4]).sole((value) => value === 2)
+// 2
+```
+
+It also takes a key and a value, compared loosely, or a key, an operator and a value, and with nothing it returns the
+collection's only item:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Chair', price: 100 },
+])
+
+collection.sole('product', 'Chair')
+// { product: 'Chair', price: 100 }
+```
+
+No match throws an `ItemNotFoundError`, "Item not found.", and more than one a `MultipleItemsFoundError`, "2 items
+were found.".
+
+#### `some()`
+
+Another name for [`contains()`](#contains).
+
+#### `sort()`
+
+`sort()` returns the items sorted, in ascending order: numbers by their value, dates by their time, and anything else
+as text, by `localeCompare()`. `null` and `undefined` come last:
+
+```ts
+collect([5, 3, 1, 2, 4]).sort().all()
+// [1, 2, 3, 4, 5]
+
+collect([10, 9, 1]).sort().all()
+// [1, 9, 10]
+```
+
+Give it a comparison function for another order, as you would to an array's `sort()`:
+
+```ts
+collect([5, 3, 1, 2, 4])
+  .sort((a, b) => b - a)
+  .all()
+// [5, 4, 3, 2, 1]
+```
+
+Unlike an array's, it leaves the collection as it was. To sort objects, see [`sortBy()`](#sortby).
+
+#### `sortBy()`
+
+`sortBy()` sorts the items by a key's value, or by what a function returns:
+
+```ts
+const collection = collect([
+  { name: 'Desk', price: 200 },
+  { name: 'Chair', price: 100 },
+  { name: 'Bookcase', price: 150 },
+])
+
+collection.sortBy('price').pluck('name').all()
+// ['Chair', 'Bookcase', 'Desk']
+
+collection.sortBy((product) => product.name.length).pluck('name').all()
+// ['Desk', 'Chair', 'Bookcase']
+```
+
+The second argument is the direction, `'asc'` or `'desc'`. To sort by several keys, give a list of keys, each with its
+direction if you like, or of comparison functions:
+
+```ts
+const collection = collect([
+  { name: 'Taylor Otwell', age: 34 },
+  { name: 'Abigail Otwell', age: 30 },
+  { name: 'Taylor Otwell', age: 36 },
+  { name: 'Abigail Otwell', age: 32 },
+])
+
+collection.sortBy([['name', 'asc'], ['age', 'desc']]).all()
+// [
+//   { name: 'Abigail Otwell', age: 32 },
+//   { name: 'Abigail Otwell', age: 30 },
+//   { name: 'Taylor Otwell', age: 36 },
+//   { name: 'Taylor Otwell', age: 34 },
+// ]
+
+collection.sortBy([(a, b) => a.name.localeCompare(b.name), (a, b) => b.age - a.age]).all()
+```
+
+Items with the same value keep their order. A `null` or missing value comes last, in both directions, where Laravel
+puts it first in ascending order.
+
+#### `sortByDesc()`
+
+`sortByDesc()` is [`sortBy()`](#sortby) in descending order.
+
+#### `sortDesc()`
+
+`sortDesc()` is [`sort()`](#sort) in descending order:
+
+```ts
+collect([5, 3, 1, 2, 4]).sortDesc().all()
+// [5, 4, 3, 2, 1]
+```
+
+#### `splice()`
+
+`splice()` removes the items from an index on and returns them, changing the collection:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+const chunk = collection.splice(2)
+
+chunk.all()
+// [3, 4, 5]
+
+collection.all()
+// [1, 2]
+```
+
+A second argument limits how many it removes, and a third is a list of items to put in their place. As in PHP, a
+negative index counts from the end, and a negative number leaves that many items at the end:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+const chunk = collection.splice(2, 1, [10, 11])
+
+chunk.all()
+// [3]
+
+collection.all()
+// [1, 2, 10, 11, 4, 5]
+```
+
+#### `split()`
+
+`split()` splits the collection into the given number of groups, as even as they can be, the first ones larger:
+
+```ts
+collect([1, 2, 3, 4, 5]).split(3).toArray()
+// [[1, 2], [3, 4], [5]]
+```
+
+#### `splitIn()`
+
+`splitIn()` splits the collection into the given number of groups, every group full except the last:
+
+```ts
+collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).splitIn(3).toArray()
+// [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]
+```
+
+#### `sum()`
+
+`sum()` returns the sum of the items, or of a key's values, or of what a function returns:
+
+```ts
+collect([1, 2, 3, 4, 5]).sum()
+// 15
+
+collect([
+  { name: 'JavaScript: The Good Parts', pages: 176 },
+  { name: 'JavaScript: The Definitive Guide', pages: 1096 },
+]).sum('pages')
+// 1272
+
+collect([
+  { name: 'Chair', colors: ['Black'] },
+  { name: 'Desk', colors: ['Black', 'Mahogany'] },
+]).sum((product) => product.colors.length)
+// 3
+```
+
+Only numbers count: `collect(['1', 2]).sum()` is `2`, where Laravel adds the numeric string.
+
+#### `take()`
+
+`take()` returns the given number of items from the start, or from the end for a negative number:
+
+```ts
+collect([0, 1, 2, 3, 4, 5]).take(3).all()
+// [0, 1, 2]
+
+collect([0, 1, 2, 3, 4, 5]).take(-2).all()
+// [4, 5]
+```
+
+#### `takeUntil()`
+
+`takeUntil()` returns the items before the first one that passes the function, or is the value, compared strictly.
+When none does, it returns every item:
+
+```ts
+collect([1, 2, 3, 4]).takeUntil((item) => item >= 3).all()
+// [1, 2]
+
+collect([1, 2, 3, 4]).takeUntil(3).all()
+// [1, 2]
+```
+
+#### `takeWhile()`
+
+`takeWhile()` returns the items before the first one that fails the function, or isn't the value:
+
+```ts
+collect([1, 2, 3, 4]).takeWhile((item) => item < 3).all()
+// [1, 2]
+```
+
+#### `tap()`
+
+`tap()` passes the collection to the function and returns the collection, so you can look at it in the middle of a
+chain:
+
+```ts
+collect([2, 4, 3, 1, 5])
+  .sort()
+  .tap((collection) => console.log(collection.all()))
+  .shift()
+// 1
+```
+
+#### `times()`
+
+Static. `Collection.times()` calls the function the given number of times, with the numbers from 1, and returns a
+collection of the results:
+
+```ts
+Collection.times(10, (number) => number * 9).all()
+// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]
+```
+
+#### `toArray()`
+
+`toArray()` returns the items as an array, with each item that has a `toArray()` method, such as a model or a
+collection, turned into what it returns:
+
+```ts
+collect([collect([1, 2]), collect([3])]).toArray()
+// [[1, 2], [3]]
+```
+
+To get the items as they are, use [`all()`](#all).
+
+#### `toJson()`
+
+`toJson()` returns the items as JSON. `toPrettyJson()` indents it with four spaces, and `toJSON()` is what
+`JSON.stringify()` calls, so a collection inside an object is written as an array:
+
+```ts
+collect([{ name: 'Desk', price: 200 }]).toJson()
+// '[{"name":"Desk","price":200}]'
+
+JSON.stringify({ items: collect([1, 2]) })
+// '{"items":[1,2]}'
+```
+
+#### `transform()`
+
+`transform()` replaces each item with what the function returns, changing the collection:
+
+```ts
+const collection = collect([1, 2, 3, 4, 5])
+
+collection.transform((item) => item * 2)
+
+collection.all()
+// [2, 4, 6, 8, 10]
+```
+
+It returns the collection, typed with the new items. To keep the collection as it is, use [`map()`](#map).
+
+#### `unique()`
+
+`unique()` keeps the first of each value, compared strictly:
+
+```ts
+collect([1, 1, 2, 2, 3, 4, 2]).unique().all()
+// [1, 2, 3, 4]
+```
+
+Given a key or a function, it keeps the first item of each value it gives:
+
+```ts
+const collection = collect([
+  { name: 'iPhone 6', brand: 'Apple', type: 'phone' },
+  { name: 'iPhone 5', brand: 'Apple', type: 'phone' },
+  { name: 'Apple Watch', brand: 'Apple', type: 'watch' },
+  { name: 'Galaxy S6', brand: 'Samsung', type: 'phone' },
+  { name: 'Galaxy Gear', brand: 'Samsung', type: 'watch' },
+])
+
+collection.unique('brand').pluck('name').all()
+// ['iPhone 6', 'Galaxy S6']
+
+collection.unique((item) => item.brand + item.type).pluck('name').all()
+// ['iPhone 6', 'Apple Watch', 'Galaxy S6', 'Galaxy Gear']
+```
+
+Laravel's `unique()` compares loosely, so `1` and `'1'` are one value there and two here.
+
+#### `uniqueStrict()`
+
+The same as [`unique()`](#unique), which already compares strictly.
+
+#### `unless()`
+
+`unless()` calls the function unless the first argument is truthy, the opposite of [`when()`](#when):
+
+```ts
+const collection = collect([1, 2, 3])
+
+collection.unless(true, (collection) => collection.push(4))
+
+collection.unless(false, (collection) => collection.push(5))
+
+collection.all()
+// [1, 2, 3, 5]
+```
+
+#### `unlessEmpty()`
+
+Another name for [`whenNotEmpty()`](#whennotempty).
+
+#### `unlessNotEmpty()`
+
+Another name for [`whenEmpty()`](#whenempty).
+
+#### `unshift()`
+
+`unshift()` adds items at the start, in the order you give them, changing the collection:
+
+```ts
+const collection = collect([3])
+
+collection.unshift(1, 2)
+
+collection.all()
+// [1, 2, 3]
+```
+
+#### `unwrap()`
+
+Static. `Collection.unwrap()` returns a collection's items as an array, and any other value as it is:
+
+```ts
+Collection.unwrap(collect(['John Doe']))
+// ['John Doe']
+
+Collection.unwrap('John Doe')
+// 'John Doe'
+```
+
+#### `value()`
+
+`value()` returns a key's value from the first item where it is truthy:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Speaker', price: 400 },
+])
+
+collection.value('price')
+// 200
+```
+
+A price of `0` would be skipped. When no item has a truthy value, it returns `undefined`, or the default you give.
+
+#### `values()`
+
+`values()` returns a copy of the collection. In Laravel it numbers the items from 0 again, which an Oriel collection
+always does.
+
+#### `when()`
+
+`when()` calls the function when the first argument is truthy. The function receives the collection and the value:
+
+```ts
+const collection = collect([1, 2, 3])
+
+collection.when(true, (collection, value) => collection.push(4))
+
+collection.when(false, (collection, value) => collection.push(5))
+
+collection.all()
+// [1, 2, 3, 4]
+```
+
+A third argument is a function to call when the value is falsy. A function as the first argument is called with the
+collection, and its result decides. `when()` returns what the function returns, or the collection when it returns
+nothing.
+
+#### `whenEmpty()`
+
+`whenEmpty()` calls the function when the collection is empty, and a second one, if you give it, when it isn't:
+
+```ts
+const collection = collect<string>([])
+
+collection.whenEmpty((collection) => collection.push('Adam'))
+
+collection.all()
+// ['Adam']
+```
+
+#### `whenNotEmpty()`
+
+`whenNotEmpty()` calls the function when the collection has items, and a second one, if you give it, when it is
+empty:
+
+```ts
+const collection = collect(['Michael', 'Tom'])
+
+collection.whenNotEmpty((collection) => collection.push('Adam'))
+
+collection.all()
+// ['Michael', 'Tom', 'Adam']
+```
+
+#### `where()`
+
+`where()` keeps the items whose key has the value, compared loosely:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Chair', price: 100 },
+  { product: 'Bookcase', price: 150 },
+  { product: 'Door', price: 100 },
+])
+
+collection.where('price', 100).all()
+// [{ product: 'Chair', price: 100 }, { product: 'Door', price: 100 }]
+```
+
+An operator goes between the key and the value: `=`, `==`, `===`, `!=`, `!==`, `<>`, `<`, `<=`, `>` or `>=`:
+
+```ts
+declare const collection: Collection<{ product: string; price: number }>
+// ---cut---
+collection.where('price', '>', 120).pluck('product').all()
+// ['Desk', 'Bookcase']
+```
+
+With a key alone, it keeps the items whose key is truthy. The key may be a function of the item.
+
+#### `whereBetween()`
+
+`whereBetween()` keeps the items whose key is between two values, both included:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Chair', price: 80 },
+  { product: 'Bookcase', price: 150 },
+  { product: 'Pencil', price: 30 },
+  { product: 'Door', price: 100 },
+])
+
+collection.whereBetween('price', [100, 200]).pluck('product').all()
+// ['Desk', 'Bookcase', 'Door']
+```
+
+#### `whereIn()`
+
+`whereIn()` keeps the items whose key is one of the values, compared strictly:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Chair', price: 100 },
+  { product: 'Bookcase', price: 150 },
+  { product: 'Door', price: 100 },
+])
+
+collection.whereIn('price', [150, 200]).pluck('product').all()
+// ['Desk', 'Bookcase']
+```
+
+Laravel's `whereIn()` compares loosely, and `whereInStrict()` strictly.
+
+#### `whereInStrict()`
+
+The same as [`whereIn()`](#wherein), which already compares strictly.
+
+#### `whereInstanceOf()`
+
+`whereInstanceOf()` keeps the items that are instances of a class, or of one of a list of classes, and types the
+result with them:
+
+```ts
+declare const people: Collection<User | Post>
+// ---cut---
+const users = people.whereInstanceOf(User)
+```
+
+#### `whereNotBetween()`
+
+`whereNotBetween()` keeps the items whose key is outside two values:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Chair', price: 80 },
+  { product: 'Bookcase', price: 150 },
+  { product: 'Pencil', price: 30 },
+  { product: 'Door', price: 100 },
+])
+
+collection.whereNotBetween('price', [100, 200]).pluck('product').all()
+// ['Chair', 'Pencil']
+```
+
+#### `whereNotIn()`
+
+`whereNotIn()` keeps the items whose key isn't one of the values, compared strictly:
+
+```ts
+const collection = collect([
+  { product: 'Desk', price: 200 },
+  { product: 'Chair', price: 100 },
+  { product: 'Bookcase', price: 150 },
+  { product: 'Door', price: 100 },
+])
+
+collection.whereNotIn('price', [150, 200]).pluck('product').all()
+// ['Chair', 'Door']
+```
+
+#### `whereNotInStrict()`
+
+The same as [`whereNotIn()`](#wherenotin), which already compares strictly.
+
+#### `whereNotNull()`
+
+`whereNotNull()` keeps the items whose key isn't `null` or `undefined`, or, with no key, the items that aren't:
+
+```ts
+const collection = collect([{ name: 'Desk' }, { name: null }, { name: 'Bookcase' }])
+
+collection.whereNotNull('name').all()
+// [{ name: 'Desk' }, { name: 'Bookcase' }]
+```
+
+#### `whereNull()`
+
+`whereNull()` keeps the items whose key is `null` or `undefined`, an item without the key included, or, with no key,
+the items that are:
+
+```ts
+const collection = collect([{ name: 'Desk' }, { name: null }, { name: 'Bookcase' }])
+
+collection.whereNull('name').all()
+// [{ name: null }]
+```
+
+#### `whereStrict()`
+
+`whereStrict()` is [`where()`](#where) with a key and a value, compared strictly:
+
+```ts
+collect([{ price: 100 }]).whereStrict('price', '100').count()
+// 0
+```
+
+#### `wrap()`
+
+Static. `Collection.wrap()` makes a collection of a value: an array's or a collection's items, nothing for `null` or
+`undefined`, and any other value as the one item:
+
+```ts
+Collection.wrap('John Doe').all()
+// ['John Doe']
+
+Collection.wrap(['John Doe']).all()
+// ['John Doe']
+
+Collection.wrap(null).all()
+// []
+```
+
+#### `zip()`
+
+`zip()` pairs each item with the item at the same index of the lists you give. A shorter list gives `undefined`:
+
+```ts
+const zipped = collect(['Chair', 'Desk']).zip([100, 200])
+
+zipped.toArray()
+// [['Chair', 100], ['Desk', 200]]
+```
+
+## Higher order messages
+
+Laravel's higher order messages, such as `$users->each->markAsVip()` and `$users->sum->votes`, aren't in Oriel.
+Pass a function or a key: `users.each((user) => user.markAsVip())`, `users.sum('votes')`.
+
+## Lazy collections
+
+### Introduction
+
+A lazy collection reads its items one at a time, as you ask for them, so a large query or file never sits in memory
+all at once. Its items can come from an async source, such as a database cursor, so it is async: you go through it
+with `for await`, and its methods that return a value return a promise.
+
+Your queries return one with `lazy()`, which reads the rows a chunk at a time, 1,000 by default:
+
+```ts
+for await (const user of User.lazy()) {
+  // ...
+}
+```
+
+### Creating lazy collections
+
+`LazyCollection.make()` takes a function that returns an iterable, or an async one. A generator function is the
+usual choice:
+
+```ts title="app/Support/logLines.ts"
+import { createReadStream } from 'node:fs'
+import { createInterface } from 'node:readline'
+import { LazyCollection } from '@orieljs/framework'
+
+export function logLines(path: string): LazyCollection<string> {
+  return LazyCollection.make(() => createInterface({ input: createReadStream(path) }))
+}
+```
+
+```ts
+declare function logLines(path: string): LazyCollection<string>
+// ---cut---
+const errors = await logLines('storage/logs/oriel.log')
+  .filter((line) => line.includes('"level":50'))
+  .take(10)
+  .collect()
+```
+
+`collection.lazy()` makes one from a collection.
+
+### Lazy collection methods
+
+A lazy collection has these methods. The first four return a new lazy collection, which reads nothing until you go
+through it; the others go through the items, and return a promise:
+
+- `map(callback)`: each item passed through the callback, which may be async;
+- `filter(callback)`: the items the callback passes;
+- `take(count)`: the first items, and stops reading after them;
+- `chunk(size)`: collections of `size` items;
+- `each(callback)`: calls the callback with each item and its index; returning `false` stops;
+- `first(callback?)`: the first item, or the first that passes the callback, or `undefined`;
+- `count()`: the number of items;
+- `collect()`: every item, in a `Collection`.
+
+```ts
+declare function logLines(path: string): LazyCollection<string>
+// ---cut---
+const count = await logLines('storage/logs/oriel.log')
+  .map((line) => JSON.parse(line) as { level: number })
+  .filter((entry) => entry.level >= 50)
+  .count()
+```
+
+> [!NOTE]
+> Laravel's lazy collections are synchronous, built on PHP generators, and have every method of a collection, and a
+> few of their own, such as `takeUntilTimeout()` and `remember()`. Oriel's are async, so they can read a database
+> cursor or a stream, and have the methods above: for any other, `collect()` the items you need first.