lakutata 3.0.0 → 3.1.0

package/doc/en/Database.md

@@ -0,0 +1,188 @@
+# Lakutata Databases
+
+The database layer of lakutata, the package `@lakutata/orm`, is built on [TypeORM](https://typeorm.io) 1. The source
+of TypeORM is part of the package, so no package `typeorm` is installed. `lakutata` re-exports it under four subpaths:
+
+| Subpath | What it provides |
+|---|---|
+| `lakutata/com/database` | The `Database` component, a connection shared by the application, and `buildDatabaseOptions` |
+| `lakutata/provider/database` | The `Database` provider, a connection of its own each time it is resolved |
+| `lakutata/decorator/orm` | The decorators of the entities (`@Entity`, `@Column`, the relations…) |
+| `lakutata/orm` | The API of TypeORM: repositories, entity manager, find operators, migrations, errors |
+
+The driver of the database is installed separately: see [DatabaseDrivers](DatabaseDrivers.md). The entities, the
+queries and the transactions are described in [Entities](Entities.md), the changes of the schema in
+[Migrations](Migrations.md).
+
+## 1. The Database component
+
+`buildDatabaseOptions` declares a `Database` component with the connection options of TypeORM:
+
+```typescript
+import {Application, Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {buildDatabaseOptions, Database} from 'lakutata/com/database'
+import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+
+@Entity('users')
+class User {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column({type: 'varchar', length: 100})
+    public name: string
+
+    @Column({unique: true})
+    public email: string
+}
+
+class Users extends Component {
+    //The component declared as "db"
+    @Inject('db')
+    protected readonly db: Database
+
+    public async register(name: string, email: string): Promise<User> {
+        return await this.db.getRepository(User).save({name: name, email: email})
+    }
+
+    public async find(id: number): Promise<User | null> {
+        return await this.db.getRepository(User).findOneBy({id: id})
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'users.app',
+        name: 'Users',
+        components: {
+            db: buildDatabaseOptions({
+                type: 'postgres',
+                url: process.env.DATABASE_URL,
+                entities: [User],
+                //Development only: the tables follow the entities. In production, use migrations
+                synchronize: true
+            }),
+            users: {class: Users}
+        },
+        bootstrap: ['db']
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const users: Users = await app.getObject<Users>('users')
+        await users.register('Ada', 'ada@example.com')
+    })
+```
+
+- The component connects when it is created. Listed in `bootstrap`, it connects while the application launches, and a
+  failed connection stops the launch. Otherwise it connects the first time an object needs it.
+- It disconnects when the application stops.
+- Other objects inject it by its name (`@Inject('db')`), or get it with `getObject('db')`.
+
+## 2. The connection options
+
+The options are the ones of TypeORM, given to it as they are. The options of each driver are in
+[DatabaseDrivers](DatabaseDrivers.md); the common ones are:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `type` | Required | The driver: `'postgres'`, `'mysql'`, `'better-sqlite3'`… |
+| `entities` | | The entity classes, `EntitySchema`s, or globs of their compiled files (`'build/entities/*.js'`) |
+| `synchronize` | `false` | Update the tables from the entities each time the database connects. For development only |
+| `logging` | `false` | What TypeORM logs: `true`, or a list among `'query'`, `'error'`, `'schema'`, `'warn'`, `'info'`, `'log'` |
+| `logger` | | Where TypeORM logs: `'advanced-console'`, `'simple-console'`, `'file'`, `'debug'`, or a logger of your own |
+| `maxQueryExecutionTime` | | Log the queries slower than this, in milliseconds |
+| `poolSize` | | The connections of the pool |
+| `extra` | | Options passed to the client of the driver |
+| `migrations`, `migrationsRun`, `migrationsTableName`, `migrationsTransactionMode` | | The migrations (see [Migrations](Migrations.md)) |
+| `subscribers` | | The entity subscribers |
+| `namingStrategy` | | How tables, columns and indices are named |
+| `cache` | | The cache of query results: `true` (in a table of the database), or `{type: 'redis', options}` |
+| `invalidWhereValuesBehavior` | `{null: 'ignore', undefined: 'ignore'}` | What `null` and `undefined` do in a where condition (below) |
+
+**`null` and `undefined` in the conditions.** By default, a property of a where condition whose value is `null` or
+`undefined` is left out of the condition, as in TypeORM 0.3; TypeORM 1 throws instead. So `findOneBy({id: undefined})`
+finds the first row of the table: check the values taken from a request before querying with them, or set
+`invalidWhereValuesBehavior: {undefined: 'throw'}` to throw on them (each key given replaces its default).
+
+**Databases created with TypeORM 0.3.** If a table or column name has characters outside ASCII, TypeORM 1 names its
+indices and constraints differently, and generated migrations would rename them.
+`namingStrategy: new NamingStrategyV03()` (from `lakutata/orm`) keeps the names of TypeORM 0.3.
+
+**A Redis query cache** (`cache: {type: 'redis'}` or `'ioredis'`) needs the package `redis` or `ioredis`.
+
+## 3. What the component provides
+
+The component exposes the API of a TypeORM data source:
+
+| Method or property | What it does |
+|---|---|
+| `getRepository(Entity)` | The repository of an entity (a `MongoRepository` on MongoDB) |
+| `getMongoRepository(Entity)`, `getTreeRepository(Entity)` | The repository of MongoDB, of a tree entity |
+| `manager` | The entity manager |
+| `transaction(fn)`, `transaction(isolationLevel, fn)` | Run a function in a transaction |
+| `query(sql, parameters)` | Run SQL; the placeholders are `$1, $2…` on PostgreSQL, `?` on MySQL and SQLite |
+| `createQueryBuilder(Entity, alias)` | A query builder |
+| `createQueryRunner(mode)` | A connection of the pool, to control a transaction by hand; `'slave'` reads from a replica |
+| `synchronize()` | Update the tables from the entities |
+| `runMigrations()`, `undoLastMigration()`, `showMigrations()` | Run, revert and list the migrations |
+| `hasMetadata(Entity)`, `getMetadata(Entity)` | Whether an entity is known, and its metadata |
+
+## 4. The Database provider
+
+The `Database` of `lakutata/provider/database` has the same API, but it is **transient**: each time it is resolved
+(`@Inject`, `getObject()`), a new instance opens its own pool of connections, and closes it when it is destroyed with
+the object or the container that created it. It suits a short task (a job, a script, a database per customer), while
+the requests of an application share the component.
+
+```typescript
+import {Application} from 'lakutata'
+import {buildDatabaseOptions, Database} from 'lakutata/provider/database'
+import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+
+@Entity('reports')
+class Report {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column()
+    public title: string
+}
+
+Application
+    .run(() => ({
+        id: 'reports.app',
+        name: 'Reports',
+        providers: {
+            reports: {
+                ...buildDatabaseOptions({type: 'postgres', url: process.env.REPORTS_URL}),
+                //Added to the entities of the connection options
+                entities: [Report]
+            }
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        //A connection opened here, and closed with the application
+        const database: Database = await app.getObject<Database>('reports')
+        console.log(await database.getRepository(Report).count())
+    })
+```
+
+## 5. Several databases
+
+Each database is a component of its own, injected by its name:
+
+```typescript
+import {Application} from 'lakutata'
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+Application.run(() => ({
+    id: 'shop.app',
+    name: 'Shop',
+    components: {
+        db: buildDatabaseOptions({type: 'postgres', url: process.env.DATABASE_URL, entities: []}),
+        analytics: buildDatabaseOptions({type: 'mysql', url: process.env.ANALYTICS_URL, entities: []})
+    },
+    bootstrap: ['db', 'analytics']
+}))
+```
+
+An entity can belong to several databases. Its repository comes from whichever database `getRepository()` is called on.

package/doc/en/DatabaseDrivers.md

@@ -0,0 +1,287 @@
+# Lakutata Database Drivers
+
+The `type` option of a database chooses its driver. The driver packages are not installed with `lakutata`: install the
+one for your database alongside it.
+
+| Database | `type` | Install |
+|---|---|---|
+| PostgreSQL | `postgres` | `pg` (8.5 or later) |
+| CockroachDB | `cockroachdb` | `pg` |
+| MySQL, MariaDB | `mysql`, `mariadb` | `mysql2` (3.15.3 or later) |
+| SQLite | `better-sqlite3` | `better-sqlite3` (12) |
+| SQLite in WebAssembly | `sqljs` | `sql.js` (1.4 or later) |
+| Microsoft SQL Server | `mssql` | `mssql` (12) |
+| Oracle | `oracle` | `oracledb` (6.3 or later, or 7) |
+| MongoDB | `mongodb` | `mongodb` (7) |
+| MongoDB embedded in the application | `mongo-embedded` | `mingo` (7.2 or later) and `bson` (7); see [MongoEmbedded](MongoEmbedded.md) |
+| SAP HANA | `sap` | `@sap/hana-client` (2.14 or later) |
+| Google Cloud Spanner | `spanner` | `@google-cloud/spanner` (8) |
+| Amazon Aurora through the Data API | `aurora-mysql`, `aurora-postgres` | `typeorm-aurora-data-api-driver` (3) |
+
+```bash
+npm install lakutata pg
+```
+
+There is no `sqlite` type: SQLite files use `better-sqlite3`, or `sqljs` where a native module cannot run. TypeORM also
+has drivers for the mobile platforms (`capacitor`, `cordova`, `expo`, `nativescript`, `react-native`); lakutata does
+not target them.
+
+## What applies to every driver
+
+- The connection options go to TypeORM as they are, and TypeORM does not check them: a missing host or password
+  is reported by the driver when the database connects.
+- `extra` is passed to the client of the driver (its pool, its connection), after the other options: it reaches the
+  settings that TypeORM has no option for.
+- `driver` gives the driver module itself (`driver: require('pg')`), instead of letting lakutata load the package.
+- Every example below declares a `Database` component. The options are the same for the `Database` provider (see
+  [Database](Database.md)).
+
+## PostgreSQL
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'postgres',
+    host: 'localhost',
+    port: 5432,
+    username: 'app',
+    password: process.env.DB_PASSWORD,
+    database: 'app',
+    //Or all of them at once: url: 'postgres://app:secret@localhost:5432/app'
+    entities: []
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `url` | | The connection URL, instead of the options below |
+| `host`, `port`, `username`, `password`, `database` | | The server and the database; `password` can be a function, sync or async, to read a rotating secret |
+| `ssl` | | `true`, or the TLS options of Node.js (`{ca, rejectUnauthorized}`) |
+| `schema` | The `search_path` of the server (usually `public`) | The schema of the tables |
+| `poolSize` | 10 (the default of `pg`) | The connections of the pool |
+| `connectTimeoutMS` | No limit | The time allowed to connect |
+| `applicationName` | | The name shown in the activity of the server |
+| `uuidExtension` | `'uuid-ossp'` | The extension of the UUID columns: `'uuid-ossp'` or `'pgcrypto'` |
+| `replication` | | `{master, slaves}`: the reads go to the replicas |
+
+- **`bigint` and `numeric` columns come back as strings**, to keep their precision (`'9007199254740993'`, `'12.50'`).
+  Convert them with a column `transformer` where a number is enough. `parseInt8: true` returns the `bigint` columns as
+  numbers, but it changes this setting of `pg` for the whole process.
+- With `pg-native` installed, the native client of `pg` is used. Streams (`stream()` of the query builders) need
+  `pg-query-stream`.
+
+**CockroachDB** uses the same driver with `type: 'cockroachdb'` and the same connection options. Its option
+`timeTravelQueries` (whether the reads use follower reads) must be given; a transaction failing on a conflict is
+retried 5 times (`maxTransactionRetries`).
+
+## MySQL and MariaDB
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'mysql',
+    host: 'localhost',
+    port: 3306,
+    username: 'app',
+    password: process.env.DB_PASSWORD,
+    database: 'app',
+    charset: 'utf8mb4',
+    entities: []
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `url`, `host`, `port`, `username`, `password` | | The server |
+| `database` | | The database. Required, unless every entity names its own |
+| `socketPath` | | A unix socket, instead of the host and the port |
+| `ssl` | | The TLS options, or the name of a TLS profile |
+| `charset` | `'UTF8_GENERAL_CI'` | The character set and collation: use `'utf8mb4'` for the full Unicode (emoji) |
+| `timezone` | `'local'` | How the dates are read and written: `'local'`, `'Z'` or an offset (`'+08:00'`) |
+| `poolSize` | 10 (the default of `mysql2`) | The connections of the pool |
+| `connectTimeout`, `acquireTimeout` | `10000` | The time allowed to connect, and to get a connection of the pool |
+| `replication` | | `{master, slaves}`: the reads go to the replicas |
+
+- Use `type: 'mariadb'` for MariaDB: the options are the same. MariaDB has the `uuid` column type from 10.7.
+- **`bigint` and `decimal` columns come back as strings**, as with PostgreSQL.
+- A table has at most one auto-increment column. MySQL has no check constraint in TypeORM's schema synchronization.
+- Only `mysql2` is supported: the old package `mysql` is not.
+
+## SQLite: better-sqlite3
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'better-sqlite3',
+    //A file (its directory is created), or ':memory:'
+    database: 'data/app.sqlite',
+    enableWAL: true,
+    entities: []
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `database` | Required | The file of the database, or `':memory:'` |
+| `enableWAL` | `false` | The write-ahead log: the reads no longer wait for the writes |
+| `timeout` | `5000` | How long a statement waits for a database locked by another connection, in milliseconds |
+| `readonly`, `fileMustExist` | `false` | Open the file read-only; fail when it does not exist |
+| `key` | | The encryption key, for a build of SQLite with SQLCipher |
+| `prepareDatabase` | | `(db) => …`, called with the connection of better-sqlite3 once it is open: pragmas, functions |
+| `nativeBinding` | | The path of the compiled module `better_sqlite3.node` |
+
+- The foreign keys are enforced (`PRAGMA foreign_keys = ON`). There is one connection: `poolSize` is not supported.
+- **`bigint` columns come back as numbers**: values beyond 2^53 lose precision. Keep such values in a text column.
+- `better-sqlite3` is a native module, compiled for one version of Node.js. An Electron application needs the build of
+  its Electron (`electron-rebuild`, or the prebuilt binaries of better-sqlite3 for Electron); Bun cannot load it (use
+  `sqljs` there).
+
+## SQLite: sql.js
+
+`sql.js` is SQLite compiled to WebAssembly: no native module, so it runs the same in Node.js, Bun, Electron and the
+browsers. The whole database is held in memory, and written to its file when it changes.
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'sqljs',
+    //Loaded when the database connects (if it exists), written after each change
+    location: 'data/app.sqlite',
+    autoSave: true,
+    entities: []
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `location` | | The file to load and to save (in a browser, the key of `localStorage`) |
+| `autoSave` | `false` | Save after each change. It needs `location` or `autoSaveCallback` |
+| `autoSaveCallback` | | `(data: Uint8Array) => …`, called instead of writing `location` |
+| `database` | | The content of a database to load (a `Uint8Array`), instead of `location` |
+| `useLocalForage` | `false` | In a browser, save to IndexedDB (through `localforage`) instead of `localStorage` |
+| `sqlJsConfig` | | The options of the initialization of sql.js (`locateFile` of its `.wasm` file) |
+
+- Without `autoSave`, nothing is written to disk until `saveDatabase()` of the entity manager (`SqljsEntityManager`)
+  is called. With `autoSave`, the changes of a transaction are saved once it is committed.
+- The file is written as a whole at each save: sql.js suits small databases.
+- As with better-sqlite3, the foreign keys are enforced and `bigint` columns come back as numbers.
+
+## Microsoft SQL Server
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'mssql',
+    host: 'localhost',
+    port: 1433,
+    username: 'sa',
+    password: process.env.DB_PASSWORD,
+    database: 'app',
+    options: {
+        //A server with a self-signed certificate, as in development
+        trustServerCertificate: true
+    },
+    entities: []
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `url`, `host`, `port`, `username`, `password`, `database` | | The server and the database |
+| `authentication` | | Another authentication than the user and password: `{type: 'ntlm', ...}`, `{type: 'azure-active-directory-default', ...}`… |
+| `schema` | The default schema of the user | The schema of the tables |
+| `options.encrypt` | `true` | Encrypt the connection |
+| `options.trustServerCertificate` | `false` | Accept a certificate not signed by a trusted authority |
+| `options.instanceName` | | A named instance |
+| `pool` | | The pool of connections: `max`, `min`, `idleTimeoutMillis` (30000 by default)… (`poolSize` is not supported) |
+| `connectionTimeout`, `requestTimeout` | `15000` | The time allowed to connect, and to run a query |
+
+- Since `encrypt` is on, a server with a self-signed certificate (a local server, a container) refuses the connection
+  unless `trustServerCertificate` is `true`.
+- Transactions cannot be nested.
+
+## Oracle
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+
+export const db = buildDatabaseOptions({
+    type: 'oracle',
+    host: 'localhost',
+    port: 1521,
+    serviceName: 'FREEPDB1',
+    username: 'app',
+    password: process.env.DB_PASSWORD,
+    entities: []
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `host`, `port`, `username`, `password` | | The server |
+| `serviceName` or `sid` | | The database service |
+| `connectString` | Built from the options above | A connect string (`'localhost:1521/FREEPDB1'`, a TNS entry), instead of them |
+| `thickMode` | `false` | The thick mode of `oracledb` (with the Oracle Client libraries): `true`, or `{libDir, configDir}` |
+| `useUTC` | `false` | Read and write the dates in UTC |
+| `poolSize` | | The connections of the pool |
+
+- `oracledb` 6 and later run in thin mode by default, with no Oracle Client. Set `thickMode` for the features that
+  need it.
+- The tables are in the schema of the user. `useUTC` sets the time zone of the sessions of the whole process (the
+  variable `ORA_SDTZ`).
+
+## MongoDB
+
+```typescript
+import {buildDatabaseOptions} from 'lakutata/com/database'
+import {Column, Entity, ObjectIdColumn} from 'lakutata/decorator/orm'
+import type {ObjectId} from 'lakutata/orm'
+
+@Entity('users')
+export class User {
+    @ObjectIdColumn()
+    public id: ObjectId
+
+    @Column()
+    public name: string
+}
+
+export const db = buildDatabaseOptions({
+    type: 'mongodb',
+    url: 'mongodb://localhost:27017/app',
+    entities: [User]
+})
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `url` | | The connection URL |
+| `host`, `port`, `username`, `password`, `database` | `127.0.0.1`, `27017` | The server, when there is no `url` |
+| `authSource`, `replicaSet`, `tls`, `readPreference`, `writeConcern`… | | The options of the client of MongoDB |
+| `poolSize` | | The largest number of connections (`maxPoolSize`) |
+
+- An entity has an `@ObjectIdColumn()`, its `_id`. Its type is the `ObjectId` of `lakutata/orm`: an
+  `import {ObjectId} from 'bson'` in an ES module is another class, whose instances are not the ids of the entities.
+- `getRepository()` returns a `MongoRepository`, with the methods of MongoDB (`find` with the MongoDB operators,
+  `aggregate`, `createCursor`…).
+- TypeORM does not support for MongoDB: the query builders, `query()`, the relations and the cascades, the tree
+  repositories, the streams. **`transaction()` runs its function without a transaction**: the writes of a failed
+  function stay written.
+- `synchronize` only creates the indices. The migrations are written by hand (see [Migrations](Migrations.md)).
+
+## SAP HANA, Google Cloud Spanner and Amazon Aurora
+
+These drivers come from TypeORM as they are:
+
+- **SAP HANA** (`sap`): `host`, `port`, `username`, `password`, `database`, `schema`, `encrypt` with `key`, `cert`,
+  `ca`, and `pool` (`maxConnectedOrPooled`, 10 by default).
+- **Google Cloud Spanner** (`spanner`): `projectId`, `instanceId`, `databaseId`, and `credentials` (`client_email`,
+  `private_key`) unless the credentials of the environment are used. The other options of its type, copied from
+  MySQL, are not read.
+- **Amazon Aurora through the Data API** (`aurora-mysql`, `aurora-postgres`): `region`, `secretArn`, `resourceArn` and
+  `database` are required; the queries go through the HTTP API of AWS, not through a connection.

package/doc/en/Decorator.md

@@ -1,8 +1,7 @@
 # Lakutata Decorators
 
-The framework declares its dependencies, options, actions and validations with decorators (TypeScript
-`experimentalDecorators` with `emitDecoratorMetadata`, both set by `lakutata/tsconfig.json`). They are exported by
-these subpaths:
+Dependencies, options, actions and validations are declared with decorators (TypeScript `experimentalDecorators` and
+`emitDecoratorMetadata`, both set by `lakutata/tsconfig.json`). These subpaths export them:
 
 | Subpath | Decorators |
 |---|---|
@@ -12,12 +11,13 @@ these subpaths:
 | `lakutata/decorator/asst` | `@Before`, `@After` |
 | `lakutata/decorator/orm` | The TypeORM decorators (`@Entity`, `@Column`…) |
 | `lakutata/com/mutex` | `@Synchronized` |
+| `lakutata/com/queue` | `@QueueAction` |
 
 ## 1. Dependency injection (`lakutata/decorator/di`)
 
 ### 1.1 `@Inject`
 
-Sets a property, when the object is created and before its `init()`, to an object of the container:
+Sets a property to an object of the container when the decorated object is created, before its `init()`:
 
 ```typescript
 import {Application, Component, type ILogger} from 'lakutata'
@@ -53,13 +53,13 @@ class Signup extends Component {
 }
 ```
 
-A registration that cannot be resolved fails the creation of the object with a `DependencyInjectionException`.
+When a dependency cannot be resolved, the creation of the object fails with a `DependencyInjectionException`.
 
 ### 1.2 `@Configurable`
 
-`@Configurable(schema?, fn?)` makes a property an option of the object, given by its declaration
-(`{class: Server, port: 8080}`) or by the second argument of `getObject()`. The value is validated (and converted) by
-the schema (`DTO.Any()` by default), then passed to `fn` (called with the instance as `this`) when given.
+`@Configurable(schema?, fn?)` makes a property an option of the object, set by the object's declaration
+(`{class: Server, port: 8080}`) or by the second argument of `getObject()`. The schema (`DTO.Any()` by default)
+validates (and converts) the value, which is then passed to `fn` when one is given, with the instance as `this`.
 
 ```typescript
 import {Application, Component, DTO} from 'lakutata'
@@ -96,22 +96,21 @@ Application.run(() => ({
 - **Value**: the value configured for the property, else its initializer (`protected readonly host: string =
   '127.0.0.1'`), else the default of its schema (`DTO.Number().default(80)`). The initializer is validated and
   transformed like a configured value, and a subclass gives its own default with its own initializer.
-- **`maxListeners`**: every component has this configurable property (11 by default): the number of listeners of one
-  event above which a possible memory leak is warned of (0 for no warning; the listeners are never limited). A component
-  sets its own default with `protected readonly maxListeners: number = 0`, or its declaration sets it:
-  `{class: MyComponent, maxListeners: 0}`.
-- **Startup check**: when a module (or the application) initializes, it checks the options of every object it declares
+- **`maxListeners`**: every component has this configurable property (11 by default). Above this number of listeners on
+  one event, a warning reports a possible memory leak (0 disables the warning; the number of listeners is never
+  limited). A component sets its own default with `protected readonly maxListeners: number = 0`, or its declaration sets
+  it: `{class: MyComponent, maxListeners: 0}`.
+- **Startup check**: when the application launches, it checks the options of every object it declares
   (components, providers and objects) before any of them is created, so a mistake shows up at startup even for an
   object that is never used:
   - a value that does not match the schema of its `@Configurable` property fails the startup with an
     `InvalidObjectOptionsException` listing every invalid option;
-  - an option that is not a `@Configurable` property of the class is ignored and warned of, with the configurable
-    properties of the class (a misspelled option name).
+  - an option that is not a `@Configurable` property of the class (a misspelled option name, for example) is ignored,
+    with a warning that lists the configurable properties of the class.
 
-  A class that reads options without configurable properties (through `getConfigurableRecords()`) overrides the static
-  `acceptsOption(name, value)` to accept them without a warning. The values validated by external (asynchronous) rules
-  are validated when the object is created. The check is disabled with `checkOptions: false` in the options of the
-  application or of the module.
+  A class that reads its options without configurable properties (through `getConfigurableRecords()`) overrides the
+  static `acceptsOption(name, value)` to accept them without a warning. Values checked by external (asynchronous) rules
+  are validated when the object is created. `checkOptions: false` in the options of the application disables the check.
 
 ### 1.3 `@Autoload`
 
@@ -123,19 +122,19 @@ transient class in the requesting container. The mark is not inherited.
 
 | Decorator | One instance… | Default of |
 |---|---|---|
-| `@Singleton(lock?)` | per container registering the class | `Component`, `Module` (locked) |
+| `@Singleton(lock?)` | per container that registers the class | `Component` (locked) |
 | `@Scoped(lock?)` | per scope (a request of an entrypoint) | `Provider`, `Controller` (locked) |
 | `@Transient(lock?)` | per resolution | `BaseObject` |
 
-`@Lifetime('SINGLETON' | 'SCOPED' | 'TRANSIENT', lock?)` is their long form. With `lock` set to `true`, the subclasses
-cannot declare another lifetime (a `LifetimeLockedException` is thrown when they are defined). A `Provider` may be a
+`@Lifetime('SINGLETON' | 'SCOPED' | 'TRANSIENT', lock?)` is their long form. With `lock` set to `true`, subclasses
+cannot declare another lifetime (defining such a subclass throws a `LifetimeLockedException`). A `Provider` may be a
 singleton, as in 2.x.
 
 ```typescript
 import {Provider} from 'lakutata'
 import {Transient} from 'lakutata/decorator/di'
 
-//Each user of the builder gets its own, with its own state
+//Each object that injects the builder gets its own instance, with its own state
 @Transient()
 export class QueryBuilder extends Provider {
     protected readonly clauses: string[] = []
@@ -147,19 +146,21 @@ export class QueryBuilder extends Provider {
 }
 ```
 
-### 1.5 The properties of subclasses
+### 1.5 Properties of subclasses
 
-- **Inheritance**: a subclass inherits the `@Inject` and `@Configurable` properties of its parents. A subclass
-  declaring a property again replaces the declaration of its parents, whatever its decorator: the closest declaration
-  wins (a property injected by the parent and declared again with `@Configurable` is configured only, and the opposite).
+- **Inheritance**: a subclass inherits the `@Inject` and `@Configurable` properties of its parents. When a subclass
+  declares a property again, its declaration replaces those of its parents, whatever the decorator: the closest
+  declaration wins (a property injected by the parent and declared again with `@Configurable` is only configured, and
+  the other way round).
 - **The type of a property**: TypeScript lets a subclass narrow the type of a property it declares again (a
-  `MemoryStore` for a `Store`), never replace it by another type: `string` for `number` fails with `TS2416` (`Property
-  'port' in type 'BrokenServer' is not assignable to the same property in base type 'PlainServer'`), and no compiler
-  option disables it. A parent whose subclasses may replace the type of a property declares it with a type parameter:
-  - the parent declares the type parameter on the class, named after the property and ending in `Type` (`StoreType` for
-    `store`), with a constraint (`extends Store`): the parent uses the property as its constraint, and its subclasses
-    replace it by compatible types only; and with a default (`= Store`): a subclass that does not replace it extends
-    the parent without type argument;
+  `MemoryStore` instead of a `Store`), but not change it to an unrelated type: `string` instead of `number` fails with
+  `TS2416` (`Property 'port' in type 'BrokenServer' is not assignable to the same property in base type 'PlainServer'`),
+  and no compiler option turns this off. A parent whose subclasses may need another type for a property declares it with
+  a type parameter:
+  - the parent declares a type parameter on the class, named after the property with `Type` at the end (`StoreType` for
+    `store`). Its constraint (`extends Store`) is the type the parent can rely on, and it limits the subclasses to
+    compatible types; its default (`= Store`) lets a subclass that keeps the type extend the parent without a type
+    argument;
   - a subclass gives the type in its `extends` clause, and declares the property again only to change its decorator.
 
 ```typescript
@@ -210,10 +211,15 @@ In `MemoryRepository`, the IDE completes `this.store` as a `MemoryStore`, and in
 type parameter in its parent, a subclass can only silence the error with `// @ts-expect-error` on the property, while
 the methods of the parent still use the property with its former type.
 
+Declaring a property again without an initializer, as `NamedPortServer` does, compiles with
+`useDefineForClassFields: false`, which `lakutata/tsconfig.json` sets. With `true` (the default of TypeScript for
+`ES2022` and later targets), the compiler refuses it with `TS2612`; write `declare` before the property instead
+(`@Configurable(...) declare protected readonly port: string`), and the decorator still applies.
+
 ## 2. Controller actions (`lakutata/decorator/ctrl`)
 
 These decorators apply to the methods (and, for `@Prefix` and `@UseMiddlewares`, to the classes) of the subclasses of
-`Controller`; [ActionPattern](ActionPattern.md) describes them in detail.
+`Controller`; [Controllers](Controllers.md) describes them in detail.
 
 | Decorator | Address |
 |---|---|
@@ -258,7 +264,7 @@ application'}})`, translated by the key `commands.package.description`).
 | Decorator | Effect |
 |---|---|
 | `@Expect(schema)` | The schema of a property of a DTO (`DTO.String().required()`) |
-| `@IndexSignature(schema)` | A DTO class keeps the keys without schema, validated against the schema |
+| `@IndexSignature(schema)` | A DTO class keeps the keys that have no schema, validating them against this schema |
 | `@Accept(...schemas)` | Validates the arguments of each call of a method, by position |
 | `@Return(schema)` | Validates the result of each call of a method |
 
@@ -297,10 +303,16 @@ class Prices extends Component {
 
 ## 5. Locks (`lakutata/com/mutex`)
 
-`@Synchronized` runs a controller action holding a lock of the `Mutex` component, acquired once the input is validated
-and the access is allowed. See [Mutex](Mutex.md).
+`@Synchronized` runs a controller action under a lock of the `Mutex` component, acquired after the input is validated
+and access is allowed. See [Mutex](Mutex.md).
+
+## 6. Queues (`lakutata/com/queue`)
+
+`@QueueAction(queue, dto?, options?)` makes a controller action the consumer of a queue: the `queueEntrypoint` adapter
+delivers the messages of the queue to it. A message is acknowledged when the action returns, retried after a failure,
+and sent to the dead letter queue once its retries are used up. See [Queue](Queue.md).
 
-## 6. Database entities (`lakutata/decorator/orm`)
+## 7. Database entities (`lakutata/decorator/orm`)
 
 `lakutata/decorator/orm` re-exports the decorators of TypeORM:
 
@@ -334,4 +346,4 @@ export class User {
 }
 ```
 
-See [ORMIntegration](ORMIntegration.md).
+See [Entities](Entities.md).