DesignLiquido · leonelsanchesdasilva · Jul 5, 2024 · Jul 4, 2024
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # lmht-js
 
-Biblioteca de transformação de documentos [LMHT](https://github.com/DesignLiquido/LMHT) para HTML para JavaScript.
+Biblioteca de transformação de documentos [LMHT](https://github.com/DesignLiquido/LMHT) para HTML, para JavaScript e TypeScript.
 
 <p align="center">
     <a href="https://github.com/DesignLiquido/lmht-js/issues" target="_blank">
@@ -24,7 +24,67 @@ Biblioteca de transformação de documentos [LMHT](https://github.com/DesignLiqu
 
 ## Formas de uso
 
-### Atual, versão 0.3.0 em diante
+### Versão 0.5.0 ou superiores
+
+```js
+import { ConversorLmht } from "@designliquido/lmht-js";
+
+const conversorLmht = new ConversorLmht();
+// Ou
+const resultado = await conversorLmht.converterPorArquivo("meu-arquivo.lmht");
+console.log(resultado);
+
+// Ou
+conversorLmht.converterPorArquivo("meu-arquivo.lmht").then(resultado => {
+    console.log(resultado);
+});
+```
+
+```js
+import { ConversorLmht } from "@designliquido/lmht-js";
+
+const conversorLmht = new ConversorLmht();
+// Ou
+const resultado = await conversorLmht.converterPorTexto("<lmht><cabeca><titulo>Teste</titulo></cabeca><corpo>Teste</corpo></lmht>");
+console.log(resultado); // Resultado: <html><head><title>Teste</title></head><body>Teste</body></html>
+
+// Ou
+conversorLmht.converterPorTexto("<lmht><cabeca><titulo>Teste</titulo></cabeca><corpo>Teste</corpo></lmht>").then(resultado => {
+    console.log(resultado); // Resultado: <html><head><title>Teste</title></head><body>Teste</body></html>
+});
+```
+
+```js
+import { ConversorHtml } from "@designliquido/lmht-js";
+
+const conversorHtml = new ConversorHtml();
+// Ou
+const resultado = await conversorHtml.converterPorArquivo("meu-arquivo.html");
+console.log(resultado);
+
+// Ou
+conversorHtml.converterPorArquivo("meu-arquivo.html").then(resultado => {
+    console.log(resultado);
+});
+```
+
+```js
+import { ConversorHtml } from "@designliquido/lmht-js";
+
+const conversorHtml = new ConversorHtml();
+// Ou
+const resultado = await conversorHtml.converterPorTexto("<html><head><title>Teste</title></head><body>Teste</body></html>");
+console.log(resultado); // Resultado: <lmht><cabeca><titulo>Teste</titulo></cabeca><corpo>Teste</corpo></lmht>
+
+// Ou
+conversorHtml.converterPorTexto("<html><head><title>Teste</title></head><body>Teste</body></html>").then(resultado => {
+    console.log(resultado); // Resultado: <lmht><cabeca><titulo>Teste</titulo></cabeca><corpo>Teste</corpo></lmht>
+});
+```
+
+### Versão 0.3.0 até versão 0.4.9
+
+Os métodos de conversão são síncronos:
 
 ```js
 import { ConversorLmht } from "@designliquido/lmht-js";
@@ -60,7 +120,7 @@ console.log(resultado); // Resultado: <lmht><cabeca><titulo>Teste</titulo></cabe
 
 ### Até a versão 0.2.0
 
-Em versões anteriores, os métodos de conversão eram assíncronos.
+Os métodos de conversão são assíncronos.
 
 ```js
 import { ConversorLmht } from "@designliquido/lmht-js";
@@ -88,16 +148,22 @@ conversorHtml.converterPorArquivo("meu-arquivo.lmht").then(resultado => {
 git submodule update --init --recursive --remote
 ```
 
+## Versões 0.3.0 até 0.4.9, usando `xslt-processor`, e mudanças na versão 0.5.0
+
+Na versão 0.3.0, tomamos a decisão de mudar para a biblioteca [`xslt-processor`](https://github.com/DesignLiquido/xslt-processor), 100% em código aberto, licença MIT, e mantida pela Design Líquido. Não apenas os _bugs_ que tínhamos com a biblioteca anterior, `saxon-js`, são totalmente evitados como também a implementação de `xslt-processor` privilegia o projeto de LMHT.
+
+Isso fez com que os métodos se tornassem síncronos. Depois da versão 3.0.0 de `xslt-processor`, em que o comando `<xsl:include>` foi implementado, o processamento de transformações XSLT passou a ser novamente assíncrono. O comando `<xsl:include>` exige um acesso a um sistema de arquivos ou um recurso na internet, o que pede para que todo o processo seja assíncrono. Para esta biblioteca, os comandos de conversão voltam a ser assíncronos na versão 0.5.0.
+
 ## Versão 0.2.0 e `saxon-js`
 
 Até a versão 0.2.0, usávamos a biblioteca [`saxon-js`](https://www.npmjs.com/package/saxon-js). Essa biblioteca tornou-se um problema por alguns motivos:
 
-- Documentação incompleta e de baixa qualidade: https://www.saxonica.com/saxon-js/documentation2/index.html;
+- Documentação incompleta, em inglês e de baixa qualidade: https://www.saxonica.com/saxon-js/documentation2/index.html;
 - [Apesar de ter uma licença gratuita](https://www.saxonica.com/saxon-js/documentation2/index.html#!conditions/public-license), os fontes não são abertos;
-- Escrita em JavaScript puro e tipagem fraca;
-- Não funciona se usada em uma extensão do Visual Studio Code, que em teoria é Node.js, mas algo acontece ao importarmos a dependência e um erro aparece.
+- Escrita em JavaScript puro e tipagem fraca, além de ter uma parte compilada em C;
+- Não funciona se usada em uma extensão do Visual Studio Code, que em teoria é Node.js, mas algo acontece ao importarmos a dependência e um erro estranho aparece.
 
-Mantemos o suporte a versões anteriores por questões de retrocompatibilidade. A biblioteca atual usada para processamento XSLT é a [`xslt-processor`](https://github.com/DesignLiquido/xslt-processor), de código aberto e também mantida pela Design Líquido.
+Mantemos o suporte a versões anteriores por questões de retrocompatibilidade. 
 
 ### Especificação e arquivos `.sef.json`
 

diff --git a/conversor-comum.ts b/conversor-comum.ts
@@ -19,10 +19,10 @@
      * @param caminhoArquivo O caminho do arquivo. Deve ser absoluto.
      * @returns O resultado da transformação de um formato para outro.
      */
-    converterPorArquivo(caminhoArquivo: string): string {
+    async converterPorArquivo(caminhoArquivo: string): Promise<string> {
         const textoArquivo = sistemaArquivos.readFileSync(caminhoArquivo).toString();
         const xml = this.avaliadorXml.xmlParse(textoArquivo);
-        return this.processadorXslt.xsltProcess(xml, this.especificacao);
+        return await this.processadorXslt.xsltProcess(xml, this.especificacao);
     }
 
     /**
@@ -32,12 +32,12 @@
      * @param caminhoArquivo O caminho do arquivo. Deve ser absoluto.
      * @returns O resultado da transformação de um formato para outro.
      */
-    converterPorTexto(texto: string) {
+    async converterPorTexto(texto: string): Promise<string> {
         if (!texto) {
-            return "";
+            return Promise.resolve("");
         }
 
         const xml = this.avaliadorXml.xmlParse(texto);
-        return this.processadorXslt.xsltProcess(xml, this.especificacao);
+        return await this.processadorXslt.xsltProcess(xml, this.especificacao);
     }
 }
diff --git a/especificacao b/especificacao
diff --git a/package.json b/package.json
@@ -9,10 +9,10 @@
   },
   "scripts": {
     "copiar-arquivos": "yarn copy-files-from-to",
-    "empacotar": "rimraf ./dist && tsc && yarn copiar-arquivos",
+    "empacotar": "yarn rimraf ./dist && tsc && yarn copiar-arquivos",
     "publicar-npm": "npm publish ./dist --access public",
     "testes-unitarios": "jest --coverage",
-    "testes-unitarios:insignias": "jest-coverage-badges --output ./recursos/imagens"
+    "testes-unitarios:insignias": "yarn jest-coverage-badges --output ./recursos/imagens"
   },
   "author": "Leonel Sanches da Silva",
   "license": "MIT",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "jsdom": "^21.1.1",
-    "xslt-processor": "^3.0.0"
+    "xslt-processor": "^3.0.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.4",

diff --git a/testes/conversor-html.test.ts b/testes/conversor-html.test.ts
@@ -7,17 +7,17 @@
         conversorHtml = new ConversorHtml();
     });
 
-    it("Vazio", () => {
-        const resultado = conversorHtml.converterPorTexto("");
+    it("Vazio", async () => {
+        const resultado = await conversorHtml.converterPorTexto("");
         expect(resultado).toBe("");
     });
 
-    it("Trivial", () => {
-        const resultado = conversorHtml.converterPorTexto("<html></html>");
+    it("Trivial", async () => {
+        const resultado = await conversorHtml.converterPorTexto("<html></html>");
         expect(resultado).toBeTruthy();
     });
 
-    it("Cabeça e corpo", () => {
+    it("Cabeça e corpo", async () => {
         const html = `<!DOCTYPE html>
         <html>
         <head>
@@ -47,7 +47,7 @@
             `</corpo>`+
             `</lmht>`;
 
-        const resultado = conversorHtml.converterPorTexto(html);
+        const resultado = await conversorHtml.converterPorTexto(html);
         expect(resultado).toBe(resultadoEsperadoLmht);
     });
 });
diff --git a/testes/conversor-lmht.test.ts b/testes/conversor-lmht.test.ts
@@ -7,13 +7,13 @@
         conversorLmht = new ConversorLmht();
     });
 
-    it("Vazio", () => {
-        const resultado = conversorLmht.converterPorTexto("");
+    it("Vazio", async () => {
+        const resultado = await conversorLmht.converterPorTexto("");
         expect(resultado).toBe("");
     });
 
-    it("Trivial", () => {
-        const resultado = conversorLmht.converterPorTexto("<lmht></lmht>");
+    it("Trivial", async () => {
+        const resultado = await conversorLmht.converterPorTexto("<lmht></lmht>");
         expect(resultado).toBeTruthy();
     });
 });
diff --git a/yarn.lock b/yarn.lock
@@ -4880,10 +4880,10 @@ xregexp@2.0.0:
   resolved "https://registry.yarnpkg.com/xregexp/-/xregexp-2.0.0.tgz#52a63e56ca0b84a7f3a5f3d61872f126ad7a5943"
   integrity sha512-xl/50/Cf32VsGq/1R8jJE5ajH1yMCQkpmoS10QbFZWl2Oor4H0Me64Pu2yxvsRWK3m6soJbmGfzSR7BYmDcWAA==
 
-xslt-processor@^3.0.0:
-  version "3.0.0"
-  resolved "https://registry.yarnpkg.com/xslt-processor/-/xslt-processor-3.0.0.tgz#93fe260700ac3d4bde6fc3e342bfce54b88761ff"
-  integrity sha512-gqYOwg8ZZ8e0iGxR/C41Qc4m9pJoQonrxGzuUoSLiX5Io0qGzQxyh1XXAq2kbHv8hq38QkfrhDWaBdwwLi8+kQ==
+xslt-processor@^3.0.1:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/xslt-processor/-/xslt-processor-3.0.1.tgz#6f133a8974a1cc345b7bdefd57e48f25ba352bfd"
+  integrity sha512-XELmhWnCFHfsfAhl0jKetcVIzSnZt90lOcPPCzoEc4+ZqfXGXxddo7q93bc0piDKLKF8EP2OCKc0EVnPwFd2aA==
   dependencies:
     he "^1.2.0"
     node-fetch cjs