libmodulor 0.4.0 → 0.5.0

package/dist/esm/target/lib/server/RequestChecker.js

@@ -27,10 +27,10 @@ let RequestChecker = class RequestChecker {
         };
     }
     exec({ secure, url, xForwardedProtoHeader }) {
-        const isSecure = secure;
-        const isSecureForwarded = xForwardedProtoHeader === 'https';
-        const isNotProd = !this.environmentManager.isProd();
-        const isSSLCertificateCheck = !!url.match(/^\/\.well-known\/acme-challenge\/(.*)/);
+        const isSecure = secure; // https://localhost:8443
+        const isSecureForwarded = xForwardedProtoHeader === 'https'; // https://domain.com => http://localhost:8080
+        const isNotProd = !this.environmentManager.isProd(); // http://localhost:8443
+        const isSSLCertificateCheck = !!url.match(/^\/\.well-known\/acme-challenge\/(.*)/); // http://localhost:8443/.well-known/acme-challenge/ywml7k8e8qxdjwFf1pN4hIKWJ1Jrc0CvAP3t9PSmnzw
         this.logger.trace('Request checker', {
             isNotProd,
             isSSLCertificateCheck,
@@ -39,6 +39,7 @@ let RequestChecker = class RequestChecker {
         });
         const allowed = isSecure || isSecureForwarded || isNotProd || isSSLCertificateCheck;
         if (!allowed) {
+            // Not sure it's the right HTTP status to send in these cases but not a big deal for now
             throw new ForbiddenError();
         }
     }

package/dist/esm/target/lib/server/RequestHandler.d.ts

@@ -5,5 +5,10 @@ export interface RequestHandlerInputRaw<I extends UCInput | undefined = undefine
     appManifest: AppManifest;
     envelope: HTTPDataEnvelope;
     ucd: UCDef<I, OPI0, OPI1>;
+    /**
+     * It is not injected in the handler constructor because it must be the same as the one used in ServerManager.
+     *
+     * And in some cases, this latter is specific to a context : for instance in automated tests.
+     */
     ucManager: UCManager;
 }

package/dist/esm/target/lib/server/RequestLogger.js

@@ -20,6 +20,11 @@ let RequestLogger = class RequestLogger {
     }
     exec({ body, method, url }) {
         const prefix = [method, url].join(' ');
+        // By security, we don't log the body in production, in case it contains sensitive info (e.g. password when authenticating).
+        // That being said, in some cases, it can be handy to investigate issues.
+        // Let's think about it and how we can do it properly.
+        // One way is to this.logger.trace the body, considering it will never be the default in production since it produces too many logs.
+        // TODO : Consider logging request body even in production
         if (this.environmentManager.isProd()) {
             this.logger.debug(prefix);
             return;

package/dist/esm/target/lib/server/ServerManager.d.ts

@@ -31,9 +31,28 @@ export interface ServerManagerSettings extends ServerManagerAuthSettings, Settin
 }
 export interface ServerManager extends Initializable {
     overrideUCManager(ucManager: UCManager): void;
+    /**
+     * Mount the use case as an endpoint
+     * @param appManifest
+     * @param ucd
+     * @param contract
+     */
     mount<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(appManifest: AppManifest, ucd: UCDef<I, OPI0, OPI1>, contract: UCHTTPContract): Promise<void>;
+    /**
+     * Mount the static directory at `/`
+     * @param dirPath
+     */
     mountStaticDir(dirPath: DirPath): Promise<void>;
+    /**
+     * Start listening on the specific host and port
+     */
     start(): Promise<void>;
+    /**
+     * Stop listening
+     */
     stop(): Promise<void>;
+    /**
+     * Warm up with things that must be done after the routes have been defined (e.g. error middleware, etc.)
+     */
     warmUp(): Promise<void>;
 }

package/dist/esm/target/lib/server/consts.d.ts

@@ -1,2 +1,5 @@
 import type { ServerManagerSettings } from './ServerManager.js';
+/**
+ * @see TARGET_DEFAULT_SERVER_CLIENT_MANAGER_SETTINGS
+ */
 export declare const TARGET_DEFAULT_SERVER_MANAGER_SETTINGS: ServerManagerSettings;

package/dist/esm/target/lib/server/consts.js

@@ -1,3 +1,6 @@
+/**
+ * @see TARGET_DEFAULT_SERVER_CLIENT_MANAGER_SETTINGS
+ */
 export const TARGET_DEFAULT_SERVER_MANAGER_SETTINGS = {
     server_basic_auth_entries: {},
     server_binding_host: 'localhost',

package/dist/esm/target/lib/web/input.d.ts

@@ -1,9 +1,30 @@
 import { type DataType, type ErrorMessage, type HTMLInputType } from '../../../dt/index.js';
 import { type UCExecState, type UCInputField } from '../../../uc/index.js';
 export interface HTMLInputDef {
+    /**
+     * Internal types that are not part of the W3C spec
+     *
+     * @see node_modules/@types/react/index.d.ts#InputHTMLAttributes
+     */
     internal?: {
+        /**
+         * When a fiels is `multiline`, you should probably render a `<textarea />` in place of an `<input />`.
+         */
         multiline?: boolean | undefined;
     };
+    /**
+     * Fields that are part of the W3C spec
+     *
+     * These are safe to destructure directly in an `<input />` component.
+     *
+     * Note that they come with their camel case form, à la React.
+     * The reason is that it's easier to transform this to the original spec (`maxLength` => `maxlength`) vs doing the opposite (`maxlength` > `maxLength`).
+     * In the first case, we can simply call `.toLowerCase()` on the keys, while in the second, we'd need a dedicated function that "camel-cases" a string.
+     *
+     * @example `<input {...attrs.spec} />`
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
+     * @see node_modules/@types/react/index.d.ts `InputHTMLAttributes`
+     */
     spec?: {
         'aria-errormessage'?: string | undefined;
         'aria-invalid'?: boolean | undefined;

package/dist/esm/target/lib/web/input.js

@@ -6,6 +6,7 @@ export function htmlInputDef(field, execState, errMsg) {
         spec: {},
     };
     if (!def.internal || !def.spec) {
+        // Just a guard to safely type the rest of the function without using !
         return def;
     }
     const { key, def: fDef } = field;
@@ -13,11 +14,14 @@ export function htmlInputDef(field, execState, errMsg) {
     def.spec.disabled = ucIsDisabled(execState);
     def.spec.id = ucifId(key);
     def.spec.name = key;
+    // Testing the types by usage probability to make the if/else evaluation stop ideally earlier
     if (fType instanceof TString) {
         const constraints = fType.getConstraints();
         if (constraints) {
             def.spec.maxLength = constraints.maxLength;
             def.spec.minLength = constraints.minLength;
+            // https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern
+            // > No forward slashes should be specified around the pattern text
             def.spec.pattern = constraints.format?.regexp?.source;
         }
         def.internal.multiline = fType.isPotentiallyLong();

package/dist/esm/target/node-core-cli/NodeCoreCLIManager.js

@@ -57,7 +57,7 @@ let NodeCoreCLIManager = class NodeCoreCLIManager {
     }
     parseArgsConfig(uc) {
         const config = {
-            allowPositionals: true,
+            allowPositionals: true, // For the command name
             strict: true,
         };
         if (uc.inputFields.length === 0) {
@@ -68,7 +68,7 @@ let NodeCoreCLIManager = class NodeCoreCLIManager {
             const { def } = f;
             let defaultValue = def.type.getDefaultValue();
             if (typeof defaultValue === 'number') {
-                defaultValue = defaultValue.toString();
+                defaultValue = defaultValue.toString(); // parseArgs does not accept numbers as default value
             }
             const [isRepeatable, _max] = ucifRepeatability(def);
             const type = def.type instanceof TBoolean ? 'boolean' : 'string';

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

@@ -77,6 +77,8 @@ let NodeExpressServerManager = class NodeExpressServerManager {
     async init() {
         this.runtime = express();
         this.runtime.use(this.helmetMB.exec({}));
+        // TODO : Add FileStorageManager (Local, S3, FSBucket)
+        // Right now, the files are only stored locally. We need more flexibility. Maybe we can also install https://imgproxy.net.
         this.runtime.use(fileUpload({
             createParentPath: true,
             debug: this.s().logger_level === 'trace',
@@ -125,6 +127,8 @@ let NodeExpressServerManager = class NodeExpressServerManager {
         if (!this.server?.listening) {
             return;
         }
+        // As stated in the docs of `close`, only awaiting `.close` is not enough to make sure all the connections are closed.
+        // Hence the wrapping in a promise, where the callback is called when the 'close' event is emitted.
         return new Promise((resolve, reject) => {
             if (!this.server) {
                 return resolve();
@@ -138,6 +142,7 @@ let NodeExpressServerManager = class NodeExpressServerManager {
         });
     }
     async warmUp() {
+        // Always at the "almost" last position to handle all the errors (from other middlewares and request handlers)
         this.runtime.use(this.errorMB.exec({}));
     }
     async createServer() {

package/dist/esm/target/node-express-server/lib/AuthCookieCreator.js

@@ -35,7 +35,7 @@ let AuthCookieCreator = class AuthCookieCreator {
                 httpOnly: this.s().server_cookies_http_only,
                 sameSite: this.s().server_cookies_same_site,
                 secure: this.s().server_cookies_secure,
-                signed: false,
+                signed: false, // Not signing to keep it simple and btw, the JWT is already signed
             },
             val: jwt,
         };

package/dist/esm/target/node-express-server/middlewares/AuthenticationCheckerMiddlewareBuilder.js

@@ -51,6 +51,7 @@ let AuthenticationCheckerMiddlewareBuilder = class AuthenticationCheckerMiddlewa
                 nextFn();
             }
             catch (err) {
+                // Always catch otherwise it breaks the middleware chain and hangs forever
                 nextFn(err);
             }
         };

package/dist/esm/target/node-express-server/middlewares/PublicApiKeyCheckerMiddlewareBuilder.js

@@ -35,6 +35,7 @@ let PublicApiKeyCheckerMiddlewareBuilder = class PublicApiKeyCheckerMiddlewareBu
                 nextFn();
             }
             catch (err) {
+                // Always catch otherwise it breaks the middleware chain and hangs forever
                 nextFn(err);
             }
         };

package/dist/esm/target/node-express-server/middlewares/RequestCheckerMiddlewareBuilder.js

@@ -28,6 +28,7 @@ let RequestCheckerMiddlewareBuilder = class RequestCheckerMiddlewareBuilder {
                 nextFn();
             }
             catch (err) {
+                // Always catch otherwise it breaks the middleware chain and hangs forever
                 nextFn(err);
             }
         };

package/dist/esm/target/node-express-server/middlewares/RequestHandlerMiddlewareBuilder.js

@@ -49,6 +49,8 @@ let RequestHandlerMiddlewareBuilder = class RequestHandlerMiddlewareBuilder {
                     if (ucor.canItem00()) {
                         item = ucor.item00().item;
                     }
+                    // Be careful with this, as some are incompatible.
+                    // For instance, if there is a REDIRECT and then a CLEAR_AUTH, the latter won't be executed as we return after the redirect.
                     for (const se of sideEffects) {
                         const { type } = se;
                         switch (type) {
@@ -74,6 +76,7 @@ let RequestHandlerMiddlewareBuilder = class RequestHandlerMiddlewareBuilder {
                 res.send(output && transform ? transform(output) : output);
             }
             catch (err) {
+                // Always catch otherwise it breaks the middleware chain and hangs forever
                 nextFn(err);
             }
         };
@@ -82,6 +85,7 @@ let RequestHandlerMiddlewareBuilder = class RequestHandlerMiddlewareBuilder {
         switch (envelope) {
             case 'form-data': {
                 const input = req.body;
+                // files is present when using express-fileupload
                 if ('files' in req && req.files) {
                     for (const [field, value] of Object.entries(req.files)) {
                         input[field] = Array.isArray(value)
@@ -89,6 +93,8 @@ let RequestHandlerMiddlewareBuilder = class RequestHandlerMiddlewareBuilder {
                             : this.toFile(value);
                     }
                 }
+                // TODO : Change this ugly code
+                // When a field has multiple values, they key is `field[]` and not `field`
                 const sanitized = {};
                 for (const [k, v] of Object.entries(input)) {
                     const sanitizedKey = k.split('[')[0];
@@ -96,6 +102,8 @@ let RequestHandlerMiddlewareBuilder = class RequestHandlerMiddlewareBuilder {
                         continue;
                     }
                     sanitized[sanitizedKey] = v;
+                    // For some reason, when there is only one value, it is received as scalar and not as an array
+                    // Even if there is only one, we want an array
                     if (k.includes('[') && !Array.isArray(v)) {
                         sanitized[sanitizedKey] = [v];
                     }

package/dist/esm/target/node-express-server/middlewares/RequestLoggerMiddlewareBuilder.js

@@ -31,6 +31,7 @@ let RequestLoggerMiddlewareBuilder = class RequestLoggerMiddlewareBuilder {
             }
             catch (err) {
                 this.logger.error(err);
+                // Continue as usual : the user shouldn't be impacted if we have issues logging the requests
                 nextFn();
             }
         };

package/dist/esm/target/node-mcp-server/NodeLocalStdioMCPServerManager.d.ts

@@ -7,6 +7,16 @@ import type { Configurable, LoggerSettings, SettingsManager } from '../../std/in
 import { UCBuilder, type UCDef, type UCHTTPContract, type UCInput, type UCManager, type UCOPIBase } from '../../uc/index.js';
 import type { ServerManager } from '../lib/server/ServerManager.js';
 type S = Pick<LoggerSettings, 'logger_level'>;
+/**
+ * A simple MCP Server implementation
+ *
+ * Although it implements {@link ServerManager}, this implementation is not necessarily a "server".
+ * Indeed, it uses a local `Transport` so it must be considered the same as a {@link NodeCoreCLIManager}.
+ * Therefore, it calls `execClient` and not `execServer`.
+ * This way, Claude AI, or any other client is just a wrapper on top of it.
+ *
+ * @alpha This implementation still has lots of TODOs and has not been tested in real conditions. It needs to be stabilized before usage.
+ */
 export declare class NodeLocalStdioMCPServerManager implements Configurable<S>, ServerManager {
     private productManifest;
     private settingsManager;

package/dist/esm/target/node-mcp-server/NodeLocalStdioMCPServerManager.js

@@ -17,6 +17,16 @@ import { inject, injectable } from 'inversify';
 import { WordingManager } from '../../i18n/index.js';
 import { UCBuilder, ucMountingPoint, ucifIsMandatory, } from '../../uc/index.js';
 import { propertyType, resError, resObj } from './funcs.js';
+/**
+ * A simple MCP Server implementation
+ *
+ * Although it implements {@link ServerManager}, this implementation is not necessarily a "server".
+ * Indeed, it uses a local `Transport` so it must be considered the same as a {@link NodeCoreCLIManager}.
+ * Therefore, it calls `execClient` and not `execServer`.
+ * This way, Claude AI, or any other client is just a wrapper on top of it.
+ *
+ * @alpha This implementation still has lots of TODOs and has not been tested in real conditions. It needs to be stabilized before usage.
+ */
 let NodeLocalStdioMCPServerManager = class NodeLocalStdioMCPServerManager {
     productManifest;
     settingsManager;
@@ -55,6 +65,9 @@ let NodeLocalStdioMCPServerManager = class NodeLocalStdioMCPServerManager {
         });
         if (this.s().logger_level !== 'error') {
             const message = 'Set the logging_level to "error" as MCP does not want the server to log to stdout (see https://modelcontextprotocol.io/docs/tools/debugging#implementing-logging)';
+            // Depending on the `Logger` implementation, this.logger.error() might not write to stderr (e.g. can write to a file).
+            // That's why we explicitly write to stdout by calling console.error().
+            // biome-ignore lint/suspicious/noConsole: we want it
             console.error(new Error(message));
         }
     }
@@ -112,6 +125,7 @@ let NodeLocalStdioMCPServerManager = class NodeLocalStdioMCPServerManager {
     }
     async execRequest(request) {
         const { name, arguments: args } = request.params;
+        // TODO : Check authentication in some way (see if MCP handles it)
         const auth = null;
         try {
             const route = this.tools.get(name);

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

@@ -6,6 +6,7 @@ import { rnInputDef } from '../lib/rn/input.js';
 const MULTIPLE_VALUES_SEPARATOR = ',';
 export function UCFormFieldControl({ errMsg = null, execState, field, onChange: onChangeBase, }) {
     const [internalValue, setInternalValue] = useState(field.getValue());
+    // biome-ignore lint/correctness/useExhaustiveDependencies: false positive : It is actually necessary (only `field` does not trigger the effect)
     useEffect(() => {
         setInternalValue(field.getValue());
     }, [field.getValue()]);

package/dist/esm/testing/AppTester.d.ts

@@ -43,6 +43,10 @@ export declare class AppTester {
     private ucExecutor;
     private configurator;
     private ctx;
+    /**
+     * We use a "safe" one to avoid any "infinite loop" while trying to import/resolve a file.
+     * This can happen in case of circular dependencies for example.
+     */
     private safeSrcImporter;
     private testResults;
     private testSummary;

package/dist/esm/testing/AppTester.js

@@ -14,6 +14,8 @@ import { inject, injectable } from 'inversify';
 import { I18nEN } from '../i18n/locales/en.js';
 import { I18nFR } from '../i18n/locales/fr.js';
 import { FAKE_USER_ADMIN, UCBuilder, UCInputFieldChangeOperator, ucHTTPContract, } from '../uc/index.js';
+// We inject directly the implementation because we'll generate all the reports and not only the one that is bound to the interface.
+// We can plan a setting à la Vitest where we specify the types of reports to generate though.
 import { SimpleHTMLAppTestReportEmitter } from './impl/SimpleHTMLAppTestReportEmitter.js';
 import { optsAllSet } from './opts.js';
 import { defaultUCAuthSetters } from './uc-auth.js';
@@ -40,7 +42,12 @@ let AppTester = class AppTester {
     ucExecutor;
     configurator;
     ctx;
+    /**
+     * We use a "safe" one to avoid any "infinite loop" while trying to import/resolve a file.
+     * This can happen in case of circular dependencies for example.
+     */
     safeSrcImporter;
+    // biome-ignore lint/suspicious/noExplicitAny: can be anything
     testResults;
     testSummary;
     ucDefSourcesCheckerOutput;
@@ -134,7 +141,9 @@ let AppTester = class AppTester {
         const inputFiller = (uc) => {
             uc.fill(input);
         };
+        // biome-ignore lint/suspicious/noExplicitAny: can be anything
         const { out } = await this.execUC({
+            // TODO : Pass the appropriate one so we test the real flow and not the auth
             auth: FAKE_USER_ADMIN,
             authName: 'ADMIN',
             inputFiller,
@@ -148,6 +157,7 @@ let AppTester = class AppTester {
             ...input,
             appManifest: this.ctx.appManifest,
         });
+        // TODO : Add errors mapping to configurator so the developer can override this default behavior
         let status = 'warning';
         if (!out.err) {
             status = 'success';
@@ -169,6 +179,9 @@ let AppTester = class AppTester {
         let sideEffects = await this.configurator.sideEffects(this.ctx);
         if (flow) {
             name = `${flow.name} > ${name}`;
+            // For regular uc tests, side effects are cleared between each execution
+            // But it's not the case for a flow, thus each flow uc test shares the same side effects ref
+            // To have the side effects at each stage, we take a snapshot (to be improved as this is not performant at all)
             if (sideEffects) {
                 const snapshot = JSON.parse(JSON.stringify(Array.from(sideEffects.entries())));
                 sideEffects = new Map(snapshot);
@@ -205,6 +218,7 @@ let AppTester = class AppTester {
     async init({ appPath, configurator, serverClientSettings, srcImporter, }) {
         this.configurator = configurator;
         this.safeSrcImporter = (path) => Promise.race([
+            // We can cast because it fails or looses the race.
             awaitForSrcImport(path),
             srcImporter(path),
         ]);
@@ -222,6 +236,7 @@ let AppTester = class AppTester {
         await this.initServer();
     }
     async ucTestData(ucdRef) {
+        // Auth setters
         const defaultASs = defaultUCAuthSetters();
         let asEntries = Object.entries(defaultASs);
         const asConfig = await this.configurator.authSettersConfig();
@@ -236,6 +251,7 @@ let AppTester = class AppTester {
                 asEntries.push(...Object.entries(add));
             }
         }
+        // Input fillers
         const defaultIFs = defaultUCInputFillers();
         const ifEntries = Object.entries(defaultIFs);
         const specificIFs = await this.configurator.inputFillers();

package/dist/esm/testing/AppTesterConfigurator.d.ts

@@ -6,21 +6,89 @@ import type { DefaultUCAuthSetter, UCAuthSetterSet } from './uc-auth.js';
 import type { CustomUCInputFiller, UCInputFillerSet } from './uc-input.js';
 import type { UCExecutorAssertion } from './workers/UCExecutor.js';
 export type AppTesterConfiguratorAuthSettersConfig = {
+    /**
+     * Specific auth setters to add to the default ones
+     */
     add?: UCAuthSetterSet;
+    /**
+     * Default auth setters to exclude
+     *
+     * For instance, if your app does not care about auth (e.g. only client side app), you can safely exclude everything except {@link ANONYMOUS}
+     */
     exclude?: Set<DefaultUCAuthSetter>;
 };
 export type AppTesterConfiguratorInputFillers<I extends UCInput = any, OPI0 extends UCOPIBase = any, OPI1 extends UCOPIBase = any> = Map<UCName, UCInputFillerSet<CustomUCInputFiller, I, OPI0, OPI1>>;
 export type AppTesterConfiguratorSideEffects = Map<string, any>;
 export type AppTesterConfiguratorSideEffectsSerialized = [string, any][];
 export type AppTesterConfiguratorSpecificAssertions<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = Map<CryptoManagerHash, UCExecutorAssertion<I, OPI0, OPI1>>;
+/**
+ * Configure the tester for a specific app
+ *
+ * @defaultValue See {@link SimpleAppTesterConfigurator}
+ */
 export interface AppTesterConfigurator {
+    /**
+     * Auth setters config to add some or exclude default ones
+     */
     authSettersConfig(): Promise<AppTesterConfiguratorAuthSettersConfig | undefined>;
+    /**
+     * Override the implementations needed by the use cases, in `ctx.container`
+     *
+     * @param ctx
+     */
     bindImplementations(ctx: AppTesterCtx): Promise<void>;
+    /**
+     * Clear what needs to be cleared after a use case execution
+     *
+     * For instance, this includes the data store, some fake queue processor checked in side effects, etc.
+     *
+     * @param ctx
+     */
     clearExecution(ctx: AppTesterCtx): Promise<void>;
+    /**
+     * Define specific flows to test multiple use cases sequentially
+     *
+     * For example : SignUp > SignIn > SignOut > ResetPassword, etc.
+     */
     flows(): Promise<AppTesterFlow[]>;
+    /**
+     * Define specific input fillers, per use case, in addition to the default ones
+     *
+     * @see defaultInputFillers
+     */
     inputFillers(): Promise<AppTesterConfiguratorInputFillers | undefined>;
+    /**
+     * Override the `ctx.opts()`, in case the app has some specificities
+     */
     opts(): Promise<AppTesterCtx['opts']>;
+    /**
+     * Seed some data in any data store needed by the use cases
+     *
+     * @param ctx
+     */
     seed(ctx: AppTesterCtx): Promise<void>;
+    /**
+     * Register the side effects that need to be tracked
+     *
+     * For instance, this is where you register {@link FakeEmailManager.entries} to check the emails sent by use cases.
+     *
+     * Or it can also be the entries of some fake job processor to check the jobs dispatched by use cases.
+     *
+     * Note that it works only if there are no `specificAssertions` for the given use case.
+     *
+     * Otherwise, you need to assert side effects manually.
+     *
+     * @param ctx
+     */
     sideEffects(ctx: AppTesterCtx): Promise<AppTesterConfiguratorSideEffects | undefined>;
+    /**
+     * Define specific assertions for a specific use case
+     *
+     * Otherwise, it matches the snapshot.
+     *
+     * For instance, you can use this if a specific use case performs some random processing (e.g. generating random data).
+     *
+     * Generally speaking, it's always better to have deterministic tests, so it's usually better to bind deterministic implementations in the tests.
+     */
     specificAssertions(): Promise<AppTesterConfiguratorSpecificAssertions | undefined>;
 }

package/dist/esm/testing/UCDataStoreTester.d.ts

@@ -3,6 +3,15 @@ import { type UCDataStore } from '../uc/index.js';
 interface Input {
     ucDataStore: UCDataStore;
 }
+/**
+ * Test that a {@link UCDataStore} conforms to the spec
+ *
+ * By default it runs tests on the projection mechanism.
+ * Therefore, you need to create one in your implementation when creating your test suite.
+ * See `src/uc/impl/KnexUCDataStore.test.ts` for an example.
+ *
+ * Otherwise you can just `skipProjectionTesting`, although it's not recommended.
+ */
 export declare class UCDataStoreTester implements Worker<Input, Promise<void>> {
     private clockManager;
     private cryptoManager;

package/dist/esm/testing/UCDataStoreTester.js

@@ -18,6 +18,15 @@ import { UCExecMode, } from '../uc/index.js';
 const ERR_SHOULD_NOT_EXIST_AFTER_DESTROY = 'It should not exist after destroy';
 const ERR_SHOULD_EXIST_AFTER_INSTALL = 'It should exist after install';
 const ERR_SHOULD_RETURN_X_RECORDS = (n) => `It should return ${n} record(s)`;
+/**
+ * Test that a {@link UCDataStore} conforms to the spec
+ *
+ * By default it runs tests on the projection mechanism.
+ * Therefore, you need to create one in your implementation when creating your test suite.
+ * See `src/uc/impl/KnexUCDataStore.test.ts` for an example.
+ *
+ * Otherwise you can just `skipProjectionTesting`, although it's not recommended.
+ */
 let UCDataStoreTester = class UCDataStoreTester {
     static { UCDataStoreTester_1 = this; }
     clockManager;
@@ -60,6 +69,7 @@ let UCDataStoreTester = class UCDataStoreTester {
         await ucDataStore.clear();
         this.readRes = await ucDataStore.read();
         this.expectXRecords(0);
+        // Write a last one in case need to watch data in the DB
         await this.ucDataStore.write({
             aggregateId: this.cryptoManager.randomUUID(),
             appName: APP_NAME_PLACEHOLDER,
@@ -116,9 +126,12 @@ let UCDataStoreTester = class UCDataStoreTester {
         ];
     }
     buildFiltersTestData() {
+        // biome-ignore lint/style/noNonNullAssertion: we're in a test
         const entry = this.entries[0];
         const [aggregateId, appName, ucNames, organizationId, userId] = entry;
+        // biome-ignore lint/style/noNonNullAssertion: we're in a test
         const name = ucNames[0];
+        // TODO : Enhance these with a combination of filters
         return [
             [{ aggregateId }, 2],
             [{ aggregateId: [aggregateId] }, 2],

package/dist/esm/testing/impl/SimpleAppDocsEmitter.js

@@ -33,6 +33,13 @@ SimpleAppDocsEmitter = __decorate([
     __metadata("design:paramtypes", [Object])
 ], SimpleAppDocsEmitter);
 export { SimpleAppDocsEmitter };
+// For now, we can have it here. When it becomes harder to maintain, we can introduce some kind of template engine.
+// Be aware that this will introduce complexities on building the lib.
+// We'll need to include these templates in the build and make them accessible via package.json "exports" or any other mechanism.
+// Hence the choice to keep it simple for now.
+// Defined it as function in case we need to pass args.
+// Using --- for the comment to make it compatible with pandoc
+// See https://stackoverflow.com/a/4829998/1259118
 const template = (cols, items) => `<!---
     All this code has been auto generated.
     DO NOT EDIT.
@@ -55,6 +62,9 @@ ${diagram(item)}`)
 |---|${cols.map((_c) => '---').join('|')}|
 ${items.map((item, idx) => ['', idx + 1, ...cols.map((c) => fmtTechSummaryField(item[c])), ''].join('|')).join('\n')}
 `;
+/*
+ * Diagram
+ */
 const CHECK_POLICY = '🔐 Check policy';
 const CHECK_POLICY_COND = 'when any validation fails';
 const CHECK_POLICY_COND_ACTION = 'show failure';
@@ -69,6 +79,8 @@ const SEND = '📤 Send';
 const SUBMIT = '↩️ Submit';
 const TRIGGER = '⤴️ Trigger';
 function diagram(item) {
+    // Debugger : https://mermaid.live/edit
+    // Messages : https://mermaid.js.org/syntax/sequenceDiagram.html#messages
     const client = 'Client';
     const server = 'Server';
     const user = 'User';
@@ -76,6 +88,8 @@ function diagram(item) {
     const { ioIFields, ioOPI0Fields, ioOPI1Fields, lifecycleClientPolicy, lifecycleClientSteps, lifecycleServerPolicy, lifecycleServerSteps, metadataSensitive, } = item;
     let req = TRIGGER;
     if (ioIFields && ioIFields.length > 0) {
+        // TODO : Include only fields to fill manually
+        // Not sure though, as for CLI for example (i.e. noContext), one needs to provide all of them
         req = `${FILL}${LB}${diagramUCFields(item.ioIFields)}`;
     }
     lines.push(`${user}->>+${client}: ${req}`);
@@ -89,6 +103,7 @@ function diagram(item) {
     if (lifecycleClientSteps) {
         lines.push(...diagramUCMainSteps(client, lifecycleClientSteps));
     }
+    // This is an approximation. Might need to improve it.
     const hasServer = item.lifecycleServerPolicy?.value;
     if (hasServer) {
         req = SEND;
@@ -142,11 +157,16 @@ function diagramUCPolicy(participant, caller, lifecyclePolicyField) {
         'end',
     ];
 }
+/*
+ * Technical Summary
+ */
 function fmtTechSummaryField(field) {
     if (!field) {
         return '';
     }
     const values = Array.isArray(field) ? field : [field];
+    // NOTE : <br> won't work for every markdown renderer.
+    // See https://stackoverflow.com/questions/11700487/how-do-i-add-a-newline-in-a-markdown-table
     return values.map(fmtTechSummaryFieldVal).join('<br>');
 }
 function fmtTechSummaryFieldVal(field) {
@@ -155,7 +175,7 @@ function fmtTechSummaryFieldVal(field) {
     if (err) {
         res += `❌ ${err}`;
     }
-    res = res.replace(/[\u00A0-\u9999<>\&]/g, (i) => `&#${i.charCodeAt(0)};`);
-    res = res.replaceAll('|', '\\|');
+    res = res.replace(/[\u00A0-\u9999<>\&]/g, (i) => `&#${i.charCodeAt(0)};`); // TS generics considered as HTML
+    res = res.replaceAll('|', '\\|'); // TS intersection vs Markdown table column
     return res;
 }