MLE-24194 Fixing checkConnection and better tests

This was way harder than it should have been, but Copilot finally got it done. checkConnection had the wrong return type, so the method didn't actually working in a "real" TS test - and we now have a "real" TS test. See the Copilot-authored README for explanation.

Author: rjrudin

.gitignore

@@ -18,4 +18,7 @@ test-app/containerLogs
 test-complete-app/build
 test-complete-app/.gradle
 test-complete-app-mlDeploy/build
-test-complete-app-mlDeploy/.gradle
+test-complete-app-mlDeploy/.gradle
+
+# Compiled TypeScript test files
+test-typescript/*.js

Jenkinsfile

@@ -78,6 +78,17 @@ def runTypeCheck() {
 	'''
 }
 
+def runTypeScriptTests() {
+  sh label: 'run-typescript-tests', script: '''
+    export PATH=${NODE_HOME_DIR}/bin:$PATH
+    cd node-client-api
+    npm ci
+    npm run test:compile
+    ./node_modules/.bin/mocha --timeout 10000 test-typescript/*.js --reporter mocha-junit-reporter --reporter-options mochaFile=$WORKSPACE/test-typescript-reports.xml || true
+	'''
+  junit '**/*test-typescript-reports.xml'
+}
+
 def runE2ETests() {
   sh label: 'run-e2e-tests', script: '''
     export PATH=${NODE_HOME_DIR}/bin:$PATH
@@ -142,6 +153,7 @@ pipeline {
         runTypeCheck()
         runDockerCompose('ml-docker-db-dev-tierpoint.bed-artifactory.bedford.progress.com/marklogic/marklogic-server-ubi:latest-12')
         runTests()
+        runTypeScriptTests()
         runE2ETests()
       }
       post {
@@ -165,6 +177,7 @@ pipeline {
           steps {
             runDockerCompose('ml-docker-db-dev-tierpoint.bed-artifactory.bedford.progress.com/marklogic/marklogic-server-ubi:latest-11')
             runTests()
+            runTypeScriptTests()
             runE2ETests()
           }
           post {
@@ -185,6 +198,7 @@ pipeline {
           steps {
             runDockerCompose('ml-docker-db-dev-tierpoint.bed-artifactory.bedford.progress.com/marklogic/marklogic-server-ubi:latest-12')
             runTests()
+            runTypeScriptTests()
             runE2ETests()
           }
           post {
@@ -205,6 +219,7 @@ pipeline {
           steps {
             runDockerCompose('ml-docker-db-dev-tierpoint.bed-artifactory.bedford.progress.com/marklogic/marklogic-server-ubi:latest-10')
             runTests()
+            runTypeScriptTests()
             runE2ETests()
           }
           post {

lib/responder.js

@@ -1224,7 +1224,7 @@ function operationResultStream() {
 function operationErrorListener(error) {
   /*jshint validthis:true */
   const operation = this;
-  if(operation.client.connectionParams.apiKey){
+  if(operation.client.connectionParams && operation.client.connectionParams.apiKey){
     if(error.statusCode === 401 && operation.expiration <= (new Date())){
       if(!operation.lockAccessToken){
         operation.lockAccessToken = true;

marklogic.d.ts

@@ -79,10 +79,11 @@ declare module 'marklogic' {
   export interface DatabaseClient {
     /**
      * Tests if a connection is successful.
+     * Call .result() to get a promise.
      * @since 2.1
-     * @returns A promise that resolves to an object indicating connection status
+     * @returns A result provider with a result() method
      */
-    checkConnection(): Promise<ConnectionCheckResult>;
+    checkConnection(): ResultProvider<ConnectionCheckResult>;
 
     /**
      * Releases the client and destroys the agent.
@@ -92,6 +93,20 @@ declare module 'marklogic' {
     release(): void;
   }
 
+  /**
+   * A result provider that wraps asynchronous operations.
+   * Call .result() to get a Promise for the result.
+   */
+  export interface ResultProvider<T> {
+    /**
+     * Gets a promise for the operation result.
+     * @param onFulfilled - Optional callback for success
+     * @param onRejected - Optional callback for errors
+     * @returns A promise that resolves to the result
+     */
+    result(onFulfilled?: (value: T) => void, onRejected?: (reason: any) => void): Promise<T>;
+  }
+
   /**
    * Creates a DatabaseClient object for accessing a database.
    * @param config - Configuration for connecting to the database

package-lock.json

@@ -18,7 +18,9 @@
   "scripts": {
     "doc": "jsdoc -c jsdoc.json lib/*.js README.md",
     "lint": "gulp lint",
-    "test:types": "tsc --noEmit"
+    "test:types": "tsc --noEmit",
+    "test:compile": "tsc test-typescript/checkConnection-runtime.test.ts",
+    "pretest:typescript": "npm run test:compile"
   },
   "keywords": [
     "marklogic",
@@ -53,6 +55,7 @@
   },
   "devDependencies": {
     "@jsdoc/salty": "0.2.9",
+    "@types/mocha": "10.0.10",
     "@types/node": "22.10.1",
     "ajv": "8.17.1",
     "ast-types": "0.14.2",

package.json

@@ -2,23 +2,72 @@
 
 This directory contains TypeScript tests to verify that the type definitions in `marklogic.d.ts` work correctly.
 
-## How to Test Types
+## Types of Tests
+
+### 1. Compile-Only Tests (Type Checking)
+Files like `basic-types.test.ts`, `connection-methods.test.ts`, `type-constraints.test.ts`, `error-examples.test.ts`
+
+- **Purpose**: Verify that TypeScript code compiles without errors
+- **Execution**: Not executed at runtime - only compiled
+- **Speed**: Very fast (seconds)
+- **Requirements**: No MarkLogic server needed
+- **Run with**: `npm run test:types`
+
+These tests validate:
+- Type definitions are syntactically correct
+- Type constraints work (e.g., `authType` only accepts valid values)
+- IntelliSense will work for users
+- Type errors are caught at compile time
+
+### 2. Runtime Tests
+Files like `checkConnection-runtime.test.ts`
 
-Run the type checking with:
+- **Purpose**: Verify that TypeScript definitions match actual runtime behavior
+- **Execution**: Compiled to JavaScript and executed with mocha
+- **Speed**: Slower (requires MarkLogic)
+- **Requirements**: MarkLogic server running
+- **Run with**: `npm run test:compile && npx mocha test-typescript/*.js`
 
+These tests validate:
+- Types compile correctly (compile-time check)
+- Real API calls return the expected types (runtime check)
+- TypeScript definitions accurately reflect the actual JavaScript behavior
+
+## How to Test Types
+
+### Type Checking Only
 ```bash
 npm run test:types
 ```
 
-This command runs `tsc --noEmit`, which checks for TypeScript errors without generating JavaScript files.
+This runs `tsc --noEmit`, which checks for TypeScript errors without generating JavaScript files.
+
+### Runtime Tests
+```bash
+npm run test:compile    # Compile TypeScript tests to JavaScript
+npx mocha test-typescript/*.js    # Run compiled tests against MarkLogic
+```
+
+Or in one command:
+```bash
+npm run test:compile && npx mocha test-typescript/*.js
+```
+
+## Why Two Approaches?
 
-## Why This Approach?
+**Compile-only tests** are great for:
+- Fast feedback during development
+- Catching type definition errors quickly
+- CI/CD pre-flight checks (before spinning up MarkLogic)
+- Validating that autocomplete/IntelliSense will work
 
-TypeScript's compiler is the best way to test type definitions because:
-- It catches type errors at compile time (before runtime)
-- It validates type constraints (like union types for `authType`)
-- It ensures IntelliSense and autocomplete will work for users
-- It's fast and doesn't require running actual code
+**Runtime tests** are essential for:
+- Ensuring type definitions match actual behavior
+- Catching mismatches between declared types and runtime values
+- Integration testing with real MarkLogic instances
+- Preventing issues like returning `{}` when a `Promise` was expected
+
+Both approaches complement each other for comprehensive type safety validation.
 
 ## Example: Testing for Type Errors
 
@@ -40,3 +89,22 @@ error TS2322: Type '"invalid-type"' is not assignable to type 'basic' | 'digest'
 ```
 
 This confirms your types are working correctly!
+
+## Adding New Tests
+
+### To add a compile-only test:
+1. Create a `.test.ts` file in this directory
+2. Use `/// <reference path="../marklogic.d.ts" />` to load types
+3. Import types with: `type MyType = import('marklogic').MyType;`
+4. Write code that should compile (or intentionally fail)
+5. Run `npm run test:types` to verify
+
+### To add a runtime test:
+1. Create a `.test.ts` file in this directory
+2. Use the same reference and import pattern as above
+3. Import test framework: `import should = require('should');`
+4. Use `describe`/`it` blocks like normal mocha tests
+5. Make actual API calls to MarkLogic
+6. Compile with `npm run test:compile` and run with mocha
+
+**Note**: Compiled `.js` files are gitignored and regenerated on each test run.

test-typescript/README.md

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2015-2025 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
+ */
+
+/// <reference path="../marklogic.d.ts" />
+
+/**
+ * TypeScript runtime test to validate that checkConnection returns ResultProvider.
+ * This test ensures the TypeScript definitions match the actual runtime behavior
+ * by making real calls to MarkLogic AND verifying types at compile time.
+ */
+
+import should = require('should');
+const marklogic = require('..');
+const testconfig = require('../etc/test-config-qa.js');
+
+const db = marklogic.createDatabaseClient(testconfig.restReaderConnection);
+
+// Type alias for easier reference
+type ResultProvider<T> = import('marklogic').ResultProvider<T>;
+type ConnectionCheckResult = import('marklogic').ConnectionCheckResult;
+type DatabaseClientConfig = import('marklogic').DatabaseClientConfig;
+
+describe('checkConnection ResultProvider validation', function() {
+
+  it('should return ResultProvider with .result() method', function(done) {
+    // This validates that checkConnection returns a ResultProvider
+    // TypeScript will verify the type at compile time
+    const resultProvider: ResultProvider<ConnectionCheckResult> = db.checkConnection();
+
+    // Verify it has a .result() method (core requirement for ResultProvider)
+    should(resultProvider).have.property('result');
+    should(resultProvider.result).be.a.Function();
+
+    // Call .result() to get a Promise
+    const promise: Promise<ConnectionCheckResult> = resultProvider.result();
+
+    // Verify .result() returns a Promise (thenable)
+    should(promise).have.property('then');
+    should(promise.then).be.a.Function();
+
+    // Verify the Promise resolves to ConnectionCheckResult
+    promise.then((response: ConnectionCheckResult) => {
+      should(response).have.property('connected');
+      should(response.connected).be.a.Boolean();
+
+      if (response.connected === true) {
+        done();
+      } else {
+        done(new Error('Expected connection to succeed but got: ' + JSON.stringify(response)));
+      }
+    }).catch(done);
+  });
+
+  it('should work with async/await pattern', async function() {
+    // TypeScript verifies the return type matches ConnectionCheckResult
+    const result: ConnectionCheckResult = await db.checkConnection().result();
+
+    // Verify result shape matches ConnectionCheckResult
+    should(result).have.property('connected');
+    should(result.connected).be.a.Boolean();
+    should(result.connected).equal(true);
+  });
+
+  it('should have error properties when connection fails', function(done) {
+    // Test with wrong password to get a failed connection
+    const config: DatabaseClientConfig = {
+      host: testconfig.restReaderConnection.host,
+      user: testconfig.restReaderConnection.user,
+      password: 'wrongpassword',  // Invalid password
+      port: testconfig.restReaderConnection.port,
+      authType: testconfig.restReaderConnection.authType
+    };
+    const db1 = marklogic.createDatabaseClient(config);
+
+    db1.checkConnection().result().then((response: ConnectionCheckResult) => {
+      should(response).have.property('connected');
+      should(response.connected).be.a.Boolean();
+
+      if (response.connected === false) {
+        // When connected is false, optional error properties should exist
+        should(response).have.property('httpStatusCode');
+        should(response.httpStatusCode).be.a.Number();
+        should(response).have.property('httpStatusMessage');
+        should(response.httpStatusMessage).be.a.String();
+      }
+
+      db1.release();
+      done();
+    }).catch(done);
+  });
+
+  after(function(done) {
+    db.release();
+    done();
+  });
+});

test-typescript/checkConnection-runtime.test.ts

@@ -5,11 +5,12 @@
     "lib": ["ES2020"],
     "strict": true,
     "esModuleInterop": true,
-    "skipLibCheck": false,
+    "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "moduleResolution": "node",
     "resolveJsonModule": true,
-    "noEmit": true
+    "noEmit": false,
+    "outDir": "test-typescript"
   },
   "include": ["test-typescript/**/*"],
   "exclude": ["node_modules", "test-typescript/basic-types.test.ts"]

tsconfig.json

@@ -6,7 +6,10 @@
   "scripts": {
     "setup": "npm install .. && npm install",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck"
+    "test": "npm run typecheck",
+    "build": "tsc",
+    "start": "node test.js",
+    "run": "npm run build && npm run start"
   },
   "keywords": [
     "marklogic",