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

package/docs/navigation.json

@@ -0,0 +1,273 @@
+{
+  "sections": [
+    {
+      "title": "Getting started",
+      "pages": [
+        {
+          "slug": "installation",
+          "title": "Installation"
+        },
+        {
+          "slug": "configuration",
+          "title": "Configuration"
+        },
+        {
+          "slug": "structure",
+          "title": "Directory structure"
+        },
+        {
+          "slug": "starter-kits",
+          "title": "Starter kits"
+        },
+        {
+          "slug": "deployment",
+          "title": "Deployment"
+        }
+      ]
+    },
+    {
+      "title": "Architecture",
+      "pages": [
+        {
+          "slug": "lifecycle",
+          "title": "Request lifecycle"
+        },
+        {
+          "slug": "container",
+          "title": "Service container"
+        },
+        {
+          "slug": "providers",
+          "title": "Service providers"
+        },
+        {
+          "slug": "facades",
+          "title": "Facades"
+        }
+      ]
+    },
+    {
+      "title": "The basics",
+      "pages": [
+        {
+          "slug": "routing",
+          "title": "Routing"
+        },
+        {
+          "slug": "middleware",
+          "title": "Middleware"
+        },
+        {
+          "slug": "csrf",
+          "title": "CSRF protection"
+        },
+        {
+          "slug": "controllers",
+          "title": "Controllers"
+        },
+        {
+          "slug": "requests",
+          "title": "Requests"
+        },
+        {
+          "slug": "session",
+          "title": "Session"
+        },
+        {
+          "slug": "responses",
+          "title": "Responses"
+        },
+        {
+          "slug": "views",
+          "title": "Views"
+        },
+        {
+          "slug": "validation",
+          "title": "Validation"
+        },
+        {
+          "slug": "errors",
+          "title": "Error handling"
+        },
+        {
+          "slug": "logging",
+          "title": "Logging"
+        }
+      ]
+    },
+    {
+      "title": "Digging deeper",
+      "pages": [
+        {
+          "slug": "console",
+          "title": "Console"
+        },
+        {
+          "slug": "cache",
+          "title": "Cache"
+        },
+        {
+          "slug": "collections",
+          "title": "Collections"
+        },
+        {
+          "slug": "events",
+          "title": "Events"
+        },
+        {
+          "slug": "storage",
+          "title": "File storage"
+        },
+        {
+          "slug": "helpers",
+          "title": "Helpers"
+        },
+        {
+          "slug": "mail",
+          "title": "Mail"
+        },
+        {
+          "slug": "notifications",
+          "title": "Notifications"
+        },
+        {
+          "slug": "queues",
+          "title": "Queues"
+        },
+        {
+          "slug": "scheduling",
+          "title": "Task scheduling"
+        }
+      ]
+    },
+    {
+      "title": "Security",
+      "pages": [
+        {
+          "slug": "authentication",
+          "title": "Authentication"
+        },
+        {
+          "slug": "authorization",
+          "title": "Authorization"
+        },
+        {
+          "slug": "verification",
+          "title": "Email verification"
+        },
+        {
+          "slug": "encryption",
+          "title": "Encryption"
+        },
+        {
+          "slug": "hashing",
+          "title": "Hashing"
+        },
+        {
+          "slug": "passwords",
+          "title": "Password reset"
+        }
+      ]
+    },
+    {
+      "title": "Database",
+      "pages": [
+        {
+          "slug": "database",
+          "title": "Getting started"
+        },
+        {
+          "slug": "queries",
+          "title": "Query builder"
+        },
+        {
+          "slug": "pagination",
+          "title": "Pagination"
+        },
+        {
+          "slug": "migrations",
+          "title": "Migrations"
+        },
+        {
+          "slug": "seeding",
+          "title": "Seeding"
+        }
+      ]
+    },
+    {
+      "title": "Models",
+      "pages": [
+        {
+          "slug": "eloquent",
+          "title": "Getting started"
+        },
+        {
+          "slug": "eloquent-relationships",
+          "title": "Relationships"
+        },
+        {
+          "slug": "eloquent-collections",
+          "title": "Collections"
+        },
+        {
+          "slug": "eloquent-mutators",
+          "title": "Accessors and casts"
+        },
+        {
+          "slug": "eloquent-factories",
+          "title": "Factories"
+        },
+        {
+          "slug": "eloquent-observers",
+          "title": "Observers"
+        }
+      ]
+    },
+    {
+      "title": "Frontend",
+      "pages": [
+        {
+          "slug": "inertia",
+          "title": "Inertia"
+        },
+        {
+          "slug": "live",
+          "title": "Live"
+        },
+        {
+          "slug": "vite",
+          "title": "Vite"
+        }
+      ]
+    },
+    {
+      "title": "Testing",
+      "pages": [
+        {
+          "slug": "testing",
+          "title": "Getting started"
+        },
+        {
+          "slug": "http-tests",
+          "title": "HTTP tests"
+        },
+        {
+          "slug": "live-tests",
+          "title": "Live tests"
+        },
+        {
+          "slug": "mocking",
+          "title": "Fakes"
+        },
+        {
+          "slug": "database-testing",
+          "title": "Database"
+        },
+        {
+          "slug": "time-travel",
+          "title": "Time travel"
+        }
+      ]
+    }
+  ]
+}

package/docs/notifications.md

@@ -0,0 +1,225 @@
+# Notifications
+
+A notification is a short message to one of your users, such as "your order has shipped", sent over one or more
+channels: as an email, as a row in your database for your app to show, or both.
+
+## Introduction
+
+Each notification is a class with a `via()` method, which names its channels, and a `toXxx()` method for each of
+them. Oriel has two channels: `mail`, which sends an email, and `database`, which stores the notification in a
+`notifications` table. You can add channels of your own with `Notification.extend()`.
+
+> [!NOTE]
+> Laravel also has broadcast, SMS (Vonage) and Slack channels. Oriel has `mail` and `database`.
+
+## Generating notifications
+
+`make:notification` writes a class to `app/Notifications`:
+
+```sh
+node oriel make:notification InvoicePaid
+```
+
+The class it writes is queued (it has `readonly shouldQueue = true`), so run `node oriel queue:work` while you work
+on it, or remove the field to send it right away.
+
+## Sending notifications
+
+### Using the Notifiable mixin
+
+A model sends and stores notifications through the `Notifiable` mixin, which the `User` model of a new app already
+has:
+
+```ts title="app/Models/User.ts"
+import { AuthenticatableModel, Authorizable, HasApiTokens, Model, Notifiable } from '@orieljs/framework'
+
+export class User extends HasApiTokens(Notifiable(Authorizable(AuthenticatableModel(Model)))) {}
+```
+
+It gives the model `notify()`, `notifyNow()` and `routeNotificationFor()`, and the `notifications()`,
+`readNotifications()` and `unreadNotifications()` relations of the [database channel](#database-notifications):
+
+```ts
+const user = await User.findOrFail(1)
+
+await user.notify(new InvoicePaid('$20.00'))
+```
+
+### Using the Notification facade
+
+To notify several users at once, pass them (an array or any iterable) to `Notification.send()`:
+
+```ts
+import { Notification } from '@orieljs/framework'
+
+const users = await User.all()
+
+await Notification.send(users, new InvoicePaid('$20.00'))
+```
+
+`Notification.sendNow()` sends right away, even a queued notification, and takes the channels to use as a third
+argument.
+
+### Specifying delivery channels
+
+`via()` gets the notifiable, so a notification can choose its channels for each user:
+
+```ts
+class InvoicePaid extends Notification {
+  via(notifiable: object): string[] {
+    return notifiable instanceof User ? ['mail', 'database'] : ['mail']
+  }
+}
+```
+
+### Queueing notifications
+
+A notification with `readonly shouldQueue = true` is queued: `notify()` and `Notification.send()` push one job per
+notifiable and per channel, and a [queue worker](queues.md#running-the-queue-worker) sends them. The fields
+`connection`, `queue` and `delay` choose where and when, and any of them also queues the notification, as a `uniqueId()`
+or `retryUntil()` method does. `notifyNow()` and `Notification.sendNow()` send a queued notification right away.
+
+### Unique notifications
+
+A queued notification with a `uniqueId()` method isn't queued again while its job is waiting or running, as a
+[unique job](queues.md#unique-jobs). The lock is taken per notifiable and per channel, so the same notification to two
+users, or by mail and by database, sends each of them.
+
+### On-demand notifications
+
+To notify someone who isn't a user of your app, give the route yourself:
+
+```ts
+await Notification.route('mail', 'taylor@example.com').notify(new InvoicePaid('$20.00'))
+```
+
+The database channel is skipped for an on-demand notification, as it needs a model to store the row against.
+
+> [!NOTE]
+> Laravel chains `route()` for several channels (`->route('mail', ...)->route('vonage', ...)`). The value
+> `Notification.route()` returns is typed with `notify()` only, so an on-demand notification has one channel.
+
+## Mail notifications
+
+### Formatting mail messages
+
+`toMail()` returns a `MailMessage`, which Oriel renders in its own styled template, with a plain-text part beside the
+HTML:
+
+```ts title="app/Notifications/InvoicePaid.ts"
+import { MailMessage, Notification } from '@orieljs/framework'
+
+export class InvoicePaid extends Notification {
+  constructor(private readonly amount: string) {
+    super()
+  }
+
+  via(): string[] {
+    return ['mail']
+  }
+
+  toMail(): MailMessage {
+    return new MailMessage()
+      .subject('Invoice paid')
+      .greeting('Hello!')
+      .line(`We received your payment of ${this.amount}.`)
+      .action('View invoice', 'https://example.com/invoices/1')
+      .line('Thank you for using our application!')
+  }
+}
+```
+
+- `greeting()` is "Hello!" when you don't set one ("Whoops!" for an error message), and `salutation()` is "Regards,"
+  and your app's name.
+- `line()`, `lines()`, `lineIf()` and `linesIf()` add paragraphs; `action()` adds a button.
+- `from()`, `to()`, `cc()`, `bcc()` and `replyTo()` set the addresses, `attach(path, { as, mime })` attaches a file and
+  `attachData(data, name, { mime })` attaches content you have in memory.
+
+Each line is plain text: Oriel escapes it, and keeps it as you wrote it.
+
+> [!NOTE]
+> Laravel reads each line as Markdown, trims it and joins its lines into one. Oriel's lines are plain text, escaped,
+> neither trimmed nor joined. A `MailMessage` has no `view()`, `markdown()`, `mailer()` or theme: for a mail of your
+> own design, return a [mailable](mail.md) from `toMail()`. A mailable is sent to its own recipients, not to the
+> notifiable's address.
+
+### Error messages
+
+`error()` gives the message the error level, which colours its button red; `success()` colours it green, and
+`level('info' | 'success' | 'error')` sets it directly.
+
+### Customizing the subject
+
+When you don't call `subject()`, the subject is the class name in title case: `InvoicePaid` is sent as "Invoice Paid".
+A notification written as an object literal has the name `Object`, so its subject is "Object": give it a `subject()`.
+
+### Customizing the recipient
+
+The mail channel sends to the notifiable's `email` attribute. To send elsewhere, add a `routeNotificationForMail()`
+method to the model:
+
+```ts
+class Customer extends Notifiable(Model) {
+  declare billing_email: string
+
+  routeNotificationForMail(): string {
+    return this.billing_email
+  }
+}
+```
+
+When there is no route, as for a notifiable with no email address, nothing is sent.
+
+## Database notifications
+
+### Prerequisites
+
+The database channel stores each notification in the `notifications` table, which a new app's migrations create.
+`toDatabase()` (or `toArray()`) returns the data to store, and the notifiable must be a model:
+
+```ts
+class InvoicePaid extends Notification {
+  constructor(readonly amount: string) {
+    super()
+  }
+
+  via(): string[] {
+    return ['database']
+  }
+
+  toDatabase(): Record<string, unknown> {
+    return { amount: this.amount }
+  }
+}
+```
+
+The row's `type` is the notification's class name, and its `data` is what `toDatabase()` returned.
+
+### Accessing the notifications
+
+`notifications()` is a relation, newest first; `unreadNotifications()` and `readNotifications()` filter it:
+
+```ts
+const user = await User.findOrFail(1)
+
+for (const notification of await user.unreadNotifications().get()) {
+  console.log(notification.data)
+}
+```
+
+### Marking notifications as read
+
+```ts
+const user = await User.findOrFail(1)
+const notification = await user.notifications().firstOrFail()
+
+await notification.markAsRead()
+await notification.markAsUnread()
+```
+
+`read()` and `unread()` tell which it is, and a collection of notifications has its own `markAsRead()`.
+
+## Custom channels
+
+`Notification.extend(name, factory)` adds a channel: an object with `send(notifiable, notification)`. List its name in
+`via()`.