libmodulor 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## v0.10.0 (2025-03-28)
+
+**Misc**
+
+- Update `examples/supertrader` to showcase type semantics and displaying UC output fields according to the definition
+- In `target/react`, make `useUCOR` return a `Part0` always set : you can remove all the now obsolete patterns like `if (listItemsPart0)`, `listItemsPart0 &&`, `listItemsPart0?.`, `listItemsPart0!.` in your React components relying on `useUCOR`. Also expose the function signatures used by `useUC` and `useUCOR` to make them easily passable as children props
+- Introduce `UCOutputFieldValueFragment` in `target/react` and `UCOutputFieldValue` in `target/react-(native|web)-pure` to display uc values using the `fmt()` method of each data type. `TBoolean.fmt()` has been adapted to display `✔️` when `true`, instead of `true|false` which are not very user friendly in a UI
+- List base and final data types directly in the documentation => https://libmodulor.c100k.eu/docs/references/data-types
+- Introduce `Year` data type
+- Adjust `fmt` of `THostPort` and `TTimestamp` (they shouldn't be formatted as numbers) and `tName` of `TEmbeddedObject`
+
 ## v0.9.0 (2025-03-20)
 
 **BREAKING**
@@ -10,7 +21,7 @@
 **Misc**
 
 - Make `buffer`, `fast-check` and `vitest` deps optional : basic uses of `libmodulor` do not require them (see https://libmodulor.c100k.eu/docs/examples/Basic as an example). You can remove them if you're not using the automated tests
-- Add `ListOrdersUCD` an `CancelOrderUCD` to `examples/supertrader` to showcase data fetching, aggregate building, sensitive use cases, test flows, etc.
+- Add `ListOrdersUCD` and `CancelOrderUCD` to `examples/supertrader` to showcase data fetching, aggregate building, sensitive use cases, test flows, etc.
 - Remove linter config from examples (linting from repo root folder)
 - Use `debug` instead of `trace` in `ConsoleLogger`
 

package/README.md

@@ -23,4 +23,4 @@ If you think you can help in any way, feel free to contact me (cf. `author` in `
 
 ## ⚖️ License
 
-[LGPL-3.0](https://github.com/c100k/libmodulor/blob/v0.9.0/LICENSE)
+[LGPL-3.0](https://github.com/c100k/libmodulor/blob/v0.10.0/LICENSE)

package/dist/esm/apps/Helper/src/lib/project.js

@@ -42,18 +42,18 @@ export const PACKAGE_JSON = (name) => `{
     },
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@types/node": "^22.13.10",
-        "@vitest/coverage-v8": "^3.0.8",
+        "@types/node": "^22.13.11",
+        "@vitest/coverage-v8": "^3.0.9",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
         "express": "^4.21.2",
         "express-fileupload": "^1.5.1",
         "fast-check": "^4.0.0",
-        "helmet": "^8.0.0",
+        "helmet": "^8.1.0",
         "jose": "^6.0.10",
         "typescript": "^5.8.2",
         "vite": "^6.2.2",
-        "vitest": "^3.0.8"
+        "vitest": "^3.0.9"
     }
 }
 `;

package/dist/esm/dt/DataType.d.ts

@@ -63,6 +63,8 @@ import type { URL } from './final/TURL.js';
 import type { URLPath } from './final/TURLPath.js';
 import type { UUID } from './final/TUUID.js';
 import type { Username } from './final/TUsername.js';
+import type { Year } from './final/TYear.js';
+import type { YesNo } from './final/TYesNo.js';
 type Primitive = string | number | boolean;
-export type DataType = Primitive | Address | Amount | ApiKey | BarCode | CSS | Color | ColorRGBA | CompanyName | CountryISO3166Alpha2 | CurrencyISO4217 | DateISO8601 | DateTimeFormat | DirPath | DomainName | Email | EmbeddedObject | Emoji | EncryptionKey | ErrorMessage | ExternalServiceId | File | FileExtension | FileMimeType | FileName | FilePath | FreeTextLong | FreeTextShort | Geolocation | GitSSHURL | HTML | HTTPContentType | HTTPMethod | HTTPStatusNumber | HostAddress | HostPort | IPv4 | IPv6 | JSONString | JWT | JavaScript | JobTitle | Markdown | NumIndex | Password | Percentage | PersonFirstname | PersonFullname | PersonInitials | PersonLastname | QRCode | SQLQuery | SSHPrivateKey | SSHPublicKey | SearchQuery | SemVerVersion | ShellCommand | Slug | Time | Timestamp | UIntDuration | UIntQuantity | URL | URLPath | UUID | Username;
+export type DataType = Primitive | Address | Amount | ApiKey | BarCode | CSS | Color | ColorRGBA | CompanyName | CountryISO3166Alpha2 | CurrencyISO4217 | DateISO8601 | DateTimeFormat | DirPath | DomainName | Email | EmbeddedObject | Emoji | EncryptionKey | ErrorMessage | ExternalServiceId | File | FileExtension | FileMimeType | FileName | FilePath | FreeTextLong | FreeTextShort | Geolocation | GitSSHURL | HTML | HTTPContentType | HTTPMethod | HTTPStatusNumber | HostAddress | HostPort | IPv4 | IPv6 | JSONString | JWT | JavaScript | JobTitle | Markdown | NumIndex | Password | Percentage | PersonFirstname | PersonFullname | PersonInitials | PersonLastname | QRCode | SQLQuery | SSHPrivateKey | SSHPublicKey | SearchQuery | SemVerVersion | ShellCommand | Slug | Time | Timestamp | UIntDuration | UIntQuantity | URL | URLPath | UUID | Username | Year | YesNo;
 export {};

package/dist/esm/dt/DataTypes.js

@@ -64,5 +64,6 @@ export const DataTypes = [
     'URLPath',
     'UUID',
     'Username',
+    'Year',
     'YesNo',
 ];

package/dist/esm/dt/base/TBoolean.d.ts

@@ -5,6 +5,7 @@ export declare class TBoolean extends TBase<boolean> {
     tName(): TName;
     assign(raw: unknown): this;
     example(): boolean;
+    fmt(ifNullOrUndefined?: string | undefined): string;
     htmlInputType(): HTMLInputType;
     validate(): Validation;
 }

package/dist/esm/dt/base/TBoolean.js

@@ -24,6 +24,12 @@ export class TBoolean extends TBase {
     example() {
         return true;
     }
+    fmt(ifNullOrUndefined) {
+        if (typeof this.raw !== 'boolean' || this.raw !== true) {
+            return super.fmt(ifNullOrUndefined);
+        }
+        return '✔️';
+    }
     htmlInputType() {
         return 'checkbox';
     }

package/dist/esm/dt/final/TEmbeddedObject.d.ts

@@ -1,6 +1,8 @@
+import type { TName } from '../base/TBase.js';
 import { TObject, type TObjectConstraints } from '../base/TObject.js';
 export type EmbeddedObject<E extends object = object> = E;
 export declare class TEmbeddedObject<E extends object = object> extends TObject<EmbeddedObject<E>> {
     protected constraints: TObjectConstraints;
     constructor(constraints?: TObjectConstraints);
+    tName(): TName;
 }

package/dist/esm/dt/final/TEmbeddedObject.js

@@ -7,4 +7,7 @@ export class TEmbeddedObject extends TObject {
         super(constraints);
         this.constraints = constraints;
     }
+    tName() {
+        return 'EmbeddedObject';
+    }
 }

package/dist/esm/dt/final/THostPort.d.ts

@@ -5,4 +5,5 @@ export declare class THostPort extends TUInt<HostPort> {
     constructor(constraints?: TUIntConstraints);
     tName(): TName;
     example(): HostPort;
+    fmt(ifNullOrUndefined?: string | undefined): string;
 }

package/dist/esm/dt/final/THostPort.js

@@ -12,4 +12,11 @@ export class THostPort extends TUInt {
     example() {
         return 443;
     }
+    fmt(ifNullOrUndefined) {
+        if (typeof this.raw !== 'number') {
+            return super.fmt(ifNullOrUndefined);
+        }
+        // Not using `fmtNumber` to avoid weird formatting (e.g. comma used as a thousands separator)
+        return this.raw.toString();
+    }
 }

package/dist/esm/dt/final/TTimestamp.d.ts

@@ -4,4 +4,5 @@ export type Timestamp = UInt;
 export declare class TTimestamp extends TUInt {
     tName(): TName;
     example(): Timestamp;
+    fmt(ifNullOrUndefined?: string | undefined): string;
 }

package/dist/esm/dt/final/TTimestamp.js

@@ -6,4 +6,11 @@ export class TTimestamp extends TUInt {
     example() {
         return 1_628_359_209;
     }
+    fmt(ifNullOrUndefined) {
+        if (typeof this.raw !== 'number') {
+            return super.fmt(ifNullOrUndefined);
+        }
+        // Not using `fmtNumber` to avoid weird formatting (e.g. comma used as a thousands separator)
+        return this.raw.toString();
+    }
 }

package/dist/esm/dt/final/TYear.d.ts

@@ -0,0 +1,9 @@
+import type { TName } from '../base/TBase.js';
+import { TUInt, type TUIntConstraints, type UInt } from '../base/TUInt.js';
+export type Year = UInt;
+export declare class TYear extends TUInt<Year> {
+    constructor(constraints?: TUIntConstraints);
+    tName(): TName;
+    example(): Year;
+    fmt(ifNullOrUndefined?: string | undefined): string;
+}

package/dist/esm/dt/final/TYear.js

@@ -0,0 +1,22 @@
+import { TUInt } from '../base/TUInt.js';
+export class TYear extends TUInt {
+    constructor(constraints) {
+        super({
+            ...constraints,
+            min: 0,
+        });
+    }
+    tName() {
+        return 'Year';
+    }
+    example() {
+        return 2025;
+    }
+    fmt(ifNullOrUndefined) {
+        if (typeof this.raw !== 'number') {
+            return super.fmt(ifNullOrUndefined);
+        }
+        // Not using `fmtNumber` to avoid weird formatting (e.g. comma used as a thousands separator)
+        return this.raw.toString();
+    }
+}

package/dist/esm/dt/index.d.ts

@@ -70,6 +70,7 @@ export { type Username, TUsername } from './final/TUsername.js';
 export { type URL, TURL } from './final/TURL.js';
 export { type URLPath, TURLPath } from './final/TURLPath.js';
 export { type UUID, TUUID } from './final/TUUID.js';
+export { type Year, TYear } from './final/TYear.js';
 export { type YesNo, TYesNo } from './final/TYesNo.js';
 export type { RNInputMode } from './targets/rn.js';
 export type { HTMLInputType } from './targets/web.js';

package/dist/esm/dt/index.js

@@ -70,6 +70,7 @@ export { TUsername } from './final/TUsername.js';
 export { TURL } from './final/TURL.js';
 export { TURLPath } from './final/TURLPath.js';
 export { TUUID } from './final/TUUID.js';
+export { TYear } from './final/TYear.js';
 export { TYesNo } from './final/TYesNo.js';
 export { DataTypes } from './DataTypes.js';
 export { Validation, } from './Validation.js';

package/dist/esm/index.react-native-pure.d.ts

@@ -8,3 +8,4 @@ export { UCFormFieldDesc } from './target/react-native-pure/UCFormFieldDesc.js';
 export { UCFormFieldErr } from './target/react-native-pure/UCFormFieldErr.js';
 export { UCFormFieldLabel } from './target/react-native-pure/UCFormFieldLabel.js';
 export { UCFormSubmitControl } from './target/react-native-pure/UCFormSubmitControl.js';
+export { UCOutputFieldValue } from './target/react-native-pure/UCOutputFieldValue.js';

package/dist/esm/index.react-native-pure.js

@@ -8,3 +8,4 @@ export { UCFormFieldDesc } from './target/react-native-pure/UCFormFieldDesc.js';
 export { UCFormFieldErr } from './target/react-native-pure/UCFormFieldErr.js';
 export { UCFormFieldLabel } from './target/react-native-pure/UCFormFieldLabel.js';
 export { UCFormSubmitControl } from './target/react-native-pure/UCFormSubmitControl.js';
+export { UCOutputFieldValue } from './target/react-native-pure/UCOutputFieldValue.js';

package/dist/esm/index.react-web-pure.d.ts

@@ -8,3 +8,4 @@ export { UCFormFieldDesc } from './target/react-web-pure/UCFormFieldDesc.js';
 export { UCFormFieldErr } from './target/react-web-pure/UCFormFieldErr.js';
 export { UCFormFieldLabel } from './target/react-web-pure/UCFormFieldLabel.js';
 export { UCFormSubmitControl } from './target/react-web-pure/UCFormSubmitControl.js';
+export { UCOutputFieldValue } from './target/react-web-pure/UCOutputFieldValue.js';

package/dist/esm/index.react-web-pure.js

@@ -8,3 +8,4 @@ export { UCFormFieldDesc } from './target/react-web-pure/UCFormFieldDesc.js';
 export { UCFormFieldErr } from './target/react-web-pure/UCFormFieldErr.js';
 export { UCFormFieldLabel } from './target/react-web-pure/UCFormFieldLabel.js';
 export { UCFormSubmitControl } from './target/react-web-pure/UCFormSubmitControl.js';
+export { UCOutputFieldValue } from './target/react-web-pure/UCOutputFieldValue.js';

package/dist/esm/index.react.d.ts

@@ -4,6 +4,7 @@ export type { UCPanelCtx, UCPanelOnDone, UCPanelOnError, UCPanelOnInit, UCPanelO
 export type { UCEntrypointTouchableProps, RenderUCEntrypointTouchable, RenderUCExecTouchable, UCExecTouchableProps, } from './target/lib/react/touchable.js';
 export { UCContainer } from './target/lib/react/UCContainer.js';
 export { UCEntrypoint } from './target/lib/react/UCEntrypoint.js';
+export { type Props as UCOutputFieldValueFragmentProps, UCOutputFieldValueFragment, } from './target/lib/react/UCOutputFieldValueFragment.js';
 export { UCPanel } from './target/lib/react/UCPanel.js';
-export { useUC } from './target/lib/react/useUC.js';
-export { useUCOR } from './target/lib/react/useUCOR.js';
+export { type CloneFunc, type DivertFunc, type RefillFunc, useUC, } from './target/lib/react/useUC.js';
+export { type AppendFunc, type RemoveFunc, type UpdateFunc, useUCOR, } from './target/lib/react/useUCOR.js';

package/dist/esm/index.react.js

@@ -1,6 +1,7 @@
 export { DIContext, useDIContext, DIContextProvider, } from './target/lib/react/DIContextProvider.js';
 export { UCContainer } from './target/lib/react/UCContainer.js';
 export { UCEntrypoint } from './target/lib/react/UCEntrypoint.js';
+export { UCOutputFieldValueFragment, } from './target/lib/react/UCOutputFieldValueFragment.js';
 export { UCPanel } from './target/lib/react/UCPanel.js';
-export { useUC } from './target/lib/react/useUC.js';
-export { useUCOR } from './target/lib/react/useUCOR.js';
+export { useUC, } from './target/lib/react/useUC.js';
+export { useUCOR, } from './target/lib/react/useUCOR.js';

package/dist/esm/target/lib/react/UCOutputFieldValueFragment.d.ts

@@ -0,0 +1,8 @@
+import { type ReactElement } from 'react';
+import type { DataType } from '../../../dt/index.js';
+import type { UCOPIBase, UCOutputField } from '../../../uc/index.js';
+export interface Props<OPI extends UCOPIBase, T extends DataType> {
+    field: UCOutputField<OPI, T>;
+    value: T;
+}
+export declare function UCOutputFieldValueFragment<OPI extends UCOPIBase, T extends DataType>({ field, value }: Props<OPI, T>): ReactElement;

package/dist/esm/target/lib/react/UCOutputFieldValueFragment.js

@@ -0,0 +1,6 @@
+import React, {} from 'react';
+export function UCOutputFieldValueFragment({ field, value }) {
+    const { def: { type }, } = field;
+    type.assign(value);
+    return React.createElement(React.Fragment, null, type.fmt());
+}

package/dist/esm/target/lib/react/useUC.d.ts

@@ -1,7 +1,7 @@
 import { type ArgsRecord, UC, type UCDef, type UCInput, type UCOPIBase } from '../../../uc/index.js';
-type CloneFunc<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = (i: Partial<I>) => UC<I, OPI0, OPI1>;
-type DivertFunc<II extends UCInput | undefined = undefined, OOPI0 extends UCOPIBase | undefined = undefined, OOPI1 extends UCOPIBase | undefined = undefined> = (siblingUCD: UCDef) => UC<II, OOPI0, OOPI1>;
-type RefillFunc<I extends UCInput | undefined = undefined> = (i: Partial<I>) => void;
+export type CloneFunc<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = (i: Partial<I>) => UC<I, OPI0, OPI1>;
+export type DivertFunc<II extends UCInput | undefined = undefined, OOPI0 extends UCOPIBase | undefined = undefined, OOPI1 extends UCOPIBase | undefined = undefined> = (siblingUCD: UCDef) => UC<II, OOPI0, OOPI1>;
+export type RefillFunc<I extends UCInput | undefined = undefined> = (i: Partial<I>) => void;
 /**
  * This hook provides utilities to init a use case and perform actions on it in a React way
  * @param appManifest
@@ -20,4 +20,3 @@ export declare function useUC<I extends UCInput | undefined = undefined, OPI0 ex
         refill: RefillFunc<I>;
     }
 ];
-export {};

package/dist/esm/target/lib/react/useUCOR.d.ts

@@ -1,7 +1,7 @@
 import type { UCInput, UCOPIBase, UCOutputReader, UCOutputReaderPart } from '../../../uc/index.js';
-type AppendFunc<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = (ucor: UCOutputReader<any, OPI0, OPI1>) => void;
-type RemoveFunc<OPI extends UCOPIBase> = (item: OPI) => void;
-type UpdateFunc<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = (ucor: UCOutputReader<any, OPI0, OPI1>) => void;
+export type AppendFunc<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = (ucor: UCOutputReader<any, OPI0, OPI1>) => void;
+export type RemoveFunc<OPI extends UCOPIBase> = (item: OPI) => void;
+export type UpdateFunc<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = (ucor: UCOutputReader<any, OPI0, OPI1>) => void;
 /**
  * This hook provides utilities to act on a {@link UCOutputReader} in a React way
  *
@@ -18,7 +18,7 @@ type UpdateFunc<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCO
  * @returns
  */
 export declare function useUCOR<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(ucor: UCOutputReader<I, OPI0, OPI1>): [
-    UCOutputReaderPart<NonNullable<OPI0>> | undefined,
+    UCOutputReaderPart<NonNullable<OPI0>>,
     UCOutputReaderPart<NonNullable<OPI1>> | undefined,
     {
         append0: AppendFunc<OPI0, OPI1>;
@@ -29,4 +29,3 @@ export declare function useUCOR<I extends UCInput | undefined = undefined, OPI0
         update1: UpdateFunc<OPI0, OPI1>;
     }
 ];
-export {};

package/dist/esm/target/react-native-pure/UCOutputFieldValue.d.ts

@@ -0,0 +1,5 @@
+import { type ReactElement } from 'react';
+import type { DataType } from '../../dt/index.js';
+import type { UCOPIBase } from '../../uc/index.js';
+import { type Props } from '../lib/react/UCOutputFieldValueFragment.js';
+export declare function UCOutputFieldValue<OPI extends UCOPIBase, T extends DataType>(props: Props<OPI, T>): ReactElement;

package/dist/esm/target/react-native-pure/UCOutputFieldValue.js

@@ -0,0 +1,7 @@
+import React, {} from 'react';
+import { Text } from 'react-native';
+import { UCOutputFieldValueFragment, } from '../lib/react/UCOutputFieldValueFragment.js';
+export function UCOutputFieldValue(props) {
+    return (React.createElement(Text, null,
+        React.createElement(UCOutputFieldValueFragment, { ...props })));
+}

package/dist/esm/target/react-web-pure/UCOutputFieldValue.d.ts

@@ -0,0 +1,5 @@
+import { type ReactElement } from 'react';
+import type { DataType } from '../../dt/index.js';
+import type { UCOPIBase } from '../../uc/index.js';
+import { type Props } from '../lib/react/UCOutputFieldValueFragment.js';
+export declare function UCOutputFieldValue<OPI extends UCOPIBase, T extends DataType>(props: Props<OPI, T>): ReactElement;

package/dist/esm/target/react-web-pure/UCOutputFieldValue.js

@@ -0,0 +1,6 @@
+import React, {} from 'react';
+import { UCOutputFieldValueFragment, } from '../lib/react/UCOutputFieldValueFragment.js';
+export function UCOutputFieldValue(props) {
+    return (React.createElement("span", null,
+        React.createElement(UCOutputFieldValueFragment, { ...props })));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "libmodulor",
     "description": "An opinionated TypeScript library to create business oriented applications",
-    "version": "0.9.0",
+    "version": "0.10.0",
     "license": "LGPL-3.0",
     "author": "Chafik H'nini <chafik.hnini@gmail.com>",
     "homepage": "https://github.com/c100k/libmodulor#readme",
@@ -75,7 +75,7 @@
         "@biomejs/biome": "^1.9.4"
     },
     "peerDependencies": {
-        "@hono/node-server": "^1.13.8",
+        "@hono/node-server": "^1.14.0",
         "@modelcontextprotocol/sdk": "^1.7.0",
         "@stricli/core": "^1.1.1",
         "buffer": "^6.0.3",
@@ -83,20 +83,20 @@
         "express": "^4.21.2",
         "express-fileupload": "^1.5.1",
         "fast-check": "^4.0.0",
-        "helmet": "^8.0.0",
-        "hono": "^4.7.4",
+        "helmet": "^8.1.0",
+        "hono": "^4.7.5",
         "inversify": "^6.2.2",
         "jose": "^6.0.10",
         "knex": "^3.1.0",
-        "pg": "^8.14.0",
+        "pg": "^8.14.1",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
-        "react-native": "^0.78.0",
+        "react-native": "^0.78.1",
         "reflect-metadata": "^0.2.2",
         "sqlite3": "^5.1.7",
         "typescript": "^5.8.2",
         "vite": "^6.2.2",
-        "vitest": "^3.0.8"
+        "vitest": "^3.0.9"
     },
     "peerDependenciesMeta": {
         "@hono/node-server": {