lakutata 3.1.5 → 3.1.6

package/doc/en/Entrypoint.md

@@ -61,6 +61,7 @@ The adapters:
 | `service` | `jsonRPCServiceEntrypoint()` | `lakutata/adapter/jsonrpc` | `ws`, for WebSocket | [ServiceCalls](ServiceCalls.md) |
 | `service` | `electronIPCServiceEntrypoint()` | `lakutata/adapter/electron` | (Electron) | [ServiceCalls](ServiceCalls.md) |
 | `service` | `nwjsServiceEntrypoint()` | `lakutata/adapter/nwjs` | (NW.js) | [ServiceCalls](ServiceCalls.md) |
+| `service` | `reactNativeServiceEntrypoint()` | `lakutata/adapter/react-native` | | [ServiceCalls](ServiceCalls.md) |
 | `service` | `grpcServiceEntrypoint()` | `@lakutata/grpc/service` | `@lakutata/grpc` | [GRPC](GRPC.md) |
 | `service` | `natsServiceEntrypoint()` | `@lakutata/nats` | `@lakutata/nats` | [NATS](NATS.md) |
 | `schedule` | `scheduleEntrypoint()` | `lakutata/com/entrypoint` | | [Schedules](Schedules.md) |

package/doc/en/GettingStarted.md

@@ -48,6 +48,7 @@ The `default` template is a small HTTP application. Other templates start from a
 | `web-next`, `web-nuxt` | An HTTP API serving a Next.js or Nuxt application from the same process |
 | `electron-react`, `electron-vue` | A desktop application: Electron, its main process serving a React or Vue renderer over IPC |
 | `nwjs-react`, `nwjs-vue` | A desktop application: NW.js, its background script serving a React or Vue user interface isolated in a webview |
+| `mobile-react` | A mobile application for Android, iOS and HarmonyOS: React Native, the Node.js inside it serving the user interface |
 
 ```bash
 npx @lakutata/cli create --name shop --template service --with i18n,installer

package/doc/en/I18n.md

@@ -174,7 +174,7 @@ The languages a request asks for are read from the sources below, in order, then
 | HTTP (Express, Fastify) | The query parameter `?lang=`, the cookie `lang`, then the `Accept-Language` header (by quality) |
 | Socket.IO | The query parameter `lang`, the cookie `lang` and `Accept-Language` of the connection's handshake |
 | HTTP service adapter, JSON-RPC (HTTP, WebSocket) | The query parameter `lang`, the cookie `lang` and `Accept-Language` of the HTTP request (for WebSocket, of the request opening the connection) |
-| Command line, Electron IPC, NW.js, JSON-RPC over stdio | The variable named by `environmentVariable` (none by default), `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`, then the language of the process |
+| Command line, Electron IPC, NW.js, React Native, JSON-RPC over stdio | The variable named by `environmentVariable` (none by default), `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`, then the language of the process |
 | Schedules | None (the default language) |
 
 A query or cookie value that is not a language tag is skipped.

package/doc/en/Migrations.md

@@ -143,8 +143,8 @@ export class Migrations1792161460658 implements MigrationInterface {
   compiled files.
 - Read the migration before running it: a renamed property becomes a column dropped and a column added, with the data
   of the old one lost. Edit the SQL when needed.
-- When nothing changed, the command writes nothing and exits with the code 1 (`No changes in database schema were
-  found`).
+- When nothing changed, the command writes nothing, says so (`No changes in database schema were found`) and exits with
+  the code 0.
 - With several databases, each database whose tables differ gets its own file. Give each database a `migrations` option
   that lists only its own files (`'build/migrations/*-db.js'`), or the databases would run each other's migrations.
 

package/doc/en/NativeAddons.md

@@ -221,5 +221,8 @@ The application depends on the addon package, and imports it as any package (`im
   (NW.js 0.111.3 or later: the earlier releases, such as 0.72 for Windows 7, run the addons of Node-API only). On
   Windows, the addons load the Node.js of NW.js (`node.dll`). The addons of the project are left as they are, for its
   tests with Node.js.
+- **Mobile applications** (React Native): `lakutata mobile stage` builds the addons from their sources for Android, iOS
+  and HarmonyOS, against the libnode the application embeds (see the `lakutata mobile` commands in the README of
+  `@lakutata/cli`).
 - **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/Overview.md

@@ -4,7 +4,8 @@
 (Electron, NW.js) applications and embedded devices one programming model: 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.
+NATS, Electron IPC, NW.js, React Native), schedules and message queues. One controller method can serve all of them at
+once.
 
 The package `lakutata` re-exports the `@lakutata/*` packages under its subpaths (see the table below) and presets two
 components in every application: `log` (the `Logger`, which writes pino-compatible JSON lines) and `entrypoint` (the
@@ -30,7 +31,7 @@ tool, a web and a desktop application, calls between services, background jobs,
 | `lakutata/decorator/ctrl` | `@HTTPAction`, `@GET`…`@OPTIONS`, `@CLIAction`, `@ServiceAction`, `@Schedule`, `@Prefix`, `@UseMiddlewares` |
 | `lakutata/adapter/express`, `lakutata/adapter/fastify` | The HTTP transports |
 | `lakutata/adapter/commander` | The CLI transport |
-| `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron`, `lakutata/adapter/nwjs` | The service transports |
+| `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron`, `lakutata/adapter/nwjs`, `lakutata/adapter/react-native` | The service transports |
 | `lakutata/com/logger` | The `Logger` component, preset as `log` (pino-compatible JSON lines) |
 | `lakutata/orm`, `lakutata/decorator/orm` | TypeORM and its decorators |
 | `lakutata/com/database`, `lakutata/provider/database` | The `Database` component and provider |
@@ -46,11 +47,12 @@ tool, a web and a desktop application, calls between services, background jobs,
 
 Not part of this package: `@lakutata/cli` (the `lakutata` command for creating projects, running migrations and packing
 applications, see [Command](Command.md)), `@lakutata/grpc` (a gRPC client, server and service transport),
-`@lakutata/nats` (a NATS component and service transport), `@lakutata/dbus` (D-Bus), `@lakutata/mcp` (the Model
-Context Protocol), `@lakutata/webrtc` (WebRTC: the signaling, a TURN server, a media server, peer connections),
-`@lakutata/ffi` (the C functions of native libraries), `@lakutata/math` (symbolic and numeric mathematics, as functions
-that need no lakutata application) and `@lakutata/netif` (servers and UDP sockets listening on a network interface
-whatever its addresses, the interfaces of the machine and their changes).
+`@lakutata/nats` (a NATS component and service transport), `@lakutata/dbus` (D-Bus), `@lakutata/mcp` (the Model Context
+Protocol), `@lakutata/webrtc` (WebRTC: the signaling, a TURN server, a media server, peer connections), `@lakutata/ffi`
+(the C functions of native libraries), `@lakutata/math` (symbolic and numeric mathematics, as functions that need no
+lakutata application), `@lakutata/barcode` (barcodes and QR codes, generated and read in a native addon) and
+`@lakutata/netif` (servers and UDP sockets listening on a network interface whatever its addresses, the interfaces of
+the machine and their changes).
 
 ## The guides
 
@@ -95,6 +97,7 @@ whatever its addresses, the interfaces of the machine and their changes).
 | [MCP](MCP.md) | The tools, resources and prompts of the Model Context Protocol (`@lakutata/mcp`), over stdio and HTTP |
 | [WebRTC](WebRTC.md) | Peer-to-peer connections and a media server (`@lakutata/webrtc`): the signaling, the TURN server, browsers and applications, the actions of an application called through data channels, WHIP and WHEP |
 | [FFI](FFI.md) | The C functions of native libraries (`@lakutata/ffi`): declarations copied from headers, structs, callbacks, memory, packaging |
+| [Barcode](Barcode.md) | Barcodes and QR codes (`@lakutata/barcode`): generating them as PNG, SVG or pixels, sizes for print, EAN, UPC and GS1, reading them from images |
 | [Math](Math.md) | Mathematics (`@lakutata/math`): formulas and exact results, equations, decimals of any precision, matrices, statistics, numeric solutions, units |
 | [Netif](Netif.md) | Network interfaces (`@lakutata/netif`): a server listening on an interface whatever its addresses, the connections of the other interfaces refused, the interfaces and their changes, UDP on one interface |
 | [Command](Command.md) | The `lakutata` command: creating projects, migrations, translations, environment variables |

package/doc/en/Packaging.md

@@ -10,6 +10,10 @@ A compiled application can be shipped without its `node_modules`, in three forms
 `lakutata package bundle`, `package exe` and `package installer` make them with `@lakutata/builder`, which the project
 installs (`npm install --save-dev @lakutata/builder`; the templates that pack their application already have it).
 
+A mobile application of the `mobile-react` template is shipped another way: `lakutata mobile stage` bundles its
+application for the Node.js the mobile application embeds, and its native projects make the release builds for the
+stores (see the section The packaging of the README the template gives the project).
+
 ## 1. What is packed
 
 - **The compiled application**: the output of `tsc` (which emits the metadata of the decorators), not the TypeScript

package/doc/en/ProjectStructure.md

@@ -97,6 +97,16 @@ The other templates add to this layout:
   `packages/app/host` holds the user interface in a webview, and its service actions), the user interface in
   `packages/ui`, the version of NW.js in `packages/app/nwjs.json` (written by `npm run nwjs:use -- <version>`), and the
   scripts that make the installers.
+- `mobile-react`: the application in `packages/app`, which runs in a Node.js embedded in the mobile application and
+  serves its actions to the user interface of React Native; the user interface in `packages/ui` (`src/App.tsx`), the
+  same on the three systems; `packages/ipc`, which connects the user interface to the Node.js side: the native module
+  embedding Node.js (`native`) and the `ipc` the user interface imports (Electron and NW.js have such a channel of their
+  own, React Native has none, so the template brings it as a package); at the root, the application of React Native
+  itself: its entry (`index.js`, which registers the component of `packages/ui`), `app.json`, the configurations of
+  Metro and Babel, and the native projects (`android`, `ios`, `harmony`), which carry the id of the application
+  (`lakutata create --bundle-id`); and the scripts that download the libnode, run the application on an emulator, a
+  device or a simulator, and deploy its Node.js side (`npm run node:android`, `npm run android`, `npm run
+  deploy:android`, and the same for `ios` and `harmony`).
 
 The packed forms are written to `dist/` at the root of the workspace; `.gitignore` leaves out `build`, `dist` and the
 outputs of the interfaces.

package/doc/en/ServiceCalls.md

@@ -2,10 +2,10 @@
 
 A service action (`@ServiceAction`) is called with a message rather than a URL: an object whose keys select the action,
 its **pattern**, and whose other keys are the input. The same actions can be served over several transports at once:
-plain HTTP, Socket.IO, JSON-RPC 2.0 (over HTTP, WebSocket or the standard input and output), the IPC of Electron and the
-windows of NW.js, as this guide describes, and gRPC, NATS and the data channels of WebRTC, which have their own guides. The controllers and
-their actions are described in [Controllers](Controllers.md), the entrypoint and its adapters in
-[Entrypoint](Entrypoint.md).
+plain HTTP, Socket.IO, JSON-RPC 2.0 (over HTTP, WebSocket or the standard input and output), the IPC of Electron, the
+windows of NW.js and the user interface of a mobile application of React Native, as this guide describes, and gRPC, NATS
+and the data channels of WebRTC, which have their own guides. The controllers and their actions are described in
+[Controllers](Controllers.md), the entrypoint and its adapters in [Entrypoint](Entrypoint.md).
 
 ## 1. A first service
 
@@ -136,7 +136,8 @@ class OrderController extends Controller {
 
 ## 3. The response
 
-The HTTP service, Socket.IO, Electron and NW.js answer with an envelope; JSON-RPC answers with its own responses (section 4).
+The HTTP service, Socket.IO, Electron, NW.js and React Native answer with an envelope; JSON-RPC answers with its own
+responses (section 4).
 
 ```text
 {"success": true, "error": null, "payload": <the result>}
@@ -180,6 +181,7 @@ export async function call<T>(message: Record<string, unknown>): Promise<T> {
 | `jsonRPCServiceEntrypoint()` | `lakutata/adapter/jsonrpc` | `ws`, for WebSocket | A JSON-RPC 2.0 request | Notifications (WebSocket, stdio) |
 | `electronIPCServiceEntrypoint()` | `lakutata/adapter/electron` | (Electron) | `ipcRenderer.invoke()` | IPC messages |
 | `nwjsServiceEntrypoint()` | `lakutata/adapter/nwjs` | (NW.js) | A call of its bridge, by the host page of a window | Calls of the function the host page gives |
+| `reactNativeServiceEntrypoint()` | `lakutata/adapter/react-native` | | A line of JSON from the host | Lines of JSON |
 | `grpcServiceEntrypoint()` | `@lakutata/grpc/service` | `@lakutata/grpc` | See [GRPC](GRPC.md) | gRPC streams |
 | `natsServiceEntrypoint()` | `@lakutata/nats` | `@lakutata/nats` | See [NATS](NATS.md) | NATS messages |
 | `webrtcServiceEntrypoint()` | `@lakutata/webrtc` | `@lakutata/webrtc` | A JSON-RPC 2.0 request on a data channel, see [WebRTC](WebRTC.md) | Notifications |
@@ -510,6 +512,38 @@ window.addEventListener('message', async (event) => {
 - The NW.js templates of `lakutata create` contain such a host page (`packages/app/host`), and a `window.ipc` for the
   interface like the one of the Electron templates.
 
+### React Native
+
+`reactNativeServiceEntrypoint()` serves the actions to the user interface of a mobile application of React Native
+(Android, iOS, HarmonyOS), in the Node.js that the application embeds. The native module of the application starts
+Node.js and gives it one end of a socket, whose file descriptor is in the environment variable `LAKUTATA_NODE_FD`. The
+adapter reads the messages of the host on that socket and writes its responses and events there, one JSON object per
+line. The values arrive as JSON carries them: a `Date` arrives as its string, a `Buffer` as `{type, data}`, `undefined`
+is left out, and a result that JSON cannot hold (a `bigint`, a cycle) is answered with an error.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `socket` | a socket on the file descriptor in `LAKUTATA_NODE_FD` | The connection to the host, or a stand-in in the tests |
+| `pause` | | Called when the application goes to the background, before the host is told that the application is ready for it |
+| `resume` | | Called when the application comes back from the background |
+
+| The host writes | The adapter answers |
+|---|---|
+| `{"type":"invoke","id":1,"clientId":"ui","data":{"cmd":"greet","name":"you"}}` | `{"type":"response","id":1,"response":{"success":true,"error":null,"payload":…}}` |
+| `{"type":"subscribe","clientId":"ui"}` | `{"type":"subscribed","clientId":"ui"}`, then the events pushed to the client |
+| `{"type":"unsubscribe","clientId":"ui"}` | Nothing; the requests of the client in progress are aborted |
+| `{"type":"pause"}` | `{"type":"paused"}`, once the `pause` option has run |
+| `{"type":"resume"}` | Nothing; the `resume` option runs |
+
+- The lines that the host writes before the application listens wait in the socket: none is lost. The answer to the
+  subscription tells the interface that the application is ready.
+- On iOS, the host asks the system for time to finish before the application is suspended, sends `pause`, and lets the
+  application be suspended once `paused` comes (or when the time runs out).
+- When Node.js ends (`process.exit()`, an uncaught exception), the mobile application keeps running: the native module
+  reports the exit code and can start Node.js again.
+- The `mobile-react` template of `lakutata create` contains such a native module, and an `ipc` for the interface like
+  the one of the Electron templates, both in its package `packages/ipc`.
+
 ## 5. Clients and events
 
 The transports that keep their clients connected can push events to them. A client is identified by the id it gives:
@@ -523,6 +557,7 @@ The transports that keep their clients connected can push events to them. A clie
 | JSON-RPC over stdio | `'stdio'` |
 | Electron | The id the page gives when it subscribes or invokes |
 | NW.js | The id the host page gives to the bridge for its page |
+| React Native | The id the user interface gives when it subscribes or invokes |
 | WebRTC | The member id of the caller in its room |
 
 An action reads the id of its client in `this.context.clientId`. The `entrypoint` component pushes the events:
@@ -559,6 +594,7 @@ A client receives `notify(clientId, 'progress', 50, 'half')` as:
 | JSON-RPC (WebSocket, stdio) | `{"jsonrpc": "2.0", "method": "progress", "params": [50, "half"]}` |
 | Electron | `('progress', [50, 'half'])`, through the `subscribe` of the preload script above |
 | NW.js | `('progress', [50, 'half'])`, given to the function of the `subscribe` of the bridge |
+| React Native | The line `{"type":"event","clientId":…,"event":"progress","args":[50,"half"]}`, which the host passes to the interface |
 | WebRTC | `proxy.on('progress', (percent, label) => …)` of a `PeerServiceProxy` |
 
 ## 6. Stopping and leaving