Merge pull request #397 from wooldridge/issues/303-compatibility

fix(#303): Update README with compatibility info

Author: wooldridge

README.md

@@ -15,7 +15,9 @@ from Node.js applications.
 
 ## Status
 
-Release 2.0.1 of the MarkLogic Node.js Client API
+Release 2.0.1 of the MarkLogic Node.js Client API, tested to work with MarkLogic
+versions 8.0-6.3 and 9.0-1. To use the new features available in release 2.0.1,
+you will need to run MarkLogic version 9.
 
 ## New Features in Release 2.0.1
 

lib/documents.js

@@ -131,6 +131,7 @@ function wipeOutputTransform(/*headers, data*/) {
  * {@link https://www.promisejs.org/|Promises} object for chaining
  * actions with then() functions.
  * @name ResultProvider#result
+ * @since 1.0
  * @function
  * @param {function}  [success] - a callback invoked when the request succeeds
  * @param {function}  [failure] - a callback invoked when the request fails
@@ -140,6 +141,7 @@ function wipeOutputTransform(/*headers, data*/) {
  * Returns a ReadableStream object in object mode for receiving results as
  * complete objects.
  * @name ResultProvider#stream
+ * @since 1.0
  * @function
  * @returns {object} a {@link http://nodejs.org/api/stream.html#stream_class_stream_readable|ReadableStream}
  * object
@@ -150,6 +152,7 @@ function wipeOutputTransform(/*headers, data*/) {
  * from the server, or for another document operation.  The descriptor may have
  * more or fewer properties depending on the operation.
  * @typedef {object} documents.DocumentDescriptor
+ * @since 1.0
  * @property {string} uri - the identifier for the document in the database
  * @property {object|string|Buffer|ReadableStream} [content] - the content
  * of the document; when writing a ReadableStream for the content, first pause
@@ -172,12 +175,14 @@ function wipeOutputTransform(/*headers, data*/) {
  * content|collections|permissions|properties|quality|metadataValues|metadata where
  * metadata is an alias for all of the categories other than content.
  * @typedef {enum} documents.categories
+ * @since 1.0
  */
 
 /**
  * A success callback for {@link ResultProvider} that receives the result from
  * the {@link documents#probe}.
  * @callback documents#probeResult
+ * @since 1.0
  * @param {documents.DocumentDescriptor} document - a sparse document descriptor with an exists
  * property that identifies whether the document exists
  */
@@ -186,6 +191,7 @@ function wipeOutputTransform(/*headers, data*/) {
  * object with the following named parameters or, as a shortcut,
  * a uri string.
  * @method documents#probe
+ * @since 1.0
  * @param {string}  uri - the uri for the database document
  * @param {string|transactions.Transaction}  [txid] - a string
  * transaction id or Transaction object identifying an open
@@ -251,13 +257,15 @@ function probeDocumentsImpl(contentOnly, args) {
  * A success callback for {@link ResultProvider} that receives the result from
  * the {@link documents#protect}.
  * @callback documents#protectResult
+ * @since 2.0.1
  * @param {documents.DocumentDescriptor} document - a sparse document descriptor
  * for the protected document
  */
 /**
  * Protects a temporal document from temporal operations for a
  * period of time.
  * @method documents#protect
+ * @since 2.0.1
  * @param {string} uri - the uri for the temporal document to protect
  * @param {string} temporalCollection - the temporal collection for the document
  * @param {string} [duration] - a protection duration; either a duration or an
@@ -375,12 +383,14 @@ Documents.prototype.protect = function protectDocument() {
  * A success callback for {@link ResultProvider} that receives the result from
  * the {@link documents#wipe}.
  * @callback documents#wipeResult
+ * @since 2.0.1
  * @param {documents.DocumentDescriptor} document - a sparse document descriptor
  * for the wipe command
  */
 /**
  * Deletes all versions of a temporal document.
  * @method documents#wipe
+ * @since 2.0.1
  * @param {string} uri - the uri for the temporal document to wipe
  * @param {string} temporalCollection - the name of the temporal collection
  * @returns {ResultProvider} an object whose result() function takes
@@ -500,6 +510,7 @@ function singleReadOutputTransform(headers, data) {
  * A success callback for {@link ResultProvider} that receives the result from
  * the {@link documents#read}.
  * @callback documents#resultList
+ * @since 1.0
  * @param {documents.DocumentDescriptor[]} documents - an array of
  * {@link documents.DocumentDescriptor} objects with the requested
  * metadata and/or content for the documents
@@ -509,6 +520,7 @@ function singleReadOutputTransform(headers, data) {
  * the following named parameters or, as a shortcut, one or more
  * uri strings or an array of uri strings.
  * @method documents#read
+ * @since 1.0
  * @param {string|string[]}  uris - the uri string or an array of uri strings
  * for the database documents
  * @param {documents.categories|documents.categories[]}  [categories] - the categories of information
@@ -681,6 +693,7 @@ function readDocumentsImpl(contentOnly, args) {
  * a stream; takes a {@link documents.DocumentDescriptor} object with the
  * following properties (but not a content property).
  * @method documents#createWriteStream
+ * @since 1.0
  * @param {string} uri - the identifier for the document to write to the database
  * @param {string[]} [collections] - the collections to which the document should belong
  * @param {object[]} [permissions] - the permissions controlling which users can read or
@@ -826,6 +839,7 @@ function writeListOutputTransform(headers, data) {
  * the {@link documents#write} or the {@link documents#createWriteStream}
  * functions.
  * @callback documents#writeResult
+ * @since 1.0
  * @param {object} response - a response with a documents property providing
  * a sparse array of array of {@link documents.DocumentDescriptor} objects
  * providing the uris of the written documents.
@@ -834,6 +848,7 @@ function writeListOutputTransform(headers, data) {
  * Writes one or more documents; takes a configuration object with
  * the following named parameters or, as a shortcut, a document descriptor.
  * @method documents#write
+ * @since 1.0
  * @param {DocumentDescriptor|DocumentDescriptor[]} documents - one descriptor
  * or an array of document descriptors to write
  * @param {documents.categories|documents.categories[]}  [categories] - the categories of information
@@ -1387,6 +1402,7 @@ function removeOutputTransform(headers/*, data*/) {
  * A success callback for {@link ResultProvider} that receives the result from
  * the {@link documents#remove}.
  * @callback documents#removeResult
+ * @since 1.0
  * @param {documents.DocumentDescriptor} document - a sparse document descriptor
  * for the removed document
  */
@@ -1395,6 +1411,7 @@ function removeOutputTransform(headers/*, data*/) {
  * object with the following named parameters or, as a shortcut, one or more
  * uri strings or an array of uri strings.
  * @method documents#remove
+ * @since 1.0
  * @param {string|string[]}  uris - the uri string or an array of uri strings
  * identifying the database documents
  * @param {string|transactions.Transaction}  [txid] - a string
@@ -1519,6 +1536,7 @@ function removeAllOutputTransform(/*headers, data*/) {
  * have the rest-admin role to to delete all documents and the rest-writer
  * role otherwise.
  * @method documents#removeAll
+ * @since 1.0
  * @param {string}  [collection] - the collection whose documents should be
  * deleted
  * @param {string}  [directory] - a directory whose documents should be
@@ -1607,6 +1625,7 @@ function listOutputTransform(headers, data) {
 /**
  * Defines a query in the structure accepted by the REST API.
  * @typedef {object} documents.CombinedQueryDefinition
+ * @since 1.0
  * @property {object} search - a combined query, which can have properties
  * for a structured query, a string query, and query options
  * @property {documents.categories|documents.categories[]}  [categories] - the categories
@@ -1632,6 +1651,7 @@ function listOutputTransform(headers, data) {
  * Executes a query built by a {@link queryBuilder} to match one or more
  * documents.
  * @method documents#query
+ * @since 1.0
  * @param {object}  query - a query built by a {@link queryBuilder} or
  * a {@link documents.CombinedQueryDefinition}
  * @returns {ResultProvider} an object whose result() function takes
@@ -1791,6 +1811,7 @@ function patchOutputTransform(/*headers, data*/) {
  * A success callback for {@link ResultProvider} that receives the result from
  * the {@link documents#patch} function.
  * @callback documents#patchResult
+ * @since 1.0
  * @param {object} document - a sparse {@link documents.DocumentDescriptor} object
  * providing the uri of the patched document.
  */
@@ -1799,6 +1820,7 @@ function patchOutputTransform(/*headers, data*/) {
  * the following named parameters or, as a shortcut, a uri string and
  * one or more patch operations produced by a {@link patchBuilder}.
  * @method documents#patch
+ * @since 1.0
  * @param {string}  uri - the uri
  * @param {patchOperation|patchOperation[]} operations - delete, insert,
  * or replace operations produced by a {@link patchBuilder} to apply
@@ -1968,6 +1990,7 @@ Documents.prototype.patch = function patchDocuments() {
  * You may pass a configuration object with the following named parameters or,
  * as a shortcut, the partial textual search, the query, and optionally bindings.
  * @method documents#suggest
+ * @since 1.0
  * @param {string} partial - the partial search string to complete
  * @param {object} query - a query built by a {@link queryBuilder} or
  * a {@link documents.CombinedQueryDefinition} that defines bindings in

lib/extlibs.js

@@ -31,7 +31,7 @@ function pathErrorTransform(message) {
 /**
  * Provides functions to maintain extension libraries on the REST server
  * for the client. The client must have been created for a user with the
- * rest-admin role. 
+ * rest-admin role.
  * @namespace config.extlibs
  */
 
@@ -56,6 +56,7 @@ function ExtLibs(client) {
 /**
  * Reads a library resource installed on the server.
  * @method config.extlibs#read
+ * @since  1.0
  * @param {string} path - the location of an installed library resource
  * @returns {ResultProvider} an object whose result() function takes
  * a success callback that receives the resource
@@ -85,6 +86,7 @@ ExtLibs.prototype.read = function readExtensionLibrary(path) {
 /**
  * Installs a library resource on the server.
  * @method config.extlibs#write
+ * @since  1.0
  * @param {string} path - the location for installing the library resource
  * @param {object[]} [permissions] - the permissions controlling which users can read, update, or
  * execute the library resource
@@ -111,16 +113,16 @@ ExtLibs.prototype.write = function writeExtensionLibrary() {
     path        = params.path;
     permissions = params.permissions;
     contentType = params.contentType;
-    source      = params.source;    
+    source      = params.source;
   } else {
     var argMax = Math.min(argLen,4);
     for (;i < argMax; i++) {
       arg = args[i];
       if (typeof arg === 'string' || arg instanceof String) {
         if (path === null) {
-          path = arg; 
+          path = arg;
         } else if (contentType === null) {
-          contentType = arg; 
+          contentType = arg;
         }
       } else if (Array.isArray(arg)) {
         permissions = arg;
@@ -137,7 +139,7 @@ ExtLibs.prototype.write = function writeExtensionLibrary() {
     throw new Error('must specify the path, content type, and source when writing a extension library');
   }
 
-  var endpoint = 
+  var endpoint =
       (path.substr(0,5) === '/ext/') ? ('/v1'+path)     :
       (path.substr(0,1) === '/')     ? ('/v1/ext'+path) :
       ('/v1/ext/'+path);
@@ -151,7 +153,7 @@ ExtLibs.prototype.write = function writeExtensionLibrary() {
       role = arg['role-name'];
       capabilities = arg.capabilities;
       if ((role === void 0) || !Array.isArray(capabilities) || capabilities.length < 1) {
-        throw new Error('cannot set permissions from '+JSON.stringify(arg));        
+        throw new Error('cannot set permissions from '+JSON.stringify(arg));
       }
       for (j=0; j < capabilities.length; j++) {
         endpoint += ((i === 0 && j=== 0) ? '?' : '&') + 'perm:'+role+'='+capabilities[j];
@@ -180,6 +182,7 @@ ExtLibs.prototype.write = function writeExtensionLibrary() {
 /**
  * Deletes a library resource from the server.
  * @method config.extlibs#remove
+ * @since  1.0
  * @param {string} path - the location of the library resource
  */
 ExtLibs.prototype.remove = function removeExtensionLibrary(path) {
@@ -208,6 +211,7 @@ ExtLibs.prototype.remove = function removeExtensionLibrary(path) {
 /**
  * Lists the library resources installed under the directory on the server.
  * @method config.extlibs#list
+ * @since  1.0
  * @param {string} [directory] - a directory containing library resources;
  * by default, all library resources installed on the server are returned
  * @returns {ResultProvider} an object whose result() function takes
@@ -222,10 +226,10 @@ ExtLibs.prototype.list = function listExtensionLibraries(directory) {
   };
 
   if (typeof directory !== 'string' && !(directory instanceof String)) {
-    requestOptions.path = '/v1/ext';  
+    requestOptions.path = '/v1/ext';
   } else if (directory.substr(0,5) === '/ext/') {
     if (directory.substr(-1,1) === '/') {
-      requestOptions.path = encodeURI(directory);      
+      requestOptions.path = encodeURI(directory);
     } else {
       requestOptions.path = encodeURI(directory+'/');
     }

lib/graphs.js

@@ -113,6 +113,7 @@ function Graphs(client) {
 /**
  * Reads the triples for a graph from the server in the specified format.
  * @method graphs#read
+ * @since 1.0
  * @param {string} [uri] - a graph name, which can be ommitted for the default graph
  * @param {string} contentType - the format for the graph such as application/n-quads,
  * application/n-triples, application/rdf+json, application/rdf+xml, text/n3, text/turtle,
@@ -195,6 +196,7 @@ Graphs.prototype.read = function readGraph() {
 /**
  * Creates or replaces the triples for the specified graph.
  * @method graphs#write
+ * @since 1.0
  * @param {string} [uri] - a graph name, which can be ommitted for the default graph
  * @param {string} contentType - the format for the graph such as application/n-quads,
  * application/n-triples, application/rdf+json, application/rdf+xml, text/n3, text/turtle,
@@ -213,6 +215,7 @@ Graphs.prototype.write = function writeGraph() {
 /**
  * Adds the triples for the specified graph.
  * @method graphs#merge
+ * @since 1.0
  * @param {string} [uri] - a graph name, which can be ommitted for the default graph
  * @param {string} contentType - the format for the graph such as application/n-quads,
  * application/n-triples, application/rdf+json, application/rdf+xml, text/n3, text/turtle,
@@ -232,6 +235,7 @@ Graphs.prototype.merge = function mergeGraph() {
  * Creates or replaces the triples for the specified graph in incremental chunks with
  * a stream; takes the following parameters (but not a data parameter).
  * @method graphs#createWriteStream
+ * @since 1.0
  * @param {string} [uri] - a graph name, which can be ommitted for the default graph
  * @param {string} contentType - the format for the graph such as application/n-quads,
  * application/n-triples, application/rdf+json, application/rdf+xml, text/n3, text/turtle,
@@ -249,6 +253,7 @@ Graphs.prototype.createWriteStream = function createGraphWriteStream() {
  * Adds the triples for the specified graph in incremental chunks with
  * a stream; takes the following parameters (but not a data parameter).
  * @method graphs#createMergeStream
+ * @since 1.0
  * @param {string} [uri] - a graph name, which can be omitted for the default graph
  * @param {string} contentType - the format for the graph such as application/n-quads,
  * application/n-triples, application/rdf+json, application/rdf+xml, text/n3, text/turtle,
@@ -387,6 +392,7 @@ function changeGraph(action, isStreaming, args) {
 /**
  * Removes the specified graph.
  * @method graphs#remove
+ * @since 1.0
  * @param {string} [uri] - a graph name, which can be omitted for the default graph
  * @param {string|transactions.Transaction}  [txid] - a string
  * transaction id or Transaction object identifying an open
@@ -402,6 +408,7 @@ Graphs.prototype.remove = function removeGraph() {
 /**
  * Check whether the specified graph exists.
  * @method graphs#probe
+ * @since 1.0
  * @param {string} [uri] - a graph name, which can be omitted for the default graph
  * @param {string|transactions.Transaction}  [txid] - a string
  * transaction id or Transaction object identifying an open
@@ -489,6 +496,7 @@ function applyGraph(action, args) {
 /**
  * Lists the graphs stored on the server.
  * @method graphs#list
+ * @since 1.0
  * @param {string} contentType - the format for the list of graphs
  * @param {string|transactions.Transaction}  [txid] - a string
  * transaction id or Transaction object identifying an open
@@ -552,6 +560,7 @@ Graphs.prototype.list = function listGraphs() {
  * configuration object with the following named parameters or, as a shortcut,
  * a contentType string, any number of default graph URIs, and a SPARQL query.
  * @method graphs#sparql
+ * @since 1.0
  * @param {string} contentType - the format for the query response
  * @param {string|string[]} [defaultGraphs] - the default graphs for the SPARQL query
  * @param {string|string[]} [namedGraphs] - the named graphs for the SPARQL query
@@ -735,6 +744,7 @@ Graphs.prototype.sparql = function queryGraphSPARQL() {
  * Executes a SPARQL update against the graphs; takes a configuration object with
  * the following named parameters or, as a shortcut, the SPARQL update data.
  * @method graphs#sparqlUpdate
+ * @since 1.0
  * @param {string|ReadableStream} data - the SPARQL update
  * @param {object[]} [permissions] - the permissions controlling which users can read or
  * write the documents with the updated triples