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

package/docs/migrations.md

@@ -0,0 +1,416 @@
+# Database: migrations
+
+Migrations are your database's version control: each one changes the schema, in code, so every copy of your app,
+your colleagues' and your servers', builds the same tables.
+
+## Introduction
+
+A migration is a class with an `up()` method, which changes the database, and a `down()` method, which undoes it.
+They describe tables with the `Schema` facade, which writes the SQL for SQLite, PostgreSQL and MySQL. Your migrations
+are in `database/migrations`, and a new app has five: its users, sessions and password reset tokens, its cache, its
+jobs, its personal access tokens and its notifications.
+
+## Generating migrations
+
+`make:migration` writes a migration in `database/migrations`. The name of the file starts with the date and time, so
+the migrations run in the order you write them:
+
+```sh
+node oriel make:migration create_flights_table
+```
+
+A name such as `create_flights_table` writes a migration that creates the `flights` table, and one such as
+`add_votes_to_users_table` a migration that changes `users`. `--create=flights` and `--table=users` name the table
+yourself, and `--path` writes the file in another folder.
+
+## Migration structure
+
+A migration's file default-exports the class. `up()` adds tables, columns or indexes; `down()` reverses what `up()`
+did:
+
+```ts title="database/migrations/2026_10_20_000000_create_flights_table.ts"
+import { Migration, Schema } from '@orieljs/framework'
+
+export default class extends Migration {
+  /** Run the migrations. */
+  async up() {
+    await Schema.create('flights', (table) => {
+      table.id()
+      table.string('name')
+      table.string('airline')
+      table.timestamps()
+    })
+  }
+
+  /** Reverse the migrations. */
+  async down() {
+    await Schema.dropIfExists('flights')
+  }
+}
+```
+
+#### Setting the migration connection
+
+A migration runs on the default connection, unless its `connection` names another:
+
+```ts
+export default class extends Migration {
+  override connection = 'pgsql'
+
+  async up() {
+    // ...
+  }
+
+  async down() {
+    // ...
+  }
+}
+```
+
+#### Migrations in a transaction
+
+On PostgreSQL and SQLite, each migration runs in a transaction, so one that fails halfway leaves nothing behind.
+MySQL can't roll back schema changes, so there a failed migration may leave part of its work. Set
+`withinTransaction = false` on a migration that mustn't run in a transaction.
+
+## Running migrations
+
+`migrate` runs the migrations that haven't run yet:
+
+```sh
+node oriel migrate
+```
+
+`migrate:status` shows which have run. `migrate` records each one in the `migrations` table, which it creates the first
+time, in a numbered batch: the migrations of one `migrate` are a batch, or one batch each with `--step`.
+
+When it finishes, outside production and in an app with a `types` folder, `migrate` writes `types/models.d.ts` again, so
+your models' types follow your tables (see the `model:types` command).
+
+#### Forcing migrations to run in production
+
+In production, `migrate` and the other commands that change your schema stop, unless you pass `--force`:
+
+```sh
+node oriel migrate --force
+```
+
+### Rolling back migrations
+
+`migrate:rollback` undoes the last batch, running each migration's `down()`. `--step` undoes that many migrations
+instead, and `--batch` a batch by its number:
+
+```sh
+node oriel migrate:rollback
+
+node oriel migrate:rollback --step=5
+
+node oriel migrate:rollback --batch=3
+```
+
+`migrate:reset` undoes every migration.
+
+#### Roll back and migrate using a single command
+
+`migrate:refresh` undoes every migration, then runs them all again; `--step` undoes and runs again only that many.
+`--seed` runs your seeders after it:
+
+```sh
+node oriel migrate:refresh
+
+node oriel migrate:refresh --seed
+```
+
+#### Drop all tables and migrate
+
+`migrate:fresh` drops every table, without running any `down()`, then runs every migration:
+
+```sh
+node oriel migrate:fresh
+
+node oriel migrate:fresh --seed
+```
+
+> [!WARNING]
+> `migrate:fresh` drops every table of the connection, those your migrations didn't make included.
+
+Each command takes `--database` to run on another connection, and `--path` to run the migrations of another folder.
+
+## Tables
+
+### Creating tables
+
+`Schema.create()` takes the table's name, and a function that defines its columns:
+
+```ts
+await Schema.create('users', (table) => {
+  table.id()
+  table.string('name')
+  table.string('email')
+  table.timestamps()
+})
+```
+
+#### Checking for table / column existence
+
+```ts
+if (await Schema.hasTable('users')) {
+  // The "users" table exists...
+}
+
+if (await Schema.hasColumn('users', 'email')) {
+  // The "users" table exists and has an "email" column...
+}
+```
+
+`hasColumns()` checks a list of columns, and `hasIndex()` an index.
+
+#### Database connection
+
+`Schema.connection()` works on another connection:
+
+```ts
+await Schema.connection('sqlite').create('users', (table) => {
+  table.id()
+})
+```
+
+### Updating tables
+
+`Schema.table()` changes a table that exists:
+
+```ts
+await Schema.table('users', (table) => {
+  table.integer('votes')
+})
+```
+
+### Renaming / dropping tables
+
+```ts
+await Schema.rename('posts', 'articles')
+
+await Schema.drop('users')
+
+await Schema.dropIfExists('users')
+```
+
+## Columns
+
+### Creating columns
+
+Inside `Schema.table()`, each column method adds a column:
+
+```ts
+await Schema.table('users', (table) => {
+  table.integer('votes')
+})
+```
+
+### Available column types
+
+| Method | Column |
+| --- | --- |
+| `id()` | An auto-incrementing `bigint` primary key, `id` |
+| `increments('id')`, `bigIncrements('id')` | An auto-incrementing primary key |
+| `integer()`, `bigInteger()`, `mediumInteger()`, `smallInteger()`, `tinyInteger()` | Integers |
+| `unsignedInteger()`, `unsignedBigInteger()`, `unsignedSmallInteger()`, `unsignedTinyInteger()` | Unsigned integers |
+| `foreignId('user_id')` | An unsigned `bigint` for a foreign key (see [Foreign key constraints](#foreign-key-constraints)) |
+| `decimal('amount', 8, 2)` | A fixed-point number, with its precision and scale |
+| `float('amount', 53)`, `double('amount')` | Floating-point numbers |
+| `boolean('confirmed')` | A boolean |
+| `string('name', 100)` | A `varchar`, 255 characters unless you give a length |
+| `char('code', 4)` | A fixed-length string |
+| `text()`, `mediumText()`, `longText()` | Text |
+| `json()`, `jsonb()` | JSON (`jsonb` on PostgreSQL) |
+| `uuid('id')`, `ulid('id')` | A UUID or a ULID |
+| `binary('data')` | Binary data |
+| `enum('difficulty', ['easy', 'hard'])` | One of a list of values |
+| `date()`, `dateTime()`, `time()`, `timestamp()` | Dates and times, with an optional precision |
+| `timestamps()` | Nullable `created_at` and `updated_at` timestamps |
+| `nullableTimestamps()` | The same |
+| `softDeletes()` | A nullable `deleted_at` timestamp, for soft deletes |
+| `rememberToken()` | A nullable `remember_token`, for "Remember me" |
+| `morphs('taggable')`, `nullableMorphs('taggable')` | `taggable_id` and `taggable_type`, for a polymorphic relation |
+
+SQLite stores every integer type as `integer`, and JSON as text.
+
+> [!NOTE]
+> Laravel's `foreignIdFor()`, `foreignUuid()`, `uuidMorphs()`, the time zone columns (`timestampTz()` and the like),
+> `year()`, `set()`, `ipAddress()`, `macAddress()`, generated columns (`virtualAs()`) and a column's own charset or
+> collation aren't in Oriel. `timestamps()` returns nothing, so it can't take modifiers.
+
+### Column modifiers
+
+Modifiers follow the column:
+
+```ts
+await Schema.table('users', (table) => {
+  table.string('email').nullable()
+})
+```
+
+| Modifier | Description |
+| --- | --- |
+| `nullable()` | The column takes `NULL` |
+| `default(value)` | The column's default value; `DB.raw()` writes an expression |
+| `unsigned()` | An unsigned integer (MySQL) |
+| `autoIncrement()` | An auto-incrementing integer, the primary key |
+| `primary()`, `unique()`, `index()` | An index on the column (see [Indexes](#indexes)) |
+| `useCurrent()` | A timestamp column defaults to the current time |
+| `useCurrentOnUpdate()` | A timestamp column takes the current time when the row changes (MySQL) |
+| `comment('...')` | A comment on the column (MySQL and PostgreSQL) |
+| `after('column')`, `first()` | Where the column goes (MySQL) |
+
+#### Default expressions
+
+A default given with `DB.raw()` is written as SQL, so it can call a function:
+
+```ts
+await Schema.create('flights', (table) => {
+  table.id()
+  table.json('movies').default(DB.raw('(JSON_ARRAY())'))
+  table.timestamp('created_at').default(DB.raw('CURRENT_TIMESTAMP'))
+})
+```
+
+### Modifying columns
+
+`change()` gives an existing column a new definition. The column becomes exactly what you write, so repeat every
+modifier you keep:
+
+```ts
+await Schema.table('users', (table) => {
+  table.string('name', 50).nullable().change()
+})
+```
+
+Here `name` becomes a nullable `varchar(50)`; without `nullable()`, it would become `NOT NULL`, which fails while a row
+holds `NULL`.
+
+In one `Schema.table()`, changes run after the columns you add and before everything else, such as renames, indexes
+and drops: to change a column you rename, rename it in a `Schema.table()` of its own first.
+
+### Renaming columns
+
+```ts
+await Schema.table('users', (table) => {
+  table.renameColumn('from', 'to')
+})
+```
+
+### Dropping columns
+
+`dropColumn()` takes a column, or a list of them:
+
+```ts
+await Schema.table('users', (table) => {
+  table.dropColumn(['votes', 'avatar', 'location'])
+})
+```
+
+`dropTimestamps()`, `dropSoftDeletes()`, `dropRememberToken()` and `dropMorphs('taggable')` drop the columns their
+creating method added.
+
+## Indexes
+
+### Creating indexes
+
+`unique()` after a column makes it unique, and `index()` indexes it:
+
+```ts
+await Schema.table('users', (table) => {
+  table.string('email').unique()
+})
+```
+
+On the table, they take one column or a list, for a compound index, and a name:
+
+```ts
+await Schema.table('users', (table) => {
+  table.index(['account_id', 'created_at'])
+  table.unique('email', 'unique_email')
+  table.primary(['id', 'parent_id'])
+})
+```
+
+An index without a name is named after the table, the columns and its kind: `users_email_unique`.
+
+### Dropping indexes
+
+`dropUnique()` and `dropIndex()` take the index's name, or its columns, from which the name is made; `dropPrimary()`
+takes the name, `{table}_pkey` unless you give one:
+
+```ts
+await Schema.table('users', (table) => {
+  table.dropUnique('users_email_unique')
+  table.dropIndex(['account_id', 'created_at'])
+})
+```
+
+### Foreign key constraints
+
+`foreign()` adds a foreign key: the column, the column it refers to, and the table:
+
+```ts
+await Schema.table('posts', (table) => {
+  table.unsignedBigInteger('user_id')
+
+  table.foreign('user_id').references('id').on('users')
+})
+```
+
+`foreignId()` with `constrained()` does both in one line: `constrained()` guesses the table from the column's name,
+`users` for `user_id`, or takes it:
+
+```ts
+await Schema.table('posts', (table) => {
+  table.foreignId('user_id').constrained()
+
+  table.foreignId('author_id').constrained('users')
+})
+```
+
+The actions on delete and update follow:
+
+```ts
+await Schema.table('posts', (table) => {
+  table.foreignId('user_id').constrained().cascadeOnDelete()
+})
+```
+
+| Method | Action |
+| --- | --- |
+| `cascadeOnDelete()`, `cascadeOnUpdate()` | Delete or update the child rows too |
+| `restrictOnDelete()`, `restrictOnUpdate()` | Refuse the delete or the update |
+| `nullOnDelete()`, `nullOnUpdate()` | Set the child's column to `NULL` |
+| `noActionOnDelete()`, `noActionOnUpdate()` | Leave the check to the end of the statement |
+
+`dropForeign()` drops a foreign key, given its columns: `table.dropForeign(['user_id'])`.
+`dropConstrainedForeignId('user_id')` drops the key and the column.
+
+#### Toggling foreign key constraints
+
+```ts
+await Schema.enableForeignKeyConstraints()
+
+await Schema.disableForeignKeyConstraints()
+
+await Schema.withoutForeignKeyConstraints(async () => {
+  // Constraints disabled within this closure...
+})
+```
+
+## SQLite and schema changes
+
+SQLite can't change a column, or add or drop a primary or foreign key, on a table that exists. Oriel does these as
+Laravel does: it builds the table again with the new definition, copies the rows over, and drops the old one. You
+write the migration as for any database, with `Schema.table()`.
+
+Each migration on SQLite runs in a transaction with foreign keys turned off, as SQLite asks for schema changes, and
+checks every foreign key before it commits: a migration that leaves a row pointing at a missing parent fails, and
+nothing of it is kept. With foreign keys off, `ON DELETE` and `ON UPDATE` actions don't run inside the migration, so
+change the child rows yourself first, or set `withinTransaction = false`.
+
+> [!NOTE]
+> Laravel's `schema:dump`, `db:wipe`, `migrate --pretend`, full text indexes and `renameIndex()` aren't in Oriel.

package/docs/mocking.md

@@ -0,0 +1,264 @@
+# Fakes
+
+A fake stands in for a service in your tests: it records what your code asks of it, does nothing else, and lets you
+check what was asked. Oriel has fakes for the bus, events, mail, notifications, queues and storage.
+
+## Introduction
+
+`Mail.fake()` and the other `fake()` methods put a fake in place of the service, for the rest of the test, and return
+it. Check your code's work on the fake they return:
+
+```ts title="tests/Feature/OrderShipment.test.ts"
+import { Mail } from '@orieljs/framework'
+import { test } from 'vitest'
+import { OrderShipped } from '../../app/Mail/OrderShipped'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot()
+
+test('orders can be shipped', async () => {
+  const mail = Mail.fake()
+
+  await t.post('/orders/1/shipment')
+
+  mail.assertSent(OrderShipped)
+})
+```
+
+Each test has a new application, so a fake ends with its test.
+
+> [!NOTE]
+> Laravel's facades also have Mockery's `shouldReceive()`, `spy()` and `partialMock()`, and its tests have
+> `$this->mock()`. Oriel has none of them: for a service without a fake, put a stand-in of your own in its place with
+> its facade's `swap()`, or `t.app.instance(Service, standIn)`. Vitest's `vi.fn()` and `vi.spyOn()` work on any
+> object. [Facades](facades.md#facades-vs-dependency-injection) shows `swap()`.
+
+## Bus fake
+
+`Bus.fake()` records the jobs your code dispatches, and runs none of them:
+
+```ts title="tests/Feature/Podcasts.test.ts"
+import { Bus } from '@orieljs/framework'
+import { RefreshDatabase } from '@orieljs/framework/testing'
+import { test } from 'vitest'
+import { OptimizePodcast } from '../../app/Jobs/OptimizePodcast'
+import { ProcessPodcast } from '../../app/Jobs/ProcessPodcast'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot({ uses: [RefreshDatabase] })
+
+test('podcasts can be published', async () => {
+  const bus = Bus.fake()
+
+  await t.post('/podcasts', { title: 'Episode 1' })
+
+  bus.assertDispatched(ProcessPodcast, (job) => job.podcast.title === 'Episode 1')
+  bus.assertDispatched(ProcessPodcast, 1)
+  bus.assertNotDispatched(OptimizePodcast)
+})
+```
+
+The second argument is a function that receives each job and returns `true` for the one you expect, or a number of
+dispatches. Give `fake()` a list of jobs to fake only those, and the others run as usual: `Bus.fake([ProcessPodcast])`.
+`BusFake.fakeExcept([ShipOrder])`, from `@orieljs/framework/testing`, fakes all but those.
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertDispatched(job, filterOrCount?)`, `assertDispatchedTimes(job, times)` | The job was dispatched, matching the filter, or that many times |
+| `assertNotDispatched(job, filter?)`, `assertNothingDispatched()` | It wasn't, or no job was |
+| `assertDispatchedSync(job)`, `assertNotDispatchedSync(job)` | It was dispatched with `dispatchSync()`, or wasn't |
+| `assertDispatchedAfterResponse(job)`, `assertNotDispatchedAfterResponse(job)` | It was dispatched to run after the response, or wasn't |
+| `assertDispatchedWithoutChain(job)` | It was dispatched with no chain |
+
+`bus.dispatched(ProcessPodcast)` returns the dispatched jobs, to check them with Vitest's `expect()`, and
+`dispatchedSync()` and `dispatchedAfterResponse()` the others.
+
+### Job chains
+
+`assertChained()` checks a chain, by class or by instance:
+
+```ts
+import { BusFake } from '@orieljs/framework/testing'
+import { OptimizePodcast } from './app/Jobs/OptimizePodcast'
+import { ProcessPodcast } from './app/Jobs/ProcessPodcast'
+import { PublishPodcast } from './app/Jobs/PublishPodcast'
+
+declare const bus: BusFake
+// ---cut---
+bus.assertChained([ProcessPodcast, OptimizePodcast, PublishPodcast])
+```
+
+An instance in the list matches a job of its class with the same fields.
+
+### Job batches
+
+`assertBatched()` receives each batch, with its `name` and `jobs`, and passes when the function returns `true` for one:
+
+```ts
+import { BusFake } from '@orieljs/framework/testing'
+
+declare const bus: BusFake
+// ---cut---
+bus.assertBatched((batch) => batch.name === 'import-csv' && batch.jobs.length === 10)
+```
+
+`assertBatchCount(count)` checks the number of batches, and `assertNothingBatched()` that there are none.
+
+## Event fake
+
+`Event.fake()` records the events your code dispatches, and runs none of their listeners:
+
+```ts
+// @filename: app/Events/OrderShipped.ts
+export class OrderShipped {
+  constructor(readonly orderId: number) {}
+}
+// ---cut---
+import { OrderShipped } from './app/Events/OrderShipped'
+
+const events = Event.fake()
+
+// Ship the order...
+
+events.assertDispatched(OrderShipped, (event) => event.orderId === 1)
+events.assertDispatchedTimes(OrderShipped, 1)
+events.assertNotDispatched('order.cancelled')
+```
+
+`assertNothingDispatched()` checks that no event was dispatched at all.
+
+`assertListening(OrderShipped, SendShipmentNotification)` checks that a listener is registered for an event, and
+`dispatched(event)` returns the dispatched events.
+
+> [!WARNING]
+> Model events, such as `creating` and `saved`, are events too. `Event.fake()` with no list stops them as well, so a
+> model whose `creating` sets a value doesn't set it. Fake only the events you check: `Event.fake([OrderShipped])`.
+
+`EventFake.fakeExcept([OrderCreated])`, from `@orieljs/framework/testing`, fakes every event but those.
+
+## Mail fake
+
+`Mail.fake()` records each mail your code sends or queues, and sends nothing:
+
+```ts
+import { OrderShipped } from './app/Mail/OrderShipped'
+
+const mail = Mail.fake()
+
+// Ship the order...
+
+mail.assertSent(OrderShipped, (mailable, record) => record.hasTo('taylor@example.com'))
+mail.assertSent(OrderShipped, 1)
+mail.assertNotQueued(OrderShipped)
+```
+
+The filter receives the mailable and its record, which has `hasTo()`, `hasCc()`, `hasBcc()` and `hasSubject()`. A
+mailable that would be queued counts as queued, not sent.
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertSent(mailable, filterOrCount?)`, `assertSentTimes(mailable, times)` | The mail was sent, matching the filter, or that many times |
+| `assertNotSent(mailable)`, `assertNothingSent()`, `assertSentCount(count)` | It wasn't sent, no mail was, or that many were |
+| `assertQueued(mailable, filterOrCount?)`, `assertNotQueued(mailable)` | It was queued, or wasn't |
+| `assertNothingQueued()`, `assertQueuedCount(count)` | No mail was queued, or that many were |
+| `assertOutgoingCount(count)`, `assertNothingOutgoing()` | That many mails were sent or queued, or none |
+
+`mail.sent(OrderShipped)` and `mail.queued(OrderShipped)` return the mailables. Nothing is rendered, so the fake
+doesn't check your views.
+
+## Notification fake
+
+`Notification.fake()` records each notification your code sends, and delivers none:
+
+```ts
+import { User } from './app/Models/User'
+import { InvoicePaid } from './app/Notifications/InvoicePaid'
+
+const notifications = Notification.fake()
+
+const user = await User.findOrFail(1)
+
+// Pay the invoice...
+
+notifications.assertSentTo(user, InvoicePaid, (notification, channels) => channels.includes('mail'))
+notifications.assertNotSentTo(user, InvoicePaid, (notification) => notification.amount === '0')
+notifications.assertCount(1)
+```
+
+The filter receives the notification, its channels and the notifiable. `assertSentTo()` also takes a list of
+notifiables, which must each have the notification.
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertSentTo(notifiable, notification, filterOrCount?)` | The notifiable was sent the notification |
+| `assertSentToTimes(notifiable, notification, times)` | It was sent it that many times |
+| `assertNotSentTo(notifiable, notification, filter?)`, `assertNothingSentTo(notifiable)` | It wasn't sent it, or anything |
+| `assertSentTimes(notification, times)`, `assertCount(count)` | That many were sent, of that class or of all |
+| `assertNothingSent()` | No notification was sent |
+| `assertSentOnDemand(notification, filterOrCount?)` | It was sent to a route, with `Notification.route()` |
+
+`notifications.sent(user, InvoicePaid)` returns the notifications the user was sent.
+
+## Queue fake
+
+`Queue.fake()` records the jobs pushed on the queue, and runs none of them. Unlike `Bus.fake()`, it sees the queue
+each job is pushed on:
+
+```ts
+import { ProcessPodcast } from './app/Jobs/ProcessPodcast'
+
+const queue = Queue.fake()
+
+// Publish the podcast...
+
+queue.assertPushed(ProcessPodcast, 1)
+queue.assertPushedOn('audio', ProcessPodcast)
+queue.assertPushed(ProcessPodcast, (job, queueName) => queueName === 'audio')
+```
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertPushed(job, filterOrCount?)`, `assertPushedTimes(job, times)` | The job was pushed, matching the filter, or that many times |
+| `assertPushedOn(queue, job, filter?)` | It was pushed on that queue |
+| `assertNotPushed(job, filter?)`, `assertNothingPushed()` | It wasn't, or no job was |
+| `assertCount(count)` | That many jobs were pushed |
+| `assertPushedWithChain(job, chain)`, `assertPushedWithoutChain(job)` | It was pushed with that chain after it, or with none |
+
+`queue.pushed(ProcessPodcast)` returns the pushed jobs. Give `fake()` a list of jobs to fake only those.
+
+## Storage fake
+
+`Storage.fake()` puts a disk in memory in place of one of yours, so a test writes no files, and returns it:
+
+```ts title="tests/Feature/Avatar.test.ts"
+import { Storage } from '@orieljs/framework'
+import { FakeFile } from '@orieljs/framework/testing'
+import { test } from 'vitest'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot()
+
+test('albums can be uploaded', async () => {
+  const disk = Storage.fake('photos')
+
+  await t.post('/photos', { photos: [FakeFile.image('photo1.jpg'), FakeFile.image('photo2.jpg')] })
+
+  await disk.assertExists(['photo1.jpg', 'photo2.jpg'])
+  await disk.assertMissing('missing.jpg')
+  await disk.assertCount('', 2)
+})
+```
+
+With no name, it fakes the default disk. The assertions read the disk, so they are async: `await` each one.
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertExists(paths, contents?)` | Each file is on the disk, with those contents |
+| `assertMissing(paths)` | No file is at the paths |
+| `assertCount(folder, count, recursive?)` | The folder has that many files |
+| `assertDirectoryEmpty(folder)` | The folder has no files |
+
+## Interacting with time
+
+`t.travelTo()`, `t.travel()` and `t.freezeTime()` move the clock your code reads. [Time travel](time-travel.md) covers
+them.