libmodulor 0.4.0 → 0.6.0

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

@@ -1,10 +1,25 @@
 import type { Validation } from '../Validation.js';
 import { TBase, type TName } from './TBase.js';
 export declare enum TObjectShapeValidationStrategy {
+    /**
+     * No shape validation is performed
+     *
+     * To be used when the object can have multiple shapes or that its shape is not important.
+     *
+     * Otherwise, you can still override {@link validate} in the `T*` class and do your own validation.
+     */
     NONE = "NONE",
+    /**
+     * Validate against the {@link TObject.example()}
+     *
+     * It checks that the keys of the value, sorted alphabetically, are the same as the example's keys.
+     */
     SAME_AS_EXAMPLE = "SAME_AS_EXAMPLE"
 }
 export interface TObjectConstraints {
+    /**
+     * @defaultValue {@link TObjectShapeValidationStrategy.SAME_AS_EXAMPLE}
+     */
     shapeValidationStrategy: TObjectShapeValidationStrategy;
 }
 export declare class TObject<T extends object> extends TBase<T> {

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

@@ -1,7 +1,19 @@
 import { TBase } from './TBase.js';
 export var TObjectShapeValidationStrategy;
 (function (TObjectShapeValidationStrategy) {
+    /**
+     * No shape validation is performed
+     *
+     * To be used when the object can have multiple shapes or that its shape is not important.
+     *
+     * Otherwise, you can still override {@link validate} in the `T*` class and do your own validation.
+     */
     TObjectShapeValidationStrategy["NONE"] = "NONE";
+    /**
+     * Validate against the {@link TObject.example()}
+     *
+     * It checks that the keys of the value, sorted alphabetically, are the same as the example's keys.
+     */
     TObjectShapeValidationStrategy["SAME_AS_EXAMPLE"] = "SAME_AS_EXAMPLE";
 })(TObjectShapeValidationStrategy || (TObjectShapeValidationStrategy = {}));
 export class TObject extends TBase {
@@ -19,6 +31,7 @@ export class TObject extends TBase {
         return {};
     }
     fmt(ifNullOrUndefined) {
+        // typeof this.raw is 'object', hence the check for nullity
         if (this.raw === null || typeof this.raw !== 'object') {
             return super.fmt(ifNullOrUndefined);
         }
@@ -26,6 +39,7 @@ export class TObject extends TBase {
     }
     validate() {
         const validation = super.validate();
+        // typeof this.raw is 'object', hence the check for nullity
         if (this.raw === null || typeof this.raw !== 'object') {
             validation.add({
                 constraint: 'type',

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

@@ -1,7 +1,7 @@
 import { TBase } from './TBase.js';
 export class TString extends TBase {
     constraints;
-    static DEFAULT_MAX_LENGTH = 999_999;
+    static DEFAULT_MAX_LENGTH = 999_999; // This is totally arbitrary and will probably be changed
     static DEFAULT_MIN_LENGTH = 0;
     constructor(constraints) {
         super();

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

@@ -1,4 +1,5 @@
 import { TNumber } from '../base/TNumber.js';
+// NOTE : We accept negative values (used for example in accounting)
 export class TAmount extends TNumber {
     currencyCode;
     constructor(currencyCode, constraints, decimalsCount) {

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

@@ -1,5 +1,6 @@
 import { TString } from '../base/TString.js';
 export class TCountryISO3166Alpha2 extends TString {
+    // From https://www.iban.com/country-codes
     static OPTIONS = [
         ['Afghanistan', 'AF'],
         ['Albania', 'AL'],

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

@@ -1,5 +1,6 @@
 import { TString } from '../base/TString.js';
 export class TCurrencyISO4217 extends TString {
+    // From https://www.iban.com/currency-codes
     static OPTIONS = [
         ['Euro', 'EUR', '€'],
         ['Pound Sterling', 'GBP', '£'],

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

@@ -1,4 +1,5 @@
 import { TString } from '../base/TString.js';
+// TODO : Validate this model with some simple heuristics. Do not make it too complicated, it's not really worth it.
 export class TDateTimeFormat extends TString {
     tName() {
         return 'DateTimeFormat';

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

@@ -1,5 +1,7 @@
 import { TString } from '../base/TString.js';
 export class TEmail extends TString {
+    // Inspired by https://github.com/jquense/yup/blob/master/src/string.ts#L19
+    // Which is inspired by https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address
     static FORMAT = /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
     constructor(constraints) {
         super({

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

@@ -1,4 +1,8 @@
 import { TString } from '../base/TString.js';
+// It is too difficult to validate safely an emoji
+// See : https://stackoverflow.com/questions/18862256/how-to-detect-emoji-using-javascript
+// Plus it does not bring much
+// At first, I used maxLength/minLength == 1 but it was naive. Composite ones' length is greater than 1.
 export class TEmoji extends TString {
     tName() {
         return 'Emoji';

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

@@ -6,6 +6,8 @@ export class TFile extends TObject {
     fileConstraints;
     constructor(fileConstraints) {
         super({
+            // We usually process instances of https://developer.mozilla.org/fr/docs/Web/API/File
+            // Therefore, it's not strictly the same as the example, with some extra fields that we don't control.
             shapeValidationStrategy: TObjectShapeValidationStrategy.NONE,
         });
         this.fileConstraints = fileConstraints;
@@ -36,6 +38,7 @@ export class TFile extends TObject {
         validation.concat(new TFileMimeType(this.fileConstraints.type)
             .assign(val.type)
             .validate());
+        // TODO : Add validation on file size
         return validation;
     }
 }

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

@@ -1,4 +1,6 @@
 import { TString } from '../base/TString.js';
+// TODO : Validate using IPv4, DomainName, etc. rules
+// But watch out, hostname can be as simple as "localhost" as well
 export class THostAddress extends TString {
     tName() {
         return 'HostAddress';

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

@@ -1,5 +1,6 @@
 import { TString } from '../base/TString.js';
 export class TIPv6 extends TString {
+    // Inspired by https://community.fortra.com/forums/intermapper/miscellaneous-topics/5acc4fcf-fa83-e511-80cf-0050568460e4?_ga=2.113564423.1432958022.1523882681-2146416484.1523557976
     static FORMAT = /^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$/;
     constructor(constraints) {
         super({

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

@@ -23,12 +23,20 @@ export class TJWT extends TString {
                 });
             }
             const [header, payload, _signature] = parts;
+            // Using atob on Node.js platforms triggers the following deprecation message :
+            //
+            // This function is only provided for compatibility with legacy web platform APIs and should never be used in new code,
+            // because they use strings to represent binary data and predate the introduction of typed arrays in JavaScript.
+            // For code running using Node.js APIs, converting between base64-encoded strings and binary data should be performed using Buffer.from(str, 'base64') andbuf.toString('base64').
+            //
+            // However this code must be executable everywhere (including and especially browsers) so we need to use it, for portability reasons
             if (header) {
                 JSON.parse(atob(header));
             }
             if (payload) {
                 JSON.parse(atob(payload));
             }
+            // signature is ignored for now
         }
         catch (err) {
             validation.add({

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

@@ -1,4 +1,6 @@
 import { TNumber } from '../base/TNumber.js';
+// TODO : Add some constraints (e.g. between 0 and 1, etc.)
+// Not forgetting that a percentage can be higher hein ! 1.25 is a valid value for 125% !
 export class TPercentage extends TNumber {
     constructor(constraints, decimalsCount) {
         super(constraints, decimalsCount, 'percent');
@@ -13,6 +15,9 @@ export class TPercentage extends TNumber {
         if (typeof this.raw !== 'number') {
             return super.fmt(ifNullOrUndefined);
         }
+        // Although it works on web, using fmtNumber and setting the unit to 'percent' does not work on React Native (Hermes)
+        // Instead of displaying '89%', it displays '89 percent'
+        // Hence the usage here of style: 'percent' directly
         return new Intl.NumberFormat(undefined, {
             maximumFractionDigits: this.decimalsCount,
             style: 'percent',

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

@@ -1,4 +1,5 @@
 import { TString } from '../base/TString.js';
+// TODO : Add basic syntax validation (without adding any dependencies)
 export class TSQLQuery extends TString {
     tName() {
         return 'SQLQuery';

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

@@ -1,7 +1,9 @@
 import { TString } from '../base/TString.js';
 export const SSHPrivatekKeyTypes = ['OPENSSH', 'RSA'];
 export class TSSHPrivateKey extends TString {
-    static FORMAT = /^-----BEGIN (OPENSSH|RSA) PRIVATE KEY-----\n(.+)?\n-----END (OPENSSH|RSA) PRIVATE KEY-----$/is;
+    static FORMAT = 
+    // @ts-ignore
+    /^-----BEGIN (OPENSSH|RSA) PRIVATE KEY-----\n(.+)?\n-----END (OPENSSH|RSA) PRIVATE KEY-----$/is;
     constructor(constraints) {
         super({
             ...constraints,

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

@@ -1,4 +1,5 @@
 import { TString } from '../base/TString.js';
+// TODO : Add basic syntax validation (without adding any dependencies)
 export class TSemVerVersion extends TString {
     static FORMAT = /^([0-9]+)\.([0-9]+)\.([0-9]+)$/;
     constructor(constraints) {

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

@@ -1,4 +1,5 @@
 import { TString } from '../base/TString.js';
+// TODO : Add basic syntax validation (without adding any dependencies)
 export class TShellCommand extends TString {
     tName() {
         return 'ShellCommand';

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

@@ -1,5 +1,6 @@
 import { TString } from '../base/TString.js';
 export class TURL extends TString {
+    // Inspired by https://github.com/jquense/yup/blob/master/src/string.ts#L24
     static FORMAT = /^((https?|ftp):)?\/\/(((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:)*@)?(((\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5]))|((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?)(:\d*)?)(\/((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)+(\/(([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)*)*)?)?(\?((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|[\uE000-\uF8FF]|\/|\?)*)?(\#((([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|\/|\?)*)?$/i;
     constructor(constraints) {
         super({
@@ -20,6 +21,7 @@ export class TURL extends TString {
         return 'url';
     }
     validate() {
+        // Workaround for https://github.com/jquense/yup/issues/224
         if (this.isLocalhost()) {
             this.removeFormatConstraint();
         }

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

@@ -1,5 +1,6 @@
 import { TString } from '../base/TString.js';
 export class TUUID extends TString {
+    // Inspired by https://github.com/jquense/yup/blob/master/src/string.ts#L29
     static FORMAT = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i;
     constructor(constraints) {
         super({

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

@@ -15,6 +15,6 @@ export class TYesNo extends TString {
         return 'YesNo';
     }
     example() {
-        return 'Y';
+        return 'Y'; // Yes Man !
     }
 }

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

@@ -4,7 +4,7 @@ export { TInt, type TIntConstraints } from './base/TInt.js';
 export { TNumber, type TNumberConstraints } from './base/TNumber.js';
 export { TObject, type TObjectConstraints, TObjectShapeValidationStrategy, } from './base/TObject.js';
 export { TString, type TStringConstraints } from './base/TString.js';
-export { TUInt, type TUIntConstraints } from './base/TUInt.js';
+export { TUInt, type TUIntConstraints, type UInt } from './base/TUInt.js';
 export { type Address, TAddress } from './final/TAddress.js';
 export { type Amount, TAmount } from './final/TAmount.js';
 export { type ApiKey, TApiKey } from './final/TApiKey.js';

package/dist/esm/i18n/WordingManager.d.ts

@@ -2,6 +2,22 @@ import type { DataType, TBase, TName } from '../dt/index.js';
 import type { ProductWording } from '../product/index.js';
 import type { I18nManager } from '../std/index.js';
 import type { UCClientConfirmConfig, UCDef, UCExecState, UCFieldKey, UCInput, UCInputField, UCName, UCOPIBase, UCOutputPartIdx, UCOutputPartWording, UCWording } from '../uc/index.js';
+/**
+ * A key to translate
+ *
+ *   - uc_CreateX_desc, uc_CreateX_label
+ *   - ucif_name_desc, uc_name_label, uc_isEnabled_desc, uc_isEnabled_label
+ *
+ * NOTE : The choice has been made to consider the input fields as "global".
+ * Which means, their key is not prefixed by the use case name (e.g. ucif_CreateX_ucif_name_desc).
+ * This has multiple advantages :
+ *
+ *   - The same field present in multiple use cases will be automatically translated
+ *   - It gives more consistency through the app with the same thing always named the same way
+ *
+ * One might argue that a label can be different for "name" in "CreateX" and "CreateY".
+ * In this case, we consider that the input field shouldn't be named "name" in both places.
+ */
 export type WordingManagerKey = `dt_${TName}_${string}_${keyof UCWording}` | `p_${keyof ProductWording}` | `uc_${UCName}_${keyof UCWording}` | `uc_${UCName}_client_confirm_${keyof UCClientConfirmConfig}` | `uc_${UCName}_i_submit_${UCExecState}` | `uc_${UCName}_op_${UCOutputPartIdx}_${keyof UCOutputPartWording}` | `ucif_${UCFieldKey}_${keyof UCWording}` | `ucof_${UCFieldKey}_${keyof UCWording}`;
 export declare class WordingManager {
     private i18nManager;

package/dist/esm/i18n/types.d.ts

@@ -1,6 +1,11 @@
 import type { ViolationI18nable, YesNo } from '../dt/index.js';
 import type { UCClientConfirmConfig, UCExecState, UCWording } from '../uc/index.js';
 export type I18nLanguageCode = 'en' | 'fr';
+/**
+ * A translation value
+ *
+ * It can contain `{{placeholders}}`.
+ */
 export type I18nTranslation = string;
 export type I18nTranslationKey = string;
 export type I18nCoreKey = ViolationI18nable | `dt_YesNo_${YesNo}_${keyof UCWording}` | `uc_client_confirm_${keyof UCClientConfirmConfig}` | `uc_i_submit_${UCExecState}`;

package/dist/esm/icon/Icon.d.ts

@@ -1 +1,8 @@
+/**
+ * The icon code (e.g. https://fontawesome.com/v6/search?o=s&m=free)
+ *
+ * There are thousands of them so we voluntarily keep it a simple string and not a union type that would become unmaintainable.
+ *
+ * You can naturally use a different icon library as long as the renderer handles it.
+ */
 export type IconCode = string;

package/dist/esm/index.d.ts

@@ -11,8 +11,11 @@ export * from './std/impl/FakeFSManager.js';
 export * from './std/impl/FakeHTTPAPICallExecutor.js';
 export * from './std/impl/FakeJobManager.js';
 export * from './std/impl/FetchHTTPAPICallExecutor.js';
+export * from './std/impl/MistralAILLMManager.js';
 export * from './std/impl/NoopHTTPAPICallExecutorAgentBuilder.js';
 export * from './std/impl/NoopXMLManager.js';
+export * from './std/impl/OllamaLLMManager.js';
+export * from './std/impl/OpenAILLMManager.js';
 export * from './std/impl/SettingsServerClientManager.js';
 export * from './std/impl/SimpleFormDataBuilder.js';
 export * from './std/impl/SimpleHTTPAPICaller.js';

package/dist/esm/index.js

@@ -1,3 +1,4 @@
+// Export only the implementations that have no external dependencies (Otherwise, export them in index.x.ts)
 export * from './app/index.js';
 export * from './dt/index.js';
 export * from './error/index.js';
@@ -11,8 +12,11 @@ export * from './std/impl/FakeFSManager.js';
 export * from './std/impl/FakeHTTPAPICallExecutor.js';
 export * from './std/impl/FakeJobManager.js';
 export * from './std/impl/FetchHTTPAPICallExecutor.js';
+export * from './std/impl/MistralAILLMManager.js';
 export * from './std/impl/NoopHTTPAPICallExecutorAgentBuilder.js';
 export * from './std/impl/NoopXMLManager.js';
+export * from './std/impl/OllamaLLMManager.js';
+export * from './std/impl/OpenAILLMManager.js';
 export * from './std/impl/SettingsServerClientManager.js';
 export * from './std/impl/SimpleFormDataBuilder.js';
 export * from './std/impl/SimpleHTTPAPICaller.js';

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

@@ -6,6 +6,7 @@ export { NodeFormDataBuilder } from './std/impl/NodeFormDataBuilder.js';
 export { NodeFSManager } from './std/impl/NodeFSManager.js';
 export { NodeHTTPAPICallExecutorAgentBuilder } from './std/impl/NodeHTTPAPICallExecutorAgentBuilder.js';
 export { NodePromptManager } from './std/impl/NodePromptManager.js';
+export { NodeSpawnShellCommandExecutor } from './std/impl/NodeSpawnShellCommandExecutor.js';
 export { NodeCoreCLIManager } from './target/node-core-cli/NodeCoreCLIManager.js';
 export { NodeExpressServerManager } from './target/node-express-server/NodeExpressServerManager.js';
 export { bindNodeCLI } from './utils/ioc/bindNodeCLI.js';

package/dist/esm/index.node.js

@@ -6,6 +6,7 @@ export { NodeFormDataBuilder } from './std/impl/NodeFormDataBuilder.js';
 export { NodeFSManager } from './std/impl/NodeFSManager.js';
 export { NodeHTTPAPICallExecutorAgentBuilder } from './std/impl/NodeHTTPAPICallExecutorAgentBuilder.js';
 export { NodePromptManager } from './std/impl/NodePromptManager.js';
+export { NodeSpawnShellCommandExecutor } from './std/impl/NodeSpawnShellCommandExecutor.js';
 export { NodeCoreCLIManager } from './target/node-core-cli/NodeCoreCLIManager.js';
 export { NodeExpressServerManager } from './target/node-express-server/NodeExpressServerManager.js';
 export { bindNodeCLI } from './utils/ioc/bindNodeCLI.js';

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

@@ -1,5 +1,5 @@
 export { DIContext, useDIContext, DIContextProvider, type DIContextT, } from './target/lib/react/DIContextProvider.js';
-export type { UCFormFieldControlOnChange, UCFormProps, RenderUCForm, } from './target/lib/react/form.js';
+export type { UCFormFieldControlOnChange, UCFormFieldControlProps, UCFormFieldDescProps, UCFormFieldElement, UCFormFieldErrProps, UCFormFieldLabelProps, UCFormFieldProps, UCFormProps, UCFormSubmitControlProps, UC_FORM_FIELD_ELEMENTS, RenderUCForm, validateFormField, } from './target/lib/react/form.js';
 export type { UCPanelCtx, UCPanelOnDone, UCPanelOnError, UCPanelOnInit, UCPanelOnStartSubmitting, UCPanelOnSubmit, UCPanelState, } from './target/lib/react/panel.js';
 export type { UCEntrypointTouchableProps, RenderUCEntrypointTouchable, RenderUCExecTouchable, UCExecTouchableProps, } from './target/lib/react/touchable.js';
 export { UCContainer } from './target/lib/react/UCContainer.js';

package/dist/esm/product/manifest.d.ts

@@ -1,8 +1,23 @@
 import type { AppName } from '../app/index.js';
 import type { UCName } from '../uc/index.js';
 export interface ProductAppReg {
+    /**
+     * It must correspond to the app folder name in the {@link APPS_ROOT_PATH}.
+     */
     name: AppName;
+    /**
+     * By default, a product mounts all the enabled use cases of an app.
+     *
+     * With this, you can override this default behavior.
+     */
     ucds?: {
+        /**
+         * Use Cases to exclude from the product
+         *
+         * For example, you can have a generic `Auth` app, used in multiple products.
+         * Some of them will require `SignUp` while others won't. With this setting,
+         * you can exclude the use cases that you don't want. In this case, they won't be mounted.
+         */
         exclude?: UCName[];
     } | undefined;
 }

package/dist/esm/products/Helper/container.js

@@ -1,4 +1,5 @@
 import { Container } from 'inversify';
+import { NodeSpawnShellCommandExecutor } from '../../std/impl/NodeSpawnShellCommandExecutor.js';
 import { VitestAppTestSuiteEmitter } from '../../testing/impl/VitestAppTestSuiteEmitter.js';
 import { VitestAppTestSuiteRunner } from '../../testing/impl/VitestAppTestSuiteRunner.js';
 import { CONTAINER_OPTS } from '../../utils/index.js';
@@ -19,4 +20,7 @@ container
 container
     .bind('AppTestSuiteRunner')
     .to(VitestAppTestSuiteRunner);
+container
+    .bind('ShellCommandExecutor')
+    .to(NodeSpawnShellCommandExecutor);
 export default container;

package/dist/esm/products/Helper/index.js

@@ -1,8 +1,13 @@
+#!/usr/bin/env node
+
 import { APPS_ROOT_DIR_NAME } from '../../convention.js';
 import { NodeCoreCLIManager } from '../../target/node-core-cli/NodeCoreCLIManager.js';
 import container from './container.js';
 const i18nManager = container.get('I18nManager');
 await i18nManager.init();
+// Before screaming, yes, this is not using any powerful CLI library.
+// The goal is to reduce the usage of dependencies as much as possible.
+// As long as the built-in Node.js API allows to build it without too many workarounds, let's keep it this way.
 await container.resolve(NodeCoreCLIManager).handleCommand({
     appsRootPath: container
         .get('FSManager')

package/dist/esm/products/Helper/manifest.d.ts

@@ -1 +1,6 @@
-export const Manifest: import("../../product/index.js").ProductManifest;
+export declare const Manifest: {
+    appReg: {
+        name: "Helper";
+    }[];
+    name: string;
+};

package/dist/esm/std/BufferManager.d.ts

@@ -1,4 +1,22 @@
 export type BufferManagerBase64String = string;
+/**
+ * The `Buffer` api is available in Node and similar server side environments. But it's not in browsers.
+ *
+ * Hence the need for this interface to provide multiple implementations (e.g. using https://github.com/feross/buffer).
+ *
+ * But the problem is that both implementations are redundant.
+ *
+ * TODO : Consider alternatives to BufferManager
+ *
+ * Possible solutions :
+ *
+ *   - Import the buffer lib as a polyfill
+ *   - Use only ECMAScript compatible primitives (`ArrayBuffer`, `Uint8Array`, `DataView`, etc.)
+ *   - Use BinaryJS
+ *   - Use Fast-Buffer
+ *
+ * Note that for the last two, keeping this interface makes actually sense since other impl. not `Buffer`-like can be used.
+ */
 export interface BufferManager {
     decodeBase64<T extends string>(value: BufferManagerBase64String): T;
     decodeUint8Array<T extends string>(value: Uint8Array): T;

package/dist/esm/std/ClockManager.d.ts

@@ -1,4 +1,9 @@
 import type { Timestamp } from '../dt/index.js';
+/**
+ * A key representing the date (e.g. 20241125141012)
+ *
+ * Useful to set a prefix when naming files in order to sort them
+ */
 export type ClockManagerDateKey = string;
 export interface ClockManager {
     now(): Date;

package/dist/esm/std/EnvironmentManager.d.ts

@@ -3,6 +3,16 @@ export type EnvironmentManagerEnvVarName = string;
 type Browser = 'chrome' | 'edge' | 'firefox' | 'opera' | 'safari';
 type MobileOS = 'android' | 'ios';
 type OS = 'darwin' | 'linux' | 'macos' | 'windows' | 'windows_nt';
+/**
+ * The type of environment
+ *
+ * The goal of this is not to give the final platform where the runtime is executed.
+ * For instance, in the context of a browser, we want to know that it's running on 'firefox' and not 'macos'.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/platform
+ * @see https://reactnative.dev/docs/platform#os
+ * @see https://nodejs.org/api/os.html#ostype
+ */
 export type EnvironmentManagerType = Browser | MobileOS | OS | (string & {});
 export interface EnvironmentManager {
     cwd(): FilePath;

package/dist/esm/std/HTTPAPICaller.d.ts

@@ -18,6 +18,9 @@ export interface HTTPAPICallerInputOpts {
     xml?: XMLManagerParseOpts;
 }
 export interface HTTPAPICallerInput<AH extends object | undefined, Req extends object, ResBad, ResGood, O> {
+    /**
+     * They are the last ones to be set so they will override any other header already set by `authorizationHeader` or `basicAuth` if any.
+     */
     additionalHeadersBuilder?: AdditionalHeadersBuilder<AH> | undefined;
     authorizationHeader?: HTTPAPICallerAuthorizationHeader | undefined;
     basicAuth?: HTTPAPICallerBasicAuth | undefined;
@@ -25,6 +28,9 @@ export interface HTTPAPICallerInput<AH extends object | undefined, Req extends o
     errBuilder: ErrBuilder<ResBad>;
     method: HTTPMethod;
     opts?: HTTPAPICallerInputOpts | undefined;
+    /**
+     * If not set, it will assume that `ResGood` and `O` are the same and thus return `ResGood` as is.
+     */
     outputBuilder?: OutputBuilder<ResGood, O> | undefined;
     req?: {
         builder: ReqBuilder<Req>;

package/dist/esm/std/I18nManager.d.ts

@@ -7,8 +7,34 @@ export interface I18nManagerTOpts {
     vars?: Record<string, string>;
 }
 export interface I18nManager extends Initializable {
+    /**
+     * Add a translation key
+     *
+     * It might not work for all the implementations, depending on where the translations are stored.
+     *
+     * @param key
+     * @param value
+     */
     add<K extends I18nTranslationKey>(key: K, value: string): Promise<void>;
+    /**
+     * Get the current lang code
+     */
     l(): I18nLanguageCode;
+    /**
+     * Get the translation for the given key
+     *
+     * If the key is missing, it should return `opts.fallback` if any. Otherwise, it should return the key itself.
+     *
+     * Optionally it can fail (by throwing) but that is not recommended since it impacts end users.
+     *
+     * @param key
+     * @param opts
+     */
     t<T extends I18nTranslationKey>(key: T, opts?: I18nManagerTOpts): string;
+    /**
+     * Get the translation for the given key, otherwise `null`
+     * @param key
+     * @param opts
+     */
     tOrNull<T extends I18nTranslationKey>(key: T, opts?: I18nManagerTOpts): string | null;
 }

package/dist/esm/std/JWTManager.d.ts

@@ -16,6 +16,9 @@ export interface JWTManagerSettings extends Settings {
     jwt_manager_subject: string | null;
 }
 export type JWTManagerDecodeOpts = Pick<JWTManagerEncodeOpts, 'secret'> & {
+    /**
+     * The public key to verify JWTs using an `alg` of type `RS*`
+     */
     spki?: SSHPublicKey;
 };
 export interface JWTManagerEncodeOpts {
@@ -28,7 +31,30 @@ export interface JWTManagerEncodeOpts {
     sub?: JWTManagerSettings['jwt_manager_subject'];
 }
 export interface JWTManager {
+    /**
+     * Decode the token
+     *
+     * Pass the ad-hoc opts when using a specific `alg` (e.g. `spki` when decoding a `RS*` token).
+     * If invalid, it must throw an {@link UnauthorizedError} (no errors related to the impl. should be thrown).
+     *
+     * @param value
+     * @param opts
+     */
     decode<T extends JWTManagerPayload>(value: JWT, opts?: JWTManagerDecodeOpts): Promise<T>;
+    /**
+     * Encode the payload
+     *
+     * It uses the global {@link JWTManagerSettings} or the ones provided via `opts`.
+     *
+     * @param payload
+     * @param opts
+     */
     encode<T extends object>(payload: T, opts?: JWTManagerEncodeOpts): Promise<JWT>;
+    /**
+     * Check whether the token is usable or not
+     *
+     * Note that the signature is not checked. Indeed, the main purpose of this method is to be used client side to save some requests (e.g. when the token is expired).
+     * In this case, no need to send a request that will trigger an error. Better to renew the token at the client's initiative.
+     */
     isUsable(value: JWT): Promise<boolean>;
 }

package/dist/esm/std/JobManager.d.ts

@@ -13,5 +13,11 @@ export interface JobManagerSettings extends Settings {
     }[];
 }
 export interface JobManager extends Clearable, Initializable {
+    /**
+     * Send a new job on the queue for processing
+     * @param queueName
+     * @param jobName
+     * @param input
+     */
     dispatch<I>(queueName: JobManagerQueueName, jobName: JobManagerJobName, input: I): Promise<void>;
 }

package/dist/esm/std/LLMManager.d.ts

@@ -0,0 +1,25 @@
+import type { FreeTextLong } from '../dt/index.js';
+export type LLMManagerModel = string;
+export type LLMManagerTemperature = number;
+export interface LLMManagerSendReq {
+    messages: {
+        content: FreeTextLong;
+        /**
+         * In the case of OpenAI :
+         * > With o1 models and newer, developer messages replace the previous system messages
+         */
+        role: 'assistant' | 'developer' | 'system' | 'user';
+    }[];
+    model: LLMManagerModel;
+    temperature?: LLMManagerTemperature;
+}
+export interface LLMManagerSendRes {
+    choices: {
+        message: {
+            content: string;
+        };
+    }[];
+}
+export interface LLMManager {
+    send(req: LLMManagerSendReq): Promise<LLMManagerSendRes>;
+}