lakutata 3.0.0 → 3.1.0

package/doc/en/NATS.md

@@ -0,0 +1,246 @@
+# Lakutata NATS
+
+The package `@lakutata/nats` connects an application to a [NATS](https://nats.io) server. It provides a component to
+publish, subscribe and send requests; a service adapter that serves the service actions of the application over NATS;
+and a service proxy that calls them from other applications. Several instances of a service share its requests, without
+a load balancer. `lakutata` does not include the package, so install it next to it:
+
+```bash
+npm install lakutata @lakutata/nats
+```
+
+It needs a NATS server 2.2 or later, with JetStream enabled (`nats-server -js`) for the payloads larger than the
+server's limit (section 7):
+
+```bash
+docker run -d --name nats -p 4222:4222 nats:2.12-alpine -js
+```
+
+## 1. The NATS component
+
+Declare the component with `buildNatsClientOptions`. It connects when it is created. When the server cannot be reached,
+the creation fails after `timeout` (20 seconds by default), and so does the launch of the application if the component
+is created during the launch (listed in `bootstrap`, or needed by an object that is).
+
+```typescript
+import {Application} from 'lakutata'
+import {buildNatsClientOptions, type NATS} from '@lakutata/nats'
+
+Application
+    .run(() => ({
+        id: 'pricing.app',
+        name: 'Pricing',
+        components: {
+            nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222', name: 'pricing'})
+        },
+        bootstrap: ['nats']
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const nats: NATS = await app.getObject<NATS>('nats')
+        //A responder: the value returned answers the request; the instances in the queue group share the requests
+        nats.subscribe('price.get', async (input: { sku: string }): Promise<number> => input.sku.length * 10, {queue: 'pricing'})
+        //A subscriber with a wildcard: the second argument is the subject of the message
+        nats.subscribe('price.changed.*', (price: number, subject: string): void => console.log(subject, price))
+        nats.publish('price.changed.eu', 42)
+        //The response, within 5 seconds
+        console.log(await nats.request('price.get', {sku: 'ABC'}, 5000)) //30
+    })
+```
+
+- `publish(subject, payload)` sends a message to every subscription of the subject (to one subscription per queue
+  group). When nobody is listening, the message is lost.
+- `subscribe(subject, callback, options?)` accepts the wildcards `*` (one token) and `>` (all the remaining tokens).
+  The options are `queue` (a queue group: each message goes to one member), `max` (end after that many messages),
+  `iterator` (handle the messages one after the other) and `errorResponse` (see below). It returns the NATS
+  subscription (`unsubscribe()`, `drain()`).
+- `request(subject, payload, timeout?)` returns the first response. Its timeout is in milliseconds, 10 minutes by
+  default. When the callback of the responder throws, the request is not answered and times out, unless the
+  subscription has `errorResponse: (error) => value` to answer it.
+- A lost connection is opened again in the background (10 attempts per server, `maxReconnectAttempts: -1` to retry
+  forever).
+- When the application stops, the component drains its connections: the messages being handled are finished, and the
+  outgoing ones sent.
+- The component emits `'error'` for the failures it cannot throw to a caller (a callback that throws, a message that
+  cannot be decoded): `nats.on('error', listener)`.
+
+The options of `buildNatsClientOptions`:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `servers` | Required | A server URL or a list of them (`'nats://127.0.0.1:4222'`) |
+| `user`, `pass` / `token` | | The credentials |
+| `name` | | The name of the connection, shown by the server |
+| `codec` | `messagePackCodec()` | How the payloads are encoded (section 6) |
+| `timeout` | `20000` | The milliseconds to wait for the first connection |
+| `reconnect`, `maxReconnectAttempts` | `true`, `10` | Whether, and how many times per server, to reconnect |
+| `pingInterval`, `maxPingOut` | `120000`, `2` | How often to ping the server, and how many pings may stay unanswered |
+| `noEcho` | `false` | Do not receive the messages this connection publishes |
+| `noRandomize` | `false` | Try the servers in their order, not at random |
+| `debug` | `false` | Print the protocol |
+| `bulk`, `bulkBucket`, `bulkTTL`, `bulkReplicas` | | The large payloads (section 7) |
+
+TLS and the NKey or JWT credentials are not supported by the component.
+
+## 2. Serving the service actions
+
+`natsServiceEntrypoint(natsComponentName, options?)` is a `service` adapter of the entrypoint: it receives the requests
+sent to the application and calls its `@ServiceAction` methods.
+
+```typescript
+import {Application, DTO} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {ServiceAction} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {buildNatsClientOptions, natsServiceEntrypoint} from '@lakutata/nats'
+
+class GetOrderDTO extends DTO {
+    @Expect(DTO.Number().integer().required())
+    public id: number
+}
+
+class OrderController extends Controller {
+    @ServiceAction({cmd: 'order.get'}, GetOrderDTO)
+    public async get(input: GetOrderDTO): Promise<{ id: number, total: number }> {
+        return {id: input.id, total: 42}
+    }
+}
+
+Application.run(() => ({
+    //The subject of the requests, and the serviceId the proxies use
+    id: 'order.service',
+    name: 'OrderService',
+    components: {
+        nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'}),
+        entrypoint: buildEntrypoints({
+            controllers: [OrderController],
+            service: natsServiceEntrypoint('nats')
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+- The first argument is the name of the NATS component.
+- The requests arrive on a subject named after the application id (`order.service`); the `subject` option sets
+  another one.
+- The instances of the service join one queue group (`order.service.serviceQueue`, or the `queue` option), so each
+  request is handled by one instance.
+- A message published without waiting for a response still runs its action, but nothing is answered.
+- When the application stops, the adapter stops receiving new requests, and finishes the ones in progress. Callers of a
+  restarting service retry their requests (section 3).
+
+The adapter also takes `middlewares`, run after the ones of the entrypoint, and `name`.
+
+## 3. Calling a service: the service proxy
+
+A `ServiceProxy` calls the actions of one remote service, and listens to its events. It is a singleton provider: declare
+one per service with `buildServiceProxy`, under `providers`.
+
+```typescript
+import {Application} from 'lakutata'
+import {
+    buildNatsClientOptions,
+    buildServiceProxy,
+    NatsRequestTimeoutException,
+    ServiceInvokeException,
+    type ServiceProxy
+} from '@lakutata/nats'
+
+Application
+    .run(() => ({
+        id: 'billing.app',
+        name: 'Billing',
+        components: {
+            nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'})
+        },
+        providers: {
+            orderService: buildServiceProxy({natsComponentName: 'nats', serviceId: 'order.service'})
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const orderService: ServiceProxy = await app.getObject<ServiceProxy>('orderService')
+        try {
+            //The pattern of the action and its input in one object, and a timeout of 30 seconds
+            console.log(await orderService.invoke({cmd: 'order.get', id: 1}, 30000))
+        } catch (error) {
+            if (error instanceof ServiceInvokeException) console.error(error.service, error.errno, error.message)
+            else if (error instanceof NatsRequestTimeoutException) console.error('No response in time')
+            else throw error
+        }
+    })
+```
+
+`invoke(input, timeout)` returns the result of the action. The timeout is 10 minutes by default; a service that is not
+running fails at once, so the timeout only limits an action that is too slow.
+
+- When no instance of the service received the request (it is not running, or is restarting), the proxy sends the
+  request again, `maxRetries` times (3 by default) every `retryDelay` milliseconds (100 by default), then throws a
+  `NatsNoRespondersAvailableException`.
+- A timeout and a failed action are never retried: the action may have run, and must not run twice.
+- **A timeout does not stop the action on the service**: the caller stops waiting, but the action runs to its end.
+  This differs from gRPC, where the deadline aborts the action.
+
+The options of `buildServiceProxy` are `natsComponentName`, `serviceId`, `maxRetries` and `retryDelay`.
+
+## 4. Events
+
+A service sends events to the proxies listening to it:
+
+- `nats.emitServiceEvent(event, ...args)`, from the NATS component, under the application id;
+- `entrypoint.broadcast(event, ...args)`, under the subject of the adapter. It returns 0: NATS does not tell how many
+  receive a message. When the `subject` option of the adapter is not the application id, the proxies whose `serviceId`
+  is the application id receive only the events of `emitServiceEvent`.
+
+`entrypoint.notify(clientId, ...)` does not reach the NATS callers, which have no client id.
+
+On the other side, `orderService.on(event, listener)`, `once` and `off` listen to the events of the service. With
+`on(event, listener, true)`, each event goes to only one of the listeners registered this way, across all the
+applications (a queue group). The events are delivered at most once: an application that is not connected when one is
+sent misses it. The listeners of a proxy are removed when it is destroyed.
+
+```typescript
+import type {ServiceProxy} from '@lakutata/nats'
+
+export function watchPayments(orderService: ServiceProxy): void {
+    orderService.on('orderPaid', (id: number, total: number): void => console.log(`Order ${id} paid: ${total}`))
+}
+```
+
+## 5. Errors
+
+| Exception | errno | statusCode | When |
+|---|---|---|---|
+| `ServiceInvokeException` | The errno of the remote error | The one of the remote error | The action failed. Its message and properties are the remote error's, its `service` is the service id |
+| `NatsNoRespondersAvailableException` | `E_NATS_NO_RESPONDERS_AVAILABLE` | 503 | No instance received the request, after the retries |
+| `NatsRequestTimeoutException` | `E_NATS_REQUEST_TIMEOUT` | 408 | No response before the timeout |
+| `NatsBulkException` | `E_NATS_BULK` | 502 | A large payload could not be stored or read (section 7) |
+
+All of them are exported by `@lakutata/nats`. The remote error carries all its properties, its stack included.
+
+## 6. Codecs
+
+Every payload is encoded with the `codec` of the component, which must be the same on both sides of a subject:
+
+- `messagePackCodec()`, the default: MessagePack, compact and fast;
+- `jsonCodec()`: JSON text, easier for the clients written in other languages.
+
+Both send the value through JSON first, so that every client receives plain JSON data: a `Date` arrives as its ISO
+string, a `Buffer` as `{type: 'Buffer', data: [...]}`, a class instance as a plain object, `undefined` as `null`. A
+`bigint` cannot be sent. Any object with `encode(value): Uint8Array` and `decode(bytes)` can be the codec, such as
+`StringCodec()` for text payloads.
+
+## 7. Large payloads
+
+A NATS message cannot be larger than the `max_payload` of the server, 1 MiB by default. The requests and the responses
+of 90% of that size or more are stored in a JetStream object store, and the message only carries a reference to them;
+the receiver reads the object, then deletes it. The callbacks, the actions and `invoke()` always see the whole value.
+
+- This channel is on by default (`bulk: true`) and needs JetStream. Without JetStream, the component prints a warning
+  and starts without it: then only the payloads larger than `max_payload` fail.
+- The applications exchanging large payloads must use the same object store: set the same `bulkBucket` on all of them.
+  By default it is named after the `name` option (`lkt-bulk-<name>`, or `lkt-bulk-default`), so two applications with
+  different names cannot read each other's objects.
+- The objects nobody read expire after `bulkTTL` (5 minutes by default). `bulkReplicas` sets the number of copies in a
+  cluster. Both apply when the store is created.
+- Published messages and events are never stored: larger than `max_payload`, they fail with the NATS error
+  `MAX_PAYLOAD_EXCEEDED`.

package/doc/en/NativeAddons.md

@@ -0,0 +1,212 @@
+# Lakutata Native Addons
+
+A native addon is a library written in C++ or Rust that Node.js loads as a `.node` file: for drivers and devices,
+codecs, system APIs, or code that must run fast. `lakutata add --native` creates an addon package in a workspace,
+ready to build and test; `lakutata native` links libraries to it; and `lakutata package` ships it with the application.
+The addons use Node-API, so one build runs in all the supported versions of Node.js and in Electron.
+
+## 1. Creating an addon
+
+In a workspace ([Workspaces](Workspaces.md)):
+
+```bash
+# One of:
+lakutata add @acme/capture --native --to app          # C++, built by node-gyp
+lakutata add @acme/capture --native cmake --to app    # C++, built by cmake-js
+lakutata add @acme/capture --native rust --to app     # Rust, built by napi-rs (cargo)
+# Then:
+npm install                                           # links the package and builds the addon
+npm run rebuild -w @acme/capture
+npm test -w @acme/capture
+```
+
+| Build system | Its files | Building it needs |
+|---|---|---|
+| `gyp` (the default) | `binding.gyp`, `cpp/binding.cc` | Python and a C++ toolchain: the Xcode command line tools on macOS, build-essential on Linux, the Visual Studio Build Tools on Windows |
+| `cmake` | `CMakeLists.txt`, `cpp/binding.cc` | CMake and a C++ toolchain |
+| `rust` | `Cargo.toml`, `build.rs`, `rust/lib.rs` | Rust (rustup) |
+
+Every addon package also has `src/index.ts`, which loads the addon and gives it a typed API, a test
+(`src/tests/index.spec.ts`), a `tsconfig.json` that compiles `src` into `dist`, and a `README.md`. The C++ addon:
+
+```cpp
+#include <napi.h>
+
+static Napi::Value Greet(const Napi::CallbackInfo &info) {
+    Napi::Env env = info.Env();
+    if (info.Length() < 1 || !info[0].IsString()) {
+        throw Napi::TypeError::New(env, "The name must be a string");
+    }
+    return Napi::String::New(env, "Hello, " + info[0].As<Napi::String>().Utf8Value() + " (native)");
+}
+
+static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    exports.Set("greet", Napi::Function::New(env, Greet));
+    return exports;
+}
+
+NODE_API_MODULE(capture, Init)
+```
+
+The Rust addon:
+
+```rust
+use napi_derive::napi;
+
+/// Greet someone: greet(name)
+#[napi]
+pub fn greet(name: String) -> String {
+    format!("Hello, {} (native)", name)
+}
+```
+
+And `src/index.ts`, the same for all three:
+
+```typescript
+import {createRequire} from 'node:module'
+import path from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+type Binding = {
+    greet(name: string): string
+}
+
+/** The addon built into build/Release, loaded from the directory of the package */
+const binding: Binding = createRequire(import.meta.url)('node-gyp-build')(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'))
+
+export function greet(name: string): string {
+    return binding.greet(name)
+}
+```
+
+| Script | What it does |
+|---|---|
+| `install` | Builds the addon when the package is installed (`npm install`) |
+| `build:native` | Builds the addon into `build/Release/<name>.node` |
+| `build` | Compiles the TypeScript into `dist` |
+| `rebuild` | `clean`, then `build:native` and `build` |
+| `test` | Runs the tests (`node --test`) |
+| `clean`, `clean:native` | Remove `dist`, or the build of the addon (`build`, and `target` for Rust) |
+
+- **Errors**: a C++ exception of node-addon-api reaches JavaScript as an error of the same kind
+  (`Napi::TypeError` becomes a `TypeError`). In Rust, an argument of the wrong type is refused by napi-rs with an
+  `Error` whose `code` says why (`StringExpected`).
+- **macOS**: the C++ addons are built for the Macs with Intel and with Apple silicon in one file; a Rust addon is built
+  for the architecture of the machine (`rustup target add` adds the other ones).
+- **Node-API**: the addons are built for Node-API version 8, which every supported version of Node.js and of Electron
+  provides, so they are not rebuilt for each of them.
+- The package is `"private": true`, like every package that `lakutata add` creates: an addon is usually shipped with
+  its application rather than published.
+
+## 2. Linking libraries
+
+`lakutata native <link|include|define> <value>`, run in the directory of the addon, changes its build file
+(`binding.gyp`, `CMakeLists.txt`, or for Rust `.cargo/config.toml`). The file is edited in place, its comments and its
+layout kept, and the sources of the addon are not touched. Running the same change again changes nothing.
+
+```bash
+lakutata native link z                              # a library of the system (-lz)
+lakutata native link ws2_32 --platform win          # a library of the system, on Windows only
+lakutata native link zlib --pkg-config              # a library found by pkg-config (not on Windows)
+lakutata native link CoreFoundation --framework     # a framework of macOS
+lakutata native link deps/lib/libfoo.a              # a static library of the package, linked into the addon
+lakutata native link deps/lib/libbar.dylib          # a dynamic library of the package, shipped with the addon
+lakutata native include deps/include                # a directory of headers (C++)
+lakutata native define TRACE_LEVEL=3                # a definition of the preprocessor (C++)
+lakutata native link libc --crate                   # a crate (Rust: cargo add)
+```
+
+```
+✔ Linked deps/lib/libbar.dylib (gyp): binding.gyp
+```
+
+- **A file or a system library**: a value with a `/`, or ending in `.a`, `.lib`, `.so`, `.dylib` or `.dll`, is a file of
+  the package; any other value is the name of a library of the system. The files must be inside the package, since they
+  are shipped with it; a directory of headers is one of the package, or an absolute directory of the system.
+- **The platform** of a change: a library file gives its own (`.dylib` macOS, `.so` Linux, `.dll` and `.lib` Windows,
+  `.a` every platform but Windows), `--framework` means macOS, `--pkg-config` every platform but Windows, and
+  `--platform mac|linux|win` chooses one. A change for a platform other than the machine's is noted
+  (`! The change is for win: it is built and tried there`).
+- **Dynamic libraries** are copied next to the addon when it is built, and the addon finds them there at run time
+  through its rpath (`@loader_path` on macOS, `$ORIGIN` on Linux). On macOS, the install name of the library must be
+  `@rpath/libbar.dylib` (`install_name_tool -id @rpath/libbar.dylib deps/lib/libbar.dylib`): the command tells you when
+  it is not. On Windows, a DLL is linked through its import library, which must be next to it (`deps/lib/bar.dll` and
+  `deps/lib/bar.lib`).
+- **Rust addons** link their native libraries through `build.rs`, which reads them from `.cargo/config.toml` (where
+  `lakutata native link` writes them); `include`, `define` and `--pkg-config` are refused, since Rust uses crates for
+  these (`--crate` adds one with `cargo add`, which looks it up in the registry of crates).
+- **Several targets**: when the build file declares several, `--target <name>` chooses the one changed.
+
+What each change writes, by build system:
+
+| | gyp | CMake | Rust |
+|---|---|---|---|
+| File | `binding.gyp`, or the `.gypi` it includes that declares the target | `CMakeLists.txt` | `.cargo/config.toml` (`[env]`), read by `build.rs` |
+| Library | `libraries` | `target_link_libraries` | `rustc-link-lib` |
+| pkg-config | `<!@(pkg-config ...)` | `pkg_check_modules(... IMPORTED_TARGET ...)` | the `-sys` crates |
+| Framework | `xcode_settings.OTHER_LDFLAGS` | `-framework` in `if(APPLE)` | `rustc-link-lib=framework=` |
+| Dynamic library | `copies`, the rpath | `INSTALL_RPATH` (`BUILD_WITH_INSTALL_RPATH`), a `POST_BUILD` copy | `rustc-cdylib-link-arg`, a copy in `build:native` |
+| Headers, definitions | `include_dirs`, `defines` | `target_include_directories`, `target_compile_definitions` | none (crates) |
+| Platform | `conditions` (`OS=="mac"`, `OS!="win"`) | `if(APPLE)`, `if(WIN32)`, `if(NOT WIN32)`, `if(CMAKE_SYSTEM_NAME STREQUAL "Linux")` | `LAKUTATA_NATIVE_MACOS`, `_LINUX`, `_WINDOWS`, `_UNIX` |
+
+For example, `link deps/lib/libbar.dylib` writes the rpath, the library and its copy into the macOS condition of
+`binding.gyp`:
+
+```
+['OS=="mac"', {
+  'xcode_settings': {
+    'MACOSX_DEPLOYMENT_TARGET': '11.0',
+    'OTHER_CFLAGS': ['-arch x86_64', '-arch arm64'],
+    'OTHER_LDFLAGS': [
+      '-arch x86_64', '-arch arm64',
+      '-Wl,-rpath,@loader_path',
+    ],
+  },
+  'libraries': ['<(module_root_dir)/deps/lib/libbar.dylib'],
+  'copies': [
+    {
+      'destination': '<(PRODUCT_DIR)',
+      'files': ['<(module_root_dir)/deps/lib/libbar.dylib']
+    }
+  ]
+}]
+```
+
+(The comments of the generated file are left out here.)
+
+## 3. Other build options
+
+The comments of the generated `binding.gyp` and `CMakeLists.txt` show the forms that `lakutata native` does not write:
+
+- the standard of C++ (`binding.gyp`: `CLANG_CXX_LANGUAGE_STANDARD` on macOS, `cflags_cc` on Linux, `/std:` on Windows;
+  `CMakeLists.txt` sets C++20, which the headers of Node.js need);
+- the options of one platform, in the `conditions` of `binding.gyp`;
+- in `CMakeLists.txt`, a package of CMake (`find_package(ZLIB REQUIRED)`) or a library built from its own sources
+  (`add_subdirectory(deps/foo)`).
+
+A library built by its own Makefile is built before the addon by a script of the package:
+
+```json
+{
+  "scripts": {
+    "build:deps": "make -C deps/foo",
+    "build:native": "npm run build:deps && node-gyp rebuild"
+  }
+}
+```
+
+## 4. Shipping an addon
+
+The application depends on the addon package, and imports it as any package (`import {greet} from '@acme/capture'`).
+
+- **Bundles and executables**: `lakutata package bundle` leaves the addon packages out of the bundle and writes them,
+  with their files (their JavaScript, the addon, its dynamic libraries) but without their sources and what built them,
+  into `dist/<name>.native/`, which is shipped with the bundle; an executable embeds them, or holds them next to it in
+  the directory layout ([Packaging](Packaging.md)). The addon is built for the platform of the machine that packs the
+  application, so pack the application of each platform on that platform (a CI matrix, or a container of the
+  architecture for Linux).
+- **Electron**: the addons are copied as they are installed. The addons that `lakutata add` creates run in Electron
+  without being rebuilt, as do all the addons built on Node-API; an addon built on the V8 API of Node.js must be
+  installed in its build for Electron before packing (`electron-rebuild`).
+- **Bun**: Bun loads the addons of Node-API; an executable of Bun warns of the addons built on the V8 API of Node.js.
+- **Alpine (musl)**: the executables of Node.js do not load native addons there: make them with Bun.

package/doc/en/Objects.md

@@ -0,0 +1,143 @@
+# Lakutata Objects and Lifetimes
+
+Every object of an application (components, providers, controllers) is created by an IoC container; you never call
+`new`. This page covers the classes of these objects, their lifetimes and scopes, how they are created and destroyed,
+and how to use them without an application. They come from the package `@lakutata/core`, which `lakutata`,
+`lakutata/decorator/di`, `lakutata/decorator/dto` and `lakutata/decorator/asst` re-export; its README and the type
+declarations of each export give the details.
+
+## 1. The classes
+
+| Class | Role | Default lifetime |
+|---|---|---|
+| `BaseObject` | The root class: asynchronous construction, `init()`/`destroy()`, `getObject()` | `@Transient` |
+| `Provider` | A unit of work that lives in a scope such as a request (a repository, a password hasher) | `@Scoped` |
+| `Component` | A long-lived service shared by the whole application (a logger, a database, an entrypoint); also an event emitter | `@Singleton` (locked) |
+| `Application` | The application: it declares the components, providers and objects, and is created by `Application.run()` | |
+| `Controller` (`lakutata/com/entrypoint`) | A provider that handles the requests of an entrypoint | `@Scoped` (locked) |
+
+## 2. Lifetimes
+
+| Decorator (`lakutata/decorator/di`) | One instance… |
+|---|---|
+| `@Singleton()` | per container that registers the class, shared by everything that uses it, including its scopes |
+| `@Scoped()` | per scope (`container.createScope()`; each request of an entrypoint is a scope, the root container is one too) |
+| `@Transient()` | per resolution, never cached |
+
+Subclasses inherit the lifetime. `Component` locks its lifetime: a subclass that declares a different one throws a
+`LifetimeLockedException`. A `Provider` is `@Scoped` by default but may be declared `@Transient` or `@Singleton` (as in
+2.x, one instance shared by all scopes, like the `ServiceProxy` of `@lakutata/nats`). A long-lived object that owns
+resources (connections, subscriptions, servers) is better written as a `Component`. When a singleton injects a scoped
+object, it keeps the instance from the scope that created it. `@Lifetime('SINGLETON' | 'SCOPED' | 'TRANSIENT', lock)` is
+the long form of the three decorators.
+
+## 3. Scopes
+
+A scope is a child container that holds its own instances of the scoped objects and shares the singletons and
+registrations of its parent. The entrypoint creates a scope for each request: the request's controller and the providers
+it injects are created in it and destroyed when the request ends. A component can create its own scope with its
+protected `createScope()`.
+
+## 4. Creation and teardown
+
+The container creates objects asynchronously: the promise returned by `getObject()` (or resolved for `@Inject`) settles
+once the object is ready. Creation goes through these steps:
+
+1. its `@Inject` properties are resolved;
+2. its `@Configurable` properties receive their configured values, validated (and converted) by their schemas; a
+   property that is not configured keeps its initializer, or the default of its schema when it has none;
+3. its `init()` runs (an error thrown here fails the creation);
+4. its `startup()` runs. By then other objects can already obtain it, but they wait for `startup()` to finish (and fail
+   with its error if it throws). The exception is anything requested from inside `startup()`, directly or through the
+   objects it creates: those get the object at once, which is how an object requested there can inject it back (an
+   entrypoint starts its adapters in `startup()`, and their hooks obtain an authenticator that injects the entrypoint).
+   The method is named `startup` rather than `start` so that classes with a `start()` method of their own, such as the
+   containers of `@lakutata/docker`, are not started by the framework;
+5. once the application has launched (and the object has started), its `launched()` runs; it is not awaited, and its
+   errors are logged.
+
+An object is torn down by `dispose()`, or along with the object, scope or application that created it. Teardown waits
+for `startup()` to end, then runs `beforeDestroy()`, destroys the objects it created, and finally runs `destroy()`. Each
+object owns a container, so whatever it creates with `this.getObject()` is destroyed with it.
+
+```typescript
+import {Application, Component, type ILogger} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+
+class Poller extends Component {
+    @Inject('log')
+    protected readonly log: ILogger
+
+    protected timer: NodeJS.Timeout
+
+    //Its dependencies are injected and its options set
+    protected async init(): Promise<void> {
+        this.log.info('init')
+    }
+
+    //Other objects can already get it, but they wait until this ends
+    protected async startup(): Promise<void> {
+        this.timer = setInterval((): void => this.log.info('polling'), 10000)
+        this.log.info('startup')
+    }
+
+    //The application has launched (not awaited)
+    protected async launched(): Promise<void> {
+        this.log.info('launched')
+    }
+
+    //Teardown begins: the objects it created still exist
+    protected async beforeDestroy(): Promise<void> {
+        this.log.info('beforeDestroy')
+    }
+
+    //Teardown ends: the objects it created are destroyed
+    protected async destroy(): Promise<void> {
+        clearInterval(this.timer)
+        this.log.info('destroy')
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'poller.app',
+        name: 'Poller',
+        components: {
+            poller: {class: Poller}
+        },
+        bootstrap: ['poller']
+    }))
+    .onLaunched((app: Application, log: ILogger): void => log.info('onLaunched'))
+    .onDone((app: Application, log: ILogger): void => log.info('onDone'))
+```
+
+It logs `init`, `startup`, `launched` and `onLaunched`. On Ctrl+C, it logs `onDone`, `beforeDestroy` and `destroy`,
+then the process exits.
+
+## 5. A container without an application
+
+Tests, scripts and libraries can use these objects in a bare container, without an application:
+
+```typescript
+import {Component, Container, DTO} from 'lakutata'
+import {Configurable} from 'lakutata/decorator/di'
+
+class Mailer extends Component {
+    @Configurable(DTO.String().required())
+    protected readonly host: string
+
+    public async send(to: string, text: string): Promise<string> {
+        return `${this.host} -> ${to}: ${text}`
+    }
+}
+
+const container: Container = new Container()
+//Created with its options; its init() is awaited
+const mailer: Mailer = await container.set(Mailer, {host: 'localhost'})
+await mailer.send('someone@example.com', 'Hello')
+//Destroys the objects it created
+await container.destroy()
+```
+
+`container.register()` and `registerNamed()` register a class without creating it, `get()` resolves an object, `build()`
+always creates a new instance whatever the lifetime, and `createScope()` creates a scope.