libmodulor 0.2.0 → 0.4.0

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/package.json

@@ -1,7 +1,7 @@
 {
     "name": "libmodulor",
     "description": "An opinionated TypeScript library to create business oriented applications",
-    "version": "0.2.0",
+    "version": "0.4.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"
         },
@@ -55,25 +58,26 @@
     },
     "peerDependencies": {
         "@hono/node-server": "^1.13.7",
-        "@modelcontextprotocol/sdk": "^1.1.1",
-        "@stricli/core": "^1.1.0",
+        "@modelcontextprotocol/sdk": "^1.4.1",
+        "@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",
+        "hono": "^4.6.19",
         "inversify": "^6.2.1",
         "jose": "^5.9.6",
         "knex": "^3.1.0",
         "pg": "^8.13.1",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
+        "react-native": "^0.76.6",
         "reflect-metadata": "^0.2.2",
         "sqlite3": "^5.1.7",
         "typescript": "^5.7.3",
-        "vite": "^6.0.7"
+        "vite": "^6.0.11"
     },
     "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.2.0",
-        "reflect-metadata": "^0.2.2"
-    },
-    "devDependencies": {
-        "@biomejs/biome": "^1.9.4",
-        "@types/node": "^22.10.2",
-        "@vitest/coverage-v8": "^2.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",
-        "jose": "^5.9.6",
-        "typescript": "^5.7.2",
-        "vite": "^6.0.5",
-        "vitest": "^2.1.8"
-    }
-}
-```
-
-## 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).