jsdoc for bitemporal, some geospatial

Author: ehennum

lib/documents.js

@@ -390,6 +390,13 @@ function createWriteStream(document) {
  * the {@link transforms#write} function.
  * @param {string}  [forestName] - the name of a forest in which to write
  * the documents.
+ * @param {string} [temporalCollection] - the name of the temporal collection;
+ * use only when writing temporal documents that have the JSON properties or XML elements
+ * specifying the valid and system start and end times as defined by the valid and
+ * system axis for the temporal collection
+ * @param {string|Date} [systemTime] - a datetime to use as the system start time
+ * instead of the current time of the database server; can only be supplied
+ * if the temporalCollection parameter is also supplied
  * @returns {ResultProvider} an object whose result() function takes
  * a {@link documents#writeResult} success callback.
  */
@@ -448,11 +455,12 @@ function writeDocumentsImpl(contentOnly, args) {
     if (!valcheck.isNullOrUndefined(temporalCollection)) {
       endpoint += sep+'temporal-collection='+temporalCollection;
       if (sep !== '&') { sep = '&'; }
-    }
-    var systemTime = requestParams.systemTime;
-    if (!valcheck.isNullOrUndefined(systemTime)) {
-      endpoint += sep+'system-time='+systemTime;
-      if (sep !== '&') { sep = '&'; }
+      var systemTime = requestParams.systemTime;
+      if (valcheck.isString(systemTime)) {
+        path += '&system-time='+systemTime;
+      } else if (valcheck.isDate(systemTime)) {
+        path += '&system-time='+systemTime.toISOString();
+      }
     }
   }
 
@@ -653,6 +661,12 @@ function removeOutputTransform(headers, data) {
  * @method documents#remove
  * @param {string}  uri - the uri for the database document
  * @param {string}  [txid] - the transaction id for an open transaction
+ * @param {string} [temporalCollection] - the name of the temporal collection;
+ * use only when deleting a document created as a temporal document; sets the
+ * system end time to record when the document was no longer active
+ * @param {string|Date} [systemTime] - a datetime to use as the system end time
+ * instead of the current time of the database server; can only be supplied
+ * if the temporalCollection parameter is also supplied
  * @returns {ResultProvider} an object whose result() function takes
  * a {@link documents#removeResult} success callback.
  */
@@ -692,9 +706,11 @@ function removeDocumentImpl(contentOnly, args) {
   }
   if (!valcheck.isNullOrUndefined(temporalCollection)) {
     path += '&temporal-collection='+temporalCollection;
-  }
-  if (!valcheck.isNullOrUndefined(systemTime)) {
-    path += '&system-time='+systemTime;
+    if (valcheck.isString(systemTime)) {
+      path += '&system-time='+systemTime;
+    } else if (valcheck.isDate(systemTime)) {
+      path += '&system-time='+systemTime.toISOString();
+    }
   }
 
   var connectionParams = this.client.connectionParams;

lib/query-builder.js

@@ -83,6 +83,18 @@ function addIndex(query, index, isContainer) {
  * or path index.
  * @typedef {object} queryBuilder.IndexedName
  */
+/**
+ * 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
+ */
+/**
+ * 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
+ */
+
 
 /**
  * Builds a query for the intersection of the subqueries.
@@ -217,6 +229,19 @@ function boost() {
     }};
   }
 }
+/**
+ * Specifies a rectangular region with the coordinates of the corners.
+ * The coordinates can either be specified either by passing the return value
+ * from the {@link queryBuilder#southWestNorthEast} function or as a list
+ * of points in South, West, North, and East order.
+ * @method
+ * @memberof queryBuilder#
+ * @param {queryBuilder.LatLon} south - the south coordinate of the box
+ * @param {queryBuilder.LatLon} west - the west coordinate for the box
+ * @param {queryBuilder.LatLon} north - the north coordinate for the box
+ * @param {queryBuilder.LatLon} east - the east coordinate for the box
+ * @returns {queryBuilder.Region} the region criteria for a geospatial query
+ */
 function box() {
   var args = mlutil.asArray.apply(null, arguments);
   var region = null;
@@ -245,6 +270,17 @@ function box() {
   }
   return {box: region};
 }
+/**
+ * Specifies a circular region based on a radius and the coordinate of the center.
+ * The coordinate can either be specified by passing the return value from
+ * the {@link queryBuilder#latlon} function or by passing the latitude and longitude
+ * numbers in that order (possibly wrapped in an array).
+ * @method
+ * @memberof queryBuilder#
+ * @param {number} radius - the radius for the circle
+ * @param {queryBuilder.LatLon} center - the center for the circle
+ * @returns {queryBuilder.Region} the region criteria for a geospatial query
+ */
 function circle() {
   var args = mlutil.asArray.apply(null, arguments);
   var query = {};
@@ -333,6 +369,25 @@ function collection() {
     uri: args
   }};
 }
+/**
+ * Builds a query matching temporal documents with a system start time
+ * prior to the LSQT (Latest System Query Time). Advancing the LSQT can be 
+ * done manually or on an automated basis to include more recent
+ * temporal documents in the result set.
+ * @method
+ * @memberof queryBuilder#
+ * @param {string} temporalCollection - the name of the temporal collection
+ * that retains the temporal documents
+ * @param {queryBuilder.WeightParam} [weight] - a weight returned
+ * by {@link queryBuilder#weight} to increase or decrease the score
+ * of subqueries relative to other queries in the complete search
+ * @param {string|Date} [timestamp] - a datetime older than the LSQT
+ * to use as the upper boundary for an older view of the database  
+ * @param {queryBuilder.TemporalOptionsParam} [temporalOptions] - a list
+ * of options returned by {@link queryBuilder#temporalOptions} to modify
+ * the temporal query
+ * @returns {queryBuilder.Query} a composable query
+ */
 function lsqtQuery() {
   var args = mlutil.asArray.apply(null, arguments);
   var argLen = args.length;
@@ -589,7 +644,21 @@ function fragmentScope() {
   }
   throw new Error('unknown argument: '+scope);
 }
-// TODO: jsdoc for geospatial
+
+/**
+ * Builds a query for a geospatial location represented by an XML attribute pair
+ * that matches the {queryBuilder.Region} criteria.
+ * The coordinates can either be specified either by passing the return value
+ * from the {@link queryBuilder#southWestNorthEast} function or as a list
+ * of points in South, West, North, and East order.
+ * @method
+ * @memberof queryBuilder#
+ * @param {string|string[]|queryBuilder.BindingParam} collections - either
+ * one or more collection uris to match or exactly one binding (returned
+ * by the {@link queryBuilder#bind} function) for parsing the collection
+ * uris from a query string; required except for values queries
+ * @returns {queryBuilder.Query} a composable query
+ */
 function geoAttributePair() {
   var args = mlutil.asArray.apply(null, arguments);
   if (args.length < 3) {
@@ -877,6 +946,16 @@ function heatmap() {
 function geoOptions() {
   return {'geo-option': mlutil.asArray.apply(null, arguments)};
 }
+/**
+ * Specifies the latitude and longitude for a coordinate of the region
+ * criteria for a geospatial query. The latitude and longitude can be
+ * passed as individual numeric parameters or wrapped in an array
+ * @method
+ * @memberof queryBuilder#
+ * @param {number} latitude - the north-south location
+ * @param {number} longitude - the east-west location
+ * @returns {queryBuilder.LatLon} a coordinate for a {queryBuilder.Region}
+ */
 function latlon() {
   var args = mlutil.asArray.apply(null, arguments);
   if (args.length !== 2)
@@ -1030,6 +1109,15 @@ function pathIndex() {
   }
   return {'path-index': query};
 }
+/**
+ * Specifies a point region either by passing the return value from
+ * the {@link queryBuilder#latlon} function or by passing the latitude and longitude
+ * numbers in that order (possibly wrapped in an array).
+ * @method
+ * @memberof queryBuilder#
+ * @param {queryBuilder.LatLon} coordinate - the point location
+ * @returns {queryBuilder.Region} the region criteria for a geospatial query
+ */
 function point() {
   var args = mlutil.asArray.apply(null, arguments);
   var region = null;
@@ -1052,6 +1140,16 @@ function point() {
   }
   return {point: [region]};
 }
+/**
+ * Specifies a polygon region as a list of coordinate parameters or as a coordinate array
+ * where each coordinate is specified either by the return value from
+ * the {@link queryBuilder#latlon} function or by wrapping the latitude and
+ * longitude numbers in an array.
+ * @method
+ * @memberof queryBuilder#
+ * @param {...queryBuilder.LatLon} coordinate - the polygon coordinates
+ * @returns {queryBuilder.Region} the region criteria for a geospatial query
+ */
 function polygon() {
   var args = mlutil.asArray.apply(null, arguments);
   var points = [];
@@ -1124,6 +1222,24 @@ function nsName() {
     throw new Error('too many arguments: '+args.length);
   }
 }
+/**
+ * The specification for a timespan or timestamp for an query
+ * returned by the {@link queryBuilder#period} function.
+ * @typedef {object} queryBuilder.PeriodParam
+ */
+/**
+ * Specifies a timespan or timestamp for comparison with
+ * a valid or system timespan in temporal documents in
+ * a {@link queryBuilder#periodRange} temporal query.
+ * @method
+ * @memberof queryBuilder#
+ * @param {string|Date} startTimestamp - the starting datetime for a timespan
+ * or the datetime for a timestamp  
+ * @param {string|Date} [endTimestamp] - the starting datetime for a timespan
+ * or the datetime for a timestamp  
+ * @returns {queryBuilder.PeriodParam} the specification of a period
+ * for a {@link queryBuilder#periodRange} temporal query
+ */
 function period() {
   var startDate = null;
   var endDate   = null;
@@ -1162,6 +1278,24 @@ function period() {
 
   return periodVal;
 }
+/**
+ * Builds a query matching temporal documents based on the relationship
+ * between the valid period and the system period.  For instance, this
+ * query can find cases where what was believed to be true (the valid time)
+ * was recorded (the system time) only afterward (the valid axis is before
+ * the system axis).
+ * @method
+ * @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
+ * ISO SQL 2011 period operator
+ * @param {string} axis2 - the configured name of the valid or system axis, which
+ * must be different from axis1
+ * @param {queryBuilder.TemporalOptionsParam} [temporalOptions] - a list
+ * of options returned by {@link queryBuilder#temporalOptions} to modify
+ * the temporal query
+ * @returns {queryBuilder.Query} a composable query
+ */
 function periodCompare() {
   var argLen = arguments.length;
 
@@ -1194,6 +1328,25 @@ function periodCompare() {
 
   return {'period-compare-query': query};
 }
+/**
+ * Builds a query matching temporal documents based on the relationship
+ * between the valid or system period and the specified period.
+ * This query can find what was believed to be true (the valid time)
+ * or was recorded (the system time) during a timespan or before or
+ * after a time.
+ * @method
+ * @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
+ * ISO SQL 2011 period operator
+ * @param {queryBuilder.PeriodParam} [period] - a timespan or timestamp
+ * returned by {@link queryBuilder#period} to compare with the valid or
+ * system time of temporal documents
+ * @param {queryBuilder.TemporalOptionsParam} [temporalOptions] - a list
+ * of options returned by {@link queryBuilder#temporalOptions} to modify
+ * the temporal query
+ * @returns {queryBuilder.Query} a composable query
+ */
 function periodRange() {
   var argLen = arguments.length;
 
@@ -1233,6 +1386,20 @@ function periodRange() {
 
   return {'period-range-query': query};
 }
+/**
+ * Options for an query returned by the {@link queryBuilder#temporalOptions}
+ * function.
+ * @typedef {object} queryBuilder.TemporalOptionsParam
+ */
+/**
+ * Provides options modifying the default behavior
+ * of an {@link queryBuilder#lsqtQuery}, {@link queryBuilder#periodCompare},
+ * or {@link queryBuilder#periodRange} query.
+ * @method
+ * @memberof queryBuilder#
+ * @param {...string} options - options supported for temporal queries
+ * @returns {queryBuilder.TemporalOptionsParam} options for the temporal query
+ */
 function temporalOptions() {
   return {'temporal-option': mlutil.asArray.apply(null, arguments)};
 }
@@ -1376,6 +1543,17 @@ function range() {
 function rangeOptions() {
   return {'range-option': mlutil.asArray.apply(null, arguments)};
 }
+/**
+ * A convenience for specifying the coordinates of a box as a list of parameters.
+ * @method
+ * @memberof queryBuilder#
+ * @param {queryBuilder.LatLon} south - the south coordinate
+ * @param {queryBuilder.LatLon} west - the west coordinate
+ * @param {queryBuilder.LatLon} north - the north coordinate
+ * @param {queryBuilder.LatLon} east - the east coordinate
+ * @returns {object} the coordinates for passing to
+ * the {@link queryBuilder#box} function to specify a region
+ */
 function southWestNorthEast() {
   var args = mlutil.asArray.apply(null, arguments);
   if (args.length !== 4) {
@@ -1881,7 +2059,7 @@ function transform(name, params) {
   return {'document-transform': transformList};
 }
 
-// TODO: jsDoc for snippet
+// TODO: jsDoc for snippet, extract, transform
 /**
  * Sets the slice clause of a built query to select a slice of documents
  * from the result set based on the start document within the result set 

lib/values-builder.js

@@ -71,10 +71,14 @@ var qb     = require('./query-builder.js');
  * @borrows queryBuilder#heatmap            as valuesBuilder#heatmap
  * @borrows queryBuilder#latlon             as valuesBuilder#latlon
  * @borrows queryBuilder#locksFragment      as valuesBuilder#locksFragment
+ * @borrows queryBuilder#lsqtQuery          as valuesBuilder#lsqtQuery
  * @borrows queryBuilder#near               as valuesBuilder#near
  * @borrows queryBuilder#not                as valuesBuilder#not
  * @borrows queryBuilder#notIn              as valuesBuilder#notIn
  * @borrows queryBuilder#pathIndex          as valuesBuilder#pathIndex
+ * @borrows queryBuilder#period             as valuesBuilder#period
+ * @borrows queryBuilder#periodCompare      as valuesBuilder#periodCompare
+ * @borrows queryBuilder#periodRange        as valuesBuilder#periodRange
  * @borrows queryBuilder#point              as valuesBuilder#point
  * @borrows queryBuilder#polygon            as valuesBuilder#polygon
  * @borrows queryBuilder#properties         as valuesBuilder#properties
@@ -86,6 +90,7 @@ var qb     = require('./query-builder.js');
  * @borrows queryBuilder#rangeOptions       as valuesBuilder#rangeOptions
  * @borrows queryBuilder#scope              as valuesBuilder#scope
  * @borrows queryBuilder#southWestNorthEast as valuesBuilder#southWestNorthEast
+ * @borrows queryBuilder#temporalOptions    as valuesBuilder#temporalOptions
  * @borrows queryBuilder#term               as valuesBuilder#term
  * @borrows queryBuilder#termOptions        as valuesBuilder#termOptions
  * @borrows queryBuilder#transform          as valuesBuilder#transform
@@ -390,10 +395,14 @@ module.exports = {
     heatmap:            qb.heatmap,
     latlon:             qb.latlon,
     locksFragment:      qb.locksFragment,
+    lsqtQuery:          qb.lsqtQuery,
     near:               qb.near,
     not:                qb.not,
     notIn:              qb.notIn,
     pathIndex:          qb.pathIndex,
+    period:             qb.period,
+    periodCompare:      qb.periodCompare,
+    periodRange:        qb.periodRange,
     point:              qb.point,
     polygon:            qb.polygon,
     properties:         qb.properties,
@@ -405,6 +414,7 @@ module.exports = {
     rangeOptions:       qb.rangeOptions,
     scope:              qb.scope,
     southWestNorthEast: qb.southWestNorthEast,
+    temporalOptions:    qb.temporalOptions,
     term:               qb.term,
     termOptions:        qb.termOptions,
     transform:          qb.transform,