libmodulor 0.2.0 → 0.3.0

package/.github/ISSUE_TEMPLATE/generic-issue.md

@@ -0,0 +1,16 @@
+---
+name: Generic Issue
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+## Problem
+
+<!-- State the problem clearly with as much details as you can. It can be a new feature request or a bug. Either way, there should be a clear problem -->
+
+## Potential Solution(s)
+
+<!-- If you have ideas, feel free to suggest them, we love it. We'll discuss the solutions and find the best one for everyone -->

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # CHANGELOG
 
+## v0.3.0 (2025-01-23)
+
+**feat(uc): introduce alternate mounting point**
+
+Added a new property `UcDef.ext.http.mountAlsoAt` to be able to define path aliases. See the comment below to understand why.
+
+```typescript
+/**
+ * The path on which the use case should also mounted at
+ *
+ * This is typically used when the mounting point is changed and you want to maintain a "legacy" endpoint for clients having
+ * a different release cycle than the server (e.g. a mobile app), who are still calling the old endpoint.
+ */
+mountAlsoAt?: UCHTTPMountingPoint[];
+```
+
+**feat(uc): add id to fields in UCOutputReader**
+
+The `UCOutputReader` automatically builds a fields list based on the `UCDef.io.o` `fields` and `order`. Although being a technical value, it's sometimes useful to get the `id` as a field as well as all the other fields explicitly defined. Hence the addition of `id` to the fields list.
+
 ## v0.2.0 (2025-01-20)
 
 It's finally here ! Very first version of the library with all the primitives discussed in the documentation.

package/README.md

@@ -197,21 +197,21 @@ block-beta
 
 _If you're not seeing the mermaid chart (e.g. on npm), head to GitHub._
 
-Please note that we'll only develop one use case to keep the Guide straightforward but you'll quickly get the idea to develop all the orders by yourself.
+Please note that we'll only develop one use case to keep the Guide straightforward but you'll quickly get the idea to develop all the others by yourself.
 
 Here are the steps we're going to follow. Don't worry. Even though it seems a lot, it will be super quick, efficient and straight to the point.
 
-1. [Create the project](./docs/getting-started/001_Create_the_project.md)
-1. [Create the App](./docs/getting-started/002_Create_the_App.md)
-1. [Create the UseCase](./docs/getting-started/003_Create_the_UseCase.md)
-1. [Test the App](./docs/getting-started/004_Test_the_App.md)
-1. [Create the Product](./docs/getting-started/005_Create_the_Product.md)
-1. [Create the server Target](./docs/getting-started/006_Create_the_server_Target.md)
-1. [Create the web Target](./docs/getting-started/007_Create_the_web_Target.md)
-1. [Switch to a persistent data storage](./docs/getting-started/008_Switch_to_a_persistent_data_storage.md)
-1. [Define wording for humans](./docs/getting-started/009_Define_wording_for_humans.md)
-1. [Create the cli Target](./docs/getting-started/010_Create_the_cli_Target.md)
-1. [Create the mcp-server Target](./docs/getting-started/011_Create_the_mcp_server_Target.md)
-1. [Summary](./docs/getting-started/012_Summary.md)
-
-Let's go with the first step : [Create the project](./docs/getting-started/001_Create_the_project.md).
+1. [Create the project](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/001_Create_the_project.md)
+1. [Create the App](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/002_Create_the_App.md)
+1. [Create the UseCase](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/003_Create_the_UseCase.md)
+1. [Test the App](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/004_Test_the_App.md)
+1. [Create the Product](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/005_Create_the_Product.md)
+1. [Create the server Target](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/006_Create_the_server_Target.md)
+1. [Create the web Target](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/007_Create_the_web_Target.md)
+1. [Switch to a persistent data storage](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/008_Switch_to_a_persistent_data_storage.md)
+1. [Define wording for humans](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/009_Define_wording_for_humans.md)
+1. [Create the cli Target](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/010_Create_the_cli_Target.md)
+1. [Create the mcp-server Target](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/011_Create_the_mcp_server_Target.md)
+1. [Summary](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/012_Summary.md)
+
+Let's go with the first step : [Create the project](https://github.com/c100k/libmodulor/blob/v0.3.0/docs/getting-started/001_Create_the_project.md).

package/dist/esm/target/node-express-server/NodeExpressServerManager.js

@@ -92,7 +92,7 @@ let NodeExpressServerManager = class NodeExpressServerManager {
     }
     async mount(appManifest, ucd, contract) {
         const { sec } = ucd;
-        const { envelope, method, path } = contract;
+        const { envelope, method, path, pathAliases } = contract;
         const httpMethod = method.toLowerCase();
         const handlers = [
             this.publicApiKeyCheckerMB.exec({
@@ -107,6 +107,9 @@ let NodeExpressServerManager = class NodeExpressServerManager {
             }),
         ];
         this.runtime[httpMethod](path, handlers);
+        for (const pathAlias of pathAliases) {
+            this.runtime[httpMethod](pathAlias, handlers);
+        }
     }
     async mountStaticDir(dirPath) {
         this.runtime.use(express.static(dirPath));

package/dist/esm/uc/ext.d.ts

@@ -2,13 +2,15 @@ import type { HTTPMethod, URLPath } from '../dt/index.js';
 import type { UCOPIBase } from './opi.js';
 import type { UCOutput } from './output.js';
 import type { UCMountingPoint } from './utils/ucMountingPoint.js';
+export type UCHTTPMountingPoint = `/${URLPath}`;
 export interface UCExt<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> {
     cmd?: {
         mountAt?: UCMountingPoint;
     };
     http?: {
         method?: HTTPMethod;
-        mountAt?: `/${URLPath}`;
+        mountAt?: UCHTTPMountingPoint;
+        mountAlsoAt?: UCHTTPMountingPoint[];
         transform?: <T extends object>(output: UCOutput<OPI0, OPI1>) => T;
     };
 }

package/dist/esm/uc/helpers/UCOutputReader.d.ts

@@ -1,4 +1,4 @@
-import type { DataType } from '../../dt/index.js';
+import { type DataType } from '../../dt/index.js';
 import type { StringKeys } from '../../utils/index.js';
 import type { UC } from '../UC.js';
 import { UCOutputField } from '../UCOutputField.js';

package/dist/esm/uc/helpers/UCOutputReader.js

@@ -1,3 +1,4 @@
+import { TUUID } from '../../dt/index.js';
 import { UCOutputField } from '../UCOutputField.js';
 const ERR_NO_FIELD = (key) => `No field ${key} is defined for this use case`;
 const ERR_NO_IO_OUTPUT = 'No output is defined for this use case';
@@ -64,7 +65,8 @@ export class UCOutputReader {
             return undefined;
         }
         const { fields, layout, order, related } = partDef;
-        const fieldKeys = order ?? Object.keys(fields);
+        const allFields = { id: { type: new TUUID() }, ...fields };
+        const allFieldsKeys = order ?? Object.keys(allFields);
         let items = [];
         let total = 0;
         const part = this._output?.parts[key];
@@ -73,7 +75,7 @@ export class UCOutputReader {
             total = part.total;
         }
         return {
-            fields: fieldKeys.map((fieldKey) => new UCOutputField(fieldKey, fields[fieldKey])),
+            fields: allFieldsKeys.map((fieldKey) => new UCOutputField(fieldKey, allFields[fieldKey])),
             idx,
             items,
             key,

package/dist/esm/uc/output-part.d.ts

@@ -10,8 +10,9 @@ export interface UCOutputPart<OPI extends UCOPIBase> {
     pagination?: ListInput;
     total: UIntQuantity;
 }
+export type UCOutputPartDefFields<OPI extends UCOPIBase> = Record<StringKeys<OPI>, UCOutputFieldDef<OPI, any>>;
 export interface UCOutputPartDef<OPI extends UCOPIBase> {
-    fields: Omit<Record<StringKeys<OPI>, UCOutputFieldDef<OPI, any>>, 'id'>;
+    fields: Omit<UCOutputPartDefFields<OPI>, 'id'>;
     layout?: UCOPILayout<OPI>;
     order?: StringKeys<OPI>[];
     related?: {

package/dist/esm/uc/utils/ucHTTPContract.d.ts

@@ -10,5 +10,6 @@ export interface UCHTTPContract {
     method: HTTPMethod;
     mountingPoint: UCMountingPoint;
     path: URLPath;
+    pathAliases: URLPath[];
 }
 export declare function ucHTTPContract<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>, pathPrefix?: `/${URLPath}`): UCHTTPContract;

package/dist/esm/uc/utils/ucHTTPContract.js

@@ -24,11 +24,16 @@ export function ucHTTPContract(uc, pathPrefix = '/api/v1') {
     }
     const mountingPoint = ucMountingPoint(uc);
     const path = ext?.http?.mountAt ?? `${pathPrefix}/${mountingPoint}`;
+    const pathAliases = [];
+    if (ext?.http?.mountAlsoAt) {
+        pathAliases.push(...ext.http.mountAlsoAt);
+    }
     return {
         contentType,
         envelope,
         method,
         mountingPoint,
         path,
+        pathAliases,
     };
 }

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

@@ -69,13 +69,13 @@ src/apps/**/test/reports
     },
     "dependencies": {
         "inversify": "^6.2.1",
-        "libmodulor": "^0.2.0",
+        "libmodulor": "^0.3.0",
         "reflect-metadata": "^0.2.2"
     },
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@types/node": "^22.10.2",
-        "@vitest/coverage-v8": "^2.1.1",
+        "@types/node": "^22.10.7",
+        "@vitest/coverage-v8": "^3.0.2",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
         "express": "^4.21.2",
@@ -83,9 +83,9 @@ src/apps/**/test/reports
         "fast-check": "^3.23.2",
         "helmet": "^8.0.0",
         "jose": "^5.9.6",
-        "typescript": "^5.7.2",
-        "vite": "^6.0.5",
-        "vitest": "^2.1.8"
+        "typescript": "^5.7.3",
+        "vite": "^6.0.11",
+        "vitest": "^3.0.3"
     }
 }
 ```

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

@@ -99,7 +99,7 @@ Update `src/apps/Trading/index.ts` to expose the use case.
 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 ?
+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';

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

@@ -13,7 +13,10 @@ Update `src/products/SuperTrader/server/container.ts` to change the implementati
     TARGET_DEFAULT_SERVER_MANAGER_SETTINGS,
 +    type UCDataStore,
 [...]
-+import { KnexUCDataStore } from 'libmodulor/uc-data-store/knex';
++import {
++    KnexUCDataStore,
++    type KnexUCDataStoreSettings,
++} from 'libmodulor/uc-data-store-knex';
 [...]
 +type S = KnexUCDataStoreSettings & ServerManagerSettings;
 [...]
@@ -37,7 +40,7 @@ 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...).
+Open the SQLite database with your favorite DB editor (e.g. TablePlus, DBeaver...).
 
 ```sh
 open dist/products/SuperTrader/server/uc-data-store.sqlite

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

@@ -5,15 +5,15 @@ By default, the UI simply "humanizes" the use case field keys. It's fine for tec
 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',
+        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`.

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

@@ -1,6 +1,6 @@
 # Create the cli Target
 
-We'll use the pre-built [Node.js parseArgs](https://nodejs.org/api/util.html#utilparseargsconfig) CLI program.
+We'll use the pre-built [Node.js parseArgs](https://nodejs.org/api/util.html#utilparseargsconfig) `CLIManager`.
 
 ```sh
 mkdir src/products/SuperTrader/cli
@@ -83,13 +83,13 @@ yarn run:server
 Execute the CLI in another terminal or tab.
 
 ```sh
-yarn run:cli BuyAsset
+yarn run:cli Trading_BuyAsset
 # ❌ ISIN must be filled
-yarn run:cli BuyAsset --isin US02079K3059 --limit 123.5 --qty 150
+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 you with your favorite DB editor (e.g. TablePlus, DBeaver...).
+Open the SQLite database with your favorite DB editor (e.g. TablePlus, DBeaver...).
 
 ```sh
 open dist/products/SuperTrader/server/uc-data-store.sqlite

package/docs/getting-started/011_Create_the_mcp_server_Target.md

@@ -1,6 +1,6 @@
 # Create the mcp-server Target
 
-We'll use the pre-built local [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input-output-stdio) server.
+We'll use the pre-built local [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input-output-stdio) `ServerManager`.
 
 ```sh
 yarn add "@modelcontextprotocol/sdk@^1.1.1"
@@ -144,7 +144,7 @@ And let the magic happens.
 
 <img src="/docs/assets/trading-target-mcp-server.png" width="600px">
 
-Open the SQLite database with you with your favorite DB editor (e.g. TablePlus, DBeaver...).
+Open the SQLite database with your favorite DB editor (e.g. TablePlus, DBeaver...).
 
 ```sh
 open dist/products/SuperTrader/server/uc-data-store.sqlite

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "libmodulor",
     "description": "An opinionated TypeScript library to create business oriented applications",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "license": "LGPL-3.0",
     "author": "Chafik H'nini <chafik.hnini@gmail.com>",
     "homepage": "https://github.com/c100k/libmodulor#readme",