@ti-engine/core 1.8.1 → 1.9.0

package/types/utils/exceptions.d.ts

@@ -0,0 +1,224 @@
+export { exceptionCodeEnum as exceptionCode };
+export { httpCodeEnum as httpCode };
+export { TiException };
+export declare var raise: (source: any, data: any, exceptionID?: undefined, httpCode?: undefined) => TiException;
+export declare var isException: (object: any) => boolean;
+export type TiExceptionCode = number;
+/**
+ * Enum for listing all system-recognized exceptions.
+ *
+ * @readonly
+ * @enum {number}
+ * @typedef {number} TiExceptionCode
+ */
+declare const exceptionCodeEnum: import("../components/definitions.types").TiEnumOf<{
+    E_UNKNOWN_ERROR: (string | number)[];
+    /** General exceptions - codes under 1xxx */
+    E_GEN_JS_INTERNAL_ERROR: (string | number)[];
+    E_GEN_ABSTRACT_CLASS_INIT: (string | number)[];
+    E_GEN_ABSTRACT_METHOD_CALL: (string | number)[];
+    E_GEN_INVALID_SERVICE_DOMAIN_NAME: (string | number)[];
+    E_GEN_SYSTEM_CACHE_UNAVAILABLE: (string | number)[];
+    E_GEN_BAD_SERVICE_HANDLER: (string | number)[];
+    E_GEN_FEATURE_UNSUPPORTED: (string | number)[];
+    E_GEN_INVALID_ARGUMENT_TYPE: (string | number)[];
+    E_GEN_NOT_INITIALIZED: (string | number)[];
+    E_GEN_UNALLOWED_OVERRIDE: (string | number)[];
+    E_GEN_NOT_IMPLEMENTED: (string | number)[];
+    /** Security & Administration exceptions - codes under 2xxx */
+    E_SEC_INVALID_AUTH_TOKEN: (string | number)[];
+    E_SEC_INVALID_EXPIRED_SESSION: (string | number)[];
+    E_SEC_UNAUTHORIZED_ACCESS: (string | number)[];
+    E_SEC_MESSAGE_TAMPERING_DETECTED: (string | number)[];
+    E_SEC_UNRECOGNIZED_AUTH_METHOD: (string | number)[];
+    /** Cross-Application Communication exceptions - codes under 3xxx */
+    E_COM_GENERAL_ERROR: (string | number)[];
+    E_COM_MESSAGE_SENDER_UNAVAILABLE: (string | number)[];
+    E_COM_SERVICE_EXEC_TIMEOUT: (string | number)[];
+    E_COM_SERVICE_NOT_REGISTERED: (string | number)[];
+    E_COM_SERVICE_NOT_FOUND: (string | number)[];
+    E_COM_SERVICE_HANDLER_NOT_FOUND: (string | number)[];
+    E_COM_MESSAGE_RECEIVER_UNAVAILABLE: (string | number)[];
+    E_COM_MESSAGE_EXCHANGE_BROKEN: (string | number)[];
+    E_COM_SERVICE_EXEC_FAILED: (string | number)[];
+    E_COM_RETRY_ATTEMPTS_EXCEEDED: (string | number)[];
+    /** Web server exceptions - codes under 4xxx */
+    E_WEB_INVALID_REQUEST_METHOD: (string | number)[];
+    E_WEB_INVALID_REQUEST_URI: (string | number)[];
+    E_WEB_INVALID_REQUEST_BODY: (string | number)[];
+    E_WEB_INVALID_REQUEST_QUERY: (string | number)[];
+    E_WEB_INVALID_REQUEST_HEADERS: (string | number)[];
+    E_WEB_INVALID_REQUEST_PARAMETERS: (string | number)[];
+    E_WEB_INVALID_REQUEST_FORMAT: (string | number)[];
+    E_WEB_INVALID_REQUEST_CONTENT_TYPE: (string | number)[];
+    E_WEB_INVALID_REQUEST_CONTENT_LENGTH: (string | number)[];
+    E_WEB_INVALID_REQUEST_CONTENT_ENCODING: (string | number)[];
+    /** Application exceptions - codes under 5xxx */
+    E_APP_RESOURCE_NOT_FOUND: (string | number)[];
+    E_APP_SERVICE_ERROR: (string | number)[];
+    E_APP_RESOURCE_ALREADY_EXISTS: (string | number)[];
+}>;
+export type TiHttpCode = number;
+/**
+ * Enum for listing all HTTP codes.
+ *
+ * @readonly
+ * @enum {number}
+ * @typedef {number} TiHttpCode
+ */
+declare const httpCodeEnum: import("../components/definitions.types").TiEnumOf<{
+    /** 1xx informational response */
+    C_100: (string | number)[];
+    C_101: (string | number)[];
+    C_102: (string | number)[];
+    C_103: (string | number)[];
+    /** 2xx success */
+    C_200: (string | number)[];
+    C_201: (string | number)[];
+    C_202: (string | number)[];
+    C_203: (string | number)[];
+    C_204: (string | number)[];
+    C_205: (string | number)[];
+    C_206: (string | number)[];
+    C_207: (string | number)[];
+    C_208: (string | number)[];
+    C_226: (string | number)[];
+    /** 3xx redirection */
+    C_300: (string | number)[];
+    C_301: (string | number)[];
+    C_302: (string | number)[];
+    C_303: (string | number)[];
+    C_304: (string | number)[];
+    C_307: (string | number)[];
+    C_308: (string | number)[];
+    /** 4xx client errors */
+    C_400: (string | number)[];
+    C_401: (string | number)[];
+    C_403: (string | number)[];
+    C_404: (string | number)[];
+    C_405: (string | number)[];
+    C_406: (string | number)[];
+    C_407: (string | number)[];
+    C_408: (string | number)[];
+    C_409: (string | number)[];
+    C_410: (string | number)[];
+    C_411: (string | number)[];
+    C_412: (string | number)[];
+    C_413: (string | number)[];
+    C_414: (string | number)[];
+    C_415: (string | number)[];
+    C_416: (string | number)[];
+    C_417: (string | number)[];
+    C_421: (string | number)[];
+    C_422: (string | number)[];
+    C_423: (string | number)[];
+    C_424: (string | number)[];
+    C_425: (string | number)[];
+    C_426: (string | number)[];
+    C_428: (string | number)[];
+    C_429: (string | number)[];
+    C_431: (string | number)[];
+    C_451: (string | number)[];
+    /** 5xx server errors */
+    C_500: (string | number)[];
+    C_501: (string | number)[];
+    C_502: (string | number)[];
+    C_503: (string | number)[];
+    C_504: (string | number)[];
+    C_505: (string | number)[];
+    C_506: (string | number)[];
+    C_507: (string | number)[];
+    C_508: (string | number)[];
+    C_510: (string | number)[];
+    C_511: (string | number)[];
+}>;
+/**
+ * Represents an any-purpose exception.
+ *
+ * @class TiException
+ * @public
+ */
+declare class TiException {
+    #private;
+    /**
+     * @constructor
+     * @param {string} id The unique ID to be assigned to this exception.
+     * @param {TiExceptionCode} exceptionCode An unique exception identifier. If this is not recognized, the default error code will be used instead.
+     * @param {Object} [data={}] Any additional data to insert into the exception.
+     * @param {string} [description=undefined] Description of the exception.
+     */
+    constructor(id: string, exceptionCode: TiExceptionCode, data?: Object, description?: string);
+    /**
+     * Unique identifier of the exception instance. Can be used for tracing problems with customer support cases.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get id(): string;
+    /**
+     * Identifier code of the exception type.
+     *
+     * @property
+     * @returns {TiExceptionCode}
+     * @public
+     */
+    get code(): TiExceptionCode;
+    /**
+     * HTTP error code if relevant.
+     *
+     * @property
+     * @returns {TiHttpCode}
+     * @public
+     */
+    get httpCode(): TiHttpCode;
+    /**
+     * HTTP error code if relevant.
+     *
+     * @property
+     * @param {TiHttpCode} httpCode
+     * @public
+     */
+    set httpCode(httpCode: TiHttpCode);
+    /**
+     * Localized label identifier.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get label(): string;
+    /**
+     * Description or additional technical information that is NOT localized.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get description(): string;
+    /**
+     * JSON containing any additional data that has relevance for the exception. Can be converted JavaScript {@link Error} object as well.
+     *
+     * @property
+     * @returns {Object}
+     * @public
+     */
+    get data(): Object;
+    /**
+     * JSON containing any additional data that has relevance for the exception. Can be converted JavaScript {@link Error} object as well.
+     *
+     * @property
+     * @param {Object} data
+     * @public
+     */
+    set data(data: Object);
+    /**
+     * Extracts the essential information about the {@link TiException} and returns it as JSON.
+     *
+     * @method
+     * @param {boolean} [includeData=true] Whether to include the data property in the output.
+     * @returns {Object}
+     * @public
+     */
+    asJSON(includeData?: boolean): Object;
+}

package/types/utils/localization.d.ts

@@ -0,0 +1,194 @@
+export { localizationLanguageEnum as localizationLanguage };
+export declare var getLabel: (label: string, language?: TiLocalizationLanguage) => string;
+export declare var getAllLabels: (language?: TiLocalizationLanguage) => TiLabelsTree;
+export type TiLocalizationLanguage = string;
+/**
+ * Enum for defining a localization language based on the ISO 639-1 language code.
+ *
+ * @readonly
+ * @enum {string}
+ * @typedef {string} TiLocalizationLanguage
+ */
+declare const localizationLanguageEnum: import("#definitions").TiEnumOf<{
+    ABKHAZIAN: string[];
+    AFAR: string[];
+    AFRIKAANS: string[];
+    AKAN: string[];
+    ALBANIAN: string[];
+    AMHARIC: string[];
+    ARABIC: string[];
+    ARAGONESE: string[];
+    ARMENIAN: string[];
+    ASSAMESE: string[];
+    AVARIC: string[];
+    AVESTAN: string[];
+    AYMARA: string[];
+    AZERBAIJANI: string[];
+    BAMBARA: string[];
+    BASHKIR: string[];
+    BASQUE: string[];
+    BELARUSIAN: string[];
+    BENGALI: string[];
+    BIHARI_LANGUAGES: string[];
+    BISLAMA: string[];
+    BOSNIAN: string[];
+    BRETON: string[];
+    BULGARIAN: string[];
+    BURMESE: string[];
+    CATALAN: string[];
+    CENTRAL_KHMER: string[];
+    CHAMORRO: string[];
+    CHECHEN: string[];
+    CHICHEWA: string[];
+    CHINESE: string[];
+    CHURCH_SLAVIC: string[];
+    CHUVASH: string[];
+    CORNISH: string[];
+    CORSICAN: string[];
+    CREE: string[];
+    CROATIAN: string[];
+    CZECH: string[];
+    DANISH: string[];
+    DIVEHI: string[];
+    DUTCH: string[];
+    DZONGKHA: string[];
+    ENGLISH: string[];
+    ESPERANTO: string[];
+    ESTONIAN: string[];
+    EWE: string[];
+    FAROESE: string[];
+    FIJIAN: string[];
+    FINNISH: string[];
+    FRENCH: string[];
+    FULAH: string[];
+    FRISIAN_WESTERN: string[];
+    GAELIC_SCOTTISH: string[];
+    GALICIAN: string[];
+    GANDA: string[];
+    GEORGIAN: string[];
+    GERMAN: string[];
+    GREEK_MODERN: string[];
+    GUARANI: string[];
+    GUJARATI: string[];
+    HAITIAN: string[];
+    HAUSA: string[];
+    HEBREW: string[];
+    HERERO: string[];
+    HINDI: string[];
+    HIRI_MOTU: string[];
+    HUNGARIAN: string[];
+    ICELANDIC: string[];
+    IDO: string[];
+    IGBO: string[];
+    INTERLINGUA: string[];
+    INTERLINGUE: string[];
+    INDONESIAN: string[];
+    INUKTITUT: string[];
+    INUPIAQ: string[];
+    IRISH: string[];
+    ITALIAN: string[];
+    JAPANESE: string[];
+    JAVANESE: string[];
+    KALAALLISUT: string[];
+    KANNADA: string[];
+    KASHMIRI: string[];
+    KAZAKH: string[];
+    KIKUYU: string[];
+    KINYARWANDA: string[];
+    KIRGHIZ: string[];
+    KOMI: string[];
+    KONGO: string[];
+    KOREAN: string[];
+    KUANYAMA: string[];
+    KURDISH: string[];
+    LAO: string[];
+    LATIN: string[];
+    LATVIAN: string[];
+    LIMBURGAN: string[];
+    LINGALA: string[];
+    LITHUANIAN: string[];
+    LUBA_KATANGA: string[];
+    LUXEMBOURGISH: string[];
+    MACEDONIAN: string[];
+    MALAGASY: string[];
+    MALAY: string[];
+    MALAYALAM: string[];
+    MALTESE: string[];
+    MANX: string[];
+    MAORI: string[];
+    MARATHI: string[];
+    MARSHALLESE: string[];
+    MONGOLIAN: string[];
+    NAURU: string[];
+    NAVAJO: string[];
+    NDEBELE_NORTH: string[];
+    NDEBELE_SOUTH: string[];
+    NDONGA: string[];
+    NEPALI: string[];
+    NORTHERN_SAMI: string[];
+    NORWEGIAN: string[];
+    NORWEGIAN_BOKMAL: string[];
+    NORWEGIAN_NYNORSK: string[];
+    OCCITAN: string[];
+    OJIBWA: string[];
+    ORIYA: string[];
+    OROMO: string[];
+    OSSETIAN: string[];
+    PANJABI: string[];
+    PALI: string[];
+    PASHTO: string[];
+    POLISH: string[];
+    PORTUGUESE: string[];
+    QUECHUA: string[];
+    ROMANIAN: string[];
+    ROMANSH: string[];
+    RUNDI: string[];
+    RUSSIAN: string[];
+    SANGO: string[];
+    SANSKRIT: string[];
+    SARDINIAN: string[];
+    SERBIAN: string[];
+    SHONA: string[];
+    SINDHI: string[];
+    SINHALA: string[];
+    SLOVAK: string[];
+    SLOVENIAN: string[];
+    SOMALI: string[];
+    SOTHO_SOUTHERN: string[];
+    SPANISH: string[];
+    SUNDANESE: string[];
+    SWAHILI: string[];
+    SWATI: string[];
+    SWEDISH: string[];
+    TAGALOG: string[];
+    TAHITIAN: string[];
+    TAJIK: string[];
+    TAMIL: string[];
+    TATAR: string[];
+    TELUGU: string[];
+    THAI: string[];
+    TIBETAN: string[];
+    TIGRINYA: string[];
+    TONGA: string[];
+    TSONGA: string[];
+    TSWANA: string[];
+    TURKISH: string[];
+    TURKMEN: string[];
+    TWI: string[];
+    UIGHUR: string[];
+    UKRAINIAN: string[];
+    URDU: string[];
+    UZBEK: string[];
+    VENDA: string[];
+    VIETNAMESE: string[];
+    VOLAPUK: string[];
+    WALLON: string[];
+    WELSH: string[];
+    WOLOF: string[];
+    XHOSA: string[];
+    YIDDISH: string[];
+    YORUBA: string[];
+    ZHUANG: string[];
+    ZULU: string[];
+}>;
+import type { TiLabelsTree } from "#definitions";

package/types/utils/logger.d.ts

@@ -0,0 +1,24 @@
+export { logSeverityEnum as logSeverity };
+export declare var getSeverityName: (severity: TiLogSeverity) => string;
+export declare var log: (message: string, level?: TiLogSeverity, data?: Object | Error | TiException, thread?: string) => void;
+import type { TiException } from "#exceptions";
+export type TiLogSeverity = number;
+/** @import { TiException } from "#exceptions" */
+/**
+ * Enum for specifying the log entry severity. This is based on the Google Stackdriver severity levels.
+ *
+ * @readonly
+ * @enum {number}
+ * @typedef {number} TiLogSeverity
+ */
+declare const logSeverityEnum: import("../components/definitions.types").TiEnumOf<{
+    DEFAULT: (string | number)[];
+    DEBUG: (string | number)[];
+    INFO: (string | number)[];
+    NOTICE: (string | number)[];
+    WARNING: (string | number)[];
+    ERROR: (string | number)[];
+    CRITICAL: (string | number)[];
+    ALERT: (string | number)[];
+    EMERGENCY: (string | number)[];
+}>;

package/types/utils/tools.d.ts

@@ -0,0 +1,70 @@
+export declare var getUUID: () => string;
+export declare var deepFreeze: (object: Object, seen?: WeakSet<any>) => Object;
+export { createEnum as enum };
+export declare var getEnumName: (enumList: TiEnum, enumValue: number | string, placeholder?: string) => string | undefined;
+export declare var errorToJSON: (value: Error) => Object;
+export declare var toBool: (value: any) => boolean;
+export declare var arrayUniques: (array: any[]) => any[];
+export declare var getUTCDateString: (date: Date) => string;
+export declare var getUTCTimeString: (date: Date, useMilliseconds?: boolean) => string;
+export declare var decycle: (object: Object, replacer?: (value: Object) => Object) => Object;
+export declare var retrocycle: ($: Object) => Object;
+export declare var stringifyJSON: (value: Object) => string | any;
+export declare var isJsonString: (string: string) => boolean;
+export declare var parseJSON: (value: string) => Object | string;
+export declare var decomposeJSON: (input: Object) => string | null;
+export declare var constantTimeEquals: (a: any, b: any) => boolean;
+export { RetryPolicy };
+import type { TiEnum, TiEnumOf } from "#definitions";
+/**
+ * Used to create a custom Enum list.
+ *
+ * @method
+ * @template {Record<string,*>} T
+ * @param {T} seed
+ * @returns {TiEnumOf<T>}
+ * @public
+ */
+declare const createEnum: <T extends Record<string, any>>(seed: T) => TiEnumOf<T>;
+/**
+ * Used to create retry policy for the execution of an operation.
+ *
+ * @class RetryPolicy
+ * @public
+ */
+declare class RetryPolicy {
+    #private;
+    /**
+     * @constructor
+     * @param {number} maxAttempts The maximum number of attempts to execute the operation.
+     * @throws {TypeError} maxAttempts must be a positive integer.
+     */
+    constructor(maxAttempts: number);
+    /**
+     * Used to start execution of the provided operation.
+     *
+     * @method
+     * @param {Object} context The context in which the operation will be executed (i.e., this reference).
+     * @param {(...args: *[]) => Promise<*>} operation Operation to be executed; must return a Promise.
+     * @param {Array<*>} [params=[]] The arguments to be provided to the operation upon execution.
+     * @returns {Promise}
+     * @public
+     */
+    execute(context: Object, operation: (...args: any[]) => Promise<any>, params?: Array<any>): Promise<any>;
+    /**
+     * Used to register a method that will be automatically called on a failed execution attempt.
+     *
+     * @method
+     * @param {(error: Error) => void} action The execution error will be provided as an argument.
+     * @public
+     */
+    onFailedAttempt(action: (error: Error) => void): void;
+    /**
+     * Used to register a method that will be automatically called on each execution retry (after the initial one).
+     *
+     * @method
+     * @param {(attempt: number, lastError: Error|undefined) => void} action The current attempt and last error are provided.
+     * @public
+     */
+    onRetry(action: (attempt: number, lastError: Error | undefined) => void): void;
+}

package/utils/cache.js

@@ -758,7 +758,6 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string|string[]} path
      * @returns {string}
-     * @private
      */
     #normalizeJSONPath( path ) {
         if ( Array.isArray( path ) ) {

package/utils/exceptions.js

@@ -307,6 +307,8 @@ class TiException {
  * @returns {TiException}
  * @public
  */
+module.exports.TiException = TiException;
+
 module.exports.raise = ( source, data, exceptionID = undefined, httpCode = undefined ) => {
     /** @type TiException */
     let exception;

package/utils/localization.js

@@ -233,6 +233,8 @@ module.exports.localizationLanguage = localizationLanguageEnum;
 /** @type {TiLabelsTree} */
 const labels = require( "#labels" );
 
+/** @import { TiLabelsTree } from "#definitions" */
+
 // Load any custom labels defined in the configuration:
 const labelsPaths = config.getSetting( config.setting.LOCALIZATION_LABELS_PATH );
 if ( labelsPaths && _.isArray( labelsPaths ) && labelsPaths.length > 0 ) {

package/utils/logger.js

@@ -11,6 +11,8 @@ const tools = require( "#tools" );
 const exceptions = require( "#exceptions" );
 const localization = require( "#localization" );
 
+/** @import { TiException } from "#exceptions" */
+
 /**
  * Enum for specifying the log entry severity. This is based on the Google Stackdriver severity levels.
  *

package/utils/tools.js

@@ -9,6 +9,8 @@
 const _ = require( "lodash" );
 const crypto = require( "node:crypto" );
 
+/** @import { TiEnum, TiEnumOf } from "#definitions" */
+
 /**
  * Used to generate and return new UUID.
  *
@@ -45,8 +47,9 @@ module.exports.deepFreeze = ( object, seen = new WeakSet() ) => {
  * Used to create a custom Enum list.
  *
  * @method
- * @param {Object} seed
- * @returns {Object} This is a {@link TiEnum} object. Setting the proper reference here would unfortunately break IDE support.
+ * @template {Record<string,*>} T
+ * @param {T} seed
+ * @returns {TiEnumOf<T>}
  * @public
  */
 // Declared as a named constant and exported below rather than assigned straight onto `module.exports`:
@@ -285,7 +288,7 @@ module.exports.getUTCTimeString = ( date, useMilliseconds = false ) => {
  *
  * @method
  * @param {Object} object
- * @param {function( Object ): Object} [replacer]
+ * @param {(value: Object) => Object} [replacer]
  * @returns {Object}
  * @public
  */
@@ -555,7 +558,7 @@ class RetryPolicy {
      *
      * @method
      * @param {Object} context The context in which the operation will be executed (i.e., this reference).
-     * @param {function( ...* ): Promise<*>} operation Operation to be executed; must return a Promise.
+     * @param {(...args: *[]) => Promise<*>} operation Operation to be executed; must return a Promise.
      * @param {Array<*>} [params=[]] The arguments to be provided to the operation upon execution.
      * @returns {Promise}
      * @public
@@ -568,7 +571,7 @@ class RetryPolicy {
      * Used to register a method that will be automatically called on a failed execution attempt.
      *
      * @method
-     * @param {function( Error )} action The execution error will be provided as an argument.
+     * @param {(error: Error) => void} action The execution error will be provided as an argument.
      * @public
      */
     onFailedAttempt( action ) {
@@ -581,7 +584,7 @@ class RetryPolicy {
      * Used to register a method that will be automatically called on each execution retry (after the initial one).
      *
      * @method
-     * @param {function( number, (Error|undefined) )} action The current attempt and last error are provided.
+     * @param {(attempt: number, lastError: Error|undefined) => void} action The current attempt and last error are provided.
      * @public
      */
     onRetry( action ) {
@@ -597,12 +600,11 @@ class RetryPolicy {
      *
      * @method
      * @param {Object} context
-     * @param {function( ...* ): Promise<*>} operation Operation to be executed; must return a Promise.
+     * @param {(...args: *[]) => Promise<*>} operation Operation to be executed; must return a Promise.
      * @param {Array<*>} params The arguments to be provided to the operation upon execution.
      * @param {number} attempt
      * @param {Error} error
      * @returns {Promise}
-     * @private
      */
     #retry( context, operation, params, attempt, error ) {
         if ( attempt > this.#maxAttempts ) {