w-html2docx 1.0.28 → 1.0.29

package/scripts/install.mjs

@@ -1,29 +1,25 @@
-import path from 'path'
-import { fileURLToPath } from 'url'
-import downloadFiles from '../src/downloadFiles.mjs'
-
-
-async function init() {
-
-    //check
-    let __dirname = path.dirname(fileURLToPath(import.meta.url))
-    if (!__dirname.includes('node_modules')) {
-        return //非位於node_modules, 代表套件本身
-    }
-
-    //fdSrv, postinstall時cwd=套件自身在node_modules內的目錄
-    let fdSrv = path.resolve()
-
-    //fdBase, npm i後觸發安裝時, 工作路徑是位於套件/專案內
-    let fdBase = `${fdSrv}/src/`
-
-    //downloadFiles
-    await downloadFiles(fdBase)
-
-}
-init()
-    .catch((err) => {
-        console.log(err)
-    })
-
-//node scripts/install.mjs
+import path from 'path'
+import { fileURLToPath } from 'url'
+import autoDownloadFiles from '../src/autoDownloadFiles.mjs'
+
+
+async function init() {
+
+    //check
+    let __dirname = path.dirname(fileURLToPath(import.meta.url))
+    if (!__dirname.includes('node_modules')) {
+        return //非位於node_modules, 代表套件本身
+    }
+
+    //autoDownloadFiles, postinstall時cwd=套件自身在node_modules內的目錄, 其依序查找<cwd>/src/與<cwd>/node_modules/w-html2docx/src/, 皆無則下載至<cwd>/src/,
+    //與執行期缺檔時之自動下載為同一套邏輯, 不另行組路徑; 已存在(重新安裝)則不重複下載
+    let { fpExe } = await autoDownloadFiles()
+    console.log(`htmlToDocx.exe is ready at [${fpExe}]`)
+
+}
+init()
+    .catch((err) => {
+        console.log(err)
+    })
+
+//node scripts/install.mjs

package/src/WHtml2docx.mjs

@@ -1,169 +1,203 @@
-import path from 'path'
-import process from 'process'
-import get from 'lodash-es/get.js'
-import isestr from 'wsemi/src/isestr.mjs'
-import isearr from 'wsemi/src/isearr.mjs'
-import ispnum from 'wsemi/src/ispnum.mjs'
-import cdbl from 'wsemi/src/cdbl.mjs'
-import str2b64 from 'wsemi/src/str2b64.mjs'
-import execProcess from 'wsemi/src/execProcess.mjs'
-import fsIsFile from 'wsemi/src/fsIsFile.mjs'
-import autoDownloadFiles from './autoDownloadFiles.mjs'
-
-
-let fdSrv = path.resolve()
-
-
-function isWindows() {
-    return process.platform === 'win32'
-}
-
-
-/**
- * Html檔轉Docx檔
- *
- * @param {String} fpInHtml 輸入來源Html檔位置字串
- * @param {String} fpOutDocx 輸入轉出Docx檔位置字串
- * @param {Object} [opt={}] 輸入設定物件，預設{}
- * @param {String} [opt.fpInTemp='./src/tmp.docx'] 輸入Docx模板檔案位置字串，預設'./src/tmp.docx'
- * @param {Array|String} [opt.fontFamilies=['標楷體','Times New Roman']] 輸入轉出Docx時強制更改字型陣列或字串，陣列順序為變更順序，若有要覆寫字型得放後面。預設['標楷體','Times New Roman']
- * @param {String} [opt.imgRatioWidthMax=1] 輸入圖片最大寬度比例，值介於0至1，預設1
- * @param {String} [opt.imgRatioHeightMax=1] 輸入圖片最大高度比例，值介於0至1，預設1
- * @returns {Promise} 回傳Promise，resolve回傳成功訊息，reject回傳錯誤訊息
- * @example
- *
- * import w from 'wsemi'
- * import WHtml2docx from './src/WHtml2docx.mjs'
- * //import WHtml2docx from 'w-html2docx/src/WHtml2docx.mjs'
- * //import WHtml2docx from 'w-html2docx'
- *
- * async function test() {
- *
- *     let fpIn = `./test/ztmp.html`
- *     let fpOut = `./test/ztmp.docx`
- *     let opt = {
- *         imgRatioWidthMax: 0.5,
- *     }
- *
- *     let r = await WHtml2docx(fpIn, fpOut, opt)
- *     console.log(r)
- *     // => ok
- *
- *     w.fsDeleteFile(fpOut)
- *
- * }
- * test()
- *     .catch((err) => {
- *         console.log('catch', err)
- *     })
- *
- */
-async function WHtml2docx(fpInHtml, fpOutDocx, opt = {}) {
-    let errTemp = null
-
-    //isWindows
-    if (!isWindows()) {
-        return Promise.reject('operating system is not windows')
-    }
-
-    //check
-    if (!fsIsFile(fpInHtml)) {
-        return Promise.reject(`fpInHtml[${fpInHtml}] does not exist`)
-    }
-
-    //fontFamilies
-    let fontFamilies = get(opt, 'fontFamilies')
-    if (isestr(fontFamilies)) {
-        fontFamilies = [fontFamilies]
-    }
-    if (!isearr(fontFamilies)) {
-        fontFamilies = ['標楷體', 'Times New Roman']
-    }
-
-    //imgRatioWidthMax
-    let imgRatioWidthMax = get(opt, 'imgRatioWidthMax')
-    if (!ispnum(imgRatioWidthMax)) {
-        imgRatioWidthMax = 1
-    }
-    imgRatioWidthMax = cdbl(imgRatioWidthMax)
-
-    //imgRatioHeightMax
-    let imgRatioHeightMax = get(opt, 'imgRatioHeightMax')
-    if (!ispnum(imgRatioHeightMax)) {
-        imgRatioHeightMax = 1
-    }
-    imgRatioHeightMax = cdbl(imgRatioHeightMax)
-
-    //fpInTemp
-    let fpInTemp = get(opt, 'fpInTemp')
-    if (!isestr(fpInTemp)) {
-
-        //fnTmp
-        let fnTmp = `tmp.docx`
-
-        //fpInTemp
-        if (true) {
-            let fpTmpSrc = `${fdSrv}/src/${fnTmp}`
-            let fpTmpNM = `${fdSrv}/node_modules/w-html2docx/src/${fnTmp}`
-            if (fsIsFile(fpTmpSrc)) {
-                fpInTemp = fpTmpSrc
-            }
-            else if (fsIsFile(fpTmpNM)) {
-                fpInTemp = fpTmpNM
-            }
-            else {
-                return Promise.reject(`can not find folder for ${fnTmp}`)
-            }
-
-        }
-
-    }
-
-    //轉絕對路徑
-    fpInHtml = path.resolve(fpInHtml)
-    fpInTemp = path.resolve(fpInTemp)
-    fpOutDocx = path.resolve(fpOutDocx)
-
-    //prog, 自動定位htmlToDocx.exe, 無檔案(安裝時npm封鎖scripts致postinstall未執行)則自動下載
-    let { fpExe } = await autoDownloadFiles()
-    let prog = fpExe
-    // console.log('prog', prog)
-
-    //inp
-    let inp = {
-        fpInSrc: fpInHtml,
-        fpInTemp,
-        fpOut: fpOutDocx,
-        fontFamilies: ['標楷體', 'Times New Roman'],
-        imgRatioWidthMax,
-        imgRatioHeightMax,
-    }
-    // console.log('inp', inp)
-
-    //input to b64
-    let cInput = JSON.stringify(inp)
-    let b64Input = str2b64(cInput)
-    // console.log('b64Input', b64Input)
-
-    //execProcess
-    await execProcess(prog, b64Input)
-        .catch((err) => {
-            console.log('execProcess catch', err)
-            errTemp = err.toString()
-        })
-
-    //check
-    if (errTemp) {
-        return Promise.reject(errTemp)
-    }
-
-    // //check
-    // if (!isestr(output)) {
-    //     return Promise.reject(`output[${cstr(output)}] is not an effective string`)
-    // }
-
-    return 'ok'
-}
-
-
-export default WHtml2docx
+import fs from 'fs'
+import path from 'path'
+import process from 'process'
+import get from 'lodash-es/get.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import ispnum from 'wsemi/src/ispnum.mjs'
+import cdbl from 'wsemi/src/cdbl.mjs'
+import str2b64 from 'wsemi/src/str2b64.mjs'
+import execProcess from 'wsemi/src/execProcess.mjs'
+import fsIsFile from 'wsemi/src/fsIsFile.mjs'
+import fsIsFolder from 'wsemi/src/fsIsFolder.mjs'
+import fsCreateFolder from 'wsemi/src/fsCreateFolder.mjs'
+import autoDownloadFiles from './autoDownloadFiles.mjs'
+
+
+let fdSrv = path.resolve()
+
+
+function isWindows() {
+    return process.platform === 'win32'
+}
+
+
+/**
+ * Html檔轉Docx檔
+ *
+ * 轉檔由套件內之htmlToDocx.exe調用本機Microsoft Word(win32com)完成，故須於Windows且已安裝Word之機器執行。htmlToDocx.exe若不存在(安裝時npm封鎖scripts致postinstall未執行)會於轉檔當下自動下載，下載失敗則reject並帶網址與落點。
+ * 轉檔器內部失敗(Word未安裝、模板無法開啟、另存失敗等)一律reject並帶轉檔器回報之原因；resolve前另確認輸出檔已產生且非空。輸出資料夾不存在時自動建立
+ *
+ * @param {String} fpInHtml 輸入來源Html檔位置字串
+ * @param {String} fpOutDocx 輸入轉出Docx檔位置字串
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.fpInTemp=''] 輸入Docx模板檔案位置字串，有給時須存在否則reject；未給時依序取模組載入當下工作路徑之`./src/tmp.docx`或`./node_modules/w-html2docx/src/tmp.docx`(套件內建模板)，預設''
+ * @param {Array|String} [opt.fontFamilies=['標楷體','Times New Roman']] 輸入轉出Docx時強制更改字型陣列或字串，陣列順序為變更順序，若有要覆寫字型得放後面。預設['標楷體','Times New Roman']
+ * @param {Number} [opt.imgRatioWidthMax=1] 輸入圖片最大寬度比例，值介於0至1，預設1
+ * @param {Number} [opt.imgRatioHeightMax=1] 輸入圖片最大高度比例，值介於0至1，預設1
+ * @param {Number} [opt.timeout=null] 輸入轉檔逾時毫秒數，預設null表示不限制；逾時時強制關閉轉檔器並reject回傳逾時訊息，惟由轉檔器經COM啟動之Word不在其程序樹內，不會一併被關閉
+ * @returns {Promise} 回傳Promise，resolve回傳'ok'，reject回傳錯誤訊息字串
+ * @example
+ *
+ * import w from 'wsemi'
+ * import WHtml2docx from './src/WHtml2docx.mjs'
+ * //import WHtml2docx from 'w-html2docx/src/WHtml2docx.mjs'
+ * //import WHtml2docx from 'w-html2docx'
+ *
+ * async function test() {
+ *
+ *     let fpIn = `./test/ztmp.html`
+ *     let fpOut = `./test/ztmp.docx`
+ *     let opt = {
+ *         imgRatioWidthMax: 0.5,
+ *     }
+ *
+ *     let r = await WHtml2docx(fpIn, fpOut, opt)
+ *     console.log(r)
+ *     // => ok
+ *
+ *     w.fsDeleteFile(fpOut)
+ *
+ * }
+ * test()
+ *     .catch((err) => {
+ *         console.log('catch', err)
+ *     })
+ *
+ */
+async function WHtml2docx(fpInHtml, fpOutDocx, opt = {}) {
+    let errTemp = null
+
+    //isWindows
+    if (!isWindows()) {
+        return Promise.reject('operating system is not windows')
+    }
+
+    //check
+    if (!fsIsFile(fpInHtml)) {
+        return Promise.reject(`fpInHtml[${fpInHtml}] does not exist`)
+    }
+
+    //fontFamilies
+    let fontFamilies = get(opt, 'fontFamilies')
+    if (isestr(fontFamilies)) {
+        fontFamilies = [fontFamilies]
+    }
+    if (!isearr(fontFamilies)) {
+        fontFamilies = ['標楷體', 'Times New Roman']
+    }
+
+    //imgRatioWidthMax
+    let imgRatioWidthMax = get(opt, 'imgRatioWidthMax')
+    if (!ispnum(imgRatioWidthMax)) {
+        imgRatioWidthMax = 1
+    }
+    imgRatioWidthMax = cdbl(imgRatioWidthMax)
+
+    //imgRatioHeightMax
+    let imgRatioHeightMax = get(opt, 'imgRatioHeightMax')
+    if (!ispnum(imgRatioHeightMax)) {
+        imgRatioHeightMax = 1
+    }
+    imgRatioHeightMax = cdbl(imgRatioHeightMax)
+
+    //timeout
+    let timeout = get(opt, 'timeout')
+    if (!ispnum(timeout)) {
+        timeout = null
+    }
+
+    //fpInTemp
+    let fpInTemp = get(opt, 'fpInTemp')
+    if (isestr(fpInTemp)) {
+
+        //check, 呼叫端有提供時須存在, 與fpInHtml之檢查對稱; 否則會由轉檔器於開啟模板時失敗, 訊息為Word之COM錯誤而看不出是路徑問題
+        if (!fsIsFile(fpInTemp)) {
+            return Promise.reject(`fpInTemp[${fpInTemp}] does not exist`)
+        }
+
+    }
+    else {
+
+        //fnTmp
+        let fnTmp = `tmp.docx`
+
+        //fpInTemp
+        if (true) {
+            let fpTmpSrc = `${fdSrv}/src/${fnTmp}`
+            let fpTmpNM = `${fdSrv}/node_modules/w-html2docx/src/${fnTmp}`
+            if (fsIsFile(fpTmpSrc)) {
+                fpInTemp = fpTmpSrc
+            }
+            else if (fsIsFile(fpTmpNM)) {
+                fpInTemp = fpTmpNM
+            }
+            else {
+                return Promise.reject(`can not find folder for ${fnTmp}`)
+            }
+
+        }
+
+    }
+
+    //轉絕對路徑
+    fpInHtml = path.resolve(fpInHtml)
+    fpInTemp = path.resolve(fpInTemp)
+    fpOutDocx = path.resolve(fpOutDocx)
+
+    //fdOutDocx, 輸出資料夾不存在時自動建立, 否則Word另存時失敗
+    let fdOutDocx = path.dirname(fpOutDocx)
+    if (!fsIsFolder(fdOutDocx)) {
+        fsCreateFolder(fdOutDocx)
+        if (!fsIsFolder(fdOutDocx)) {
+            return Promise.reject(`can not create folder[${fdOutDocx}] for fpOutDocx`)
+        }
+    }
+
+    //prog, 自動定位htmlToDocx.exe, 無檔案(安裝時npm封鎖scripts致postinstall未執行)則自動下載
+    let { fpExe } = await autoDownloadFiles()
+    let prog = fpExe
+    // console.log('prog', prog)
+
+    //inp
+    let inp = {
+        fpInSrc: fpInHtml,
+        fpInTemp,
+        fpOut: fpOutDocx,
+        fontFamilies,
+        imgRatioWidthMax,
+        imgRatioHeightMax,
+    }
+    // console.log('inp', inp)
+
+    //input to b64
+    let cInput = JSON.stringify(inp)
+    let b64Input = str2b64(cInput)
+    // console.log('b64Input', b64Input)
+
+    //execProcess, 轉檔器成功時印success且離開碼0, 失敗時印error: 原因且離開碼1, 故離開碼非0即reject並帶其輸出
+    //  codeCmd給auto: 現行轉檔器以utf-8輸出, 尚未重新下載之舊版轉檔器以系統字碼頁(中文Windows為cp950)輸出, auto先以utf-8嚴格解碼, 遇非utf-8位元組改用系統字碼頁, 兩者皆可正確解碼; 轉檔器損毀時bootloader之ANSI訊息亦同
+    let output = ''
+    await execProcess(prog, b64Input, { codeCmd: 'auto', timeout })
+        .then((r) => {
+            output = r
+        })
+        .catch((err) => {
+            errTemp = String(err).trim()
+        })
+
+    //check
+    if (errTemp) {
+        return Promise.reject(errTemp)
+    }
+
+    //check, 轉檔器回報成功仍須確認輸出檔存在且非空: 舊版轉檔器於Word未安裝、模板無法開啟等失敗時仍以離開碼0結束, 只在輸出印出error
+    if (!fsIsFile(fpOutDocx) || fs.statSync(fpOutDocx).size === 0) {
+        return Promise.reject(`fpOutDocx[${fpOutDocx}] was not generated: ${output.trim()}`)
+    }
+
+    return 'ok'
+}
+
+
+export default WHtml2docx

package/src/autoDownloadFiles.mjs

@@ -18,6 +18,9 @@ let pmDownload = null
  * 依序偵測當前工作路徑的src/與node_modules/w-html2docx/src/，皆無htmlToDocx.exe時，
  * 代表安裝時npm封鎖scripts致postinstall未執行，故自動調用downloadFiles重新下載
  *
+ * 下載係先寫入暫存檔`htmlToDocx.exe.download`，完成後才改名為htmlToDocx.exe，故下載中途斷線或程序被終止時不會留下截斷之htmlToDocx.exe，下次呼叫會重新下載；
+ * 下載失敗(斷網、代理不可達、非2xx回應、中途斷線)時reject字串`failed to download url[網址] to file[落點]: 原因`
+ *
  * 供w-html2docx自身與其他依賴w-html2docx的套件調用，無須各自實作偵測與下載邏輯
  *
  * 因htmlToDocx.exe只能用於Windows作業系統，故調用前須自行檢核作業系統
@@ -66,12 +69,11 @@ async function autoDownloadFiles() {
         //併發呼叫共用同一個下載Promise, 避免重複下載
         if (pmDownload === null) {
             pmDownload = downloadFiles(fdBaseDL)
-                .catch((err) => {
+                .finally(() => {
 
-                    //下載失敗歸零, 使下次呼叫可重試下載
+                    //下載結束(成敗皆然)歸零, 使下次呼叫重新依檔案是否存在判定; 若只於失敗時歸零, 下載成功後檔案被移除(重裝套件、防毒隔離)或程序切換工作路徑時, 會沿用已resolve之Promise而不再下載
                     pmDownload = null
 
-                    return Promise.reject(err)
                 })
         }
         await pmDownload
@@ -85,7 +87,7 @@ async function autoDownloadFiles() {
 
     //check
     if (fdBase === '') {
-        return Promise.reject('can not find htmlToDocx.exe')
+        return Promise.reject(`can not find ${fnExe} in [${fdBaseSelf}] or [${fdBaseNM}]`)
     }
 
     //fpExe