v-transform 2.2.2 → 2.3.0

package/package.json

@@ -4,12 +4,12 @@
     "vt": "src/index.js"
   },
   "type": "module",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "main": "index.js",
   "scripts": {
     "clean": "npx rimraf test",
-    "vt": "node src/index.js",
-    "transform": "node src/index.js transform"
+    "vt": "vt",
+    "transform": "vt transform"
   },
   "repository": {
     "type": "git",
@@ -20,7 +20,9 @@
   "dependencies": {
     "commander": "^15.0.0",
     "glob": "^13.0.6",
-    "js-yaml": "^5.2.0",
-    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
+    "js-yaml": "^5.2.2",
+    "ts-to-zod": "^5.1.0",
+    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
+    "zod": "^4.4.3"
   }
 }

package/src/calibrator.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { generate } from 'ts-to-zod'
+
+export async function calibrateTsData(data, name, types, pk) {
+    // 如果没配对应的 .types.ts 文件，直接退回原始数据，类型签名为 any[]
+    if (!types || !fs.existsSync(types)) {
+        console.warn(
+            `⚠️ 提示: 在 Excel 同级目录下未找到 [${name}.types.ts]，将退回普通无类型导出。`,
+        )
+        const isArray = Array.isArray(data)
+        const extra = {
+            typeSign: isArray ? 'any[]' : 'Map<any, any>',
+            types: isArray ? `export type ${name.toUpperCase()} = any;` : '',
+            isNativeMap: !isArray, // 👈 即使降级也需要同步对齐是否为 Map 的标记
+        }
+        return { data, extra }
+    }
+
+    console.info(
+        `🔍 [vTransform TS] 成功在 Excel 目录定位规范，正在校准 [${name}]...`,
+    )
+    const sourceText = fs.readFileSync(types, 'utf-8')
+    const options = { keepOptionalProperties: true }
+    const zod = generate({ sourceText, options })
+    const zodRawCode = zod
+        .getZodSchemasFile()
+        .replace(/z\.boolean\(\)/g, 'z.coerce.boolean()')
+    const base64Code = Buffer.from(zodRawCode).toString('base64')
+    const zodModule = await import(`data:text/javascript;base64,${base64Code}`)
+    const targetSchemaName = `${name}Schema`
+    const RowZodValidator = zodModule[targetSchemaName]
+
+    if (!RowZodValidator) {
+        throw new Error(
+            `无法从类型文件中自动推导出名为 ${targetSchemaName} 的主校验器。`,
+        )
+    }
+
+    let cleanData
+    let typeSign = ''
+    const typeName = name.charAt(0).toUpperCase() + name.slice(1)
+
+    if (Array.isArray(data)) {
+        cleanData = []
+        typeSign = `${typeName}[]`
+        for (let i = 0; i < data.length; i++) {
+            const parseResult = RowZodValidator.safeParse(data[i])
+            if (!parseResult.success) {
+                printZodError(
+                    name,
+                    `第 ${i + 1} 条数据`,
+                    parseResult.error.issues,
+                    data[i],
+                )
+            }
+            cleanData.push(parseResult.data)
+        }
+        console.info(`📦 [Array 模式] 完美对齐数组规范`)
+    }
+    // 2. Map 模式验证
+    else if (typeof data === 'object' && data !== null) {
+        const tempCleanMap = {}
+        for (const key in data) {
+            const parseResult = RowZodValidator.safeParse(data[key])
+            if (!parseResult.success) {
+                printZodError(
+                    name,
+                    `Key 为 [${key}] 的数据`,
+                    parseResult.error.issues,
+                    data[key],
+                )
+            }
+            tempCleanMap[key] = parseResult.data
+        }
+        // ========================================================
+        // 🌟 终极修复：利用 Zod 原生验证自适应看穿 readonly 伪装
+        // ========================================================
+        let keyType = 'string'
+        if (pk && RowZodValidator.shape && RowZodValidator.shape[pk]) {
+            const validator = RowZodValidator.shape[pk]
+
+            // 💡 核心黑科技：直接用 1（数字）和 "1"（字符串）去该字段的校验器里试探！
+            // 无论它套了多少层 readonly() 还是可选约束，只要它不接受数字 1 校验，就说明它不是 number
+            if (
+                validator.safeParse(1).success &&
+                !validator.safeParse('1').success
+            ) {
+                keyType = 'number'
+            }
+        }
+
+        const isNumKey = keyType === 'number'
+        cleanData = Object.entries(tempCleanMap).map(([k, v]) => [
+            isNumKey ? Number(k) : k,
+            v,
+        ])
+        typeSign = `Map<${keyType}, ${typeName}>`
+        console.info(
+            `🎯 [Map 模式] 完美对齐原生 Map 规范，主键 [${pk}] 自动识别为: ${keyType}`,
+        )
+    }
+
+    // 🌟 核心修改 2：在返回的 extra 元数据层，加上 isNativeMap 的明确布尔标记。
+    // 这可以让下游的 dump.js 接收到它后，通过简单的一行流判断，决定是将 cleanData 渲染为普通 JSON，还是渲染为强大的 new Map(...)
+    const extra = {
+        typeSign,
+        types: sourceText,
+        isNativeMap: !Array.isArray(data), // 如果上游合并出来的不是数组（即Map模式），标记为 true
+    }
+
+    return { data: cleanData, extra }
+}
+
+/**
+ * 统一的美化报错打印
+ */
+function printZodError(sheetName, positionLabel, issues, rawRowData) {
+    console.error(`\n❌ [vTransform 数据校准失败]`)
+    console.error(
+        `👉 发生位置: 表格 [${sheetName}] ${positionLabel}不兼容你的 TS 类型限制！`,
+    )
+    console.error(`👉 冲突细节详情:`)
+    issues.forEach(err => {
+        const wrongField = err.path.join('.') || '根节点'
+        console.error(`  - 错误字段: \x1b[33m${wrongField}\x1b[0m`)
+        console.error(`  - 期待类型/约束: ${err.message}`)
+        console.error(
+            `  - 当前收到的脏数据值:`,
+            rawRowData[wrongField] ?? '缺失字段',
+        )
+        console.error(`  -----------------------------------------`)
+    })
+    process.exit(1)
+}

package/src/dump.js

@@ -1,23 +1,48 @@
-import yaml from 'js-yaml'
+import { dump as dumpYAML } from 'js-yaml'
 import path from 'node:path'
 import { writeFile, stat, mkdir } from 'node:fs/promises'
 
-function jsonify(data, space) {
+function j(data, space) {
     return JSON.stringify(data, null, space)
 }
 
-function cjsify(data, space) {
-    return `module.exports = ${jsonify(data, space)}`
+function jsonify(name, { data, addition }, space) {
+    return j(addition ? { [name]: data, ...addition } : data, space)
 }
 
-function esmify(data, space) {
-    return `export default ${jsonify(data, space)}`
+function cjsify(name, data, space) {
+    return `module.exports = ${jsonify(name, data, space)}`
 }
 
-function yamlify(data, space) {
-    return yaml.dump(data, {
-        indent: space || undefined,
-    })
+function esmify(name, { data, addition }, space) {
+    const main = `export const ${name} = ${jsonify(name, { data, addition }, space)}`
+    const def = `export default ${name}`
+    if (!addition) return `${main}\n${def}`
+    const extra = Object.entries(addition)
+        .map(([key, value]) => `export const ${key} = ${j(value, space)}`)
+        .join('\n')
+    return `${main}\n${extra}\n${def}`
+}
+
+function yamlify(name, { data, addition }, indent) {
+    const options = { indent: indent || undefined }
+    if (!addition) return dumpYAML(data, options)
+    return dumpYAML({ [name]: data, ...addition }, options)
+}
+
+function tsify(name, { data, extra, addition }, space) {
+    const { types, typeSign, isNativeMap } = extra
+    if (!types)
+        return `export default ${jsonify(name, { data, addition }, space)}`
+    const raw = j(data, space)
+    const d = isNativeMap ? `new Map(${raw})` : raw
+    const main = `${types}\nexport const ${name} = ${d} as unknown as ${typeSign};`
+    const def = `export default ${name}`
+    if (!addition) return `${main}\n${def}`
+    const extraExports = Object.entries(addition)
+        .map(([key, value]) => `export const ${key} = ${j(value, space)}`)
+        .join('\n')
+    return `${main}\n${extraExports}\n${def}`
 }
 
 async function mkdirs(dir) {
@@ -38,9 +63,13 @@ async function write(sheet, data) {
     await writeFile(sheet, data)
 }
 
-export async function dump(sheet, data, type, space) {
+export async function dump(sheet, data, type, space, name) {
     let ext, ify
     switch (type) {
+        case 'ts':
+            ext = '.ts'
+            ify = tsify
+            break
         case 'cjs':
             ext = '.js'
             ify = cjsify
@@ -62,5 +91,5 @@ export async function dump(sheet, data, type, space) {
             ify = jsonify
             break
     }
-    return write(`${sheet}${ext}`, ify(data, space))
+    return write(`${sheet}${ext}`, ify(name, data, space))
 }

package/src/index.js

@@ -11,7 +11,7 @@ program
     .command('transform [list...]')
     .option(
         '-t, --type <type>',
-        'type of transform, available: js, esm, cjs, json',
+        'type of transform, available: js, ts, esm, cjs, json',
         'json',
     )
     .option('-s, --space <space>', 'format space number', 0)

package/src/loader.js

@@ -1,5 +1,5 @@
 import { glob } from 'glob'
-import yaml from 'js-yaml'
+import { load as loadYAML } from 'js-yaml'
 import path from 'node:path'
 import { readFile } from 'node:fs/promises'
 
@@ -51,7 +51,7 @@ async function loadConfig(config) {
         case '.json':
         case '.yaml':
         case '.yml':
-            return yaml.load(await readFile(config))
+            return loadYAML(await readFile(config))
         case '.js':
         case '.mjs':
             return (await import(config)).default

package/src/parser.js

@@ -1,4 +1,4 @@
-import yaml from 'js-yaml'
+import { load } from 'js-yaml'
 
 function isCommentKey(key) {
     return key.startsWith('#')
@@ -9,6 +9,14 @@ function isJsonKey(key) {
 }
 
 function processHeaderColumn(col, head, layer, subs, json) {
+    // 💡 核心修复：如果该单元格为 null、undefined 或空，直接跳过不处理，防止错位和崩溃
+    if (
+        head[col] === null ||
+        head[col] === undefined ||
+        String(head[col]).trim() === ''
+    )
+        return
+
     let key = head[col].trim()
     if (isCommentKey(key)) return
     if (isJsonKey(key)) {
@@ -88,7 +96,7 @@ function formatRow({ type, key, source, subs }, row, original, json) {
 
 function formatValue(key, source, value, json) {
     if (value == null) return null
-    if (json.includes(source)) value = yaml.load(value)
+    if (json.includes(source)) value = load(value)
     return { key, value }
 }
 
@@ -134,7 +142,13 @@ function formatSheet(struct, rawSheet, json) {
 }
 
 export function parser(rawSheet) {
-    const struct = parseStruct(rawSheet.shift())
+    const head = rawSheet.shift()
+    const struct = parseStruct(head)
     rawSheet.shift()
-    return formatSheet(struct, rawSheet, struct.json)
+    const data = formatSheet(struct, rawSheet, struct.json)
+    if (struct.key) {
+        const col = struct.key.substring(1)
+        return [data, head[col].substring(1)]
+    }
+    return [data, null]
 }

package/src/prepare.js

@@ -15,8 +15,11 @@ export async function prepare(xlsxPath) {
     const datas = []
     for (const name in xlsx.Sheets) {
         const sheetRawData = xlsx.Sheets[name]
-        if (!sheetRawData['!ref']) break
-        const data = utils.sheet_to_json(sheetRawData, { header: 1 })
+        if (!sheetRawData['!ref']) continue
+        const data = utils.sheet_to_json(sheetRawData, {
+            header: 1,
+            defval: null,
+        })
         datas.push({ name, data })
     }
     return datas

package/src/transform.js

@@ -3,6 +3,7 @@ import { load } from './loader.js'
 import { prepare } from './prepare.js'
 import { parser } from './parser.js'
 import { dump } from './dump.js'
+import { calibrateTsData } from './calibrator.js'
 
 export async function transform(options) {
     const now = Date.now()
@@ -16,21 +17,21 @@ async function task({ files, dest, cwd, type, space, addition }) {
     const m = new Map()
     for (const file of files) {
         const dir = path.resolve(dest, path.dirname(file))
-        const prepared = await prepare(path.resolve(cwd, file))
-        processPrepared(prepared, dir, m)
+        await processPrepared(path.resolve(cwd, file), dir, m, type == 'ts')
     }
     for (const [sheet, job] of m) {
-        const data = job.result()
-        if (addition) await dump(sheet, { data, ...addition }, type, space)
-        else await dump(sheet, data, type, space)
+        const data = await job.result()
+        await dump(sheet, { ...data, addition }, type, space, job.name)
     }
 }
 
-function processPrepared(prepared, dir, m) {
+async function processPrepared(src, dir, m, isTs) {
+    const prepared = await prepare(src)
+    const xlsxDir = path.dirname(src)
     for (const { name, data } of prepared) {
         if (name.startsWith('#')) continue
         const { sheet, keys } = parseSheetAndKeys(name, dir)
-        if (!m.has(sheet)) m.set(sheet, new JobData())
+        if (!m.has(sheet)) m.set(sheet, new JobData(isTs, name, xlsxDir))
         m.get(sheet).append({ keys, data: parser(data) })
     }
 }
@@ -45,17 +46,24 @@ function parseSheetAndKeys(name, dir) {
 }
 
 class JobData {
-    constructor(data) {
-        if (data) this.append(data)
+    constructor(isTs, name, xlsxDir) {
+        this.#isTs = isTs
+        this.#name = name
+        this.#xlsxDir = xlsxDir
     }
 
     #data = []
+    #pk = null
+    #isTs = false
+    #name = ''
+    #xlsxDir = ''
 
-    append(data) {
-        this.#data.push(data)
+    append({ data: [data, pk], keys }) {
+        this.#data.push({ data, keys })
+        if (pk) this.#pk = pk
     }
 
-    result() {
+    async result() {
         if (!this.#data.length) return {}
         let result
         for (const { keys, data } of this.#data) {
@@ -72,7 +80,15 @@ class JobData {
             }
             r[last] = this.#combine(r[last], data)
         }
-        return result
+        if (!this.#isTs) return { data: result }
+
+        // TODO: 这里调用数据清洗
+        return await calibrateTsData(
+            result,
+            this.#name,
+            path.join(this.#xlsxDir, `${this.#name}.types.ts`),
+            this.#pk,
+        )
     }
 
     #combine(a, b) {
@@ -90,4 +106,8 @@ class JobData {
         for (const key in b) if (!result[key]) result[key] = b[key]
         return result
     }
+
+    get name() {
+        return this.#name
+    }
 }