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

package/docs/eloquent-collections.md

@@ -0,0 +1,218 @@
+# Eloquent: collections
+
+Every query of models returns an `EloquentCollection`: a collection with Laravel's collection methods, and a few more
+that know about models and their keys.
+
+## Introduction
+
+`get()`, `all()`, a has-many relation and an eager load all return an `EloquentCollection`. It has every method of
+[Collections](collections.md), and it is iterable:
+
+```ts
+const users = await User.whereNotNull('email_verified_at').get()
+
+for (const user of users) {
+  console.log(user.name)
+}
+```
+
+Methods that keep the same models, such as `filter()`, `sortBy()` and `where()`, return an `EloquentCollection`.
+Methods that make other values, such as `map()` and `pluck()`, return a plain `Collection`:
+
+```ts
+const names = (await User.all()).filter((user) => user.email_verified_at !== null).map((user) => user.name)
+```
+
+`toBase()` returns the models in a plain collection.
+
+> [!WARNING]
+> A collection's `sum()`, `avg()`, `min()`, `max()` and `median()` count numbers only. A column read as a string, such
+> as a `decimal:2` cast or a large integer on PostgreSQL, is left out: convert it first, with
+> `sum((order) => Number(order.price))`.
+
+## Available methods
+
+#### `append(attributes)`
+
+`append()` adds attributes to every model's `toArray()` and JSON, as a model's `appends` does (see
+[Appending values to JSON](eloquent-mutators.md#appending-values-to-json)).
+
+#### `contains(key)`
+
+`contains()` tells you whether the collection holds a model, given the model or its key:
+
+```ts
+declare const user: User
+// ---cut---
+const users = await User.all()
+
+users.contains(1)
+
+users.contains(user)
+```
+
+With a key and a value, or a function, it is the collection's `contains()`. `containsStrict()` matches a model only by
+identity, not by key.
+
+#### `diff(items)`
+
+`diff()` returns the models whose keys aren't among the models you give:
+
+```ts
+const users = (await User.all()).diff(await User.whereIn('id', [1, 2, 3]).get())
+```
+
+#### `except(...keys)`
+
+`except()` returns the models without these keys:
+
+```ts
+const users = (await User.all()).except(1, 2, 3)
+```
+
+#### `find(key)`
+
+`find()` returns the model with that key, or `undefined`. Given a list of keys, it returns a collection of those
+models. `findOrFail()` throws a `ModelNotFoundError` instead of returning `undefined`:
+
+```ts
+const users = await User.all()
+
+const user = users.find(1)
+
+const some = users.find([1, 2])
+```
+
+#### `fresh(...relations)`
+
+`fresh()` reads every model again from the database, with the relations you name loaded, in one query:
+
+```ts
+const users = await User.all()
+
+const fresh = await users.fresh('posts')
+```
+
+#### `intersect(items)`
+
+`intersect()` returns the models whose keys are also among the models you give:
+
+```ts
+const users = (await User.all()).intersect(await User.whereIn('id', [1, 2, 3]).get())
+```
+
+#### `load(...relations)`
+
+`load()` loads relations on every model, one query per relation, and takes the forms `with()` takes:
+
+```ts
+const users = await User.all()
+
+await users.load('posts', 'roles')
+
+await users.load({ posts: (query) => query.where('title', 'like', '%Oriel%') })
+```
+
+`loadCount()` adds the counts, and `loadSum()`, `loadAvg()`, `loadMin()`, `loadMax()` and `loadExists()` the other
+aggregates, on every model.
+
+#### `loadMissing(...relations)`
+
+`loadMissing()` loads the relations that aren't loaded yet on each model:
+
+```ts
+const users = await User.all()
+
+await users.loadMissing('posts', 'roles')
+```
+
+#### `modelKeys()`
+
+`modelKeys()` returns the models' primary keys:
+
+```ts
+const keys = (await User.all()).modelKeys() // [1, 2, 3, 4, 5]
+```
+
+#### `makeVisible(attributes)` / `makeHidden(attributes)`
+
+`makeVisible()` shows attributes that the model hides in its `toArray()` and JSON, and `makeHidden()` hides more, on
+every model. `setVisible()` and `setHidden()` replace the lists:
+
+```ts
+const users = (await User.all()).makeVisible(['password', 'remember_token'])
+
+const safe = (await User.all()).makeHidden(['email'])
+```
+
+#### `only(...keys)`
+
+`only()` returns the models with these keys:
+
+```ts
+const users = (await User.all()).only(1, 2, 3)
+```
+
+#### `toQuery()`
+
+`toQuery()` returns a query that matches the collection's models, by their keys, so you can update them all at once:
+
+```ts
+const users = await User.whereNull('email_verified_at').get()
+
+await users.toQuery().update({ email_verified_at: new Date() })
+```
+
+The models must all be of one class, and the collection mustn't be empty.
+
+#### `unique(key)`
+
+`unique()` returns one model per key. Given an attribute or a function, it is the collection's `unique()`:
+
+```ts
+const users = (await User.all()).unique()
+```
+
+#### `merge(items)`
+
+`merge()` adds the models you give, replacing those with the same key.
+
+## Custom collections
+
+A model returns its collections from `newCollection()`. Override it to return a subclass of `EloquentCollection` with
+your own methods:
+
+```ts title="app/Models/Team.ts"
+import { EloquentCollection, Model } from '@orieljs/framework'
+
+export class TeamCollection<T extends Model> extends EloquentCollection<T> {
+  names(): string[] {
+    return this.map((team) => String(team.getAttribute('name'))).all()
+  }
+}
+
+export class Team extends Model {
+  override newCollection<T extends Model>(this: T, models: T[] = []): TeamCollection<T> {
+    return new TeamCollection(models)
+  }
+}
+```
+
+Every query, relation and eager load of `Team` then returns a `TeamCollection`. Their type is still
+`EloquentCollection`, so narrow it to call your methods:
+
+```ts
+declare class Team extends Model {}
+declare class TeamCollection<T extends Model> extends EloquentCollection<T> {
+  names(): string[]
+}
+const teams = await Team.all()
+// ---cut---
+if (teams instanceof TeamCollection) {
+  console.log(teams.names())
+}
+```
+
+> [!NOTE]
+> Laravel names the collection class with a `#[CollectedBy]` attribute or a `newCollection()` method. Oriel uses the
+> method.

package/docs/eloquent-factories.md

@@ -0,0 +1,255 @@
+# Eloquent: factories
+
+A factory makes models with realistic attribute values, for your tests and your seeders: one model, or a hundred, with
+their related models.
+
+## Introduction
+
+Each factory is a class in `database/factories` that describes one model's default attributes. A new app has
+`UserFactory`:
+
+```ts title="database/factories/UserFactory.ts"
+import { Factory, Hash, fake } from '@orieljs/framework'
+import { User } from '../../app/Models/User'
+
+type Attributes = Record<string, unknown>
+
+/** The password every factory-made user has, hashed once. */
+let password: string | undefined
+
+export default class UserFactory extends Factory<User> {
+  model = User
+
+  definition() {
+    return {
+      name: fake().name(),
+      email: fake().unique().safeEmail(),
+      email_verified_at: new Date(),
+      password: 'password',
+      remember_token: fake().lexify('??????????'),
+    }
+  }
+
+  /** Indicate that the model's email address should be unverified. */
+  unverified() {
+    return this.state({ email_verified_at: null })
+  }
+
+  /** Hashes the default password (the model has no hashed cast). */
+  protected override async attributesFor(overrides: Attributes, index: number): Promise<Attributes> {
+    const attributes = await super.attributesFor(overrides, index)
+    if (attributes.password === 'password') attributes.password = password ??= await Hash.make('password')
+    return attributes
+  }
+}
+```
+
+`model` names the model, and `definition()` returns the attributes every model gets, unless you give others. `fake()`
+makes the values: names, email addresses, sentences, numbers and dates.
+
+Factories set every attribute they are given, whatever the model's `fillable` says.
+
+## Defining model factories
+
+### Generating factories
+
+`make:factory` writes a factory in `database/factories`, named after its model:
+
+```sh
+node oriel make:factory PostFactory
+```
+
+Oriel finds the factories in `database/factories` by itself when your app runs through `oriel`, as a command or under
+`oriel serve`, and in your tests: every factory class a file there exports. An app started another way, such as with
+`public/index.ts`, registers its factories with `Factory.register()`, or `User.factory()` throws "No factory registered
+for [User].".
+
+A model's `factory()` returns its factory. To have its own methods, such as `unverified()`, typed, declare it, as a new
+app's `User` does:
+
+```ts title="app/Models/User.ts"
+// @filename: database/factories/UserFactory.ts
+import { Factory } from '@orieljs/framework'
+import { User } from '../../app/Models/User'
+export default class UserFactory extends Factory<User> {
+  model = User
+  definition() {
+    return {}
+  }
+}
+// ---cut---
+import { Model, type HasFactory } from '@orieljs/framework'
+import type UserFactory from '../../database/factories/UserFactory'
+
+export class User extends Model {
+  declare static factory: HasFactory<UserFactory>
+}
+```
+
+### Factory states
+
+A state changes some attributes. Write it as a method that calls `state()`:
+
+```ts
+class PostFactory extends Factory<Post> {
+  model = Post
+
+  definition() {
+    return { title: fake().sentence(), slug: fake().slug(), body: fake().paragraph() }
+  }
+
+  /** Indicate that the post is published. */
+  published() {
+    return this.state({ published_at: new Date() })
+  }
+}
+```
+
+`state()` also takes a function, which receives the attributes so far and the model's place in the batch:
+
+```ts
+const users = await User.factory(3)
+  .state((attributes, { index }) => ({ name: `User ${index + 1}` }))
+  .make()
+```
+
+#### "Trashed" state
+
+`trashed()` makes soft-deleted models, with a `deleted_at` date:
+
+```ts
+const post = await Post.factory().trashed().create()
+```
+
+### Factory callbacks
+
+`afterMaking()` and `afterCreating()` run a function with each model made or created. Register them in the factory's
+`configure()`:
+
+```ts
+class UserFactory extends Factory<User> {
+  model = User
+
+  definition() {
+    return { name: fake().name(), email: fake().unique().safeEmail() }
+  }
+
+  override configure() {
+    return this.afterMaking((user) => {
+      // ...
+    }).afterCreating((user) => {
+      // ...
+    })
+  }
+}
+```
+
+## Creating models using factories
+
+### Instantiating models
+
+`make()` makes models without saving them. With `count()`, or a number given to `factory()`, it makes a collection: a
+plain `Collection`, where Laravel's is an Eloquent collection, so `modelKeys()` and `load()` aren't on it:
+
+```ts
+const user = await User.factory().make()
+
+const users = await User.factory().count(3).make()
+
+const others = await User.factory(3).make()
+```
+
+#### Applying states
+
+```ts
+const users = await User.factory().count(5).unverified().make()
+```
+
+#### Overriding attributes
+
+Give `make()` or `create()` the attributes to set:
+
+```ts
+const user = await User.factory().make({ name: 'Abigail Otwell' })
+```
+
+### Persisting models
+
+`create()` makes the models and saves them:
+
+```ts
+const user = await User.factory().create()
+
+const users = await User.factory().count(3).create()
+```
+
+`makeOne()` and `createOne()` always return one model, typed as one. `createMany()` takes a number, or a list of
+attributes, one model each. `raw()` returns the attributes without making a model.
+
+### Sequences
+
+`sequence()` gives the models of a batch attributes in turn, starting again after the last:
+
+```ts
+const users = await User.factory().count(10).sequence({ name: 'Taylor' }, { name: 'Abigail' }).create()
+```
+
+Five users are named Taylor, and five Abigail.
+
+## Factory relationships
+
+### Has many relationships
+
+`has()` creates related models with each model, through a relation of the model, named after the related model in the
+plural unless you name it:
+
+```ts
+const user = await User.factory().has(Post.factory().count(3)).create()
+
+const writer = await User.factory().has(Post.factory().count(3), 'posts').create()
+```
+
+### Belongs to relationships
+
+`for()` sets the parent of the models it makes, a model you have or one its factory creates once for all of them:
+
+```ts
+const user = await User.factory().createOne()
+
+const posts = await Post.factory().count(3).for(user, 'author').create()
+```
+
+An attribute of a factory can also be another factory: the factory creates that model, and the attribute takes its
+key, as `author_id: UserFactory.new()` does in a post's definition.
+
+### Many to many relationships
+
+`has()` works on a many-to-many relation too, and its third argument gives the pivot table's extra columns:
+
+```ts
+const user = await User.factory().has(Role.factory().count(3), 'roles', { active: 1 }).create()
+```
+
+### Polymorphic relationships
+
+`has()` creates the models of a `morphMany()` relation, and `for()` sets the owner of a `morphTo()` one.
+
+> [!NOTE]
+> Laravel's "magic" relationship methods (`hasPosts()`, `forUser()`), `hasAttached()`, `recycle()` and the `Sequence`
+> class aren't in Oriel. Use `has()` with its pivot argument, `for()`, and `sequence()`.
+
+## The `fake()` helper
+
+`fake()` returns the generator factories use: a seedable subset of Faker's methods. `unique()` gives a value that the
+generator hasn't given before, and `seed()` makes the values repeat from one run to the next:
+
+| Kind | Methods |
+| --- | --- |
+| People and companies | `firstName()`, `lastName()`, `name()`, `userName()`, `email()`, `safeEmail()`, `company()`, `phoneNumber()` |
+| Text | `word()`, `words()`, `sentence()`, `sentences()`, `paragraph()`, `paragraphs()`, `text()`, `title()`, `slug()`, `url()`, `city()`, `country()` |
+| Numbers | `numberBetween()`, `randomNumber()`, `randomFloat()`, `randomDigit()`, `random()` (a number from 0 to 1), `boolean()`, `uuid()` |
+| Patterns and dates | `numerify('###')`, `lexify('???')`, `bothify('##??')`, `hexColor()`, `dateTime()`, `dateTimeBetween('-1 year', 'now')`, `date()` |
+
+> [!NOTE]
+> Laravel's factories use the full Faker library, with its locales. Oriel's `fake()` has the methods above, in
+> English. To pick from a list, use `fake().numberBetween()` as an index.