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

package/docs/pagination.md

@@ -0,0 +1,247 @@
+# Database: pagination
+
+Split a long list into pages with one call on a query or a model, and show the page links in a view, an Inertia page
+or a Live component.
+
+## Introduction
+
+`paginate()` runs a query for one page of rows, reads the page number from the request's `page` parameter, and gives
+back a paginator: the rows of that page, with the page numbers and the URLs of the other pages.
+
+## Basic usage
+
+### Paginating query builder results
+
+`paginate()` takes the number of rows per page:
+
+```ts title="app/Http/Controllers/UserController.ts"
+import { DB, view } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class UserController extends Controller {
+  /** Show all application users. */
+  async index() {
+    const users = await DB.table('users').paginate(15)
+
+    return view('user.index', { users })
+  }
+}
+```
+
+It runs two queries: one counts the rows, so the paginator knows the last page, and one reads the page.
+
+A page number that isn't a whole number of 1 or more is page 1. A page past the last one is empty.
+
+#### Simple pagination
+
+`simplePaginate()` reads one row more than a page, to tell whether there is a next page, and doesn't count the rows.
+Use it for long lists where you show only "Previous" and "Next":
+
+```ts
+const users = await DB.table('users').where('votes', '>', 100).simplePaginate(15)
+```
+
+### Paginating model results
+
+Your models paginate in the same way, as a static method or at the end of a query. Without a number, a model's
+`perPage`, 15, is the page size:
+
+```ts
+declare const user: User
+// ---cut---
+const users = await User.paginate(15)
+
+const verified = await User.whereNotNull('email_verified_at').paginate(15)
+
+const posts = await user.posts().paginate(10)
+```
+
+#### Multiple paginator instances per page
+
+Two paginators on one page need their own parameter. The third argument names it, after the columns:
+
+```ts
+const users = await User.whereNotNull('email_verified_at').paginate(15, ['*'], 'users')
+```
+
+The fourth argument sets the page number yourself, in place of the request's: `paginate(15, ['*'], 'page', 2)`.
+
+### Cursor pagination
+
+`cursorPaginate()` pages with a cursor, the values of the ordering columns of the last row, rather than with an offset.
+The query needs an `orderBy()`; a model's query orders by its key when it has none:
+
+```ts
+const users = await DB.table('users').orderBy('id').cursorPaginate(15)
+```
+
+The next page's URL carries the cursor in the `cursor` parameter, such as
+`http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0`.
+
+#### Cursor vs. offset pagination
+
+An offset query, `limit 15 offset 15000`, makes the database read and skip the rows before the page, which gets slow on
+large tables, and a row added while someone pages can show twice or be skipped. A cursor query,
+`where id > 15000 limit 15`, uses an index and is steady while rows change. In exchange, a cursor paginator has no page
+numbers and no total, only next and previous, and its ordering columns must be unique together. `orderByRaw()` and
+`inRandomOrder()` can't be used with it.
+
+### Manually creating a paginator
+
+To paginate rows you already have, make a `LengthAwarePaginator` (`paginate()`'s), a `Paginator`
+(`simplePaginate()`'s) or a `CursorPaginator` yourself, with the page's items, the total for a length-aware one, the
+page size and the page:
+
+```ts
+declare const pageOfItems: { id: number }[]
+// ---cut---
+const paginator = new LengthAwarePaginator(pageOfItems, 100, 15, 2)
+```
+
+### Customizing pagination URLs
+
+The links point at the current URL, without its query string. `withPath()` points them elsewhere:
+
+```ts
+const users = (await User.paginate(15)).withPath('/admin/users')
+```
+
+#### Appending query string values
+
+`appends()` adds values to every link, and `withQueryString()` keeps the current request's:
+
+```ts
+const users = (await User.paginate(15)).appends('sort', 'votes')
+
+const filtered = (await User.paginate(15)).withQueryString()
+```
+
+#### Appending hash fragments
+
+```ts
+const users = (await User.paginate(15)).fragment('users')
+```
+
+## Displaying pagination results
+
+A paginator is iterable, so `for...of` goes through its items, and `items()` returns them as an array. Its other
+methods describe the page:
+
+| Method | Returns |
+| --- | --- |
+| `currentPage()` | The current page number |
+| `firstItem()`, `lastItem()` | The number of the page's first and last item, or `null` for an empty page |
+| `perPage()` | The page size |
+| `count()` | The number of items on this page |
+| `onFirstPage()`, `onLastPage()` | Whether this is the first or the last page (`onLastPage()`: not `cursorPaginate()`) |
+| `hasPages()`, `hasMorePages()` | Whether there are pages to show (not `cursorPaginate()`), and pages after this one |
+| `previousPageUrl()`, `nextPageUrl()` | The URL of the previous and next pages, or `null` |
+| `url(page)` | The URL of a page |
+| `total()`, `lastPage()` | The number of rows and of pages (`paginate()` only) |
+| `cursor()`, `nextCursor()`, `previousCursor()` | The cursors (`cursorPaginate()` only) |
+| `getCollection()`, `through(fn)` | The items as a collection, and a paginator of the items passed through `fn` |
+
+### In views
+
+Oriel's views are TSX, so there is no `links()` that prints the links for you. `linkCollection()` gives them as objects,
+with a `url` (`null` for the "..." gaps, and for Previous or Next when there is no such page), a `label` and whether the
+link is `active`, from "« Previous" to "Next »":
+
+```tsx title="resources/views/user/index.tsx"
+import type { LengthAwarePaginator } from '@orieljs/framework'
+
+interface User {
+  id: number
+  name: string
+}
+
+export default function Index({ users }: { users: LengthAwarePaginator<User> }) {
+  return (
+    <div>
+      <ul>
+        {users.items().map((user) => (
+          <li>{user.name}</li>
+        ))}
+      </ul>
+      <nav>
+        {users.linkCollection().map((link) =>
+          link.url === null ? <span>{link.label}</span> : <a href={link.url} class={link.active ? 'active' : undefined}>{link.label}</a>,
+        )}
+      </nav>
+    </div>
+  )
+}
+```
+
+`onEachSide(count)` sets how many page links show on each side of the current one, 3 unless you set it.
+
+### In Inertia pages
+
+Pass the paginator as a prop. It reaches the page as Laravel's JSON shape, which `oriel inertia:types` types: the
+`data`, the page numbers and URLs, and the `links`. `Inertia.scroll(paginator)` makes it a prop for infinite scrolling
+(see [More Inertia features](inertia.md#more-inertia-features)).
+
+### In Live components
+
+A Live component pages with the `WithPagination` mixin, and shows its links with the `Pagination` component:
+
+```tsx title="app/Live/ShowPosts.tsx"
+import { Component, Pagination, WithPagination } from '@orieljs/framework'
+import { Post } from '../Models/Post'
+
+export default class ShowPosts extends WithPagination(Component) {
+  search = ''
+
+  async updatedSearch() {
+    await this.resetPage()
+  }
+
+  async render() {
+    const posts = await Post.whereLike('title', `%${this.search}%`).paginate(10)
+
+    return (
+      <div>
+        <ul>
+          {posts.items().map((post) => (
+            <li>{post.title}</li>
+          ))}
+        </ul>
+        <Pagination paginator={posts} />
+      </div>
+    )
+  }
+}
+```
+
+The page number is the component's `page`: its actions `nextPage`, `previousPage`, `gotoPage(n)` and `resetPage`
+move it. It isn't written to the address bar, so a reload shows page 1. `Pagination` takes `paginate()` and
+`simplePaginate()` paginators, not cursor ones.
+
+## Converting results to JSON
+
+A paginator returned from a route, or given to `JSON.stringify()`, becomes Laravel's JSON shape:
+
+```json
+{
+  "current_page": 1,
+  "data": [{ "id": 1, "name": "Taylor" }],
+  "first_page_url": "http://localhost/users?page=1",
+  "from": 1,
+  "last_page": 4,
+  "last_page_url": "http://localhost/users?page=4",
+  "links": [{ "url": null, "label": "« Previous", "active": false }],
+  "next_page_url": "http://localhost/users?page=2",
+  "path": "http://localhost/users",
+  "per_page": 15,
+  "prev_page_url": null,
+  "to": 15,
+  "total": 50
+}
+```
+
+A simple paginator has no `last_page`, `last_page_url`, `links` or `total`, and a cursor paginator has `next_cursor`
+and `prev_cursor` in place of page numbers.
+
+> [!NOTE]
+> Laravel renders the links with Blade views you can publish and theme (`links()`, Tailwind and Bootstrap views).
+> Oriel builds them in your TSX from `linkCollection()`, or with Live's `Pagination` component.

package/docs/passwords.md

@@ -0,0 +1,207 @@
+# Resetting passwords
+
+A user who forgot their password asks for a reset link by email, and sets a new password on the page it opens. The
+`Password` facade does the work, and the starter kits come with the pages.
+
+## Introduction
+
+Every starter kit lets a user reset their password: the kits with pages have a "Forgot password" page and a page to set
+the new password, and the API kit has the two endpoints (see [Starter kits](starter-kits.md#authentication)). This page
+explains what they do, so you can change them or write your own.
+
+### Model preparation
+
+The user model must be able to give its email address and to receive the reset mail. A model built on
+`AuthenticatableModel`, as a new app's `User` is, does both: `getEmailForPasswordReset()` returns its `email`
+attribute, and `sendPasswordResetNotification(token)` sends it the `ResetPassword` notification by mail.
+
+### Database preparation
+
+The reset tokens are stored in the `password_reset_tokens` table, which a new app's first migration creates: one row
+per email address, with the token and when it was made. A new token for an address replaces the one before it.
+
+### Configuring trusted hosts
+
+> [!WARNING]
+> The reset link in the mail starts with the scheme and host of the request that asked for it, as Laravel's does.
+> Laravel can restrict the hosts it answers (`trustHosts()`); Oriel can't. Have your web server or proxy answer only
+> your app's own host names, or build the link from `APP_URL` yourself, as
+> [Reset link customization](#reset-link-customization) shows, so that a request with a forged `Host` header can't
+> send your users a link to another site.
+
+## Routing
+
+### Requesting the password reset link
+
+#### The password reset link request form
+
+The kits with pages show the form at `/forgot-password`, the `password.request` route, behind the `guest` middleware.
+It asks for the email address and posts it to the same URI.
+
+#### Handling the form submission
+
+`Password.sendResetLink()` takes the credentials that find the user, the email address here, and sends the user a
+reset link:
+
+```ts title="app/Http/Controllers/Auth/PasswordResetLinkController.ts"
+import { __, back, Password, request } from '@orieljs/framework'
+import { Controller } from '../Controller'
+
+export class PasswordResetLinkController extends Controller {
+  /** Handle an incoming password reset link request. */
+  async store() {
+    await request().validate({
+      email: 'required|email',
+    })
+
+    await Password.sendResetLink(request().only('email'))
+
+    return back().with('status', __('A reset link will be sent if the account exists.'))
+  }
+}
+```
+
+It returns a status, which `__()` turns into a message:
+
+| Status | Message |
+| --- | --- |
+| `passwords.sent` | "We have emailed your password reset link." |
+| `passwords.user` | "We can't find a user with that email address." |
+| `passwords.throttled` | "Please wait before retrying." |
+
+The kits answer with the same message whatever the status, as above, so the form can't be used to find out who has an
+account.
+
+A new link for an address is refused while the last one is younger than `throttle` seconds, 60 in a new app, so the
+form can't be used to flood a user's inbox. With a function as the second argument, `sendResetLink()` calls it with
+the user and the token instead of sending the mail.
+
+### Resetting the password
+
+#### The password reset form
+
+The link in the mail opens `/reset-password/{token}?email=…`, the `password.reset` route. The page there asks for the
+new password, twice, and posts it with the token and the email address to `/reset-password`, the `password.store`
+route.
+
+#### Handling the form submission
+
+`Password.reset()` checks the token against the user's, then calls your function with the user and the new password,
+and deletes the token. Your function saves the password, hashed:
+
+```ts title="app/Http/Controllers/Auth/NewPasswordController.ts"
+import { randomBytes } from 'node:crypto'
+import { __, event, Hash, Password, PasswordReset, redirect, request, Rule, ValidationException } from '@orieljs/framework'
+import type { User } from '../../../Models/User'
+import { Controller } from '../Controller'
+
+export class NewPasswordController extends Controller {
+  /** Handle an incoming new password request. */
+  async store() {
+    await request().validate({
+      token: 'required',
+      email: 'required|email',
+      password: ['required', 'confirmed', Rule.password()],
+    })
+
+    const status = await Password.reset(
+      request().only('email', 'password', 'password_confirmation', 'token'),
+      async (user, password) => {
+        await (user as User)
+          .forceFill({
+            password: await Hash.make(password),
+            remember_token: randomBytes(30).toString('hex'),
+          })
+          .save()
+
+        await event(new PasswordReset(user))
+      },
+    )
+
+    if (status === 'passwords.reset') {
+      return redirect().route('login').with('status', __(status))
+    }
+
+    // An unknown email answers like a bad token, so the reset can't reveal whether an account exists.
+    throw ValidationException.withMessages({ email: [__(status === 'passwords.user' ? 'passwords.token' : status)] })
+  }
+}
+```
+
+`reset()` returns `passwords.reset` ("Your password has been reset."), `passwords.token` ("This password reset token is
+invalid.") for a wrong or expired token, or `passwords.user` when no user has the address. A token lasts `expire`
+minutes, 60 in a new app. The new `remember_token` signs the user out of the browsers where they chose "Remember me".
+
+In the Live kit, the two pages are the `ForgotPassword` and `ResetPassword` components, which do the same in their
+actions. The API kit's endpoints answer JSON, and its reset also revokes every API token of the user.
+
+A model with the `hashed` cast on `password` can take the plain password in the callback, in place of
+`Hash.make()`.
+
+## Deleting expired tokens
+
+An expired token can't be used, but its row stays until the user asks for another link. Laravel's
+`auth:clear-resets` command isn't in Oriel; the token repository's `deleteExpired()` deletes them, so schedule it in
+`routes/console.ts` if you want the table kept small:
+
+```ts title="routes/console.ts"
+import { Password, Schedule } from '@orieljs/framework'
+
+Schedule.call(() => Password.broker().tokens.deleteExpired())
+  .everyFifteenMinutes()
+  .name('clear-password-resets')
+```
+
+## Customization
+
+The broker's settings are under `passwords` in `config/auth.ts`:
+
+```ts
+const auth = {
+  passwords: { users: { provider: 'users', table: 'password_reset_tokens', expire: 60, throttle: 60 } },
+}
+```
+
+`expire` is in minutes and `throttle` in seconds. `Password.broker(name)` uses another entry of `passwords`, with its
+own table or user provider.
+
+#### Reset link customization
+
+`ResetPassword.createUrlUsing()` builds the link yourself, in a service provider's `boot()`. This one starts it with
+`APP_URL`, whatever host the request came to:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { config, ResetPassword, ServiceProvider } from '@orieljs/framework'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    ResetPassword.createUrlUsing((user, token) => {
+      const email = encodeURIComponent(user.getEmailForPasswordReset())
+
+      return `${String(config('app.url'))}/reset-password/${token}?email=${email}`
+    })
+  }
+}
+```
+
+A client app on another domain, such as one using the API kit, points the link at its own page the same way.
+
+#### Reset email customization
+
+`ResetPassword.toMailUsing()` builds the mail yourself: return a `MailMessage` with your own lines, or a
+[mailable](mail.md). Its function receives the user and the token:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { MailMessage, ResetPassword, ServiceProvider, url } from '@orieljs/framework'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    ResetPassword.toMailUsing((user, token) =>
+      new MailMessage()
+        .subject('Reset your password')
+        .line('Someone asked to reset the password of your account.')
+        .action('Choose a new password', url(`/reset-password/${token}`, { email: user.getEmailForPasswordReset() })),
+    )
+  }
+}
+```

package/docs/providers.md

@@ -0,0 +1,187 @@
+# Service providers
+
+Service providers set up your app and every part of Oriel: they bind services in the container, then configure them
+once every provider has registered.
+
+## Introduction
+
+Service providers are the central place of your app's setup. Your own app, and each of Oriel's components, start
+through them. Setting up here means registering things: bindings in the [service container](container.md), event
+listeners, view composers, route patterns and bindings.
+
+Oriel uses 22 service providers of its own, for the mailer, the queue, the cache and the rest. [Request
+lifecycle](lifecycle.md#service-providers) lists them, and shows where providers fit in how your app starts. Your own
+providers are listed in `bootstrap/providers.ts`. This page shows how to write them and register them.
+
+## Writing service providers
+
+A service provider extends the `ServiceProvider` class. Most have a `register()` method and a `boot()` method. In
+`register()`, only bind things into the service container: never listen for events or set anything else up there, as
+the providers that offer what you would use may not have registered yet.
+
+`make:provider` writes a new provider in `app/Providers`:
+
+```sh
+node oriel make:provider Riak
+```
+
+It adds `ServiceProvider` to the name when the name doesn't end with it, so this writes
+`app/Providers/RiakServiceProvider.ts`, with an empty `register()` and `boot()`:
+
+```ts title="app/Providers/RiakServiceProvider.ts"
+import { ServiceProvider } from '@orieljs/framework'
+
+export class RiakServiceProvider extends ServiceProvider {
+  override register(): void {
+    //
+  }
+
+  override boot(): void {
+    //
+  }
+}
+```
+
+`make:provider` doesn't register the provider: add it to `bootstrap/providers.ts` yourself, as [Registering
+providers](#registering-providers) shows. `--force` overwrites a provider that exists.
+
+> [!NOTE]
+> Laravel's `make:provider` adds the new provider to `bootstrap/providers.php` for you. Oriel's writes the class only.
+
+### The register method
+
+In `register()`, bind things into the service container, and nothing else. Every provider method has the
+application, which is also the container, in `this.app`:
+
+```ts title="app/Providers/RiakServiceProvider.ts"
+// @filename: app/Services/Riak/Connection.ts
+export declare class Connection {
+  constructor(host: string, port: number)
+}
+// ---cut---
+import { Config, ServiceProvider } from '@orieljs/framework'
+import { Connection } from '../Services/Riak/Connection'
+
+export class RiakServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(Connection, () => new Connection(Config.string('riak.host'), Config.integer('riak.port')))
+  }
+}
+```
+
+This provider only has a `register()` method, which tells the container how to build a `Connection`. [Service
+container](container.md) covers the bindings.
+
+`register()` is synchronous: Oriel doesn't wait for a promise it returns, and the next provider registers at once. Do
+async work in `boot()`, which Oriel awaits. Your configuration is loaded before any provider registers, so
+`register()` can read it.
+
+> [!NOTE]
+> Laravel's providers can list simple bindings in `$bindings` and `$singletons` properties. Oriel's have no such
+> properties: call `this.app.bind()` and `this.app.singleton()` in `register()`.
+
+#### Default configuration
+
+A provider that ships with its own settings, as a package's does, gives them to your app with `mergeConfigFrom()` in
+`register()`. It takes the defaults and the name of the configuration file they belong to:
+
+```ts title="app/Providers/RiakServiceProvider.ts"
+import { ServiceProvider } from '@orieljs/framework'
+
+export class RiakServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.mergeConfigFrom({ host: '127.0.0.1', port: 8087, options: { timeout: 5 } }, 'riak')
+  }
+}
+```
+
+`config('riak.port')` is then 8087 unless your app's `config/riak.ts` sets a `port`, which wins. The merge is shallow,
+as Laravel's is: each key your app sets replaces the default's whole value. If `config/riak.ts` sets
+`options: { retries: 3 }`, the `options` are `{ retries: 3 }`, and `timeout` is gone.
+
+### The boot method
+
+`boot()` runs once every provider has registered, so every binding of the framework and of your app is in place.
+Set things up there, such as a [view composer](views.md#view-composers):
+
+```ts title="app/Providers/ComposerServiceProvider.ts"
+import { ServiceProvider, View } from '@orieljs/framework'
+
+export class ComposerServiceProvider extends ServiceProvider {
+  override boot(): void {
+    View.composer('profile', (view) => {
+      // ...
+    })
+  }
+}
+```
+
+`boot()` may be async: Oriel awaits it before it boots the next provider. The providers boot in the order they
+registered, the framework's first, and your routes load after the last one has booted (see [Request
+lifecycle](lifecycle.md#service-providers)).
+
+An error thrown in `register()` or `boot()` stops your app from starting. Oriel throws a `ProviderRegisterError` or a
+`ProviderBootError` that names the provider, with the original error as its `cause`: "Service provider
+[RiakServiceProvider] failed to boot: Riak is down".
+
+#### Boot method dependency injection
+
+`boot()` takes no arguments. Resolve what it needs from the container, with `this.app.make()`:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { ServiceProvider } from '@orieljs/framework'
+import { ConfigRepository } from '@orieljs/framework/contracts'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    const config = this.app.make(ConfigRepository)
+
+    if (config.get('app.debug')) {
+      // ...
+    }
+  }
+}
+```
+
+> [!NOTE]
+> Laravel injects the services that `boot()`'s parameters type-hint. TypeScript types are gone when your app runs,
+> so Oriel calls `boot()` with no arguments: take what you need from `this.app`, or with `inject()`.
+
+## Registering providers
+
+Your providers are listed in `bootstrap/providers.ts`. It exports a list of the provider classes, which
+`bootstrap/app.ts` gives to `withProviders()`:
+
+```ts title="bootstrap/providers.ts"
+import { AppServiceProvider } from '../app/Providers/AppServiceProvider'
+
+export default [AppServiceProvider]
+```
+
+To register a provider you wrote, add it to the list:
+
+```ts title="bootstrap/providers.ts"
+// @filename: app/Providers/ComposerServiceProvider.ts
+import { ServiceProvider } from '@orieljs/framework'
+export class ComposerServiceProvider extends ServiceProvider {}
+// ---cut---
+import { AppServiceProvider } from '../app/Providers/AppServiceProvider'
+import { ComposerServiceProvider } from '../app/Providers/ComposerServiceProvider'
+
+export default [AppServiceProvider, ComposerServiceProvider]
+```
+
+Oriel registers the framework's providers first, then yours, in the order of the list. A provider listed twice is
+registered once.
+
+`this.app.register()` registers a provider while your app runs, as a package's provider might for another one it
+needs: `await this.app.register(RiakServiceProvider)`. If the app has booted already, the new provider boots at once.
+
+## Deferred providers
+
+Every provider registers and boots when your app starts: Oriel has no deferred providers.
+
+> [!NOTE]
+> Laravel can defer a provider that only binds services until one of them is needed, through `DeferrableProvider` and
+> `provides()`, so that a request doesn't load providers it never uses. An Oriel app boots once per process, not once
+> per request, so each provider's cost is paid once: Oriel loads them all.