cishu-data-format 1.0.0 → 1.0.1

package/README.md

@@ -1,13 +1,154 @@
 # cishu-data-format
 
-辞书处理数据集合 NPM 包的 Demo。
+辞书处理 XML 与 JSON 数据格式转换的 NPM 工具库。
 
 ## 安装
 
 ```bash
 npm install cishu-data-format
+```
 
-##
+## 使用说明
+
+本工具包支持 ES Modules (ESM) 导入。
+
+### 1. 导入方法
+
+```javascript
+// 方式一：导入命名函数（推荐）
+import { xmlToJson, jsonToXml } from 'cishu-data-format';
+
+// 方式二：导入默认对象
+import cishuFormat from 'cishu-data-format';
+// 使用 cishuFormat.xmlToJson(...) 或 cishuFormat.jsonToXml(...)
+```
+
+### 2. XML 转 JSON (`xmlToJson`)
+
+将 XML 字符串转换为特定的 JSON 树形结构。
+
+#### 参数
+- `xml` (`string`): 待转换的 XML 字符串。
+
+#### 返回值
+- `Object | Array`: 解析后的 JSON 节点。如果 XML 根节点只有一个，则返回该节点对象；如果有多个并列根节点，则返回节点数组。
+
+#### 示例
+
+```javascript
+import { xmlToJson } from 'cishu-data-format';
+
+const xmlString = `
+<book id="1" category="fiction">
+  <title>Harry Potter</title>
+  <author>J.K. Rowling</author>
+  <price currency="USD">29.99</price>
+  <description />
+</book>
+`;
+
+const json = xmlToJson(xmlString);
+console.log(JSON.stringify(json, null, 2));
+```
+
+**输出 JSON 结构：**
+```json
+{
+  "type": "element",
+  "name": "book",
+  "attributes": {
+    "id": "1",
+    "category": "fiction"
+  },
+  "children": [
+    {
+      "type": "element",
+      "name": "title",
+      "attributes": {},
+      "children": [
+        {
+          "type": "text",
+          "text": "Harry Potter"
+        }
+      ]
+    },
+    {
+      "type": "element",
+      "name": "author",
+      "attributes": {},
+      "children": [
+        {
+          "type": "text",
+          "text": "J.K. Rowling"
+        }
+      ]
+    },
+    {
+      "type": "element",
+      "name": "price",
+      "attributes": {
+        "currency": "USD"
+      },
+      "children": [
+        {
+          "type": "text",
+          "text": "29.99"
+        }
+      ]
+    },
+    {
+      "type": "element",
+      "name": "description",
+      "attributes": {},
+      "children": []
+    }
+  ]
+}
+```
+
+---
+
+### 3. JSON 转 XML (`jsonToXml`)
+
+将符合上述结构的 JSON 树形对象转换回 XML 字符串，且会自动对属性和文本内容进行安全转义（处理 `&`, `<`, `>`, `"` 字符）。
+
+#### 参数
+- `node` (`Object`): 符合格式的 JSON 节点对象（包含 `type`, `name`, `attributes`, `children` 或 `text`）。
+
+#### 返回值
+- `string`: 转换后的 XML 字符串。
+
+#### 示例
+
+```javascript
+import { jsonToXml } from 'cishu-data-format';
+
+const jsonNode = {
+  type: "element",
+  name: "book",
+  attributes: { id: "1" },
+  children: [
+    {
+      type: "element",
+      name: "title",
+      attributes: {},
+      children: [{ type: "text", text: "Harry & Potter" }]
+    }
+  ]
+};
+
+const xmlString = jsonToXml(jsonNode);
+console.log(xmlString);
+// 输出: <book id="1"><title>Harry &amp; Potter</title></book>
+```
+
+---
+
+## 开发者发布指南
+
+如果您需要发布或更新此 NPM 包，可参考以下步骤：
+
+```bash
 # 1. 在项目根目录初始化（如果还没做）
 npm init -y
 
@@ -16,14 +157,14 @@ npm login
 
 # 3. 验证是否登录成功
 npm whoami
-# 发布（第一次用这个）
-npm publish --access public
-# 修改版本号（推荐方式）
+
+# 4. 修改版本号（推荐方式）
 npm version patch     # 1.0.0 -> 1.0.1
 # 或
 npm version minor     # 1.0.0 -> 1.1.0
 # 或
 npm version major     # 1.0.0 -> 2.0.0
 
-# 然后发布
-npm publish
+# 5. 发布到 npm
+npm publish --access public
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cishu-data-format",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "辞书处理xml数据格式的工具库",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -1,20 +1,131 @@
 /**
- * 一个简单的问候函数
- * @param {string} name - 名字
- * @returns {string} 问候语
+ * 将 XML 字符串转换为 JSON 对象结构
+ * @param {string} xml - XML 字符串
+ * @returns {Object|Array} 解析后的 JSON 节点或节点数组
  */
-export function greet(name = '世界') {
-  return `你好，${name}！欢迎使用我的第一个 NPM 包 🎉`;
+export function xmlToJson(xml) {
+  xml = xml.trim();
+  const tagRegex = /<([^>]+)>/g;
+  let lastIndex = 0;
+
+  const root = { name: null, attributes: {}, children: [], text: "" };
+  const stack = [root];
+
+  function parseAttributes(str) {
+    const attrs = {};
+    const attrRegex = /(\w[\w:-]*)\s*=\s*"([^"]*)"/g;
+    let m;
+    while ((m = attrRegex.exec(str))) {
+      attrs[m[1]] = m[2];
+    }
+    return attrs;
+  }
+
+  let match;
+  while ((match = tagRegex.exec(xml))) {
+    const textBetween = xml.substring(lastIndex, match.index);
+    lastIndex = tagRegex.lastIndex;
+
+    if (textBetween.trim()) {
+      const node = stack[stack.length - 1];
+      node.children.push({
+        type: "text",
+        text: textBetween.trim()
+      });
+    }
+
+    const tag = match[1].trim();
+
+    // 处理结束标签 </xxx>
+    if (tag.startsWith("/")) {
+      stack.pop();
+      continue;
+    }
+
+    // 判断是否为自闭合标签 <xxx />
+    const selfClosing = tag.endsWith("/");
+
+    // 提取标签名
+    const parts = tag.replace(/\/$/, "").split(/\s+/);
+    const tagName = parts[0];
+
+    const attrs = parseAttributes(tag);
+
+    const newNode = {
+      type: "element",
+      name: tagName,
+      attributes: attrs,
+      children: []
+    };
+
+    const parent = stack[stack.length - 1];
+    parent.children.push(newNode);
+
+    if (!selfClosing) {
+      stack.push(newNode);
+    }
+  }
+
+  return root.children.length === 1 ? root.children[0] : root.children;
 }
 
 /**
- * 加法函数（测试用）
+ * XML 内容转义
+ * @param {string} str - 待转义的 XML 文本内容
+ * @returns {string} 转义后的文本
  */
-export function add(a, b) {
-  return a + b;
+function escapeXml(str) {
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * 属性值转义
+ * @param {string} str - 待转义的属性值
+ * @returns {string} 转义后的属性值
+ */
+function escapeAttr(str) {
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;");
+}
+
+/**
+ * 将 JSON 对象结构转换为 XML 字符串
+ * @param {Object} node - 符合结构的 JSON 节点
+ * @returns {string} XML 字符串
+ */
+export function jsonToXml(node) {
+  // 文本节点
+  if (node.type === "text") {
+    return escapeXml(node.text || "");
+  }
+
+  // 处理属性
+  const attrs = Object.entries(node.attributes || {})
+    .map(([key, value]) => `${key}="${escapeAttr(value)}"`)
+    .join(" ");
+
+  const hasAttrs = attrs.length > 0;
+  const openTag = hasAttrs ? `<${node.name} ${attrs}>` : `<${node.name}>`;
+
+  // 子节点
+  const children = (node.children || [])
+    .map(child => jsonToXml(child))
+    .join("");
+
+  // 如果没有 children 且没有文本 → 可能写成自闭合
+  if (!children) {
+    return hasAttrs ? `<${node.name} ${attrs}/>` : `<${node.name}/>`;
+  }
+
+  return `${openTag}${children}</${node.name}>`;
 }
 
 export default {
-  greet,
-  add
+  xmlToJson,
+  jsonToXml
 };