chore(typescript): src/utils

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;
 }

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
 	}
-};
+}

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,

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);
-};
+}

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) {

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<FieldFormat>} 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?

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;
+	};
+}

src/utils/orderby_unwrap.js

@@ -1,12 +1,22 @@
-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 '';
 	});
 
 	return {
 		field,
 		direction,
 	};
-};
+}

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;

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('$');
 

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 ||

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('.');
 

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;