libmodulor 0.3.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "libmodulor",
     "description": "An opinionated TypeScript library to create business oriented applications",
-    "version": "0.3.0",
+    "version": "0.5.0",
     "license": "LGPL-3.0",
     "author": "Chafik H'nini <chafik.hnini@gmail.com>",
     "homepage": "https://github.com/c100k/libmodulor#readme",
@@ -31,6 +31,9 @@
         "./node": {
             "import": "./dist/esm/index.node.js"
         },
+        "./react-native-pure": {
+            "import": "./dist/esm/index.react-native-pure.js"
+        },
         "./react-web-pure": {
             "import": "./dist/esm/index.react-web-pure.js"
         },
@@ -54,26 +57,27 @@
         }
     },
     "peerDependencies": {
-        "@hono/node-server": "^1.13.7",
-        "@modelcontextprotocol/sdk": "^1.1.1",
-        "@stricli/core": "^1.1.0",
+        "@hono/node-server": "^1.13.8",
+        "@modelcontextprotocol/sdk": "^1.5.0",
+        "@stricli/core": "^1.1.1",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
         "express": "^4.21.2",
         "express-fileupload": "^1.5.1",
         "fast-check": "^3.23.2",
         "helmet": "^8.0.0",
-        "hono": "^4.6.16",
-        "inversify": "^6.2.1",
-        "jose": "^5.9.6",
+        "hono": "^4.7.2",
+        "inversify": "^6.2.2",
+        "jose": "^6.0.6",
         "knex": "^3.1.0",
-        "pg": "^8.13.1",
+        "pg": "^8.13.3",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
+        "react-native": "^0.78.0",
         "reflect-metadata": "^0.2.2",
         "sqlite3": "^5.1.7",
         "typescript": "^5.7.3",
-        "vite": "^6.0.7"
+        "vite": "^6.1.1"
     },
     "peerDependenciesMeta": {
         "@hono/node-server": {
@@ -103,6 +107,9 @@
         "react-dom": {
             "optional": true
         },
+        "react-native": {
+            "optional": true
+        },
         "sqlite3": {
             "optional": true
         },

package/docs/getting-started/001_Create_the_project.md

@@ -1,168 +0,0 @@
-# Create the project
-
-Assuming you have the following installed (otherwise, install them or adapt the commands) :
-
-- `node` >= 22
-- `yarn` >= 1.x
-- `wget` and `curl`
-
-If you're on macOS, for the `sed` commands, add a `''` after `-i` ([Explanation](https://stackoverflow.com/a/4247319/1259118)).
-
-```sh
-# Create the directory
-mkdir libmodulor-tuto && cd libmodulor-tuto # Note how the repository is generic to contain multiple apps and products
-
-# Initialize git
-git init
-
-# Initialize config files
-touch .gitignore biome.json package.json README.md tsconfig.json vitest.config.ts
-```
-
-## .gitignore
-
-```.gitignore
-coverage
-dist
-node_modules
-src/apps/**/test/reports
-.env
-```
-
-## biome.json
-
-```json
-{
-    "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
-    "files": {
-        "ignore": ["coverage", "dist", "node_modules"],
-        "ignoreUnknown": true
-    },
-    "formatter": {
-        "indentStyle": "space",
-        "indentWidth": 4
-    },
-    "javascript": {
-        "formatter": {
-            "quoteStyle": "single"
-        },
-        "parser": {
-            "unsafeParameterDecoratorsEnabled": true
-        }
-    }
-}
-```
-
-## package.json
-
-```json
-{
-    "name": "libmodulor-tuto",
-    "version": "0.1.0",
-    "author": "Chafik H'nini <chafik.hnini@gmail.com>",
-    "type": "module",
-    "private": true,
-    "scripts": {
-        "helper": "node ./node_modules/libmodulor/dist/esm/products/Helper/index.js",
-        "lint": "biome check --write .",
-        "test": "tsc && vitest run"
-    },
-    "dependencies": {
-        "inversify": "^6.2.1",
-        "libmodulor": "^0.3.0",
-        "reflect-metadata": "^0.2.2"
-    },
-    "devDependencies": {
-        "@biomejs/biome": "^1.9.4",
-        "@types/node": "^22.10.7",
-        "@vitest/coverage-v8": "^3.0.2",
-        "buffer": "^6.0.3",
-        "cookie-parser": "^1.4.7",
-        "express": "^4.21.2",
-        "express-fileupload": "^1.5.1",
-        "fast-check": "^3.23.2",
-        "helmet": "^8.0.0",
-        "jose": "^5.9.6",
-        "typescript": "^5.7.3",
-        "vite": "^6.0.11",
-        "vitest": "^3.0.3"
-    }
-}
-```
-
-## README.md
-
-```md
-# libmodulor-tuto
-
-🚀🚀🚀
-```
-
-## tsconfig.json
-
-```json
-{
-    "compilerOptions": {
-        "allowSyntheticDefaultImports": true,
-        "declaration": true,
-        "lib": ["dom", "esnext"],
-        "module": "NodeNext",
-        "moduleResolution": "NodeNext",
-        "noEmit": true,
-        "removeComments": true,
-        "skipLibCheck": true,
-        "sourceMap": true,
-        "target": "ESNext",
-
-        "strict": true,
-        "allowUnreachableCode": false,
-        "allowUnusedLabels": false,
-        "exactOptionalPropertyTypes": true,
-        "noFallthroughCasesInSwitch": true,
-        "noPropertyAccessFromIndexSignature": true,
-        "noImplicitOverride": true,
-        "noImplicitReturns": true,
-        "noUncheckedIndexedAccess": true,
-        "noUnusedLocals": true,
-        "noUnusedParameters": true,
-        "verbatimModuleSyntax": true,
-
-        "emitDecoratorMetadata": true,
-        "experimentalDecorators": true,
-
-        "jsx": "react"
-    }
-}
-```
-
-## vitest.config.ts
-
-```typescript
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-    test: {
-        coverage: {
-            enabled: true,
-            exclude: ['src/apps/**/test', 'src/**/*.test.ts'],
-            include: ['src'],
-            reporter: ['html', 'lcov', 'text'],
-        },
-        reporters: ['verbose'],
-    },
-});
-```
-
-## Install
-
-```sh
-yarn install
-```
-
-```sh
-yarn lint && git add . && git commit -m "chore: init source code"
-```
-
-Optionally, you can create a remote repository (e.g. on GitHub) and push it.
-
-Now that's done, let's [Create the App](./002_Create_the_App.md).

package/docs/getting-started/002_Create_the_App.md

@@ -1,49 +0,0 @@
-# Create the App
-
-An app is composed of three main files : `i18n.ts`, `manifest.ts` and `index.ts`.
-
-```sh
-mkdir -p src/apps/Trading/src/ucds
-touch src/apps/Trading/src/{i18n.ts,manifest.ts}
-touch src/apps/Trading/index.ts
-```
-
-> [!NOTE]
-> There is a lot of controversy about barrel files. In this specific context, they are useful to only expose the necessary things to the upper layers and keep the app isolated.
-
-## i18n.ts
-
-```typescript
-import type { AppI18n } from 'libmodulor';
-
-export const I18n: AppI18n = {
-    en: {},
-};
-```
-
-## manifest.ts
-
-```typescript
-import type { AppManifest } from 'libmodulor';
-
-export const Manifest = {
-    languageCodes: ['en'],
-    name: 'Trading',
-    ucReg: {},
-} satisfies AppManifest;
-```
-
-## index.ts
-
-```typescript
-// Expose only what's necessary
-
-export { I18n } from './src/i18n.js';
-export { Manifest } from './src/manifest.js';
-```
-
-```sh
-yarn lint && git add . && git commit -m "feat: add the app"
-```
-
-Now that's done, let's [Create the UseCase](./003_Create_the_UseCase.md).

package/docs/getting-started/003_Create_the_UseCase.md

@@ -1,205 +0,0 @@
-# Create the UseCase
-
-> [!NOTE]
-> Starting now, you'll see `UC` or `uc` a lot. It's the abbreviation of `UseCase`. Acronyms are not good in codebases, except those that are commonly used ([debate](https://stackoverflow.com/questions/2236807/java-naming-convention-with-acronyms)). In any case, when you write `UseCase` hundreds of times, you're happy to be able to write `UC` instead. Thus, `UCD` stands for `Use Case Definition`, `UCIF` stands for `Use Case Input Field` and so on.
-
-The app manifest registers all the use cases metadata. Use cases can depend on each other as we'll see later, and this dependency must go through the manifest. Never directly.
-
-Update `manifest.ts` to register the new use case.
-
-```typescript
-    // ...
-    ucReg: {
-        BuyAsset: {
-            action: 'Create',
-            icon: 'plus',
-            name: 'BuyAsset',
-        },
-    },
-    // ...
-```
-
-If you're using an IDE with auto-complete, you might have noticed the other properties like `beta`, `new`, `sensitive`. We'll come back to them later.
-
-```sh
-mkdir src/apps/Trading/src/dt
-touch src/apps/Trading/src/dt/TISIN.ts
-touch src/apps/Trading/src/ucds/{BuyAssetServerMain.ts,BuyAssetUCD.ts}
-```
-
-## TISIN.ts
-
-An asset is usually identified by a unique code called [ISIN](https://www.isin.org). This is a typical business data type that has specific rules and that is not simply a `string`.
-
-```typescript
-import { type TName, TString, type TStringConstraints } from 'libmodulor';
-
-export type ISIN = Capitalize<string>;
-
-export class TISIN extends TString<ISIN, 'ISIN'> {
-    public static readonly FORMAT: RegExp = /^[A-Z]{2}[A-Z0-9]{9}[0-9]$/;
-
-    constructor(constraints?: TStringConstraints) {
-        super({
-            ...constraints,
-            format: { f: 'ISIN', regexp: TISIN.FORMAT },
-        });
-    }
-
-    public override tName(): TName {
-        return 'ISIN';
-    }
-
-    public override example(): ISIN {
-        return 'US02079K3059';
-    }
-}
-```
-
-## BuyAssetUCD.ts
-
-```typescript
-import {
-    type AggregateOPI0,
-    type Amount,
-    EverybodyUCPolicy,
-    TAmount,
-    TBoolean,
-    TUIntQuantity,
-    type UCDef,
-    type UCInput,
-    type UCInputFieldValue,
-    type UCMain,
-    type UCMainInput,
-    type UCOutputOrNothing,
-    type UCTransporter,
-    type UIntQuantity,
-} from 'libmodulor';
-import { inject, injectable } from 'inversify';
-
-import { Manifest } from '../manifest.js';
-
-import { type ISIN, TISIN } from '../dt/TISIN.js';
-import { BuyAssetServerMain } from './BuyAssetServerMain.js';
-
-export interface BuyAssetInput extends UCInput {
-    isin: UCInputFieldValue<ISIN>;
-    limit: UCInputFieldValue<Amount>;
-    qty: UCInputFieldValue<UIntQuantity>;
-}
-
-export interface BuyAssetOPI0 extends AggregateOPI0 {
-    executedDirectly: boolean;
-}
-
-@injectable()
-class BuyAssetClientMain implements UCMain<BuyAssetInput, BuyAssetOPI0> {
-    constructor(
-        @inject('UCTransporter')
-        private ucTransporter: UCTransporter,
-    ) {}
-
-    public async exec({
-        uc,
-    }: UCMainInput<BuyAssetInput, BuyAssetOPI0>): Promise<
-        UCOutputOrNothing<BuyAssetOPI0>
-    > {
-        return this.ucTransporter.send(uc);
-    }
-}
-
-export const BuyAssetUCD: UCDef<BuyAssetInput, BuyAssetOPI0> = {
-    io: {
-        i: {
-            fields: {
-                isin: {
-                    type: new TISIN(),
-                },
-                limit: {
-                    type: new TAmount('USD'),
-                },
-                qty: {
-                    type: new TUIntQuantity(),
-                },
-            },
-        },
-        o: {
-            parts: {
-                _0: {
-                    fields: {
-                        executedDirectly: {
-                            type: new TBoolean(),
-                        },
-                    },
-                },
-            },
-        },
-    },
-    lifecycle: {
-        client: {
-            main: BuyAssetClientMain,
-            policy: EverybodyUCPolicy,
-        },
-        server: {
-            main: BuyAssetServerMain,
-            policy: EverybodyUCPolicy,
-        },
-    },
-    metadata: Manifest.ucReg.BuyAsset,
-};
-```
-
-## BuyAssetServerMain.ts
-
-```typescript
-import {
-    type UCMain,
-    type UCMainInput,
-    type UCManager,
-    type UCOutput,
-    UCOutputBuilder,
-} from 'libmodulor';
-import { inject, injectable } from 'inversify';
-
-import type { BuyAssetInput, BuyAssetOPI0 } from './BuyAssetUCD.js';
-
-@injectable()
-export class BuyAssetServerMain implements UCMain<BuyAssetInput, BuyAssetOPI0> {
-    constructor(@inject('UCManager') private ucManager: UCManager) {}
-
-    public async exec({
-        uc,
-    }: UCMainInput<BuyAssetInput, BuyAssetOPI0>): Promise<
-        UCOutput<BuyAssetOPI0>
-    > {
-        // >=> Persist the order
-        const { aggregateId } = await this.ucManager.persist(uc);
-
-        // >=> TODO : Check the user has enough funds to place the order
-
-        // >=> TODO : Send the order to a queue for processing
-        const executedDirectly: BuyAssetOPI0['executedDirectly'] = false;
-
-        return new UCOutputBuilder<BuyAssetOPI0>()
-            .add({
-                executedDirectly,
-                id: aggregateId,
-            })
-            .get();
-    }
-}
-```
-
-For now, we won't detail all this code but take the time to read it and understand how it works. Hopefully it's clear enough and self-explanatory.
-
-> [!TIP]
-> Using a comment following the pattern `// >=> ` in `ClientMain` and `ServerMain` has a specific meaning as we'll see a little bit later.
-
-> [!NOTE]
-> Unlike `ClientMain`, `ServerMain` is put in another file for "historical" reasons, mainly for stripping and tree shaking reasons. More on this later.
-
-```sh
-yarn lint && git add . && git commit -m "feat: add the use case"
-```
-
-Now that's done, let's [Test the App](./004_Test_the_App.md).

package/docs/getting-started/004_Test_the_App.md

@@ -1,114 +0,0 @@
-# Test the App
-
-## Preliminary test
-
-By default, we rely on [vitest](https://vitest.dev) to run the tests and [@vitest/coverage-v8](https://vitest.dev/guide/coverage) for the coverage.
-
-```sh
-yarn test
-```
-
-```sh
- % Coverage report from v8
-------------------------|---------|----------|---------|---------|-------------------
-File                    | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
-------------------------|---------|----------|---------|---------|-------------------
-All files               |       0 |       40 |      40 |       0 |                   
- Trading                |       0 |        0 |       0 |       0 |                   
-  index.ts              |       0 |        0 |       0 |       0 | 1                 
- Trading/src            |       0 |      100 |     100 |       0 |                   
-  i18n.ts               |       0 |      100 |     100 |       0 | 3-5               
-  manifest.ts           |       0 |      100 |     100 |       0 | 3-14              
- Trading/src/ucds       |       0 |        0 |       0 |       0 |                   
-  BuyAssetServerMain.ts |       0 |        0 |       0 |       0 | 1-28              
-  BuyAssetUCD.ts        |       0 |        0 |       0 |       0 | 1-92              
-------------------------|---------|----------|---------|---------|-------------------
-```
-
-As expected, the coverage report is pretty lame. Which is understandable, since we haven't written any tests yet.
-
-```sh
-mkdir src/apps/Trading/test
-touch src/apps/Trading/test/Configurator.ts
-```
-
-## Configurator.ts
-
-```typescript
-import { type AppTesterCtx, type CryptoManager, bindCommon } from 'libmodulor';
-import {
-    NodeDeterministicCryptoManager,
-    bindNodeCore,
-    bindServer,
-} from 'libmodulor/node';
-import { SimpleAppTesterConfigurator } from 'libmodulor/node-test';
-import { injectable } from 'inversify';
-
-@injectable()
-export class Configurator extends SimpleAppTesterConfigurator {
-    public override async bindImplementations(
-        ctx: AppTesterCtx,
-    ): Promise<void> {
-        await super.bindImplementations(ctx);
-
-        const { container } = ctx;
-
-        bindCommon(container);
-        bindNodeCore(container);
-        bindServer(container);
-
-        container
-            .rebind<CryptoManager>('CryptoManager')
-            .to(NodeDeterministicCryptoManager);
-    }
-}
-```
-
-## Automated test
-
-Generate the automated tests and execute them with the CLI (it does more than a simple `yarn test`).
-
-```sh
-yarn helper GenerateAppsTests
-yarn helper TestApp --appName Trading
-```
-
-```sh
- % Coverage report from v8
-------------------------|---------|----------|---------|---------|-------------------
-File                    | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
-------------------------|---------|----------|---------|---------|-------------------
-All files               |   98.83 |       80 |      80 |   98.83 |                   
- Trading                |       0 |        0 |       0 |       0 |                   
-  index.ts              |       0 |        0 |       0 |       0 | 1                 
- Trading/src            |     100 |      100 |     100 |     100 |                   
-  i18n.ts               |     100 |      100 |     100 |     100 |                   
-  manifest.ts           |     100 |      100 |     100 |     100 |                   
- Trading/src/ucds       |     100 |      100 |     100 |     100 |                   
-  BuyAssetServerMain.ts |     100 |      100 |     100 |     100 |                   
-  BuyAssetUCD.ts        |     100 |      100 |     100 |     100 |                   
-------------------------|---------|----------|---------|---------|-------------------
-2024-12-29T11:00:53.178Z [info] Coverage Report => open src/apps/Trading/test/reports/coverage/index.html
-2024-12-29T11:00:53.178Z [info] Simple HTML Report => open src/apps/Trading/test/reports/simple-html/index.html
-```
-
-That's much better. Without writing any line of test code, we've reached almost 100% coverage. Although coverage is a vanity metric in some way, it still is a valuable one.
-
-Note another important thing : auto documentation. Check out the generated `src/apps/Trading/README.md` that shows a mermaid chart for each use case and a technical summary. This is very valuable to whoever wants to understand what the app does.
-
-To vizualize the mermaid chart, you can copy/paste it [here](https://mermaid.live) or if you've published your repository to GitHub, they are displayed out of the box.
-
-<img src="/docs/assets/trading-buy-asset-sequence-diagram.png" width="600px">
-
-You can see how the special comments we've mentioned earlier show up in this chart. It's nice in order to describe with more details what happens at each step.
-
-Note also the generated "Coverage Report" and the "Simple HTML Report". The former is provided by `c8` while the other is built by `libmodulor`. It gives a great overview of the test scenarios.
-
-> [!NOTE]
-> You might have seen that `Configurator` is extensible. It allows you to define specific flows to test a suite of use cases, define specific assertions, etc.
-
-```sh
-yarn lint && git add . && git commit -m "test: init app tests"
-```
-
-Now that's done, let's [Create the Product](./005_Create_the_Product.md).

package/docs/getting-started/005_Create_the_Product.md

@@ -1,46 +0,0 @@
-# Create the Product
-
-Like the app, the product has a `i18n.ts` and `manifest.ts`.
-
-```sh
-mkdir -p src/products/SuperTrader
-touch src/products/SuperTrader/{i18n.ts,manifest.ts}
-```
-
-## i18n.ts
-
-```typescript
-import type { ProductI18n } from 'libmodulor';
-import { I18nEN } from 'libmodulor/locales/en';
-
-import { I18n as TradingI18n } from '../../apps/Trading/index.js';
-
-export const I18n: ProductI18n = {
-    en: {
-        ...I18nEN,
-        ...TradingI18n.en,
-        p_desc: 'A simple app to trade crypto, shares and other assets',
-        p_slogan: 'Trading made simple',
-    },
-};
-```
-
-## manifest.ts
-
-```typescript
-import type { ProductManifest } from 'libmodulor';
-
-export const Manifest: ProductManifest = {
-    appReg: [{ name: 'Trading' }],
-    name: 'SuperTrader',
-};
-```
-
-> [!NOTE]
-> The same way we register use cases in an app, we register apps in a product. Since apps are reusable across products, you can even exclude some use cases for a given product.
-
-```sh
-yarn lint && git add . && git commit -m "feat: add the product"
-```
-
-Now that's done, let's [Create the server Target](./006_Create_the_server_Target.md).