lakutata 3.1.5 → 3.1.6

package/README.md

@@ -21,8 +21,8 @@ English | [中文](README.zh-CN.md)
 An IoC-based application framework for Node.js and TypeScript, with one programming model for web services, CLI tools,
 desktop (Electron, NW.js) applications and embedded devices. An application is a tree of objects (components, providers,
 controllers) that a container creates. DTOs validate their options and inputs, and transports expose the controllers:
-HTTP (Express, Fastify), CLI (Commander), service RPC (HTTP, Socket.IO, JSON-RPC 2.0, gRPC, NATS, Electron IPC, NW.js),
-schedules and message queues. One controller method can serve all of them at once.
+HTTP (Express, Fastify), CLI (Commander), service RPC (HTTP, Socket.IO, JSON-RPC 2.0, gRPC, NATS, Electron IPC, NW.js,
+React Native), schedules and message queues. One controller method can serve all of them at once.
 
 This package is the framework itself: it re-exports the `@lakutata/*` packages under the subpaths listed below and
 presets two components in every application, `log` and `entrypoint`. The typings of each subpath document every
@@ -108,7 +108,7 @@ Application
 | `lakutata/decorator/ctrl` | `@lakutata/entrypoint` | `@HTTPAction`, `@GET`…`@OPTIONS`, `@CLIAction`, `@ServiceAction`, `@Schedule`, `@Prefix`, `@UseMiddlewares` |
 | `lakutata/adapter/express`, `lakutata/adapter/fastify` | `@lakutata/entrypoint` | The HTTP transports, `staticUI` (Express only) |
 | `lakutata/adapter/commander` | `@lakutata/entrypoint` | The CLI transport |
-| `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron`, `lakutata/adapter/nwjs` | `@lakutata/entrypoint` | The service transports |
+| `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron`, `lakutata/adapter/nwjs`, `lakutata/adapter/react-native` | `@lakutata/entrypoint` | The service transports |
 | `lakutata/com/logger` | `@lakutata/logger` | The `Logger` component preset as `log` (pino-compatible JSON lines) |
 | `lakutata/orm`, `lakutata/decorator/orm` | `@lakutata/orm` | TypeORM, its decorators |
 | `lakutata/com/database`, `lakutata/provider/database` | `@lakutata/orm` | The `Database` component and provider, the migration commands |
@@ -144,9 +144,9 @@ on. Each package's README lists its exceptions.
   `Entrypoint.md`, `Middlewares.md`, `HTTP.md`, `CLI.md`, `ServiceCalls.md`, `GRPC.md`, `NATS.md`, `Schedules.md`,
   `Queue.md`, `Database.md`, `DatabaseDrivers.md`, `MongoEmbedded.md`, `Entities.md`, `Migrations.md`, `Cache.md`,
   `Mutex.md`, `I18n.md`, `DockerIntegration.md`, `ContainerdIntegration.md`, `Monitor.md`, `Security.md`, `DBus.md`,
-  `MCP.md`, `WebRTC.md`, `FFI.md`, `Math.md`, `Netif.md`, `Command.md`, `Workspaces.md`, `NativeAddons.md`,
-  `Packaging.md`, `Installers.md`; and the examples, in `doc/en/examples` and `doc/zh/examples`: whole applications
-  built from the templates.
+  `MCP.md`, `WebRTC.md`, `FFI.md`, `Barcode.md`, `Math.md`, `Netif.md`, `Command.md`, `Workspaces.md`,
+  `NativeAddons.md`, `Packaging.md`, `Installers.md`; and the examples, in `doc/en/examples` and `doc/zh/examples`:
+  whole applications built from the templates.
 - `@lakutata/cli`: creating, building and packaging applications.
 - The official Agent Skill for AI coding assistants that work on lakutata projects:
   [lakutata.com/skill](https://lakutata.com/skill/).

package/README.zh-CN.md

@@ -18,7 +18,7 @@
 
 # lakutata
 
-一个基于 IoC 的 Node.js 和 TypeScript 应用框架，让 Web 服务、命令行工具、桌面（Electron、NW.js）应用和嵌入式设备共用同一套编程模型。应用是一棵由容器创建的对象树（组件、提供者、控制器）。DTO 校验对象的选项和输入，各种传输方式把控制器暴露出去：HTTP（Express、Fastify）、CLI（Commander）、服务调用（HTTP、Socket.IO、JSON-RPC 2.0、gRPC、NATS、Electron IPC、NW.js）、定时任务和消息队列。同一个控制器方法可以同时通过所有这些方式调用。
+一个基于 IoC 的 Node.js 和 TypeScript 应用框架，让 Web 服务、命令行工具、桌面（Electron、NW.js）应用和嵌入式设备共用同一套编程模型。应用是一棵由容器创建的对象树（组件、提供者、控制器）。DTO 校验对象的选项和输入，各种传输方式把控制器暴露出去：HTTP（Express、Fastify）、CLI（Commander）、服务调用（HTTP、Socket.IO、JSON-RPC 2.0、gRPC、NATS、Electron IPC、NW.js、React Native）、定时任务和消息队列。同一个控制器方法可以同时通过所有这些方式调用。
 
 这个包就是框架本身：它通过下面列出的子路径重新导出各个 `@lakutata/*` 包，并为每个应用预置两个组件：`log` 和 `entrypoint`。各子路径的类型声明中，每一项都附有说明和示例，每个 `@lakutata/*` 包也都有自己的 README。
 
@@ -97,7 +97,7 @@ Application
 | `lakutata/decorator/ctrl` | `@lakutata/entrypoint` | `@HTTPAction`、`@GET`…`@OPTIONS`、`@CLIAction`、`@ServiceAction`、`@Schedule`、`@Prefix`、`@UseMiddlewares` |
 | `lakutata/adapter/express`、`lakutata/adapter/fastify` | `@lakutata/entrypoint` | HTTP 传输、`staticUI`（仅 Express） |
 | `lakutata/adapter/commander` | `@lakutata/entrypoint` | CLI 传输 |
-| `lakutata/adapter/socket.io`、`lakutata/adapter/jsonrpc`、`lakutata/adapter/electron`、`lakutata/adapter/nwjs` | `@lakutata/entrypoint` | 服务传输 |
+| `lakutata/adapter/socket.io`、`lakutata/adapter/jsonrpc`、`lakutata/adapter/electron`、`lakutata/adapter/nwjs`、`lakutata/adapter/react-native` | `@lakutata/entrypoint` | 服务传输 |
 | `lakutata/com/logger` | `@lakutata/logger` | `Logger` 组件，预置为 `log`（输出与 pino 兼容的 JSON 行） |
 | `lakutata/orm`、`lakutata/decorator/orm` | `@lakutata/orm` | TypeORM 及其装饰器 |
 | `lakutata/com/database`、`lakutata/provider/database` | `@lakutata/orm` | `Database` 组件和提供者、迁移命令 |
@@ -121,7 +121,7 @@ Application
 ## 另见
 
 - 网站 <https://lakutata.com/zh/>：指南、示例和 API 参考，中英文都有。
-- 指南在这个包的 `doc/zh`（中文）和 `doc/en`（英文）中：`Overview.md`、`GettingStarted.md`、`ProjectStructure.md`、`UpgradingFrom2.md`、`UpgradingFrom1.md`、`Application.md`、`Objects.md`、`Injection.md`、`DTOValidation.md`、`Exceptions.md`、`Logger.md`、`Decorator.md`、`Time.md`、`HelperFunctions.md`、`Controllers.md`、`Entrypoint.md`、`Middlewares.md`、`HTTP.md`、`CLI.md`、`ServiceCalls.md`、`GRPC.md`、`NATS.md`、`Schedules.md`、`Queue.md`、`Database.md`、`DatabaseDrivers.md`、`MongoEmbedded.md`、`Entities.md`、`Migrations.md`、`Cache.md`、`Mutex.md`、`I18n.md`、`DockerIntegration.md`、`ContainerdIntegration.md`、`Monitor.md`、`Security.md`、`DBus.md`、`MCP.md`、`WebRTC.md`、`FFI.md`、`Math.md`、`Netif.md`、`Command.md`、`Workspaces.md`、`NativeAddons.md`、`Packaging.md`、`Installers.md`；示例在 `doc/zh/examples` 和 `doc/en/examples` 中：从模板构建的完整应用。
+- 指南在这个包的 `doc/zh`（中文）和 `doc/en`（英文）中：`Overview.md`、`GettingStarted.md`、`ProjectStructure.md`、`UpgradingFrom2.md`、`UpgradingFrom1.md`、`Application.md`、`Objects.md`、`Injection.md`、`DTOValidation.md`、`Exceptions.md`、`Logger.md`、`Decorator.md`、`Time.md`、`HelperFunctions.md`、`Controllers.md`、`Entrypoint.md`、`Middlewares.md`、`HTTP.md`、`CLI.md`、`ServiceCalls.md`、`GRPC.md`、`NATS.md`、`Schedules.md`、`Queue.md`、`Database.md`、`DatabaseDrivers.md`、`MongoEmbedded.md`、`Entities.md`、`Migrations.md`、`Cache.md`、`Mutex.md`、`I18n.md`、`DockerIntegration.md`、`ContainerdIntegration.md`、`Monitor.md`、`Security.md`、`DBus.md`、`MCP.md`、`WebRTC.md`、`FFI.md`、`Barcode.md`、`Math.md`、`Netif.md`、`Command.md`、`Workspaces.md`、`NativeAddons.md`、`Packaging.md`、`Installers.md`；示例在 `doc/zh/examples` 和 `doc/en/examples` 中：从模板构建的完整应用。
 - `@lakutata/cli`：创建、构建和打包应用。
 - 官方 Agent Skill（智能体技能），供 AI 编程助手在 lakutata 项目中使用：<https://lakutata.com/zh/skill/>。
 

package/dist/cjs/exports/ReactNativeAdapter.d.ts

@@ -0,0 +1 @@
+export * from '@lakutata/entrypoint/adapter/react-native';

package/dist/cjs/exports/ReactNativeAdapter.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("@lakutata/entrypoint/adapter/react-native"), exports);
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

package/dist/esm/exports/ReactNativeAdapter.js

@@ -0,0 +1 @@
+export * from '@lakutata/entrypoint/adapter/react-native';

package/dist/types/exports/ReactNativeAdapter.d.ts

@@ -0,0 +1 @@
+export * from '@lakutata/entrypoint/adapter/react-native';

package/doc/en/Application.md

@@ -55,6 +55,11 @@ Application
     })
 ```
 
+The environment variables and the aliases are set when the application launches, before its options are read. An option
+that uses an alias, such as `path.resolve('@data/app.sqlite')`, is therefore written in an options function given to
+`run()`, as above: an object given to `run()` is made before the launch, when `@data` is not declared yet, and
+`path.resolve()` gives `app.sqlite` in a directory named `@data` of the working directory.
+
 `app.exit(code)` ends the application gracefully with that exit code; `app.exit(true)` ends the process immediately with
 exit code 2, skipping the done handlers and the teardown.
 

package/doc/en/Barcode.md

@@ -0,0 +1,386 @@
+# Lakutata Barcode
+
+The package `@lakutata/barcode` generates barcodes and QR codes and reads them from images: product labels, shipping
+labels, tickets and links printed as QR codes, scanned from uploaded photos or from the frames of a camera. It is not
+part of `lakutata`: install it on its own. What it is like:
+
+- **What it generates, it reads back**: 32 linear and matrix formats, from EAN-13, UPC, Code 128 and the GS1 DataBar to
+  QR Code, Data Matrix, PDF417, Aztec and MaxiCode. The formats only one side handles (the postal codes, Han Xin,
+  DotCode…) are left out.
+- **Generated** as a PNG, an SVG or pixels, at the size, in the colors and the rotation, with the error correction asked
+  for.
+- **Read** from PNG, JPEG, GIF, BMP, WebP and TGA images, or from pixels; every code of an image, with its position.
+- **A component**, `Barcode`, injected without being registered, with the default options; the components registered
+  under names in the configuration have defaults, a time limit and a concurrency of their own. Every call can take a
+  time limit, and can be cancelled.
+- **A native addon** built on [zint](https://zint.org.uk) and [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp),
+  compiled when the package is installed on Linux, macOS and Windows, and by `lakutata mobile stage` for the mobile
+  applications of Android, iOS and HarmonyOS; it also runs in Bun and in the main process of Electron. Its work runs in
+  its own threads, never in the thread of JavaScript.
+
+The README of `@lakutata/barcode` describes every option; this guide goes through what the package is for, with an
+example of each use.
+
+```bash
+npm install @lakutata/barcode
+```
+
+The addon is compiled when the package is installed, so the machine needs Python 3 and a C++20 compiler (the Command
+Line Tools of Xcode, `build-essential` or `build-base` on Linux, the Build Tools of Visual Studio on Windows). The
+package manager has to run the install script of the package: npm runs it, and may warn that the script is "not yet
+covered by allowScripts" (`npm install-scripts approve @lakutata/barcode` records that you allow it); Bun and pnpm run
+it only for the packages they are told to trust (`trustedDependencies` in the package.json for Bun, `pnpm
+approve-builds` for pnpm). The component needs `@lakutata/core`, a peer dependency that `lakutata` brings.
+
+## 1. Generating a code
+
+`generate(format, content, options)` takes the content as text, encoded in UTF-8, or as bytes (a `Uint8Array`), and
+gives a PNG by default:
+
+```typescript
+import {Container} from 'lakutata'
+import {Barcode, type RawImage} from '@lakutata/barcode'
+
+const container: Container = new Container()
+const barcode: Barcode = await container.get(Barcode)
+
+const png: Buffer = await barcode.generate('QRCode', 'https://example.com/orders/123')
+const svg: string = await barcode.generate('DataMatrix', 'LKT-1001', {output: 'svg'})
+const pixels: RawImage = await barcode.generate('Code128', 'LKT-1001', {output: 'raw', scale: 2})
+console.log(png.length, svg.length)                          //704 1008
+console.log(pixels.width, pixels.height, pixels.channels)    //264 116 1
+
+await container.destroy()
+```
+
+- The size of a matrix code (its version) and the way its content is encoded are chosen for the content: the smallest
+  symbol that holds it, unless `version` asks for one.
+- The pixels are gray in black and white (1 byte a pixel), RGB with colors (3), RGBA with transparency (4): what a
+  canvas, an image library or a printer driver takes.
+- A content the format cannot encode (letters in an EAN-13, too long for the version asked) throws
+  `BarcodeContentException`, with the reason given by zint.
+
+In an application, the component is injected instead of taken from a container; for options of your own, register a
+component under a name in the configuration and inject it by that name (section 5).
+
+## 2. Size, colors and printing
+
+`scale` is the size of a module, the narrowest bar or a square of a matrix code: pixels in a PNG and in pixels, units
+in an SVG. It is a whole number, so the bars of a PNG keep sharp edges. For print, the size of a module in millimetres
+gives the scale: `scale = mm × dpi / 25.4`, rounded. An EAN-13 has modules of 0.33 mm at its nominal size, and may be
+printed from 80% to 200% of it: on a thermal label printer of 203 dpi, a scale of 3 gives modules of 0.375 mm (114%);
+at 300 dpi, a scale of 4 gives 0.34 mm. An SVG prints at any size: its scale only sets its units.
+
+- `height` sets the height of the bars of a linear format, in modules, so it follows the scale.
+- `showText` prints the content under the bars of a linear format, from a scale of 2 in a PNG or in pixels (the font
+  needs 2 pixels a module).
+- `quietZone` keeps the margins the standard of the format asks for (by default); a scanner needs them to find the code,
+  so a label without them must leave the space around the code blank.
+- `foreground` and `background` take `#RRGGBB` and `#RRGGBBAA`. Keep dark bars on a light background: the package
+  reads light on dark too (`tryInvert`), but many scanners do not. A transparent background is read as if it were white.
+- `rotate` turns the code by 90, 180 or 270 degrees, clockwise, for a label printed sideways.
+- `errorCorrection` lets a matrix code be read with part of it damaged or covered: from `'L'` (about 7%) to `'H'`
+  (about 30%) for QR Code. A higher level makes a larger code for the same content.
+
+## 3. EAN, UPC and GS1
+
+The retail formats compute their check digit, and verify the one they are given:
+
+```typescript
+import {Container} from 'lakutata'
+import {Barcode, type BarcodeResult, BarcodeContentException} from '@lakutata/barcode'
+
+const container: Container = new Container()
+const barcode: Barcode = await container.get(Barcode)
+
+//12 digits: the check digit is computed
+const ean: Buffer = await barcode.generate('EAN13', '590123412345', {addOn: '12'})
+const [product]: BarcodeResult[] = await barcode.read(ean)
+console.log(product.format, product.text, product.addOn)        //EAN13 5901234123457 12
+
+//13 digits: the check digit is verified
+await barcode.generate('EAN13', '5901234123458').catch((error: BarcodeContentException) => console.log(error.message))
+//Error 275: Invalid check digit '8', expecting '7'
+
+//A logistics label: the GTIN, the expiry date and the batch
+const gs1: Buffer = await barcode.generate('Code128', '[01]09506000134352[17]261231[10]ABC123', {gs1: true})
+const [label]: BarcodeResult[] = await barcode.read(gs1)
+console.log(label.text, label.gs1, label.symbologyIdentifier)   //(01)09506000134352(17)261231(10)ABC123 true ]C1
+
+await container.destroy()
+```
+
+- **UPC.** A UPC-A is an EAN-13 that starts with 0, and is read as an `EAN13` of 13 digits: `01234567890` gives
+  `0012345678905`. Asking for `formats: ['UPCA']` without `EAN13` gives the format `UPCA`, with the same 13 digits. An
+  ISBN is read as an `EAN13` too.
+- **Add-ons.** The add-on of 2 or 5 digits (an issue number, a price) is in `addOn`, apart from the text. With
+  `addOn: 'require'`, a read keeps only the codes that have one.
+- **GS1.** The application identifiers are written in brackets or in parentheses; with `gs1: true`, Code 128 becomes
+  GS1-128, and QR Code, Data Matrix and Aztec take GS1 data too. The DataBar Expanded formats always hold GS1 data; the
+  other DataBar formats hold a GTIN, given with or without its check digit. A read gives the data in parentheses, with
+  `gs1: true`.
+
+The README of the package lists, format by format, the format it is read as and the text a read gives.
+
+## 4. Reading images
+
+`read(image, options)` takes an image file (its bytes, a `Buffer` or a `Uint8Array`) or pixels, and gives every code it
+finds, an empty array when there is none:
+
+```typescript
+import {readFileSync} from 'node:fs'
+import {Container} from 'lakutata'
+import {Barcode, type BarcodeResult, type RawImage} from '@lakutata/barcode'
+
+const container: Container = new Container()
+const barcode: Barcode = await container.get(Barcode)
+
+const photo: Buffer = readFileSync('qrcode.jpeg')
+for (const result of await barcode.read(photo, {formats: ['QRCode', 'DataMatrix']})) {
+    console.log(result.format, result.text, result.position.topLeft, result.orientation)
+    //QRCode https://lakutata.com/fixtures { x: 16, y: 16 } 0
+}
+
+//Pixels: 1 byte a pixel in gray, 3 in RGB, 4 in RGBA (the ImageData of a canvas, a decoded video frame)
+const frame: RawImage = await barcode.generate('DataMatrix', 'LKT-1001', {output: 'raw'})
+const rgba: Uint8Array = new Uint8Array(frame.width * frame.height * 4)
+frame.data.forEach((gray: number, index: number): void => rgba.set([gray, gray, gray, 255], index * 4))
+const results: BarcodeResult[] = await barcode.read({data: rgba, width: frame.width, height: frame.height, channels: 4})
+console.log(results.map((result: BarcodeResult): string => result.text))   //[ 'LKT-1001' ]
+
+await container.destroy()
+```
+
+- **Faster reads.** `formats` limits the search to the formats expected: reading a QR Code in a 1920×1080 frame takes
+  about 8 ms looking for every format, 1.4 ms looking for QR codes only (section 7). `pure: true` reads an image that
+  holds one code, straight, with nothing around it, such as an image made by `generate()`.
+- **Harder images.** `tryHarder`, `tryRotate`, `tryInvert` and `tryDownscale` are on by default: they look again for
+  codes that are small, turned, light on dark or in large images. Turned off, a read of images known to be easy is
+  faster.
+- **What is not read.** A code whose modules are less than about 2 pixels wide, a blurred or a glaring photo, a code cut
+  by the edge of the image. The read then gives fewer codes, or none: it throws only for an image it cannot decode
+  (`BarcodeImageException`).
+- **Large images** of more than 50 million pixels are refused before their pixels are decoded, so an uploaded file
+  cannot make the process allocate gigabytes.
+- **The bytes.** `bytes` holds the content as it is encoded; `text` is its readable form (with the check digits, GS1 in
+  parentheses), and `symbologyIdentifier` tells how to read the bytes (`]Q1` a QR Code, `]C1` GS1-128…).
+
+## 5. In an application
+
+The component is injected without being registered (`@Inject(Barcode)`), with the default options. For options of your
+own, register a component in the `components` of the configuration: `buildBarcodeOptions()` declares it under a name,
+with defaults for `generate()` and `read()`, a time limit and a concurrency; an application may register several, under
+different names, each with its own options. The application below registers two, `labels` to print labels and
+`scanner` to read photos:
+
+```typescript
+import {Application, Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {type Barcode, type BarcodeResult, buildBarcodeOptions} from '@lakutata/barcode'
+
+class Warehouse extends Component {
+    @Inject('labels')
+    protected readonly labels: Barcode
+
+    @Inject('scanner')
+    protected readonly scanner: Barcode
+
+    //The label of an item: a Code 128 with its number printed under the bars
+    public async label(sku: string): Promise<Buffer> {
+        return await this.labels.generate('Code128', sku)
+    }
+
+    //The codes of a photo: Code 128 and QR codes only
+    public async scan(photo: Buffer): Promise<BarcodeResult[]> {
+        return await this.scanner.read(photo)
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'warehouse.app',
+        name: 'Warehouse',
+        components: {
+            //A label printer of 203 dpi: modules of 3 pixels, the content under the bars
+            labels: buildBarcodeOptions({defaults: {generate: {scale: 3, showText: true}}}),
+            //At most 2 seconds a photo
+            scanner: buildBarcodeOptions({defaults: {read: {formats: ['Code128', 'QRCode']}}, timeout: 2000}),
+            warehouse: {class: Warehouse}
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const warehouse: Warehouse = await app.getObject<Warehouse>('warehouse')
+        const [code]: BarcodeResult[] = await warehouse.scan(await warehouse.label('LKT-1001'))
+        console.log(code.format, code.text)     //Code128 LKT-1001
+    })
+```
+
+- `buildBarcodeOptions()` declares the component under the name of your choice; the other objects inject it by that name
+  (`@Inject('labels')`) or get it with `getObject('labels')`.
+- A registered component is injected by its name only: `@Inject(Barcode)` gives another component, autoloaded with the
+  default options; the options of the configuration do not apply to it.
+
+A controller that serves the label of a product as a PNG and reads the codes of an uploaded image:
+
+```typescript
+import express, {type Express, type Request} from 'express'
+import {Application, DTO} from 'lakutata'
+import {buildEntrypoints, Controller, type FileResult, Result} from 'lakutata/com/entrypoint'
+import {GET, POST} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+import {Expect} from 'lakutata/decorator/dto'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {Barcode, type BarcodeResult, buildBarcodeOptions} from '@lakutata/barcode'
+
+class LabelDTO extends DTO {
+    @Expect(DTO.String().pattern(/^\d{12,13}$/).required())
+    public ean: string
+}
+
+class ScanDTO extends DTO {
+    @Expect(DTO.Binary().required())
+    public image: Buffer
+}
+
+class LabelController extends Controller {
+    @Inject('labels')
+    protected readonly labels: Barcode
+
+    //GET /labels/590123412345: the EAN-13 of a product, as a PNG
+    @GET('/labels/:ean', LabelDTO)
+    public async label(input: LabelDTO): Promise<FileResult> {
+        return Result.file(await this.labels.generate('EAN13', input.ean), {contentType: 'image/png'})
+    }
+
+    //POST /scans, an image as its body: the codes found in it
+    @POST('/scans', ScanDTO)
+    public async scan(input: ScanDTO): Promise<{ format: string, text: string }[]> {
+        const results: BarcodeResult[] = await this.labels.read(input.image)
+        return results.map((result: BarcodeResult) => ({format: result.format, text: result.text}))
+    }
+}
+
+Application.run(() => ({
+    id: 'shop.app',
+    name: 'Shop',
+    components: {
+        labels: buildBarcodeOptions({defaults: {generate: {scale: 3}, read: {formats: ['EAN13', 'QRCode']}}, timeout: 10000}),
+        entrypoint: buildEntrypoints({
+            controllers: [LabelController],
+            http: expressHTTPEntrypoint({
+                port: 8080,
+                before: (app: Express): void => {
+                    //The body of POST /scans is the image
+                    app.post('/scans', express.raw({type: 'image/*', limit: '10mb'}))
+                },
+                input: (request: Request): Record<string, unknown> => Buffer.isBuffer(request.body) ? {image: request.body} : {...request.query, ...request.body}
+            })
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+```text
+$ curl -s -o label.png localhost:8080/labels/590123412345
+$ curl -s --data-binary @label.png -H 'Content-Type: image/png' localhost:8080/scans
+[{"format":"EAN13","text":"5901234123457"}]
+```
+
+- The options of a call go over the defaults of the component: `this.labels.generate('QRCode', url, {scale: 6})` keeps
+  the other defaults.
+- The arguments are validated: an unknown format or a color not written `#RRGGBB` is refused with
+  `InvalidMethodAcceptException` before the addon is called.
+- One component serves every controller at once: its calls do not depend on one another, except for its
+  `concurrency`.
+- In a mobile application of React Native (the mobile template), the component runs in the Node.js of the application in
+  the same way: `lakutata mobile stage` compiles the addon from its sources for Android (with the NDK), iOS (Xcode) and
+  HarmonyOS (DevEco Studio).
+
+## 6. Time limits, cancellation and concurrency
+
+Every call takes a `signal` (an `AbortSignal`) and a `timeout` in milliseconds, which count from the call; the
+`timeout` of the component applies to the calls without one.
+
+```typescript
+import {readFileSync} from 'node:fs'
+import {Container} from 'lakutata'
+import {Barcode, type BarcodeResult} from '@lakutata/barcode'
+
+const container: Container = new Container()
+const barcode: Barcode = await container.get(Barcode)
+const photo: Buffer = readFileSync('qrcode.jpeg')
+
+//At most 2 seconds, the wait for its turn included
+const results: BarcodeResult[] = await barcode.read(photo, {timeout: 2000})
+
+//Until the scan is cancelled
+const scan: AbortController = new AbortController()
+const reading: Promise<BarcodeResult[]> = barcode.read(photo, {signal: scan.signal})
+scan.abort()
+await reading.catch((error: Error) => console.log(error.constructor.name))   //BarcodeCancelledException
+
+await container.destroy()
+```
+
+- An operation that has not started yet is dropped. One that is running cannot be stopped, since zint and zxing-cpp
+  have no point where they could be interrupted: its promise is rejected at once (`BarcodeTimeoutException`,
+  `BarcodeCancelledException`), and its result is discarded when it ends. The operations are short (section 7); the
+  time limits are there for the large photos and the hostile uploads.
+- `concurrency` limits the operations of a component running at once; the others wait for their turn, and their time
+  limit runs while they wait. Without it, the operations queue in the threads of the addon.
+- The addon runs `LAKUTATA_BARCODE_THREADS` threads, by default one less than the processors, shared by every
+  component; it does not use the thread pool of libuv, so file and DNS operations are not held up.
+- When the application stops, the component waits for its operations running, at most `drainTimeout` milliseconds
+  (10000 by default); the operations still waiting are rejected with `BarcodeCancelledException`, and so is every call
+  after that.
+
+## 7. Speed
+
+Measured on an Apple M4 (Node.js 24, one call at a time unless stated):
+
+| Operation | Time |
+|---|---|
+| A QR Code of a URL, as a PNG (148×148) | 0.19 ms |
+| The same QR Code as pixels / as an SVG | 0.08 ms / 0.17 ms |
+| An EAN-13 / a Code 128 as a PNG, with its text | 0.62 ms / 1.6 ms |
+| Reading that QR Code PNG, every format / `formats: ['QRCode']` | 0.33 ms / 0.11 ms |
+| Reading its pixels, `formats: ['QRCode']`, `pure: true` | 0.06 ms |
+| Reading a QR Code in a 1920×1080 frame, every format / `formats: ['QRCode']` | 7.8 ms / 1.4 ms |
+| 1000 QR Code PNGs generated at once / read at once (9 threads) | 63 ms / 33 ms |
+
+A photo taken by a phone is slower to read than these images made by `generate()`: its code is smaller, turned and
+blurred, and the `try…` options work harder on it.
+
+## 8. How it is checked, and what it does not do
+
+The tests generate every format and read it back from its PNG and from its pixels, with random contents (text in several
+scripts, and bytes), check the effect of each option, read images in the seven file formats, and read 240 damaged
+images, which must give codes or `BarcodeImageException` and nothing else. They run on macOS (arm64: Node.js 24 and
+18.10, Bun 1.4), on Linux (arm64: Node.js 22 on Debian 12, Node.js 24 on Alpine) and on Windows 11 (arm64: Node.js 24);
+the package also runs in the main process of Electron 44, and in the mobile applications of Android, iOS and HarmonyOS,
+where every format and the seven file formats are read back on their emulators.
+
+What it does not do, whether by design or not yet:
+
+- The formats zxing-cpp cannot read back are not generated: the four-state postal codes, Han Xin, DotCode, Code One,
+  Grid Matrix, Codablock-F, Code 16K, Code 49 and the other stacked formats of zint. Telepen Numeric is left out too,
+  since a read takes it for Telepen unless it looks for nothing else.
+- A code split over several symbols (structured append) is read symbol by symbol: `structuredAppend` gives the place of
+  each, and joining their contents is left to the application.
+- The pixels are gray, RGB or RGBA; BGR and BGRA (some camera APIs) are converted by the application. A GIF is read
+  from its first frame.
+- The output is PNG, SVG or pixels: EPS, EMF and PDF are not offered.
+
+## 9. Exceptions
+
+All of them extend `BarcodeException`, which extends the `Exception` of lakutata.
+
+| Exception | `errno` | When |
+|---|---|---|
+| `BarcodeContentException` | `E_BARCODE_CONTENT` | A content the format cannot encode, with the reason given by zint |
+| `BarcodeOptionException` | `E_BARCODE_OPTION` | An option of the symbol the format does not take (`errorCorrection` for Code 128), or a value out of its range (`version: 41`) |
+| `BarcodeImageException` | `E_BARCODE_IMAGE` | An image that cannot be decoded or has more than 50 million pixels; pixels that are not `width × height × channels` bytes |
+| `BarcodeTimeoutException` | `E_BARCODE_TIMEOUT` | An operation past its time limit |
+| `BarcodeCancelledException` | `E_BARCODE_CANCELLED` | An operation whose signal aborted, or a call to a destroyed component |
+| `BarcodeException` | `E_BARCODE` | An internal error of the addon |

package/doc/en/Command.md

@@ -41,6 +41,7 @@ lakutata create --name tool --template cli --package-manager none --no-git
 |---|---|---|
 | `--name` | asked in a terminal | The name of the application, and of its directory |
 | `--id` | the name in lower case | The ID of the application and the name of its package |
+| `--bundle-id` | `com.example.<name>` | The id of the application on the mobile systems (reverse domain name), for the mobile templates; the stores refuse `com.example` |
 | `--template` | `default` | An official template (`lakutata templates`), `npm:<package>[@<version>]`, `github:<owner>/<repo>[#<ref>]`, or a directory |
 | `--path` | `.` | Where the project directory is created (`<path>/<name>`) |
 | `--init` | | Create the project in `--path` itself, a directory that already exists |
@@ -103,6 +104,13 @@ An NW.js application gets its version of NW.js from `lakutata nwjs use <version>
 application in the sdk flavor of that NW.js (with the DevTools), its native addons made to load in it, and gives it the
 arguments. Its installers hold the normal flavor ([Installers](Installers.md), section 9).
 
+A mobile application of React Native laid out as the `mobile-react` template runs in a libnode that its native module
+embeds. `lakutata mobile node <android|ios|harmony>` downloads the libnode of a system from the releases of
+lakutata/libnode; `lakutata mobile stage <platform>` makes the Node.js project of the application where the native
+project of the system takes it; `lakutata mobile run <platform>` builds the application and runs it on an emulator, a
+device or a simulator; `lakutata mobile deploy <platform>` puts the Node.js project into the application installed there
+and starts the application again.
+
 ## 6. Environment variables
 
 | Variable | Meaning |
@@ -110,9 +118,11 @@ arguments. Its installers hold the normal flavor ([Installers](Installers.md), s
 | `LAKUTATA_LANG` | The language of the tool (`en`, `zh-CN`, `zh-TW`) |
 | `LAKUTATA_NPM_REGISTRY` | The registry the templates come from (else `npm_config_registry`, else `https://registry.npmjs.org`) |
 | `LAKUTATA_GITHUB_DOWNLOAD` | Where the `github:` templates are downloaded from (`https://github.com` by default) |
-| `LAKUTATA_CACHE_DIR` | The cache of the tool: the templates, the tools that make installers and the runtimes of NW.js (`$XDG_CACHE_HOME/lakutata`, else `~/.cache/lakutata`) |
+| `LAKUTATA_CACHE_DIR` | The cache of the tool: the templates, the tools that make installers, the runtimes of NW.js, and the libnode of the mobile applications with their native addons (`$XDG_CACHE_HOME/lakutata`, else `~/.cache/lakutata`) |
 | `LAKUTATA_NWJS_MIRROR` | Where the runtimes of NW.js are downloaded from (`https://dl.nwjs.io` by default) |
 | `LAKUTATA_NWJS_VERSIONS` | The list of the releases of NW.js (`https://nwjs.io/versions.json` by default) |
+| `LAKUTATA_LIBNODE_MIRROR` | A mirror of the releases of lakutata/libnode, which the libnode of the mobile applications is downloaded from (`<mirror>/v<version>/libnode_<platform>_<arch>.tar.gz`) |
+| `LAKUTATA_MOBILE_NODE_DIR` | A libnode of your own for the mobile applications, built with the repository of lakutata/libnode (a directory per system: `android`, `ios`, `harmony`), used instead of the releases |
 | `NO_COLOR` | Turns the colors off |
 
 The scripts and the applications the tool runs get the environment the tool was started with. The variables of the

package/doc/en/Database.md

@@ -103,6 +103,10 @@ The options are the ones of TypeORM, given to it as they are. The options of eac
 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).
 
+**Paths with aliases.** A path given with an alias of the application (`@data/app.sqlite`, `@app/migrations/*.js`) is
+resolved when the database connects: the file of the database (`database`, the `location` of sql.js) and the globs of
+the entities, the migrations and the subscribers. The aliases are declared by `.alias()` ([Application](Application.md), section 2).
+
 **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.

package/doc/en/DatabaseDrivers.md

@@ -23,8 +23,9 @@ 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.
+has drivers for the JavaScript of the mobile platforms (`capacitor`, `cordova`, `expo`, `nativescript`, `react-native`);
+lakutata does not use them. A mobile application of the `mobile-react` template runs the lakutata application in a
+Node.js instead, with the drivers of this page (see [The mobile applications](#the-mobile-applications)).
 
 ## What applies to every driver
 
@@ -139,6 +140,11 @@ export const db = buildDatabaseOptions({
   its Electron (`electron-rebuild`, or the prebuilt binaries of better-sqlite3 for Electron); an NW.js application has
   it built again with the headers of NW.js (0.111.3 or later: use `sqljs` with the earlier releases); Bun cannot load it
   (use `sqljs` there).
+- Built from its sources against the headers of Node.js 24.19 or later, it aborts the process when the garbage collector
+  frees one of its objects (`Assertion failed: (env) != nullptr`, in `RemoveEnvironmentCleanupHook`:
+  [nodejs/node#65446](https://github.com/nodejs/node/issues/65446)), as every addon built on `node::ObjectWrap` does.
+  Its prebuilt binaries are built against earlier headers; `lakutata mobile stage` builds the addons for the mobile
+  systems without the cleanup hooks of `node::ObjectWrap` that cause it.
 
 ## SQLite: sql.js
 
@@ -165,6 +171,7 @@ export const db = buildDatabaseOptions({
 | `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) |
+| `driver` | | A build of sql.js to use instead of the package's: its asm.js build (`sql.js/dist/sql-asm.js`) needs no WebAssembly |
 
 - 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.
@@ -286,3 +293,66 @@ These drivers come from TypeORM as they are:
   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.
+
+## The mobile applications
+
+A mobile application of the `mobile-react` template runs its lakutata application in the Node.js it embeds (Node.js
+24.20), where the drivers of this page work as on a computer. The table gives what was verified on the emulators of
+Android (API 36), iOS (27.2) and HarmonyOS: a database written, closed, then opened again.
+
+| Driver | Android | iOS | HarmonyOS |
+|---|---|---|---|
+| `better-sqlite3` | Yes | Yes | Yes |
+| `sqljs`, its asm.js build | Yes | Yes | Yes |
+| `sqljs`, its WebAssembly | Yes | Yes, much slower (the polyfill: 1.5 s where the asm.js build took 0.09 s) | No: `ReferenceError: WebAssembly is not defined` |
+| `mongo-embedded` | Yes | Yes | Yes |
+| `postgres`, `mysql`, `mongodb` (a server on the network) | Yes | Yes | Yes |
+
+SQL Server and Oracle have not been checked there.
+
+- `lakutata mobile stage` builds `better-sqlite3` from its sources for each system, with the NDK, Xcode or DevEco Studio
+  (see the `lakutata mobile` commands in the README of `@lakutata/cli`).
+- The file of a database has to last, and `os.tmpdir()` is the cache of the application, which the system may empty. The
+  `App.ts` of the template declares the data directory of the application as the alias `@data`: the `files` directory of
+  the application on Android, `Library/Application Support` on iOS, `/data/storage/el2/base/files` on HarmonyOS, and
+  `packages/app/data` on the computer of the development. The options of the database name a file there as
+  `@data/app.sqlite`: the alias is resolved when the database connects.
+- The asm.js build of sql.js is SQLite compiled to JavaScript: no WebAssembly and no other file, so it runs the same on
+  the three systems. The Node.js of HarmonyOS has no WebAssembly, and the one of iOS has only the polyfill of
+  nodejs-mobile, which is much slower:
+
+```typescript
+import type {ApplicationOptions} from 'lakutata'
+import {buildDatabaseOptions} from 'lakutata/com/database'
+import {createRequire} from 'node:module'
+
+/**
+ * The options of the application
+ */
+export function config(): ApplicationOptions {
+    return {
+        id: 'app',
+        name: 'app',
+        components: {
+            db: buildDatabaseOptions({
+                type: 'sqljs',
+                location: '@data/app.sqlite',
+                autoSave: true,
+                //The asm.js build of sql.js, instead of its WebAssembly
+                driver: createRequire(import.meta.url)('sql.js/dist/sql-asm.js'),
+                entities: []
+            })
+        }
+    }
+}
+```
+
+- sql.js 1.15 marks its asm.js build as deprecated: the build prints a warning each time it is loaded, and the authors
+  ask the users who cannot leave it to say so ([sql-js/sql.js#635](https://github.com/sql-js/sql.js/issues/635)). The
+  build they recommend instead, `sql-wasm-inline.js`, needs WebAssembly, which the Node.js of HarmonyOS does not have.
+  For a database that the application keeps, `better-sqlite3`, which works on the three systems, is the better choice.
+- The WebAssembly of sql.js is read from `sql-wasm.wasm`, next to its module, which the bundle of the application does
+  not keep: declare the file as a resource in `lakutata.resources` (its `from` is where npm installed `sql.js` in the
+  workspace), and give its path among the resources to `sqlJsConfig.locateFile` ([Packaging](Packaging.md), section 6).
+- A database server is reached over the network of the device; from an emulator, the computer is reached through
+  `adb reverse` (Android) or `hdc rport` (HarmonyOS).