libmodulor 0.3.0 → 0.4.0

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`. Instead, we would create fine-grained components. Everybody does that, right ? 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,55 +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,
-+    type KnexUCDataStoreSettings,
-+} 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 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).

package/docs/getting-started/010_Create_the_cli_Target.md

@@ -1,102 +0,0 @@
-# Create the cli Target
-
-We'll use the pre-built [Node.js parseArgs](https://nodejs.org/api/util.html#utilparseargsconfig) `CLIManager`.
-
-```sh
-mkdir src/products/SuperTrader/cli
-touch src/products/SuperTrader/cli/{container.ts,index.ts}
-```
-
-## container.ts
-
-```typescript
-import {
-    CONTAINER_OPTS,
-    type ServerClientManagerSettings,
-    TARGET_DEFAULT_SERVER_CLIENT_MANAGER_SETTINGS,
-    bindCommon,
-    bindProduct,
-} from 'libmodulor';
-import { bindNodeCLI, bindNodeCore } from 'libmodulor/node';
-import { Container } from 'inversify';
-
-import { I18n } from '../i18n.js';
-import { Manifest } from '../manifest.js';
-
-const container = new Container(CONTAINER_OPTS);
-
-bindCommon<ServerClientManagerSettings>(container, () => ({
-    ...TARGET_DEFAULT_SERVER_CLIENT_MANAGER_SETTINGS,
-}));
-bindNodeCore(container);
-bindNodeCLI(container);
-bindProduct(container, Manifest, I18n);
-
-export default container;
-```
-
-## index.ts
-
-```typescript
-import {
-    APPS_ROOT_DIR_NAME,
-    type FSManager,
-    type I18nManager,
-} from 'libmodulor';
-import { NodeCoreCLIManager } from 'libmodulor/node';
-
-import container from './container.js';
-
-await container.get<I18nManager>('I18nManager').init();
-
-await container.resolve(NodeCoreCLIManager).handleCommand({
-    appsRootPath: container
-        .get<FSManager>('FSManager')
-        .path('..', '..', '..', APPS_ROOT_DIR_NAME),
-    srcImporter: (path) => import(path),
-});
-```
-
-## Build & Run
-
-Update `package.json` to add a new entry to the `scripts`.
-
-```json
-"run:cli": "cd dist/products/SuperTrader/cli && node index.js",
-```
-
-```sh
-yarn build && yarn run:cli
-```
-
-You can see the CLI help appearing with the available commands.
-
-> [!TIP]
-> Update the app's `i18n.ts` to add `uc_BuyAsset_desc` and `ucif_isin_desc` to have a more detailed help section.
-
-Start the server if it's not running.
-
-```sh
-yarn run:server
-```
-
-Execute the CLI in another terminal or tab.
-
-```sh
-yarn run:cli Trading_BuyAsset
-# ❌ ISIN must be filled
-yarn run:cli Trading_BuyAsset --isin US02079K3059 --limit 123.5 --qty 150
-# ✅ {"parts":{"_0":{"items":[{"executedDirectly":false,"id":"da3dc295-6d7c-41b1-a00a-62683f3e6ab9"}],"total":1}}}
-```
-
-Open the SQLite database with your favorite DB editor (e.g. TablePlus, DBeaver...).
-
-```sh
-open dist/products/SuperTrader/server/uc-data-store.sqlite
-```
-
-```sh
-yarn lint && git add . && git commit -m "feat: add the cli target"
-```
-
-Now that's done, let's [Create the mcp-server Target](./011_Create_the_mcp_server_Target.md).