lakutata 3.0.0 → 3.1.0

package/doc/en/Migrations.md

@@ -0,0 +1,202 @@
+# Lakutata Migrations
+
+`synchronize: true` changes the tables to match the entities each time the database connects: handy in development, but
+unsafe in production, where a renamed column would be dropped with its data. In production the schema changes through
+**migrations**: classes that each make one change, run in order, and recorded in the database so that each runs once.
+
+## 1. A migration
+
+A migration implements `MigrationInterface` from `lakutata/orm`. `up()` makes the change, `down()` reverts it:
+
+```typescript
+import type {MigrationInterface, QueryRunner} from 'lakutata/orm'
+
+export class AddBookAuthor1792161460658 implements MigrationInterface {
+    public name: string = 'AddBookAuthor1792161460658'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query('ALTER TABLE "books" ADD "author" character varying')
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query('ALTER TABLE "books" DROP COLUMN "author"')
+    }
+}
+```
+
+- The name of a migration ends with a timestamp in milliseconds (13 digits): the migrations run in the order of their
+  timestamps. Two migrations with the same name are an error.
+- The `migrations` option of the database lists them: the classes, or globs of their compiled files, relative to the
+  working directory.
+
+  ```typescript
+  import {buildDatabaseOptions} from 'lakutata/com/database'
+
+  export const db = buildDatabaseOptions({
+      type: 'postgres',
+      url: process.env.DATABASE_URL,
+      entities: [],
+      migrations: ['build/migrations/*.js']
+  })
+  ```
+
+- The migrations run are recorded in a table named `migrations` (`migrationsTableName` changes its name). A
+  migration is run once, even if its timestamp is older than the last one run.
+
+## 2. The `lakutata` command
+
+The projects created by `lakutata` have scripts for the migrations:
+
+```bash
+npm run migration:generate          # a migration of the changes of the entities
+npm run migration:create -- seed    # an empty migration, src/migrations/<timestamp>-seed.ts
+npm run migration:run               # run the pending migrations
+npm run migration:show              # list the migrations, run and pending
+npm run migration:revert            # revert the last migration run
+```
+
+They call `lakutata migration <action>`:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--dir` | `src/migrations` | The directory of the migrations written (`generate`, `create`) |
+| `--script` | `dev` | The npm script that builds and starts the application |
+| `--database` | Every database | The database of the command; required to revert with several databases |
+| `--transaction` | The `migrationsTransactionMode` of the database | `all`, `each` or `none` (section 6) |
+| `--fake` | `false` | Record the migrations as run (or reverted) without running them |
+| `--package` | The current directory | The package of the workspace to run the command in |
+
+`create` writes an empty migration without starting the application. The other actions run the npm script of the
+application with the environment variables of section 3: the application itself does the command.
+
+## 3. The commands of the application
+
+An application started with one of these environment variables does the command instead of launching: it reads its
+options, connects to its databases, does the command, and exits. Its `bootstrap` and its `onLaunched` handlers do not
+run, and no server starts.
+
+| Variable | Command |
+|---|---|
+| `MIGRATION_GENERATE=<directory>` | Write a migration of the differences between the entities and the tables (section 4) |
+| `MIGRATION_RUN=1` | Run the pending migrations |
+| `MIGRATION_REVERT=1` | Revert the last migration run |
+| `MIGRATION_SHOW=1` | List the migrations of the options, run (`[X]`) and pending (`[ ]`) |
+| `MIGRATION_DATABASE=<name>` | The database of the command: the name of its component or provider (every database by default) |
+| `MIGRATION_TRANSACTION=all\|each\|none` | The transactions of `MIGRATION_RUN` and `MIGRATION_REVERT` (section 6) |
+| `MIGRATION_FAKE=1` | Record the migrations as run (or reverted) without running them |
+
+```text
+$ MIGRATION_SHOW=1 node build/App.js
+[db] [ ] Migrations1792161460658
+[db] 1 pending migration
+$ MIGRATION_RUN=1 node build/App.js
+[db] Migration Migrations1792161460658 has been run
+$ MIGRATION_REVERT=1 node build/App.js
+[db] Migration Migrations1792161460658 has been reverted
+```
+
+- A flag is set by `1`, `true` or `yes`: `MIGRATION_RUN=0` starts the application as usual.
+- The commands work on the `Database` components and providers declared at the top of the options (`components`,
+  `providers`), each named by its key.
+- The exit code is 0 when the command succeeded, 1 when it failed. With several databases, `MIGRATION_REVERT` needs
+  `MIGRATION_DATABASE`.
+
+## 4. Generating a migration
+
+`MIGRATION_GENERATE` compares the entities with the tables of the database, and writes the SQL of the differences as a
+migration:
+
+```text
+$ MIGRATION_GENERATE=src/migrations node build/App.js
+Migration /home/app/src/migrations/1792161460658-db.ts has been generated successfully.
+```
+
+```typescript
+import { MigrationInterface, QueryRunner } from "lakutata/orm";
+
+export class Migrations1792161460658 implements MigrationInterface {
+    name = 'Migrations1792161460658'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE TABLE "books" (
+                "id" SERIAL NOT NULL,
+                "title" character varying NOT NULL,
+                CONSTRAINT "PK_f3f2f25a099d24e12545b70b022" PRIMARY KEY ("id")
+            )
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            DROP TABLE "books"
+        `);
+    }
+
+}
+```
+
+- The database must be reachable, and up to date with the migrations already written: the differences are computed
+  from its tables.
+- The file is `<directory>/<timestamp>-<database name>.ts`, a TypeScript class named after the directory
+  (`src/migrations` gives `Migrations<timestamp>`). Build it with the application: the `migrations` option lists the
+  compiled files.
+- Read the migration before running it: a renamed property becomes a column dropped and a column added, with the data
+  of the old one lost. Edit the SQL when needed.
+- When nothing changed, the command writes nothing and exits with the code 1 (`No changes in database schema were
+  found`).
+- With several databases, each database whose tables differ gets its own file. Give each database a `migrations` option
+  that lists only its own files (`'build/migrations/*-db.js'`), or the databases would run each other's migrations.
+
+## 5. Running the migrations at startup
+
+Instead of a command, the database can run its pending migrations each time it connects, with `migrationsRun: true`.
+The order is then: `dropSchema` (if set), the migrations, then `synchronize` (if set).
+
+- The `Database` component connects once: listed in `bootstrap`, it runs the migrations while the application launches.
+- The `Database` provider connects each time it is resolved, so it checks the migrations each time.
+
+The component and the provider also have the methods `runMigrations({transaction, fake})`,
+`undoLastMigration({transaction, fake})` and `showMigrations()` (which resolves to whether migrations are pending).
+
+## 6. Transactions
+
+`migrationsTransactionMode`, an option of the database, or `MIGRATION_TRANSACTION` for one command:
+
+| Mode | The pending migrations run… |
+|---|---|
+| `all` (default) | In one transaction: a failure reverts all of them |
+| `each` | Each in its own transaction: a failure keeps the migrations run before it |
+| `none` | Without a transaction |
+
+- A migration can set its own `transaction` property (`true` or `false`) in the modes `each` and `none`; in the mode
+  `all`, this is an error.
+- PostgreSQL and SQLite run the changes of the schema inside transactions. MySQL and MariaDB commit each change of the
+  schema at once: a failed migration can leave part of its changes applied.
+
+## 7. MongoDB
+
+The MongoDB databases (`mongodb`, `mongo-embedded`) have no schema to compare: `MIGRATION_GENERATE` writes nothing for
+them, and their migrations are written by hand. `queryRunner.query()` is not supported; the entity manager of MongoDB
+does the work:
+
+```typescript
+import type {MigrationInterface, MongoEntityManager, QueryRunner} from 'lakutata/orm'
+
+export class RenameTitle1792161460700 implements MigrationInterface {
+    public name: string = 'RenameTitle1792161460700'
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        const manager: MongoEntityManager = queryRunner.manager as MongoEntityManager
+        await manager.updateMany('notes', {}, {$rename: {title: 'name'}})
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        const manager: MongoEntityManager = queryRunner.manager as MongoEntityManager
+        await manager.updateMany('notes', {}, {$rename: {name: 'title'}})
+    }
+}
+```
+
+MongoDB runs them without transactions: a failed migration leaves the migrations run before it, and its own changes made
+before the failure.

package/doc/en/MongoEmbedded.md

@@ -0,0 +1,149 @@
+# Lakutata Embedded MongoDB
+
+The `mongo-embedded` driver gives an application a MongoDB of its own, inside its process: the entities, the
+repositories and the query operators of MongoDB in TypeORM, with the documents stored in the files of a directory. There
+is no server to install or to run, which suits desktop applications, devices, command line tools and tests.
+
+It is a part of lakutata, not of TypeORM. It runs the queries with [mingo](https://github.com/kofrasa/mingo), a
+JavaScript implementation of the query language of MongoDB.
+
+## 1. A first database
+
+```bash
+npm install lakutata mingo bson
+```
+
+```typescript
+import {Application} from 'lakutata'
+import {buildDatabaseOptions, type Database} from 'lakutata/com/database'
+import {Column, Entity, Index, ObjectIdColumn} from 'lakutata/decorator/orm'
+import type {MongoRepository, ObjectId} from 'lakutata/orm'
+
+@Entity('notes')
+class Note {
+    @ObjectIdColumn()
+    public id: ObjectId
+
+    @Index()
+    @Column()
+    public folder: string
+
+    @Column()
+    public title: string
+
+    @Column()
+    public words: number
+}
+
+Application
+    .run(() => ({
+        id: 'notes.app',
+        name: 'Notes',
+        components: {
+            db: buildDatabaseOptions({
+                type: 'mongo-embedded',
+                //A directory, created when missing
+                database: 'data/notes',
+                entities: [Note],
+                //Creates the indices of the entities
+                synchronize: true
+            })
+        },
+        bootstrap: ['db']
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const db: Database = await app.getObject<Database>('db')
+        const notes: MongoRepository<Note> = db.getMongoRepository(Note)
+        await notes.save([
+            {folder: 'work', title: 'Plan', words: 120},
+            {folder: 'work', title: 'Review', words: 40},
+            {folder: 'home', title: 'Shopping', words: 15}
+        ])
+        //The query operators of MongoDB: ["Plan"]
+        console.log((await notes.find({where: {folder: 'work', words: {$gte: 50}}})).map((note: Note): string => note.title))
+        //An aggregation: [{_id: 'home', words: 15}, {_id: 'work', words: 160}]
+        console.log(await notes.aggregate([{$group: {_id: '$folder', words: {$sum: '$words'}}}, {$sort: {_id: 1}}]).toArray())
+        await notes.updateMany({folder: 'home'}, {$set: {folder: 'personal'}})
+    })
+```
+
+The entities, the repositories and the queries are the ones of MongoDB in TypeORM (see
+[MongoDB](DatabaseDrivers.md#mongodb)): an `@ObjectIdColumn()` typed with the `ObjectId` of `lakutata/orm`, a
+`MongoRepository` with the methods of MongoDB. An application can move to a MongoDB server by changing its options only.
+
+## 2. Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `database` | `':memory:'` | The directory of the database, or `':memory:'` for a database that is not saved |
+| `sync` | `'interval'` | When the writes are flushed to the disk: `'interval'`, `'always'` or `'never'` (section 3) |
+| `syncInterval` | `100` | The interval of the flushes of `sync: 'interval'`, in milliseconds |
+| `cacheSize` | 64 MiB | The memory of the documents kept in memory after they are read, in bytes; `0` keeps none |
+| `compaction` | `{minimumSize: 16 MiB, ratio: 2}` | When the file of a collection is compacted; `false` never (section 3) |
+| `snapshot` | `{minimumSize: 64 MiB, ratio: 0.25}` | When the indices of a collection are saved while it is open; `false` only when it closes (section 3) |
+| `worker` | `true` | Run the database in a worker thread (section 4) |
+| `workerResourceLimits` | None | The memory limits of the worker thread (section 4) |
+
+The options common to every database (`entities`, `synchronize`, `logging`…) apply too.
+
+## 3. How the documents are stored
+
+- Each collection has its own file in the directory. A write is appended to the file in one write; the documents are
+  found by their `_id` through an index held in memory, outside the heap of JavaScript.
+- **Durability.** With `sync: 'interval'`, the writes are flushed to the disk every 100 milliseconds: a write that has
+  resolved survives a crash of the application, but the last interval of writes can be lost if the computer crashes or
+  loses power. `'always'` flushes before each write resolves (the writes made together share one flush); `'never'`
+  leaves the flushes to the system.
+- **Crashes.** A write cut by a crash is ignored when the database opens again: the database is as it was before that
+  write.
+- **Compaction.** An update or a delete leaves the old version of the document in the file. Once the file is
+  `minimumSize` and `ratio` times larger than its live documents, it is compacted: its live documents are copied to a
+  new file, while the reads and the writes go on.
+- **Snapshots.** The indices are saved to a snapshot when the database closes, and while it is open once `minimumSize`
+  bytes and a `ratio` of the file have been written since the last one. Opening the database reads the snapshot, then
+  only the records written after it. Without a snapshot (after a crash before the first one), the indices are built
+  again from the whole file: about 60 seconds for 10 million documents with two indices.
+- **One process.** A directory is locked by the process that opens it. A second process fails to open it, with an error
+  naming the process that holds it.
+
+## 4. The worker thread
+
+By default the database runs in a worker thread: its queries, its writes and its files never block the event loop of
+the application. Each call and its results cross between the threads encoded as BSON, which costs about 20 µs a call.
+
+- `worker: false` runs the database in the thread of the application. Its calls are faster, and the queries can then
+  use JavaScript functions (`$where`, `$function`, `$accumulator`), which cannot be sent to a worker thread.
+- The worker thread has the memory limits of the application unless `workerResourceLimits` sets its own
+  (`maxOldGenerationSizeMb`, `maxYoungGenerationSizeMb`, `codeRangeSizeMb`, `stackSizeMb`). A worker thread that
+  exceeds them is stopped, not the application: its calls fail and its directory is unlocked. A limit of 256 MB or less
+  may stop the whole process on Node.js 24 instead; Bun ignores these limits.
+
+## 5. Large collections
+
+- **Long writes.** `insertMany`, `updateMany`, `deleteMany`, and the creation of an index on existing documents run in
+  batches of 1000 documents, letting the application run between them. As in MongoDB without a transaction, a write
+  that fails on a document leaves the documents before it written.
+- **`insertMany`.** As in MongoDB, it stops at its first duplicate key, or inserts the other documents with
+  `ordered: false`. It then fails with `writeErrors`, `insertedCount` and `insertedIds`.
+- **Cursors.** A cursor without a sort (`createCursor`, `createEntityCursor`) read with `next()`, `hasNext()` or
+  `for await` reads 1000 documents at a time; `toArray()` reads all of them at once.
+- **Sorting.** A sort without an index holds all the documents it sorts in memory: index the fields that large
+  collections are sorted on. A sort with a `limit` reads the order of an index.
+- **Grouping.** A `$group` at the start of a pipeline, after stages that work on one document at a time (`$match`,
+  `$project`, `$unwind`…), reads the documents a batch at a time: its memory is the one of its groups.
+- **Index keys** are limited to about 1000 bytes: a write giving a larger key fails before it is written, with the code
+  17280 of MongoDB.
+- Integers beyond 2^53 are kept as `Long`. In a sort done in memory (without an index, or without a `limit`), they come
+  after the other numbers, in the order of their text.
+
+## 6. What it does not do
+
+As with a MongoDB server in TypeORM:
+
+- no relations, no query builders;
+- no transactions: **`transaction()` runs its function without a transaction**;
+- `synchronize` creates the indices, and the migrations are written by hand (see [Migrations](Migrations.md)).
+
+The `ObjectId` of the ids is the one exported by `lakutata/orm`. The queries accept the `ObjectId` of the package
+`bson` too, but `instanceof` tells them apart: an id read from the database is not an instance of the `ObjectId` of
+`import {ObjectId} from 'bson'`.

package/doc/en/Monitor.md

@@ -0,0 +1,164 @@
+# Lakutata Monitors
+
+The monitors of `lakutata/com/monitor` measure the process an application runs in: its CPU usage, its memory, the delays
+of its event loop, and the time its HTTP requests take. Each one is a component that keeps the statistics of its
+measures since it was created, or since its last `reset()`, in constant memory. They need nothing more than `lakutata`.
+
+## 1. Declaring and reading the monitors
+
+```typescript
+import {Application, type ILogger} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {GET} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {CpuMonitor, EventLoopMonitor, HttpRequestMonitor, MemoryMonitor} from 'lakutata/com/monitor'
+
+class MetricsController extends Controller {
+    @Inject('cpu')
+    protected readonly cpu: CpuMonitor
+
+    @Inject('memory')
+    protected readonly memory: MemoryMonitor
+
+    @Inject('eventLoop')
+    protected readonly eventLoop: EventLoopMonitor
+
+    @Inject('httpRequests')
+    protected readonly httpRequests: HttpRequestMonitor
+
+    @GET('/metrics')
+    public async metrics(): Promise<Record<string, unknown>> {
+        return {
+            cpu: this.cpu.statistics,
+            memory: this.memory.statistics,
+            eventLoop: this.eventLoop.statistics,
+            httpRequests: this.httpRequests.statistics
+        }
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'api.app',
+        name: 'API',
+        components: {
+            cpu: {class: CpuMonitor},
+            memory: {class: MemoryMonitor},
+            eventLoop: {class: EventLoopMonitor},
+            httpRequests: {class: HttpRequestMonitor},
+            entrypoint: buildEntrypoints({
+                controllers: [MetricsController],
+                http: expressHTTPEntrypoint({port: 8080})
+            })
+        },
+        //Created when the application launches, so that they measure from the start
+        bootstrap: ['cpu', 'memory', 'eventLoop', 'httpRequests', 'entrypoint']
+    }))
+    .onLaunched(async (app: Application, log: ILogger): Promise<void> => {
+        const cpu: CpuMonitor = await app.getObject<CpuMonitor>('cpu')
+        const eventLoop: EventLoopMonitor = await app.getObject<EventLoopMonitor>('eventLoop')
+        //Every minute, the statistics of the minute, then a new period (/metrics starts over with it)
+        setInterval((): void => {
+            log.info({cpuAvg: cpu.statistics.usageAvg, eventLoopMax: eventLoop.statistics.max}, 'the last minute')
+            cpu.reset()
+            eventLoop.reset()
+        }, 60000)
+    })
+```
+
+- Declare each monitor you need with its `class`, under the name of your choice. A monitor is a singleton, so every
+  object that injects it shares its statistics.
+- A monitor measures from its creation: list it in `bootstrap`. Otherwise it is created the first time it is used, and
+  measures from then on.
+- The monitors have no options. An option given to one is ignored, with a warning when the application starts.
+- `statistics` is computed at each read. `reset()` starts a new period: the statistics then cover the measures taken
+  since.
+- Their timers do not keep the process alive, and they stop when the application stops.
+
+## 2. What they measure
+
+| Monitor | Measures | Sampled | Unit |
+|---|---|---|---|
+| `CpuMonitor` | The CPU time of the process | Every second | Percent of one core |
+| `MemoryMonitor` | The memory of the process: resident, heap, external | At its creation, then every second | Bytes |
+| `EventLoopMonitor` | The delays of the event loop, and the share of the time it is busy | Continuously | Milliseconds, percent |
+| `HttpRequestMonitor` | The duration of the HTTP requests the process answers | Each request | Milliseconds |
+
+The statistics of the CPU, the memory and the HTTP requests hold the latest value, the minimum, the maximum and the
+mean, which are exact, and percentiles (P50, P90, P95, P99) with 3 significant digits. The statistics of the CPU and of
+the HTTP requests are all 0 before their first measure.
+
+## 3. `CpuMonitor`
+
+| Field | Meaning |
+|---|---|
+| `usage` | The latest sample |
+| `usageMin`, `usageMax`, `usageAvg` | The minimum, the maximum and the mean of the samples |
+| `usageP50`, `usageP90`, `usageP95`, `usageP99` | The percentiles of the samples |
+
+- The usage is the CPU time of the whole process (user and system, every thread) over the elapsed time, in percent of
+  one core: 100 is one core fully busy, and a process using several cores (worker threads, the thread pool of Node.js)
+  goes above 100. The values are rounded to 5 decimals.
+- The first sample is taken one second after the monitor is created.
+- When the event loop is blocked, the next sample comes late and covers the whole blocked time. It then counts once per
+  second it covers, so that the mean and the percentiles weigh the busy periods by their duration.
+
+## 4. `MemoryMonitor`
+
+| Fields | Meaning |
+|---|---|
+| `physicalTotal` | The memory of the machine (`os.totalmem()`), not the limit of a container |
+| `physicalUsed`, `physicalUsage` | The resident memory of the process (`rss`), and its percentage of `physicalTotal` |
+| `heapTotal`, `heapUsed`, `heapUsage` | The heap of V8 and its used part, and their ratio in percent |
+| `externalUsed` | The memory of the C++ objects bound to JavaScript objects, the `Buffer`s among them |
+| `physicalUsedMin`, `…Max`, `…Avg`, `…P50`, `…P90`, `…P95`, `…P99` | The statistics of `physicalUsed` |
+| `heapUsedMin`, `…Max`, `…Avg`, `…P50`, `…P90`, `…P95`, `…P99` | The statistics of `heapUsed` |
+| `externalUsedMin`, `…Max`, `…Avg`, `…P50`, `…P90`, `…P95`, `…P99` | The statistics of `externalUsed` |
+
+- The values are in bytes; the means and the two percentages are rounded to 2 decimals.
+- `heapUsage` compares the used heap with the heap allocated so far, not with its limit: a high value alone is not a
+  problem. A leak shows as a `heapUsedMin` that rises from one period to the next.
+- `reset()` keeps the latest values (`physicalUsed`, `heapUsed`…); the other statistics start again.
+
+## 5. `EventLoopMonitor`
+
+| Field | Meaning |
+|---|---|
+| `min`, `max`, `avg`, `stdDev` | The minimum, the maximum, the mean and the standard deviation of the delays |
+| `p50`, `p90`, `p95`, `p99` | The percentiles of the delays |
+| `utilRate` | The share of the time the event loop was busy, in percent |
+
+- The delay is the interval between the runs of a timer of 1 ms: about 1 ms when the event loop is idle, more when
+  synchronous work (a long computation, synchronous I/O, a large JSON) holds it. `max` is the longest block.
+- `utilRate` covers the whole period since the creation or the last `reset()`: near 100, the event loop has no idle
+  time left. Right after a `reset()`, it reads 100, the event loop being busy running the code that called it.
+- The values come from the histogram of Node.js (`monitorEventLoopDelay`): they are not rounded, and they are
+  approximate, the minimum, the maximum and the mean included.
+- The timer of 1 ms costs about 1.5 % of one core while the application is idle: on a device that runs on a battery,
+  declare this monitor only when you need it.
+
+## 6. `HttpRequestMonitor`
+
+| Field | Meaning |
+|---|---|
+| `count` | The number of requests answered |
+| `min`, `max`, `avg`, `stdDev` | The minimum, the maximum, the mean and the standard deviation of their durations |
+| `p50`, `p90`, `p95`, `p99` | The percentiles of their durations |
+
+- It counts the requests answered by every HTTP server of the process (the HTTP adapters, the HTTP service, JSON-RPC
+  over HTTP, the server of Socket.IO, a server of your own), errors included, HTTPS too. It does not count the requests
+  of HTTP/2, those that the process sends, nor those it never answers.
+- It gives no breakdown by route or by status.
+- It only counts the requests that start after its creation: a request in progress when the monitor is created is not
+  counted. Read from an action, the statistics do not include the request being answered.
+- The durations are in milliseconds, rounded to 2 decimals.
+
+## 7. Worker threads
+
+A worker thread that declares monitors measures:
+
+- the delays and the busy time of its own event loop (`EventLoopMonitor`);
+- the requests of its own HTTP servers (`HttpRequestMonitor`);
+- the CPU and the resident memory of the whole process (`CpuMonitor`, `physicalUsed` of `MemoryMonitor`), but its own
+  heap (`heapUsed`).

package/doc/en/Mutex.md

@@ -1,9 +1,10 @@
 # Lakutata Mutex
 
-The **Mutex component** (`lakutata/com/mutex`, package `@lakutata/mutex`) gives the named locks of an application: a
-work runs in one holder at a time, between the components of a process, the processes of a host, or every instance of
-the application, as its driver shares the locks. It also provides `@Synchronized` for the controller actions and the
-locks of the `exclusive` schedules. The README of `@lakutata/mutex` gives the details.
+The **Mutex component** (`lakutata/com/mutex`, package `@lakutata/mutex`) gives an application named locks: the work
+protected by a lock runs in one place at a time. Depending on the driver, a lock is shared by the components of a
+process, by the processes of a machine, or by every instance of the application. The component also serves
+`@Synchronized`, which runs a controller action under a lock, and the `exclusive` schedules. The README of
+`@lakutata/mutex` gives the details.
 
 ## 1. Configuration
 
@@ -33,14 +34,14 @@ Application.run(() => ({
 
 | Driver | Shared by | Notes |
 |---|---|---|
-| `{type: 'memory'}` (default) | the components of a process | development, tests, a single instance |
-| `{type: 'file', directory}` | the processes of a host | lock files created exclusively; a lock of a dead process is taken over at once |
-| `{type: 'redis', url}` | every instance | Redis 4+ or Valkey, package `redis`; fencing tokens; use `noeviction` (an evicted key is a lost lock) |
-| `{type: 'postgres', host, database, username, password, mode}` | every instance | package `pg`; `mode: 'advisory'` (default): advisory locks on a connection of its own, released when it closes, not through PgBouncer in transaction mode; `mode: 'table'`: rows of a table, expiring, fencing tokens |
-| `{type: 'mysql', host, database, username, password, mode}` | every instance | package `mysql2`; `mode: 'advisory'` (default): `GET_LOCK` on a connection of its own, not shared by the clusters; `mode: 'table'`: rows of a table, expiring, fencing tokens |
+| `{type: 'memory'}` (default) | The components of a process | Development, tests, a single instance |
+| `{type: 'file', directory?}` | The processes of a machine | Lock files, created exclusively (in `lakutata-mutex` under the temporary directory of the system unless `directory` is given); the lock of a process that died is taken over at once |
+| `{type: 'redis', url}` | Every instance | Redis 4+ or Valkey, package `redis`; fencing tokens; use `noeviction` (an evicted key is a lost lock) |
+| `{type: 'postgres', host, database, username, password, mode}` | Every instance | Package `pg`; `mode: 'advisory'` (default): advisory locks on a connection of its own, released when it closes, not usable through PgBouncer in transaction mode; `mode: 'table'`: rows of a table, which expire, with fencing tokens |
+| `{type: 'mysql', host, database, username, password, mode}` | Every instance | Package `mysql2`; `mode: 'advisory'` (default): `GET_LOCK` on a connection of its own, which the nodes of a cluster do not share; `mode: 'table'`: rows of a table, which expire, with fencing tokens |
 
-The clients (`redis`, `pg`, `mysql2`) are optional peer dependencies: a driver whose package is missing fails its first
-acquisition with `MutexDriverNotFoundException`. The driver connects at the first acquisition.
+The clients (`redis`, `pg`, `mysql2`) are optional peer dependencies. A driver connects at the first acquisition; when
+its package is missing, that acquisition fails with `MutexDriverNotFoundException`.
 
 ## 2. Usage
 
@@ -88,20 +89,20 @@ class Orders extends Component {
 - **Lost locks**: when a renewal fails until the lock expires, or the connection holding an advisory lock closes,
   `lock.held` becomes `false` and `lock.signal` is aborted with a `MutexLostException`. The work is not interrupted: it
   should watch the signal.
-- **Fencing tokens**: `lock.fence` increases with each acquisition (memory, Redis, the `table` modes): the stores
-  written under a lock may refuse the writes of an older holder.
+- **Fencing tokens**: `lock.fence` increases with each acquisition (memory, Redis, the `table` modes): a store written
+  under a lock can use it to refuse the writes of an older holder.
 - **Not reentrant**: acquiring a lock the component already holds waits for its release, like any other holder.
 - **Lifecycle**: the component releases its locks and closes its driver when it is destroyed (the application
   stopping).
 
 ## 3. Synchronized actions
 
-`@Synchronized(name, options?)` runs a controller action holding a lock, acquired once its input is validated and its
-access control passed, released after it: the requests of a same lock run one at a time in every instance (whatever
-their transport), the others in parallel. The name is a template whose `{field}` are fields of the validated input, or
-a function `(input, context) => string`. The options are `mutex` (the component name, `'mutex'` by default), `timeout`,
-`wait` and `ttl`. A request not getting the lock in time fails with `MutexTimeoutException` (HTTP 409); the wait stops
-when the request is aborted.
+`@Synchronized(name, options?)` runs a controller action under a lock, acquired after its input is validated and its
+access control has passed, and released when the action returns. The requests that need the same lock run one at a time,
+across every instance and whatever their transport; the other requests run in parallel. The name is a template whose
+`{field}` are fields of the validated input, or a function `(input, context) => string`. The options are `mutex` (the
+name of the component, `'mutex'` by default), `timeout`, `wait` and `ttl`. A request that does not get the lock in time
+fails with `MutexTimeoutException` (HTTP 409); it stops waiting when it is aborted.
 
 ```typescript
 import {Controller} from 'lakutata/com/entrypoint'
@@ -132,11 +133,12 @@ class OrderController extends Controller {
 
 ## 4. Exclusive schedules
 
-A scheduled action declared `exclusive` runs in one instance of the application at a time: each run tries to acquire
-the lock `schedule:<key>` (the action name by default) from the component `mutex` (or `exclusive: {mutex, key}`), and
-the instances not getting it skip the run. Its intervals are aligned on their multiples so that every instance plans the
-same times, and its lock is kept until half of its period (30 s at most) after a short run, so that the instances whose
-clocks are late skip it too. Without its lock component, the action does not run (the error is logged).
+A scheduled action declared `exclusive` runs in one instance of the application at a time: each run tries to acquire the
+lock `schedule:<key>` (the key is the name of the action by default) from the component `mutex` (or the one
+`exclusive: {mutex, key}` names), and the instances that do not get it skip the run. Its intervals are aligned on the
+clock (every 5 minutes means at :00, :05, :10…), so that every instance plans the same times. After a run, the lock is
+held until half the period has passed since the planned time (30 s at most), so that an instance whose clock is a little
+behind does not run it again. Without its lock component, the action does not run, and the error is logged.
 
 ```typescript
 import {Controller} from 'lakutata/com/entrypoint'
@@ -156,7 +158,7 @@ class ReportController extends Controller {
 ```
 
 The entrypoint needs a schedule adapter: `buildEntrypoints({controllers: [ReportController], schedule:
-scheduleEntrypoint()})` (see [ActionPattern](ActionPattern.md)).
+scheduleEntrypoint()})` (see [Schedules](Schedules.md)).
 
 ## 5. Exceptions