[ci skip] Update comments in reqQueryFields

src/libs/middlewares/reqQueryFields.js

@@ -6,13 +6,38 @@ const _ = require('lodash');
 
 class ReqQueryFields {
     constructor(fields = {}, fieldValues = {}) {
+        // Exemplo de requisição: `/api/v1/enrollments?dims=state,region,location`
+
         // Parâmetros no campo query da requisição.
         // Exemplo de field:
+        // ```js
         // {
         //    name: 'dims',
         //    field: true,
         //    where: false
         // }
+        // ```
+        // Array de valores aceitos pelo campo.
+        // Exemplo de valor:
+        // ```
+        // {
+        //     name: 'location',
+        //     table: 'localizacao',
+        //     tableField: 'descricao'
+        //     resultField: 'location_name',
+        //     where: {
+        //         relation: '=',
+        //         type: 'integer',
+        //         field: 'id_localizacao',
+        //         table: 'turma'
+        //     },
+        //     join: {
+        //         primary: 'pk_localizacao_id',
+        //         foreign: 'id_localizacao',
+        //         foreignTable: 'turma'
+        //     }
+        // }
+        // ```
         this.fields = fields;
         this.fieldValues = fieldValues;
     }
@@ -20,12 +45,14 @@ class ReqQueryFields {
     addField(field) {
         // Parâmetro no campo query da requisição.
         // Exemplo de field:
+        // ```
         // {
         //    name: 'dims',
         //    field: true,
         //    where: false,
         //    fieldValues: {}
         // }
+        // ```
         if(typeof this.fields[field.name] === 'undefined') {
             log.debug("added field "+field.name);
             this.fields[field.name] = field;
@@ -34,8 +61,9 @@ class ReqQueryFields {
     }
 
     addValue(fieldValue) {
-        // Array de valores aceitos pelo campo
+        // Valor aceito por **todos** os campos.
         // Exemplo de valor:
+        // ```
         // {
         //     name: 'location',
         //     table: 'localizacao',
@@ -53,7 +81,7 @@ class ReqQueryFields {
         //         foreignTable: 'turma'
         //     }
         // }
-
+        // ```
         if(typeof this.fieldValues[fieldValue.name] === 'undefined') {
             this.fieldValues[fieldValue.name] = fieldValue;
             log.debug("added value "+fieldValue.name);
@@ -62,7 +90,9 @@ class ReqQueryFields {
     }
 
     addValueToField(fieldValue, field) {
+        // Valor aceito **apenas** pelo campo `field`.
         if(typeof this.fields[field] === 'undefined') {
+            // Se o campo não existe, lança uma exception
             throw 'No field with name ' +field+ ' defined';
         }
         if(typeof this.fields[field].values === 'undefined') {
@@ -76,47 +106,56 @@ class ReqQueryFields {
     }
 
     parse() {
+        // Faz o parse dos valores que vem na requisição para objetos.
         return (req, res, next) => {
+            // "Foreach" nos campos aceitos
             Object.keys(this.fields).map((key, index) => {
                 let params = [];
+                // f é o campo
                 let f = this.fields[key];
                 log.debug('f');
                 log.debug(f);
-                // Unimos os valores aceitos globalmente com os aceitos apenas pelo parâmetro
+                // Unimos os valores parametros globalmente com os aceitos apenas pelo campo
                 let values = _.merge(this.fieldValues, f.values);
+                // Fazemos um foreach nos parametros aceitos
                 Object.keys(values).map((k, i) => {
                     let value = values[k];
                     log.debug('value');
                     log.debug(value);
+                    // Pushamos o parametro
                     params.push(value.name);
                 });
                 let queryField = f.name;
                 let arrayOfParams = params;
+                // Criamos o atributo com o nome do **campo** no objeto `req` (nome do campo é 'filter', 'dims', 'search', etc)
                 req[queryField] = {};
                 if (req.query[queryField]) {
+                    // Se há mais de um parametro no campo, eles estão separados por vírgula.
+                    // Fazemos o split então para separar os valores
                     const params = req.query[queryField].split(',');
-                    // Temporary object to hold the params and it's values
+                    // Objeto temporário para guardar os parametros e seus valores.
                     const obj = {};
                     for (const param of params) {
-                        // Get the key and the value - state:41 is key 'state' whith value 41.
-                        // kv is then an array [key, value] or [key] if there is no value
+                        // O parametro *pode* ter um valor (por exemplo: `state:41`).
+                        // Fazemos o split e temos um array `['state', 41]`
                         const kv = param.split(':');
-                        // Check if there is a value. If there isn't, assign true
+                        // Checa se há um valor. Se não tem, definimos como true.
                         obj[kv[0]] = (typeof kv[1] === 'undefined') ? true : kv[1];
-                        // obj is now an object {kv[0]: kv[1]} ou {kv[0]: true}
+                        // `obj` é agora `{kv[0]: kv[1]}` ou `{kv[0]: true}`.
+                        // No exemplo `{'state': 41}`
                     }
 
-                    // If the array exists and is not empty we intersect
+                    // Se o array existe e não está vazio fazemos a interseção
                     if (typeof arrayOfParams !== 'undefined' && arrayOfParams.length > 0) {
-                        // Intersect the keys of the obj with the array arrayOfParams
-                        // The intersection array is assigned with the keys
+                        // Fazemos a interseção das chaves de `obj` com o array `arrayOfParams`.
+                        // O array resultante são as chaves aceitas pelo campo.
                         const intersection = _.intersection(arrayOfParams, Object.keys(obj));
-                        // This is a bit tricky...
-                        // For each key in the intersection array we get it's value in the obj
-                        // and assign it to the custom attribute in the req obj.
-                        // For example: instersection => ["state"] so
-                        // obj[intersection[i]] (with i=0) is obj["state"], that is 41
-                        // and req[queryField]["state"] = 41
+                        // Isso é um pouco complicado...
+                        // Para cada chave na interseção pegamos seu valor em `obj`
+                        // e atribuímos para o atributo que definimos no objeto `req`.
+                        // Por exemplo: intersection = `['state']` então
+                        // `obj[intersection[i]]` (com i=0) é `obj['state']`, cujo valor é 41.
+                        // Então fazemos `req[queryField]['state'] = 41`
                         for (let i = 0; i < intersection.length; ++i) {
                             req[queryField][intersection[i]] = obj[intersection[i]];
                         }
@@ -132,13 +171,18 @@ class ReqQueryFields {
     }
 
     build() {
+        // "Constrói" o SQL
         return (req, res, next) => {
+            // Foreach no campos
             Object.keys(this.fields).map((key, index) => {
+                // Campo
                 let field = this.fields[key];
                 log.debug(field);
+                // `param` aqui é o atributo no objeto `req` (dims, filter, search, ...)
                 let param = req[field.name];
                 log.debug('param');
                 log.debug(param);
+                // Fazemos um foreach nos parametros dentro do atributo
                 Object.keys(param).map((k, i) => {
                     let values = _.merge(this.fieldValues, field.values);
                     log.debug('ValueS');
@@ -146,7 +190,7 @@ class ReqQueryFields {
                     log.debug('k');
                     log.debug(k);
                     if(typeof values[k] !== 'undefined') {
-                        // Clonamos para não alterar
+                        // Clonamos para não alterar o original
                         let value = _.clone(values[k]);
                         log.debug(value);
                         // Checa se não fizemos o join para este valor e se é necessário fazer