libmodulor 0.4.0 → 0.5.0

package/dist/esm/uc/server.d.ts

@@ -6,7 +6,17 @@ import type { UCMain } from './main.js';
 import type { UCOPIBase } from './opi.js';
 import type { UCPolicy } from './policy.js';
 export interface UCServerDef<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> {
+    /**
+     * Define how the use case can be executed
+     *
+     * When set to {@link UCExecMode.AUTO}, the use case is not mounted on the target (i.e. no endpoint on a server).
+     *
+     * @defaultValue {@link UCExecMode.USER}
+     */
     execMode?: UCExecMode;
+    /**
+     * Routine to run when mounting the use case in a {@link ServerManager}
+     */
     init?: Class<UCInit>;
     main: Class<UCMain<I, OPI0, OPI1>>;
     policy: Class<UCPolicy<I, OPI0, OPI1>>;

package/dist/esm/uc/settings.d.ts

@@ -4,8 +4,33 @@ import type { UCDataStoreDatasetName } from './data-store.js';
 import type { UCFileInputFieldRefPrefix } from './file.js';
 import type { UCName } from './metadata.js';
 export interface UCSettings extends Settings {
+    /**
+     * The name of the collection/table storing the persisted use cases in the data store
+     *
+     * @default UC_DEFAULT_SETTINGS.uc_data_store_ucs_dataset_name
+     */
     uc_data_store_ucs_dataset_name: UCDataStoreDatasetName;
+    /**
+     * The list of disabled use cases (see {@link UCExecChecker})
+     *
+     * This should be used only in specific cases (e.g. disabling in emergency a use case in production).
+     *
+     * If you want a feature-flag like mechanism, chances are you need a dedicated setting, "wrapping" multiple use cases.
+     *
+     * @default UC_DEFAULT_SETTINGS.uc_disabled_use_cases
+     */
     uc_disabled_use_cases: UCName[];
+    /**
+     * The prefix of the file path when the use case has been processed, before storing
+     * @default UC_DEFAULT_SETTINGS.uc_file_ref_prefix
+     */
     uc_file_ref_prefix: UCFileInputFieldRefPrefix;
+    /**
+     * The directory path where the use case input files are copied after being processed
+     *
+     * In the future, we can imagine storing in other types of storage (e.g. S3-like).
+     *
+     * @default UC_DEFAULT_SETTINGS.uc_files_directory_path
+     */
     uc_files_directory_path: FilePath;
 }

package/dist/esm/uc/side-effect.d.ts

@@ -1,6 +1,22 @@
 export declare enum UCOutputSideEffectType {
+    /**
+     * Trigger a clearing of the auth on the calling system (e.g. `SignOut`).
+     */
     CLEAR_AUTH = "CLEAR_AUTH",
+    /**
+     * Trigger a redirect on the calling system (e.g. after the final round of an OAuth1 flow)
+     *
+     * NOTE : This is a "final" side effects, which means it must be the last one in the array of side effects.
+     * Indeed, in most servers, once you redirect, you cannot do more with the `req`/`res` (e.g. on `express`).
+     *
+     * It expects a field `redirect: URL` in `output.parts._0.items[0]`.
+     */
     REDIRECT = "REDIRECT",
+    /**
+     * Trigger a setting of the auth on the calling system (e.g. `SignIn` / `SignUp`).
+     *
+     * It expects a field `jwt: JWT` in `output.parts._0.items[0]`.
+     */
     SET_AUTH = "SET_AUTH"
 }
 export type UCOutputSideEffect = {

package/dist/esm/uc/side-effect.js

@@ -1,6 +1,22 @@
 export var UCOutputSideEffectType;
 (function (UCOutputSideEffectType) {
+    /**
+     * Trigger a clearing of the auth on the calling system (e.g. `SignOut`).
+     */
     UCOutputSideEffectType["CLEAR_AUTH"] = "CLEAR_AUTH";
+    /**
+     * Trigger a redirect on the calling system (e.g. after the final round of an OAuth1 flow)
+     *
+     * NOTE : This is a "final" side effects, which means it must be the last one in the array of side effects.
+     * Indeed, in most servers, once you redirect, you cannot do more with the `req`/`res` (e.g. on `express`).
+     *
+     * It expects a field `redirect: URL` in `output.parts._0.items[0]`.
+     */
     UCOutputSideEffectType["REDIRECT"] = "REDIRECT";
+    /**
+     * Trigger a setting of the auth on the calling system (e.g. `SignIn` / `SignUp`).
+     *
+     * It expects a field `jwt: JWT` in `output.parts._0.items[0]`.
+     */
     UCOutputSideEffectType["SET_AUTH"] = "SET_AUTH";
 })(UCOutputSideEffectType || (UCOutputSideEffectType = {}));

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

@@ -2,9 +2,21 @@ import type { UC } from '../UC.js';
 import type { UCInput } from '../input.js';
 import type { UCOPIBase } from '../opi.js';
 interface Opts {
+    /**
+     * @defaultValue false
+     */
     forceArrayAsEmpty?: boolean | undefined;
+    /**
+     * @defaultValue true
+     */
     forceBooleanAsFalse?: boolean | undefined;
+    /**
+     * @defaultValue false
+     */
     ignoreTransient?: boolean | undefined;
+    /**
+     * @defaultValue false
+     */
     ignoreUndefined?: boolean | undefined;
 }
 export declare function rInput<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>, opts?: Opts): NonNullable<I>;

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

@@ -32,6 +32,8 @@ export function rInput(uc, opts) {
             value = [];
         }
         if (!ignoreUndefined || (ignoreUndefined && value !== undefined)) {
+            // Useful when we get the input before persisting for example.
+            // Otherwise it will persist `undefined` as a string in the database, for nothing.
             input[f.key] = value;
         }
     }

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

@@ -1,5 +1,30 @@
 import type { DataType } from '../../dt/index.js';
 import type { Value } from '../value.js';
+/**
+ * Read the value as a primitive
+ *
+ * To be used when the field has a 0..1 cardinality.
+ *
+ * @param value
+ * @param or
+ * @returns
+ */
 export declare function rVal0<T extends DataType>(value: Value<T>, or?: T): T | null;
+/**
+ * Require the value as a primitive
+ *
+ * To be used when the field has a 1..1 cardinality.
+ *
+ * @param value
+ * @returns
+ */
 export declare function reqVal0<T extends DataType>(value: Value<T>): T;
+/**
+ * Get the value as an array
+ *
+ * To be used when the field has a 0..* cardinality.
+ *
+ * @param value
+ * @returns
+ */
 export declare function rValArr<T extends DataType>(value: Value<T>): T[];

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

@@ -1,10 +1,29 @@
 import { isBlank } from '../../utils/index.js';
+// NOTE : the "r" prefix stands for "read" and the "req" prefix stands for "require"
+/**
+ * Read the value as a primitive
+ *
+ * To be used when the field has a 0..1 cardinality.
+ *
+ * @param value
+ * @param or
+ * @returns
+ */
+// TODO : Find a way to return `T` when `or` is set (function override does not work)
 export function rVal0(value, or) {
     if (isBlank(value)) {
         return or ?? null;
     }
     return Array.isArray(value) ? (value[0] ?? null) : value;
 }
+/**
+ * Require the value as a primitive
+ *
+ * To be used when the field has a 1..1 cardinality.
+ *
+ * @param value
+ * @returns
+ */
 export function reqVal0(value) {
     const val = rVal0(value);
     if (isBlank(val)) {
@@ -12,6 +31,14 @@ export function reqVal0(value) {
     }
     return val;
 }
+/**
+ * Get the value as an array
+ *
+ * To be used when the field has a 0..* cardinality.
+ *
+ * @param value
+ * @returns
+ */
 export function rValArr(value) {
     if (isBlank(value)) {
         return [];

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

@@ -2,4 +2,13 @@ import type { UCDataStoreRecord } from '../data-store.js';
 import type { UCData } from '../data.js';
 import type { UCInput } from '../input.js';
 import type { UCName } from '../metadata.js';
+/**
+ * Check whether a data store records corresponds to the passed type
+ *
+ * Useful when fetching multiple records at once and looping over them to build an aggregate
+ *
+ * @param rec
+ * @param name
+ * @returns
+ */
 export declare const recIs: <I extends UCInput | undefined = undefined, D extends UCData | null = null>(rec: UCDataStoreRecord<any, any>, name: UCName) => rec is UCDataStoreRecord<I, D>;

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

@@ -1 +1,12 @@
-export const recIs = (rec, name) => rec.name === name;
+/**
+ * Check whether a data store records corresponds to the passed type
+ *
+ * Useful when fetching multiple records at once and looping over them to build an aggregate
+ *
+ * @param rec
+ * @param name
+ * @returns
+ */
+export const recIs = (
+// biome-ignore lint/suspicious/noExplicitAny: can be anything
+rec, name) => rec.name === name;

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[];