Add type definitions and pause/resume functionality (#3)

Added typescript type definitions and the ability to pause / resume the binlog listener.

Author: Rentacookie

.changeset/thick-carpets-shake.md

@@ -0,0 +1,8 @@
+---
+'@powersync/mysql-zongji': minor
+---
+
+Added the functionality to pause / resume the zongji binlog listener
+Improved stop/start functionality to better handle some race conditions
+Added type definitions
+The first time a TableMap event is emitted, it will always be emitted, but subsequent events will only be emitted if the table map has changed.

.github/workflows/dev-packages.yaml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version-file: '.nvmrc'
-      - uses: pnpm/action-setup@v2
+      - uses: pnpm/action-setup@v4
         name: Install pnpm
         with:
           version: 9

.github/workflows/test.yml

@@ -26,16 +26,14 @@ jobs:
           -e MYSQL_ROOT_PASSWORD=my_password \
           -p 3306:3306 \
           -d mysql:${{ matrix.mysql-version }} \
-          --server-id=1 \
-          --log-bin=/var/lib/mysql/mysql-bin.log \
-          --binlog-format=row
+          --log-bin=/var/lib/mysql/mysql-bin.log
 
       - name: Setup NodeJS
         uses: actions/setup-node@v4
         with:
           node-version-file: '.nvmrc'
 
-      - uses: pnpm/action-setup@v2
+      - uses: pnpm/action-setup@v4
         name: Install pnpm
         with:
           version: 9

.nvmrc

@@ -1 +1 @@
-v20.12.2
+v22.14.0

README.md

@@ -143,8 +143,9 @@ Neither method requires any arguments.
 
 ## Run Tests
 
-- install [Docker](https://www.docker.com/community-edition#download)
-- run `docker-compose up` and then `./docker-test.sh`
+- Install [Docker](https://www.docker.com/community-edition#download)
+- Run `docker-compose up` and then `./docker-test.sh`
+- Some tests can be run directly, but some of the types.js tests pertaining to dates are affected by the host's timezone and are consequently brittle.
 
 ## References
 
@@ -157,7 +158,7 @@ The following resources provided valuable information that greatly assisted in c
 - https://kkaefer.com/node-cpp-modules/
 - https://dev.mysql.com/doc/internals/en/replication-protocol.html
 - https://web.archive.org/web/20200201195450/https://www.cs.wichita.edu/~chang/lecture/cs742/program/how-mysql-c-api.html
-- https://github.com/jeremycole/mysql_binlog (Ruby implemenation of MySQL binlog parser)
+- https://github.com/jeremycole/mysql_binlog (Ruby implementation of MySQL binlog parser)
 - https://dev.mysql.com/doc/internals/en/date-and-time-data-type-representation.html
 
 ## License

docker-test.sh

@@ -2,6 +2,6 @@
 MYSQL_HOSTS="mysql80 mysql84"
 
 for hostname in ${MYSQL_HOSTS}; do
-  echo $hostname + node 20
+  echo $hostname + node 22
     docker run -it --network=powersync-mysql-zongji_default -e MYSQL_HOST=$hostname -w /build -v $PWD:/build node:20 npm test
 done

index.js

@@ -22,6 +22,7 @@ function ZongJi(dsn) {
   this.ctrlCallbacks = [];
   this.tableMap = {};
   this.ready = false;
+  this.stopped = false;
   this.useChecksum = false;
 
   this._establishConnection(dsn);
@@ -192,6 +193,9 @@ ZongJi.prototype.start = function (options = {}) {
   this._filters(options);
 
   const testChecksum = (resolve, reject) => {
+    if (this.stopped) {
+      resolve();
+    }
     this._isChecksumEnabled((err, checksumEnabled) => {
       if (err) {
         reject(err);
@@ -203,6 +207,9 @@ ZongJi.prototype.start = function (options = {}) {
   };
 
   const findBinlogEnd = (resolve, reject) => {
+    if (this.stopped) {
+      resolve();
+    }
     this._findBinlogEnd((err, result) => {
       if (err) {
         return reject(err);
@@ -240,9 +247,8 @@ ZongJi.prototype.start = function (options = {}) {
             this.emit('binlog', event);
             this.connection.resume();
           });
-          return;
         }
-        break;
+        return;
       }
       case 'Rotate':
         if (this.options.filename !== event.binlogName) {
@@ -263,25 +269,41 @@ ZongJi.prototype.start = function (options = {}) {
   Promise.all(promises)
     .then(() => {
       this.BinlogClass = initBinlogClass(this);
-      this.ready = true;
-      this.emit('ready');
-
-      this.connection._protocol._enqueue(new this.BinlogClass(binlogHandler));
+      if (!this.stopped) {
+        this.connection._protocol._enqueue(new this.BinlogClass(binlogHandler));
+        this.ready = true;
+        this.emit('ready');
+      }
     })
     .catch((err) => {
       this.emit('error', err);
     });
 };
 
 ZongJi.prototype.stop = function () {
-  // Binary log connection does not end with destroy()
-  this.connection.destroy();
-  this.ctrlConnection.query('KILL ' + this.connection.threadId, () => {
-    if (this.ctrlConnectionOwner) {
-      this.ctrlConnection.destroy();
-    }
-    this.emit('stopped');
-  });
+  if (!this.stopped) {
+    this.stopped = true;
+    // Binary log connection does not end with destroy()
+    this.connection.destroy();
+    this.ctrlConnection.query('KILL ' + this.connection.threadId, (err, result) => {
+      if (this.ctrlConnectionOwner) {
+        this.ctrlConnection.destroy();
+      }
+      this.emit('stopped');
+    });
+  }
+};
+
+ZongJi.prototype.pause = function () {
+  if (!this.stopped) {
+    this.connection.pause();
+  }
+};
+
+ZongJi.prototype.resume = function () {
+  if (!this.stopped) {
+    this.connection.resume();
+  }
 };
 
 // It includes every events by default.
@@ -312,3 +334,4 @@ ZongJi.prototype._skipSchema = function (database, table) {
 };
 
 module.exports = ZongJi;
+module.exports.ZongJi = ZongJi;

package.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "description": "A MySQL 8.0 >= compatible fork of ZongJi - a MySQL binlog listener for Node.js.",
   "main": "index.js",
+  "types": "types/index.d.ts",
   "directories": {
     "test": "test"
   },
@@ -35,15 +36,15 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.27.3",
-    "prettier": "^2.8.8",
+    "@changesets/cli": "^2.29.4",
+    "prettier": "^3.5.3",
     "tap": "^21.0.1"
   },
   "dependencies": {
-    "big-integer": "1.6.51",
+    "big-integer": "1.6.52",
     "iconv-lite": "0.6.3",
     "@vlasky/mysql": "^2.18.6"
   }