s202226701001/wisdom-server/node_modules/pg-promise/lib/helpers/column.js

/*
 * Copyright (c) 2015-present, Vitaly Tomilov
 *
 * See the LICENSE file at the top-level directory of this distribution
 * for licensing information.
 *
 * Removal or modification of this copyright notice is prohibited.
 */

const {InnerState} = require('../inner-state');
const {assert} = require('../assert');

const npm = {
    os: require('os'),
    utils: require('../utils'),
    formatting: require('../formatting'),
    patterns: require('../patterns')
};

/**
 *
 * @class helpers.Column
 * @description
 *
 * Read-only structure with details for a single column. Used primarily by {@link helpers.ColumnSet ColumnSet}.
 *
 * The class parses details into a template, to be used for query generation.
 *
 * @param {string|helpers.ColumnConfig} col
 * Column details, depending on the type.
 *
 * 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`, `:list`, `:json`, `:alias`, `:name`, `:raw`, `:value`), which is then removed from the name and put
 * into property `mod`. If the name starts with `?`, it is removed, while setting flag `cnd` = `true`.
 *
 * If the string doesn't adhere to the above requirements, the method will throw {@link external:TypeError TypeError} = `Invalid column syntax`.
 *
 * When `col` is a simple {@link helpers.ColumnConfig ColumnConfig}-like object, it is used as an input configurator to set all the properties
 * of the class.
 *
 * @property {string} name
 * 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 non-empty string.
 *
 * @property {string} [prop]
 * Source property name, if different from the column's name. It must adhere to JavaScript syntax for variables.
 *
 * It is ignored when it is the same as `name`.
 *
 * @property {string} [mod]
 * Formatting modifier, as supported by method {@link formatting.format as.format}: `^`, `~`, `#`, `:csv`, `:list`, `:json`, `:alias`, `:name`, `:raw`, `:value`.
 *
 * @property {string} [cast]
 * Server-side type casting, without `::` in front.
 *
 * @property {boolean} [cnd]
 * Conditional column flag.
 *
 * Used by methods {@link helpers.update update} and {@link helpers.sets sets}, ignored by methods {@link helpers.insert insert} and
 * {@link helpers.values values}. It indicates that the column is reserved for a `WHERE` condition, not to be set or updated.
 *
 * It can be set from a string initialization, by adding `?` in front of the name.
 *
 * @property {*} [def]
 * Default value for the property, to be used only when the source object doesn't have the property.
 * It is ignored when property `init` is set.
 *
 * @property {helpers.initCB} [init]
 * Override callback for the value.
 *
 * @property {helpers.skipCB} [skip]
 * An override for skipping columns dynamically.
 *
 * Used by methods {@link helpers.update update} (for a single object) and {@link helpers.sets sets}, ignored by methods
 * {@link helpers.insert insert} and {@link helpers.values values}.
 *
 * It is also ignored when conditional flag `cnd` is set.
 *
 * @returns {helpers.Column}
 *
 * @see
 * {@link helpers.ColumnConfig ColumnConfig},
 * {@link helpers.Column#castText castText},
 * {@link helpers.Column#escapedName escapedName},
 * {@link helpers.Column#variable variable}
 *
 * @example
 *
 * const pgp = require('pg-promise')({
 *     capSQL: true // if you want all generated SQL capitalized
 * });
 *
 * const {Column} = pgp.helpers;
 *
 * // creating a column from just a name:
 * const col1 = new Column('colName');
 * console.log(col1);
 * //=>
 * // Column {
 * //    name: "colName"
 * // }
 *
 * // creating a column from a name + modifier:
 * const col2 = new Column('colName:csv');
 * console.log(col2);
 * //=>
 * // Column {
 * //    name: "colName"
 * //    mod: ":csv"
 * // }
 *
 * // creating a column from a configurator:
 * const col3 = new Column({
 *     name: 'colName', // required
 *     prop: 'propName', // optional
 *     mod: '^', // optional
 *     def: 123 // optional
 * });
 * console.log(col3);
 * //=>
 * // Column {
 * //    name: "colName"
 * //    prop: "propName"
 * //    mod: "^"
 * //    def: 123
 * // }
 *
 */
class Column extends InnerState {

    constructor(col) {
        super();

        if (typeof col === 'string') {
            const info = parseColumn(col);
            this.name = info.name;
            if ('mod' in info) {
                this.mod = info.mod;
            }
            if ('cnd' in info) {
                this.cnd = info.cnd;
            }
        } else {
            col = assert(col, ['name', 'prop', 'mod', 'cast', 'cnd', 'def', 'init', 'skip']);
            if ('name' in col) {
                if (!npm.utils.isText(col.name)) {
                    throw new TypeError(`Invalid 'name' value: ${npm.utils.toJson(col.name)}. A non-empty string was expected.`);
                }
                if (npm.utils.isNull(col.prop) && !isValidVariable(col.name)) {
                    throw new TypeError(`Invalid 'name' syntax: ${npm.utils.toJson(col.name)}.`);
                }
                this.name = col.name; // column name + property name (if 'prop' isn't specified)

                if (!npm.utils.isNull(col.prop)) {
                    if (!npm.utils.isText(col.prop)) {
                        throw new TypeError(`Invalid 'prop' value: ${npm.utils.toJson(col.prop)}. A non-empty string was expected.`);
                    }
                    if (!isValidVariable(col.prop)) {
                        throw new TypeError(`Invalid 'prop' syntax: ${npm.utils.toJson(col.prop)}.`);
                    }
                    if (col.prop !== col.name) {
                        // optional property name, if different from the column's name;
                        this.prop = col.prop;
                    }
                }
                if (!npm.utils.isNull(col.mod)) {
                    if (typeof col.mod !== 'string' || !isValidMod(col.mod)) {
                        throw new TypeError(`Invalid 'mod' value: ${npm.utils.toJson(col.mod)}.`);
                    }
                    this.mod = col.mod; // optional format modifier;
                }
                if (!npm.utils.isNull(col.cast)) {
                    this.cast = parseCast(col.cast); // optional SQL type casting
                }
                if ('cnd' in col) {
                    this.cnd = !!col.cnd;
                }
                if ('def' in col) {
                    this.def = col.def; // optional default
                }
                if (typeof col.init === 'function') {
                    this.init = col.init; // optional value override (overrides 'def' also)
                }
                if (typeof col.skip === 'function') {
                    this.skip = col.skip;
                }
            } else {
                throw new TypeError('Invalid column details.');
            }
        }

        const variable = '${' + (this.prop || this.name) + (this.mod || '') + '}';
        const castText = this.cast ? ('::' + this.cast) : '';
        const escapedName = npm.formatting.as.name(this.name);

        this.extendState({variable, castText, escapedName});
        Object.freeze(this);
    }

    /**
     * @name helpers.Column#variable
     * @type string
     * @readonly
     * @description
     * Full-syntax formatting variable, ready for direct use in query templates.
     *
     * @example
     *
     * const cs = new ColumnSet([
     *     'id',
     *     'coordinate:json',
     *     {
     *         name: 'places',
     *         mod: ':csv',
     *         cast: 'int[]'
     *     }
     * ]);
     *
     * // cs.columns[0].variable = ${id}
     * // cs.columns[1].variable = ${coordinate:json}
     * // cs.columns[2].variable = ${places:csv}::int[]
     */
    get variable() {
        return this._inner.variable;
    }

    /**
     * @name helpers.Column#castText
     * @type string
     * @readonly
     * @description
     * Full-syntax sql type casting, if there is any, or else an empty string.
     */
    get castText() {
        return this._inner.castText;
    }

    /**
     * @name helpers.Column#escapedName
     * @type string
     * @readonly
     * @description
     * Escaped name of the column, ready to be injected into queries directly.
     *
     */
    get escapedName() {
        return this._inner.escapedName;
    }

}

function parseCast(name) {
    if (typeof name === 'string') {
        const s = name.replace(/^[:\s]*|\s*$/g, '');
        if (s) {
            return s;
        }
    }
    throw new TypeError(`Invalid 'cast' value: ${npm.utils.toJson(name)}.`);
}

function parseColumn(name) {
    const m = name.match(npm.patterns.validColumn);
    if (m && m[0] === name) {
        const res = {};
        if (name[0] === '?') {
            res.cnd = true;
            name = name.substring(1);
        }
        const mod = name.match(npm.patterns.hasValidModifier);
        if (mod) {
            res.name = name.substring(0, mod.index);
            res.mod = mod[0];
        } else {
            res.name = name;
        }
        return res;
    }
    throw new TypeError(`Invalid column syntax: ${npm.utils.toJson(name)}.`);
}

function isValidMod(mod) {
    return npm.patterns.validModifiers.indexOf(mod) !== -1;
}

function isValidVariable(name) {
    const m = name.match(npm.patterns.validVariable);
    return !!m && m[0] === name;
}

/**
 * @method helpers.Column#toString
 * @description
 * Creates a well-formatted multi-line string that represents the object.
 *
 * It is called automatically when writing the object into the console.
 *
 * @param {number} [level=0]
 * Nested output level, to provide visual offset.
 *
 * @returns {string}
 */
Column.prototype.toString = function (level) {
    level = level > 0 ? parseInt(level) : 0;
    const gap0 = npm.utils.messageGap(level),
        gap1 = npm.utils.messageGap(level + 1),
        lines = [
            gap0 + 'Column {',
            gap1 + 'name: ' + npm.utils.toJson(this.name)
        ];
    if ('prop' in this) {
        lines.push(gap1 + 'prop: ' + npm.utils.toJson(this.prop));
    }
    if ('mod' in this) {
        lines.push(gap1 + 'mod: ' + npm.utils.toJson(this.mod));
    }
    if ('cast' in this) {
        lines.push(gap1 + 'cast: ' + npm.utils.toJson(this.cast));
    }
    if ('cnd' in this) {
        lines.push(gap1 + 'cnd: ' + npm.utils.toJson(this.cnd));
    }
    if ('def' in this) {
        lines.push(gap1 + 'def: ' + npm.utils.toJson(this.def));
    }
    if ('init' in this) {
        lines.push(gap1 + 'init: [Function]');
    }
    if ('skip' in this) {
        lines.push(gap1 + 'skip: [Function]');
    }
    lines.push(gap0 + '}');
    return lines.join(npm.os.EOL);
};

npm.utils.addInspection(Column, function () {
    return this.toString();
});

/**
 * @typedef helpers.ColumnConfig
 * @description
 * A simple structure with column details, to be passed into the {@link helpers.Column Column} constructor for initialization.
 *
 * @property {string} name
 * 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 non-empty string.
 *
 * @property {string} [prop]
 * Source property name, if different from the column's name. It must adhere to JavaScript syntax for variables.
 *
 * It is ignored when it is the same as `name`.
 *
 * @property {string} [mod]
 * Formatting modifier, as supported by method {@link formatting.format as.format}: `^`, `~`, `#`, `:csv`, `:list`, `:json`, `:alias`, `:name`, `:raw`, `:value`.
 *
 * @property {string} [cast]
 * Server-side type casting. Leading `::` is allowed, but not needed (automatically removed when specified).
 *
 * @property {boolean} [cnd]
 * Conditional column flag.
 *
 * Used by methods {@link helpers.update update} and {@link helpers.sets sets}, ignored by methods {@link helpers.insert insert} and
 * {@link helpers.values values}. It indicates that the column is reserved for a `WHERE` condition, not to be set or updated.
 *
 * It can be set from a string initialization, by adding `?` in front of the name.
 *
 * @property {*} [def]
 * Default value for the property, to be used only when the source object doesn't have the property.
 * It is ignored when property `init` is set.
 *
 * @property {helpers.initCB} [init]
 * Override callback for the value.
 *
 * @property {helpers.skipCB} [skip]
 * An override for skipping columns dynamically.
 *
 * Used by methods {@link helpers.update update} (for a single object) and {@link helpers.sets sets}, ignored by methods
 * {@link helpers.insert insert} and {@link helpers.values values}.
 *
 * It is also ignored when conditional flag `cnd` is set.
 *
 */

/**
 * @callback helpers.initCB
 * @description
 * A callback function type used by parameter `init` within {@link helpers.ColumnConfig ColumnConfig}.
 *
 * It works as an override for the corresponding property value in the `source` object.
 *
 * The function is called with `this` set to the `source` object.
 *
 * @param {*} col
 * Column-to-property descriptor.
 *
 * @param {object} col.source
 * The source object, equals to `this` that's passed into the function.
 *
 * @param {string} col.name
 * Resolved name of the property within the `source` object, i.e. the value of `name` when `prop` is not used
 * for the column, or the value of `prop` when it is specified.
 *
 * @param {*} col.value
 *
 * Property value, set to one of the following:
 *
 * - Value of the property within the `source` object (`value` = `source[name]`), if the property exists
 * - If the property doesn't exist and `def` is set in the column, then `value` is set to the value of `def`
 * - If the property doesn't exist and `def` is not set in the column, then `value` is set to `undefined`
 *
 * @param {boolean} col.exists
 * Indicates whether the property exists in the `source` object (`exists = name in source`).
 *
 * @returns {*}
 * The new value to be used for the corresponding column.
 */

/**
 * @callback helpers.skipCB
 * @description
 * A callback function type used by parameter `skip` within {@link helpers.ColumnConfig ColumnConfig}.
 *
 * It is to dynamically determine when the property with specified `name` in the `source` object is to be skipped.
 *
 * The function is called with `this` set to the `source` object.
 *
 * @param {*} col
 * Column-to-property descriptor.
 *
 * @param {object} col.source
 * The source object, equals to `this` that's passed into the function.
 *
 * @param {string} col.name
 * Resolved name of the property within the `source` object, i.e. the value of `name` when `prop` is not used
 * for the column, or the value of `prop` when it is specified.
 *
 * @param {*} col.value
 *
 * Property value, set to one of the following:
 *
 * - Value of the property within the `source` object (`value` = `source[name]`), if the property exists
 * - If the property doesn't exist and `def` is set in the column, then `value` is set to the value of `def`
 * - If the property doesn't exist and `def` is not set in the column, then `value` is set to `undefined`
 *
 * @param {boolean} col.exists
 * Indicates whether the property exists in the `source` object (`exists = name in source`).
 *
 * @returns {boolean}
 * A truthy value that indicates whether the column is to be skipped.
 *
 */

module.exports = {Column};