Skip to content

Commit 55f7d74

Browse files
rjrudinrjrudin
committed
MLE-24194 Adding TS for releaseClient and checkConnection
Also added a test-project for manual testing.
1 parent 0ce247f commit 55f7d74

File tree

11 files changed

+480
-37
lines changed

11 files changed

+480
-37
lines changed

‎.copyrightconfig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ startyear: 2015
1111
# - Dotfiles already skipped automatically
1212
# Enable by removing the leading '# ' from the next line and editing values.
1313
# filesexcluded: third_party/*, docs/generated/*.md, assets/*.png, scripts/temp_*.py, vendor/lib.js
14-
filesexcluded: .github/*, README.md, Jenkinsfile, test-app/*, *.md, docker-compose.yaml, test-complete-app-mlDeploy/*, *.json
14+
filesexcluded: .github/*, README.md, Jenkinsfile, test-app/*, *.md, docker-compose.yaml, test-complete-app-mlDeploy/*, *.json, *.sh

‎CONTRIBUTING.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,11 @@ or
5858
There are also tests in the `test-complete` folder. The setup for these is more complicated and can
5959
be found in the `Jenkinsfile` file in this repository in the `runE2ETests` function.
6060

61+
## Testing TypeScript support
62+
63+
The 4.1.0 release will add TypeScript support for the client. To try this out locally and manually,
64+
see the `README.md` file in the `./typescript-test-project` directory.
65+
6166
## Generating documentation
6267

6368
After installing the project dependencies, you can build the reference documentation locally from the root

‎marklogic.d.ts‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,13 +60,36 @@ declare module 'marklogic' {
6060
apiVersion?: string;
6161
}
6262

63+
/**
64+
* Result object returned by checkConnection method.
65+
*/
66+
export interface ConnectionCheckResult {
67+
/** Whether the connection was successful */
68+
connected: boolean;
69+
/** HTTP status code if connection failed */
70+
httpStatusCode?: number;
71+
/** HTTP status message if connection failed */
72+
httpStatusMessage?: string;
73+
}
74+
6375
/**
6476
* A database client object returned by createDatabaseClient.
6577
* Provides access to document, graph, and query operations.
6678
*/
6779
export interface DatabaseClient {
68-
// Methods will be added as we expand the type definitions
69-
// For now, this is a placeholder to enable basic typing
80+
/**
81+
* Tests if a connection is successful.
82+
* @since 2.1
83+
* @returns A promise that resolves to an object indicating connection status
84+
*/
85+
checkConnection(): Promise<ConnectionCheckResult>;
86+
87+
/**
88+
* Releases the client and destroys the agent.
89+
* Call this method when you're done with the client to free up resources.
90+
* @since 3.0.0
91+
*/
92+
release(): void;
7093
}
7194

7295
/**
@@ -76,8 +99,17 @@ declare module 'marklogic' {
7699
*/
77100
export function createDatabaseClient(config: DatabaseClientConfig): DatabaseClient;
78101

102+
/**
103+
* Releases a client and destroys its agent.
104+
* This is a standalone function equivalent to calling client.release().
105+
* @since 3.0.0
106+
* @param client - The DatabaseClient to release
107+
*/
108+
export function releaseClient(client: DatabaseClient): void;
109+
79110
const marklogic: {
80111
createDatabaseClient: typeof createDatabaseClient;
112+
releaseClient: typeof releaseClient;
81113
};
82114

83115
export default marklogic;

‎test-typescript/README.md‎

Lines changed: 0 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -12,40 +12,6 @@ npm run test:types
1212

1313
This command runs `tsc --noEmit`, which checks for TypeScript errors without generating JavaScript files.
1414

15-
## What Gets Tested
16-
17-
### ✅ Type Constraints
18-
- Valid values for `authType` (basic, digest, application-level, certificate, kerberos, saml, cloud)
19-
- Optional vs required properties
20-
- Union types (string | Buffer for certificates)
21-
- Array types (string[] for multiple certificates)
22-
23-
### ✅ Type Safety
24-
If you uncomment the error examples in the test files, TypeScript will catch:
25-
- Invalid `authType` values
26-
- Incorrect property types
27-
- Missing required properties
28-
29-
## Test Files
30-
31-
### `type-constraints.test.ts`
32-
Tests the `DatabaseClientConfig` interface constraints without importing the module. This works immediately without needing to simulate package installation.
33-
34-
### `basic-types.test.ts` (currently excluded)
35-
Full integration test that imports the `marklogic` module. To use this:
36-
1. Build/link the package locally (`npm link`)
37-
2. Remove it from the exclude list in `tsconfig.json`
38-
3. Run `npm run test:types` again
39-
40-
## Adding More Type Tests
41-
42-
As you add more interfaces to `marklogic.d.ts`, add corresponding test files here. The pattern is:
43-
44-
1. Create a `.test.ts` file
45-
2. Write TypeScript code that uses the types
46-
3. Include examples that should work AND commented examples that should fail
47-
4. Run `npm run test:types` to verify
48-
4915
## Why This Approach?
5016

5117
TypeScript's compiler is the best way to test type definitions because:

‎test-typescript/connection-methods.test.ts‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
/*
2+
* Copyright (c) 2015-2025 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
3+
*/
4+
5+
/**
6+
* TypeScript type checking tests for connection-related methods.
7+
*
8+
* This file validates:
9+
* - checkConnection() return type
10+
* - release() method
11+
* - releaseClient() standalone function
12+
*
13+
* These tests are compiled but NOT executed - they verify type correctness only.
14+
* Run with: npm run test:types
15+
*/
16+
17+
// Create test types that should match the actual marklogic types
18+
type ConnectionCheckResult = {
19+
connected: boolean;
20+
httpStatusCode?: number;
21+
httpStatusMessage?: string;
22+
};
23+
24+
type DatabaseClient = {
25+
checkConnection(): Promise<ConnectionCheckResult>;
26+
release(): void;
27+
};
28+
29+
type DatabaseClientConfig = {
30+
host?: string;
31+
port?: number;
32+
user?: string;
33+
password?: string;
34+
};
35+
36+
// Simulate the marklogic module interface
37+
type MarkLogicModule = {
38+
createDatabaseClient(config: DatabaseClientConfig): DatabaseClient;
39+
releaseClient(client: DatabaseClient): void;
40+
};
41+
42+
// Test checkConnection() return type
43+
async function testCheckConnection(marklogic: MarkLogicModule) {
44+
const client = marklogic.createDatabaseClient({
45+
host: 'localhost',
46+
port: 8000,
47+
user: 'admin',
48+
password: 'admin'
49+
});
50+
51+
// Should return a Promise<ConnectionCheckResult>
52+
const result = await client.checkConnection();
53+
54+
// result.connected should be boolean
55+
const isConnected: boolean = result.connected;
56+
57+
// When not connected, should have optional error properties
58+
if (!result.connected) {
59+
const statusCode: number | undefined = result.httpStatusCode;
60+
const statusMessage: string | undefined = result.httpStatusMessage;
61+
62+
console.log(`Connection failed: ${statusCode} - ${statusMessage}`);
63+
}
64+
65+
return isConnected;
66+
}
67+
68+
// Test release() method on client
69+
function testRelease(marklogic: MarkLogicModule) {
70+
const client = marklogic.createDatabaseClient({
71+
host: 'localhost',
72+
port: 8000,
73+
user: 'admin',
74+
password: 'admin'
75+
});
76+
77+
// Should be callable with no return value
78+
client.release();
79+
80+
// This is the correct usage pattern
81+
}
82+
83+
// Test releaseClient() standalone function
84+
function testReleaseClientFunction(marklogic: MarkLogicModule) {
85+
const client = marklogic.createDatabaseClient({
86+
host: 'localhost',
87+
port: 8000,
88+
user: 'admin',
89+
password: 'admin'
90+
});
91+
92+
// Should accept a DatabaseClient and return void
93+
marklogic.releaseClient(client);
94+
95+
// This is equivalent to client.release()
96+
}
97+
98+
// Test proper cleanup pattern
99+
async function testProperCleanupPattern(marklogic: MarkLogicModule) {
100+
const client = marklogic.createDatabaseClient({
101+
host: 'localhost',
102+
port: 8000,
103+
user: 'admin',
104+
password: 'admin'
105+
});
106+
107+
try {
108+
const result = await client.checkConnection();
109+
if (result.connected) {
110+
console.log('Connected successfully!');
111+
// Do database operations...
112+
} else {
113+
console.error(`Connection failed: ${result.httpStatusCode}`);
114+
}
115+
} finally {
116+
// Always clean up resources
117+
client.release();
118+
}
119+
}
120+
121+
// Test ConnectionCheckResult structure
122+
const successResult: ConnectionCheckResult = {
123+
connected: true
124+
};
125+
126+
const failureResult: ConnectionCheckResult = {
127+
connected: false,
128+
httpStatusCode: 401,
129+
httpStatusMessage: 'Unauthorized'
130+
};
131+
132+
// These should cause errors if uncommented:
133+
// const invalidResult1: ConnectionCheckResult = {
134+
// connected: 'yes' // Error: should be boolean
135+
// };
136+
137+
// const invalidResult2: ConnectionCheckResult = {
138+
// connected: true,
139+
// httpStatusCode: 'error' // Error: should be number
140+
// };
141+
142+
console.log('✅ Connection method types validated!');
143+
144+
// Export to prevent "unused" errors
145+
export {
146+
testCheckConnection,
147+
testRelease,
148+
testReleaseClientFunction,
149+
testProperCleanupPattern,
150+
successResult,
151+
failureResult
152+
};

‎typescript-test-project/.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Dependencies
2+
node_modules/
3+
package-lock.json
4+
5+
# Compiled output
6+
*.js
7+
*.js.map
8+
*.d.ts
9+
10+
# Build artifacts
11+
dist/
12+
build/
13+
14+
# IDE
15+
.vscode/
16+
.idea/
17+
*.swp
18+
*.swo
19+
*~

‎typescript-test-project/README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Test Project - Realistic TypeScript Usage
2+
3+
This is a **standalone npm project** that demonstrates how users will consume the MarkLogic Node.js Client with TypeScript support.
4+
5+
## Purpose
6+
7+
This folder serves as:
8+
- A realistic demo of TypeScript integration for colleagues and users
9+
- A quick testing ground for new TypeScript features
10+
- Validation that the library works as an installed npm package
11+
- A showcase of IntelliSense and type safety in action
12+
13+
## Quick Start
14+
15+
### 1. Setup (First Time Only)
16+
```bash
17+
cd test-project
18+
npm run setup
19+
```
20+
21+
This will:
22+
- Install the parent `marklogic` package (via `file:..`)
23+
- Install TypeScript and type dependencies
24+
- Set up everything needed for type checking
25+
26+
### 2. Test TypeScript Types
27+
```bash
28+
npm test
29+
# or
30+
npm run typecheck
31+
```
32+
33+
This runs TypeScript's compiler in check-only mode (no JS output).
34+
35+
### 3. Edit and Experiment
36+
Open `test.ts` in your IDE (VS Code, IntelliJ, etc.) and start typing:
37+
- You'll get **autocomplete** for all config properties
38+
- **Hover** over methods to see their signatures
39+
- **IntelliSense** shows available options (like authType values)
40+
- Type **errors are highlighted** in real-time
41+
42+
## How It Works
43+
44+
This project installs the parent `marklogic` package using npm's `file:..` protocol, which:
45+
- Simulates a real npm install
46+
- Picks up the `types` field from `package.json`
47+
- Loads `marklogic.d.ts` automatically
48+
- Provides full TypeScript support
49+
50+
## Demo This to Colleagues
51+
52+
1. **Show autocomplete**: In `test.ts`, type `marklogic.createDatabaseClient({` and watch the suggestions appear
53+
2. **Show type safety**: Try setting `authType: 'invalid'` - TypeScript catches it!
54+
3. **Show IntelliSense**: Hover over `checkConnection()` to see its return type
55+
4. **Show error detection**: Run `npm test` with an invalid config to see type errors
56+
57+
## Files
58+
59+
- `package.json` - Standard npm package configuration
60+
- `tsconfig.json` - TypeScript compiler configuration
61+
- `test.ts` - Example TypeScript code using the marklogic client
62+
- `.gitignore` - Ignores node_modules and build artifacts
63+
64+
## Updating After Changes
65+
66+
If you make changes to the parent `marklogic` package:
67+
68+
```bash
69+
# Quick way - just reinstall the local package
70+
npm install ..
71+
72+
# Or full clean reinstall
73+
rm -rf node_modules package-lock.json
74+
npm run setup
75+
```
76+
77+
## Note
78+
79+
This is a **development/testing project only** - it's not meant to be published. The `"private": true` flag prevents accidental publishing to npm.

‎typescript-test-project/package.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"name": "marklogic-typescript-test-project",
3+
"version": "1.0.0",
4+
"description": "Test project for validating MarkLogic Node.js Client TypeScript definitions",
5+
"private": true,
6+
"scripts": {
7+
"setup": "npm install .. && npm install",
8+
"typecheck": "tsc --noEmit",
9+
"test": "npm run typecheck"
10+
},
11+
"keywords": [
12+
"marklogic",
13+
"typescript",
14+
"test"
15+
],
16+
"author": "",
17+
"license": "Apache-2.0",
18+
"devDependencies": {
19+
"@types/node": "^22.10.1",
20+
"typescript": "^5.7.2"
21+
},
22+
"dependencies": {
23+
"marklogic": "file:.."
24+
}
25+
}

0 commit comments

Comments
 (0)