@sankhyalabs/core 2.3.6 → 2.4.0

package/dist/dataunit/DataUnit.js

@@ -23,6 +23,9 @@ import { getSelection, hasNext, hasPrevious, SelectionReducer } from "./state/sl
 import { getField, getMetadata, UnitMetadataReducer } from "./state/slice/UnitMetadataSlice.js";
 import { getBlockingWaitingChanges, getWaitingChangePromisses, isWaiting, WaitingChangesReducer } from "./state/slice/WaitingChangesSlice.js";
 import { canRedo, canUndo, HistReducer } from "./state/HistReducer.js";
+/***
+ * `DataUnit`: Atua como uma camada de abstração entre o back-end e a interface do usuário.
+ */
 export default class DataUnit {
     constructor(name) {
         this._name = name;
@@ -44,14 +47,37 @@ export default class DataUnit {
         this._sortingProvider = undefined;
         this._interceptors = [];
     }
+    /**
+     *
+     * Obtém o nome de identificação do DataUnit (geralmente em formato de URI - Uniform Resource Identifier).
+     *
+     * @returns - Nome de identificação do DataUnit.
+     *
+    */
     get name() {
         return this._name;
     }
-    // Métodos privados
+    /**
+     *
+     * Obtém o valor convertido de acordo com o tipo do campo.
+     *
+     * @param fieldName - Identificador do campo.
+     * @param newValue - Novo valor que será atribuído ao campo pós validação.
+     *
+     * @returns - Novo valor convertido em um tipo valido.
+     *
+    */
     validateAndTypeValue(fieldName, newValue) {
         const descriptor = this.getField(fieldName);
         return descriptor ? convertType(descriptor.dataType, newValue) : newValue;
     }
+    /**
+     *
+     * Obtém todos os filtros de dados.
+     *
+     * @returns - Lista de filtros.
+     *
+    */
     getFilters() {
         let filters = undefined;
         this._filterProviders.forEach(p => {
@@ -62,15 +88,41 @@ export default class DataUnit {
         });
         return filters;
     }
+    /**
+     *
+     * Obtém a estrutura de ordenação das colunas dos dados.
+     *
+     * @returns - Lista dos ordenáveis por prioridade.
+     *
+    */
     getSort() {
         return this._sortingProvider ? this._sortingProvider.getSort(this._name) : undefined;
     }
+    /**
+     *
+     * Obtém chave única para identificação do FilterProvider.
+     *
+     * @param provider - Interface FilterProvider na qual será retornada uma chave correspondente.
+     *
+     * @returns - A chave do provider.
+     *
+    */
     getFielterProviderKey(provider) {
         if (provider.getKey) {
             return provider.getKey();
         }
         return StringUtils.hashCode(provider.getFilter.toString());
     }
+    /**
+     *
+     * Executa o carregamento dos registros.
+     *
+     * @param request - Dados da requisição para carregamento dos registros.
+     * @param executionCtx - Contexto de execução do carregamento dos registros do DataUnit.
+     *
+     * @returns - Registros do DataUnit.
+     *
+    */
     executeLoadData(request, executionCtx) {
         return new Promise((resolve, fail) => __awaiter(this, void 0, void 0, function* () {
             if (yield this.dispatchAction(Action.LOADING_DATA, request, executionCtx)) {
@@ -87,6 +139,15 @@ export default class DataUnit {
         }));
     }
     // Loaders
+    /**
+     *
+     * Carrega os metadados do DataUnit.
+     *
+     * @param executionCtx - Contexto de execução do carregamento dos metadados do DataUnit.
+     *
+     * @returns - Metadados carregados.
+     *
+    */
     loadMetadata(executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             if (yield this.dispatchAction(Action.LOADING_METADATA, undefined, executionCtx)) {
@@ -104,6 +165,16 @@ export default class DataUnit {
             }
         });
     }
+    /**
+     *
+     * Carrega os registros do DataUnit.
+     *
+     * @param quickFilter - Filtros a serem aplicados.
+     * @param executionCtx - Contexto de execução do carregamento dos registros.
+     *
+     * @returns - Registros requisitados.
+     *
+    */
     loadData(quickFilter, executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             const loadDataRequest = {
@@ -118,6 +189,16 @@ export default class DataUnit {
             return this.executeLoadData(loadDataRequest, executionCtx);
         });
     }
+    /**
+     *
+     * Alterna entre os registros por número de página.
+     *
+     * @param page - Número da página desejada.
+     * @param executionCtx - Contexto de execução do carregamento dos registros do DataUnit.
+     *
+     * @returns - Registros da página desejada.
+     *
+    */
     gotoPage(page, executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             let request = getCurrentRequest(this._stateManager);
@@ -132,16 +213,43 @@ export default class DataUnit {
             }
         });
     }
+    /**
+     *
+     * Vai para os registros da página seguinte.
+     *
+     * @param executionCtx - Contexto de execução do carregamento dos registros do DataUnit.
+     *
+     * @returns - Registros da página seguinte.
+     *
+    */
     nextPage(executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.gotoPage(getCurrentPage(this._stateManager) + 1, executionCtx);
         });
     }
+    /**
+     *
+     * Vai para os registros da página anterior.
+     *
+     * @param executionCtx - Contexto de execução do carregamento dos registros do DataUnit.
+     *
+     * @returns - Registros da página anterior.
+     *
+    */
     previousPage(executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.gotoPage(getCurrentPage(this._stateManager) - 1, executionCtx);
         });
     }
+    /**
+     *
+     * Salva o estado do registro do DataUnit.
+     *
+     * @param executionCtx - Contexto de execução da persistencia do registro do DataUnit.
+     *
+     * @returns - Resposta da solicitação.
+     *
+    */
     saveData(executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             const blockingWaitingChanges = getBlockingWaitingChanges(this._stateManager);
@@ -176,6 +284,15 @@ export default class DataUnit {
             return Promise.resolve();
         });
     }
+    /**
+     *
+     * Remove o registro selecionado.
+     *
+     * @param buffered - Se será utilizado buffer na solicitação.
+     *
+     * @returns - ID's dos registros removidos.
+     *
+    */
     removeSelectedRecords(buffered = false) {
         return __awaiter(this, void 0, void 0, function* () {
             const selection = getSelection(this._stateManager);
@@ -186,6 +303,18 @@ export default class DataUnit {
             return Promise.resolve(selection);
         });
     }
+    /**
+     *
+     * Efetua requisição para remoção dos registros.
+     *
+     * @param recordIds - Lista de IDs dos registros que serão removidos.
+     * @param cachedRecords - Dados dos registros que serão removidos.
+     * @param buffered - Se será utilizado buffer na solicitação.
+     * @param executionCtx - Contexto de execução da remoção do registro do DataUnit.
+     *
+     * @returns - ID's dos registros removidos.
+     *
+    */
     removeRecords(recordIds, cachedRecords, buffered = false, executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             if (recordIds) {
@@ -221,70 +350,216 @@ export default class DataUnit {
         });
     }
     // API
+    /**
+     *
+     * Obtém o valor do campo em seu formato/tipo correto a partir de uma string.
+     *
+     * @param fieldName - Nome do campo que terá o tipo identificado para conversão.
+     * @param value - Texto que será convertido de acordo com o tipo identificado no campo.
+     *
+     * @returns - Valor convertido ou ele mesmo.
+     *
+    */
     valueFromString(fieldName, value) {
         const descriptor = this.getField(fieldName);
         return descriptor ? convertType(descriptor.dataType, value) : value;
     }
+    /**
+     *
+     * Converte o valor informado para texto de acordo com o tipo do campo informado.
+     *
+     * @param fieldName - Nome do campo utilizado para buscar o tipo de dado com o padrão de conversão para string.
+     * @param value - Valor a ser convertido.
+     *
+     * @returns - Valor informado convertido.
+     *
+    */
     valueToString(fieldName, value) {
         const descriptor = this.getField(fieldName);
         return toString(descriptor === null || descriptor === void 0 ? void 0 : descriptor.dataType, value);
     }
+    /**
+     *
+     * Adiciona um interceptor correspondente a uma ação do DataUnit para fazer um processamento customizado.
+     *
+     * @param interceptor - Interceptor a ser adicionado.
+     *
+    */
     addInterceptor(interceptor) {
         this._interceptors.push(interceptor);
     }
+    /**
+     *
+     * Remove um interceptor da lista de interceptors.
+     *
+     * @param interceptor - Interceptor a ser removido.
+     *
+    */
     removeInterceptor(interceptor) {
         this._interceptors = this._interceptors.filter(i => i !== interceptor);
     }
+    /**
+     *
+     * Adiciona um FilterProvider.
+     *
+     * @param provider - FilterProvider que será adicionado.
+     *
+    */
     addFilterProvider(provider) {
         this._filterProviders.set(this.getFielterProviderKey(provider), provider);
     }
+    /**
+     *
+     * Obtém informações de paginação dos registros.
+     *
+     * @returns - Informações da paginação de registros.
+    */
     getPaginationInfo() {
         return getPaginationInfo(this._stateManager);
     }
+    /**
+     *
+     * Define a lógica de ordenação dos registros.
+     *
+     * @param provider - Objeto usado para definir a propriedade sortingProvider da instância da classe.
+     *
+     */
     set sortingProvider(provider) {
         this._sortingProvider = provider;
     }
+    /**
+     *
+     * Define a propriedade metadata da instância da classe com um novo valor e chama o método dispatchAction para notificar os observers da aplicação sobre a mudança.
+     *
+     */
     set metadata(md) {
         this.dispatchAction(Action.METADATA_LOADED, md, undefined);
     }
+    /**
+     *
+     * Obtém os metadados do DataUnit.
+     *
+     */
     get metadata() {
         return getMetadata(this._stateManager);
     }
+    /**
+     *
+     * Define a propriedade records da instância da classe com um novo valor e chama o método dispatchAction para notificar os observers da aplicação sobre a mudança.
+     *
+     */
     set records(r) {
         this.dispatchAction(Action.DATA_LOADED, { records: this.records }, undefined);
     }
+    /**
+     *
+     * Obtém todos os registros atuais.
+     *
+     * @returns - Todos os registros atuais.
+     *
+     */
     get records() {
         const records = getCurrentRecords(this._stateManager);
         return records ? Array.from(records.values()) : [];
     }
+    /**
+     *
+     * Define a quantidade de registros que será exibido por página.
+     *
+     * @param size - Quantidade de registros que será exibido por página.
+     *
+     */
     set pageSize(size) {
         this._pageSize = size;
     }
+    /**
+     *
+     * Obtém a quantidade de registros que está sendo exibido por página.
+     *
+     * @returns - Quantidade de registros exibidos por página.
+     *
+     */
     get pageSize() {
         return this._pageSize;
     }
+    /**
+     *
+     * Obtém os registros modificados e ainda não salvos no DataUnit.
+     *
+     * @returns - Lista dos registros em edição.
+     *
+     */
     getModifiedRecords() {
         const modified = getModifiedRecords(this._stateManager);
         return modified || [];
     }
+    /**
+     *
+     * Obtém metadados de um campo específico.
+     *
+     * @param fieldName - Identificador do campo.
+     *
+     * @returns - Metadados do campo informado.
+     */
     getField(fieldName) {
         return getField(this._stateManager, fieldName);
     }
+    /**
+     *
+     * Adiciona um novo registro.
+     *
+     * @param executionCtx - Contexto de execução da inserção do dado no DataUnit.
+     *
+    */
     addRecord(executionCtx) {
         this.dispatchAction(Action.RECORDS_ADDED, prepareAddedRecordId(this._stateManager, [{}]), executionCtx);
     }
+    /**
+     *
+     * Efetua a cópia do registro selecionado.
+     *
+     * @param executionCtx - Contexto de execução da cópia do dado do DataUnit.
+     *
+    */
     copySelected(executionCtx) {
         const selectedRecords = this.getSelectedRecords();
         if (selectedRecords) {
             this.dispatchAction(Action.RECORDS_COPIED, prepareCopiedRecord(this._stateManager, selectedRecords), executionCtx);
         }
     }
+    /**
+     *
+     * Retorna se a alteração no campo já foi concluída ou se ainda está incompleta.
+     *
+     * @param fieldName - Identificador do campo a ser verificado.
+     *
+     * @returns - Verdadeiro se ainda está pendente.
+     *
+    */
     waitingForChange(fieldName) {
         return isWaiting(this._stateManager, fieldName);
     }
+    /**
+     *
+     * Obtém valor do campo desejado.
+     *
+     * @param fieldName - Identificador do campo a ser buscado.
+     *
+     * @returns - Valor do campo.
+     *
+    */
     getFieldValue(fieldName) {
         return getFieldValue(this._stateManager, fieldName);
     }
+    /**
+     *
+     *  Insere valor no campo desejado.
+     *
+     * @param fieldName -Identificador do campo a ser modificado.
+     * @param newValue - Valor a ser inserido no campo.
+     * @param records - Indica quais registros foram afetados pela alteração no valor do campo.
+     *
+    */
     setFieldValue(fieldName, newValue, records) {
         const typedValue = this.validateAndTypeValue(fieldName, newValue);
         const currentValue = this.getFieldValue(fieldName);
@@ -292,31 +567,90 @@ export default class DataUnit {
             this.dispatchAction(Action.DATA_CHANGED, { [fieldName]: typedValue, records }, undefined);
         }
     }
+    /**
+     *
+     *  Inicia alteração no campo.
+     *
+     * @param fieldName - Identificador do campo a ser modificado.
+     * @param waitingChange - Informa que uma mudança irá iniciar.
+     *
+    */
     startChange(fieldName, waitingChange) {
         this.dispatchAction(Action.CHANGING_DATA, { [fieldName]: waitingChange }, undefined);
     }
+    /**
+     *
+     *  Cancela o início de uma alteração no campo.
+     *
+     * @param fieldName - Identificador do campo.
+     *
+    */
     cancelWaitingChange(fieldName) {
         this.dispatchAction(Action.WAITING_CHANGE_CANCELED, { fieldName }, undefined);
     }
+    /**
+     *
+     *  Obtém registros selecionados.
+     *
+     * @returns - Registros selecionados.
+     *
+    */
     getSelection() {
         return getSelection(this._stateManager);
     }
+    /**
+     *
+     * Seleciona múltiplos registros por ID.
+     *
+     * @param selection - IDs para selecionar.
+     * @param executionCtx - Contexto de execução da seleção dos registros do DataUnit.
+     *
+    */
     setSelection(selection, executionCtx) {
         this.dispatchAction(Action.SELECTION_CHANGED, { type: "id", selection }, executionCtx);
     }
+    /**
+     *
+     * Seleciona o primeiro registro.
+     *
+     * @param executionCtx - Contexto de execução da seleção do registro do DataUnit.
+     *
+    */
     selectFirst(executionCtx) {
         if (this.records.length > 0) {
             this.setSelectionByIndex([0], executionCtx);
         }
     }
+    /**
+     *
+     * Seleciona o último registro.
+     *
+     * @param executionCtx - Contexto de execução da seleção do registro do DataUnit.
+     *
+    */
     selectLast(executionCtx) {
         if (this.records.length > 0) {
             this.setSelectionByIndex([this.records.length - 1], executionCtx);
         }
     }
+    /**
+     *
+     * Seleciona múltiplos registros por índice.
+     *
+     * @param selection - Índices desejados para a seleção.
+     * @param executionCtx - Contexto de execução da seleção do registro do DataUnit.
+     *
+    */
     setSelectionByIndex(selection, executionCtx) {
         this.dispatchAction(Action.SELECTION_CHANGED, { type: "index", selection }, executionCtx);
     }
+    /**
+     *
+     * Obtém todos os registros selecionados.
+     *
+     * @returns - Lista de registros selecionados.
+     *
+    */
     getSelectedRecords() {
         const selection = this.getSelection();
         if (selection) {
@@ -324,6 +658,14 @@ export default class DataUnit {
             return currentRecords === null || currentRecords === void 0 ? void 0 : currentRecords.filter(r => selection.includes(r.__record__id__));
         }
     }
+    /**
+     *
+     * Seleciona o próximo registro.
+     *
+     * @param executionCtx - Contexto de execução da seleção do registro do DataUnit.
+     *
+     *
+    */
     nextRecord(executionCtx) {
         if (!hasNext(this._stateManager)) {
             if (hasMorePages(this._stateManager)) {
@@ -344,6 +686,13 @@ export default class DataUnit {
             this.dispatchAction(Action.NEXT_SELECTED, undefined, executionCtx);
         }
     }
+    /**
+     *
+     * Seleciona o registro anterior.
+     *
+     * @param executionCtx - Contexto de execução da seleção do registro do DataUnit.
+     *
+    */
     previousRecord(executionCtx) {
         if (!hasPrevious(this._stateManager)) {
             if (hasPreviousPages(this._stateManager)) {
@@ -364,15 +713,43 @@ export default class DataUnit {
             this.dispatchAction(Action.PREVIOUS_SELECTED, undefined, executionCtx);
         }
     }
+    /**
+     *
+     * Cancela edição do registro atual.
+     *
+     * @param executionCtx - Contexto de execução do cancelamento da seleção dos registros.
+     *
+    */
     cancelEdition(executionCtx) {
         this.dispatchAction(Action.EDITION_CANCELED, undefined, executionCtx);
     }
+    /**
+     *
+     * Retorna se existe algum tipo de alteração pendente.
+     *
+     * @returns Verdadeiro se existir alterações pendentes.
+     *
+    */
     isDirty() {
         return isDirty(this._stateManager);
     }
+    /**
+     *
+     * Retorna se existe algum registro em modo de edição.
+     *
+     * @returns Verdadeiro se existir alterações de registros pendentes.
+     *
+    */
     hasDirtyRecords() {
         return hasDirtyRecords(this._stateManager);
     }
+    /**
+     *
+     * Retorna se existir uma pagina seguinte a atual na paginação.
+     *
+     * @returns Verdadeiro se existir uma próxima página.
+     *
+    */
     hasNext() {
         let result = hasNext(this._stateManager);
         if (!result) {
@@ -380,6 +757,13 @@ export default class DataUnit {
         }
         return result;
     }
+    /**
+     *
+     * Retorna se existe uma página anterior a atual na paginação.
+     *
+     * @returns Verdadeiro se existir uma página anterior.
+     *
+    */
     hasPrevious() {
         let result = hasPrevious(this._stateManager);
         if (!result) {
@@ -387,22 +771,69 @@ export default class DataUnit {
         }
         return result;
     }
+    /**
+     *
+     * Retorna se a informação do estado anterior está salva, permitindo desfazer a ação.
+     *
+     * @returns Verdadeiro se for possível desfazer a ação.
+     *
+    */
     canUndo() {
         return canUndo(this._stateManager);
     }
+    /**
+     *
+     * Retorna se a informação do estado futuro está salva, permitindo refazer a ação.
+     *
+     * @returns Verdadeiro se for possível refazer a ação.
+     *
+    */
     canRedo() {
         return canRedo(this._stateManager);
     }
+    /**
+     *
+     * Desfaz a última ação.
+     *
+     * @param executionCtx - Contexto de execução de desfazer a última ação.
+     *
+     *
+    */
     undo(executionCtx) {
         this.dispatchAction(Action.CHANGE_UNDONE, undefined, executionCtx);
     }
+    /**
+     *
+     * Refaz a última ação.
+     *
+     * @param executionCtx - Contexto de execução de refazer a última ação.
+     *
+    */
     redo(executionCtx) {
         this.dispatchAction(Action.CHANGE_REDONE, undefined, executionCtx);
     }
+    /**
+     *
+     * Obtém a representação textual do DataUnit, nesse caso, o nome do DataUnit.
+     *
+     * @returns - Valor contido na propriedade name.
+     *
+    */
     toString() {
         return this.name;
     }
     // Actions / State manager
+    /**
+     *
+     * Lança ação do DataUnit para que sejam processadas.
+     *
+     * @param actionType - Tipo de ação que será executada.
+     * @param payload - Dados que serão processados na ação.
+     * @param executionCtx - Contexto de execução de lançar a ação que será executada.
+     *
+     * @returns - Verdadeiro se ação iniciada.
+     *
+    */
     dispatchAction(actionType, payload, executionCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             return new Promise((resolve) => __awaiter(this, void 0, void 0, function* () {
@@ -426,6 +857,16 @@ export default class DataUnit {
             }));
         });
     }
+    /**
+     *
+     * Notifica os interceptors de que uma ação foi executada, para que cada interceptor possa fazer sua respectiva tratativa dos dados.
+     *
+     * @param action - Ação que foi executada.
+     * @param interceptors - Interceptors que serão notificados.
+     *
+     * @returns - Ação executada no DataUnit.
+     *
+    */
     intercept(action, interceptors) {
         return __awaiter(this, void 0, void 0, function* () {
             return new Promise((resolve) => __awaiter(this, void 0, void 0, function* () {
@@ -437,6 +878,13 @@ export default class DataUnit {
             }));
         });
     }
+    /**
+     *
+     * Processa as ações no DataUnit e notifica os observers.
+     *
+     * @param action - Ações em execução no DataUnit.
+     *
+    */
     doDispatchAction(action) {
         this._stateManager.process(action);
         this._observers.forEach(f => {
@@ -452,12 +900,34 @@ export default class DataUnit {
             }
         });
     }
+    /**
+     *
+     * Adiciona um novo observer no DataUnit.
+     * Ela vai ser chamada sempre que uma ação for despachada (dispatchAction()).
+     *
+     * @param observer - Função que recebe como parâmetro as ações que serão monitoradas.
+     *
+    */
     subscribe(observer) {
         this._observers.push(observer);
     }
+    /**
+     *
+     * Remove um observer existente.
+     *
+     * @param observer - Observer que se deseja remover.
+     *
+    */
     unsubscribe(observer) {
         this._observers = this._observers.filter(f => f !== observer);
     }
+    /**
+     *
+     * Recarrega registro selecionado com dados atualizados do servidor.
+     *
+     * @returns - Dados atualizados do registro selecionado.
+     *
+    */
     reloadCurrentRecord() {
         return new Promise((resolve, fail) => __awaiter(this, void 0, void 0, function* () {
             const selection = this.getSelection();
@@ -482,26 +952,64 @@ export var ChangeOperation;
     ChangeOperation["UPDATE"] = "UPDATE";
     ChangeOperation["DELETE"] = "DELETE";
 })(ChangeOperation || (ChangeOperation = {}));
+/***
+ * `Change`: Dados que representam uma alteração.
+ */
 export class Change {
-    constructor(dataUnit, record, updates, operation, sourceId) {
-        this.dataUnit = dataUnit;
+    constructor(DataUnit, record, updates, operation, sourceId) {
+        this.DataUnit = DataUnit;
         this.record = record;
         this.sourceId = sourceId;
         this.updatingFields = updates;
         this._operation = operation;
     }
+    /**
+     *
+     * Obtém o tipo de operação que está sendo realizada.
+     *
+     * @returns - Ação que está sendo executada.
+     *
+     */
     get operation() {
         return this._operation.toString();
     }
+    /**
+     *
+     * Retorna se o DataUnit está em uma operação de inserção.
+     *
+     * @returns - Verdadeiro se a operação for de inserção.
+     *
+     */
     isInsert() {
         return this._operation === ChangeOperation.INSERT;
     }
+    /**
+     *
+     * Retorna se o DataUnit está em uma operação de cópia.
+     *
+     * @returns - Verdadeiro se a operação for de cópia.
+     *
+     */
     isCopy() {
         return this._operation === ChangeOperation.COPY;
     }
+    /**
+     *
+     * Retorna se o DataUnit está em uma operação de deleção.
+     *
+     * @returns - Verdadeiro se a operação for de deleção.
+     *
+     */
     isDelete() {
         return this._operation === ChangeOperation.DELETE;
     }
+    /**
+     *
+     * Retorna se o DataUnit está em uma operação de atualização.
+     *
+     * @returns - Verdadeiro se a operação for de atualização.
+     *
+     */
     isUpdate() {
         return this._operation === ChangeOperation.UPDATE;
     }