From 01e6883accfb2dcf1a2f8ec42c3926fa55bfbcd6 Mon Sep 17 00:00:00 2001 From: Mike Wooldridge Date: Tue, 14 Mar 2017 15:05:30 -0700 Subject: [PATCH 1/3] fix(#303): Update README with compatibility info --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dae6a6bc..4e8a1d84 100644 --- a/README.md +++ b/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, compatible with MarkLogic +versions 8 and 9. To use the new features available in 2.0.1, you will need to +run MarkLogic version 9. ## New Features in Release 2.0.1 From 8d6a7db19234a371d5343ab52195cfd03698a13d Mon Sep 17 00:00:00 2001 From: Mike Wooldridge Date: Wed, 15 Mar 2017 14:33:37 -0700 Subject: [PATCH 2/3] Add "since" jsdoc tags to specify compatibility of methods, type def's --- lib/documents.js | 23 +++++++ lib/extlibs.js | 20 +++--- lib/graphs.js | 10 +++ lib/marklogic.js | 31 +++++++++ lib/patch-builder.js | 39 ++++++++++++ lib/query-builder.js | 116 ++++++++++++++++++++++++++++++++++ lib/resources-config.js | 4 ++ lib/resources-exec.js | 4 ++ lib/rest-server-properties.js | 8 ++- lib/server-exec.js | 9 ++- lib/transactions.js | 5 ++ lib/transforms.js | 4 ++ lib/values-builder.js | 9 +++ lib/values.js | 3 +- 14 files changed, 270 insertions(+), 15 deletions(-) diff --git a/lib/documents.js b/lib/documents.js index e31fc41a..c7686c63 100644 --- a/lib/documents.js +++ b/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,6 +257,7 @@ 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 */ @@ -258,6 +265,7 @@ function probeDocumentsImpl(contentOnly, args) { * 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 diff --git a/lib/extlibs.js b/lib/extlibs.js index af5ecfad..bd8511ee 100644 --- a/lib/extlibs.js +++ b/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+'/'); } diff --git a/lib/graphs.js b/lib/graphs.js index da4a686d..7b11055e 100644 --- a/lib/graphs.js +++ b/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 diff --git a/lib/marklogic.js b/lib/marklogic.js index ed90cd69..c568d2d9 100644 --- a/lib/marklogic.js +++ b/lib/marklogic.js @@ -51,6 +51,7 @@ var valuesBuilder = require('./values-builder.js'); /** * Reads a patch replacement library installed on the server. * @method config.patch.replace#read + * @since 1.0 * @param {string} moduleName - the filename without a path for the patch replacement library * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the source code for the library @@ -58,6 +59,7 @@ var valuesBuilder = require('./values-builder.js'); /** * Installs a patch replacement library on the server. * @method config.patch.replace#write + * @since 1.0 * @param {string} moduleName - the filename without a path for the patch replacement library; * the filename must end in an extension registered in the server's mime type mapping table * for the mime type of the source code format; at present, the extension should be ".xqy" @@ -69,11 +71,13 @@ var valuesBuilder = require('./values-builder.js'); /** * Deletes a patch replacement library from the server. * @method config.patch.replace#remove + * @since 1.0 * @param {string} moduleName - the filename without a path for the patch replacement library */ /** * Lists the patch replacement libraries installed on the server. * @method config.patch.replace#list + * @since 1.0 * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the list of replacement libraries */ @@ -87,6 +91,7 @@ var valuesBuilder = require('./values-builder.js'); /** * Reads a custom query library installed on the server. * @method config.query.custom#read + * @since 1.0 * @param {string} moduleName - the filename without a path for the custom query library * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the source code for the library @@ -94,6 +99,7 @@ var valuesBuilder = require('./values-builder.js'); /** * Installs a custom query library on the server. * @method config.query.custom#write + * @since 1.0 * @param {string} moduleName - the filename without a path for the custom query library; * the filename must end in an extension registered in the server's mime type mapping table * for the mime type of the source code format; at present, the extension should be ".xqy" @@ -105,11 +111,13 @@ var valuesBuilder = require('./values-builder.js'); /** * Deletes a custom query library from the server. * @method config.query.custom#remove + * @since 1.0 * @param {string} moduleName - the filename without a path for the custom query library */ /** * Lists the custom query libraries installed on the server. * @method config.query.custom#list + * @since 1.0 * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the list of replacement libraries */ @@ -123,6 +131,7 @@ var valuesBuilder = require('./values-builder.js'); /** * Reads a query snippet library installed on the server. * @method config.query.snippet#read + * @since 1.0 * @param {string} moduleName - the filename without a path for the query snippet library * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the source code for the library @@ -130,6 +139,7 @@ var valuesBuilder = require('./values-builder.js'); /** * Installs a query snippet library on the server. * @method config.query.snippet#write + * @since 1.0 * @param {string} moduleName - the filename without a path for the query snippet library; * the filename must end in an extension registered in the server's mime type mapping table * for the mime type of the source code format; at present, the extension should be ".xqy" @@ -141,11 +151,13 @@ var valuesBuilder = require('./values-builder.js'); /** * Deletes a query snippet library from the server. * @method config.query.snippet#remove + * @since 1.0 * @param {string} moduleName - the filename without a path for the query snippet library */ /** * Lists the custom query libraries installed on the server. * @method config.query.snippet#list + * @since 1.0 * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the list of replacement libraries */ @@ -217,6 +229,7 @@ function expandExtlibsWrapper(action, args) { * and queries. The constructor takes a configuration object with the following * named parameters. * @function marklogic.createDatabaseClient + * @since 1.0 * @param {string} [host=localhost] - the host with the REST server for the database * @param {number} [port=8000] - the port with the REST server for the database * @param {string} [database] - the name of the database to access, defaulting @@ -256,6 +269,7 @@ function MarkLogicClient(connectionParams) { * on documents in the database. As a convenience, the same functions are * provided on the database client. * @name documents + * @since 1.0 * @memberof! DatabaseClient# * @type {documents} */ @@ -264,6 +278,7 @@ function MarkLogicClient(connectionParams) { * Provides functions that open, commit, or rollback multi-statement * transactions. * @name transactions + * @since 1.0 * @memberof! DatabaseClient# * @type {transactions} */ @@ -273,6 +288,7 @@ function MarkLogicClient(connectionParams) { * Provides functions that read, write, merge, remove, list, or query * with SPARQL on triple graphs. * @name graphs + * @since 1.0 * @memberof! DatabaseClient# * @type {graphs} */ @@ -281,6 +297,7 @@ function MarkLogicClient(connectionParams) { * Provides functions that submit get, put, post, or remove requests * to resource service extensions. * @name resources + * @since 1.0 * @memberof! DatabaseClient# * @type {resources} */ @@ -289,6 +306,7 @@ function MarkLogicClient(connectionParams) { * Provides functions that submit values queries to project * tuples (rows) of values from documents. * @name values + * @since 1.0 * @memberof! DatabaseClient# * @type {values} */ @@ -300,6 +318,7 @@ function MarkLogicClient(connectionParams) { * Provides access to namespaces that configure the REST server for the client. * The client must have been created for a user with the rest-admin role. * @name config + * @since 1.0 * @memberof! DatabaseClient# * @property {config.extlibs} extlibs - provides functions that * maintain the extension libraries on the REST server @@ -348,6 +367,7 @@ MarkLogicClient.prototype.invoke = serverExec.serverInvoke; * accepting a uri identifier and metadata (such as multiple collections) * and optionally transforming each document on the server. * @method DatabaseClient#createCollection + * @since 1.0 * @param {string} collection - the name of the collection for the documents * @param {object|object[]} content - the objects with the content for the * documents @@ -390,6 +410,7 @@ MarkLogicClient.prototype.createCollection = function createCollection() { * The {@link documents#probe} function is less simple but more complete, * returning an object with additional information. * @method DatabaseClient#probe + * @since 1.0 * @param {string} uri - the uri for the database document * @returns {ResultProvider} an object whose result() function takes * a success callback that receives a boolean. @@ -407,6 +428,7 @@ MarkLogicClient.prototype.probe = function probeClient() { * as well as the content. * an object for each document with additional information. * @method DatabaseClient#queryCollection + * @since 1.0 * @param {string} collection - the name of the document collection * @param {object} [query] - a query built by a {@link queryBuilder} * @returns {ResultProvider} an object whose result() function takes @@ -431,6 +453,7 @@ MarkLogicClient.prototype.queryCollection = function queryClient(collection, bui * documents on the server and returning an envelope object for * each document with the uri and metadata as well as the content. * @method DatabaseClient#read + * @since 1.0 * @param {string|string[]} uris - the uri string or an array of uri strings * for the database documents * @returns {ResultProvider} an object whose result() function takes @@ -444,6 +467,7 @@ MarkLogicClient.prototype.read = function readClient() { * identifying the document. * The {@link documents#remove} function is less simple but more complete. * @method DatabaseClient#remove + * @since 1.0 * @param {string|string[]} uris - the uri string or an array of uri strings * identifying the database documents * @returns {ResultProvider} an object whose result() function takes @@ -463,6 +487,7 @@ MarkLogicClient.prototype.remove = function removeClient() { * The {@link documents#removeAll} function is less simple but more complete, * supporting deleting a directory or all documents in the database. * @method DatabaseClient#removeCollection + * @since 1.0 * @param {string} collection - the collection whose documents should be * deleted * @returns {ResultProvider} an object with a result() function takes @@ -483,6 +508,7 @@ MarkLogicClient.prototype.removeCollection = function removeCollectionClient(col * accepting a uri identifier and metadata (such as multiple collections) * and optionally transforming each document on the server. * @method DatabaseClient#writeCollection + * @since 1.0 * @param {string} collection - the name of the collection for the documents * @param {object} documents - an object in which every key is the uri string * for a document and every value is the content for the document @@ -530,6 +556,7 @@ MarkLogicClient.prototype.release = function releaseMarkLogicClient() { * a logging level from the debug|info|warn|error|silent enumeration (where silent * is the initial setting) for the default console logger. * @method DatabaseClient#setLogger + * @since 1.0 * @param {object} logger - an object providing debug(), info(), warn(), and error() * logging methods such as a logger provided by the * {@link https://github.com/trentm/node-bunyan|Bunyan} or @@ -660,18 +687,21 @@ module.exports = { /** * A factory for creating a document query builder. * @function marklogic.queryBuilder + * @since 1.0 * @returns {queryBuilder} a helper for defining a document query */ queryBuilder: queryBuilder.builder, /** * A factory for creating a document patch builder * @function marklogic.patchBuilder + * @since 1.0 * @returns {patchBuilder} a helper for defining a document patch */ patchBuilder: patchBuilder, /** * A factory for creating a values builder * @function marklogic.valuesBuilder + * @since 1.0 * @returns {valuesBuilder} a helper for defining a query * to project tuples (rows) of values from documents */ @@ -684,6 +714,7 @@ module.exports = { * is one-based. The default is array slice mode. Legacy slice mode * is deprecated and will be removed in the next major release. * @function marklogic.setSliceMode + * @since 1.0 * @param {string} mode - "array" or "legacy" */ setSliceMode: setSliceMode diff --git a/lib/patch-builder.js b/lib/patch-builder.js index 7dc4546c..e5492e60 100644 --- a/lib/patch-builder.js +++ b/lib/patch-builder.js @@ -29,11 +29,13 @@ var qb = require('./query-builder.js'); /** * An operation as part of a document patch request. * @typedef {object} patchBuilder.PatchOperation + * @since 1.0 */ /** * Builds an operation to remove a JSON property or XML element or attribute. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} select - the path to select the fragment to remove * @param {string} [cardinality] - a specification from the ?|.|*|+ @@ -77,6 +79,7 @@ function remove() { /** * Builds an operation to insert content. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} context - the path to the container of the inserted content * @param {string} position - a specification from the before|after|last-child @@ -145,6 +148,7 @@ function insert() { * The specification for a library of replacement functions as returned by * the {@link patchBuilder#library} function. * @typedef {object} patchBuilder.LibraryParam + * @since 1.0 */ /** * Specifies a library supplying functions to apply to existing content @@ -153,6 +157,7 @@ function insert() { * The library must be installed as /ext/marklogic/patch/apply/MODULE_NAME.xqy * and must have the http://marklogic.com/patch/apply/MODULE_NAME namespace. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} moduleName - the name of the module with the functions * @returns {patchBuilder.LibraryParam} the specification for applying a function @@ -180,12 +185,14 @@ function library(module) { * {@link patchBuilder#replace} or {@link patchBuilder#replaceInsert} * operation. * @typedef {object} patchBuilder.ApplyDefinition + * @since 1.0 */ /** * Specifies a function to apply to produce the replacement or insertion * content for a {@link patchBuilder#replace} or {@link patchBuilder#replaceInsert} * operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} functionName - the name of the function to apply * @param ...args - arguments to pass to the applied function; you can use the @@ -243,6 +250,7 @@ function apply() { * Adds a number to the existing value to produce the replace content * for a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {number} number - the number to add * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -257,6 +265,7 @@ function add(number) { * Subtracts a number from the existing value to produce the replace content * for a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {number} number - the number to subtract * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -271,6 +280,7 @@ function subtract(number) { * Multiplies the existing value by a number to produce the replace content * for a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {number} multiplier - the number to multiply by * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -285,6 +295,7 @@ function multiplyBy(multiplier) { * Divides the existing by a number to produce the replace content * for a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {number} divisor - the number to divide by * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -298,6 +309,7 @@ function divideBy(divisor) { /** * Prepends a value to the existing value for a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} prepended - the string to prepend * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -311,6 +323,7 @@ function concatBefore(prepended) { /** * Appends a value to the existing value for a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} appended - the string to append * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -325,6 +338,7 @@ function concatAfter(appended) { * Prepends and appends values to the existing value for * a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} prepended - the string to prepend * @param {string} appended - the string to append @@ -340,6 +354,7 @@ function concatBetween(prepended, appended) { * Trims a leading substring from the existing value for * a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} start - the leading string to trim * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -354,6 +369,7 @@ function substringAfter(start) { * Trims a trailing substring from the existing value for * a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} end - the trailing string to trim * @returns {patchBuilder.ApplyDefinition} the specification for applying a function @@ -368,6 +384,7 @@ function substringBefore(end) { * Applies a regular expression to the existing value to produce a new value for * a {@link patchBuilder#replace} operation. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} match - the expression extracting parts of the existing value * @param {string} end - the expression to assembling the extracted parts into @@ -387,6 +404,7 @@ function replaceRegex(match, replace, flags) { /** * Builds an operation to replace a JSON property or XML element or attribute. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} select - the path to select the fragment to replace * @param [content] - the object or value replacing the selected fragment or @@ -460,6 +478,7 @@ function replace() { * The content argument is optional if an apply argument is provided and * required otherwise. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} select - the path to select the fragment to replace * @param {string} context - the path to the container for inserting the content @@ -552,6 +571,7 @@ function replaceInsert() { * XPath or JSONPath as returned by * the {@link patchBuilder#pathLanguage} function. * @typedef {object} patchBuilder.PathLanguageParam + * @since 1.0 */ /** * Specifies whether the language used in context and select paths @@ -560,6 +580,7 @@ function replaceInsert() { * JSONPath may only be used for JSON documents. A document patch * cannot contain a mix of XPath and JSONPath. * @method + * @since 1.0 * @memberof patchBuilder# * @param {string} language - one of the enumeration xpath|jsonpath * @returns {patchBuilder.PathLanguageParam} the specification for the path language @@ -583,6 +604,7 @@ function pathLanguage() { /** * Specifies a collection to add to a document's metadata. * @method patchBuilderCollections#add + * @since 1.0 * @param {string} collection - the name of the collection * @returns {patchBuilder.PatchOperation} a patch operation */ @@ -595,6 +617,7 @@ function addCollection(collection) { /** * Specifies a collection to remove from a document's metadata. * @method patchBuilderCollections#remove + * @since 1.0 * @param {string} collection - the name of the collection * @returns {patchBuilder.PatchOperation} a patch operation */ @@ -615,6 +638,7 @@ function removeCollection(collection) { * object with the following named parameters or, as a shortcut, * a role string and capabilities string or array. * @method patchBuilderPermissions#add + * @since 1.0 * @param {string} role - the name of a role defined in the server configuration * @param {string|string[]} capabilities - the capability or an array of * capabilities from the insert|update|read|execute enumeration @@ -634,6 +658,7 @@ function addPermission() { * takes a configuration object with the following named parameters or, * as a shortcut, a role string and capabilities string or array. * @method patchBuilderPermissions#replace + * @since 1.0 * @param {string} role - the name of an existing role with permissions * on the document * @param {string|string[]} capabilities - the role's modified capability or @@ -654,6 +679,7 @@ function replacePermission() { /** * Specifies a role to remove from a document's permissions. * @method patchBuilderPermissions#remove + * @since 1.0 * @param {string} role - the role to remove from access to the document * @returns {patchBuilder.PatchOperation} a patch operation */ @@ -722,6 +748,7 @@ function getPermission(args) { /** * Specifies a new property to add to a document's metadata. * @method patchBuilderProperties#add + * @since 1.0 * @param {string} name - the name of the new metadata property * @param value - the value of the new metadata property * @returns {patchBuilder.PatchOperation} a patch operation @@ -737,6 +764,7 @@ function addProperty(name, value) { /** * Specifies a different value for a property in a document's metadata. * @method patchBuilderProperties#replace + * @since 1.0 * @param {string} name - the name of the existing metadata property * @param value - the modified value of the metadata property * @returns {patchBuilder.PatchOperation} a patch operation @@ -750,6 +778,7 @@ function replaceProperty(name, value) { /** * Specifies a metadata property to remove from the document's metadata. * @method patchBuilderProperties#remove + * @since 1.0 * @param {string} name - the name of the metadata property to remove * @returns {patchBuilder.PatchOperation} a patch operation */ @@ -768,6 +797,7 @@ function removeProperty(name) { /** * Sets the search quality of a document. * @method patchBuilderQuality#set + * @since 1.0 * @param {number} quality - the numeric value of the quality */ function setQuality(quality) { @@ -780,11 +810,13 @@ function setQuality(quality) { /** * Specifies operations to patch the metadata values of a document. * @namespace patchBuilderMetadataValues + * @since 2.0.1 */ /** * Specifies a new metadata value to add to a document. * @method patchBuilderMetadataValues#add + * @since 2.0.1 * @param {string} name - the name of the new metadata value * @param value - the value of the new metadata value * @returns {patchBuilder.PatchOperation} a patch operation @@ -800,6 +832,7 @@ function addMetadataValue(name, value) { /** * Specifies a metadata value to replace for a document. * @method patchBuilderMetadataValues#replace + * @since 2.0.1 * @param {string} name - the name of the existing metadata value * @param value - the modified value * @returns {patchBuilder.PatchOperation} a patch operation @@ -813,6 +846,7 @@ function replaceMetadataValue(name, value) { /** * Specifies a metadata value to remove from the document. * @method patchBuilderMetadataValues#remove + * @since 2.0.1 * @param {string} name - the name of the metadata value to remove * @returns {patchBuilder.PatchOperation} a patch operation */ @@ -828,6 +862,7 @@ module.exports = { * Provides functions that specify patch operations on the collections * to which a document belongs. * @name collections + * @since 1.0 * @memberof! patchBuilder# * @type {patchBuilderCollections} */ @@ -839,6 +874,7 @@ module.exports = { * Provides functions that specify patch operations on the permissions * of a document. * @name permissions + * @since 1.0 * @memberof! patchBuilder# * @type {patchBuilderPermissions} */ @@ -851,6 +887,7 @@ module.exports = { * Provides functions that specify patch operations on the metadata properties * of a document. * @name properties + * @since 1.0 * @memberof! patchBuilder# * @type {patchBuilderProperties} */ @@ -863,6 +900,7 @@ module.exports = { * Provides functions that specify patch operations on the ranking quality * of a document. * @name quality + * @since 1.0 * @memberof! patchBuilder# * @type {patchBuilderQuality} */ @@ -873,6 +911,7 @@ module.exports = { * Provides functions that specify patch operations on the metadata values * for a document. * @name metadataValues + * @since 2.0.1 * @memberof! patchBuilder# * @type {patchBuilderMetadataValues} */ diff --git a/lib/query-builder.js b/lib/query-builder.js index bdddc525..6eb94a46 100644 --- a/lib/query-builder.js +++ b/lib/query-builder.js @@ -79,34 +79,40 @@ function addIndex(query, index, isContainer) { /** * A composable query. * @typedef {object} queryBuilder.Query + * @since 1.0 */ /** * An indexed name such as a JSON property, {@link queryBuilder#element} or * {@link queryBuilder#attribute}, {@link queryBuilder#field}, * or {@link queryBuilder#pathIndex}. * @typedef {object} queryBuilder.IndexedName + * @since 1.0 */ /** * An indexed name such as a JSON property, XML element, or path that * represents a geospatial location for matched by a geospatial query. * @typedef {object} queryBuilder.GeoLocation + * @since 1.0 */ /** * The specification of a point or an area (such as a box, circle, or polygon) * for use as criteria in a geospatial query. * @typedef {object} queryBuilder.Region + * @since 1.0 */ /** * The specification of the latitude and longitude * returned by the {@link queryBuilder#latlon} function * for a coordinate of a {@link queryBuilder.Region}. * @typedef {object} queryBuilder.LatLon + * @since 1.0 */ /** * The specification of the coordinate system * returned by the {@link queryBuilder#coordSystem} function * for a geospatial path index * @typedef {object} queryBuilder.CoordSystem + * @since 1.0 */ /** @ignore */ @@ -165,6 +171,7 @@ function ConstraintDef() { /** * Builds a query for the intersection of the subqueries. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...queryBuilder.Query} subquery - a word, value, range, geospatial, * or other query or a composer such as an or query. @@ -254,6 +261,7 @@ function QueryListDef(queries, ordered, weight, distance) { /** * Builds a query with positive and negative subqueries. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} positiveQuery - a query that must match * the result documents @@ -311,6 +319,7 @@ function PositiveNegativeDef(positive, negative) { * array with uri and name strings or as an object returned by the * {@link queryBuilder#qname} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|string[]|queryBuilder.QName} element - the name of the element * @param {string|string[]|queryBuilder.QName} attribute - the name of the attribute @@ -385,6 +394,7 @@ function AttributeDef(elemQName, attrQName) { /** * Builds a query with matching and boosting subqueries. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} matchingQuery - a query that must match * the result documents @@ -442,6 +452,7 @@ function MatchingBoostingDef(matching, boosting) { * from the {@link queryBuilder#southWestNorthEast} function or as a list * of {queryBuilder.LatLon} coordinates in South, West, North, and East order. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.LatLon} south - the south coordinate of the box * @param {queryBuilder.LatLon} west - the west coordinate for the box @@ -489,6 +500,7 @@ function BoxRegionDef(box) { * the {@link queryBuilder#latlon} function or by passing the latitude and longitude * numbers in that order (possibly wrapped in an array). * @method + * @since 1.0 * @memberof queryBuilder# * @param {number} radius - the radius for the circle * @param {queryBuilder.LatLon} center - the center for the circle @@ -569,6 +581,7 @@ function CircleDef(radius, center) { * projected from each document have a column whose values are the * collections to which the document belongs. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|string[]|queryBuilder.BindingParam} collections - either * one or more collection uris to match or exactly one binding (returned @@ -681,6 +694,7 @@ util.inherits(CollectionQueryDef, QueryDef); * done manually or on an automated basis to include more recent * temporal documents in the result set. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} temporalCollection - the name of the temporal collection * that retains the temporal documents @@ -791,6 +805,7 @@ function LSQTQueryDef(temporalCollection, weight, timestamp, temporalOptions) { * the matches for a subquery (which may be a composer query such as those * returned by the {@link queryBuilder#and} and {@link queryBuilder#or}). * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|queryBuilder.IndexedName} propertyOrElement - the JSON * property or XML element that contains the query matches; a string is @@ -925,10 +940,12 @@ function ContainedDef(index, fragmentScope, query) { * The datatype specification returned by the {@link queryBuilder#datatype} * function. * @typedef {object} queryBuilder.DatatypeParam + * @since 1.0 */ /** * Identifies the datatype of an index. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} datatype - a value from the enumeration * int|unsignedInt|long|unsignedLong|float|double|decimal|dateTime|time|date|gYearMonth|gYear|gMonth|gDay|yearMonthDuration|dayTimeDuration|string|anyURI|point @@ -971,6 +988,7 @@ function DatatypeDef(datatype, collation) { /** * Builds a query matching documents in one or more database directories. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|string[]} uris - one or more directory uris * to match @@ -1015,6 +1033,7 @@ util.inherits(DirectoryQueryDef, QueryDef); /** * Builds a query matching documents. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|string[]} uris - one or more document uris * to match @@ -1063,6 +1082,7 @@ function UrisDef(uris, infinite) { * Builds a query that applies the subquery to document content by contrast * with the {@link queryBuilder#properties} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} query - the query that must match document content * @returns {queryBuilder.Query} a composable query @@ -1089,6 +1109,7 @@ util.inherits(DocumentFragmentDef, QueryDef); * array with uri and name strings or as an object returned by the * {@link queryBuilder#qname} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|string[]|queryBuilder.QName} name - the name of the element * @returns {queryBuilder.IndexedName} an indexed name for specifying a query @@ -1126,6 +1147,7 @@ function ElementDef(qname) { /** * Specifies a field for a query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} name - the name of the field * @param {string} [collation] - the collation of a field over strings @@ -1182,11 +1204,13 @@ function FieldNameDef(name, collation) { * document content or document metadata properties; returned * by the {@link queryBuilder#fragmentScope} function. * @typedef {object} queryBuilder.FragmentScopeParam + * @since 1.0 */ /** * Configures a query to match documents based on document content or * document metadata properties. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} scopeType - a value from the documents|properties * enumeration where 'documents' queries document content and @@ -1214,6 +1238,7 @@ function FragmentScopeDef(scope) { * Specifies the geospatial locations represented by an XML attribute pair * for passing to the {@link queryBuilder#geospatial} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|queryBuilder.QName} parent - the name of the element * containing the attributes as returned by the {@link queryBuilder#qname} function @@ -1260,6 +1285,7 @@ function geoAttributePair() { * containing a comma-separated pair of latitude-longitude values * for passing to the {@link queryBuilder#geospatial} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|queryBuilder.QName} [parent] - the optional name of the parent * of the geospatial element as returned by the {@link queryBuilder#qname} function @@ -1309,6 +1335,7 @@ function geoElement() { * Specifies the geospatial locations represented by an XML element pair * for passing to the {@link queryBuilder#geospatial} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|queryBuilder.QName} parent - the name of the containing * parent element as returned by the {@link queryBuilder#qname} function @@ -1350,6 +1377,7 @@ function geoElementPair() { * containing a pair of latitude-longitude values for passing to * the {@link queryBuilder#geospatial} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} [parent] - the optional name of the parent * of the geospatial property @@ -1394,6 +1422,7 @@ function geoProperty() { * Specifies the geospatial locations represented by a JSON property pair * for passing to the {@link queryBuilder#geospatial} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} parent - the name of the containing parent property * @param {string} latitude - the name of the latitude property @@ -1430,6 +1459,7 @@ function geoPropertyPair() { * JSON properties or XML elements containing a pair of latitude-longitude values * for passing to the {@link queryBuilder#geospatial} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|object} path - the XPath for the path index as a string or * as the return value of the {@link queryBuilder#pathIndex} function @@ -1498,6 +1528,7 @@ function geoPath() { * or a binding to parse the region criteria from a query string but not * both. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.GeoLocation} location - the JSON property or XML element * representing the geospatial locations @@ -1525,6 +1556,7 @@ function geospatial() { * or a binding to parse the region criteria from a query string but not * both. * @method + * @since 2.0.1 * @memberof queryBuilder# * @param {queryBuilder.GeoLocation} location - the JSON property or XML element * representing the geospatial locations @@ -1688,6 +1720,7 @@ util.inherits(GeospatialConstraintDef, ConstraintDef); /** * Specifies the buckets for a geospatial facet. * @typedef {object} queryBuilder.HeatMapParam + * @since 1.0 */ /** * Divides a geospatial box into a two-dimensional grid for calculating facets @@ -1696,6 +1729,7 @@ util.inherits(GeospatialConstraintDef, ConstraintDef); * from the {@link queryBuilder#southWestNorthEast} function or as a list * of {queryBuilder.LatLon} coordinates in South, West, North, and East order. * @method + * @since 1.0 * @memberof queryBuilder# * @param {number} latdivs - the number of latitude divisions in the grid * @param {number} londivs - the number of longitude divisions in the grid @@ -1781,11 +1815,13 @@ function heatmap() { * Options for a geospatial query returned by * the {@link queryBuilder#geoOptions} function. * @typedef {object} queryBuilder.GeoOptionsParam + * @since 1.0 */ /** * Provides options modifying the default behavior of a * {@link queryBuilder#geospatial} query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...string} options - options supported for geospatial queries * @returns {queryBuilder.GeoOptionsParam} options for the geospatial query @@ -1812,6 +1848,7 @@ function GeoOptionsDef(options) { * criteria for a geospatial query. The latitude and longitude can be * passed as individual numeric parameters or wrapped in an array * @method + * @since 1.0 * @memberof queryBuilder# * @param {number} latitude - the north-south location * @param {number} longitude - the east-west location @@ -1858,6 +1895,7 @@ function LatLongDef(latitude, longitude) { * Builds a query that applies the subquery to document lock fragments by contrast * with the {@link queryBuilder#documentFragment} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} query - the query that must match document lock fragments * @returns {queryBuilder.Query} a composable query @@ -1886,6 +1924,7 @@ util.inherits(LocksFragmentDef, QueryDef); * Specifies a minimum distance between matching subqueries to consider for the * {@link queryBuilder#minDistance} function. * @method + * @since 2.0.1 * @memberof queryBuilder# * @param {number} distance - the minimum number of words * between any two matching subqueries @@ -1913,6 +1952,7 @@ function MinDistanceDef(distance) { * is the default). While turning on filtering can be convenient during * development, setting up indexes is recommended for production. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...queryBuilder.Query} subquery - a word, value, range, geospatial, * or other query or a composer such as an or query. @@ -1992,6 +2032,7 @@ util.inherits(NearDef, QueryDef); /** * Builds a query that removes any documents matched by the subquery. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} subquery - a word, value, range, geospatial, * or other query or a composer such as an or query. @@ -2017,6 +2058,7 @@ util.inherits(NotDef, QueryDef); * Builds a query where the matching content qualifies for the positive query * and does not qualify for the negative query. Positions must be enabled for indexes. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} positiveQuery - a query that must match * the content @@ -2053,6 +2095,7 @@ util.inherits(NotInDef, QueryDef); /** * Builds a query for the union intersection of subqueries. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...queryBuilder.Query} subquery - a word, value, range, geospatial, * or other query or a composer such as an and query. @@ -2081,11 +2124,13 @@ util.inherits(OrDef, QueryDef); /** * The ordering returned by the {@link queryBuilder#ordered} function. * @typedef {object} queryBuilder.OrderParam + * @since 1.0 */ /** * Specifies ordering for an {@link queryBuilder#and} or * {@link queryBuilder#near} query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {boolean} isOrdered - whether subqueries are ordered * @returns {queryBuilder.OrderParam} a query flag for ordering @@ -2108,6 +2153,7 @@ function OrderedDef(on) { /** * Specifies a path configured as an index over JSON or XML documents on the server. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} pathExpression - the indexed path * @param {object} namespaces - bindings between the prefixes in the path and @@ -2160,6 +2206,7 @@ function PathDef(pathExpression, namespaces) { /** * Identifies the coordinate system used by a geospatial path index. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} coord - the name of the coordinate system * @returns {queryBuilder.CoordSystem} a coordinate system identifier @@ -2194,6 +2241,7 @@ function CoordSystemDef(coordSystem) { * the {@link queryBuilder#latlon} function or by passing the latitude and longitude * numbers in that order (possibly wrapped in an array). * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.LatLon} coordinate - the point location * @returns {queryBuilder.Region} the region criteria for a geospatial query @@ -2231,6 +2279,7 @@ function PointRegionDef(point) { * the {@link queryBuilder#latlon} function or by wrapping the latitude and * longitude numbers in an array. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...queryBuilder.LatLon} coordinate - the polygon coordinates * @returns {queryBuilder.Region} the region criteria for a geospatial query @@ -2274,6 +2323,7 @@ function PolygonRegionDef(points) { * Builds a query that applies the subquery to document metadata by contrast * with the {@link queryBuilder#documentFragment} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} query - the query that must match document metadata * properties @@ -2299,6 +2349,7 @@ util.inherits(PropertiesFragmentDef, QueryDef); * Specifies a JSON property for a query. As a shortcut, a JSON property * can also be specified with a string instead of calling this function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} name - the name of the property * @returns {queryBuilder.IndexedName} an indexed name for specifying a query @@ -2332,10 +2383,12 @@ function JSONPropertyDef(name) { * A namespaced name for an element or attribute returned * by the {@link queryBuilder#qname} function. * @typedef {object} queryBuilder.QName + * @since 1.0 */ /** * Specifies an XML qualified name. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|string[]} parts - the namespace URI and name * for the QName supplied either as two strings or as an array with @@ -2378,12 +2431,14 @@ function QNameDef(ns, name) { * The specification for a timespan or timestamp for an query * returned by the {@link queryBuilder#period} function. * @typedef {object} queryBuilder.PeriodParam + * @since 1.0 */ /** * Specifies a timespan or timestamp for comparison with * a valid or system timespan in temporal documents in * a {@link queryBuilder#periodRange} temporal query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|Date} startTimestamp - the starting datetime for a timespan * or the datetime for a timestamp @@ -2442,6 +2497,7 @@ function PeriodDef(startDate, endDate) { * was recorded (the system time) only afterward (the valid axis is before * the system axis). * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} axis1 - the configured name of the valid or system axis * @param {string} operator - the name of an Allen interval operator or @@ -2540,6 +2596,7 @@ function PeriodCompareQueryDef( * or was recorded (the system time) during a timespan or before or * after a time. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} axis - the configured name of the valid or system axis * @param {string} operator - the name of an Allen interval operator or @@ -2650,6 +2707,7 @@ function PeriodRangeQueryDef( * to retreive suggestions for completing criteria * for the constraints. * @typedef {object} queryBuilder.SuggestBindings + * @since 1.0 */ /** * Maps constraint names to indexes for passing to @@ -2657,6 +2715,7 @@ function PeriodRangeQueryDef( * to retreive suggestions for completing criteria * for the constraints. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query} ...query - queries that contain a binding * to a constraint name as returned by the {@link queryBuilder#bind} @@ -2671,11 +2730,13 @@ function suggestBindings() { * index as returned by * the {@link queryBuilder#suggestOptions} function. * @typedef {object} queryBuilder.SuggestOptionsParam + * @since 1.0 */ /** * Provides options modifying the default behavior of an * {@link documents#suggest} query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...string} options - one or more options supported by {@link documents#suggest} * for the type of index @@ -2703,6 +2764,7 @@ function SuggestOptionsDef(options) { * Options for a temporal query returned by * the {@link queryBuilder#temporalOptions} function. * @typedef {object} queryBuilder.TemporalOptionsParam + * @since 1.0 */ /** * Provides options modifying the default behavior of an @@ -2710,6 +2772,7 @@ function SuggestOptionsDef(options) { * {@link queryBuilder#periodCompare}, or * {@link queryBuilder#periodRange} query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...string} options - options supported for temporal queries * @returns {queryBuilder.TemporalOptionsParam} options for the temporal query @@ -2737,6 +2800,7 @@ function TemporalOptionsDef(options) { * to parse the comparison and value from a query string but not both. * You can provide both named and default bindings for the same query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|queryBuilder.IndexedName} indexedName - the JSON * property, XML element or attribute, field, or path providing the values @@ -2937,11 +3001,13 @@ function RangeDef( * Options for a range query returned by the {@link queryBuilder#rangeOptions} * function. * @typedef {object} queryBuilder.RangeOptionsParam + * @since 1.0 */ /** * Provides options modifying the default behavior * of a {@link queryBuilder#range} query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...string} options - options supported for range queries * @returns {queryBuilder.RangeOptionsParam} options for a {@link queryBuilder#range} query @@ -2968,6 +3034,7 @@ function RangeOptionsDef(options) { * for passing to the {@link queryBuilder#box} function * or to the {@link queryBuilder#heatmap} function * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.LatLon} south - the south coordinate * @param {queryBuilder.LatLon} west - the west coordinate @@ -3024,6 +3091,7 @@ function BoxDef(south, west, north, east) { /** * Builds a query for matching words in a JSON, text, or XML document. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} [...text] - one or more words to match * @param {queryBuilder.WeightParam} [weight] - a weight returned @@ -3074,12 +3142,14 @@ util.inherits(TermDef, QueryDef); /** * Options for a range query returned by the {@link queryBuilder#termOptions} * function. + * @since 1.0 * @typedef {object} queryBuilder.TermOptionsParam */ /** * Provides options modifying the default behavior * of a {@link queryBuilder#value} or {@link queryBuilder#word} query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...string} options - options supported for value or word queries * @returns {queryBuilder.TermOptionsParam} options for a value or word query @@ -3315,6 +3385,7 @@ function TextDef(index, jsontype, text, weight, termOptions, fragmentScope) { * value from a query string but not both. You can provide both named and * default bindings for the same query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|queryBuilder.IndexedName} indexedName - the JSON * property, XML element, field, or path containing the value @@ -3342,10 +3413,12 @@ function value() { * The specification returned by the {@link queryBuilder#jsontype} * function. * @typedef {object} queryBuilder.JSONTypeParam + * @since 1.0 */ /** * Identifies whether a JSON property has boolean, null, numeric, or string values in the database. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} jsontype - a value from the enumeration * boolean|null|number|string @@ -3375,11 +3448,13 @@ function JSONTypeDef(type) { /** * The weight modification returned by the {@link queryBuilder#weight} function. * @typedef {object} queryBuilder.WeightParam + * @since 1.0 */ /** * Increases or decreases the contribution of the query relative * to other queries in the result documents ranking. * @method + * @since 1.0 * @memberof queryBuilder# * @param {number} modifier - a number between -16 and 64 modifying * the contribution of the query to the score @@ -3407,6 +3482,7 @@ function WeightDef(number) { * from a query string but not both. You can provide both named and * default bindings for the same query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|queryBuilder.IndexedName} indexedName - the JSON * property, XML element, field, or path containing the word @@ -3435,12 +3511,14 @@ function word() { * An object representing the result of building a query using * the helper functions of a {@link queryBuilder}. * @namespace queryBuilder.BuiltQuery + * @since 1.0 */ /** * Initializes a new query builder by copying any where, calculate, * orderBy, slice, or withOptions clause defined in the built query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.BuiltQuery} query - an existing query with * clauses to copy @@ -3478,6 +3556,7 @@ function copyFromQueryBuilder(otherQueryBuilder) { * in a single request). * This function may be called on a query builder or on the result of building a query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query|queryBuilder.ParsedQuery|queryBuilder.QueryByExample} [query] - one * or more composable queries returned by query builder functions; or @@ -3556,6 +3635,7 @@ QueryBuilder.prototype.where = where; * A query definition returned by the {@link queryBuilder#byExample} function * to pass to a {@link queryBuilder#where} function. * @typedef {object} queryBuilder.QueryByExample + * @since 1.0 */ /** * Builds a query by example from one or more objects that annotate instances @@ -3565,6 +3645,7 @@ QueryBuilder.prototype.where = where; * documents, you can also pass a JavaScript object with a $query property * that has the query and a $format property of 'xml'. * @method + * @since 1.0 * @memberof queryBuilder# * @param {object} ...query - one or more objects with example properties * @returns {queryBuilder.QueryByExample} a query @@ -3591,6 +3672,7 @@ function byExample() { * of a {@link queryBuilder} to specify the sequence and direction * of sorting. This function may be called on the result of building a query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.IndexedName|queryBuilder.Score|queryBuilder.Sort} ...sortItem - a * JSON property, XML element or attribute, field, or path with a range index @@ -3652,11 +3734,13 @@ QueryBuilder.prototype.orderBy = orderBy; * A sort definition returned by the {@link queryBuilder#score} function * to pass to a {@link queryBuilder#orderBy} function. * @typedef {object} queryBuilder.Score + * @since 1.0 */ /** * Specifies the relevance ranking for ordering documents * in the query results, optionally specifying the score method. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} [method] - a scoring strategy from the enumeration * logtfidf|logtf|simple|random|zero, defaulting to logtfidf. @@ -3673,11 +3757,13 @@ function score() { * A sort definition returned by the {@link queryBuilder#sort} function * to pass to a {@link queryBuilder#orderBy} function. * @typedef {object} queryBuilder.Sort + * @since 1.0 */ /** * Specifies the direction for sorting documents for a range index or * relevance score. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.IndexedName|queryBuilder.Score} sortItem - a * JSON property, XML element or attribute, field, or path with a range index @@ -3741,6 +3827,7 @@ function sort() { * The transform must have been installed previously by * the {@link config.transforms#write} function * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} name - the name of the transform * @param {object} [params] - the parameters of the transform @@ -3763,6 +3850,7 @@ function transform(name, params) { /** * Builds a query that matches all documents. * @method + * @since 2.0.1 * @memberof queryBuilder# * @returns {queryBuilder.Query} a composable query */ @@ -3786,6 +3874,7 @@ util.inherits(TrueQueryDef, QueryDef); * to legacy slice mode with {@link module:marklogic.setSliceMode}. Legacy * slice mode is deprecated and will be removed in the next major release. * @method + * @since 1.0 * @memberof queryBuilder# * @param {number} start - in array slice mode, the zero-based position * within the result set of the first document; in legacy slice mode, the @@ -3819,6 +3908,7 @@ QueryBuilder.prototype.slice = slice; * XML elements or attributes, fields, or paths with a range index for * value frequency or other aggregate calculation. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Facet} ...facets - the facets to calculate * over the documents in the result set as returned by @@ -3846,6 +3936,7 @@ QueryBuilder.prototype.calculate = calculate; * A facet definition returned by the {@link queryBuilder#facet} function * to pass to a {@link queryBuilder#calculate} function. * @typedef {object} queryBuilder.Facet + * @since 1.0 */ /** * Calculates frequency of the values in a collection, range index, or geospatial index @@ -3856,6 +3947,7 @@ QueryBuilder.prototype.calculate = calculate; * (if supplied in the {@link queryBuilder#where} clause) and bind the values * to a query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} name - a name for the facet to identify the calculated * result and use as a constraint to tag values in a parsed query string @@ -4060,6 +4152,7 @@ function facet() { * as returned by {@link queryBuilder#calculateFunction} to pass * to the {@link queryBuilder#facet} function. * @typedef {object} queryBuilder.CalculateFunction + * @since 1.0 */ /** * Specifies a module that generates a custom facet as an argument to the @@ -4070,6 +4163,7 @@ function facet() { * can implement a parse() function for a custom parser specified with the * {@link queryBuilder#parseFunction} helper. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} moduleName - the name of the module with the functions * @returns {queryBuilder.CalculateFunction} the specification for a custom facet @@ -4106,11 +4200,13 @@ function calculateFunction() { * Options for a facet calculation returned by the {@link queryBuilder#facetOptions} * function. * @typedef {object} queryBuilder.FacetOptionsParam + * @since 1.0 */ /** * Provides options modifying the default behavior * of a {@link queryBuilder#facet} calculation. * @method + * @since 1.0 * @memberof queryBuilder# * @param {...string} options - options supported for facet calculations * @returns {queryBuilder.FacetOptionsParam} options for a {@link queryBuilder#facet} calculation @@ -4135,6 +4231,7 @@ function FacetOptionsDef(options) { /** * Builds a query that matches no documents. * @method + * @since 2.0.1 * @memberof queryBuilder# * @returns {queryBuilder.Query} a composable query */ @@ -4153,6 +4250,7 @@ util.inherits(FalseQueryDef, QueryDef); * The definition of a numeric or datetime range returned by the {@link queryBuilder#bucket} function * for aggregating value frequencies with a {@link queryBuilder#facet} function. * @typedef {object} queryBuilder.BucketParam + * @since 1.0 */ /** * Defines a numeric or datetime range of for aggregating value frequencies @@ -4160,6 +4258,7 @@ util.inherits(FalseQueryDef, QueryDef); * relative to the same anchor, you can as a convenience return both bounds and the relation * from a single call to an {@link queryBuilder#anchor} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} name - the name of the bucket * @param [lower] - the lower numeric or datetime boundary, which is less than or equal to the values @@ -4335,6 +4434,7 @@ function ComputedBucketDef(name, lower, upper) { * The specification for computing a datetime boundary or range as returned by * the {@link queryBuilder#anchor} function to pass to the {@link queryBuilder#bucket} function. * @typedef {object} queryBuilder.AnchorParam + * @since 1.0 */ /** * Defines a numeric or datetime range of for aggregating value frequencies @@ -4342,6 +4442,7 @@ function ComputedBucketDef(name, lower, upper) { * relative to the same anchor, you can as a convenience return both bounds and the comparison * from a single call to an {@link queryBuilder#anchor} function. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} milestone - the temporal milestone from the enumeration * now|start-of-day|start-of-month|start-of-year @@ -4453,11 +4554,13 @@ function defaultConstraintName(index) { * A query definition returned by the {@link queryBuilder#parsedFrom} function * to pass to a {@link queryBuilder#where} function. * @typedef {object} queryBuilder.ParsedQuery + * @since 1.0 */ /** * Builds a parsed query from a string and bindings of constraint tags * to queries. The query parsing occurs on the server. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} query - the string to parse * @param {queryBuilder.ParseBindings} bindings - the mappings of constraint names to queries @@ -4534,6 +4637,7 @@ function ParsedQueryDef(qtext, constraints, term) { * to pass to a {@link queryBuilder#parsedFrom} function * for tagging values within the query string. * @typedef {object} queryBuilder.ParseBindings + * @since 1.0 */ /** * Maps constraint names to queries and passed to @@ -4541,6 +4645,7 @@ function ParsedQueryDef(qtext, constraints, term) { * for tagging values within the query string. * The query parsing occurs on the server. * @method + * @since 1.0 * @memberof queryBuilder# * @param {queryBuilder.Query|queryBuilder.ParseFunction} ...query - queries that contain a binding * to a constraint name as returned by the {@link queryBuilder#bind} (instead of @@ -4651,6 +4756,7 @@ function TermBindingDef(defaultConstraints, empty, suggestOptions) { * that tags the values in the query string and occupies the position * of the values in a query. * @typedef {object} queryBuilder.BindingParam + * @since 1.0 */ /** * Specifies a constraint name that binds values provided by a parsed @@ -4658,6 +4764,7 @@ function TermBindingDef(defaultConstraints, empty, suggestOptions) { * name in the query string. The binding occupies the position of the * values in the query specification. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} parts - the constraint name * @returns {queryBuilder.BindingParam} the binding for the constraint name @@ -4685,12 +4792,14 @@ function BindDef(name) { * in the query string with a query, occupying the position of the * values in a query. A search can have only one default binding. * @typedef {object} queryBuilder.DefaultBindingParam + * @since 1.0 */ /** * Binds untagged values provided by a parsed query string to a query. The * binding occupies the position of the values in the query specification. * A search can have only one default binding. * @method + * @since 1.0 * @memberof queryBuilder# * @returns {queryBuilder.DefaultBindingParam} the binding for the constraint name */ @@ -4710,10 +4819,12 @@ function BindDefaultDef() { * to a query for no documents or all documents as returned * by the {@link queryBuilder#bindEmptyAs} function. * @typedef {object} queryBuilder.EmptyBindingParam + * @since 1.0 */ /** * Binds an empty query string to no documents or all documents. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} apply - a function from the all-results|no-results * enumeration to control whether empty criteria matches all or no results @@ -4758,6 +4869,7 @@ function EmptyApplyDef(binding) { * {@link queryBuilder#parseFunction} to pass * to the {@link queryBuilder#parseBindings} function. * @typedef {object} queryBuilder.ParseFunction + * @since 1.0 */ /** * Specifies a custom constraint module that parses a tagged value as an argument @@ -4768,6 +4880,7 @@ function EmptyApplyDef(binding) { * and finish-facet() functions for a custom facet specified with the * {@link queryBuilder#calculateFunction} helper. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} moduleName - the name of the module with the function * @param {queryBuilder.TermOptionsParam} [options] - options @@ -4865,6 +4978,7 @@ function CustomParserDef(moduleName) { * Specifies JSON properties or XML elements to project from the * documents returned by a query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {string|string[]} paths - restricted XPaths (valid for * the cts:valid-index-path() function) to match in documents @@ -4925,6 +5039,7 @@ function extract() { * The custom snippeting library must have been installed previously * by the {@link config.query.snippet#write} function * @method + * @since 1.0 * @memberof queryBuilder# * @param {string} name - either the name of a builtin snippeting * function from the empty|metadata|snippet enumeration (where @@ -4984,6 +5099,7 @@ function snippet() { * takes a configuration object with the following named parameters. * This function may be called on the result of building a query. * @method + * @since 1.0 * @memberof queryBuilder# * @param {documents.categories} [categories] - the categories of information * to retrieve for the result documents diff --git a/lib/resources-config.js b/lib/resources-config.js index 934d0e59..2984a456 100644 --- a/lib/resources-config.js +++ b/lib/resources-config.js @@ -61,6 +61,7 @@ function Resources(client) { /** * Reads the source for a resource service installed on the server. * @method config.resources#read + * @since 1.0 * @param {string} name - the name of an installed resource service * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the source code @@ -87,6 +88,7 @@ Resources.prototype.read = function readResourceConfig(name) { /** * Installs a resource service on the server. * @method config.resources#write + * @since 1.0 * @param {string} name - the name of the resource service * @param {string} format - a value from the javascript|xquery enumeration * @param {object|string} source - the source for the resource service @@ -180,6 +182,7 @@ Resources.prototype.write = function writeResourceConfig() { /** * Deletes a resource service from the server. * @method config.resources#remove + * @since 1.0 * @param {string} name - the name of the resource service */ Resources.prototype.remove = function removeResourceConfig(name) { @@ -204,6 +207,7 @@ Resources.prototype.remove = function removeResourceConfig(name) { /** * Lists the resource services installed on the server. * @method config.resources#list + * @since 1.0 * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the list of resource services installed * on the server diff --git a/lib/resources-exec.js b/lib/resources-exec.js index 6217fa32..9f8605e5 100644 --- a/lib/resources-exec.js +++ b/lib/resources-exec.js @@ -103,6 +103,7 @@ function Resources(client) { /** * Invokes the get() function in the resource service. * @method resources#get + * @since 1.0 * @param {string} name - the name of the service * @param {object} [params] - an object in which each property has * a variable name as a key and a number, string, or boolean value @@ -148,6 +149,7 @@ function readResourceExec(self, responseType, contentType, args) { /** * Invokes the post() function in the resource service. * @method resources#post + * @since 1.0 * @param {string} name - the name of the service * @param {object} [params] - an object in which each property has * a variable name as a key and a number, string, or boolean value @@ -165,6 +167,7 @@ Resources.prototype.post = function postResourceExec() { /** * Invokes the put() function in the resource service. * @method resources#put + * @since 1.0 * @param {string} name - the name of the service * @param {object} [params] - an object in which each property has * a variable name as a key and a number, string, or boolean value @@ -286,6 +289,7 @@ function addPart(partList, document) { /** * Invokes the delete() function in the resource service. * @method resources#remove + * @since 1.0 * @param {string} name - the name of the service * @param {object} [params] - an object in which each property has * a variable name as a key and a number, string, or boolean value diff --git a/lib/rest-server-properties.js b/lib/rest-server-properties.js index 1bb70d74..e5958e0c 100644 --- a/lib/rest-server-properties.js +++ b/lib/rest-server-properties.js @@ -21,7 +21,7 @@ var Operation = require('./operation.js'); /** * Provides functions to modify the properties of 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.serverprops */ @@ -36,6 +36,7 @@ function RESTServerProperties(client) { /** * Reads the configuration properties for the server. * @method config.serverprops#read + * @since 1.0 * @returns {object} the properties */ RESTServerProperties.prototype.read = function readRESTServerProperties() { @@ -45,7 +46,7 @@ RESTServerProperties.prototype.read = function readRESTServerProperties() { 'Accept': 'application/json' }; requestOptions.path = '/v1/config/properties'; - + var operation = new Operation( 'read REST server properties', this.client, requestOptions, 'empty', 'single' ); @@ -65,6 +66,7 @@ function RESTServerPropertiesOutputTransform(/*headers, data*/) { /** * Modifies the configuration properties for the server. * @method config.serverprops#write + * @since 1.0 * @param {object} properties - the modified properties */ RESTServerProperties.prototype.write = function writeRESTServerProperties(properties) { @@ -85,7 +87,7 @@ RESTServerProperties.prototype.write = function writeRESTServerProperties(proper operation.outputTransform = RESTServerPropertiesOutputTransform; operation.requestBody = properties; - return requester.startRequest(operation); + return requester.startRequest(operation); }; module.exports = RESTServerProperties; diff --git a/lib/server-exec.js b/lib/server-exec.js index 735084fa..0e3f4e60 100644 --- a/lib/server-exec.js +++ b/lib/server-exec.js @@ -167,9 +167,10 @@ function execOutputTransform(headers, data) { * Evaluates JavaScript on the server; the user for the database client must have * permission to evaluate code on the server and, in addition, permission * to execute the actions performed by the source; takes a configuration object - * with the following named parameters or, as a shortcut, the source + * with the following named parameters or, as a shortcut, the source * with or without variables. * @method serverExec#eval + * @since 1.0 * @param {string} source - the JavaScript source code * @param {object} [variables] - an object in which each property has * a variable name as a key and a number, string, or boolean value @@ -187,9 +188,10 @@ function serverJavaScriptEval() { * Evaluates XQuery on the server; the user for the database client must have * permission to evaluate code on the server and, in addition, permission * to execute the actions performed by the source; takes a configuration object - * with the following named parameters or, as a shortcut, the source + * with the following named parameters or, as a shortcut, the source * with or without variables. * @method serverExec#xqueryEval + * @since 1.0 * @param {string} source - the XQuery source code * @param {object} [variables] - an object in which each property has * a variable name as a key and a number, string, or boolean value; the key @@ -211,6 +213,7 @@ function serverXQueryEval() { * with the following named parameters or, as a shortcut, the path * with or without variables. * @method serverExec#invoke + * @since 1.0 * @param {string} path - the path of the module in the modules database * for the REST server; the module must have been installed previously * (typically with the {@link config.extlibs#write} function) using @@ -267,7 +270,7 @@ function serverExec(execName, args) { var body = {}; if (isInvoke) { - body.module = source; + body.module = source; } else { body[execType] = source; } diff --git a/lib/transactions.js b/lib/transactions.js index 96f88e8f..fc6b0734 100644 --- a/lib/transactions.js +++ b/lib/transactions.js @@ -47,6 +47,7 @@ function Transactions(client) { /** * An object representing a multi-statement transaction on the server. * @typedef {object} transactions.Transaction + * @since 1.0 */ /** @@ -55,6 +56,7 @@ function Transactions(client) { * before calling the {@link transactions#commit} or {@link transactions#rollback} * function to finish the transaction. * @method transactions#open + * @since 1.0 * @param {string} [transactionName] - a label to assign to the transaction * for easier recognition in reports * @param {number} [timeLimit] - the maximum number of seconds that @@ -127,6 +129,7 @@ Transactions.prototype.open = function openTransaction() { * Reads the current state of a multi-statement transaction * created with the {@link transactions#open} function. * @method transactions#read + * @since 1.0 * @param {string|transactions.Transaction} txid - a string * transaction id or Transaction object identifying an open * multi-statement transaction @@ -156,6 +159,7 @@ Transactions.prototype.read = function readTransaction(txid) { /** * Finishes a multi-statement transaction by applying the changes. * @method transactions#commit + * @since 1.0 * @param {string|transactions.Transaction} txid - a string * transaction id or Transaction object identifying an open * multi-statement transaction @@ -167,6 +171,7 @@ Transactions.prototype.commit = function commitTransaction(txid) { /** * Finishes a multi-statement transaction by reverting the changes. * @method transactions#rollback + * @since 1.0 * @param {string|transactions.Transaction} txid - a string * transaction id or Transaction object identifying an open * multi-statement transaction diff --git a/lib/transforms.js b/lib/transforms.js index 4afd18f2..10ef3bb4 100644 --- a/lib/transforms.js +++ b/lib/transforms.js @@ -61,6 +61,7 @@ function Transforms(client) { /** * Reads the source for a transform installed on the server. * @method config.transforms#read + * @since 1.0 * @param {string} name - the name of an installed transform * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the source code @@ -87,6 +88,7 @@ Transforms.prototype.read = function readTransform(name) { /** * Installs a transform on the server. * @method config.transforms#write + * @since 1.0 * @param {string} name - the name of the transform * @param {string} format - a value from the javascript|xquery|xslt enumeration * @param {object|string} source - the source for the transform @@ -183,6 +185,7 @@ Transforms.prototype.write = function writeTransform() { /** * Deletes a transform from the server. * @method config.transforms#remove + * @since 1.0 * @param {string} name - the name of the transform */ Transforms.prototype.remove = function removeTransform(name) { @@ -207,6 +210,7 @@ Transforms.prototype.remove = function removeTransform(name) { /** * Lists the transforms installed on the server. * @method config.transforms#list + * @since 1.0 * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the list of transforms installed * on the server diff --git a/lib/values-builder.js b/lib/values-builder.js index fb207b21..513a0427 100644 --- a/lib/values-builder.js +++ b/lib/values-builder.js @@ -25,6 +25,7 @@ var qb = require('./query-builder.js').builder; * XML element or attribute, field, or path range or * geospatial index or from the collection or uri index. * @typedef {object} valuesBuilder.DatatypedValuesIndex + * @since 1.0 */ /** @@ -116,6 +117,7 @@ function ValueBuilder() { * in the documents selected by the where clause. * This function must be called on the values builder. * @method valuesBuilder#fromIndexes + * @since 1.0 * @param {string|valuesBuilder.DatatypedValuesIndex} indexes - a list * of parameters or array specifying the JSON properties, XML elements or attributes, * fields, or paths providing the range or geospatial indexes or the return value @@ -179,6 +181,7 @@ ValueBuilder.prototype.fromIndexes = valuesFromIndexes; * by the {@link valuesBuilder#valuesFromIndexes} function * or another function specifying a values query clause. * @method valuesBuilder.BuiltQuery#where + * @since 1.0 * @param {queryBuilder.Query} query - one or more composable queries * returned by the values query builder functions. * @returns {valuesBuilder.BuiltQuery} a built query @@ -245,6 +248,7 @@ ValueBuilder.prototype.where = function valuesWhere() { * by the {@link valuesBuilder#valuesFromIndexes} function * or another function specifying a values query clause. * @method valuesBuilder.BuiltQuery#aggregates + * @since 1.0 * @param {string[]} functions - one or more built-in functions such * avg, correlation, count, covariance, covariance-population, max, median, min, * stddev, stddev-population, sum, variance, or variance-population or the @@ -285,6 +289,7 @@ ValueBuilder.prototype.aggregates = function valuesAggregates() { * installed in the database server distribution on all hosts * where the database has forests. * @method valuesBuilder#udf + * @since 1.0 * @param {string} pluginName - the name of the plugin library * that implements the UDF * @param {string} functionName - the name of the function @@ -308,6 +313,7 @@ function udf() { * by the {@link valuesBuilder#valuesFromIndexes} function * or another function specifying a values query clause. * @method valuesBuilder.BuiltQuery#slice + * @since 1.0 * @param {number} start - the one-based position within the * result set of the first tuple. * @param {number} length - the number of tuples in the slice. @@ -334,6 +340,7 @@ ValueBuilder.prototype.slice = function valuesSlice() { * by the {@link valuesBuilder#valuesFromIndexes} function * or another function specifying a values query clause. * @method valuesBuilder.BuiltQuery#withOptions + * @since 1.0 * @param {...string} [forestNames] - the names of forests providing documents * for the result set * @param {...string} [values] - options modifying the default behaviour of the query @@ -373,6 +380,7 @@ ValueBuilder.prototype.withOptions = function valuesWithOptions() { * Each tuple (aka row) projected from a document includes the * uri of the document as one of the columns. * @method valuesBuilder#uri + * @since 1.0 * @returns {valuesBuilder.DatatypedValuesIndex} an identifier for the uri index */ function valuesUri() { @@ -384,6 +392,7 @@ function valuesUri() { * and any where, aggregates, slice, or withOptions clause defined in * the built query. * @method valuesBuilder#copyFrom + * @since 1.0 * @param {valuesBuilder.BuiltQuery} query - an existing values query * with clauses to copy * @returns {valuesBuilder.BuiltQuery} a built query diff --git a/lib/values.js b/lib/values.js index 76146368..b8edeae0 100644 --- a/lib/values.js +++ b/lib/values.js @@ -25,7 +25,7 @@ var Operation = require('./operation.js'); * Values can also come from the collection or uri index. Each co-occurrence * of the specified indexes in a document produces a tuple. For instance, * if one JSON property occurs twice in a document but another occurs only - * once, the result will include two tuples: that is, one co-occurrence + * once, the result will include two tuples: that is, one co-occurrence * for each value of the first property with the value of the second property. * @namespace values */ @@ -41,6 +41,7 @@ function Values(client) { * Executes a values query built by a {@link valuesBuilder} to read tuples * from the specified indexes for the documents qualified by the query. * @method values#read + * @since 1.0 * @param {object} valuesQuery - a query built by a {@link valuesBuilder} * @returns {ResultProvider} an object whose result() function takes * a success callback that receives the tuples. From 84a8bed01a8b7507cf3e01464acd09cdf3dede72 Mon Sep 17 00:00:00 2001 From: Mike Wooldridge Date: Wed, 15 Mar 2017 15:29:00 -0700 Subject: [PATCH 3/3] Be more specific about MarkLogic version support --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4e8a1d84..fd247cf8 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,9 @@ from Node.js applications. ## Status -Release 2.0.1 of the MarkLogic Node.js Client API, compatible with MarkLogic -versions 8 and 9. To use the new features available in 2.0.1, you will need to -run MarkLogic version 9. +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