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

package/docs/structure.md

@@ -0,0 +1,264 @@
+# Directory structure
+
+A new Oriel app has Laravel's layout: your code in `app`, your settings in `config`, your routes in `routes`, and a
+few folders that Oriel reads by itself.
+
+## Introduction
+
+The layout is a starting point, not a rule: your files import each other by relative path, so a class can live
+wherever suits your app. A few folders are the exception. Oriel looks in them by name to find your models, your
+commands, your listeners and your policies, as [Folders Oriel discovers](#folders-oriel-discovers) lists.
+
+Every starter kit is built from layers: `base`, which every app has, then the layers of its kit. The
+[starter kits' layers](#the-starter-kits-layers) section says which folders each layer adds.
+
+## The root directory
+
+### The app directory
+
+`app` holds the core code of your app: its controllers, models, providers and most of its other classes. The
+[app directory](#the-app-directory-1) section looks inside it.
+
+### The bootstrap directory
+
+`bootstrap/app.ts` creates your app: it names your route files, configures middleware and error handling, and lists your
+[service providers](providers.md) through `bootstrap/providers.ts`. Your server, your `oriel` command and your tests all
+start from it.
+
+The Inertia kits with server-side rendering build their SSR bundle into `bootstrap/ssr`, which git ignores. There is
+no `bootstrap/cache`: Oriel has no route or config cache to store.
+
+### The config directory
+
+`config` holds your app's [configuration](configuration.md) files, one TypeScript module per part of the framework.
+
+### The database directory
+
+`database` holds your migrations (`database/migrations`), your model factories (`database/factories`) and your seeders
+(`database/seeders`). A new app keeps its SQLite database here too, in `database/database.sqlite`, which git ignores.
+
+### The public directory
+
+`public` holds the files the server sends as they are, such as `favicon.svg`, and `public/index.ts`, the entry point
+that runs your app in production (see [Deployment](deployment.md)). A request for a file that exists in `public` gets
+the file before your routes run. TypeScript files and dotfiles there are never sent.
+
+Vite builds your scripts and styles into `public/build`, and while `npm run dev` runs it writes `public/hot`, which
+tells your pages to load their assets from Vite. `node oriel storage:link` adds `public/storage`, a link to
+`storage/app/public`. Git ignores all three.
+
+### The resources directory
+
+`resources` holds your views and the uncompiled sources of your pages:
+
+- `resources/views`: your [views](views.md), written in TSX, such as `welcome.tsx`. In the Inertia kits, `app.tsx`
+  there is the root view every page is rendered into.
+- `resources/css/app.css`: the kits' stylesheet, with Tailwind and the Oriel theme.
+- `resources/js`: your pages' scripts. In the Inertia kits, the pages are in `resources/js/pages`, with their
+  `components` and `layouts` beside them.
+- `resources/js/oriel`: the route and page types that `route:types` and `inertia:types` write, which git ignores.
+
+The API kit has no `resources` folder until `npm run typecheck` writes `resources/js/oriel/routes.ts`.
+
+### The routes directory
+
+`routes` holds your route files. A new app has two:
+
+- `routes/web.ts`: the routes of your pages, in the `web` middleware group, which gives them the session, cookie
+  encryption and [CSRF protection](csrf.md).
+- `routes/console.ts`: your closure commands, such as the `inspire` command a new app comes with, and your scheduled
+  tasks.
+
+The kits with pages add `routes/auth.ts`, for registration, signing in and out, password resets and email
+verification, and `routes/settings.ts`, for the settings pages. The API kit has `routes/api.ts` in place of
+`routes/web.ts`: its routes are stateless, their URIs start with `/api`, and their users sign in with tokens.
+`node oriel install:api` adds a `routes/api.ts` to another app. `bootstrap/app.ts` lists the files to load (see
+[Routing](routing.md#the-default-route-files)).
+
+### The storage directory
+
+`storage` holds the files your app and the framework write:
+
+- `storage/app/private`: the `local` disk, for files your app keeps to itself.
+- `storage/app/public`: the `public` disk, for files anyone may download, such as avatars. `node oriel storage:link`
+  links `public/storage` to it.
+- `storage/framework/cache/data`: the `file` cache store.
+- `storage/framework/sessions`: the `file` session driver's sessions.
+- `storage/framework/views`: kept from Laravel's layout. Oriel's views are TSX modules, so nothing compiles into it.
+- `storage/logs`: your logs, `oriel.log`, and `mail.log` when mail is logged to its own channel.
+
+Git keeps the folders and ignores what is written into them.
+
+### The tests directory
+
+`tests` holds your tests: `tests/Feature` for tests that send requests to your app or run its commands, and `tests/Unit`
+for the rest, with `tests/TestCase.ts`, the class they boot the app with. A test file's name ends in `.test.ts`, or
+`.test.tsx`. Run them with `node oriel test`, or with `npm test`, and on Bun with `npm run test:bun`.
+
+### The types directory
+
+`types` holds the type declarations Oriel writes for your app:
+
+- `types/models.d.ts`: your models' columns, written by `node oriel model:types` from your database. `migrate`,
+  `migrate:fresh` and `migrate:refresh` write it again when they finish, outside production. It is in git, so your
+  app type-checks on a fresh clone.
+- `types/routes.d.ts`: your route names and parameters, written by `node oriel route:types`. Git ignores it.
+
+### The node_modules directory
+
+`node_modules` holds your dependencies, as `vendor` does in a Laravel app. Your package manager writes it, and git
+ignores it.
+
+### The files at the root
+
+| File | What it is |
+| --- | --- |
+| `oriel` | Your app's command line: `node oriel <command>`, or `bun oriel <command>` |
+| `.env`, `.env.example` | Your environment's values, and the list of the variables your app reads (see [Configuration](configuration.md#environment-configuration)) |
+| `package.json` | Your dependencies and scripts, such as `dev`, `build`, `start`, `test`, `test:bun` and `typecheck` |
+| `tsconfig.json` | TypeScript's settings for your server code; the kits' pages have their own in `resources/js` |
+| `vite.config.ts` | Vite's settings, with the `oriel()` plugin (not in the API kit) |
+| `vitest.config.ts` | Vitest's settings for your tests |
+| `README.md` | How to run the app, written for your kit |
+| `.gitignore` | What git leaves out |
+| `.github/workflows/ci.yml` | The CI workflow the installer writes for your package manager |
+
+## The app directory
+
+Most of your app lives in `app`. A new app has `app/Http`, with its base `Controller`, `app/Models`, with the `User`
+model, and `app/Providers`, with the `AppServiceProvider`. The other folders appear when a `make:` command writes a
+class into them: `app/Console` doesn't exist until you run `make:command`. `node oriel list` shows every `make:`
+command.
+
+### The Console directory
+
+`app/Console/Commands` holds your [console commands](console.md#writing-commands), written by `make:command`. Oriel
+finds them by itself.
+
+### The Events directory
+
+`app/Events` holds your [event](events.md) classes, written by `make:event`.
+
+### The Http directory
+
+`app/Http` holds what handles a request: `Controllers` (`make:controller`), `Middleware` (`make:middleware`), form
+`Requests` (`make:request`) and API `Resources` (`make:resource`).
+
+### The Jobs directory
+
+`app/Jobs` holds your [queued jobs](queues.md), written by `make:job`.
+
+### The Listeners directory
+
+`app/Listeners` holds the classes that handle your events, written by `make:listener`. Oriel finds each one by itself,
+and registers it for the events its `static listensTo` names.
+
+### The Live directory
+
+`app/Live` holds the [Live](live.md) kit's components, and the ones `make:live` writes. Each component's name comes from
+its path: `app/Live/Auth/Login.tsx` is `auth.login`.
+
+### The Mail directory
+
+`app/Mail` holds your [mail](mail.md) classes, written by `make:mail`, which also writes the mail's view in
+`resources/views/mail`.
+
+### The Models directory
+
+`app/Models` holds your [models](eloquent.md), written by `make:model`. Oriel finds them by itself: a route parameter
+named after a model receives it, and `model:types` writes their columns.
+
+### The Notifications directory
+
+`app/Notifications` holds your [notifications](notifications.md), written by `make:notification`.
+
+### The Policies directory
+
+`app/Policies` holds your [authorization policies](authorization.md#creating-policies), written by `make:policy`. A
+policy named after a model, as `PostPolicy` for `Post`, applies to that model without being registered.
+
+### The Providers directory
+
+`app/Providers` holds your [service providers](providers.md). A new app has `AppServiceProvider`. `make:provider` writes
+a new one there, which you then add to the list in `bootstrap/providers.ts`.
+
+### The Rules directory
+
+`app/Rules` holds your [validation rule objects](validation.md#custom-validation-rules), written by `make:rule`.
+
+### The other directories
+
+`make:cast` writes into `app/Casts` and `make:observer` into `app/Observers`. The kits with pages also have
+`app/Support/GettingStarted.ts`, which builds the dashboard's checklist.
+
+> [!NOTE]
+> Laravel's `app/Exceptions` and `app/Broadcasting` folders, and their `make:exception` and `make:channel` commands,
+> aren't in Oriel: errors are configured in `bootstrap/app.ts`, and Oriel has no broadcasting.
+
+## Folders Oriel discovers
+
+A TypeScript module runs only when something imports it, so Oriel imports these folders itself, and registers what
+it finds there:
+
+| Folder | What Oriel registers | When |
+| --- | --- | --- |
+| `app/Models` | Every exported model, for route model binding by name, `model:types`, and the queue and Live, which store a model as its class and key | When the app boots |
+| `app/Policies` | Each `<Model>Policy` file's policy, for the model of that name (only the folder's top level) | When the app boots |
+| `app/Listeners` | Every listener with a `static listensTo`, for the events it names | When the app boots |
+| `app/Live` | Every component, under the name its path gives it | When the app boots |
+| `app/Console/Commands` | Every command class | When an `oriel` command or a test runs |
+| `database/factories` | Every factory, for its model's `factory()` (only the folder's top level) | When an `oriel` command or a test runs |
+| `app/Jobs`, `app/Events`, `app/Listeners`, `app/Mail`, `app/Notifications` | The classes a queued job carries, so the worker can rebuild them | When `queue:work` starts |
+
+Each folder is read with the folders inside it, except `app/Policies` and `database/factories`. A class in another
+folder works, but isn't discovered: register it yourself, as `Event.listen()` does for a listener or `Gate.policy()`
+for a policy.
+
+Other folders are read when they are needed: `config` when the app is created, `resources/views` for each view,
+`database/migrations` by `migrate`, and `database/seeders` by `db:seed`.
+
+## The starter kits' layers
+
+Each kit is the `base` layer and its own layers, applied in order, a later layer's file replacing an earlier one's:
+
+| Kit | Layers |
+| --- | --- |
+| React, Vue, Svelte, Solid, Angular | `base`, `web`, `inertia`, then `react`, `vue`, `svelte`, `solid` or `angular` |
+| Live | `base`, `web`, `live` |
+| API | `base`, `api` |
+
+What each layer adds:
+
+| Layer | Adds |
+| --- | --- |
+| `base` | The skeleton of every app: `app/Http/Controllers/Controller.ts`, `app/Models/User.ts`, `app/Providers`, `bootstrap`, `config`, `database`, `public`, `resources/views/welcome.tsx`, `routes/web.ts` and `routes/console.ts`, `storage`, `tests`, `types`, and the root files |
+| `web` | What the kits with pages share: the email verification controller, the `HandleAppearance` middleware, `app/Support/GettingStarted.ts`, `resources/css/app.css`, the browser scripts in `resources/js` (`appearance.ts`, `checklist.ts`, `menus.ts`, `names.ts`) and `resources/views/partials/appearance.tsx` |
+| `inertia` | The Inertia kits' server side: the auth, dashboard and settings controllers, `HandleInertiaRequests`, the form requests, `config/inertia.ts`, `bootstrap/app.ts`, and `routes/web.ts`, `routes/auth.ts` and `routes/settings.ts` |
+| `react`, `vue`, `svelte`, `solid`, `angular` | The pages, layouts and components in `resources/js`, the browser entry and, except in Angular, the SSR entry, the root view `resources/views/app.tsx`, `vite.config.ts` and the kit's `README.md` |
+| `live` | The components in `app/Live`, their views and view components in `resources/views`, `resources/js/app.ts`, `bootstrap/app.ts`, the three route files, `vite.config.ts` and the kit's `README.md` |
+| `api` | The token auth controllers, the login request, `bootstrap/app.ts`, `routes/api.ts` and the kit's `README.md`; it removes `routes/web.ts`, `resources/views` and the welcome page's test |
+
+Each layer but `inertia` also adds to `package.json` (`web` its dev dependencies only), and all but the five framework
+layers add their tests.
+
+[Starter kits](starter-kits.md) describes what the kits do with them.
+
+## Generated and ignored files
+
+Some files are written by a command rather than by you. Don't edit them: run the command again.
+
+| File | Written by | In git |
+| --- | --- | --- |
+| `types/models.d.ts` | `model:types`, and `migrate` outside production | Yes |
+| `types/routes.d.ts` | `route:types` | No |
+| `resources/js/oriel/routes.ts` | `route:types`, and the Inertia kits' Vite plugin | No |
+| `resources/js/oriel/pages.d.ts` | `inertia:types`, and the Inertia kits' Vite plugin | No |
+| `public/build` | `npm run build` | No |
+| `public/hot` | `npm run dev`, while it runs | No |
+| `bootstrap/ssr` | `npm run build` in the kits with server-side rendering | No |
+| `public/storage` | `storage:link` | No |
+| `database/database.sqlite` | The first connection to it, such as `migrate` | No |
+| `.env` | The installer, from `.env.example` | No |
+
+Git also ignores `node_modules`, the files under `storage`, `.env.backup`, `.DS_Store` and Yarn's
+`.yarn/install-state.gz`.

package/docs/testing.md

@@ -0,0 +1,165 @@
+# Testing: getting started
+
+Oriel apps are tested with Vitest. A new app has tests ready to run, a `TestCase` that gives each test a fresh
+application, and helpers to send requests, run commands and check the database.
+
+## Introduction
+
+`tests` has two folders: `tests/Feature` for tests that send requests to your app or run its commands, and
+`tests/Unit` for tests of one piece of code on its own. A test file's name ends in `.test.ts`, or `.test.tsx` for one
+that renders TSX.
+
+`tests/TestCase.ts` is the class your tests boot the app with, and `vitest.config.ts` sets Vitest up for your app. A
+test file boots the test case once, at the top, and uses it in each test:
+
+```ts title="tests/Feature/Example.test.ts"
+import { test } from 'vitest'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot()
+
+test('the application returns a successful response', async () => {
+  const response = await t.get('/')
+
+  response.assertOk()
+})
+```
+
+`TestCase.boot()` registers Vitest's `beforeEach` and `afterEach` hooks: before each test, it creates and boots a new
+application; after it, it tears that application down. No state survives from one test to the next.
+
+## Environment
+
+Before each application is created, the test case sets these variables, unless they are already set:
+
+| Variable | Value |
+| --- | --- |
+| `APP_ENV` | `testing` |
+| `BCRYPT_ROUNDS` | `4` |
+| `CACHE_STORE` | `array` |
+| `DB_CONNECTION` | `sqlite` |
+| `DB_DATABASE` | `:memory:` |
+| `MAIL_MAILER` | `array` |
+| `QUEUE_CONNECTION` | `sync` |
+| `SESSION_DRIVER` | `array` |
+
+So your tests send no mail, run jobs at once, and each test gets its own empty in-memory database. A new app's
+`vitest.config.ts` sets the same values as Vitest's `env`, because Bun reads `.env` before the tests start. Vitest's
+`env` replaces what your shell or your CI sets, so to run your tests with another value, such as a MySQL database,
+change it in `vitest.config.ts`.
+
+With `APP_ENV` set to `testing`, a `.env.testing` file, when you add one, is read in place of `.env`. For the other
+variables, what you set in your shell or your CI wins over both files.
+
+To change the app before it boots, override `defineEnvironment()` in your `TestCase`:
+
+```ts title="tests/TestCase.ts"
+import type { Application } from '@orieljs/framework'
+import { ConfigRepository } from '@orieljs/framework/contracts'
+import { TestCase as BaseTestCase } from '@orieljs/framework/testing'
+import { afterEach, beforeEach } from 'vitest'
+import { createApplication } from '../bootstrap/app'
+
+export class TestCase extends BaseTestCase {
+  static override hooks = { beforeEach, afterEach }
+
+  override createApplication(): Promise<Application> {
+    return createApplication()
+  }
+
+  protected override defineEnvironment(app: Application): void {
+    app.make(ConfigRepository).set('mail.default', 'array')
+  }
+}
+```
+
+## Creating tests
+
+`make:test` writes a test in `tests/Feature`, and with `--unit` in `tests/Unit`:
+
+```sh
+node oriel make:test UserTest
+
+node oriel make:test UserTest --unit
+```
+
+The file is named after the test without its `Test`: `tests/Feature/User.test.ts`. Both write the same Vitest test, with
+`test()`, `describe()` and `expect()`; for a feature test, import your `TestCase` and add `const t = TestCase.boot()`. A
+unit test that doesn't need the app leaves it out:
+
+```ts title="tests/Unit/Example.test.ts"
+import { expect, test } from 'vitest'
+
+test('true is true', () => {
+  expect(true).toBe(true)
+})
+```
+
+`t.app` is the current test's application, inside a test: `t.app.make(Service)` resolves a service from it.
+
+> [!NOTE]
+> Laravel's PHPUnit tests are classes, with a method for each test. Oriel's are Vitest files, as Pest's are: each
+> `test()` is one test, and the test case `TestCase.boot()` returns gives every test the helpers Laravel's `$this`
+> has.
+
+## Running tests
+
+`oriel test` runs your tests with Vitest:
+
+```sh
+node oriel test
+```
+
+`npm test` does the same, and `npm run test:bun` runs them on Bun. Name files or folders to run only those, and
+`--filter` runs the tests whose names match:
+
+```sh
+node oriel test tests/Feature/User.test.ts
+
+node oriel test --filter="the application returns"
+```
+
+Anything after `--` goes to Vitest as it is, such as `node oriel test -- --coverage` for a coverage report (with
+`@vitest/coverage-v8` installed).
+
+### Running tests in parallel
+
+Vitest runs your test files at the same time, in several workers. With the default in-memory SQLite database, each
+test has its own database, so tests can't see each other's rows.
+
+> [!WARNING]
+> On a database in a file, or a MySQL or PostgreSQL server (set in `vitest.config.ts`), every worker uses the same
+> database. Run those tests one
+> file at a time, with `node oriel test -- --no-file-parallelism`, or give each worker its own database.
+
+## Test traits
+
+A trait adds setup to the tests of a file. `RefreshDatabase` gives each test a migrated database:
+
+```ts title="tests/Feature/Posts.test.ts"
+import { RefreshDatabase } from '@orieljs/framework/testing'
+import { test } from 'vitest'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot({ uses: [RefreshDatabase] })
+
+test('posts can be listed', async () => {
+  ;(await t.get('/posts')).assertOk()
+})
+```
+
+[Database testing](database-testing.md) covers it and the other database traits.
+
+## What the test case gives you
+
+| Helper | Page |
+| --- | --- |
+| `t.get()`, `t.post()`, `t.actingAs()` and the response's assertions | [HTTP tests](http-tests.md) |
+| `t.artisan()` | [Testing commands](console.md#testing-commands) |
+| `Live.test()` | [Live tests](live-tests.md) |
+| `Mail.fake()`, `Queue.fake()` and the other fakes | [Fakes](mocking.md) |
+| `t.assertDatabaseHas()` and the database traits | [Database testing](database-testing.md) |
+| `t.travelTo()`, `t.freezeTime()` | [Time travel](time-travel.md) |
+
+While your tests run, the app runs as a console app in the `testing` environment: CSRF tokens aren't checked, so your
+tests can post forms without one.

package/docs/time-travel.md

@@ -0,0 +1,138 @@
+# Time travel
+
+Code that depends on the time, such as an expiring link, a cache entry or a trial that ends after 30 days, is tested
+by moving the clock. The test case's time travel moves the clock your code reads, and puts it back after each test.
+
+## Introduction
+
+`t.travel(5).days()` moves the clock five days on, and `t.travelTo(date)` sets it to a date:
+
+```ts title="tests/Feature/Trial.test.ts"
+import { expect, test } from 'vitest'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot()
+
+test('time can be manipulated', () => {
+  t.travelTo(new Date('2026-01-01T00:00:00Z'))
+
+  t.travel(5).days()
+
+  expect(new Date().toISOString()).toBe('2026-01-06T00:00:00.000Z')
+
+  t.travelBack()
+})
+```
+
+While you travel, the clock stands still: each `new Date()` gives the same time until you travel again. `travelBack()`
+returns to the real time, and the test case does it after each test.
+
+## Travelling
+
+`travel(n)` moves the clock by `n` of a unit, from where it stands, and a negative `n` moves it back:
+
+```ts
+import { TestCase } from './tests/TestCase'
+const t = TestCase.boot()
+// ---cut---
+t.travel(5).milliseconds()
+t.travel(5).seconds()
+t.travel(5).minutes()
+t.travel(5).hours()
+t.travel(5).days()
+t.travel(5).weeks()
+t.travel(5).months()
+t.travel(5).years()
+
+t.travel(-5).hours()
+```
+
+Each unit has a singular form too, as `t.travel(1).day()`. Months and years overflow as Laravel's do: 31 January plus a
+month is 3 March. The units count in UTC.
+
+`travelTo()` takes a `Date`, an ISO string, or milliseconds since 1970:
+
+```ts
+import { TestCase } from './tests/TestCase'
+const t = TestCase.boot()
+// ---cut---
+t.travelTo('2026-03-04T10:00:00Z')
+```
+
+### Travelling for one function
+
+Give a function, and the clock travels while it runs. After it, or after its promise settles, the clock returns to
+the real time, as `travelBack()` does, even when you had travelled before. The function's result is returned:
+
+```ts
+import { TestCase } from './tests/TestCase'
+import { User } from './app/Models/User'
+const t = TestCase.boot()
+// ---cut---
+const user = await t.travelTo('2026-01-01T00:00:00Z', () => User.factory().create())
+
+await t.travel(5).days(async () => {
+  // The clock is five days on here...
+})
+```
+
+## Freezing time
+
+`freezeTime()` holds the clock where it is now, and returns that time. `freezeSecond()` does the same at the start of
+the current second, which helps when your database keeps seconds only:
+
+```ts
+import { TestCase } from './tests/TestCase'
+const t = TestCase.boot()
+// ---cut---
+const frozen = t.freezeTime()
+
+const second = t.freezeSecond()
+```
+
+Both also take a function, and freeze the clock only while it runs, then return to the real time.
+
+## What the clock moves
+
+Time travel changes JavaScript's `Date`: `new Date()`, `Date()` and `Date.now()` read the travelled time, and so does
+everything in your app that reads them:
+
+- `now()`, model timestamps and the dates your casts write
+- Expiry in the `array`, `file` and `database` cache stores, cache locks and rate limiters
+- Signed URLs, password reset tokens, API tokens, and the expiry dates of the cookies your app sets
+- Job delays and retry times
+
+It doesn't change what runs outside JavaScript's `Date`:
+
+- Timers: `setTimeout()` and `setInterval()` still wait in real time
+- `performance.now()`
+- Redis, whose keys expire on the server's clock, so Redis cache entries and locks don't expire when you travel
+- Your database's own clock: `CURRENT_TIMESTAMP` and `now()` in SQL
+
+A test's session doesn't end either: the test client carries it from request to request, so travelling past
+`session.lifetime` doesn't sign the user out.
+
+> [!NOTE]
+> Vitest's `vi.useFakeTimers()` fakes `Date` and the timers too. Use one or the other in a test: both replace `Date`,
+> and the last one wins.
+
+## Outside a test case
+
+`travelTo()`, `travel()`, `travelBack()`, `freezeTime()` and `freezeSecond()` are also functions, from
+`@orieljs/framework/testing`, for a test that doesn't boot the test case. They work the same, but nothing travels back
+for you: call `travelBack()` in an `afterEach()`, or pass a function.
+
+```ts title="tests/Unit/Trial.test.ts"
+import { travelBack, travelTo } from '@orieljs/framework/testing'
+import { afterEach, expect, test } from 'vitest'
+
+afterEach(() => {
+  travelBack()
+})
+
+test('the clock can be set', () => {
+  travelTo('2026-01-01T00:00:00Z')
+
+  expect(Date.now()).toBe(Date.parse('2026-01-01T00:00:00Z'))
+})
+```