libmodulor 0.4.0 → 0.6.0

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

@@ -1,2 +1,15 @@
 import type { UCDefSourceRaw } from '../def.js';
+/**
+ * Strip the server part of the UCD
+ *
+ * To be used by bundlers when building for the web for example, or any other clients (e.g. React Native).
+ *
+ * WARNING : This implementation is very naive and will have unexpected behaviors when the UCD has a specific shape.
+ * For instance, if there is another `server: {` occurence than the lifecycle.server definition, it will be wrongly replaced.
+ *
+ * TODO : Make this implementation more robust (let's try not to use an AST parser though, to keep things fast and simple).
+ *
+ * @param source
+ * @returns
+ */
 export declare function stripUCDLifecycleServer(source: UCDefSourceRaw): UCDefSourceRaw;

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

@@ -5,6 +5,19 @@ const TOKEN_IMPORT_END = ';';
 const TOKEN_LIFECYCLE_SERVER = 'server: {';
 const TOKEN_LIFECYCLE_SERVER_END = '},';
 const TOKEN_LIFECYCLE_SERVER_REPLACE = 'server: true,';
+/**
+ * Strip the server part of the UCD
+ *
+ * To be used by bundlers when building for the web for example, or any other clients (e.g. React Native).
+ *
+ * WARNING : This implementation is very naive and will have unexpected behaviors when the UCD has a specific shape.
+ * For instance, if there is another `server: {` occurence than the lifecycle.server definition, it will be wrongly replaced.
+ *
+ * TODO : Make this implementation more robust (let's try not to use an AST parser though, to keep things fast and simple).
+ *
+ * @param source
+ * @returns
+ */
 export function stripUCDLifecycleServer(source) {
     const occurrences = [
         ...source.matchAll(new RegExp(UC_MAIN_SERVER_SUFFIX, 'g')),
@@ -14,6 +27,7 @@ export function stripUCDLifecycleServer(source) {
     let occIdx = 0;
     for (const occ of occurrences) {
         if (count === 3 && occIdx === 1) {
+            // Skip the 2nd occurrence as it is part of the import of the 1st (Rrrrh very hacky...)
             occIdx += 1;
             continue;
         }
@@ -37,6 +51,9 @@ export function stripUCDLifecycleServer(source) {
         toReplace.push(toRep);
         occIdx += 1;
     }
+    // Flip the items to replace in order to remove the usage before the imports
+    // This is related to the edge case of IdleServerMain that we remove from the imports list,
+    // while for specific ServerMain, we remove the entire import instruction.
     toReplace.reverse();
     let cleaned = source;
     for (const { str } of toReplace) {

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

@@ -1,2 +1,8 @@
 import { UCInputFieldChangeOperator } from '../input-field.js';
+/**
+ * Check whether a {@link UCInputFieldChangeOperator} is for an array or not.
+ *
+ * @param op
+ * @returns
+ */
 export declare function ucifcoIsForArray(op: UCInputFieldChangeOperator): op is UCInputFieldChangeOperator.ADD | UCInputFieldChangeOperator.REMOVE;

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

@@ -1,4 +1,10 @@
 import { UCInputFieldChangeOperator } from '../input-field.js';
+/**
+ * Check whether a {@link UCInputFieldChangeOperator} is for an array or not.
+ *
+ * @param op
+ * @returns
+ */
 export function ucifcoIsForArray(op) {
     return [
         UCInputFieldChangeOperator.ADD,

package/dist/esm/uc/workers/SimpleAggregateFinder.d.ts

@@ -12,6 +12,18 @@ interface Input {
 interface Output<I extends UCInput | undefined = undefined, D extends UCData | null = null> {
     record: UCDataStoreRecord<I, D>;
 }
+/**
+ * Find an aggregate by id by replaying additive use cases and removal ones
+ *
+ * This works only in simple scenarios where you have the following use cases :
+ *   - `CreateX`
+ *   - `CreateX`, `DeleteX`
+ *   - `CreateX`, `[DeleteX, ArchiveX]`
+ *
+ * If there is an `UpdateX` for example, do not use this as the record won't be accurate. Replay the records yourself with {@link UCDataStore.read()}.
+ *
+ * It throws a {@link NotFoundError} if there are more than one record (in which case somethin is wrong with the data store) or none.
+ */
 export declare class SimpleAggregateFinder implements Worker<Input, Promise<Output>> {
     private ucDataStore;
     constructor(ucDataStore: UCDataStore);

package/dist/esm/uc/workers/SimpleAggregateFinder.js

@@ -12,6 +12,18 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from 'inversify';
 import { NotFoundError } from '../../error/index.js';
+/**
+ * Find an aggregate by id by replaying additive use cases and removal ones
+ *
+ * This works only in simple scenarios where you have the following use cases :
+ *   - `CreateX`
+ *   - `CreateX`, `DeleteX`
+ *   - `CreateX`, `[DeleteX, ArchiveX]`
+ *
+ * If there is an `UpdateX` for example, do not use this as the record won't be accurate. Replay the records yourself with {@link UCDataStore.read()}.
+ *
+ * It throws a {@link NotFoundError} if there are more than one record (in which case somethin is wrong with the data store) or none.
+ */
 let SimpleAggregateFinder = class SimpleAggregateFinder {
     ucDataStore;
     constructor(ucDataStore) {

package/dist/esm/uc/workers/UCBuilder.d.ts

@@ -4,6 +4,13 @@ import type { UCInput } from '../input.js';
 import type { UCOPIBase } from '../opi.js';
 type Input<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = ArgsRecord<I, OPI0, OPI1>;
 type Output<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = UC<I, OPI0, OPI1>;
+/**
+ * Build a Use Case
+ *
+ * When initially implemented this, {@link I18nManager} was injected to provide the `languageCode` to the {@link UC}.
+ *
+ * But this dependency has been removed when introducing {@link WordingManager}. Let's keep it for now in case we need to inject something.
+ */
 export declare class UCBuilder implements Worker<Input, Output> {
     exec<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ appManifest, auth, def }: Input<I, OPI0, OPI1>): Output<I, OPI0, OPI1>;
 }

package/dist/esm/uc/workers/UCBuilder.js

@@ -6,6 +6,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { injectable } from 'inversify';
 import { UC } from '../UC.js';
+/**
+ * Build a Use Case
+ *
+ * When initially implemented this, {@link I18nManager} was injected to provide the `languageCode` to the {@link UC}.
+ *
+ * But this dependency has been removed when introducing {@link WordingManager}. Let's keep it for now in case we need to inject something.
+ */
 let UCBuilder = class UCBuilder {
     exec({ appManifest, auth, def }) {
         return new UC(appManifest, def, auth);

package/dist/esm/uc/workers/UCExecChecker.js

@@ -54,6 +54,8 @@ let UCExecChecker = class UCExecChecker {
                 break;
             }
             case 'server':
+                // Nothing specific for the moment as everything is checked in function of authentication
+                // @see AuthenticationChecker called in the request lifecycle
                 output.allowed = typeof server === 'object';
                 break;
             default:

package/dist/esm/uc/workers/UCInputFilesProcessor.js

@@ -42,6 +42,9 @@ let UCInputFilesProcessor = class UCInputFilesProcessor {
             if (isRepeatable) {
                 const files = rValArr(field.getValue());
                 const fileNameRefs = await Promise.all(files.map(async (f) => this.processFile(f)));
+                // Although the field is a file, here we fill it with the refs (for persistence)
+                // TODO : Improve the mgmt of FileNameRef vs actual File at the use case level
+                // I think we need to introduce another value, something like `setValueSerialized` or similar.
                 field.setValue(UCInputFieldChangeOperator.SET, fileNameRefs);
             }
             else {
@@ -54,12 +57,15 @@ let UCInputFilesProcessor = class UCInputFilesProcessor {
         }
     }
     async processFile(file) {
-        const extension = this.fsManager.fileExtension(file.name);
+        const extension = this.fsManager.fileExtension(file.name); // => jpg
         const prefix = this.clockManager.nowToKey();
-        const fileName = `${prefix}-${this.cryptoManager.randomUUID()}.${extension}`;
-        const fileNameRef = `${this.s().uc_file_ref_prefix}${fileName}`;
+        const fileName = `${prefix}-${this.cryptoManager.randomUUID()}.${extension}`; // => 20230110143732-155eb8d3-9af5-430e-b856-248007859df1.jpg
+        const fileNameRef = `${this.s().uc_file_ref_prefix}${fileName}`; // => $ref:20230110143732-155eb8d3-9af5-430e-b856-248007859df1.jpg
+        // When calling this client side, we still have a https://developer.mozilla.org/en-US/docs/Web/API/File
+        // Consider moving this logic to UCManager.execClient ?
+        // TODO : Improve client/server input files management
         const path = file instanceof File ? file.name : file.path;
-        await this.fsManager.cp(path, this.fsManager.path(this.s().uc_files_directory_path, fileName));
+        await this.fsManager.cp(path, this.fsManager.path(this.s().uc_files_directory_path, fileName)); // => /path/to/files/20230110143732-155eb8d3-9af5-430e-b856-248007859df1.jpg
         await this.fsManager.rm(path);
         return fileNameRef;
     }

package/dist/esm/uc/workers/UCOutputFilesProcessor.js

@@ -36,8 +36,12 @@ let UCOutputFilesProcessor = class UCOutputFilesProcessor {
         output.filePaths = await Promise.all(fileNameRefs.map(async (fileNameRef) => {
             let filePath;
             if (typeof fileNameRef === 'string') {
-                const fileName = fileNameRef.replace(this.s().uc_file_ref_prefix, '');
-                filePath = this.fsManager.path(this.s().uc_files_directory_path, fileName);
+                // If they have been processed by UCInputFilesProcessor, the refs are not actual File.
+                // They are string like '$ref:20230110143732-155eb8d3-9af5-430e-b856-248007859df1.jpg'.
+                // Hence this workaround.
+                // TODO : Find a better way to process output files
+                const fileName = fileNameRef.replace(this.s().uc_file_ref_prefix, ''); // => 20230110143732-155eb8d3-9af5-430e-b856-248007859df1.jpg
+                filePath = this.fsManager.path(this.s().uc_files_directory_path, fileName); // => /path/to/files/20230110143732-155eb8d3-9af5-430e-b856-248007859df1.jpg
             }
             else {
                 filePath = fileNameRef.path;

package/dist/esm/utils/async/sleep.d.ts

@@ -1,2 +1,12 @@
 import type { UIntDuration } from '../../dt/index.js';
+/**
+ * Sleep during the specified duration
+ *
+ * NOTE : We are in an async world so do this only when necessary or when you want to "fake" time.
+ * Generally speaking, if something is fast, do not make it slower just for the sake of showing a fancy animation.
+ * Well... If it's a good one, maybe.
+ *
+ * @param durationInMs
+ * @returns
+ */
 export declare function sleep(durationInMs: UIntDuration): Promise<void>;

package/dist/esm/utils/async/sleep.js

@@ -1,3 +1,13 @@
+/**
+ * Sleep during the specified duration
+ *
+ * NOTE : We are in an async world so do this only when necessary or when you want to "fake" time.
+ * Generally speaking, if something is fast, do not make it slower just for the sake of showing a fancy animation.
+ * Well... If it's a good one, maybe.
+ *
+ * @param durationInMs
+ * @returns
+ */
 export function sleep(durationInMs) {
     return new Promise((resolve) => {
         setTimeout(() => {

package/dist/esm/utils/http/appendData.js

@@ -1,4 +1,8 @@
-export async function appendData(data, func) {
+export async function appendData(data, 
+// biome-ignore lint/suspicious/noExplicitAny: can be anything
+func) {
+    // Checking undefined and null because Object.keys(undefined|null) throws
+    // TypeError: Cannot convert undefined or null to object
     if (data === undefined || data === null) {
         return;
     }

package/dist/esm/utils/ioc/ContainerPrinter.js

@@ -18,6 +18,8 @@ let ContainerPrinter = class ContainerPrinter {
         this.logger = logger;
     }
     async exec({ container }) {
+        // See https://github.com/inversify/InversifyJS/issues/1584
+        // @ts-ignore
         const dictionary = container._bindingDictionary._map;
         const entries = [];
         const keys = [...dictionary.keys()].map(this.symToString);

package/dist/esm/utils/ioc/bindCommon.js

@@ -1,3 +1,4 @@
+// NOTE : Expose this only at a higher level, otherwise, if exposed in utils/index.js, it will create circular dependencies
 import { APP_NAME_PLACEHOLDER, PRODUCT_NAME_PLACEHOLDER, } from '../../convention.js';
 import { ConsoleLogger } from '../../std/impl/ConsoleLogger.js';
 import { FetchHTTPAPICallExecutor } from '../../std/impl/FetchHTTPAPICallExecutor.js';
@@ -25,12 +26,14 @@ export function bindCommon(container, settingsFunc) {
         ...commonSettings,
         ...settingsFunc?.(commonSettings),
     };
+    // product
     if (!container.isBound('ProductManifest')) {
         container.bind('ProductManifest').toConstantValue({
             appReg: [{ name: APP_NAME_PLACEHOLDER }],
             name: PRODUCT_NAME_PLACEHOLDER,
         });
     }
+    // std
     container.bind('ClockManager').to(StdDateClockManager);
     container
         .bind('FormDataBuilder')
@@ -56,6 +59,7 @@ export function bindCommon(container, settingsFunc) {
         .bind('ServerClientManager')
         .to(SettingsServerClientManager);
     container.bind('XMLManager').to(NoopXMLManager);
+    // uc
     bindProvider(container, 'UCInit');
     bindProvider(container, 'UCMain');
     bindProvider(container, 'UCPolicy');

package/dist/esm/utils/ioc/bindNodeCLI.js

@@ -1,7 +1,9 @@
 import { NodePromptManager } from '../../std/impl/NodePromptManager.js';
 import { PromptUCClientConfirmManager } from '../../uc/impl/PromptUCClientConfirmManager.js';
 export function bindNodeCLI(container) {
+    // std
     container.bind('PromptManager').to(NodePromptManager);
+    // uc
     container
         .rebind('UCClientConfirmManager')
         .to(PromptUCClientConfirmManager);

package/dist/esm/utils/ioc/bindNodeCore.js

@@ -4,6 +4,7 @@ import { NodeEnvironmentManager } from '../../std/impl/NodeEnvironmentManager.js
 import { NodeFSManager } from '../../std/impl/NodeFSManager.js';
 import { NodeFormDataBuilder } from '../../std/impl/NodeFormDataBuilder.js';
 export function bindNodeCore(container) {
+    // std
     container.bind('BufferManager').to(NodeBufferManager);
     container.bind('CryptoManager').to(NodeCryptoManager);
     container

package/dist/esm/utils/ioc/bindProduct.js

@@ -1,4 +1,6 @@
 export function bindProduct(container, productManifest, productI18n) {
+    // Using rebind because these are already bound by default in {@link bindCommon}.
+    // The goal is to make it easier to get started for a user.
     container.rebind('I18n').toConstantValue(productI18n);
     container
         .rebind('ProductManifest')

package/dist/esm/utils/ioc/bindRN.js

@@ -1,4 +1,5 @@
 import { BufferLibBufferManager } from '../../std/impl/BufferLibBufferManager.js';
 export function bindRN(container) {
+    // std
     container.bind('BufferManager').to(BufferLibBufferManager);
 }

package/dist/esm/utils/ioc/bindServer.js

@@ -2,6 +2,7 @@ import { JoseJWTManager } from '../../index.std-jwt-manager-jose.js';
 import { FakeEmailManager } from '../../std/impl/FakeEmailManager.js';
 import { FakeJobManager } from '../../std/impl/FakeJobManager.js';
 export function bindServer(container) {
+    // std
     container.bind('EmailManager').to(FakeEmailManager);
     container.bind('JWTManager').to(JoseJWTManager);
     container.bind('JobManager').to(FakeJobManager);

package/dist/esm/utils/ioc/bindWeb.js

@@ -3,9 +3,11 @@ import { WebCryptoManager } from '../../std/impl/WebCryptoManager.js';
 import { WebFSManager } from '../../std/impl/WebFSManager.js';
 import { WebUCClientConfirmManager } from '../../uc/impl/WebUCClientConfirmManager.js';
 export function bindWeb(container) {
+    // std
     container.bind('BufferManager').to(BufferLibBufferManager);
     container.bind('CryptoManager').to(WebCryptoManager);
     container.bind('FSManager').to(WebFSManager);
+    // uc
     container
         .rebind('UCClientConfirmManager')
         .to(WebUCClientConfirmManager);

package/dist/esm/utils/ioc/container.js

@@ -1,3 +1,9 @@
 export const CONTAINER_OPTS = {
+    /**
+     * Allows us to avoid binding concrete classes
+     *
+     * @see https://github.com/inversify/InversifyJS/issues/1302
+     * @see https://github.com/inversify/InversifyJS/blob/master/wiki/container_api.md#autobindinjectable
+     */
     autoBindInjectable: true,
 };

package/dist/esm/utils/numbers/units.js

@@ -1,3 +1,6 @@
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+// https://unicode.org/reports/tr35/tr35-general.html#Unit_Elements
+// https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers
 const CORE_UNITS = [
     'acre',
     'bit',

package/dist/esm/utils/types/funcs.d.ts

@@ -1,6 +1,41 @@
 import type { NumIndex, UIntQuantity } from '../../dt/index.js';
+/**
+ * Assert that the value is defined
+ * @param value
+ * @param key
+ * @see isBlank
+ */
 export declare function assertIsDefined<T>(value: T, key: string): asserts value is NonNullable<T>;
+/**
+ * Checker whether the value is blank or not
+ *
+ * Blank means `undefined`, `null`, `''` (if string), `[]` (if array).
+ *
+ * This is insipred by Ruby's `blank?` method.
+ *
+ * @param value
+ * @returns
+ */
 export declare function isBlank<T>(value: T | T[] | undefined | null): value is undefined | null;
+/**
+ * Get an array filled with `[0 .. n-1]`
+ * @param n
+ * @returns
+ */
 export declare function range(n: UIntQuantity): NumIndex[];
+/**
+ * Get a random item from the array
+ *
+ * Although the name is inspired by Ruby's, the signature and implementation is not exactly the same (for now).
+ *
+ * @param items
+ * @returns
+ */
 export declare function sample<T>(items: T[]): T | null;
+/**
+ * Get an array of size `n` filled with `val`
+ * @param val
+ * @param n
+ * @returns
+ */
 export declare function tupleOf<T>(val: T, n: UIntQuantity): T[];

package/dist/esm/utils/types/funcs.js

@@ -1,15 +1,36 @@
 import { IllegalArgumentError } from '../../error/index.js';
+/**
+ * Assert that the value is defined
+ * @param value
+ * @param key
+ * @see isBlank
+ */
 export function assertIsDefined(value, key) {
     if (isBlank(value)) {
         throw new IllegalArgumentError(`${key} is required`);
     }
 }
+/**
+ * Checker whether the value is blank or not
+ *
+ * Blank means `undefined`, `null`, `''` (if string), `[]` (if array).
+ *
+ * This is insipred by Ruby's `blank?` method.
+ *
+ * @param value
+ * @returns
+ */
 export function isBlank(value) {
     return (value === undefined ||
         value === null ||
         (typeof value === 'string' && value.trim().length === 0) ||
         (Array.isArray(value) && value.length === 0));
 }
+/**
+ * Get an array filled with `[0 .. n-1]`
+ * @param n
+ * @returns
+ */
 export function range(n) {
     const items = [];
     for (let i = 0; i < n; i++) {
@@ -17,12 +38,26 @@ export function range(n) {
     }
     return items;
 }
+/**
+ * Get a random item from the array
+ *
+ * Although the name is inspired by Ruby's, the signature and implementation is not exactly the same (for now).
+ *
+ * @param items
+ * @returns
+ */
 export function sample(items) {
     if (items.length === 0) {
         return null;
     }
     return items[Math.floor(Math.random() * items.length)] ?? null;
 }
+/**
+ * Get an array of size `n` filled with `val`
+ * @param val
+ * @param n
+ * @returns
+ */
 export function tupleOf(val, n) {
     const items = [];
     for (let i = 0; i < n; i++) {

package/dist/esm/utils/types/utility-types.d.ts

@@ -1,5 +1,22 @@
+/**
+ * Extract a subset of a union type in a strict manner
+ *
+ * @example
+ *
+ * ```
+ * type Color = 'red' | 'orange' | 'green';
+ * type PassColor = Extract<Color, 'green' | 'toto'>; // Does not trigger any error
+ * type PassColor = ExtractStrict<Color, 'green' | 'toto'>; // Type '"green" | "toto"' does not satisfy the constraint 'Color'. Type '"toto"' is not assignable to type 'Color'.
+ * ```
+ */
 export type ExtractStrict<T, U extends T> = Extract<T, U>;
+/**
+ * Get a type corresponding to T with all the properties `NonNullable`, recursively
+ */
 export type RecursiveNonNullable<T> = {
     [K in keyof T]-?: RecursiveNonNullable<NonNullable<T[K]>>;
 };
+/**
+ * Extract the string keys of T
+ */
 export type StringKeys<T extends object> = Extract<keyof T, string>;

package/dist/esm/utils/types/utility-types.js

@@ -1 +1,2 @@
+// Some Utility Types that are not provided by TypeScript out of the box
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "libmodulor",
     "description": "An opinionated TypeScript library to create business oriented applications",
-    "version": "0.4.0",
+    "version": "0.6.0",
     "license": "LGPL-3.0",
     "author": "Chafik H'nini <chafik.hnini@gmail.com>",
     "homepage": "https://github.com/c100k/libmodulor#readme",
@@ -13,9 +13,6 @@
         ".": {
             "import": "./dist/esm/index.js"
         },
-        "./helper": {
-            "import": "./dist/products/Helper/index.js"
-        },
         "./locales/en": {
             "import": "./dist/esm/i18n/locales/en.js"
         },
@@ -56,9 +53,10 @@
             "import": "./dist/esm/index.web.js"
         }
     },
+    "bin": "./dist/esm/products/Helper/index.js",
     "peerDependencies": {
-        "@hono/node-server": "^1.13.7",
-        "@modelcontextprotocol/sdk": "^1.4.1",
+        "@hono/node-server": "^1.13.8",
+        "@modelcontextprotocol/sdk": "^1.6.0",
         "@stricli/core": "^1.1.1",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
@@ -66,18 +64,19 @@
         "express-fileupload": "^1.5.1",
         "fast-check": "^3.23.2",
         "helmet": "^8.0.0",
-        "hono": "^4.6.19",
-        "inversify": "^6.2.1",
-        "jose": "^5.9.6",
+        "hono": "^4.7.2",
+        "inversify": "^6.2.2",
+        "jose": "^6.0.8",
         "knex": "^3.1.0",
-        "pg": "^8.13.1",
-        "react": "^18.3.1",
-        "react-dom": "^18.3.1",
-        "react-native": "^0.76.6",
+        "pg": "^8.13.3",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "react-native": "^0.78.0",
         "reflect-metadata": "^0.2.2",
         "sqlite3": "^5.1.7",
         "typescript": "^5.7.3",
-        "vite": "^6.0.11"
+        "vite": "^6.2.0",
+        "vitest": "^3.0.7"
     },
     "peerDependenciesMeta": {
         "@hono/node-server": {