Skip to content

fix(#303): Update README with compatibility info #397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 15, 2017
Merged

fix(#303): Update README with compatibility info #397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
01e6883
fix(#303): Update README with compatibility info
wooldridge Mar 14, 2017
8d6a7db
Add "since" jsdoc tags to specify compatibility of methods, type def's
wooldridge Mar 15, 2017
84a8bed
Be more specific about MarkLogic version support
wooldridge Mar 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ from Node.js applications.

## Status

Release 2.0.1 of the MarkLogic Node.js Client API
Release 2.0.1 of the MarkLogic Node.js Client API, tested to work with MarkLogic
versions 8.0-6.3 and 9.0-1. To use the new features available in release 2.0.1,
you will need to run MarkLogic version 9.

## New Features in Release 2.0.1

Expand Down
23 changes: 23 additions & 0 deletions lib/documents.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
*/
Expand All @@ -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
Expand Down Expand Up @@ -251,13 +257,15 @@ function probeDocumentsImpl(contentOnly, args) {
* A success callback for {@link ResultProvider} that receives the result from
* the {@link documents#protect}.
* @callback documents#protectResult
* @since 2.0.1
* @param {documents.DocumentDescriptor} document - a sparse document descriptor
* for the protected document
*/
/**
* Protects a temporal document from temporal operations for a
* period of time.
* @method documents#protect
* @since 2.0.1
* @param {string} uri - the uri for the temporal document to protect
* @param {string} temporalCollection - the temporal collection for the document
* @param {string} [duration] - a protection duration; either a duration or an
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
*/
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
*/
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
20 changes: 12 additions & 8 deletions lib/extlibs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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;
Expand All @@ -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);
Expand All @@ -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];
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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
Expand All @@ -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+'/');
}
Expand Down
10 changes: 10 additions & 0 deletions lib/graphs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading