@lakutata/core 1.0.59 → 3.0.0-beta.0

package/dist/esm/lib/dto/internal/CronValidator.js

@@ -0,0 +1,125 @@
+const DEFAULT_OPTIONS = {
+    alias: false,
+    seconds: false,
+    allowBlankDay: false,
+    allowSevenAsSunday: false,
+    allowNthWeekdayOfMonth: false
+};
+const MONTH_ALIASES = {
+    jan: '1', feb: '2', mar: '3', apr: '4', may: '5', jun: '6', jul: '7', aug: '8', sep: '9', oct: '10', nov: '11', dec: '12'
+};
+const WEEKDAY_ALIASES = {
+    sun: '0', mon: '1', tue: '2', wed: '3', thu: '4', fri: '5', sat: '6'
+};
+/**
+ * The number of a field: only digits (parseInt() would read "1*" as 1)
+ * @param value
+ */
+function safeParseInt(value) {
+    return /^\d+$/.test(value) ? Number(value) : NaN;
+}
+function isInRange(value, start, stop) {
+    return value >= start && value <= stop;
+}
+/**
+ * A value, a range of values or a wildcard
+ * @param value
+ * @param start
+ * @param stop
+ */
+function isValidRange(value, start, stop) {
+    const sides = value.split('-');
+    switch (sides.length) {
+        case 1:
+            return value === '*' || isInRange(safeParseInt(value), start, stop);
+        case 2: {
+            const [small, big] = sides.map(safeParseInt);
+            return small <= big && isInRange(small, start, stop) && isInRange(big, start, stop);
+        }
+        default:
+            return false;
+    }
+}
+function isValidStep(value) {
+    return value === undefined || (value.search(/[^\d]/) === -1 && safeParseInt(value) > 0);
+}
+/**
+ * A list of values, ranges or wildcards with their steps
+ * @param value
+ * @param start
+ * @param stop
+ */
+function validateForRange(value, start, stop) {
+    if (value.search(/[^\d-,\/*]/) !== -1)
+        return false;
+    return value.split(',').every((condition) => {
+        const splits = condition.split('/');
+        //"*/" has no step, "*/*/*" several
+        if (condition.trim().endsWith('/') || splits.length > 2)
+            return false;
+        return isValidRange(splits[0], start, stop) && isValidStep(splits[1]);
+    });
+}
+/**
+ * The names replaced by their numbers
+ * @param value
+ * @param aliases
+ */
+function unalias(value, aliases) {
+    return value.toLowerCase().replace(/[a-z]{3}/g, (match) => aliases[match] ?? match);
+}
+function hasValidDays(days, allowBlankDay) {
+    return (allowBlankDay && days === '?') || validateForRange(days, 1, 31);
+}
+function hasValidMonths(months, alias) {
+    //A name is not a step
+    if (months.search(/\/[a-zA-Z]/) !== -1)
+        return false;
+    //An unknown name is left, the validation of the numbers rejects it
+    return validateForRange(alias ? unalias(months, MONTH_ALIASES) : months, 1, 12);
+}
+function hasValidWeekdays(weekdays, options) {
+    if (weekdays === '?')
+        return options.allowBlankDay;
+    //A name is not a step
+    if (weekdays.search(/\/[a-zA-Z]/) !== -1)
+        return false;
+    const remapped = options.alias ? unalias(weekdays, WEEKDAY_ALIASES) : weekdays;
+    const maxWeekday = options.allowSevenAsSunday ? 7 : 6;
+    const splitByHash = remapped.split('#');
+    //The nth weekday of the month (Quartz): weekday#occurrence
+    if (options.allowNthWeekdayOfMonth && splitByHash.length >= 2) {
+        const [weekday, occurrence, ...leftOvers] = splitByHash;
+        if (leftOvers.length)
+            return false;
+        return isInRange(safeParseInt(occurrence), 1, 5) && isInRange(safeParseInt(weekday), 0, maxWeekday);
+    }
+    return validateForRange(remapped, 0, maxWeekday);
+}
+/**
+ * Whether a cron expression is valid: five fields (minutes, hours, days, months, weekdays), or six with the seconds
+ * first when they are allowed
+ * @param cron
+ * @param partialOptions
+ */
+export function isValidCron(cron, partialOptions) {
+    const options = { ...DEFAULT_OPTIONS, ...partialOptions };
+    const splits = cron.trim().split(/\s+/);
+    if (splits.length > (options.seconds ? 6 : 5) || splits.length < 5)
+        return false;
+    const checks = [];
+    if (splits.length === 6) {
+        const seconds = splits.shift();
+        if (seconds)
+            checks.push(validateForRange(seconds, 0, 59));
+    }
+    const [minutes, hours, days, months, weekdays] = splits;
+    checks.push(validateForRange(minutes, 0, 59));
+    checks.push(validateForRange(hours, 0, 23));
+    checks.push(hasValidDays(days, options.allowBlankDay));
+    checks.push(hasValidMonths(months, options.alias));
+    checks.push(hasValidWeekdays(weekdays, options));
+    //Not both days blank
+    checks.push(!(options.allowBlankDay && days === '?' && weekdays === '?'));
+    return checks.every(Boolean);
+}

package/dist/esm/lib/foundation/BasicInfo.js

@@ -0,0 +1,106 @@
+import { As } from '@lakutata/utils/As';
+import { throwWarning } from './ThrowWarning.js';
+/**
+ * An environment variable, read by its computed name: the bundlers replace the reads of process.env.NODE_ENV with the
+ * mode of their build (Bun: "development"), the mode of the run would be lost
+ * @param name
+ */
+function variable(name) {
+    return process.env[name];
+}
+/**
+ * A mode of the environment (development or production, in any case), undefined for the other values
+ * @param value
+ */
+function modeOf(value) {
+    const mode = value?.trim().toLowerCase();
+    return mode === 'development' || mode === 'production' ? mode : undefined;
+}
+/**
+ * The mode of the application: the environment overrides the options (the same build runs in each mode). The one of
+ * the MODE environment variable (the one of lakutata), of NODE_ENV, of the options, development otherwise. A MODE
+ * which is not a mode is warned of and left; a NODE_ENV which is not a mode (test) is left
+ * @param configured the mode of the options of the application
+ */
+export function resolveMode(configured) {
+    const mode = modeOf(variable('MODE'));
+    if (mode)
+        return mode;
+    if (variable('MODE')?.trim())
+        throwWarning(`The MODE environment variable "${variable('MODE')}" is not a mode (development, production), it is ignored`);
+    return modeOf(variable('NODE_ENV')) ?? configured ?? 'development';
+}
+/**
+ * The mode of the application running: the one written to MODE and NODE_ENV when it launched, development otherwise
+ */
+export function currentMode() {
+    return modeOf(variable('MODE')) ?? modeOf(variable('NODE_ENV')) ?? 'development';
+}
+/**
+ * Whether a time zone is known by the runtime: the canonical IANA names and their aliases ("UTC", "Etc/GMT+8", "US/Eastern")
+ * @param timezone
+ */
+function isTimezone(timezone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether passed timezone parameter is a valid timezone string or not
+ * If passed timezone is valid, return the timezone string, else return default timezone string
+ * @param timezone
+ * @constructor
+ */
+export function validateTimezone(timezone) {
+    const defaultTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (!isTimezone(timezone)) {
+        throwWarning(`The passed time zone "${timezone}" is invalid, use the default time zone "${defaultTimezone}"`);
+        return defaultTimezone;
+    }
+    return timezone;
+}
+/**
+ * Set application basic info
+ * @param info
+ * @constructor
+ */
+export function setBasicInfo(info) {
+    process.env.appId = info.appId;
+    process.env.appName = info.appName;
+    const timezone = info.timezone === 'auto' ? Intl.DateTimeFormat().resolvedOptions().timeZone : info.timezone;
+    process.env.TZ = validateTimezone(timezone);
+    //The mode in both variables: the libraries read NODE_ENV, the applications MODE too
+    process.env.NODE_ENV = info.mode;
+    process.env.MODE = info.mode;
+    return getBasicInfo();
+}
+/**
+ * Get application id (reads a single environment variable, much cheaper than getBasicInfo())
+ * @constructor
+ */
+export function getAppId() {
+    return process.env.appId || 'Unknown';
+}
+/**
+ * Get application name (reads a single environment variable, much cheaper than getBasicInfo())
+ * @constructor
+ */
+export function getAppName() {
+    return process.env.appName || 'Unknown';
+}
+/**
+ * Get application basic info
+ * @constructor
+ */
+export function getBasicInfo() {
+    return {
+        appId: getAppId(),
+        appName: getAppName(),
+        timezone: As(process.env.TZ),
+        mode: currentMode()
+    };
+}

package/dist/esm/lib/foundation/EndProcess.js

@@ -0,0 +1,26 @@
+/**
+ * The process is ending (EndProcess): the code given first is its exit code
+ */
+let ending = false;
+/**
+ * End the process with a code: it exits by itself, its work done (process.exitCode), else it is ended after a moment
+ * (an object keeping it running). Ended by process.exit at once, node crashes on Windows while the connections of fetch
+ * close (libuv: UV_HANDLE_CLOSING); the process exits by itself as soon as they are closed. The code given first is the
+ * exit code: the code still running once the application is destroyed (its launch going on after its exit) does not
+ * change it
+ * @param code
+ * @param grace the time it is given to exit by itself
+ */
+export function endProcess(code, grace = 500) {
+    if (ending)
+        return;
+    ending = true;
+    process.exitCode = code;
+    setTimeout(() => process.exit(code), grace).unref();
+}
+/**
+ * Whether the process is ending: the errors of the code still running are not the ones of the application
+ */
+export function isEnding() {
+    return ending;
+}

package/dist/esm/lib/foundation/Exception.js

@@ -0,0 +1,160 @@
+import { format as utilFormat } from 'node:util';
+import { getAppId, getAppName } from './BasicInfo.js';
+import { templating } from '@lakutata/utils/Templating';
+import { As } from '@lakutata/utils/As';
+import { camelCase } from '@lakutata/utils/CamelCase';
+import { DevNull } from '@lakutata/utils/DevNull';
+/**
+ * The placeholders of util.format() consuming an argument
+ */
+const PLACEHOLDERS = 'sdifjoOc';
+/**
+ * Format the placeholders of a message as util.format() of Node.js (%s, %d, %i, %f, %j, %o, %O, %c, %%): an unknown
+ * placeholder, a placeholder without argument and a % alone are kept; the arguments left are not appended (they are
+ * the data of the templates too); a placeholder its argument cannot be formatted by (%j of a bigint) is kept, the
+ * creation of an exception never throws
+ * @param template
+ * @param args
+ */
+function format(template, ...args) {
+    if (!args.length)
+        return template;
+    let result = '';
+    let lastPosition = 0;
+    let argument = 0;
+    for (let i = 0; i < template.length - 1; i++) {
+        if (template[i] !== '%')
+            continue;
+        const placeholder = template[++i];
+        if (argument < args.length && PLACEHOLDERS.includes(placeholder)) {
+            let formatted;
+            try {
+                formatted = placeholder === 'c' ? '' : utilFormat(`%${placeholder}`, args[argument]);
+            }
+            catch {
+                formatted = `%${placeholder}`;
+            }
+            result += template.slice(lastPosition, i - 1) + formatted;
+            argument++;
+            lastPosition = i + 1;
+        }
+        else if (placeholder === '%') {
+            result += template.slice(lastPosition, i);
+            lastPosition = i + 1;
+        }
+    }
+    return result + template.slice(lastPosition);
+}
+/**
+ * The parameters of the template of the message of an exception
+ */
+const PARAMS = Symbol('EXCEPTION.PARAMS');
+/**
+ * Read the parameters an exception's message template was formatted with (`new XxxException('Order {id} not found',
+ * {id: 1})`), to translate the message into another language with the same values.
+ * @param exception The error to read; any error is accepted.
+ * @returns The object given as the single parameter, the parameters as an array when several (or a single non-object
+ * one) were given, or undefined when the exception was created without parameters or is not an {@link Exception}.
+ * @example
+ * ```typescript
+ * import {Exception, exceptionParams} from 'lakutata'
+ *
+ * class OrderNotFoundException extends Exception {
+ *     public errno: string = 'E_ORDER_NOT_FOUND'
+ * }
+ *
+ * const error: OrderNotFoundException = new OrderNotFoundException('Order {id} not found', {id: 1})
+ * console.log(error.message) //Order 1 not found
+ * console.log(exceptionParams(error)) //{id: 1}
+ * ```
+ */
+export function exceptionParams(exception) {
+    return exception[PARAMS];
+}
+/**
+ * The base class of the framework's exceptions, and of the applications' own: extend it, set its `errno` and, for the
+ * errors sent to clients, its `statusCode`. The entrypoints send `errno`, `errMsg` and `statusCode` to the clients, and
+ * the HTTP adapters reply with `statusCode`.
+ *
+ * The message is built from the constructor arguments:
+ * - `new XxxException('Order {id} not found', {id: 1})`: a template, its `{name}` placeholders filled from an object, or
+ *   its `{0}`, `{1}` placeholders from the parameters given one by one (`new XxxException('{0} of {1}', a, b)`) or from
+ *   an array; the `util.format()` placeholders (`%s`, `%d`, `%j`…) are filled from the parameters too. A missing value
+ *   leaves its placeholder in the message; building the message never throws.
+ * - `new XxxException('Order not found')`: the message as given.
+ * - `new XxxException(error)`: the message of another error.
+ * - `new XxxException()`: a message made from the class name.
+ *
+ * The template parameters are kept for the translation of the message, see {@link exceptionParams}.
+ * @example
+ * ```typescript
+ * import {Exception} from 'lakutata'
+ *
+ * export class OrderNotFoundException extends Exception {
+ *     public errno: string = 'E_ORDER_NOT_FOUND'
+ *
+ *     public readonly statusCode: number = 404
+ * }
+ *
+ * export function findOrder(id: number): never {
+ *     throw new OrderNotFoundException('Order {id} not found', {id: id})
+ * }
+ * ```
+ */
+export class Exception extends Error {
+    constructor(a, ...b) {
+        super();
+        /**
+         * The ID of the application the exception was created in, "Unknown" before the application's options are loaded.
+         */
+        this.appId = getAppId();
+        /**
+         * The name of the application the exception was created in, "Unknown" before the application's options are loaded.
+         */
+        this.appName = getAppName();
+        /**
+         * The HTTP status the HTTP entrypoints reply with when the exception fails a request; a subclass overrides it
+         * (404 for a missing resource…).
+         * @default 500
+         */
+        this.statusCode = 500;
+        if (b.length) {
+            const template = a;
+            const templatingArgs = b.length > 1 ? b : b[0];
+            //Kept for the translations of the message, not an enumerable property (the errors sent are not changed)
+            Object.defineProperty(this, PARAMS, { value: b.length > 1 || typeof b[0] !== 'object' || b[0] === null ? b : b[0], enumerable: false });
+            try {
+                this.message = templating(template, templatingArgs, { ignoreMissing: true });
+            }
+            catch (e) {
+                this.message = template;
+                DevNull(e);
+            }
+            this.message = format(this.message, ...b);
+        }
+        else if (a) {
+            if (typeof (a) === 'string') {
+                //Error message
+                this.message = a;
+            }
+            else {
+                //Error instance
+                this.message = As(a).message;
+            }
+        }
+        else {
+            //Empty message
+            const message = camelCase(this.name).toLowerCase();
+            this.message = `${message.charAt(0).toUpperCase()}${message.slice(1)}`;
+        }
+        this.errMsg = this.message;
+        this.err = this.name;
+    }
+    /**
+     * The name of the exception: the name of its class.
+     * @returns The class name.
+     */
+    get name() {
+        return this.constructor.name;
+    }
+}

package/dist/esm/lib/foundation/LifecycleErrorReporter.js

@@ -0,0 +1,59 @@
+import { throwWarning } from './ThrowWarning.js';
+const defaultLifecycleErrorReporter = (error, message) => {
+    throwWarning(`${message}: ${error.stack ? error.stack : error.message}`);
+};
+let lifecycleErrorReporter = defaultLifecycleErrorReporter;
+/**
+ * Set the reporter of the errors of the lifecycle of the objects, pass nothing to restore the default reporter
+ * (process warning)
+ * @param reporter
+ * @constructor
+ */
+export function setLifecycleErrorReporter(reporter) {
+    lifecycleErrorReporter = reporter ? reporter : defaultLifecycleErrorReporter;
+}
+/**
+ * Flatten aggregated errors, keeping the message of every enclosing aggregate as context
+ * @param error
+ * @param context
+ */
+function flatten(error, context) {
+    if (error instanceof AggregateError)
+        return error.errors.flatMap((item) => flatten(item, error.message));
+    const item = error instanceof Error ? error : new Error(String(error));
+    return [context ? new Error(`${context}: ${item.message}`, { cause: item }) : item];
+}
+/**
+ * Report errors, a reporter failure never breaks the lifecycle
+ * @param errors
+ * @param message
+ */
+function report(errors, message) {
+    for (const error of errors) {
+        try {
+            lifecycleErrorReporter(error, message);
+        }
+        catch {
+            //A broken reporter must not break the lifecycle
+        }
+    }
+}
+/**
+ * Report an error raised by cascaded destruction
+ * @param error
+ * @param objectName name of the object whose teardown failed
+ * @constructor
+ */
+export function reportDestroyError(error, objectName) {
+    const context = objectName && !(error instanceof AggregateError) ? `Failed to destroy object "${objectName}"` : undefined;
+    report(flatten(error, context), 'An error occurred while destroying an object');
+}
+/**
+ * Report an error raised by the launched() hook of an object
+ * @param error
+ * @param objectName
+ * @constructor
+ */
+export function reportLaunchedError(error, objectName) {
+    report(flatten(error, `Failed to run the launched() hook of object "${objectName}"`), 'An error occurred in the launched() hook of an object');
+}

package/dist/esm/lib/foundation/Packaging.js

@@ -0,0 +1,38 @@
+/**
+ * The global symbol the packed applications (the bundles and the executables of lakutata) are given by their first
+ * code: the directory of their resources
+ */
+const PACKAGED = Symbol.for('lakutata.packaged');
+/**
+ * Tell whether the application runs packed: bundled by `lakutata package bundle`, or inside a single executable built by
+ * `lakutata package exe`.
+ * @returns `true` when packed, `false` when it runs from its sources or its build (in development).
+ * @example
+ * ```typescript
+ * import {isPackaged} from 'lakutata'
+ *
+ * //The updates are only checked by the released builds
+ * if (isPackaged()) console.log('Running the released build')
+ * ```
+ */
+export function isPackaged() {
+    return !!globalThis[PACKAGED];
+}
+/**
+ * Get the directory of the resources of a packed application: the files declared by the `lakutata.resources` field of
+ * its package.json, at their `to` paths (extracted first when it runs in a single executable).
+ * @returns The absolute path of the directory, or `undefined` when the application does not run packed: it then locates
+ * its resources itself (in development, the directory they are built in).
+ * @example
+ * ```typescript
+ * import path from 'node:path'
+ * import {resourcesPath} from 'lakutata'
+ *
+ * //The web UI served by the application: its packed copy, or its build in development
+ * const resources: string | undefined = resourcesPath()
+ * const ui: string = resources ? path.join(resources, 'ui') : path.resolve('ui', 'dist')
+ * ```
+ */
+export function resourcesPath() {
+    return globalThis[PACKAGED]?.resources();
+}

package/dist/esm/lib/foundation/ThrowWarning.js

@@ -0,0 +1,13 @@
+class Warning extends Error {
+    get name() {
+        return this.constructor.name;
+    }
+}
+/**
+ * Throw warning message through process
+ * @param message
+ * @constructor
+ */
+export function throwWarning(message) {
+    return process.emit('warning', new Warning(message));
+}

package/dist/esm/lib/helpers/internal/WithCause.js

@@ -0,0 +1,9 @@
+/**
+ * Set the cause of an exception (the error it wraps) and return the exception
+ * @param exception
+ * @param cause
+ */
+export function withCause(exception, cause) {
+    exception.cause = cause;
+    return exception;
+}

package/dist/esm/lib/ioc/ConstructorSymbol.js

@@ -0,0 +1,17 @@
+import { DI_TARGET_CONSTRUCTOR_SYMBOL } from '../../constants/DIMetadataKey.js';
+import { randomUUID } from 'node:crypto';
+const symbolConstructorMap = new Map();
+export function constructorSymbol(constructor) {
+    if (!Reflect.hasOwnMetadata(DI_TARGET_CONSTRUCTOR_SYMBOL, constructor)) {
+        const uuidSymbol = Symbol(randomUUID());
+        symbolConstructorMap.set(uuidSymbol, constructor.name);
+        Reflect.defineMetadata(DI_TARGET_CONSTRUCTOR_SYMBOL, uuidSymbol, constructor);
+    }
+    return Reflect.getOwnMetadata(DI_TARGET_CONSTRUCTOR_SYMBOL, constructor);
+}
+export function resolveConstructorNameBySymbol(symbol) {
+    const realName = symbolConstructorMap.get(symbol);
+    if (realName)
+        return realName;
+    return symbol;
+}