diff --git a/src/format/groupby_reducer.js b/src/format/groupby_reducer.js index 956ecf18..46b54f59 100644 --- a/src/format/groupby_reducer.js +++ b/src/format/groupby_reducer.js @@ -2,6 +2,20 @@ import fieldUnwrap from '../utils/unwrap_field.js'; import fieldRelativePath from '../utils/field_relative.js'; import mapReduce from '../utils/map_reduce.js'; +/* eslint-disable jsdoc/valid-types */ +/** + * @typedef {import('../utils/unwrap_field.js').UnwrappedField} UnwrappedField + */ +/* eslint-enable jsdoc/valid-types */ + +/** + * Groupby Reducer + * Create a groupby in the associate model + * @param {object} options - The options + * @param {string} options.current_path - The current path + * @param {Function} options.extract - The extract function + * @returns {Function} - The reducer + */ export default function groupbyReducer({current_path, extract}) { return mapReduce(field => { // Get the field address @@ -35,6 +49,12 @@ export default function groupbyReducer({current_path, extract}) { }); } +/** + * Field Wrap + * Wrap the field + * @param {UnwrappedField} item - The field format + * @returns {string} - The wrapped field + */ function fieldWrap(item) { return item.prefix + item.field + item.suffix; } diff --git a/src/utils/JSONparse.js b/src/utils/JSONparse.js index 26152538..03ae62a4 100644 --- a/src/utils/JSONparse.js +++ b/src/utils/JSONparse.js @@ -1,5 +1,11 @@ // Prevent a bad format from killing the service, instead return undefined -export default value => { + +/** + * Parse JSON + * @param {string} value - The value to parse + * @returns {any} - The parsed value + */ +export default function JSONParse(value) { try { // Ensure Buffers are converted.. if (Buffer.isBuffer(value)) { @@ -21,4 +27,4 @@ export default value => { } catch { // Continue } -}; +} diff --git a/src/utils/field_format.js b/src/utils/field_format.js index a920c2ce..bab59f6d 100644 --- a/src/utils/field_format.js +++ b/src/utils/field_format.js @@ -1,5 +1,22 @@ import unwrap_expression from './unwrap_field.js'; +/** + * Field Format + * @typedef {object} FieldFormat + * @property {string} [original] - The original field expression + * @property {string} expression - The field expression + * @property {string} label - The label + * @property {boolean} [agg] - Is this an aggregate function + */ + +/** + * Format a field expression + * @param {string} original - The original field expression + * @param {string} label - The label + * @param {string} table_prefix - The table prefix + * @param {string} label_prefix - The label prefix + * @returns {FieldFormat} - The field format + */ export default function field_format( original, label, diff --git a/src/utils/field_relative.js b/src/utils/field_relative.js index 98ecb640..aa74eefc 100644 --- a/src/utils/field_relative.js +++ b/src/utils/field_relative.js @@ -1,12 +1,13 @@ -// Relative Address - -/* - * Overlap strings +/** + * Join paths * Given two strings, e.g. 'this.is.not' and 'is.not.over' * Find the over laping section in this case 'is.not' * Return the various parts as an array ['this', '.is.not', '.over'] + * @param {string} a - The first path + * @param {string} b - The second path + * @returns {string} - The relative path */ -export default (a, b) => { +export default function pathJoin(a, b) { let path = b; /* @@ -27,4 +28,4 @@ export default (a, b) => { } return b.slice(path.length); -}; +} diff --git a/src/utils/format_datetime.js b/src/utils/format_datetime.js index e7999417..bd2b5282 100644 --- a/src/utils/format_datetime.js +++ b/src/utils/format_datetime.js @@ -1,3 +1,8 @@ +/** + * Format date and time values + * @param {string} values - The date and time values + * @returns {string} - The formatted date and time values + */ export default function formatDateTime(values) { if (typeof values === 'string') { if (values.indexOf('..') === -1) { diff --git a/src/utils/group_concat.js b/src/utils/group_concat.js index f63d568a..6e464642 100644 --- a/src/utils/group_concat.js +++ b/src/utils/group_concat.js @@ -1,7 +1,19 @@ -/* +/* eslint-disable jsdoc/valid-types */ +/** + * @typedef {import('./field_format.js').FieldFormat} FieldFormat + */ +/* eslint-enable jsdoc/valid-types */ + +/** * Generate GROUP_CONCAT statement given an array of fields definitions * Label the GROUP CONCAT(..) AS 'address[fields,...]' * Wrap all the fields in a GROUP_CONCAT statement + * + * @param {Array} fields - The fields to group + * @param {string} address - The address of the fields + * @param {string} sql_alias - The SQL alias of the table + * @param {string} rowid - The rowid field _rowid + * @returns {{expression: string, label: string}} - The field definition and the label */ export default function group_concat(fields, address = '', sql_alias, rowid) { // Is this an aggregate list? diff --git a/src/utils/map_reduce.js b/src/utils/map_reduce.js index 5c598e73..7a29c67b 100644 --- a/src/utils/map_reduce.js +++ b/src/utils/map_reduce.js @@ -1,10 +1,18 @@ -// Create a map reduce function which converts content as well as filters out undefined -export default callback => (list, item, index) => { - const response = callback(item, index); +/** + * MapReduce + * Create a handler to be applied to a array.reduce function + * Executes the callback function on each item in the array and creating a new array of the results + * @param {Function} callback - The function to be executed on each item + * @returns {Function} - The handler + */ +export default function mapReduce(callback) { + return (list, item, index) => { + const response = callback(item, index); - if (response) { - list.push(response); - } + if (response) { + list.push(response); + } - return list; -}; + return list; + }; +} diff --git a/src/utils/orderby_unwrap.js b/src/utils/orderby_unwrap.js index 48ade46e..17f8c99e 100644 --- a/src/utils/orderby_unwrap.js +++ b/src/utils/orderby_unwrap.js @@ -1,7 +1,17 @@ -export default str => { +/** + * @typedef {"" | "asc" | "desc"} DirectionType + */ + +/** + * Unwrap the orderBy string into field and direction + * @param {string} str - The orderBy string + * @returns {{field: string, direction: DirectionType}} - The unwrapped orderBy + */ +export default function orderByUnwrap(str) { + /** @type {DirectionType} */ let direction = ''; const field = str.replace(/\s*(?:desc|asc)$/i, m => { - direction = m.toUpperCase(); + direction = /** @type {DirectionType} */ (m.toUpperCase()); return ''; }); @@ -9,4 +19,4 @@ export default str => { field, direction, }; -}; +} diff --git a/src/utils/unwrap_field.js b/src/utils/unwrap_field.js index 8ba9c6e8..7336a3b6 100644 --- a/src/utils/unwrap_field.js +++ b/src/utils/unwrap_field.js @@ -2,6 +2,25 @@ /* eslint-disable prefer-named-capture-group */ import DareError from './error.js'; +/** + * Unwrap a field expression to its components + * @typedef {object} UnwrappedField + * @property {string} [field] - The field expression + * @property {string} [field_name] - The field name + * @property {string} [field_path] - The field path + * @property {string} [prefix] - The prefix + * @property {string} [suffix] - The suffix + * @property {string} [suffix] - The suffix + * @property {string} [value] - The value + * @property {string} [direction] - The orderby field direction + */ + +/** + * Unwrap a field expression to its components + * @param {string} expression - The field expression + * @param {boolean} allowValue - Allow a value to be returned + * @returns {UnwrappedField} - The unwrapped field or value + */ export default function unwrap_field(expression, allowValue = true) { if (typeof expression === 'string') { let m; diff --git a/src/utils/validate_alias.js b/src/utils/validate_alias.js index 7a8bdfc0..94851b8e 100644 --- a/src/utils/validate_alias.js +++ b/src/utils/validate_alias.js @@ -1,5 +1,11 @@ import DareError from './error.js'; +/** + * Validate an alias + * @param {string} key - The alias + * @returns {void} + * @throws {DareError} - If the alias is invalid + */ export default function validate_alias(key) { const [name, label] = key.split('$'); diff --git a/src/utils/validate_body.js b/src/utils/validate_body.js index 892ff269..5a354e77 100644 --- a/src/utils/validate_body.js +++ b/src/utils/validate_body.js @@ -1,7 +1,11 @@ -// Validate POST body - import DareError from './error.js'; +/** + * Validate the body of a POST request + * @param {object} body - The body of the request + * @returns {void} + * @throws {DareError} - If the body is invalid + */ export default function validate_body(body) { if ( !body || diff --git a/src/utils/validate_field.js b/src/utils/validate_field.js index 97768ca9..19b69103 100644 --- a/src/utils/validate_field.js +++ b/src/utils/validate_field.js @@ -1,6 +1,12 @@ import DareError from './error.js'; import validate_alias from './validate_alias.js'; +/** + * Validate a field + * @param {string} key - The field + * @returns {string} - The validated field + * @throws {DareError} - If the field is invalid + */ export default function validate_field(key) { const a = key.split('.'); diff --git a/src/utils/validate_label.js b/src/utils/validate_label.js index b1fd5431..1f7a4deb 100644 --- a/src/utils/validate_label.js +++ b/src/utils/validate_label.js @@ -1,5 +1,11 @@ import DareError from './error.js'; +/** + * Validate a label + * @param {string} label - The label + * @returns {void} + * @throws {DareError} - If the label is invalid + */ export default function validate_label(label) { const reg = /^[^"'?`]+$/i;