befly-shared 1.3.2 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly-shared",
-    "version": "1.3.2",
+    "version": "1.3.3",
     "private": false,
     "description": "Befly 纯函数与纯常量共享包（不包含 Node/浏览器特定实现）",
     "license": "Apache-2.0",
@@ -19,5 +19,5 @@
     "engines": {
         "bun": ">=1.3.0"
     },
-    "gitHead": "7dd54bc1ed484139fa52ce5408f1a6c166e2a928"
+    "gitHead": "549fff1035081111a5ba32b5088e7c37907fa894"
 }

package/utils/normalizePathnameListInput.ts

@@ -0,0 +1,58 @@
+const HTTP_METHOD_PREFIX_RE = /^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\b/i;
+
+/**
+ * 将未知输入规范化为 pathname 字符串数组。
+ *
+ * 规则（契约）：
+ * - value 为“假值”（null/undefined/""/0/false/NaN）时返回空数组 []。
+ * - value 必须是 string[]，否则抛错：`${fieldLabel} 必须是字符串数组`。
+ * - 数组元素必须满足：
+ *   - 类型为 string
+ *   - 不允许为空字符串
+ *   - 不允许包含任何空白字符（空格/制表符/换行等）
+ *   - 必须以 "/" 开头（pathname）
+ * - forbidMethodPrefix=true 时，禁止 "GET/POST/..." 等 method 前缀，并给出更明确的错误提示。
+ *
+ * 注意：该函数不会做任何隐式修复/转换（例如 trim/split/JSON.parse/去重/排序）。
+ */
+export function normalizePathnameListInput(value: unknown, fieldLabel: string, forbidMethodPrefix: boolean): string[] {
+    // “假值”统一视为空数组：null/undefined/""/0/false/NaN
+    if (!value) return [];
+
+    if (!Array.isArray(value)) {
+        throw new Error(`${fieldLabel} 必须是字符串数组`);
+    }
+
+    const out: string[] = [];
+
+    for (let i = 0; i < value.length; i += 1) {
+        const item = value[i];
+        const itemLabel = `${fieldLabel}[${i}]`;
+
+        if (typeof item !== "string") {
+            throw new Error(`${itemLabel} 必须是字符串`);
+        }
+
+        if (item.length === 0) {
+            throw new Error(`${itemLabel} 不允许为空字符串`);
+        }
+
+        // 优先给出 method 前缀提示（更明确）
+        if (forbidMethodPrefix && HTTP_METHOD_PREFIX_RE.test(item)) {
+            throw new Error(`${itemLabel} 不允许包含 method 前缀，应为 url.pathname（例如 /api/app/xxx）`);
+        }
+
+        // 不做 trim 自动转换：含任何空白字符都视为不合法
+        if (/\s/.test(item)) {
+            throw new Error(`${itemLabel} 不允许包含空白字符（空格/制表符/换行等）`);
+        }
+
+        if (!item.startsWith("/")) {
+            throw new Error(`${itemLabel} 必须是 pathname（以 / 开头）`);
+        }
+
+        out.push(item);
+    }
+
+    return out;
+}