@ti-engine/core 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 This document contains the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.9.0
+
+TypeScript declarations now ship with the package. The previous attempt was withdrawn in 1.8.1 because the generated
+declarations did not type-check for a consumer using TypeScript's default settings; this one is verified under those
+settings before it can be committed, by a check that runs in CI.
+
+What made the first attempt look finished was the verification, not the output: it ran with `skipLibCheck: true`, which
+suppresses errors *inside* `.d.ts` files — precisely the class of error declaration emit produces. The real number was
+larger than the 45 that measurement eventually admitted to. A parse error anywhere in a program suppresses the whole
+semantic pass, so the malformed declarations in one package were hiding every unresolved name in the other two: the
+first honest measurement across all three was **251** errors, not 7.
+
+* feat(types): generate and publish `.d.ts` declarations for every module, wired into `exports` and `imports` through
+  `types` conditions so both a consumer's import and the framework's own `#` specifiers resolve to them
+* feat(exceptions): export the `TiException` class. It is named in the signature of everything that raises or inspects
+  an exception and was never exported, so no consumer could name the type it was being handed
+* feat(tools): `tools.enum()` now returns a type carrying the seed's own members. Every enum was previously documented
+  as returning `Object`, on which TypeScript permits no property access at all — `exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS`
+  did not type-check, and neither did any other enum member in the framework. A misspelled member is now a compile
+  error rather than `undefined` at runtime
+* feat(definitions): expose the shared type definitions as `@ti-engine/core/definitions`. The types in it appear
+  throughout the public API and the module declaring them was not exported
+* fix(types)!: rewrite every closure-style `{function(...)}` JSDoc annotation in arrow syntax. The declaration emitter
+  reduces that form to a nameless `: Function` and leaks the remainder of the annotation into the doc comment, which is
+  a syntax error in the emitted declaration — so the annotations documenting a callback were the ones destroying it
+* fix(types): stop marking `#`-named members `@private`. The emitter combines the two into `private #name`, which
+  TypeScript rejects outright; the `#private` brand each class already emits carries the same meaning
+* fix(exchange): `onConnectionDisrupted`, `onConnectionRecovered` and `onConnectionLost` are no longer marked
+  `@private` in `MessageHandler`. They override public methods of `ConnectionObserver` and their own documentation
+  tells you to override them, so the tag contradicted both the base class and the instruction directly above it
+* fix(types): `Object.<K,V>` in a standalone `@typedef` emits as the non-generic `Object<K,V>`; the map typedefs are
+  now `Record<K,V>`, and `TiLabelsTree` an index signature, since a self-referential `Record` alias is circular
+* refactor(exchange): the lazy `require` inside `addMessageObserver` binds under a distinct name. As `MessageObserver`
+  it shadowed the file-level type import, leaving the documented parameter type unresolvable
+* build(deps): add `@types/node`. The published declarations name `NodeJS.Process`, so a consumer cannot read them
+  without it
+
 ## Version 1.8.1
 
 Presentation and documentation only — no functional change. The npm page is the first thing a prospective user sees, and it was working against the package.

package/components/auditing.js

@@ -13,6 +13,8 @@ const logger = require( "#logger" );
 const config = require( "#config" );
 const ServiceInstance = require( "#service-instance" );
 
+/** @import { TiLogSeverity } from "#logger" */
+
 /**
  * Used to create and/or return an Auditing System singleton instance.
  *
@@ -77,7 +79,6 @@ class Auditing {
      * @param {string} message
      * @param {Object} data
      * @returns {TiLogEntry}
-     * @private
      */
     static #createLogEntry( severity, thread, message, data ) {
         let currentDate = new Date();
@@ -104,7 +105,6 @@ class Auditing {
      *
      * @method
      * @param {TiLogEntry} logEntry
-     * @private
      */
     static #logToConsole( logEntry ) {
         if ( config.getSetting( config.setting.AUDITING_LOG_USES_JSON ) === true ) {
@@ -127,7 +127,6 @@ class Auditing {
      * @method
      * @param {TiLogEntry} logEntry
      * @returns {string}
-     * @private
      */
     static #formatConsoleMessage( logEntry ) {
         let logDate = new Date( logEntry.timestamp );
@@ -144,7 +143,6 @@ class Auditing {
      * @param {number} [maxDepth=5]
      * @param {Set} [visited=new Set()]
      * @returns {string}
-     * @private
      */
     static #formatConsoleData( data, prefix = "", currentDepth = 0, maxDepth = 5, visited = new Set() ) {
         if ( data === null || data === undefined || !_.isObjectLike( data ) ) {

package/components/definitions.types.js

@@ -6,6 +6,11 @@
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
+/** @import { TiException } from "#exceptions" */
+/** @import { TiLocalizationLanguage } from "#localization" */
+/** @import { TiLogSeverity } from "#logger" */
+/** @import { ServiceHandlerMethod } from "#service-executor" */
+
 // Configuration Definitions:
 
 /**
@@ -123,6 +128,16 @@
  * @property {(enumValue: number|string) => boolean} contains
  */
 
+/**
+ * The shape `tools.enum()` produces for a given seed. Every key of the seed is carried over as an enum
+ * member, so a typo is a compile error rather than `undefined` at runtime, and the lookup helpers of
+ * {@link TiEnum} come along with it. Members are typed as the value they hold, not as the
+ * `[ value, name, description ]` tuple the seed declares them with.
+ *
+ * @template {Record<string,*>} T
+ * @typedef {{ [K in keyof T]: number|string } & TiEnum} TiEnumOf
+ */
+
 /**
  * @typedef {Object} TiLogEntry
  * @property {string} _id Unique identifier that can be used to identify the document in a NoSQL database.
@@ -151,13 +166,13 @@
 /**
  * The key of this object is the language code, and the value is the textual representation of the label.
  *
- * @typedef {Object<TiLocalizationLanguage, string>} TiLocalizedLabel
+ * @typedef {Record<TiLocalizationLanguage, string>} TiLocalizedLabel
  */
 
 /**
  * A nested labels tree where intermediate nodes are objects and leaf nodes are language-to-text maps.
  *
- * @typedef {Object<string, TiLocalizedLabel | TiLabelsTree>} TiLabelsTree
+ * @typedef {{ [label: string]: TiLocalizedLabel | TiLabelsTree }} TiLabelsTree
  */
 
 // Service Bus Definitions:
@@ -209,11 +224,11 @@
  */
 
 /**
- * @typedef {Object.<string, ServiceInterfaceVersion>} ServiceInterface
+ * @typedef {Record<string, ServiceInterfaceVersion>} ServiceInterface
  */
 
 /**
- * @typedef {Object.<number, ServiceHandlerMethod>} ServiceInterfaceVersion
+ * @typedef {Record<number, ServiceHandlerMethod>} ServiceInterfaceVersion
  */
 
 /**

package/components/exchange/default/default-message-exchange.js

@@ -10,6 +10,8 @@ const MessageExchange = require( "#message-exchange" );
 const config = require( "#config" );
 const exceptions = require( "#exceptions" );
 
+/** @import { Message } from "#definitions" */
+
 /**
  * The default {@link MessageExchange} behavior for the Ti Engine using Redis for message exchange.
  *

package/components/exchange/default/default-message-receiver.js

@@ -11,6 +11,8 @@ const memoryCache = require( "#message-memory-cache" );
 const config = require( "#config" );
 const exceptions = require( "#exceptions" );
 
+/** @import { Message } from "#definitions" */
+
 /**
  * The default {@link MessageReceiver} behavior for the Ti Engine using Redis for message exchange.
  *

package/components/exchange/default/default-message-sender.js

@@ -12,6 +12,8 @@ const config = require( "#config" );
 const exceptions = require( "#exceptions" );
 const memoryCache = require( "#message-memory-cache" );
 
+/** @import { Message } from "#definitions" */
+
 /**
  * The default {@link MessageSender} behavior for the Ti Engine using Redis for message exchange.
  *

package/components/exchange/message-dispatcher.js

@@ -11,6 +11,10 @@ const exceptions = require( "#exceptions" );
 const logger = require( "#logger" );
 const messageTracer = require( "#message-tracer" );
 
+/** @import { Message } from "#definitions" */
+/** @import MessageExchange from "#message-exchange" */
+/** @import MessageObserver from "#message-observer" */
+
 /**
  * Used to create and/or return a Message Dispatcher singleton instance.
  * This class handles the internal message dispatching between the microservices.

package/components/exchange/message-exchange.js

@@ -11,6 +11,10 @@ const _ = require( "lodash" );
 const exceptions = require( "#exceptions" );
 const messageTracer = require( "#message-tracer" );
 
+/** @import { Message } from "#definitions" */
+/** @import MessageReceiver from "#message-receiver" */
+/** @import MessageSender from "#message-sender" */
+
 /**
  * An abstract class that defines a message exchange behavior.
  * <br/>

package/components/exchange/message-handler.js

@@ -14,6 +14,9 @@ const logger = require( "#logger" );
 const tools = require( "#tools" );
 const config = require( "#config" );
 
+/** @import { Message } from "#definitions" */
+/** @import MessageObserver from "#message-observer" */
+
 const OLD_DEFAULT_HASH_KEY = "23e7bdc7-a793-41f9-856e-6760332f0c73";
 let keyWarningEmitted = false;
 
@@ -145,8 +148,10 @@ class MessageHandler extends ConnectionObserver {
      * @public
      */
     addMessageObserver( messageObserver ) {
-        const MessageObserver = require( "#message-observer" );
-        if ( messageObserver instanceof MessageObserver ) {
+        // Bound under a distinct name: `MessageObserver` at method scope would shadow the file-level type
+        // import, leaving the documented parameter type unresolvable in the generated declarations.
+        const MessageObserverClass = require( "#message-observer" );
+        if ( messageObserver instanceof MessageObserverClass ) {
             this.#messageObservers.push( messageObserver );
             this.#messageObservers = _.orderBy( this.#messageObservers, [ "priority" ], [ "desc" ] );
         } else {
@@ -180,7 +185,6 @@ class MessageHandler extends ConnectionObserver {
      * @method
      * @param {string} identifier The identifier of the observed connection.
      * @override
-     * @private
      */
     onConnectionRecovered( identifier ) {
         if ( this.#isAvailable === false && identifier === this.#connectionIdentifier ) {
@@ -200,7 +204,6 @@ class MessageHandler extends ConnectionObserver {
      * @method
      * @param {string} identifier The identifier of the observed connection.
      * @override
-     * @private
      */
     onConnectionDisrupted( identifier ) {
         if ( this.#isAvailable === true && identifier === this.#connectionIdentifier ) {
@@ -220,7 +223,6 @@ class MessageHandler extends ConnectionObserver {
      * @method
      * @param {string} identifier The identifier of the observed connection.
      * @override
-     * @private
      */
     onConnectionLost( identifier ) {
         if ( identifier === this.#connectionIdentifier ) {

package/components/exchange/message-memory-cache.js

@@ -11,6 +11,9 @@ const tools = require( "#tools" );
 const exceptions = require( "#exceptions" );
 const redis = require( "#redis-integration" );
 
+/** @import ConnectionObserver from "#connection-observer" */
+/** @import { Message } from "#definitions" */
+
 /**
  * Used to create a Redis Cache client wrapped in a specialized message memory cache interface.
  *

package/components/exchange/message-observer.js

@@ -10,6 +10,8 @@ const ConnectionObserver = require( "#connection-observer" );
 const _ = require( "lodash" );
 const exceptions = require( "#exceptions" );
 
+/** @import { Message } from "#definitions" */
+
 /**
  * An abstract class that allows the child class to observe and take action on message events.
  * <br/>

package/components/exchange/message-receiver.js

@@ -12,6 +12,8 @@ const exceptions = require( "#exceptions" );
 const config = require( "#config" );
 const tools = require( "#tools" );
 
+/** @import { Message } from "#definitions" */
+
 /**
  * An abstract class that defines a basic message receiver behavior.
  *
@@ -154,7 +156,6 @@ class MessageReceiver extends MessageHandler {
      * @method
      * @param {Message} message
      * @returns {Promise<Message>}
-     * @private
      */
     #postReceive( message ) {
         return new Promise( ( resolve, reject ) => {

package/components/exchange/message-sender.js

@@ -10,6 +10,8 @@ const MessageHandler = require( "#message-handler" );
 const exceptions = require( "#exceptions" );
 const config = require( "#config" );
 
+/** @import { Message } from "#definitions" */
+
 /**
  * An abstract class that defines a basic message sender behavior.
  *
@@ -113,7 +115,6 @@ class MessageSender extends MessageHandler {
      * @method
      * @param {Message} message
      * @returns {Promise<Message>}
-     * @private
      */
     #preSend( message ) {
         if ( this.isAvailable === true ) {
@@ -132,7 +133,6 @@ class MessageSender extends MessageHandler {
      *
      * @method
      * @returns {Promise}
-     * @private
      */
     #postSend() {
         return Promise.resolve();

package/components/exchange/message-tracer.js

@@ -13,6 +13,8 @@ const logger = require( "#logger" );
 const exceptions = require( "#exceptions" );
 const cache = require( "#cache" );
 
+/** @import { Message } from "#definitions" */
+
 const traceRoot = {
     trace: []
 };
@@ -174,7 +176,6 @@ class MessageTracer {
      * @method
      * @param {TiTraceEntry} traceEntry The trace entry to log.
      * @param {TiLogSeverity} severity The log entry severity.
-     * @private
      */
     static #createLogEntry( traceEntry, severity ) {
         logger.log( MessageTracer.#formatLogEntry( traceEntry ), severity, traceEntry );
@@ -186,7 +187,6 @@ class MessageTracer {
      * @method
      * @param {TiTraceEntry} traceEntry
      * @return {string} Prepared trace info.
-     * @private
      */
     static #formatLogEntry( traceEntry ) {
         return `Message(${ traceEntry.chainID || traceEntry.messageID }) Trace: '${ traceEntry.messageType } ${ traceEntry.dispatchEvent } ${ traceEntry.messageState }' From: '${ traceEntry.fromAddress }' To: '${ traceEntry.toAddress }'`;
@@ -198,7 +198,6 @@ class MessageTracer {
      * @method
      * @param {Message} message
      * @returns {Message}
-     * @private
      */
     static #obscureSensitiveData( message ) {
         /** @type Message */

package/components/service-caller.js

@@ -14,6 +14,8 @@ const config = require( "#config" );
 const cache = require( "#cache" );
 const messageDispatcher = require( "#message-dispatcher" );
 
+/** @import { ServiceAddress, ServiceCall, ServiceCallResult, ServiceExecContext } from "#definitions" */
+
 /**
  * Used to assemble and prepare a new {@link ServiceCall} object.
  *
@@ -182,7 +184,6 @@ class ServiceCallProcessor {
      *
      * @method
      * @returns {Promise<ServiceCallResult>}
-     * @private
      */
     #execute() {
         return new Promise( ( resolve, reject ) => {
@@ -207,7 +208,6 @@ class ServiceCallProcessor {
      *
      * @method
      * @returns {Promise<ServiceCallResult>}
-     * @private
      */
     #timeout() {
         return new Promise( ( resolve, reject ) => {
@@ -335,7 +335,6 @@ class ServiceCaller extends MessageObserver {
      * @method
      * @param {string} messageID
      * @param {ServiceCallProcessor} processor
-     * @private
      */
     #addProcessor( messageID, processor ) {
         this.#serviceCallProcessors[ messageID ] = processor;
@@ -347,7 +346,6 @@ class ServiceCaller extends MessageObserver {
      * @method
      * @param {string} messageID
      * @returns {ServiceCallProcessor}
-     * @private
      */
     #getProcessor( messageID ) {
         return this.#serviceCallProcessors[ messageID ];
@@ -358,7 +356,6 @@ class ServiceCaller extends MessageObserver {
      *
      * @method
      * @param {string} messageID
-     * @private
      */
     #removeProcessor( messageID ) {
         if ( this.#serviceCallProcessors[ messageID ] ) {

package/components/service-consumer.js

@@ -10,6 +10,8 @@ const ServiceInstance = require( "#service-instance" );
 const exceptions = require( "#exceptions" );
 const messageDispatcher = require( "#message-dispatcher" );
 
+/** @import { ServiceAddress, ServiceCallResult, ServiceConfiguration, ServiceExecContext } from "#definitions" */
+
 /**
  * Abstract class used to define a Service Consumer behavior.
  * <br/>

package/components/service-executor.js

@@ -15,11 +15,13 @@ const config = require( "#config" );
 const cache = require( "#cache" );
 const messageDispatcher = require( "#message-dispatcher" );
 
+/** @import { ServiceAddress, ServiceCall, ServiceDefinition, ServiceExecContext, ServiceInterface } from "#definitions" */
+
 /**
  * @callback VerifyAccessMethod
  * @param {string} authToken
  * @param {ServiceAddress} serviceAddress
- * @returns {Promise}
+ * @returns {Promise<*>}
  */
 
 /**
@@ -181,7 +183,6 @@ class ServiceExecutor extends MessageObserver {
      * @method
      * @param {ServiceCall} serviceCall
      * @returns {ServiceExecContext}
-     * @private
      */
     static #assembleServiceExecContext( serviceCall ) {
         return {
@@ -206,7 +207,6 @@ class ServiceExecutor extends MessageObserver {
      * @method
      * @param {string} serviceAlias
      * @returns {Promise}
-     * @private
      */
     #registerServiceToCatalog( serviceAlias ) {
         return new Promise( ( resolve, reject ) => {
@@ -226,7 +226,6 @@ class ServiceExecutor extends MessageObserver {
      * @method
      * @param {ServiceCall} serviceCall
      * @returns {Promise<ServiceCall>}
-     * @private
      */
     #processServiceCall( serviceCall ) {
         return new Promise( ( resolve ) => {
@@ -252,7 +251,6 @@ class ServiceExecutor extends MessageObserver {
      * @method
      * @param {ServiceAddress} serviceAddress
      * @returns {Promise<ServiceHandlerMethod>}
-     * @private
      */
     #identifyService( serviceAddress ) {
         return new Promise( ( resolve, reject ) => {

package/components/service-instance.js

@@ -15,6 +15,8 @@ const exceptions = require( "#exceptions" );
 const cache = require( "#cache" );
 const messageDispatcher = require( "#message-dispatcher" );
 
+/** @import { ServiceConfiguration } from "#definitions" */
+
 /**
  * Abstract class used to define a Service Instance behavior.
  * <br/>
@@ -244,7 +246,6 @@ class ServiceInstance {
      *
      * @method
      * @returns {Promise}
-     * @private
      */
     #preStart() {
         return new Promise( ( resolve ) => {
@@ -260,7 +261,6 @@ class ServiceInstance {
      *
      * @method
      * @returns {Promise}
-     * @private
      */
     #postStart() {
         return new Promise( ( resolve ) => {
@@ -285,7 +285,6 @@ class ServiceInstance {
      *
      * @method
      * @returns {Promise}
-     * @private
      */
     #preStop() {
         return new Promise( ( resolve ) => {
@@ -303,7 +302,6 @@ class ServiceInstance {
      *
      * @method
      * @returns {Promise}
-     * @private
      */
     #postStop() {
         return new Promise( ( resolve ) => {

package/components/service-provider.js

@@ -13,6 +13,9 @@ const exceptions = require( "#exceptions" );
 const logger = require( "#logger" );
 const messageDispatcher = require( "#message-dispatcher" );
 
+/** @import { ServiceAddress, ServiceConfiguration, ServiceDefinition } from "#definitions" */
+/** @import { ServiceHandlerMethod } from "#service-executor" */
+
 /**
  * Abstract class used to define a Service Provider behavior.
  * <br/>

package/integrations/redis-integration.js

@@ -282,7 +282,7 @@ class RedisClient {
      *
      * @method
      * @param {string} channel Unique identifier of the channel to subscribe to.
-     * @param {function( Object )} messageHandler Will execute this handler every time a new message is received.
+     * @param {(message: Object) => void} messageHandler Will execute this handler every time a new message is received.
      * @returns {Promise}
      * @public
      */
@@ -428,7 +428,6 @@ class RedisClient {
      * @param {number} [retryMaxIntervalMs=1000] Optional max backoff interval.
      * @param {number|undefined} [retryMaxAttempts=undefined] Optional max (re)connection attempts before abort.
      * @returns {Promise}
-     * @private
      */
     #setupClient( host, port, authKey, user, defaultDB, retryMaxIntervalMs, retryMaxAttempts ) {
         return new Promise( ( resolve, reject ) => {
@@ -510,7 +509,6 @@ class RedisClient {
      * Used to notify all connection observers about the current connection state.
      *
      * @method
-     * @private
      */
     #notifyConnectionObservers() {
         // Notify all connection observers about the event:
@@ -530,7 +528,6 @@ class RedisClient {
      *
      * @method
      * @returns {Promise}
-     * @private
      */
     #fetchServerInfo() {
         return new Promise( ( resolve, reject ) => {
@@ -570,7 +567,6 @@ class RedisClient {
      *
      * @method
      * @returns {Promise<number>}
-     * @private
      */
     #getClientID() {
         let commandArguments = [ "client", "id" ];