Add more JSDOC

Author: madnificent

helpers/mu/index.js

@@ -1,44 +1,34 @@
 import { app, errorHandler, beforeExit, exitHandler, setExitHandler } from './server.js';
 import sparql from './sparql.js';
+import { SPARQL, query, update, sparqlEscape, sparqlEscapeString, sparqlEscapeUri, sparqlEscapeDecimal, sparqlEscapeInt, sparqlEscapeFloat, sparqlEscapeDate, sparqlEscapeDateTime, sparqlEscapeBool } from './sparql.js';
 import { v1 as uuidV1 } from 'uuid';
 
 // generates a uuid
 const uuid = uuidV1;
 
 const mu = {
-  app: app,
-  sparql: sparql,
-  SPARQL: sparql.sparql,
-  query: sparql.query,
-  update: sparql.update,
-  sparqlEscape: sparql.sparqlEscape,
-  sparqlEscapeString: sparql.sparqlEscapeString,
-  sparqlEscapeUri: sparql.sparqlEscapeUri,
-  sparqlEscapeDecimal: sparql.sparqlEscapeDecimal,
-  sparqlEscapeInt: sparql.sparqlEscapeInt,
-  sparqlEscapeFloat: sparql.sparqlEscapeFloat,
-  sparqlEscapeDate: sparql.sparqlEscapeDate,
-  sparqlEscapeDateTime: sparql.sparqlEscapeDateTime,
-  sparqlEscapeBool: sparql.sparqlEscapeBool,
+  app,
+  sparql,
+
   uuid,
   errorHandler,
   beforeExit,
   exitHandler,
-  setExitHandler
-};
+  setExitHandler,
 
-const SPARQL = mu.SPARQL,
-      query = mu.query,
-      update = mu.update,
-      sparqlEscape = mu.sparqlEscape,
-      sparqlEscapeString = mu.sparqlEscapeString,
-      sparqlEscapeUri = mu.sparqlEscapeUri,
-      sparqlEscapeInt = mu.sparqlEscapeInt,
-      sparqlEscapeDecimal = mu.sparqlEscapeDecimal,
-      sparqlEscapeFloat = mu.sparqlEscapeFloat,
-      sparqlEscapeDate = mu.sparqlEscapeDate,
-      sparqlEscapeDateTime = mu.sparqlEscapeDateTime,
-      sparqlEscapeBool = mu.sparqlEscapeBool;
+  SPARQL,
+  query,
+  update,
+  sparqlEscape,
+  sparqlEscapeString,
+  sparqlEscapeUri,
+  sparqlEscapeDecimal,
+  sparqlEscapeInt,
+  sparqlEscapeFloat,
+  sparqlEscapeDate,
+  sparqlEscapeDateTime,
+  sparqlEscapeBool
+};
 
 export {
   app,

helpers/mu/server.js

@@ -2,6 +2,10 @@ import httpContext from 'express-http-context';
 import express from 'express';
 import bodyParser from 'body-parser';
 
+/**
+ * The express JS server
+ * @type {express.Express}
+ */
 var app = express();
 
 var bodySizeLimit = process.env.MAX_BODY_SIZE || '100kb';

helpers/mu/sparql.js

@@ -51,7 +51,21 @@ function newSparqlClient(userOptions) {
   });
 }
 
-// executes a query (you can use the template syntax)
+/**
+ * @typedef {Object} QueryOptions
+ * @property {boolean?} sudo Execute the query as sudo
+ * @property {string?} scope URI of the scope with whith the query is executed.  Use the environment variable `DEFAULT_MU_AUTH_SCOPE` if possible.
+ */
+
+/**
+ * Execute a sparql QUERY.  Intended for use with QUERY and ASK.
+ *
+ * See environment variables for logging: `LOG_SPARQL_ALL`, `LOG_SPARQL_QUERIES`, `DEBUG_AUTH_HEADERS`
+ *
+ * @param { string } queryString SPARQL query as a string.
+ * @param { QueryOptions? } options Operational changes to the SPARQL query.
+ * @return { Promise<object?> } The response is returned as a parsed JSON object, or null if the response could not be parsed as JSON.
+ */
 function query( queryString, options ) {
   if (LOG_SPARQL_QUERIES) {
     console.log(queryString);
@@ -60,10 +74,14 @@ function query( queryString, options ) {
 };
 
 /**
- * Executes an update query
+ * Execute a sparql QUERY.
+ * Intended for use with `DELETE {} INSERT {} WHERE {}`, `INSERT DATA` and `DELETE DATA`.
+ *
+ * See environment variables for logging: `LOG_SPARQL_ALL`, `LOG_SPARQL_UPDATES`, `DEBUG_AUTH_HEADERS`
  *
- * @param { string } queryString String containing SPARQL query for the backend.
- * @param { object? } options Options to be sent to 
+ * @param { string } queryString SPARQL query as a string.
+ * @param { QueryOptions? } options Operational changes to the SPARQL query.
+ * @return { Promise<object?> } The response is returned as a parsed JSON object, or null if the response could not be parsed as JSON.
  */
 function update( queryString, options ) {
   if (LOG_SPARQL_UPDATES) {
@@ -119,35 +137,74 @@ function executeQuery( queryString, options ) {
   });
 }
 
+/**
+ * Escapes a string for use in SPARQL.
+ *
+ * Wraps the string in quotes and escapes necessary characters.
+ *
+ * @param {string} value String to be escaped.
+ * @return {string} Escaped string for use in SPARQL.
+ */
 function sparqlEscapeString( value ){
   return '"""' + value.replace(/[\\"]/g, function(match) { return '\\' + match; }) + '"""';
 };
 
+/**
+ * Escapes a URI for use in SPARQL.
+ *
+ * Wraps the URI in < and > and escapes necessary characters.
+ *
+ * @param {string} value URI string to be escaped.
+ * @return {string} Escaped URI string for use in SPARQL.
+ */
 function sparqlEscapeUri( value ){
   return '<' + value.replace(/[\\"<>]/g, function(match) { return '\\' + match; }) + '>';
 };
 
+/**
+ * Escapes a float for use in SPARQL as xsd:decimal.
+ *
+ * @param {string|number} value Number string or value to be escaped.
+ * @return {string} Escaped number for use in SPARQL.
+ */
 function sparqlEscapeDecimal( value ){
   return '"' + Number.parseFloat(value) + '"^^xsd:decimal';
 };
 
+/**
+ * Escapes an integer for use in SPARQL as xsd:integer.
+ *
+ * @param {string|number} value Number string or value to be escaped.
+ * @return {string} Escaped number for use in SPARQL.
+ */
 function sparqlEscapeInt( value ){
   return '"' + Number.parseInt(value) + '"^^xsd:integer';
 };
 
+/**
+ * Escapes a number for use in SPARQL as xsd:float.
+ *
+ * @param {string|number} value Number string or value to be escaped.
+ * @return {string} Escaped number for use in SPARQL.
+ */
 function sparqlEscapeFloat( value ){
   return '"' + Number.parseFloat(value) + '"^^xsd:float';
 };
 
+/**
+ * Escapes a date string or date object into an xsd:date for use in SPARQL.
+ *
+ * @param {string|Date|number} value Number string or value to be escaped.
+ * @return {string} Escaped number for use in SPARQL.
+ */
 function sparqlEscapeDate( value ){
   return '"' + new Date(value).toISOString().substring(0, 10) + '"^^xsd:date'; // only keep 'YYYY-MM-DD' portion of the string
 };
 
 /**
- * Escape date string or date object into an xsd:dateTime for use in a SPARQL string.
+ * Escapes a date string or date object into an xsd:dateTime for use in a SPARQL.
  *
- * @param { Date | string | number } value Date representation
- * (understood by `new Date`) to convert.
+ * @param { Date | string | number } value Date representation (understood by `new Date`) to convert.
  * @return { string } Date representation for SPARQL query.
  */
 function sparqlEscapeDateTime( value ){
@@ -164,6 +221,14 @@ function sparqlEscapeBool( value ){
   return value ? '"true"^^xsd:boolean' : '"false"^^xsd:boolean';
 };
 
+/**
+ * Escapes a value based on the supplide type rather than the separately published functions.  Prefer to use the
+ * functions.
+ *
+ * @param { "string"|"uri"|"bool"|"decimal"|"int"|"float"|"date"|"dateTime"} type The value to be escaped.
+ * @param {*} value The value to be escaped.
+ * @return { string } Boolean representation for SPARQL query.
+ */
 function sparqlEscape( value, type ){
   switch(type) {
   case 'string':