MLE-25554 TS for a handful of documents functions

Author: rjrudin

marklogic.d.ts

@@ -72,11 +72,116 @@ declare module 'marklogic' {
     httpStatusMessage?: string;
   }
 
+  /**
+   * Generic document content type - can be JSON, XML, text, or binary
+   */
+  export type DocumentContent = any;
+
+  /**
+   * A document descriptor for reading or writing documents.
+   */
+  export interface DocumentDescriptor {
+    /** The URI identifier for the document */
+    uri: string;
+    /** The content of the document (JSON, XML, text, or Buffer for binary) */
+    content?: DocumentContent;
+    /** The MIME type of the document */
+    contentType?: string;
+    /** Collections to which the document belongs */
+    collections?: string | string[];
+    /** Permissions controlling document access */
+    permissions?: Array<{
+      'role-name': string;
+      capabilities: string[];
+    }>;
+    /** Properties (metadata) for the document */
+    properties?: Record<string, any>;
+    /** Quality ranking for the document */
+    quality?: number;
+    /** Metadata values for the document */
+    metadataValues?: Record<string, any>;
+  }
+
+  /**
+   * Result from a probe operation indicating if a document exists.
+   */
+  export interface ProbeResult {
+    /** The URI of the document */
+    uri: string;
+    /** Whether the document exists */
+    exists: boolean;
+    /** Content type if document exists */
+    contentType?: string;
+    /** Content length if document exists */
+    contentLength?: number;
+  }
+
+  /**
+   * Result from a remove operation.
+   */
+  export interface RemoveResult {
+    /** Array of removed document URIs */
+    uris: string[];
+    /** Whether documents were removed */
+    removed: boolean;
+    /** System time of the operation */
+    systemTime?: string;
+  }
+
+  /**
+   * Result from a write operation.
+   */
+  export interface WriteResult {
+    /** Array of document descriptors with URIs of written documents */
+    documents: DocumentDescriptor[];
+    /** System time of the operation */
+    systemTime?: string;
+  }
+
+  /**
+   * Documents interface for reading and writing documents.
+   */
+  export interface Documents {
+    /**
+     * Checks whether a document exists.
+     * @param uri - The URI of the document to check
+     * @returns A result provider that resolves to probe result
+     */
+    probe(uri: string): ResultProvider<ProbeResult>;
+
+    /**
+     * Reads one or more documents.
+     * @param uris - A URI string or array of URI strings
+     * @returns A result provider that resolves to an array of document descriptors
+     */
+    read(uris: string | string[]): ResultProvider<DocumentDescriptor[]>;
+
+    /**
+     * Writes one or more documents.
+     * @param documents - A document descriptor or array of document descriptors
+     * @returns A result provider that resolves to a write result with document URIs
+     */
+    write(documents: DocumentDescriptor | DocumentDescriptor[]): ResultProvider<WriteResult>;
+
+    /**
+     * Removes one or more documents.
+     * @param uris - A URI string or array of URI strings
+     * @returns A result provider that resolves to a remove result
+     */
+    remove(uris: string | string[]): ResultProvider<RemoveResult>;
+  }
+
   /**
    * A database client object returned by createDatabaseClient.
    * Provides access to document, graph, and query operations.
    */
   export interface DatabaseClient {
+    /**
+     * Documents interface for reading and writing documents.
+     * @since 1.0
+     */
+    documents: Documents;
+
     /**
      * Tests if a connection is successful.
      * Call .result() to get a promise.

package.json

@@ -18,9 +18,10 @@
   "scripts": {
     "doc": "jsdoc -c jsdoc.json lib/*.js README.md",
     "lint": "gulp lint",
+    "pretest:typescript": "npm run test:compile",
     "test:types": "tsc --noEmit",
-    "test:compile": "tsc test-typescript/checkConnection-runtime.test.ts",
-    "pretest:typescript": "npm run test:compile"
+    "test:compile": "tsc test-typescript/*-runtime.test.ts",
+    "test:typescript": "npx mocha test-typescript/*.js"
   },
   "keywords": [
     "marklogic",

test-typescript/documents-runtime.test.ts

@@ -0,0 +1,114 @@
+/*
+* Copyright (c) 2015-2025 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
+*/
+
+/// <reference path="../marklogic.d.ts" />
+
+/**
+ * Runtime validation tests for Documents API.
+ *
+ * These tests make actual calls to MarkLogic to verify:
+ * - Type definitions match runtime behavior
+ * - ResultProvider pattern works correctly
+ * - Methods return expected data structures
+ *
+ * Run with: npm run test:compile && npx mocha test-typescript/*.js
+ */
+
+import should = require('should');
+import type { DatabaseClient } from 'marklogic';
+
+const testConfig = require('../etc/test-config.js');
+const marklogic = require('../lib/marklogic.js');
+
+describe('Documents API runtime validation', function() {
+  let client: DatabaseClient;
+  const testUri = '/test-typescript/documents-runtime-test.json';
+  const testContent = { message: 'TypeScript test document', timestamp: Date.now() };
+
+  before(function() {
+    client = marklogic.createDatabaseClient(testConfig.restWriterConnection);
+  });
+
+  after(function() {
+    client.release();
+  });
+
+  it('write() returns ResultProvider with WriteResult', async function() {
+    const resultProvider = client.documents.write({
+      uri: testUri,
+      content: testContent,
+      contentType: 'application/json'
+    });
+
+    // Verify ResultProvider has result() method
+    resultProvider.should.have.property('result');
+    resultProvider.result.should.be.a.Function();
+
+    const writeResult = await resultProvider.result();
+
+    // Verify return type is WriteResult with documents array
+    writeResult.should.be.an.Object();
+    writeResult.should.have.property('documents');
+    writeResult.documents.should.be.an.Array();
+    writeResult.documents.should.have.length(1);
+    writeResult.documents[0].should.have.property('uri');
+    writeResult.documents[0].uri.should.equal(testUri);
+  });
+
+  it('probe() returns ResultProvider with ProbeResult', async function() {
+    const resultProvider = client.documents.probe(testUri);
+
+    // Verify ResultProvider has result() method
+    resultProvider.should.have.property('result');
+    resultProvider.result.should.be.a.Function();
+
+    const probeResult = await resultProvider.result();
+
+    // Verify ProbeResult structure
+    probeResult.should.have.property('uri', testUri);
+    probeResult.should.have.property('exists', true);
+    probeResult.should.have.property('contentType');
+    probeResult.should.have.property('contentLength');
+  });
+
+  it('read() returns ResultProvider with DocumentDescriptor array', async function() {
+    const resultProvider = client.documents.read(testUri);
+
+    // Verify ResultProvider has result() method
+    resultProvider.should.have.property('result');
+    resultProvider.result.should.be.a.Function();
+
+    const docs = await resultProvider.result();
+
+    // Verify return type is DocumentDescriptor array
+    docs.should.be.an.Array();
+    docs.should.have.length(1);
+
+    const doc = docs[0];
+    doc.should.have.property('uri', testUri);
+    doc.should.have.property('content');
+    doc.content.should.have.property('message', testContent.message);
+  });
+
+  it('remove() returns ResultProvider with RemoveResult', async function() {
+    const resultProvider = client.documents.remove(testUri);
+
+    // Verify ResultProvider has result() method
+    resultProvider.should.have.property('result');
+    resultProvider.result.should.be.a.Function();
+
+    const result = await resultProvider.result();
+
+    // Verify RemoveResult structure
+    result.should.have.property('uris');
+    result.should.have.property('removed', true);
+    result.uris.should.be.an.Array();
+    result.uris.should.have.length(1);
+    result.uris[0].should.equal(testUri);
+
+    // Verify document was actually removed
+    const probeResult = await client.documents.probe(testUri).result();
+    probeResult.exists.should.equal(false);
+  });
+});