tons of changes for the helpers.

lib/errors/index.js

@@ -13,21 +13,29 @@ var $npm = {
  * @description
  * Error types namespace, available as `pgp.errors`, before and after initializing the library.
  *
- * @property {errors.QueryResultError} QueryResultError
- * Represents all result-specific errors from query methods.
- *
- * @property {errors.queryResultErrorCode} queryResultErrorCode
- * Error codes `enum` used by class {@link QueryResultError}.
+ * @property {Function} PreparedStatementError
+ * {@link errors.PreparedStatementError PreparedStatementError} class constructor.
  *
- * @property {errors.PreparedStatementError} PreparedStatementError
  * Represents all errors that can be reported by class {@link PreparedStatement}.
  *
- * @property {errors.ParameterizedQueryError} ParameterizedQueryError
+ * @property {Function} ParameterizedQueryError
+ * {@link errors.ParameterizedQueryError ParameterizedQueryError} class constructor.
+ *
  * Represents all errors that can be reported by class {@link ParameterizedQuery}.
  *
- * @property {errors.QueryFileError} QueryFileError
+ * @property {Function} QueryFileError
+ * {@link errors.QueryFileError QueryFileError} class constructor.
+ *
  * Represents all errors that can be reported by class {@link QueryFile}.
  *
+ * @property {Function} QueryResultError
+ * {@link errors.QueryResultError QueryResultError} class constructor.
+ *
+ * Represents all result-specific errors from query methods.
+ *
+ * @property {errors.queryResultErrorCode} queryResultErrorCode
+ * Error codes `enum` used by class {@link errors.QueryResultError QueryResultError}.
+ *
  */
 
 // To add when ready:

lib/helpers/column.js

@@ -15,14 +15,19 @@ var $npm = {
  *
  * Represents formatting details for a single column.
  *
- * @param {String|helpers~ColumnDescriptor} col
- * Column details, depending on the parameter's type:
- * - `string` - column name, with an optional format modifier
- * - `object` - {@link helpers~ColumnDescriptor ColumnDescriptor} object.
+ * @param {String|helpers~ColumnConfig} col
+ * Column details, depending on the type:
  *
- * When it is a string, the name adheres to the variable name format as used by method {@link formatting.format as.format}:
- * property name + optional modifier (`^`, `~`, `#`, `:csv`, `:json`, `name`, `raw`, `:value`). When a valid modifier is
- * specified, it is removed from the name and put into property `mod`.
+ * - When it is a string, it is expected to contain a name for both the column and the source property,
+ *   assuming that the two are the same. The name must adhere to JavaScript syntax for variable names.
+ *   The name can be appended with any format modifier as supported by {@link formatting.format as.format}
+ *   (`^`, `~`, `#`, `:csv`, `:json`, `name`, `raw`, `:value`), which is then removed from the name and put
+ *   into property `mod`.
+ *
+ * - When it is a simple {@link helpers~ColumnConfig ColumnConfig}-like object, it is used as an
+ *   input configurator to set all the properties of the class.
+ *
+ * - When it is none of the above, it will throw {@link external:TypeError TypeError} = `A column must be a string or a configurator object.`
  *
  * @property {string} name
  * Column name + property name (if `prop` isn't specified).
@@ -43,8 +48,8 @@ var $npm = {
  * Value override callback.
  *
  * @returns {helpers.Column}
- * 
- * @see {@link helpers~ColumnDescriptor ColumnDescriptor}
+ *
+ * @see {@link helpers~ColumnConfig ColumnConfig}
  */
 function Column(col) {
 
@@ -81,7 +86,7 @@ function Column(col) {
                 this.init = col.init; // optional value override (overrides 'def' also)
             }
         } else {
-            throw new TypeError("A column must be a string or a non-null object.");
+            throw new TypeError("A column must be a string or a configurator object.");
         }
     }
 
@@ -150,38 +155,35 @@ Column.prototype.inspect = function () {
 };
 
 /**
- * @typedef helpers~ColumnDescriptor
- * @type Object
+ * @typedef helpers~ColumnConfig
  * @description
- * It is a simple object/structure that can be used when constructing type {@link helpers.Column Column}.
+ * A simple structure with column details, to be passed into the {@link helpers.Column Column} constructor for initialization.    
  *
  * @property {string} name
- * Column name + property name (if `prop` is skipped). The name must adhere to the syntax
- * supported by JavaScript variables.
+ * Destination column name + source property name (if `prop` is skipped). The name must adhere to JavaScript syntax for variables,
+ * unless `prop` is specified, in which case `name` represents only the column name, and therefore can be any string.
  *
  * @property {string} [prop]
- * Source property name, if different from the column's name.
+ * Source property name, if different from the column's name. It must adhere to JavaScript syntax for variables.
  *
  * @property {string} [mod]
  * Formatting modifier, as supported by method {@link formatting.format as.format}: `^`, `~`, `#`, `:csv`, `:json`, `name`, `raw`, `:value`.
  *
  * @property {string} [cast]
- * Server-side type casting.
- *
- * Leading `::` is allowed, but not needed (automatically removed when specified).
+ * Server-side type casting. Leading `::` is allowed, but not needed (automatically removed when specified).
  *
  * @property {} [def]
  * Default value for the property, to be used only when the source object doesn't have the property.
  *
  * @property {helpers.InitCB} [init]
- * Value override callback.
+ * Override callback for the value.
  *
  */
 
 /**
  * @callback helpers.InitCB
  * @description
- * A callback function type used as parameter `init` within {@link helpers~ColumnDescriptor ColumnDescriptor}.
+ * A callback function type used for parameter `init` within {@link helpers~ColumnConfig ColumnConfig}.
  *
  * It works as an override for the corresponding property value in the source object.
  *
@@ -194,7 +196,7 @@ Column.prototype.inspect = function () {
  * then the `value` is set to the `def` value.
  *
  * @returns {}
- * The value to be used for the corresponding column.
+ * The new value to be used for the corresponding column.
  */
 
 module.exports = Column;

lib/helpers/columnSet.js

@@ -18,18 +18,31 @@ var $npm = {
  * Information about all query-formatting columns.
  *
  * @param {Array|Object} columns
- * Column information object, depending on the type:
- * - if a simple object, its properties are enumerated to represent both column names and source property names.
- * - if it is an array, each element is assumed to represent a column details, and passed directly into {@link helpers.Column Column}.
+ * Columns information object, depending on the type:
  *
+ * - When it is a simple object, its properties are enumerated to represent both column names and property names
+ *   within the source objects. See also option `inherit` that's applicable in this case.
  *
+ * - When it is a single {@link helpers.Column Column} object, property {@link helpers.ColumnSet.columns columns} is initialized with
+ *   just a single column. It is not a unique situation when only a single column is required for an update operation.
+ *
+ * - When it is an array, each element is assumed to represent details for a column. If the element is already of type {@link helpers.Column Column},
+ *   it is used directly; otherwise the element is passed into {@link helpers.Column Column} constructor for initialization.
+ *
+ * - When it is none of the above, it will throw {@link external:TypeError TypeError} = `Invalid parameter 'columns' specified.`
+ * 
  * @param {Object} [options]
  *
- * @param {string} [options.table]
+ * @param {String} [options.table]
  * Table name.
  *
- * @param {boolean} [options.inherit = false]
- * Use inherited properties when enumerating an object.
+ * It can be used as the default for methods {@link helpers.insert insert} and {@link helpers.update update} when their parameter
+ * `table` is omitted, and for logging purposes.
+ *
+ * @param {Boolean} [options.inherit = false]
+ * Use inherited properties in addition to the object's own properties.
+ *
+ * By default, only the object's own properties are enumerated for column names.
  *
  * @returns {helpers.ColumnSet}
  *
@@ -59,6 +72,7 @@ function ColumnSet(columns, options) {
     /**
      * @name helpers.ColumnSet#table
      * @type String
+     * @readonly
      * @description
      * Destination table name. It can be specified for two purposes:
      *
@@ -70,18 +84,23 @@ function ColumnSet(columns, options) {
     /**
      * @name helpers.ColumnSet#columns
      * @type Array
+     * @readonly
      * @description
      * Array of {@link helpers.Column Column} objects.
      */
     if (Array.isArray(columns)) {
         this.columns = columns.$map(function (c) {
-            return new $npm.Column(c);
+            return (c instanceof $npm.Column) ? c : new $npm.Column(c);
         });
     } else {
-        this.columns = [];
-        for (var name in columns) {
-            if (inherit || columns.hasOwnProperty(name)) {
-                this.columns.push(new $npm.Column(name));
+        if (columns instanceof $npm.Column) {
+            this.columns = [columns];
+        } else {
+            this.columns = [];
+            for (var name in columns) {
+                if (inherit || columns.hasOwnProperty(name)) {
+                    this.columns.push(new $npm.Column(name));
+                }
             }
         }
     }
@@ -134,6 +153,21 @@ function ColumnSet(columns, options) {
         }
     });
 
+    /**
+     * @method helpers.ColumnSet.prepare
+     * @description
+     * Prepares a source object to be formatted, by cloning it and applying the rules
+     * as set by the columns configuration.
+     *
+     * This method is meant primarily for internal use.
+     *
+     * @param {Object} obj
+     * Source object to be prepared.
+     *
+     * @returns {Object}
+     * A clone of the source objects, with all properties and values set according to
+     * the columns configuration.
+     */
     this.prepare = function (obj) {
         var target = {};
         this.columns.$forEach(function (c) {
@@ -183,7 +217,7 @@ ColumnSet.prototype.toString = function (level) {
         lines.push(gap1 + 'columns: [');
         this.columns.$forEach(function (c) {
             lines.push(c.toString(2));
-        }, this);
+        });
         lines.push(gap1 + ']');
     } else {
         lines.push(gap1 + 'columns: []');

lib/helpers/index.js

@@ -3,16 +3,30 @@
 var $npm = {
     insert: require('./methods/insert'),
     update: require('./methods/update'),
-    ColumnSet: require('./columnSet')
+    ColumnSet: require('./columnSet'),
+    Column: require('./column')
 };
 
 /**
  * @namespace helpers
  * @description
- * 
+ *
  * ** WARNING: Everything within the {@link helpers} namespace is currently in its Alpha version.**
  *
- * Namespace for high-level query-formatting functions, available as `pgp.helpers` after initializing the library.
+ * Namespace for automated query formatting helpers, available as `pgp.helpers` after initializing the library.
+ *
+ * @property {Function} ColumnSet
+ * {@link helpers.ColumnSet ColumnSet} class constructor.
+ *
+ * @property {Function} Column
+ * {@link helpers.Column Column} class constructor.
+ *
+ * @property {Function} insert
+ * {@link helpers.insert insert} static method.
+ *
+ * @property {Function} update
+ * {@link helpers.update update} static method.
+ *
  */
 module.exports = function (config) {
     var res = {
@@ -24,7 +38,8 @@ module.exports = function (config) {
             var capSQL = config.options && config.options.capSQL;
             return $npm.update(data, columns, table, options, capSQL);
         },
-        ColumnSet: $npm.ColumnSet
+        ColumnSet: $npm.ColumnSet,
+        Column: $npm.Column
     };
     Object.freeze(res);
     return res;

lib/helpers/methods/insert.js

@@ -19,7 +19,7 @@ var $npm = {
  * And if `data` is an array that contains an invalid insert object, the method will throw {@link external:Error Error} =
  * `Invalid insert object at index N.`
  *
- * @param {Array|helpers.ColumnSet} [columns]
+ * @param {Array|helpers.Column|helpers.ColumnSet} [columns]
  * Set of columns to be inserted.
  *
  * It is optional when `data` is a single object, and required when `data` is an array of objects. When not specified for an array

lib/helpers/methods/update.js

@@ -19,7 +19,7 @@ var $npm = {
  * And if `data` is an array that contains an invalid update object, the method will throw {@link external:Error Error} =
  * `Invalid update object at index N.`
  *
- * @param {Array|helpers.ColumnSet} [columns]
+ * @param {Array|helpers.Column|helpers.ColumnSet} [columns]
  * Set of columns to be updated.
  *
  * It is optional when `data` is a single object, and required when `data` is an array of objects. When not specified for an array
@@ -58,7 +58,7 @@ function update(data, columns, table, options, capSQL) {
     if (!data || typeof data !== 'object') {
         throw new TypeError("Invalid parameter 'data' specified.");
     }
-
+    
     if (columns instanceof $npm.ColumnSet) {
         if ($npm.utils.isNull(table)) {
             table = columns.table;

lib/txMode.js

@@ -13,16 +13,16 @@
 var isolationLevel = {
     /** Isolation level not specified. */
     none: 0,
-
+    
     /** ISOLATION LEVEL SERIALIZABLE */
     serializable: 1,
 
     /** ISOLATION LEVEL REPEATABLE READ */
     repeatableRead: 2,
-
+    
     /** ISOLATION LEVEL READ COMMITTED */
     readCommitted: 3
-
+    
     // From the official documentation: http://www.postgresql.org/docs/9.5/static/sql-set-transaction.html
     // The SQL standard defines one additional level, READ UNCOMMITTED. In PostgreSQL READ UNCOMMITTED is treated as READ COMMITTED.
     // => skipping `READ UNCOMMITTED`.
@@ -163,10 +163,10 @@ function TransactionMode(tiLevel, readOnly, deferrable) {
  *  - access mode
  *  - deferrable mode
  *
- * @property {TransactionMode} TransactionMode
- * Automated Transaction Mode class
+ * @property {Function} TransactionMode
+ * {@link txMode.TransactionMode TransactionMode} class constructor.
  *
- * @property {isolationLevel} isolationLevel
+ * @property {txMode.isolationLevel} isolationLevel
  * Transaction Isolation Level enumerator
  *
  * @see $[BEGIN]
@@ -176,4 +176,4 @@ module.exports = {
     TransactionMode: TransactionMode
 };
 
-Object.freeze(module.exports);
+Object.freeze(module.exports);

package.json

@@ -1,10 +1,10 @@
 {
   "name": "pg-promise",
-  "version": "4.0.7",
+  "version": "4.0.8",
   "description": "PostgreSQL via promises",
   "main": "lib/index.js",
   "scripts": {
-    "test": "jasmine-node test",
+    "test": "jasmine-node test --nohelpers",
     "test-native": "jasmine-node test --config PG_NATIVE true",
     "doc": "./node_modules/.bin/jsdoc -c ./jsdoc/jsDoc.json ./jsdoc/README.md",
     "coverage": "istanbul cover ./node_modules/jasmine-node/bin/jasmine-node test",

test/typescript/build.bat

@@ -13,3 +13,4 @@ call tsc pg %PARAMS%
 call tsc prepared %PARAMS%
 call tsc paramQuery %PARAMS%
 call tsc errors %PARAMS%
+call tsc helpers %PARAMS%