MarkLogic 10 Product Documentation

Node.js Application Developer's Guide — Chapter 10

Node.js Annotations for Declarations

The service and function declarations can take the following annotations to affect the generated module:

The $jsType annotation supports the mappings listed below for return values.

The $jsType annotation is not supported for other server data types or for parameters.

Parameters accept and implicitly convert JavaScript input values to server data types as follows:

The declarations can also contain $java* annotations, which are ignored in the Node.js environment. Similarly, the $js* annotations are ignored in the Java environment.

Using Gulp to Generate Models

Gulp provides a tool for build task execution in Node.js environments that's comparable Gradle in Java environments.

The Node.js API makes it easy to write Gulp pipelines that generate proxy modules. The proxy-generator.js module provides a generate() factory function, which return a Node.js Transform that takes the Gulp Vinyl descriptor for a proxy service directory as input and produces the Gulp Vinyl wrapper for a generated proxy module as output.

Following the Gradle project convention (where ml-modules/root/ds contains proxy service directories), the example below of a gulpfile.js pipes proxy service directories to the proxy module generator and then pipes the generated proxy modules to the lib directory for the project:

'use strict';
const gulp  = require('gulp');
const proxy = require('marklogic/lib/proxy-generator.js');
function proxygen() {
  return gulp.src('ml-modules/root/ds/*')
      .pipe(proxy.generate())
      .pipe(gulp.dest('lib/'));
}
exports.proxygen = proxygen;

The following Gulp command command is used to process this gulfile.js:

gulp proxygen

The Node.js client modules can use require() to import the generated proxy modules in the usual way and then construct proxy objects and call the methods of the proxy objects to invoke the server endpoints.

Generated Modules

Similar to the Interface generated for Java, the JavaScript module generated for Node.js defines and exports a JavaScript class with the following characteristics:

• A constructor that takes a database client with the host, port, and authentication for the server as well as an optional service declaration (where this optional service declaration specifies a directory in the modules database with custom endpoints that implement the interface for the service).
• A static on() method that takes the database client and optional service declaration parameters of the constructor and provides a convenience for instantiating the class.
• A method for each function declared in the proxy service directory.
• If any of those functions takes a session parameter, a createSession() method for constructing a ServiceState argument.
• JSDoc documentation comments for the class and each method for generating reference documentation where the content of the JSDoc comments uses the desc properties from the service declaration and *.api function declarations.

Expected Pattern of Use

A JavaScript MJS module can be invoked through the /v1/invoke endpoint. This is the preferred method.

The following listings show a generic example of how a developer might write code to use a Data Service method available on a service you have defined:

// Import the marklocig utilities
const marklogic = require('marklogic');
// import the generated class
const GENERATED_CLASS = require("./lib/GENERATED_CLASS.js");
// create a client for the host and port as the user
const client =
marklogic.createDatabaseClient({host:THE_HOST, port:THE_PORT, user:THE_USER, password:THE_PASSWORD});
// construct an instance of the class
const theInstance = GENERATED_CLASS.on(client);
// call a method of the instance to execute an endpoint on the server
const theOutput = theInstance.theMethod(...parameters...);

The method returns either a JavaScript Promise or a stream for the output depending on the $jsOutputMode annotation (as described earlier).

By providing the class instead of providing only a factory for instances, we make it possible to use the class in instanceof tests.