topbit 3.1.1 → 3.1.3

package/README.cn.md

@@ -1579,15 +1579,6 @@ app.run(1235)
 
 ---
 
-以下是根据你提供的 `titbit-toolkit` 原始文档内容，按照新的列表顺序重新整理的文档。
-
-**注意**：
-*   根据指示，文档已针对新的 **Topbit** 框架语境进行了调整（即不再强调独立安装扩展）。
-*   列表中未包含的组件（如 `Timing`, `RealIP`, `MixLogger`, `SendType`, `SetFinal`, `Http2Limit`）已被移除。
-*   列表中包含但原文档未提供详细说明的组件（如 `SNI`），仅保留了描述占位符。
-
----
-
 ### 1. Cors (跨域支持)
 
 支持跨域请求的中间件。尽管是对跨域场景的支持，但在具备 `origin` 消息头的跨域通信和 `referer` 资源引入场景都做了支持，并且可以灵活选择和配置。

package/README.md

@@ -1543,14 +1543,6 @@ app.run(1235)
 
 ---
 
-The following documentation is reorganized based on the original `titbit-toolkit` documentation you provided, adapted for the new list order.
-
-**Note**:
-*   The documentation has been adjusted for the **Topbit** framework context (no longer emphasizing standalone installation of extensions).
-*   Components not included in the list above have been removed.
-
----
-
 ### 1. Cors (Cross-Origin Support)
 
 Middleware that supports cross-origin requests. It supports cross-origin communication via the `origin` header as well as resource inclusion via `referer`, allowing for flexible selection and configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "topbit",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "A Server-side web framework support http/1.1 and http/2",
   "main": "src/topbit.js",
   "directories": {

package/src/lib/npargv.js

@@ -1,354 +1,298 @@
 'use strict'
 
 /**
- * {
- *    '-a' : {
- *      name: 'a',
- *      type: 'number|string|int|float|bool',
- *      min: 0,
- *      max: 100,
- *      match: RegExp,
- *      default : any
- *    },
- *    
- *    '$2': {
- * 
- *    },
- *    {
- *      '--port=' : {
- *        name : 'port',
- *        type : 'int',
- *        min: 2000,
- *        max: 5000,
- *        default: 3456
- *      }
- *    }
- * }
- * 
+ * 验证并转换数值
  */
+function validateAndConvert(name, rule, value) {
+  let val = value
 
-function setVal (a, ainfo, obj, next) {
-
-  if (ainfo.type && ['int', 'float', 'number'].indexOf(ainfo.type) >= 0) {
-      if (isNaN(next)) {
-        return {
-          ok: false,
-          message: `${a} 类型错误，要求参数必须是数字类型：${next}`
-        }
-      }
-
-      if (ainfo.type === 'int' || ainfo.type === 'number') {
-        next = parseInt(next)
-      } else {
-        next = parseFloat(next)
-      }
-  }
-
-  if (ainfo.min !== undefined) {
-    if (next < ainfo.min) {
-      return {
-        ok: false,
-        message: `${a} 数值不能低于 ${ainfo.min}`
-      }
-    }
-  }
-
-  if (ainfo.max !== undefined) {
-    if (next > ainfo.max) {
-      return {
-        ok: false,
-        message: `${a} 数值不能大于 ${ainfo.max}`
-      }
+  // 1. 类型检查与转换
+  if (['int', 'float', 'number'].includes(rule.type)) {
+    if (isNaN(val)) {
+      throw new Error(`${name} 类型错误，要求参数必须是数字类型，当前值为：${val}`)
     }
-  }
-
-  if (ainfo.match && ainfo.match instanceof RegExp) {
-    if (!ainfo.match.test(next)) {
-      return {
-        ok: false,
-        message: `${a} 数值无法匹配 ${next}`
-      }
+    if (rule.type === 'int') {
+      val = parseInt(val, 10)
+    } else {
+      val = parseFloat(val)
     }
   }
 
-  let val = next
-
-  if (ainfo.callback && typeof ainfo.callback === 'function') {
-    val = ainfo.callback(next)
-    if (val === undefined) val = next
-  }
-
-  obj[ ainfo.name || a ] = val
-
-  return {
-    ok: true,
-    message: ''
-  }
-
-}
-
-function checkAndSet (a, ainfo, obj, next) {
-
-  if (typeof ainfo === 'boolean') {
-    obj[a] = true
-    return {
-      ok: true,
-      message: '',
-      op: 'none'
-    }
+  // 2. 范围检查
+  if (rule.min !== undefined && val < rule.min) {
+    throw new Error(`${name} 数值不能低于 ${rule.min}`)
   }
-
-  if (ainfo.type === 'bool' || ainfo.type === 'boolean') {
-    obj[ ainfo.name || a ] = true
-
-    return {
-      ok: true,
-      message: '',
-      op: 'none'
-    }
+  if (rule.max !== undefined && val > rule.max) {
+    throw new Error(`${name} 数值不能大于 ${rule.max}`)
   }
 
-  if (next === null) {
-    return {
-      ok: false,
-      message: `${a} 必须携带参数。`
+  // 3. 正则匹配
+  if (rule.match && rule.match instanceof RegExp) {
+    if (!rule.match.test(String(value))) { // 确保用原始字符串测试
+      throw new Error(`${name} 格式不匹配`)
     }
   }
 
-  let r = setVal(a, ainfo, obj, next)
-
-  if (!r.ok && ainfo.default !== undefined) {
-    r.ok = true
-  }
-
-  if (r.ok) {
-    r.op = 'next'
-
-    if (a[a.length - 1] === '=') {
-      r.op = 'none'
-    }
+  // 4. 回调处理
+  if (typeof rule.callback === 'function') {
+    const callbackVal = rule.callback(val)
+    if (callbackVal !== undefined) val = callbackVal
   }
 
-  return r
+  return val
 }
 
-function setAutoDefault (opts, k) {
-  switch (opts[k].type) {
+/**
+ * 自动填充默认值配置
+ */
+function applyAutoDefault(rule) {
+  if (rule.default !== undefined) return
+
+  switch (rule.type) {
     case 'number':
     case 'int':
     case 'float':
-      opts[k].default = 0
-      if (opts[k].min)
-        opts[k].default = opts[k].min;
+      rule.default = rule.min !== undefined ? rule.min : 0
       break
-
     case 'string':
-      opts[k].default = ''
+      rule.default = ''
       break
-
     case 'bool':
     case 'boolean':
-      opts[k].default = false
+      rule.default = false
       break
   }
 }
 
-/*
- * opts['@autoDefault'] = true 表示自动设定默认值
- *
- * */
-
-function parseArgv (options = null, obj = null) {
-  if (!options) options = {}
-
-  if (obj === null) obj = {}
-
-  let opts = {}
-
-  for (let k in options) {
-    opts[k] = options[k]
-  }
-
-  let autoDefault = false
+/**
+ * 规范化 Schema 定义
+ * 将简写转换为完整对象，处理自动默认值
+ */
+function normalizeSchema(schema, autoDefault) {
+  const normalized = {}
+  
+  for (let key in schema) {
+    let rule = schema[key]
+
+    // 1. 字符串简写处理: {'-v': 'verbose'} -> {'-v': { name: 'verbose', type: 'boolean' }}
+    if (typeof rule === 'string' && rule.trim().length > 0) {
+      rule = { name: rule.trim(), type: 'boolean', default: false }
+    }
+    else if (typeof rule !== 'object' || rule === null) {
+      rule = { name: key, type: 'boolean' }
+    }
 
-  if (opts['@autoDefault'] === undefined) opts['@autoDefault'] = true;
+    // 3. 自动推断 Type
+    if (!rule.type) {
+      if (key.includes('=')) {
+        rule.type = 'string'
+      } else if (rule.match || rule.callback) {
+        rule.type = 'string'
+      } else if (rule.min !== undefined || rule.max !== undefined) {
+        rule.type = 'int'
+      } else if (rule.default !== undefined) {
+        const defaultType = typeof rule.default
+        rule.type = ['number', 'boolean', 'string'].includes(defaultType) ? defaultType : 'string'
+      } else {
+        rule.type = 'boolean'
+      }
+    }
 
-  if (opts['@autoDefault'] !== undefined) {
-    autoDefault = !!opts['@autoDefault']
-    delete opts['@autoDefault']
-  }
+    // 4. 应用自动默认值
+    if (autoDefault) {
+      applyAutoDefault(rule)
+    }
 
-  let commands = []
-  if (opts['@command'] !== undefined) {
-    if (typeof opts['@command'] === 'string') {
-      opts['@command'].split(' ').filter(p => p.length > 0).forEach(a => {
-        commands.push(a.trim())
-      })
-    } else if (Array.isArray(opts['@command'])) {
-      commands = opts['@command'];
+    // 5. 处理别名 (Alias)
+    normalized[key] = rule
+    if (rule.alias && typeof rule.alias === 'string') {
+      normalized[rule.alias] = rule
     }
-    delete opts['@command'];
   }
+  
+  return normalized
+}
 
-  let defaultCommand = ''
-  if (opts['@defaultCommand'] !== undefined && commands.indexOf(opts['@defaultCommand']) >= 0) {
-    defaultCommand = opts['@defaultCommand'];
-    delete opts['@defaultCommand'];
+/**
+ * 主解析函数
+ * 
+ * @param {Object} schema 参数定义
+ * @param {Object} options 配置项 { strict: boolean, autoDefault: boolean, commands: [], defaultCommand: string, argv: [] }
+ */
+function parseArgv(schema = {}, options = {}) {
+  // --- 1. 配置初始化 ---
+  const config = {
+    strict: true,        // 默认为严格模式，报错即停
+    autoDefault: true,   // 默认自动生成 default 值
+    commands: options.commands && Array.isArray(options.commands) ? options.commands : [],
+    defaultCommand: options.defaultCommand || '',  // 默认子命令
+    argv: process.argv,  // 允许传入自定义 argv 用于测试
+    ...options
   }
 
+  if (config.commands && config.commands.length > 0 && !options.defaultCommand) {
+    config.defaultCommand = config.commands[0]
+  }
+ 
+  // --- 2. 预处理 ---
+  const rules = normalizeSchema(schema, config.autoDefault)
+  const result = {}
+  const errors = []
+  const unknownList = []
   let userCommand = null
-  let commandFromInput = false
-  if (commands.length > 0) {
-    if (process.argv.length < 3) {
-      if (defaultCommand) userCommand = defaultCommand;
-      else {
-        return {
-          ok: false,
-          message: '请使用子命令：' + commands.join('|'),
-          args: obj
-        }
-      }
-    } else if  (commands.indexOf(process.argv[2]) < 0) {
-      if (defaultCommand) userCommand = defaultCommand;
-      else {
-        return {
-          ok: false,
-          message: '不支持的子命令',
-          args: obj
-        }
-      }
+  
+  // 初始化结果对象中的默认值
+  for (let key in rules) {
+    const rule = rules[key]
+    const name = rule.name || key
+    if (rule.type === 'bool' || rule.type === 'boolean') {
+      if (result[name] === undefined) result[name] = rule.default !== undefined ? rule.default : false
     } else {
-      commandFromInput = true
-      userCommand = process.argv[2]
+      if (result[name] === undefined && rule.default !== undefined) result[name] = rule.default
     }
   }
 
-  let tmp_val
-
-  for (let k in opts) {
-    if (typeof opts[k] === 'string' && opts[k].trim().length > 0) {
-      opts[k] = {
-        name: opts[k].trim(),
-        type: 'boolean',
-        default: false
-      }
-    }
+  // --- 3. 解析子命令 ---
+  let index = 2
+  if (config.argv[0].endsWith('node')) { 
+      // 标准 node xxx.js 格式，从下标2开始
+      // 如果是 compiled binary 或者是 electron 等环境，可能需要自行调整 config.argv
+  }
 
-    if (typeof opts[k] !== 'object' || opts[k].toString() !== '[object Object]') {
+  if (config.commands.length > 0) {
+    const inputCmd = config.argv[index]
 
-      opts[k] = {
-        type : 'boolean',
-        name : k,
-        default: false
+    if (!inputCmd || inputCmd.startsWith('-')) {
+      // 没有提供命令，或者直接开始了参数
+      if (config.defaultCommand) {
+        userCommand = config.defaultCommand
+      } else {
+        const msg = `缺少子命令，可用命令: ${config.commands.join('|')}`
+        if (config.strict) return { ok: false, message: msg, args: result }
+        errors.push(msg)
       }
-
-    } else if (opts[k].type === undefined) {
-
-      if (k.indexOf('=') > 0) {
-        opts[k].type = 'string'
-      } else if (opts[k].match || opts[k].callback) {
-        opts[k].type = 'string'
+    } else if (config.commands.includes(inputCmd)) {
+      userCommand = inputCmd
+      index++ // 消耗掉命令参数
+    } else {
+      // 提供了命令但不在列表中
+      if (config.defaultCommand) {
+        userCommand = config.defaultCommand
+        // 注意：这里不 index++，因为当前这个 unknown command 可能是个普通参数？
+        // 根据惯例，如果命令不对，通常视为错误，或者回退到 defaultCommand 但把当前词作为参数解析
       } else {
-          if (opts[k].min !== undefined || opts[k].max !== undefined) {
-            opts[k].type = 'int'
-          } else if (opts[k].default !== undefined) {
-            tmp_val = typeof opts[k].default
-            if (tmp_val === 'number' || tmp_val === 'boolean' || tmp_val === 'string') {
-              opts[k].type = tmp_val
-            } else {
-              opts[k].type = 'string'
-            }
-          } else {
-            opts[k].type = 'bool'
-          }
+        const msg = `不支持的子命令: ${inputCmd}`
+        if (config.strict) return { ok: false, message: msg, args: result }
+        errors.push(msg)
       }
-
-    }
-
-    autoDefault && opts[k].default === undefined && setAutoDefault(opts, k)
-
-    if (opts[k].type === 'bool' || opts[k].type === 'boolean') {
-      obj[ opts[k].name || k ] = false
-    } else if (opts[k].default !== undefined) {
-      obj[ opts[k].name || k ] = opts[k].default
     }
-
   }
 
-  for (let k in opts) {
-    if (opts[k].alias && typeof opts[k].alias === 'string' && opts[k].alias !== k) {
-      opts[opts[k].alias] = opts[k]
-    }
-  }
+  // --- 4. 遍历参数 ---
+  // 计算位置参数的偏移量 (如果有子命令，$1 应该是子命令后的第一个参数)
+  const posOffset = index - 1 
 
-  let a
-  let next
-  let next_end = process.argv.length - 1
-  let r = ''
-  let i = 2
-  let offset = 1
-  if (commands.length > 0 && commandFromInput) {
-    i++
-    offset = 2
-  }
-
-  let ind = 0
-  let pos_key = ''
-  let aList = []
-
-  while (i < process.argv.length) {
-
-    //先检测是否存在对位置的引用
-    pos_key = '$' + `${i-offset}`
-    if (opts[pos_key]) {
-      r = checkAndSet(pos_key, opts[pos_key], obj, process.argv[i])
-      if (!r.ok) {
-        r.args = obj
-        return r
+  while (index < config.argv.length) {
+    let rawArg = config.argv[index]
+    
+    // 4.1 处理位置参数引用 ($1, $2...)
+    const posKey = `$${index - posOffset}`
+    if (rules[posKey]) {
+      const rule = rules[posKey]
+      const name = rule.name || posKey
+      try {
+        result[name] = validateAndConvert(name, rule, rawArg)
+      } catch (e) {
+        if (config.strict) return { ok: false, message: e.message, args: result }
+        errors.push(e.message)
       }
-      i++
+      index++
       continue
     }
 
-    a = process.argv[i]
-    
-    next = i < next_end ? process.argv[i+1] : null
+    // 4.2 解析 Key-Value (处理 --port=8080 这种情况)
+    let nextArg = (index + 1 < config.argv.length) ? config.argv[index + 1] : null
+    let key = rawArg
+    let valStr = null
+    let consumeNext = false // 是否消耗了下一个参数
+
+    const equalIndex = rawArg.indexOf('=')
+    if (equalIndex > 0) {
+      key = rawArg.substring(0, equalIndex + 1) // 保留 = 号以匹配定义
+      if (!rules[key]) {
+         key = rawArg.substring(0, equalIndex) // 尝试不带 = 匹配
+      }
+      valStr = rawArg.substring(equalIndex + 1)
+    }
 
-    ind = a.indexOf('=')
+    // 4.3 匹配定义
+    if (rules[key]) {
+      const rule = rules[key]
+      const name = rule.name || key
 
-    if (ind > 0) {
-      a = a.substring(0, ind+1)
-      next = process.argv[i].substring(ind+1)
-    }
+      // 布尔类型不需要下一个参数值 (除非显式赋值，暂不支持 --bool=false 写法，按原逻辑处理)
+      if (rule.type === 'bool' || rule.type === 'boolean') {
+        result[name] = true
+      } else {
+        // 取值
+        let valToProcess = (valStr !== null) ? valStr : nextArg
+        
+        // 如果是从 nextArg 取值的，标记需要跳过下一个循环
+        if (valStr === null) {
+            if (valToProcess === null) {
+                // 已经是最后一个了，却需要参数
+                const msg = `${key} 必须携带参数`
+                if (config.strict) return { ok: false, message: msg, args: result }
+                errors.push(msg)
+            }
+            consumeNext = true 
+        }
 
-    if (opts[a]) {
-      r = checkAndSet(a, opts[a], obj, next)
-      if (!r.ok) {
-        r.args = obj
-        return r
+        if (valToProcess !== null) {
+            try {
+                result[name] = validateAndConvert(name, rule, valToProcess)
+            } catch (e) {
+                if (config.strict) return { ok: false, message: e.message, args: result }
+                errors.push(e.message)
+                // 出错时，非 strict 模式下保留默认值
+            }
+        }
       }
 
-      if (r.op === 'next') {
-        i += 2
-        continue
+      if (consumeNext) index++
+    } else {
+       // 1. 处理转义字符 (例如输入 \-name，实际意图是文件名 -name)
+      if (rawArg.startsWith('\\')) {
+        // 去掉开头的反斜杠，将其余部分作为普通参数存入 list
+        unknownList.push(rawArg.substring(1))
       }
 
-    } else {
-      if (a[0] !== '-') {
-        a[0] !== '\\' ? aList.push(a) : aList.push(a.substring(1))
+      // 2. 处理普通参数 (文件名、纯字符串等，不以 - 开头)
+      else if (!rawArg.startsWith('-')) {
+        unknownList.push(rawArg)
+      }
+
+      // 3. 剩下的即为以 - 开头但未定义的未知 Flag
+      else {
+        //unknownList.push(rawArg)
+        // 这一块可以根据你的需求决定：
+        // 选项 A: 忽略 (保持当前逻辑)
+        // 选项 B: 报错 (如果 config.strict 为 true)
+        // 选项 C: 也放入 list (通常不建议，因为可能是用户输错的参数)
       }
     }
 
-    i++
+    index++
   }
 
   return {
-    ok: true,
-    message: '',
-    args: obj,
-    list: aList,
+    ok: errors.length === 0,
+    message: errors.length > 0 ? errors[0] : '', // 向下兼容，返回第一个错误
+    errors: errors, // 新增：返回所有错误
+    args: result,
+    list: unknownList,
     command: userCommand
   }
 }
 
-module.exports = parseArgv
+module.exports = parseArgv