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

package/docs/scheduling.md

@@ -0,0 +1,277 @@
+# Task scheduling
+
+The scheduler runs your app's recurring tasks: you define them in your code, and one cron entry on your server runs
+them all.
+
+## Introduction
+
+Apps once needed a cron entry for every task. Oriel's scheduler, as Laravel's, keeps the whole schedule in your code, in
+`routes/console.ts`, so it is in your repository with the rest of your app. Your server needs one cron entry, which runs
+`schedule:run` every minute (see [Running the scheduler](#running-the-scheduler)).
+
+## Defining schedules
+
+Define your tasks with the `Schedule` facade, in `routes/console.ts`. This one empties a table every day at midnight:
+
+```ts title="routes/console.ts"
+import { DB, Schedule } from '@orieljs/framework'
+
+Schedule.call(async () => {
+  await DB.table('recent_users').delete()
+}).daily()
+```
+
+A task is a console command, a closure or a job. `node oriel schedule:list` lists the tasks you have defined, each
+with its cron expression.
+
+### Scheduling commands
+
+`Schedule.command()` runs a console command by its name, with its arguments and options in an array, or written into
+the name:
+
+```ts
+Schedule.command('emails:send', ['taylor', '--force']).daily()
+
+Schedule.command('emails:send taylor --force').daily()
+```
+
+A command fails when it ends with an exit code other than 0.
+
+> [!NOTE]
+> Laravel runs each scheduled Artisan command in a PHP process of its own. Oriel runs it in the `schedule:run`
+> process, through your app's console kernel, as `Artisan.call()` does: there is no process to start, and your
+> commands share that process with the other tasks.
+
+### Scheduling closures
+
+`Schedule.call()` runs a function, which may be async, as in the [example above](#defining-schedules). It fails when
+it throws, or returns `false`.
+
+### Scheduling queued jobs
+
+`Schedule.job()` takes a job, and the queue and the connection to push it onto:
+
+```ts
+// @filename: app/Jobs/Heartbeat.ts
+import { Queueable } from '@orieljs/framework'
+export class Heartbeat extends Queueable {
+  async handle(): Promise<void> {}
+}
+// ---cut---
+import { Heartbeat } from './app/Jobs/Heartbeat'
+
+Schedule.job(new Heartbeat(), 'heartbeats', 'redis').everyFiveMinutes()
+```
+
+The job is made when `routes/console.ts` loads, which is on every `node oriel` command, so don't read the database to
+make it: a job that needs a model finds it in its `handle()`.
+
+A queued job, such as one that extends `Queueable`, is pushed onto its queue each time the task runs, and a worker runs
+it. Any other job runs at once, in the scheduler's process.
+
+> [!NOTE]
+> A job that runs in the scheduler's process fails, as a closure does, when its `handle()` returns `false`. Laravel's
+> `Schedule::job()` doesn't look at what the job returns.
+
+### Schedule frequency options
+
+A task's frequency is a method on it:
+
+| Method | Runs the task |
+| --- | --- |
+| `cron('* * * * *')` | On a cron expression of your own |
+| `everySecond()`, `everyTwoSeconds()`, `everyFiveSeconds()`, `everyTenSeconds()`, `everyFifteenSeconds()`, `everyTwentySeconds()`, `everyThirtySeconds()` | Every second, or every 2, 5, 10, 15, 20 or 30 seconds (see [Sub-minute tasks](#sub-minute-tasks)) |
+| `everyMinute()` | Every minute |
+| `everyTwoMinutes()`, `everyThreeMinutes()`, `everyFourMinutes()`, `everyFiveMinutes()`, `everyTenMinutes()`, `everyFifteenMinutes()`, `everyThirtyMinutes()` | Every 2, 3, 4, 5, 10, 15 or 30 minutes |
+| `hourly()` | Every hour, on the hour |
+| `hourlyAt(17)` | Every hour at 17 minutes past (or a list of minutes: `hourlyAt([0, 30])`) |
+| `everyOddHour(minute)`, `everyTwoHours(minute)`, `everyThreeHours(minute)`, `everyFourHours(minute)`, `everySixHours(minute)` | Every odd hour, or every 2, 3, 4 or 6 hours, at `minute` past (0 when left out) |
+| `daily()` | Every day at midnight |
+| `dailyAt('13:00')`, `at('13:00')` | Every day at 13:00 |
+| `twiceDaily(1, 13)` | Every day at 1:00 and 13:00 |
+| `twiceDailyAt(1, 13, 15)` | Every day at 1:15 and 13:15 |
+| `weekly()` | Every Sunday at 00:00 |
+| `weeklyOn(1, '8:00')` | Every week on Monday at 8:00 (or a list of days) |
+| `monthly()` | On the first day of every month at 00:00 |
+| `monthlyOn(4, '15:00')` | Every month on the 4th at 15:00 |
+| `twiceMonthly(1, 16, '13:00')` | Every month on the 1st and the 16th at 13:00 |
+| `lastDayOfMonth('15:00')` | On the last day of every month at 15:00 |
+| `quarterly()` | On the first day of every quarter at 00:00 |
+| `quarterlyOn(4, '14:00')` | Every quarter on the 4th at 14:00 |
+| `yearly()` | On the first day of every year at 00:00 |
+| `yearlyOn(6, 1, '17:00')` | Every year on June 1st at 17:00 |
+
+Combine a frequency with the constraints below to narrow it, such as a task that runs every hour on weekdays:
+
+```ts
+Schedule.command('reports:send').weekdays().hourly()
+```
+
+#### Day constraints
+
+`weekdays()`, `weekends()`, `mondays()`, `tuesdays()`, `wednesdays()`, `thursdays()`, `fridays()`, `saturdays()` and
+`sundays()` limit a task to those days. `days()` takes the days as numbers, with 0 for Sunday:
+
+```ts
+Schedule.command('emails:send').hourly().days(0, 3)
+```
+
+#### Between time constraints
+
+`between()` runs a task only between two times of day, and `unlessBetween()` only outside them. A window may cross
+midnight:
+
+```ts
+Schedule.command('emails:send').hourly().between('7:00', '22:00')
+
+Schedule.command('emails:send').hourly().unlessBetween('23:00', '4:00')
+```
+
+#### Truth test constraints
+
+`when()` runs a task only when its function returns `true`, and `skip()` skips it when its function returns `true`.
+The function may be async:
+
+```ts
+Schedule.command('emails:send').daily().when(() => true)
+
+Schedule.command('emails:send').daily().skip(async () => (await DB.table('jobs').count()) > 1000)
+```
+
+#### Environment constraints
+
+Laravel's `environments()` isn't in Oriel. Give `when()` the check instead:
+
+```ts
+Schedule.command('emails:send').daily().when(() => app().environment('staging', 'production'))
+```
+
+### Timezones
+
+A task's times are read in your app's timezone, `timezone` in `config/app.ts`, which is UTC in a new app.
+`timezone()` sets another for one task:
+
+```ts
+Schedule.command('report:generate').timezone('America/New_York').at('2:00')
+```
+
+### Preventing task overlaps
+
+A task runs again when it is due, even if its last run hasn't finished. `withoutOverlapping()` skips a run while the
+last one is still going:
+
+```ts
+Schedule.command('emails:send').everyMinute().withoutOverlapping()
+```
+
+The task holds a cache lock while it runs. In case a run never ends, the lock expires after 24 hours, or after the
+number of minutes you give: `withoutOverlapping(10)`. `node oriel schedule:clear-cache` deletes the locks of the tasks
+that use it, so a task stuck behind a run that was killed runs again.
+
+A closure has no command to tell it apart from the others, so it needs a name first, or `withoutOverlapping()` throws
+"A scheduled event name is required to prevent overlapping. Use the 'name' method before 'withoutOverlapping'.":
+
+```ts
+Schedule.call(async () => {
+  await DB.table('recent_users').delete()
+})
+  .daily()
+  .name('prune-recent-users')
+  .withoutOverlapping()
+```
+
+A job is named after its class, so it needs no `name()`.
+
+### Running tasks on one server
+
+When your app runs the scheduler on several servers, `onOneServer()` runs a task on only one of them each time it is
+due: the first server to take its lock runs it. The lock is in your default cache store, so every server must share
+that store, as the `database` store does with a shared database, or the `redis` store with a shared Redis. A closure
+needs a `name()` here too.
+
+```ts
+Schedule.command('report:generate').fridays().at('17:00').onOneServer()
+```
+
+### Background tasks
+
+The tasks due at the same time run one after the other. `runInBackground()` starts a task and goes on with the next
+one without waiting for it, so a long task doesn't hold the others back. `schedule:run` still waits for it before it
+ends:
+
+```ts
+Schedule.command('analytics:report').daily().runInBackground()
+```
+
+> [!NOTE]
+> Laravel's scheduler can also run shell commands (`exec()`), group tasks, keep running in maintenance mode, write or
+> mail a task's output, ping URLs and dispatch scheduling events. Oriel's has none of these: run a shell command from
+> a closure with `node:child_process`, and write what you need to the log.
+
+## Running the scheduler
+
+Add one cron entry to your server, which runs `schedule:run` every minute:
+
+```sh
+* * * * * cd /path-to-your-project && node oriel schedule:run >> /dev/null 2>&1
+```
+
+`schedule:run` runs each due task once, prints its name, and goes on to the next one when a task fails, after
+printing the error. With nothing due, it prints "No scheduled commands are ready to run.".
+
+### Sub-minute tasks
+
+A task that runs every few seconds, such as `everyTenSeconds()`, is due every minute. Its `schedule:run` runs it
+again each time those seconds have passed, until the minute ends, then the next minute's `schedule:run` takes over:
+
+```ts
+Schedule.call(async () => {
+  await DB.table('recent_users').delete()
+}).everyTenSeconds()
+```
+
+Since that `schedule:run` keeps going for the whole minute, a deploy would wait for it. `schedule:interrupt` tells it
+to stop repeating its sub-minute tasks for the rest of the minute; run it as part of your deploy:
+
+```sh
+node oriel schedule:interrupt
+```
+
+The signal is kept in your default cache store until the minute ends.
+
+### Running the scheduler locally
+
+On your own machine, run `schedule:work` instead of adding a cron entry. It runs the scheduler every minute in the
+foreground, until you stop it:
+
+```sh
+node oriel schedule:work
+```
+
+When one minute's run fails, as when the cache can't be read, it reports the error and goes on with the next minute.
+[Deployment](deployment.md#task-scheduling) shows both ways in production.
+
+## Task hooks
+
+`before()` runs a function before the task, and `after()` after it, whether it succeeded or not. `onSuccess()` runs
+one when it succeeded, and `onFailure()` when it failed. Each may be async:
+
+```ts
+Schedule.command('emails:send')
+  .daily()
+  .before(() => {
+    // The task is about to run...
+  })
+  .after(() => {
+    // The task has run...
+  })
+  .onSuccess(() => {
+    // The task succeeded...
+  })
+  .onFailure(() => {
+    // The task failed...
+  })
+```
+
+`then()` is another name for `after()`. A task skipped by a constraint, an overlap or another server runs none of
+its hooks.

package/docs/seeding.md

@@ -0,0 +1,122 @@
+# Database: seeding
+
+Seeders fill your database with data, such as a first user for your own machine or the rows your tests and demos
+need.
+
+## Introduction
+
+A seeder is a class in `database/seeders` with a `run()` method. A new app has one, `DatabaseSeeder`, which `db:seed`
+runs unless you name another. It creates a test user; add a `this.call()` for each seeder you write.
+
+Seeders run with mass assignment protection off, so `create()` takes every attribute you give it.
+
+## Writing seeders
+
+`make:seeder` writes a seeder in `database/seeders`:
+
+```sh
+node oriel make:seeder UserSeeder
+```
+
+A seeder's `run()` can insert rows with the [query builder](queries.md), or create models with their
+[factories](#using-model-factories). It is async, so `await` each insert:
+
+```ts title="database/seeders/UserSeeder.ts"
+import { DB, Hash, Seeder, Str } from '@orieljs/framework'
+
+export default class UserSeeder extends Seeder {
+  /** Run the database seeders. */
+  async run(): Promise<void> {
+    await DB.table('users').insert({
+      name: Str.random(10),
+      email: `${Str.random(10)}@example.com`,
+      password: await Hash.make('password'),
+    })
+  }
+}
+```
+
+The file's default export is the seeder, or its export named after the file.
+
+### Using model factories
+
+Factories make many rows at once, with realistic values. A new app's `DatabaseSeeder` uses the `User` factory:
+
+```ts title="database/seeders/DatabaseSeeder.ts"
+import { Seeder } from '@orieljs/framework'
+import { User } from '../../app/Models/User'
+
+export default class DatabaseSeeder extends Seeder {
+  async run(): Promise<void> {
+    await User.factory().create({
+      name: 'Test User',
+      email: 'test@example.com',
+    })
+  }
+}
+```
+
+`User.factory(50).create()` makes 50 users. [Factories](eloquent-factories.md) shows how to write factories and give
+them related models.
+
+### Calling additional seeders
+
+`call()` runs other seeders, in order, and prints each one's name as it runs:
+
+```ts title="database/seeders/DatabaseSeeder.ts"
+// @filename: database/seeders/UserSeeder.ts
+import { Seeder } from '@orieljs/framework'
+export default class UserSeeder extends Seeder {
+  async run(): Promise<void> {}
+}
+// @filename: database/seeders/PostSeeder.ts
+import { Seeder } from '@orieljs/framework'
+export default class PostSeeder extends Seeder {
+  async run(): Promise<void> {}
+}
+// ---cut---
+import { Seeder } from '@orieljs/framework'
+import PostSeeder from './PostSeeder'
+import UserSeeder from './UserSeeder'
+
+export default class DatabaseSeeder extends Seeder {
+  async run(): Promise<void> {
+    await this.call(UserSeeder, PostSeeder)
+  }
+}
+```
+
+`callSilent()` runs them without printing.
+
+> [!NOTE]
+> Laravel's `WithoutModelEvents` trait, which mutes model events while a seeder runs, and `callWith()` aren't in
+> Oriel. Wrap the code in `Model.withoutEvents()` to mute the events.
+
+## Running seeders
+
+`db:seed` runs `DatabaseSeeder`. Name another seeder to run it alone:
+
+```sh
+node oriel db:seed
+
+node oriel db:seed UserSeeder
+```
+
+`--database` runs the seeder on another connection, which becomes the default while it runs.
+
+`--seed` runs `DatabaseSeeder` after `migrate`, `migrate:fresh` or `migrate:refresh`, and `--seeder` another one:
+
+```sh
+node oriel migrate:fresh --seed
+
+node oriel migrate:fresh --seed --seeder=UserSeeder
+```
+
+#### Forcing seeders to run in production
+
+In production, `db:seed` stops unless you pass `--force`, so you can't fill your live database with test data by
+mistake:
+
+```sh
+node oriel db:seed --force
+```