libmodulor 0.4.0 → 0.5.0

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

@@ -5,12 +5,41 @@ import type { UCMountingPoint } from './utils/ucMountingPoint.js';
 export type UCHTTPMountingPoint = `/${URLPath}`;
 export interface UCExt<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> {
     cmd?: {
+        /**
+         * The command on which the use case is mounted at
+         *
+         * By default, it's mounted at `${fqucn}`.
+         */
         mountAt?: UCMountingPoint;
     };
     http?: {
+        /**
+         * The verb on which the use case is mounted at
+         *
+         * By default, it's computed from the {@link UCMetadata.action} with some specific heuristics.
+         *
+         * For instance, you can set `POST` even for a `List` use case, which usually defaults to `GET`.
+         * This can be useful in case you want the input to "travel" through the body of the request, and not the query params.
+         */
         method?: HTTPMethod;
+        /**
+         * The path on which the use case should mounted at
+         *
+         * By default, it's mounted at `/api/v1/${fqucn}`.
+         */
         mountAt?: UCHTTPMountingPoint;
+        /**
+         * The path on which the use case should also mounted at
+         *
+         * This is typically used when the mounting point is changed and you want to maintain a "legacy" endpoint for clients having
+         * a different release cycle than the server (e.g. a mobile app), who are still calling the old endpoint.
+         */
         mountAlsoAt?: UCHTTPMountingPoint[];
-        transform?: <T extends object>(output: UCOutput<OPI0, OPI1>) => T;
+        /**
+         * Transform the output received to fit with some specific cases where the endpoint is expected to respect a certain contract
+         * @param output
+         * @returns
+         */
+        transform?: (output: UCOutput<OPI0, OPI1>) => object;
     };
 }

package/dist/esm/uc/helpers/UCOutputBuilder.js

@@ -19,13 +19,17 @@ export class UCOutputBuilder {
     }
     addAll1(items) {
         this.init1IfNecessary();
+        // biome-ignore lint/style/noNonNullAssertion: set in the call above
         this.output.parts._1.items.push(...items);
+        // biome-ignore lint/style/noNonNullAssertion: set in the call above
         this.output.parts._1.total += items.length;
         return this;
     }
     add1(item) {
         this.init1IfNecessary();
+        // biome-ignore lint/style/noNonNullAssertion: set in the call above
         this.output.parts._1.items.push(item);
+        // biome-ignore lint/style/noNonNullAssertion: set in the call above
         this.output.parts._1.total += 1;
         return this;
     }
@@ -34,6 +38,7 @@ export class UCOutputBuilder {
     }
     count1() {
         this.init1IfNecessary();
+        // biome-ignore lint/style/noNonNullAssertion: set in the call above
         return this.output.parts._1.total;
     }
     has(predicate) {

package/dist/esm/uc/helpers/UCOutputReader.js

@@ -75,7 +75,9 @@ export class UCOutputReader {
             total = part.total;
         }
         return {
-            fields: allFieldsKeys.map((fieldKey) => new UCOutputField(fieldKey, allFields[fieldKey])),
+            fields: allFieldsKeys.map((fieldKey) => 
+            // biome-ignore lint/suspicious/noExplicitAny: can be anything
+            new UCOutputField(fieldKey, allFields[fieldKey])),
             idx,
             items,
             key,

package/dist/esm/uc/impl/HTTPUCTransporter.js

@@ -40,6 +40,7 @@ let HTTPUCTransporter = class HTTPUCTransporter {
         const publicApiKeyCheckType = sec?.publicApiKeyCheckType ?? DEFAULT_UC_SEC_PAKCT;
         switch (publicApiKeyCheckType) {
             case 'off':
+                // Nothing to do
                 break;
             case 'on': {
                 const publicApiKey = await this.serverClientManager.publicApiKey();
@@ -102,6 +103,9 @@ let HTTPUCTransporter = class HTTPUCTransporter {
             },
             urlBuilder: async () => `${baseURL}${path}`,
         });
+        // In case of 204, we get an empty object.
+        // Even though it makes deserializing easier, this is not considered a valid output.
+        // So we handle the case here.
         if (!res || Object.keys(res).length === 0) {
             return;
         }

package/dist/esm/uc/impl/InMemoryUCDataStore.js

@@ -19,6 +19,7 @@ function predicate(key, filter) {
     return (r) => r[key] === filter;
 }
 let InMemoryUCDataStore = class InMemoryUCDataStore {
+    // biome-ignore lint/suspicious/noExplicitAny: can be anything
     entries;
     tx;
     constructor() {
@@ -46,10 +47,13 @@ let InMemoryUCDataStore = class InMemoryUCDataStore {
         };
     }
     async install() {
+        // Nothing to do
     }
     async read(opts) {
         let items = this
             .entries;
+        // Filter
+        // Of course it handles only simple cases (eq X, is null, in) with the AND operator
         if (opts?.filters) {
             const { aggregateId, appName, name, organizationId, userId } = opts.filters;
             if (aggregateId !== undefined) {
@@ -68,6 +72,8 @@ let InMemoryUCDataStore = class InMemoryUCDataStore {
                 items = items.filter(predicate('userId', userId));
             }
         }
+        // Sort
+        // => No need, we are processing them by order of insertion in the Map
         return {
             records: items,
         };
@@ -79,6 +85,7 @@ let InMemoryUCDataStore = class InMemoryUCDataStore {
         return [];
     }
     async testKey() {
+        // Nothing to do
     }
     async write(record) {
         this.writeBulk([record]);

package/dist/esm/uc/impl/KnexUCDataStore.d.ts

@@ -5,6 +5,10 @@ import type { UCDataStore, UCDataStoreReadOpts, UCDataStoreReadProjectionOpts, U
 import type { UCData } from '../data.js';
 import type { UCInput } from '../input.js';
 import type { UCSettings } from '../settings.js';
+/**
+ * @see https://knexjs.org/guide/#configuration-options
+ * @see https://knexjs.org/guide/#pool
+ */
 export interface KnexUCDataStoreSettings extends Settings {
     knex_uc_data_store_conn_string: `postgresql://${string}`;
     knex_uc_data_store_file_path: FilePath | ':memory:';

package/dist/esm/uc/impl/KnexUCDataStore.js

@@ -58,6 +58,7 @@ let KnexUCDataStore = class KnexUCDataStore {
     }
     async read(opts) {
         const query = this.client(this.s().uc_data_store_ucs_dataset_name);
+        // Filter
         if (opts?.filters) {
             const { aggregateId, appName, idWithinInput, name, organizationId, userId, } = opts.filters;
             this.filter(query, aggregateId, 'aggregateId');
@@ -67,10 +68,17 @@ let KnexUCDataStore = class KnexUCDataStore {
             this.filter(query, userId, 'userId');
             if (idWithinInput !== undefined) {
                 for (const [k, v] of Object.entries(idWithinInput)) {
+                    // Not comfortable with the key here but it seems to escape correctly :
+                    // select * from "d2efe54a-ce85-437c-958e-440f54c0743d"
+                    //   where jsonb_path_query_first("input", ?) #>> '{}' = ?
+                    //   and "name" = ?
+                    //   and "organization_id" = ?
+                    //   order by "created_at" asc
                     query.whereJsonPath('input', `$.${k}`, '=', v);
                 }
             }
         }
+        // Sort
         query.orderBy('created_at', 'asc');
         const records = (await query).map((r) => this.mapRowToRecord(r));
         return {
@@ -79,11 +87,13 @@ let KnexUCDataStore = class KnexUCDataStore {
     }
     async readProjection(name, opts) {
         const query = this.client(name);
+        // Sort
         if (opts?.orderBy) {
             for (const [k, v] of Object.entries(opts.orderBy)) {
                 query.orderBy(k, v);
             }
         }
+        // Paginate
         if (opts?.limit) {
             query.limit(opts.limit);
         }
@@ -201,9 +211,13 @@ let KnexUCDataStore = class KnexUCDataStore {
         };
     }
     parseJSONColIfNecessary(value) {
+        // In some DBs, the json type is returned as string (e.g. sqlite3)
         return typeof value === 'string' ? JSON.parse(value) : value;
     }
+    //#region migrations
     async migration001CreateMainTable() {
+        // Using hasTable and then createTable because createTableIfNotExists has been deprecated
+        // See https://github.com/knex/knex/issues/1303#issuecomment-594489136
         const exists = await this.client.schema.hasTable(this.s().uc_data_store_ucs_dataset_name);
         if (exists) {
             return;

package/dist/esm/uc/impl/SimpleUCManager.js

@@ -29,6 +29,7 @@ let SimpleUCManager = class SimpleUCManager {
     ucInputValidator;
     ucInitProvider;
     ucMainProvider;
+    // WARNING : This property makes this class "thread unsafe". Be careful how you inject it into your components.
     tx;
     constructor(ucClientConfirmManager, clockManager, cryptoManager, logger, ucDataStore, ucExecChecker, ucInputFilesProcessor, ucInputValidator, ucInitProvider, ucMainProvider) {
         this.ucClientConfirmManager = ucClientConfirmManager;
@@ -64,6 +65,7 @@ let SimpleUCManager = class SimpleUCManager {
         if (!client) {
             throw new Error(`The use case ${metadata.name} has no client lifecycle`);
         }
+        // Always check the right to execute, even if done when displaying the control
         const { allowed } = await this.ucExecChecker.exec({
             lifecycle: 'client',
             uc,
@@ -72,6 +74,9 @@ let SimpleUCManager = class SimpleUCManager {
             throw new ForbiddenError();
         }
         this.ucInputValidator.exec({ uc });
+        // Process the file client side only if it is not sent to the server
+        // Be careful with some edge cases where the file needs to be uploaded somewhere else.
+        // Note that we cannot check server !== true because in some cases, the server is not stripped (e.g. tests, node cli client, etc.).
         if (server === undefined) {
             await this.ucInputFilesProcessor.exec({ uc });
         }
@@ -85,6 +90,7 @@ let SimpleUCManager = class SimpleUCManager {
         if (typeof server !== 'object') {
             throw new Error(`The use case ${metadata.name} has no server lifecycle`);
         }
+        // Always check the right to execute, even if done when displaying the control
         const { allowed } = await this.ucExecChecker.exec({
             lifecycle: 'server',
             uc,

package/dist/esm/uc/input-field.d.ts

@@ -2,30 +2,90 @@ import type { DataType, TBase, UIntQuantity } from '../dt/index.js';
 import type { UCFieldKey } from './def.js';
 import type { Value } from './value.js';
 export declare enum UCInputFieldChangeOperator {
+    /**
+     * Considering the cardinality of the field (min > 1), add a new value
+     */
     ADD = "ADD",
+    /**
+     * Considering the cardinality of the field (min > 1), remove a value
+     */
     REMOVE = "REMOVE",
+    /**
+     * Reset the value of the field
+     */
     RESET = "RESET",
+    /**
+     * Considering the cardinality of the field (max <= 1), set the value
+     */
     SET = "SET"
 }
 export declare enum UCInputFieldFillingMode {
+    /**
+     * Set programmatically on behalf of the user (e.g. a foreign key id for a given object)
+     */
     AUTO_PRE = "AUTO_PRE",
+    /**
+     * Set manually by the user (e.g. a form field, a cli flag, etc.)
+     */
     MANUAL = "MANUAL"
 }
 export interface UCInputFieldDefCardinality {
     max?: UIntQuantity;
     min?: UIntQuantity;
 }
+/**
+ * Definition of a use case input field
+ */
 export interface UCInputFieldDef<T extends DataType> {
+    /**
+     * A field can have 0, 1 or n values. This field defines the rules.
+     *
+     * @defaultValue { max: 1, min: 1 } => the user must absolutely provide one value only
+     *
+     * @example { max: 5, min: 0 } => the user must provide at most 5 values or none
+     * @example { min: 0 } => the user must provide 0 values or none
+     */
     cardinality?: UCInputFieldDefCardinality;
+    /**
+     * @defaultValue {@link UCInputFieldFillingMode.MANUAL}
+     */
     fillingMode?: UCInputFieldFillingMode;
+    /**
+     * @defaultValue false
+     */
     readOnly?: boolean;
+    /**
+     * Some types are automatically considered sensitive (e.g. {@link Password}).
+     *
+     * But you can force the behavior with this setting for any other type of field.
+     *
+     * @defaultValue false
+     */
     sensitive?: boolean;
+    /**
+     * When you persist a use case, all the input fields are automatically persisted as well.
+     *
+     * Sometimes this is not wanted. Setting the field as transient will exclude it from being persisted.
+     *
+     * @defaultValue false
+     */
     transient?: boolean;
     type: TBase<T>;
 }
 export type UCInputFieldValue<T extends DataType> = Value<T>;
 export declare function ucifExamples<T extends DataType>(def: UCInputFieldDef<T>): T[] | undefined;
 export declare function ucifHint<T extends DataType>(def: UCInputFieldDef<T>): string | undefined;
+/**
+ * The unique id associated to this field
+ *
+ * By default it would return `inputfield-myField`.
+ * If you have the same field multiple times in one context (e.g. a web page), pass a unique element to the `prefix`.
+ * For example `uc1-inputfield-myField` and `uc2-inputfield-myField`
+ *
+ * @param prefix
+ * @param separator
+ * @returns
+ */
 export declare function ucifId(key: UCFieldKey, prefix?: string, separator?: string): string;
 export declare function ucifIsMandatory<T extends DataType>(def: UCInputFieldDef<T>): boolean;
 export declare function ucifRepeatability<T extends DataType>(def: UCInputFieldDef<T>): [boolean, UIntQuantity];

package/dist/esm/uc/input-field.js

@@ -1,21 +1,41 @@
 export var UCInputFieldChangeOperator;
 (function (UCInputFieldChangeOperator) {
+    /**
+     * Considering the cardinality of the field (min > 1), add a new value
+     */
     UCInputFieldChangeOperator["ADD"] = "ADD";
+    /**
+     * Considering the cardinality of the field (min > 1), remove a value
+     */
     UCInputFieldChangeOperator["REMOVE"] = "REMOVE";
+    /**
+     * Reset the value of the field
+     */
     UCInputFieldChangeOperator["RESET"] = "RESET";
+    /**
+     * Considering the cardinality of the field (max <= 1), set the value
+     */
     UCInputFieldChangeOperator["SET"] = "SET";
 })(UCInputFieldChangeOperator || (UCInputFieldChangeOperator = {}));
 export var UCInputFieldFillingMode;
 (function (UCInputFieldFillingMode) {
+    /**
+     * Set programmatically on behalf of the user (e.g. a foreign key id for a given object)
+     */
     UCInputFieldFillingMode["AUTO_PRE"] = "AUTO_PRE";
+    /**
+     * Set manually by the user (e.g. a form field, a cli flag, etc.)
+     */
     UCInputFieldFillingMode["MANUAL"] = "MANUAL";
 })(UCInputFieldFillingMode || (UCInputFieldFillingMode = {}));
 export function ucifExamples(def) {
     const { type } = def;
     const examples = type.getExamples();
+    // Leaving the value `undefined` means you want the default value
     if (examples === undefined) {
         return [type.example()];
     }
+    // Setting the examples to `[]` means you don't want them
     if (examples.length === 0) {
         return undefined;
     }
@@ -37,6 +57,17 @@ export function ucifHint(def) {
     }
     return examples.join(', ');
 }
+/**
+ * The unique id associated to this field
+ *
+ * By default it would return `inputfield-myField`.
+ * If you have the same field multiple times in one context (e.g. a web page), pass a unique element to the `prefix`.
+ * For example `uc1-inputfield-myField` and `uc2-inputfield-myField`
+ *
+ * @param prefix
+ * @param separator
+ * @returns
+ */
 export function ucifId(key, prefix = 'inputfield', separator = '-') {
     return `${prefix}${separator}${key}`;
 }
@@ -60,12 +91,14 @@ export function ucifIsSensitive(def) {
 }
 export function ucifMustBeFilledManually(def, opts) {
     const { fillingMode } = def;
+    // If there is no mode, we consider it as UCInputFieldFillingMode.MANUAL
     if (!fillingMode) {
         return true;
     }
     const fillingModes = [
         UCInputFieldFillingMode.MANUAL,
     ];
+    // If there is no context, it means that the field cannot be set via UCInputFieldFillingMode.AUTO_PRE (e.g. in CLI target)
     if (opts?.noContext) {
         fillingModes.push(UCInputFieldFillingMode.AUTO_PRE);
     }

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

@@ -1,11 +1,35 @@
 import type { StringKeys } from '../utils/index.js';
 import type { UCInputFieldDef } from './input-field.js';
+/**
+ * Base interface all the use case input interfaces must extend
+ */
 export interface UCInput {
 }
+/**
+ * Definition of a use case input
+ */
 export interface UCInputDef<I extends UCInput> {
+    /**
+     * This is useful when you want to render a given field only after its dependent fields have been set.
+     */
     dependencies?: Partial<Record<StringKeys<I>, StringKeys<I>[]>>;
+    /**
+     * It must follow strictly the shape of the corresponding {@link UCInput} with fields sorted alphabetically.
+     */
     fields: Record<StringKeys<I>, UCInputFieldDef<any>>;
+    /**
+     * By default, the fields are displayed in the same order as in {@link fields} (i.e. alphabetically).
+     *
+     * You can customize this by specifying the desired order here.
+     *
+     * For example, when rendering a form, this is used.
+     */
     order?: StringKeys<I>[];
+    /**
+     * Cross-field validation rules
+     *
+     * For example, if you want the user to provide `a` OR `b` but not both.
+     */
     validation?: {
         or?: StringKeys<I>[];
     };

package/dist/esm/uc/lifecycle/client/IdleClientMain.js

@@ -7,6 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { injectable } from 'inversify';
 let IdleClientMain = class IdleClientMain {
     async exec(_props) {
+        // NOOP
     }
 };
 IdleClientMain = __decorate([

package/dist/esm/uc/lifecycle/server/IdleServerMain.js

@@ -7,6 +7,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { injectable } from 'inversify';
 let IdleServerMain = class IdleServerMain {
     async exec(_props) {
+        // Right now it's the same as IdleClientMain, but it's better to have 2 impls in case they need to diverge
+        // NOOP
     }
 };
 IdleServerMain = __decorate([

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

@@ -8,8 +8,19 @@ import type { UCInput } from './input.js';
 import type { UCOPIBase } from './opi.js';
 import type { UCOutputOrNothing } from './output.js';
 export interface UCManagerPersistOpts {
+    /**
+     * In case the use case relates to an existing aggregate, pass its `aggregateId` in this field.
+     * This is typically used in a `Delete` use case in order to link it to the `Create` one executed in the past.
+     */
     aggregateId?: UUID;
+    /**
+     * @defaultValue {@link UCExecMode.USER}
+     */
     executionMode?: UCExecMode;
+    /**
+     * In case the use case is performed by an anonymous user or a user outside the organization, pass the actual `organizationId` in this field.
+     * This is typically used in a use case where someone anonymous posts something for a specific organization in a multi-tenant architecture.
+     */
     organizationId?: UUID;
 }
 export interface UCManager {

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

@@ -1,8 +1,18 @@
 import type { AppName } from '../app/index.js';
 import type { IconCode } from '../icon/index.js';
+/**
+ * The type of action the use case performs
+ *
+ * This impacts the HTTP verb used in the transport layer for example.
+ */
 export type UCAction = 'Create' | 'Delete' | 'List' | 'Search' | 'Update' | 'View';
 export type UCName = Capitalize<string>;
 export type FQUCNameSeparator = '_';
+/**
+ * Fully qualified use case name
+ *
+ * It's made with the {@link AppName} and the {@link UCName} linked by {@link FQUCNameSeparator}.
+ */
 export type FQUCName = `${AppName}${FQUCNameSeparator}${UCName}`;
 export interface UCMetadata {
     action: UCAction;

package/dist/esm/uc/opi-layout.d.ts

@@ -7,6 +7,9 @@ export interface UCOPILayoutContext {
     availableWidthInPx: UIntQuantity;
     target: 'cli' | 'mobile' | 'web';
 }
+/**
+ * @alpha This feature is not fully ready yet.
+ */
 export type UCOPILayout<OPI extends UCOPIBase, LT extends UCOPILayoutType = UCOPILayoutType, LI extends UCOPILayoutInput = UCOPILayoutInput> = {
     get: (item: OPI, context: UCOPILayoutContext) => LI;
     type: LT;

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

@@ -1,6 +1,14 @@
 import type { DataType, UUID } from '../dt/index.js';
 import type { Value } from './value.js';
+/**
+ * Base interface all the use case OPI interfaces must extend
+ */
 export interface UCOPIBase {
     id: UUID;
 }
+/**
+ * A value returned as part of an OPI
+ *
+ * Unlike {@link UCInputFieldValue}, it cannot be `undefined` because it is not serializable in JSON.
+ */
 export type UCOPIValue<T extends DataType> = Exclude<Value<T>, undefined>;

package/dist/esm/uc/output-field.d.ts

@@ -1,8 +1,17 @@
 import type { DataType, TBase } from '../dt/index.js';
 import type { StringKeys } from '../utils/index.js';
 import type { UCOPIBase } from './opi.js';
+/**
+ * Definition of a use case output field
+ */
 export interface UCOutputFieldDef<OPI extends UCOPIBase, T extends DataType> {
+    /**
+     * Indicates another field of the output this field can potentially link to (in the `<a></a>` way).
+     */
     linksTo?: StringKeys<OPI>;
+    /**
+     * The aggregation method to use to present the summary of this field across all the corresponding items.
+     */
     totalType?: 'sum';
     type: TBase<T>;
 }

package/dist/esm/uc/output-part.d.ts

@@ -6,14 +6,36 @@ import type { UCOPILayout } from './opi-layout.js';
 import type { UCOPIBase } from './opi.js';
 import type { UCOutputFieldDef } from './output-field.js';
 export interface UCOutputPart<OPI extends UCOPIBase> {
+    /**
+     * The items making the part
+     */
     items: OPI[];
+    /**
+     * Pagination to pass to the next call of the use case.
+     */
     pagination?: ListInput;
+    /**
+     * The total number of items regardless pagination.
+     */
     total: UIntQuantity;
 }
 export type UCOutputPartDefFields<OPI extends UCOPIBase> = Record<StringKeys<OPI>, UCOutputFieldDef<OPI, any>>;
+/**
+ * Definition of a use case output part
+ */
 export interface UCOutputPartDef<OPI extends UCOPIBase> {
+    /**
+     * It must follow strictly the shape of the corresponding {@link UCOPIBase} with fields sorted alphabetically.
+     */
     fields: Omit<UCOutputPartDefFields<OPI>, 'id'>;
     layout?: UCOPILayout<OPI>;
+    /**
+     * By default, the fields are displayed in the same order as in {@link fields} (i.e. alphabetically).
+     *
+     * You can customize this by specifying the desired order here.
+     *
+     * For example, when rendering a card with the data, this is used.
+     */
     order?: StringKeys<OPI>[];
     related?: {
         global: UCDef<any, any, any>[];

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

@@ -10,6 +10,9 @@ export interface UCOutput<OPI0 extends UCOPIBase | undefined = undefined, OPI1 e
     };
 }
 export type UCOutputOrNothing<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> = UCOutput<OPI0, OPI1> | void;
+/**
+ * Definition of a use case output
+ */
 export interface UCOutputDef<OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> {
     parts?: {
         _0: UCOutputPartDef<NonNullable<OPI0>>;

package/dist/esm/uc/policies/RoleRegularUCPolicy.js

@@ -12,6 +12,7 @@ let RoleRegularUCPolicy = class RoleRegularUCPolicy {
     }
     async exec({ uc, }) {
         const out = defaultUCPolicyOutput();
+        // Note that this excludes admin as policies have no hierarchy.
         out.allowed = uc.auth?.role === 'regular';
         return out;
     }

package/dist/esm/uc/policies/funcs.js

@@ -1,5 +1,6 @@
 export function defaultUCPolicyOutput() {
     const out = {
+        // The stricter, the better for security
         allowed: false,
     };
     return out;

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

@@ -8,6 +8,28 @@ export interface UCPolicyInput<I extends UCInput | undefined = undefined, OPI0 e
 export interface UCPolicyOutput {
     allowed: boolean;
 }
+/**
+ * The policy defines the type(s) of user(s) who can perform the use case
+ *
+ * It corresponds more or less to RBAC (Resource Based Access Control).
+ *
+ * At this moment, for simplicity, ABAC (Attribute Based Access Control) must be done in the `main` of a use case.
+ * For example, if you have to check that a user must be the owner of a resource.
+ *
+ * The main reason for this choice at this moment, is to avoid "double-fetching" in the `policy` and in `main`.
+ *   1. Fetch the resource (e.g. by id) to check if the user is the owner => Accept
+ *   2. Fetch the resource again to perform actions on it
+ *
+ * A good solution for this would be to pass the resources fetched from the `policy` to `main` but that is,
+ * at least for the moment, out of scope.
+ */
 export interface UCPolicy<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined> extends Worker<UCPolicyInput<I, OPI0, OPI1>, Promise<UCPolicyOutput>> {
+    /**
+     * Determines whether the policy check can be executed before checking the auth
+     *
+     * For example, for {@link NobodyUCPolicy}, we know that there is no need to check the auth,
+     * as the policy will always return false. The same goes for {@link EverybodyUCPolicy} but
+     * in the opposite way.
+     */
     canBeExecutedPreAuth(): Promise<boolean>;
 }

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

@@ -1,6 +1,15 @@
 export type UCSecAuthType = 'apiKey' | 'basic' | 'jwt';
 export type UCSecPublicApiKeyCheckType = 'off' | 'on';
+/**
+ * Definition of the security scheme of a use case
+ */
 export interface UCSec {
+    /**
+     * @defaultValue {@link DEFAULT_UC_SEC_AT}
+     */
     authType?: UCSecAuthType;
+    /**
+     * @defaultValue {@link DEFAULT_UC_SEC_PAKCT}
+     */
     publicApiKeyCheckType?: UCSecPublicApiKeyCheckType;
 }