Updated gitignore and added some documentation and better naming

- Using _ to indicate variable/function is private and shouldn't be accessed - Added JSDocs syntax to generate documentation -
2019-07-25 00:08:29 +08:00 · 2019-07-25 00:08:29 +08:00 · 96d82938a0
parent b8193dac90
commit 96d82938a0
5 changed files with 76 additions and 86 deletions
--- a/.gitignore
+++ b/.gitignore
@ -11,3 +11,5 @@ debs/
 rpms/
 *.pyc
 *.tmp
+src/connector/nodejs/node_modules/
+src/connector/nodejs/out/
--- a/src/connector/nodejs/nodetaos/cinterface.js
+++ b/src/connector/nodejs/nodetaos/cinterface.js
@ -1,8 +1,13 @@
+/**
+ * C Interface with TDengine Module
+ * @module CTaosInterface
+ */
+
 const ref = require('ref');
 const ffi = require('ffi');
 const ArrayType = require('ref-array');
 const Struct = require('ref-struct');
-const fieldTypes = require('./constants');
+const FieldTypes = require('./constants');
 const errors = require ('./error')

 module.exports = CTaosInterface;
@ -145,18 +150,18 @@ function convertNchar(data, num_of_rows, nbytes = 0, offset = 0, micro=false) {
  return res;
 }

-//Object with all the relevant converters from pblock data to javascript data
+// Object with all the relevant converters from pblock data to javascript readable data
 let convertFunctions = {
-    [fieldTypes.C_BOOL] : convertBool,
-    [fieldTypes.C_TINYINT] : convertTinyint,
-    [fieldTypes.C_SMALLINT] : convertSmallint,
-    [fieldTypes.C_INT] : convertInt,
-    [fieldTypes.C_BIGINT] : convertBigint,
-    [fieldTypes.C_FLOAT] : convertFloat,
-    [fieldTypes.C_DOUBLE] : convertDouble,
-    [fieldTypes.C_BINARY] : convertBinary,
-    [fieldTypes.C_TIMESTAMP] : convertTimestamp,
-    [fieldTypes.C_NCHAR] : convertNchar
+    [FieldTypes.C_BOOL] : convertBool,
+    [FieldTypes.C_TINYINT] : convertTinyint,
+    [FieldTypes.C_SMALLINT] : convertSmallint,
+    [FieldTypes.C_INT] : convertInt,
+    [FieldTypes.C_BIGINT] : convertBigint,
+    [FieldTypes.C_FLOAT] : convertFloat,
+    [FieldTypes.C_DOUBLE] : convertDouble,
+    [FieldTypes.C_BINARY] : convertBinary,
+    [FieldTypes.C_TIMESTAMP] : convertTimestamp,
+    [FieldTypes.C_NCHAR] : convertNchar
 }

 // Define TaosField structure
@ -168,7 +173,12 @@ TaosField.fields.name.type.size = 64;
 TaosField.defineProperty('bytes', ref.types.short);
 TaosField.defineProperty('type', ref.types.char);

-//The C interface with the Taos TSDB
+/**
+ * Constructor for the C interface with TDengine
+ * @constructor
+ * @param {Object} config - Configuration options for the interface
+ * @return {CTaosInterface}
+ */
 function CTaosInterface (config = null, pass = false) {
  ref.types.char_ptr = ref.refType(ref.types.char);
  ref.types.void_ptr = ref.refType(ref.types.void);
@ -208,7 +218,7 @@ function CTaosInterface (config = null, pass = false) {
    }
    else {
      try {
-        this._config = ref.allocCString(config);;
+        this._config = ref.allocCString(config);
      }
      catch(err){
        throw "Attribute Error: config is expected as a str";
@ -219,6 +229,7 @@ function CTaosInterface (config = null, pass = false) {
    }
    this.libtaos.taos_init();
  }
+  return this;
 }
 CTaosInterface.prototype.config = function config() {
    return this._config;
@ -298,7 +309,7 @@ CTaosInterface.prototype.fetchBlock = function fetchBlock(result, fields) {
  if (num_of_rows == 0) {
    return {block:null, num_of_rows:0};
  }
-  let isMicro = (this.libtaos.taos_result_precision(result) == fieldTypes.C_TIMESTAMP_MICRO)
+  let isMicro = (this.libtaos.taos_result_precision(result) == FieldTypes.C_TIMESTAMP_MICRO)
  let blocks = new Array(fields.length);
  blocks.fill(null);
  num_of_rows = Math.abs(num_of_rows);
--- a/src/connector/nodejs/nodetaos/connection.js
+++ b/src/connector/nodejs/nodetaos/connection.js
@ -2,11 +2,14 @@ const TDengineCursor = require('./cursor')
 const CTaosInterface = require('./cinterface')
 module.exports = TDengineConnection;

-/*
- * TDengine Connection object
- * @param {Object.<string, string>} options - Options for configuring the connection with TDengine
+/**
+ * TDengine Connection Class
+ * @param {object} options - Options for configuring the connection with TDengine
 * @return {TDengineConnection}
- *
+ * @class TDengineConnection
+ * @constructor
+ * @example
+ * var conn = new TDengineConnection({host:"127.0.0.1", user:"root", password:"taosdata", config:"/etc/taos",port:0})
 *
 */
 function TDengineConnection(options) {
@ -18,11 +21,15 @@ function TDengineConnection(options) {
  this._port = 0;
  this._config = null;
  this._chandle = null;
-  this.config(options)
+  this._configConn(options)
  return this;
 }
-
-TDengineConnection.prototype.config = function config(options) {
+/**
+ * Configure the connection to TDengine
+ * @private
+ * @memberof TDengineConnection
+ */
+TDengineConnection.prototype._configConn = function _configConn(options) {
  if (options['host']) {
    this._host = options['host'];
  }
@ -44,10 +51,14 @@ TDengineConnection.prototype.config = function config(options) {
  this._chandle = new CTaosInterface(this._config);
  this._conn = this._chandle.connect(this._host, this._user, this._password, this._database, this._port);
 }
-
+/** Close the connection to TDengine */
 TDengineConnection.prototype.close = function close() {
-  return this._chandle.close(this._conn);
+  this._chandle.close(this._conn);
 }
+/**
+ * Initialize a new cursor to interact with TDengine with
+ * @return {TDengineCursor}
+ */
 TDengineConnection.prototype.cursor = function cursor() {
  //Pass the connection object to the cursor
  return new TDengineCursor(this);
@ -58,7 +69,11 @@ TDengineConnection.prototype.commit = function commit() {
 TDengineConnection.prototype.rollback = function rollback() {
  return this;
 }
-TDengineConnection.prototype.clear_result_set = function clear_result_set() {
+/**
+ * Clear the results from connector
+ * @private
+ */
+TDengineConnection.prototype._clearResultSet = function _clearResultSet() {
  var result = this._chandle.useResult(this._conn).result;
  if (result) {
    this._chandle.freeResult(result)
--- a/src/connector/nodejs/nodetaos/constants.js
+++ b/src/connector/nodejs/nodetaos/constants.js
@ -1,10 +1,25 @@
-/*
- * TDengine Field Types
+/**
+ * TDengine Field Types and their type codes
+ * @typedef {Object} FieldTypes
+ * @property {number} C_NULL - Null
+ * @property {number} C_BOOL - Boolean. Note, 0x02 is the C_BOOL_NULL value.
+ * @property {number} C_TINYINT - Tiny Int, values in the range [-2^7+1, 2^7-1]. Note, -2^7 has been used as the C_TINYINT_NULL value
+ * @property {number} C_SMALLINT - Small Int, values in the range [-2^15+1, 2^15-1]. Note, -2^15 has been used as the C_SMALLINT_NULL value
+ * @property {number} C_INT - Int, values in the range [-2^31+1, 2^31-1]. Note, -2^31 has been used as the C_INT_NULL value
+ * @property {number} C_BIGINT - Big Int, values in the range [-2^59, 2^59].
+ * @property {number} C_FLOAT - Float, values in the range [-3.4E38, 3.4E38], accurate up to 6-7 decimal places.
+ * @property {number} C_DOUBLE - Double, values in the range [-1.7E308, 1.7E308], accurate up to 15-16 decimal places.
+ * @property {number} C_BINARY - Binary, encoded in utf-8.
+ * @property {number} C_TIMESTAMP - Timestamp in format "YYYY:MM:DD HH:MM:SS.MMM". Measured in number of milliseconds passed after
+                                    1970-01-01 08:00:00.000 GMT.
+ * @property {number} C_NCHAR - NChar field type encoded in ASCII, a wide string.
 *
 *
+ *
+ * @property {number} C_TIMESTAMP_MILLI - The code for millisecond timestamps, as returned by libtaos.taos_result_precision(result).
+ * @property {number} C_TIMESTAMP_MICRO - The code for microsecond timestamps, as returned by libtaos.taos_result_precision(result).
 */
 module.exports = {
-    // Type Code
    C_NULL : 0,
    C_BOOL : 1,
    C_TINYINT : 2,
@ -23,7 +38,10 @@ module.exports = {
    C_SMALLINT_NULL : -32768,
    C_INT_NULL : -2147483648,
    C_BIGINT_NULL : -9223372036854775808,
-
+    C_FLOAT_NULL : 2146435072,
+    C_DOUBLE_NULL : -9223370937343148032,
+    C_NCHAR_NULL : 4294967295,
+    C_BINARY_NULL : 255,
    C_TIMESTAMP_MILLI : 0,
    C_TIMESTAMP_MICRO : 1,
 }
--- a/src/connector/nodejs/package-lock.json
+++ b/src/connector/nodejs/package-lock.json
@ -1,5 +1,5 @@
 {
-  "name": "tdconnector",
+  "name": "td-connector",
  "version": "1.0.5",
  "lockfileVersion": 1,
  "requires": true,
@ -144,22 +144,6 @@
      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.2.tgz",
      "integrity": "sha1-tf1UIgqivFq1eqtxQMlAdUUDwac="
    },
-    "ctypes": {
-      "version": "0.0.1",
-      "resolved": "https://registry.npmjs.org/ctypes/-/ctypes-0.0.1.tgz",
-      "integrity": "sha1-/C7F5ZmRwG9mNksh7yxy/SkQnLE=",
-      "requires": {
-        "array-index": "^1.0.0",
-        "debug": "^2.2.0",
-        "es6-weak-map": "^2.0.1",
-        "ffi": "^2.0.0",
-        "function-class": "^1.1.0",
-        "ref": "^1.3.1",
-        "ref-array": "^1.1.2",
-        "ref-struct": "^1.0.2",
-        "setprototypeof": "^1.0.0"
-      }
-    },
    "d": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/d/-/d-1.0.1.tgz",
@ -238,17 +222,6 @@
        "es5-ext": "~0.10.14"
      }
    },
-    "es6-weak-map": {
-      "version": "2.0.3",
-      "resolved": "https://registry.npmjs.org/es6-weak-map/-/es6-weak-map-2.0.3.tgz",
-      "integrity": "sha512-p5um32HOTO1kP+w7PRnB+5lQ43Z6muuMuIMffvDN8ZB4GcnjLBV6zGStpbASIMk4DCAvEaamhe2zhyCb/QXXsA==",
-      "requires": {
-        "d": "1",
-        "es5-ext": "^0.10.46",
-        "es6-iterator": "^2.0.3",
-        "es6-symbol": "^3.1.1"
-      }
-    },
    "extend": {
      "version": "3.0.2",
      "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
@ -321,25 +294,6 @@
      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
      "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8="
    },
-    "function-class": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/function-class/-/function-class-1.1.0.tgz",
-      "integrity": "sha1-yCK8J5x4py11je/y4kzXwPtYWLo=",
-      "requires": {
-        "es6-symbol": "^3.0.2",
-        "function-name": "^1.0.0",
-        "setprototypeof": "^1.0.0"
-      }
-    },
-    "function-name": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/function-name/-/function-name-1.0.0.tgz",
-      "integrity": "sha1-r+4YP9eh3JIi1fZae/htpYNd90U=",
-      "requires": {
-        "bindings": "^1.2.1",
-        "nan": "2"
-      }
-    },
    "gauge": {
      "version": "2.7.4",
      "resolved": "https://registry.npmjs.org/gauge/-/gauge-2.7.4.tgz",
@ -737,11 +691,6 @@
      "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
      "integrity": "sha1-BF+XgtARrppoA93TgrJDkrPYkPc="
    },
-    "setprototypeof": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.1.1.tgz",
-      "integrity": "sha512-JvdAWfbXeIGaZ9cILp38HntZSFSo3mWg6xGcJJsd+d4aRMOqauag1C63dJfDw7OaMYwEbHMOxEZ1lqVRYP2OAw=="
-    },
    "signal-exit": {
      "version": "3.0.2",
      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.2.tgz",
@ -845,11 +794,6 @@
        "punycode": "^2.1.0"
      }
    },
-    "utf8": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/utf8/-/utf8-3.0.0.tgz",
-      "integrity": "sha512-E8VjFIQ/TyQgp+TZfS6l8yp/xWppSAHzidGiRrqe4bK4XP9pTRyKFgGJpO3SN7zdX4DeomTrwaseCHovfpFcqQ=="
-    },
    "util-deprecate": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",