utils

Namespace for general-purpose static functions, available as pgp.utils, before and after initializing the library.

Properties:
Name Type Description
camelize function

camelize - camelizes a text string
camelizeVar function

camelizeVar - camelizes a text string as a variable
enumSql function

enumSql - enumerates SQL files in a directory
taskArgs function

taskArgs - prepares arguments for tasks and transactions
Source:

Methods

(static) camelize(text) → {string}

Camelizes a text string.

Case-changing characters include:

  • hyphen
  • underscore
  • period
  • space
Parameters:
Name Type Description
text string

Input text string.
Source:
See:
Returns:

Camelized text string.

Type
string

(static) camelizeVar(text) → {string}

Camelizes a text string, while making it compliant with JavaScript variable names:

  • contains symbols a-z, A-Z, 0-9, _ and $
  • cannot have leading digits

First, it removes all symbols that do not meet the above criteria, except for hyphen, period and space, and then it forwards into camelize.

Parameters:
Name Type Description
text string

Input text string.

If it doesn't contain any symbols to make up a valid variable name, the result will be an empty string.
Source:
See:
Returns:

Camelized text string that can be used as an open property name.

Type
string

(static) enumSql(dir, optionsopt, cbopt) → {object}

Synchronously enumerates all SQL files (within a given directory) into a camelized SQL tree.

All property names within the tree are camelized via camelizeVar, so they can be used in the code directly, as open property names.

Parameters:
Name Type Attributes Description
dir string

Directory path where SQL files are located, either absolute or relative to the current directory.

SQL files are identified by using .sql extension (case-insensitive).
options Object <optional>

Search options.

Properties
Name Type Attributes Default Description
recursive boolean <optional>
 false

Include sub-directories into the search.

Sub-directories without SQL files will be skipped from the result.
ignoreErrors boolean <optional>
 false

Ignore the following types of errors:

  • access errors, when there is no read access to a file or folder
  • empty or duplicate camelized property names

This flag does not affect errors related to invalid input parameters, or if you pass in a non-existing directory.
cb function <optional>

A callback function that takes three arguments:

  • file - SQL file path, relative or absolute, according to how you specified the search directory
  • name - name of the property that represents the SQL file
  • path - property resolution path (full property name)

If the function returns anything other than undefined, it overrides the corresponding property value in the tree.
Source:
Returns:

Camelized SQL tree object, with each value being an SQL file path (unless changed via the callback).

Type
object
Examples
// simple SQL tree generation for further processing:
const tree = pgp.utils.enumSql('../sql', {recursive: true});
// generating an SQL tree for dynamic use of names:
const sql = pgp.utils.enumSql(__dirname, {recursive: true}, file => {
    return new pgp.QueryFile(file, {minify: true});
});
const {join: joinPath} = require('path');

// replacing each relative path in the tree with a full one:
const tree = pgp.utils.enumSql('../sql', {recursive: true}, file => {
    return joinPath(__dirname, file);
});

(static) taskArgs(args) → {Array}

Normalizes/prepares arguments for tasks and transactions.

Its main purpose is to simplify adding custom methods task, taskIf, tx and txIf within event extend, as the those methods use fairly complex logic for parsing inputs.

Parameters:
Name Type Description
args Object

Array-like object of arguments that was passed into the method. It is expected that the arguments are always made of two parameters - (options, cb), same as all the default task/transaction methods.

And if your custom method needs additional parameters, they should be passed in as extra properties within options.
Source:
Returns:

Array of arguments that can be passed into a task or transaction.

It is extended with properties options and cb to access the corresponding array elements [0] and [1] by name.

Type
Array
Example
// Registering a custom transaction method that assigns a default Transaction Mode:

const initOptions = {
    extend: obj => {
        obj.myTx = function(options, cb) {
            const args = pgp.utils.taskArgs(arguments); // prepare arguments

            if (!('mode' in args.options)) {
                // if no 'mode' was specified, set default for transaction mode:
                args.options.mode = myTxModeObject; // of type pgp.txMode.TransactionMode
            }

            return obj.tx.apply(this, args);
            // or explicitly, if needed:
            // return obj.tx.call(this, args.options, args.cb);
        }
    }
};