libmodulor 0.2.0 → 0.4.0

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).

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

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

package/docs/getting-started/007_Create_the_web_Target.md

@@ -1,262 +0,0 @@
-# Create the web Target
-
-We'll use the pre-built [React](https://react.dev) components to build a SPA (Single Page Application), bundled with [vite](https://vite.dev) and served with the server defined above.
-
-> [!WARNING]
-> For readers used to "beautiful" websites à la Linear, Vercel and related, your eyes will burn. You're going to discover the simple and pure CSS-less Web. The most beautiful one.
-> Of course, feel free to add CSS if you want to. The main goal here is to focus on the essence of the UI and not the UI design.
-
-```sh
-yarn add --dev "@types/react@^18.3.17" "@types/react-dom@^18.3.5"
-yarn add "react@^18.3.1" "react-dom@^18.3.1"
-
-mkdir -p src/products/SuperTrader/web/components
-touch src/products/SuperTrader/vite.config.web.ts
-touch src/products/SuperTrader/web/{container.ts,index.html,index.tsx}
-touch src/products/SuperTrader/web/components/App.tsx
-```
-
-## vite.config.web.ts
-
-```typescript
-import { join } from 'node:path';
-
-import { StripUCDLifecycleServerPlugin } from 'libmodulor/vite';
-import { defineConfig } from 'vite';
-
-const base = process.cwd();
-const root = join('src', 'products', 'SuperTrader', 'web');
-const outDir = join(
-    base,
-    'dist',
-    'products',
-    'SuperTrader',
-    'server',
-    'public',
-);
-
-export default defineConfig({
-    build: {
-        emptyOutDir: true,
-        outDir,
-    },
-    plugins: [StripUCDLifecycleServerPlugin],
-    root,
-});
-```
-
-## container.ts
-
-```typescript
-import {
-    CONTAINER_OPTS,
-    type ServerClientManagerSettings,
-    TARGET_DEFAULT_SERVER_CLIENT_MANAGER_SETTINGS,
-    bindCommon,
-    bindProduct,
-} from 'libmodulor';
-import { bindWeb } from 'libmodulor/web';
-import { Container } from 'inversify';
-
-import { I18n } from '../i18n.js';
-import { Manifest } from '../manifest.js';
-
-type S = ServerClientManagerSettings;
-
-const container = new Container(CONTAINER_OPTS);
-
-bindCommon<S>(container, () => ({
-    ...TARGET_DEFAULT_SERVER_CLIENT_MANAGER_SETTINGS,
-}));
-bindWeb(container);
-bindProduct(container, Manifest, I18n);
-
-export default container;
-```
-
-## index.html
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-    <head>
-        <meta charset="utf-8" />
-        <meta content="width=device-width, initial-scale=1" name="viewport"
-        />
-    </head>
-    <body>
-        <div id="root"></div>
-        <script type="module" src="/index.tsx"></script>
-    </body>
-</html>
-```
-
-## App.tsx
-
-Update `src/apps/Trading/index.ts` to expose the use case.
-
-```typescript
-export { BuyAssetUCD } from './src/ucds/BuyAssetUCD.js';
-```
-
-Naturally, in real life scenarios, we would never have such a bloated `App.tsx` and we could create fine-grained components. Everybody does that, right ?
-
-```tsx
-import { type Logger, type ProductManifest, UCOutputReader } from 'libmodulor';
-import {
-    UCPanel,
-    type UCPanelOnError,
-    useDIContext,
-    useUC,
-    useUCOR,
-} from 'libmodulor/react';
-import {
-    UCAutoExecLoader,
-    UCExecTouchable,
-    UCForm,
-} from 'libmodulor/react-web-pure';
-import React, { useEffect, useState, type ReactElement } from 'react';
-
-import { BuyAssetUCD, Manifest } from '../../../../apps/Trading/index.js';
-
-export default function App(): ReactElement {
-    const { container, i18nManager, wordingManager } = useDIContext();
-    const [logger] = useState(container.get<Logger>('Logger'));
-    const [productManifest] = useState(
-        container.get<ProductManifest>('ProductManifest'),
-    );
-
-    const [buyAssetUC] = useUC(Manifest, BuyAssetUCD, null);
-    const [buyAssetPart0, _buyAssetPart1, { append0 }] = useUCOR(
-        new UCOutputReader(BuyAssetUCD, undefined),
-    );
-
-    const [loading, setLoading] = useState(true);
-
-    useEffect(() => {
-        (async () => {
-            logger.debug('Initializing i18n');
-            await i18nManager.init();
-            logger.debug('Done initializing i18n');
-            setLoading(false);
-        })();
-
-        const { slogan } = wordingManager.p();
-        document.title = `${productManifest.name} : ${slogan}`;
-    }, [i18nManager, logger, productManifest, wordingManager]);
-
-    const onError: UCPanelOnError = async (err) => alert(err.message);
-
-    const { slogan } = wordingManager.p();
-    const { label } = wordingManager.uc(buyAssetUC.def);
-    const { label: idLabel } = wordingManager.ucof('id');
-    const { label: executedDirectlyLabel } =
-        wordingManager.ucof('executedDirectly');
-
-    return (
-        <div>
-            {loading && 'Loading...'}
-
-            {!loading && (
-                <>
-                    <h1>
-                        {productManifest.name} : {slogan}
-                    </h1>
-
-                    <h2>{label}</h2>
-
-                    <UCPanel
-                        clearAfterExec={false}
-                        onDone={async (ucor) => append0(ucor)}
-                        onError={onError}
-                        renderAutoExecLoader={UCAutoExecLoader}
-                        renderExecTouchable={UCExecTouchable}
-                        renderForm={UCForm}
-                        sleepInMs={200} // Fake delay to see submit wording changing
-                        uc={buyAssetUC}
-                    />
-
-                    <table>
-                        <thead>
-                            <tr>
-                                <th>{idLabel}</th>
-                                <th>{executedDirectlyLabel}</th>
-                            </tr>
-                        </thead>
-                        <tbody>
-                            {buyAssetPart0?.items.map((i) => (
-                                <tr key={i.id}>
-                                    <td>{i.id}</td>
-                                    <td>{i.executedDirectly ? '✅' : '❌'}</td>
-                                </tr>
-                            ))}
-                        </tbody>
-                        <tfoot>
-                            <tr>
-                                <th>{i18nManager.t('total')}</th>
-                                <th>{buyAssetPart0?.pagination.total}</th>
-                            </tr>
-                        </tfoot>
-                    </table>
-                </>
-            )}
-        </div>
-    );
-}
-```
-
-## index.tsx
-
-```typescript
-import { DIContextProvider } from 'libmodulor/react';
-import React, { StrictMode } from 'react';
-import ReactDOM from 'react-dom/client';
-
-import App from './components/App.js';
-import container from './container.js';
-
-const rootElt = document.getElementById('root');
-if (!rootElt) {
-    throw new Error('Add a div#root in index.html');
-}
-
-ReactDOM.createRoot(rootElt).render(
-    <StrictMode>
-        <DIContextProvider container={container}>
-            <App />
-        </DIContextProvider>
-    </StrictMode>,
-);
-```
-
-## Build & Run
-
-Update `package.json` to add the `web` build to the `build` command.
-
-```json
-"build": "tsc --project tsconfig.build.json && cp .env dist/products/SuperTrader/server/.env && vite -c src/products/SuperTrader/vite.config.web.ts build",
-```
-
-Update `src/products/SuperTrader/server/container.ts` to mount the `public` directory.
-
-```diff
-...TARGET_DEFAULT_SERVER_MANAGER_SETTINGS,
-+server_static_dir_path: 'public',
-```
-
-Press <kbd>ctrl</kbd> + <kbd>C</kbd> to stop the server (we'll setup hot reload later).
-
-```sh
-yarn build && yarn run:server
-open http://localhost:7443
-```
-
-Et voilà ! The server is running ! Fill the form and see how it automatically submits to the server with client side and server side validation out of the box.
-
-<img src="/docs/assets/trading-target-web.png" width="600px">
-
-```sh
-yarn lint && git add . && git commit -m "feat: add the web target"
-```
-
-Now that's done, let's [Switch to a persistent data storage](./008_Switch_to_a_persistent_data_storage.md).

package/docs/getting-started/008_Switch_to_a_persistent_data_storage.md

@@ -1,52 +0,0 @@
-# Switch to a persistent data storage
-
-By default, the data is stored in memory on the server. Therefore, whenever we restart it, we lose everything. That is not very practical in real life scenarios. Let's use SQLite instead.
-
-```sh
-yarn add "knex@^3.1.0" "sqlite3@^5.1.7"
-```
-
-Update `src/products/SuperTrader/server/container.ts` to change the implementation.
-
-```diff
-[...]
-    TARGET_DEFAULT_SERVER_MANAGER_SETTINGS,
-+    type UCDataStore,
-[...]
-+import { KnexUCDataStore } from 'libmodulor/uc-data-store/knex';
-[...]
-+type S = KnexUCDataStoreSettings & ServerManagerSettings;
-[...]
-    ...TARGET_DEFAULT_SERVER_MANAGER_SETTINGS,
-+    knex_uc_data_store_conn_string: 'postgresql://toto',
-+    knex_uc_data_store_file_path: 'uc-data-store.sqlite',
-+    knex_uc_data_store_pool_max: 5,
-+    knex_uc_data_store_pool_min: 0,
-+    knex_uc_data_store_type: 'sqlite3',
-    server_static_dir_path: 'public',
-[...]
-container.rebind<SettingsManager>('SettingsManager').to(EnvSettingsManager);
-+container.rebind<UCDataStore>('UCDataStore').to(KnexUCDataStore);
-```
-
-Press <kbd>ctrl</kbd> + <kbd>C</kbd> to stop the server.
-
-```sh
-yarn build && yarn run:server
-```
-
-Fill and submit the use case multiple times.
-
-Open the SQLite database with you with your favorite DB editor (e.g. TablePlus, DBeaver...).
-
-```sh
-open dist/products/SuperTrader/server/uc-data-store.sqlite
-```
-
-You should see all your submissions stored in the database.
-
-```sh
-yarn lint && git add . && git commit -m "feat: persist data in SQLite"
-```
-
-Now that's done, let's [Define wording for humans](./009_Define_wording_for_humans.md).

package/docs/getting-started/009_Define_wording_for_humans.md

@@ -1,42 +0,0 @@
-# Define wording for humans
-
-By default, the UI simply "humanizes" the use case field keys. It's fine for technical people, but not for humans.
-
-Update `src/apps/Trading/src/i18n.ts` and add the following keys to `en`.
-
-```typescript
-uc_BuyAsset_label: 'Buy an asset',
-uc_BuyAsset_i_submit_idle: 'Send buy order',
-uc_BuyAsset_i_submit_submitting: 'Sending',
-ucif_isin_label: 'ISIN',
-ucif_qty_label: 'Quantity',
-ucof_executedDirectly_label: '🚀 Executed directly',
-ucof_id_label: 'Identifier',
-validation_format_ISIN:
-    'Must be 2 uppercase letters, followed by 9 alphanumeric characters and 1 digit',
-```
-
-Update `src/products/SuperTrader/i18n.ts` and add the following keys to `en`.
-
-```typescript
-total: 'Total',
-```
-
-> [!NOTE]
-> We distinguish what's related to the app from what's related to the product. Usually, in the app's `i18n`, you'll add only translations following a certain convention like `dt_*` (data type choices), `err_*` (error messages), `uc_*` (use cases), `ucif_*` (use case input fields), `ucof_*` (use case output fields), `validation_*` (validation messages), etc.
-
-Press <kbd>ctrl</kbd> + <kbd>C</kbd> to stop the server.
-
-```sh
-yarn build && yarn run:server
-```
-
-Refresh the page. You should see a better wording. Try to type an invalid `ISIN` and see how the full validation message is displayed as well.
-
-<img src="/docs/assets/trading-target-web-human.png" width="600px">
-
-```sh
-yarn lint && git add . && git commit -m "feat: define wording for humans"
-```
-
-Now that's done, let's [Create the cli Target](./010_Create_the_cli_Target.md).