@breautek/storm 8.0.0 → 8.1.0

package/lib/private/ConnectionReplicationWaiter.js

@@ -0,0 +1,92 @@
+"use strict";
+/*
+   Copyright 2017-2024 Norman Breau
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionReplicationWaiter = void 0;
+const InternalError_1 = require("../InternalError");
+const TimeoutError_1 = require("../TimeoutError");
+class ConnectionReplicationWaiter {
+    constructor(conn, retryDelay = ConnectionReplicationWaiter.DEFAULT_RETRY_DELAY) {
+        this.$conn = conn;
+        this.$retryDelay = retryDelay;
+    }
+    $sleep(timeout) {
+        return new Promise((resolve, reject) => {
+            setTimeout(() => {
+                resolve();
+            }, timeout);
+        });
+    }
+    async wait(target, timeout = ConnectionReplicationWaiter.DEFAULT_TIMEOUT) {
+        if (!this.$conn.isReadOnly()) {
+            return;
+        }
+        let shouldTimeout = false;
+        let didTimeout = false;
+        let timeoutTimer = setTimeout(() => {
+            shouldTimeout = true;
+        }, timeout);
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            if (shouldTimeout) {
+                didTimeout = true;
+                break;
+            }
+            let currentPos = await this.$conn.getCurrentDatabasePosition();
+            if (currentPos === null || (currentPos && !currentPos.page === null) || (currentPos && !currentPos.position === null)) {
+                throw new InternalError_1.InternalError('Database Position not supported');
+            }
+            // If the current page is greater than the target page,
+            // then the position doesn't matter, we are ahead of the
+            // desired target position.
+            if (currentPos.page > target.page) {
+                break;
+            }
+            // If the pages are equal, we need to check the position
+            // and ensure we are at or greater than the target.
+            if (currentPos.page === target.page && currentPos.position >= target.position) {
+                break;
+            }
+            // If we made it here, it means the position state checks failed
+            // so wait a short while and then re-iterate
+            await this.$sleep(this.$retryDelay);
+        }
+        if (didTimeout) {
+            // If the while loop exited due to the timeout,
+            // then throw a timeout error
+            throw new TimeoutError_1.TimeoutError();
+        }
+        // Otherwise we are good to go!
+        clearTimeout(timeoutTimer);
+    }
+}
+exports.ConnectionReplicationWaiter = ConnectionReplicationWaiter;
+/**
+ * The default retry delay in milliseconds.
+ * Defaults to 1 second.
+ *
+ * This is the value used in between status query iterations.
+ */
+ConnectionReplicationWaiter.DEFAULT_RETRY_DELAY = 1000;
+/**
+ * The default timeout delay. Defaults to 120 seconds.
+ * If the connection could not reach the target position in time,
+ * then the wait will timeout
+ *
+ * Using `Infinity` will disable the timeout
+ */
+ConnectionReplicationWaiter.DEFAULT_TIMEOUT = 120 * 1000; // 120 seconds in ms
+//# sourceMappingURL=ConnectionReplicationWaiter.js.map

package/lib/private/ConnectionReplicationWaiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionReplicationWaiter.js","sourceRoot":"","sources":["../../src/private/ConnectionReplicationWaiter.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;EAcE;;;AAIF,oDAAiD;AACjD,kDAA+C;AAE/C,MAAa,2BAA2B;IAqBpC,YAAmB,IAAyB,EAAE,aAAqB,2BAA2B,CAAC,mBAAmB;QAC9G,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;IAClC,CAAC;IAEO,MAAM,CAAC,OAAe;QAC1B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,UAAU,CAAC,GAAG,EAAE;gBACZ,OAAO,EAAE,CAAC;YACd,CAAC,EAAE,OAAO,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACP,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,MAAyB,EAAE,UAAkB,2BAA2B,CAAC,eAAe;QACtG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC;YAC3B,OAAO;QACX,CAAC;QAED,IAAI,aAAa,GAAY,KAAK,CAAC;QACnC,IAAI,UAAU,GAAY,KAAK,CAAC;QAEhC,IAAI,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;YAC/B,aAAa,GAAG,IAAI,CAAC;QACzB,CAAC,EAAE,OAAO,CAAC,CAAC;QAEZ,iDAAiD;QACjD,OAAO,IAAI,EAAE,CAAC;YACV,IAAI,aAAa,EAAE,CAAC;gBAChB,UAAU,GAAG,IAAI,CAAC;gBAClB,MAAM;YACV,CAAC;YAED,IAAI,UAAU,GAAsB,MAAM,IAAI,CAAC,KAAK,CAAC,0BAA0B,EAAE,CAAC;YAElF,IAAI,UAAU,KAAK,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,QAAQ,KAAK,IAAI,CAAC,EAAE,CAAC;gBACpH,MAAM,IAAI,6BAAa,CAAC,iCAAiC,CAAC,CAAC;YAC/D,CAAC;YAED,uDAAuD;YACvD,wDAAwD;YACxD,2BAA2B;YAC3B,IAAI,UAAU,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAChC,MAAM;YACV,CAAC;YAED,wDAAwD;YACxD,mDAAmD;YACnD,IAAI,UAAU,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,IAAI,UAAU,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBAC5E,MAAM;YACV,CAAC;YAED,gEAAgE;YAChE,4CAA4C;YAC5C,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACxC,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YACb,+CAA+C;YAC/C,6BAA6B;YAC7B,MAAM,IAAI,2BAAY,EAAE,CAAC;QAC7B,CAAC;QAED,+BAA+B;QAC/B,YAAY,CAAC,YAAY,CAAC,CAAC;IAC/B,CAAC;;AArFL,kEAsFC;AArFG;;;;;GAKG;AACoB,+CAAmB,GAAW,IAAI,CAAC;AAE1D;;;;;;GAMG;AACoB,2CAAe,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,oBAAoB"}

package/lib/private/GetBinLogPositionQuery.d.ts

@@ -0,0 +1,12 @@
+import { Query } from '../Query';
+import { IDatabasePosition } from '../IDatabasePosition';
+import { IDatabaseConnection } from '../IDatabaseConnection';
+/**
+ * @since 8.1.0
+ */
+export declare abstract class GetBinLogPositionQuery<TStatusRow = unknown> extends Query<void, TStatusRow[], IDatabasePosition> {
+    protected abstract _getQuery(): string;
+    protected abstract _getFile(row: TStatusRow): string;
+    protected abstract _getPosition(row: TStatusRow): string;
+    onPostProcess(connection: IDatabaseConnection, resultSet: TStatusRow[]): Promise<IDatabasePosition>;
+}

package/lib/private/GetBinLogPositionQuery.js

@@ -0,0 +1,49 @@
+"use strict";
+/*
+   Copyright 2017-2024 Norman Breau
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetBinLogPositionQuery = void 0;
+const Query_1 = require("../Query");
+/**
+ * @since 8.1.0
+ */
+class GetBinLogPositionQuery extends Query_1.Query {
+    async onPostProcess(connection, resultSet) {
+        let row = null;
+        if (resultSet.length > 0) {
+            row = resultSet[0];
+        }
+        if (!row) {
+            return null;
+        }
+        let pageParts = this._getFile(row).split('.');
+        let strPage = pageParts[pageParts.length - 1];
+        let page = parseInt(strPage);
+        if (isNaN(page)) {
+            return null;
+        }
+        let position = parseInt(this._getPosition(row));
+        if (isNaN(position)) {
+            return null;
+        }
+        return {
+            page: page,
+            position: position
+        };
+    }
+}
+exports.GetBinLogPositionQuery = GetBinLogPositionQuery;
+//# sourceMappingURL=GetBinLogPositionQuery.js.map

package/lib/private/GetBinLogPositionQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetBinLogPositionQuery.js","sourceRoot":"","sources":["../../src/private/GetBinLogPositionQuery.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;EAcE;;;AAEF,oCAA+B;AAI/B;;GAEG;AACH,MAAsB,sBAA6C,SAAQ,aAA4C;IAM5G,KAAK,CAAC,aAAa,CAAC,UAA+B,EAAE,SAAuB;QAC/E,IAAI,GAAG,GAAe,IAAI,CAAC;QAC3B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;QAED,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,IAAI,SAAS,GAAa,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxD,IAAI,OAAO,GAAW,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAEtD,IAAI,IAAI,GAAW,QAAQ,CAAC,OAAO,CAAC,CAAC;QAErC,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,IAAI,QAAQ,GAAW,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QACxD,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,OAAO;YACH,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,QAAQ;SACrB,CAAC;IACN,CAAC;CACJ;AAnCD,wDAmCC"}

package/lib/private/GetMasterPositionQuery.d.ts

@@ -0,0 +1,11 @@
+import { GetBinLogPositionQuery } from './GetBinLogPositionQuery';
+interface IStatus {
+    File: string;
+    Position: string;
+}
+export declare class GetMasterPositionQuery extends GetBinLogPositionQuery<IStatus> {
+    protected _getQuery(): string;
+    protected _getFile(row: IStatus): string;
+    protected _getPosition(row: IStatus): string;
+}
+export {};

package/lib/private/GetMasterPositionQuery.js

@@ -0,0 +1,32 @@
+"use strict";
+/*
+   Copyright 2017-2024 Norman Breau
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetMasterPositionQuery = void 0;
+const GetBinLogPositionQuery_1 = require("./GetBinLogPositionQuery");
+class GetMasterPositionQuery extends GetBinLogPositionQuery_1.GetBinLogPositionQuery {
+    _getQuery() {
+        return 'SHOW MASTER STATUS';
+    }
+    _getFile(row) {
+        return row.File;
+    }
+    _getPosition(row) {
+        return row.Position;
+    }
+}
+exports.GetMasterPositionQuery = GetMasterPositionQuery;
+//# sourceMappingURL=GetMasterPositionQuery.js.map

package/lib/private/GetMasterPositionQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetMasterPositionQuery.js","sourceRoot":"","sources":["../../src/private/GetMasterPositionQuery.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;EAcE;;;AAEF,qEAAkE;AAOlE,MAAa,sBAAuB,SAAQ,+CAA+B;IAEpD,SAAS;QACxB,OAAO,oBAAoB,CAAC;IAChC,CAAC;IAEkB,QAAQ,CAAC,GAAY;QACpC,OAAO,GAAG,CAAC,IAAI,CAAC;IACpB,CAAC;IAEkB,YAAY,CAAC,GAAY;QACxC,OAAO,GAAG,CAAC,QAAQ,CAAC;IACxB,CAAC;CACJ;AAbD,wDAaC"}

package/lib/private/GetSlavePositionQuery.d.ts

@@ -0,0 +1,11 @@
+import { GetBinLogPositionQuery } from './GetBinLogPositionQuery';
+interface IStatus {
+    Master_Log_File: string;
+    Read_Master_Log_Pos: string;
+}
+export declare class GetSlavePositionQuery extends GetBinLogPositionQuery<IStatus> {
+    protected _getQuery(): string;
+    protected _getFile(row: IStatus): string;
+    protected _getPosition(row: IStatus): string;
+}
+export {};

package/lib/private/GetSlavePositionQuery.js

@@ -0,0 +1,32 @@
+"use strict";
+/*
+   Copyright 2017-2024 Norman Breau
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetSlavePositionQuery = void 0;
+const GetBinLogPositionQuery_1 = require("./GetBinLogPositionQuery");
+class GetSlavePositionQuery extends GetBinLogPositionQuery_1.GetBinLogPositionQuery {
+    _getQuery() {
+        return 'SHOW SLAVE STATUS';
+    }
+    _getFile(row) {
+        return row.Master_Log_File;
+    }
+    _getPosition(row) {
+        return row.Read_Master_Log_Pos;
+    }
+}
+exports.GetSlavePositionQuery = GetSlavePositionQuery;
+//# sourceMappingURL=GetSlavePositionQuery.js.map

package/lib/private/GetSlavePositionQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetSlavePositionQuery.js","sourceRoot":"","sources":["../../src/private/GetSlavePositionQuery.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;EAcE;;;AAEF,qEAAkE;AAOlE,MAAa,qBAAsB,SAAQ,+CAA+B;IAEnD,SAAS;QACxB,OAAO,mBAAmB,CAAC;IAC/B,CAAC;IAEkB,QAAQ,CAAC,GAAY;QACpC,OAAO,GAAG,CAAC,eAAe,CAAC;IAC/B,CAAC;IAEkB,YAAY,CAAC,GAAY;QACxC,OAAO,GAAG,CAAC,mBAAmB,CAAC;IACnC,CAAC;CACJ;AAbD,sDAaC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breautek/storm",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Object-Oriented REST API framework",
   "main": "lib/api.js",
   "types": "lib/api.d.ts",
@@ -51,19 +51,19 @@
     "@types/formidable": "3.4.5",
     "@types/jsonwebtoken": "9.0.6",
     "@types/mysql": "2.15.26",
-    "@types/node": "20.12.7",
+    "@types/node": "20.14.2",
     "@types/uuid": "9.0.8",
-    "ajv": "8.12.0",
+    "ajv": "8.16.0",
     "body-parser": "1.20.2",
-    "commander": "12.0.0",
+    "commander": "12.1.0",
     "express": "4.19.2",
     "form-data": "4.0.0",
     "formidable": "3.5.1",
     "jsonwebtoken": "9.0.2",
     "mysql": "2.18.1",
     "sql-formatter": "15.3.1",
-    "tslib": "2.6.2",
-    "uuid": "9.0.1"
+    "tslib": "2.6.3",
+    "uuid": "10.0.0"
   },
   "peerDependencies": {
     "@arashi/interfaces": "1.x",
@@ -74,16 +74,16 @@
     "@arashi/logger": "4.0.6",
     "@totalpave/eslint-plugin": "6.2.0",
     "@types/jest": "29.5.12",
-    "@typescript-eslint/eslint-plugin": "7.7.1",
-    "@typescript-eslint/parser": "7.7.1",
+    "@typescript-eslint/eslint-plugin": "7.13.0",
+    "@typescript-eslint/parser": "7.13.0",
     "auto-changelog": "2.4.0",
     "eslint": "8.57.0",
     "jest": "29.7.0",
     "jest-jasmine2": "29.7.0",
-    "ts-jest": "29.1.2",
+    "ts-jest": "29.1.4",
     "ts-node": "10.9.2",
     "typedoc": "0.25.13",
-    "typedoc-plugin-markdown": "3.17.1",
+    "typedoc-plugin-markdown": "4.0.3",
     "typescript": "5.4.5"
   }
 }

package/src/Database.ts

@@ -17,6 +17,7 @@
 import * as UUID from 'uuid';
 import {DatabaseConnection} from './DatabaseConnection';
 import { getInstance } from './instance';
+import { IDatabasePosition } from './IDatabasePosition';
 
 const MASTER_NAME: string = 'MASTER';
 const TAG: string = 'Database';
@@ -61,7 +62,7 @@ export abstract class Database<TDatabaseConfig, TConnectionAPI> {
         this._removeNode(slaveID);
     }
 
-    public getConnection(requireWriteAccess: boolean = false, nodeID?: string): Promise<DatabaseConnection<TConnectionAPI>> {
+    public getConnection(requireWriteAccess: boolean = false, nodeID?: string, requiredPosition?: IDatabasePosition): Promise<DatabaseConnection<TConnectionAPI>> {
         let query: string = 'SLAVE*';
         
         if (nodeID) {
@@ -71,7 +72,7 @@ export abstract class Database<TDatabaseConfig, TConnectionAPI> {
             query = 'MASTER';
         }
 
-        return this._getConnection(query, requireWriteAccess);
+        return this._getConnection(query, requireWriteAccess, requiredPosition);
     }
 
     public destroy(): Promise<void> {
@@ -81,6 +82,6 @@ export abstract class Database<TDatabaseConfig, TConnectionAPI> {
     protected abstract _destroy(): Promise<void>;
     protected abstract _addNode(name: string, config: TDatabaseConfig): void;
     protected abstract _removeNode(name: string): void;
-    protected abstract _getConnection(query: string, requireWriteAccess: boolean): Promise<DatabaseConnection<TConnectionAPI>>;
+    protected abstract _getConnection(query: string, requireWriteAccess: boolean, requiredPosition?: IDatabasePosition): Promise<DatabaseConnection<TConnectionAPI>>;
     public abstract escape(query: string): string;
 }

package/src/DatabaseConnection.ts

@@ -22,6 +22,7 @@ import {IDatabaseConnection} from './IDatabaseConnection';
 import {IQueryable} from './IQueryable';
 import { IConfig } from './IConfig';
 import { IsolationLevel } from './IsolationLevel';
+import { IDatabasePosition } from './IDatabasePosition';
 
 export const LINGER_WARNING: number = 10000;
 export const DEFAULT_QUERY_TIMEOUT: number = 3600000;
@@ -260,4 +261,9 @@ export abstract class DatabaseConnection<TAPI> implements IDatabaseConnection {
      */
     // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
     protected abstract _stream(query: string, params?: any, streamOptions?: any): Readable;
+
+    /**
+     * @since 8.1.0
+     */
+    public abstract getCurrentDatabasePosition(): Promise<IDatabasePosition>;
 }

package/src/IDatabaseConnection.ts

@@ -17,6 +17,7 @@
 import { Readable } from 'stream';
 import { IQueryable } from './IQueryable';
 import { IsolationLevel } from './IsolationLevel';
+import { IDatabasePosition } from './IDatabasePosition';
 
 export interface IDatabaseConnection {
     setInstantiationStack(stack: string): void;
@@ -33,4 +34,9 @@ export interface IDatabaseConnection {
     isTransaction(): boolean;
     commit(): Promise<void>;
     rollback(): Promise<void>;
+
+    /**
+     * @since 8.1.0
+     */
+    getCurrentDatabasePosition(): Promise<IDatabasePosition>;
 }

package/src/IDatabasePosition.ts

@@ -0,0 +1,23 @@
+/*
+   Copyright 2017-2024 Norman Breau
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+/**
+ * @since 8.1.0
+ */
+export interface IDatabasePosition {
+    page: number;
+    position: number;
+}

package/src/ManagedDatabaseConnection.ts

@@ -19,6 +19,7 @@ import {getInstance} from './instance';
 import {Readable} from 'stream';
 import { Query } from './Query';
 import { IsolationLevel } from './IsolationLevel';
+import { IDatabasePosition } from './IDatabasePosition';
 
 const TAG: string = 'ManagedDatabaseConnection';
 
@@ -81,6 +82,11 @@ export class ManagedDatabaseConnection implements IDatabaseConnection {
         }
     }
 
+    public async getCurrentDatabasePosition(): Promise<IDatabasePosition> {
+        let conn: IDatabaseConnection = await this.$getConnection();
+        return await conn.getCurrentDatabasePosition();
+    }
+
     public isWriteRequired(): boolean {
         return this.$requiresWrite;
     }

package/src/MySQLConnection.ts

@@ -31,6 +31,10 @@ import { DeadLockError } from './DeadLockError';
 import { IsolationLevel } from './IsolationLevel';
 import {SetIsolationLevelQuery} from './private/SetIsolationLevelQuery';
 import { LockWaitTimeoutError } from './LockWaitTimeoutError';
+import { IDatabasePosition } from './IDatabasePosition';
+import { GetBinLogPositionQuery } from './private/GetBinLogPositionQuery';
+import { GetSlavePositionQuery } from './private/GetSlavePositionQuery';
+import { GetMasterPositionQuery } from './private/GetMasterPositionQuery';
 
 const DEFAULT_HIGH_WATERMARK: number = 512; // in number of result objects
 const TAG: string = 'MySQLConnection';
@@ -57,12 +61,14 @@ let rollbackQuery: Query = new RollbackQuery();
 export class MySQLConnection extends DatabaseConnection<MySQL.PoolConnection> {
     private $transaction: boolean;
     private $opened: boolean;
+    private $isMasterConnection: boolean;
 
     public constructor(connection: MySQL.PoolConnection, instantiationStack: string, isReadOnly: boolean = true) {
         super(connection, isReadOnly, instantiationStack);
 
         this.$opened = true;
         this.$transaction = false;
+        this.$isMasterConnection = null;
 
         connection.config.queryFormat = function(query: string, values: any) {
             if (!values) return query;
@@ -77,6 +83,22 @@ export class MySQLConnection extends DatabaseConnection<MySQL.PoolConnection> {
         };
     }
 
+    /**
+     * @internal - Do not use in application code
+     */
+    public async __internal_init(): Promise<void> {
+        let result = await new GetSlavePositionQuery().execute(this);
+        this.$isMasterConnection = result === null;
+    }
+
+    public isMaster(): boolean {
+        return this.$isMasterConnection;
+    }
+
+    public isReplication(): boolean {
+        return !this.isMaster();
+    }
+
     public isTransaction(): boolean {
         return this.$transaction;
     }
@@ -85,6 +107,11 @@ export class MySQLConnection extends DatabaseConnection<MySQL.PoolConnection> {
         return this.$opened;
     }
 
+    public override async getCurrentDatabasePosition(): Promise<IDatabasePosition> {
+        let statusQuery: GetBinLogPositionQuery = this.isReplication() ? new GetSlavePositionQuery() : new GetMasterPositionQuery();
+        return await statusQuery.execute(this);
+    }
+
     // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
     protected _query(query: string, params?: any): Promise<any> {
         let logger: BaseLogger = getInstance().getLogger();

package/src/MySQLDatabase.ts

@@ -18,6 +18,8 @@ import {Database} from './Database';
 import {MySQLConnection} from './MySQLConnection';
 import * as MySQL from 'mysql';
 import {getInstance} from './instance';
+import { IDatabasePosition } from './IDatabasePosition';
+import { ConnectionReplicationWaiter } from './private/ConnectionReplicationWaiter';
 
 const TAG: string = 'MySQLDatabase';
 
@@ -69,18 +71,44 @@ export class MySQLDatabase extends Database<MySQL.PoolConfig, MySQL.PoolConnecti
         });
     }
 
-    protected _getConnection(query: string, requireWriteAccess: boolean): Promise<MySQLConnection> {
-        getInstance().getLogger().trace(TAG, `Querying connection pool for "${query}".`);
+    private $getConnectionFromPool(query: string, requireWriteAccess: boolean, instantationStack: string): Promise<MySQLConnection> {
         return new Promise<MySQLConnection>((resolve, reject) => {
-            let instantationStack: string = new Error().stack;
             this.$cluster.getConnection(query, (error: MySQL.MysqlError, connection: MySQL.PoolConnection) => {
                 if (error) {
                     reject(error);
                     return;
                 }
-
+    
                 resolve(new MySQLConnection(connection, instantationStack, !requireWriteAccess));
             });
         });
     }
+
+    protected override async _getConnection(query: string, requireWriteAccess: boolean, position?: IDatabasePosition): Promise<MySQLConnection> {
+        getInstance().getLogger().trace(TAG, `Querying connection pool for "${query}".`);
+        let instantationStack: string = new Error().stack;
+
+        let conn: MySQLConnection = await this.$getConnectionFromPool(query, requireWriteAccess, instantationStack);
+        await conn.__internal_init();
+
+        if (conn.isReplication()) {
+            // master connections will not wait on database positions
+            // they are guarenteed to be at the tip.
+            // readonly, or otherwise known as replication connections
+            // may have replication lag. If we have a desired position target,
+            // then await for the connection to catch up to that target.
+            if (position && position.page && position.position) {
+                let waiter: ConnectionReplicationWaiter = new ConnectionReplicationWaiter(conn);
+                try {
+                    await waiter.wait(position);
+                }
+                catch (ex) {
+                    conn.close(true);
+                    throw ex;
+                }
+            }
+        }
+
+        return conn;
+    }
 }

package/src/TimeoutError.ts

@@ -0,0 +1,44 @@
+/*
+   Copyright 2017-2024 Norman Breau
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+import {StormError} from './StormError';
+import {ErrorCode} from './ErrorCode';
+import {StatusCode} from './StatusCode';
+
+/**
+ * @since 8.1.0
+ */
+export class TimeoutError extends StormError {
+    public constructor() {
+        super();
+    }
+
+    public getMessage(): string {
+        return `The requested resource could not be reached in time.`;
+    }
+
+    public getCode(): ErrorCode {
+        return ErrorCode.INTERNAL;
+    }
+
+    public getHTTPCode(): StatusCode {
+        return StatusCode.ERR_REQUEST_TIMEOUT;
+    }
+
+    public override getLocaleCode(): string {
+        return '@breautek/storm/TimeoutError/message';
+    }
+}

package/src/api.ts

@@ -51,6 +51,7 @@ export {
     IErrorResponse,
     IAdditionalErrorDetails
 } from './StormError';
+export {TimeoutError} from './TimeoutError';
 export {JWTError} from './JWTError';
 export {MissingParameterError} from './MissingParameterError';
 export {InvalidCredentialsError} from './InvalidCredentialsError';
@@ -96,6 +97,7 @@ export {IDatabaseConnection} from './IDatabaseConnection';
 export {IServiceHeaders} from './IServiceHeaders';
 export {IAuthTokenData} from './IAuthTokenData';
 export {IQueryable} from './IQueryable';
+export {IDatabasePosition} from './IDatabasePosition';
 
 // Token
 export {Token} from './Token';