libmodulor 0.1.0 → 0.2.0

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

@@ -0,0 +1,49 @@
+# 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

@@ -0,0 +1,205 @@
+# 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

@@ -0,0 +1,114 @@
+# 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

@@ -0,0 +1,46 @@
+# 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).

package/docs/getting-started/006_Create_the_server_Target.md

@@ -0,0 +1,130 @@
+# Create the server Target
+
+We'll use the pre-built [express](https://expressjs.com) `ServerManager`.
+
+```sh
+mkdir src/products/SuperTrader/server
+touch src/products/SuperTrader/server/{container.ts,index.ts}
+touch tsconfig.build.json
+touch .env
+```
+
+## container.ts
+
+```typescript
+import {
+    CONTAINER_OPTS,
+    EnvSettingsManager,
+    type ServerManager,
+    type ServerManagerSettings,
+    type SettingsManager,
+    TARGET_DEFAULT_SERVER_MANAGER_SETTINGS,
+    bindCommon,
+    bindProduct,
+} from 'libmodulor';
+import {
+    NodeExpressServerManager,
+    bindNodeCore,
+    bindServer,
+} from 'libmodulor/node';
+import { Container } from 'inversify';
+
+import { I18n } from '../i18n.js';
+import { Manifest } from '../manifest.js';
+
+type S = ServerManagerSettings;
+
+const container = new Container(CONTAINER_OPTS);
+
+bindCommon<S>(container, () => ({
+    ...TARGET_DEFAULT_SERVER_MANAGER_SETTINGS,
+}));
+bindNodeCore(container);
+bindServer(container);
+bindProduct(container, Manifest, I18n);
+
+container.rebind<SettingsManager>('SettingsManager').to(EnvSettingsManager);
+
+container.bind<ServerManager>('ServerManager').to(NodeExpressServerManager);
+
+export default container;
+```
+
+## index.ts
+
+```typescript
+import {
+    APPS_ROOT_DIR_NAME,
+    type FSManager,
+    type I18nManager,
+    ServerBooter,
+} from 'libmodulor';
+
+import container from './container.js';
+
+await container.get<I18nManager>('I18nManager').init();
+
+await container.resolve(ServerBooter).exec({
+    appsRootPath: container
+        .get<FSManager>('FSManager')
+        .path('..', '..', '..', APPS_ROOT_DIR_NAME),
+    srcImporter: (path) => import(path),
+});
+```
+
+## tsconfig.build.json
+
+```json
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "noEmit": false,
+        "outDir": "dist"
+    },
+    "include": ["src"]
+}
+```
+
+## .env
+
+```properties
+app_logger_level=trace # the default is 'debug'
+```
+
+> [!TIP]
+> A setting named `my_setting` in the code can be overriden with an environment variable called `app_my_setting`.
+
+## Build & Run
+
+Update `package.json` to add new entries to the `scripts`.
+
+```json
+"build": "tsc --project tsconfig.build.json && cp .env dist/products/SuperTrader/server/.env",
+"run:server": "cd dist/products/SuperTrader/server && node --env-file .env index.js",
+```
+
+```sh
+yarn build && yarn run:server
+```
+
+Et voilà ! The server is running !
+
+```sh
+curl -X POST -H "Content-Type: application/json" http://localhost:7443/api/v1/Trading_BuyAsset
+# ❌ {"message":"Invalid credentials"}
+curl -X POST -H "Content-Type: application/json" -H "X-API-Key: PublicApiKeyToBeChangedWhenDeploying" http://localhost:7443/api/v1/Trading_BuyAsset
+# ❌ {"message":"isin must be filled"}
+curl -X POST -H "Content-Type: application/json" -H "X-API-Key: PublicApiKeyToBeChangedWhenDeploying" -d '{"isin":"US02079K3059","limit":123.5,"qty":150}' http://localhost:7443/api/v1/Trading_BuyAsset
+# ✅ {"parts":{"_0":{"items":[{"executedDirectly":false,"id":"95dddca5-5e9d-48ac-a90c-71a58d4e8554"}],"total":1}}}
+```
+
+As you can see, validation comes out of the box. Later we'll see how to add even more precise rules to the data types.
+
+> [!NOTE]
+> The `public_api_key` is just a first layer of security to "authenticate" the client apps calling the server. Hopefully this is not the only security mechanism because of course, this key must be present in clear client side (web, cli, curl...). We'll dive deeper in security when we study the policies.
+
+```sh
+yarn lint && git add . && git commit -m "feat: add the server target"
+```
+
+Now that's done, let's [Create the web Target](./007_Create_the_web_Target.md).