ms-vite-plugin 1.5.12 → 1.5.13

package/docs/apipython/sqlite.md

@@ -0,0 +1,181 @@
+# SQLite 数据库模块 (SQLite)
+
+SQLite 模块提供本地数据库文件的打开、查询、执行和事务。可以同时打开多个库，每个库用 `open` 返回的句柄操作。
+
+## 功能概览
+
+- **多库句柄**: `open` 返回句柄，后续方法把句柄作为第一个参数
+- **数据查询**: 执行 SELECT 查询
+- **数据更新**: 执行 CREATE、INSERT、UPDATE、DELETE
+- **事务支持**: `beginTransaction` / `commit` / `rollback`
+- **参数绑定**: 使用 `?` 占位，防止 SQL 注入
+
+## 注意事项
+
+1. **文件路径**: 路径必须是绝对路径，与 `file` 模块相同。相对路径会打开失败。
+2. **内存库**: 路径传 `":memory:"` 打开内存数据库。
+3. **句柄**: 先 `open` 再查询；脚本结束会关闭本次运行打开的全部句柄，仍建议用完 `close`。
+4. **BLOB**: 第一版不把 BLOB 转成字符串，读到的该格为 `None`。
+5. **锁定等待**: 数据库被占用时最多等待 5 秒。
+
+## 类型定义
+
+### SqliteResult
+
+查询 / 执行结果。
+
+```python
+from typing import Any, Dict, List, Optional
+from kuaijs._types import KuaiJSNamespace
+
+class SqliteResult(KuaiJSNamespace):
+    rows: List[Dict[str, Any]]
+    affectedRows: int
+    insertId: Optional[int]
+    success: bool
+    error: Optional[str]
+```
+
+**参数说明:**
+
+| 参数名         | 类型                 | 描述                         |
+| -------------- | -------------------- | ---------------------------- |
+| `rows`         | List[Dict[str, Any]] | 查询结果数据行               |
+| `affectedRows` | int                  | 受影响的行数                 |
+| `insertId`     | int                  | 本次连接最近一次插入的 rowid |
+| `success`      | bool                 | 是否成功                     |
+| `error`        | str                  | 错误信息                     |
+
+## API 参考
+
+### 连接管理
+
+#### open - 打开数据库
+
+```python
+def open(path: str) -> Optional[str]
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                      |
+| ------ | ---- | -------- | ------ | ------------------------- |
+| `path` | str  | 是       |        | 绝对路径，或 `":memory:"` |
+
+**返回值:**
+
+| 类型            | 描述                        |
+| --------------- | --------------------------- |
+| `Optional[str]` | 成功返回句柄，失败返回 `None` |
+
+**示例:**
+
+```python
+from kuaijs import sqlite, file, logger
+
+path = file.getInternalDir("documents") + "/app.db"
+db = sqlite.open(path)
+if not db:
+    logger.error("打开失败")
+```
+
+#### close - 关闭数据库
+
+```python
+def close(handle: str)
+```
+
+**示例:**
+
+```python
+sqlite.close(db)
+```
+
+#### isOpen - 检查句柄是否仍打开
+
+```python
+def isOpen(handle: str) -> bool
+```
+
+**示例:**
+
+```python
+if sqlite.isOpen(db):
+    logger.info("数据库已打开")
+```
+
+### 数据操作
+
+#### query - 执行查询
+
+```python
+def query(handle: str, sql: str, params: list = []) -> SqliteResult
+```
+
+**示例:**
+
+```python
+result = sqlite.query(db, "SELECT * FROM t WHERE id = ?", [1])
+if result.success:
+    logger.info(f"查询到 {len(result.rows)} 条记录")
+else:
+    logger.error(f"查询失败: {result.error}")
+```
+
+#### execute - 执行更新
+
+```python
+def execute(handle: str, sql: str, params: list = []) -> SqliteResult
+```
+
+**示例:**
+
+```python
+sqlite.execute(
+    db,
+    "CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, name TEXT)",
+)
+insert_result = sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["a"])
+if insert_result.success:
+    logger.info(f"插入 ID: {insert_result.insertId}")
+```
+
+### 事务管理
+
+#### beginTransaction / commit / rollback
+
+```python
+def beginTransaction(handle: str) -> bool
+def commit(handle: str) -> bool
+def rollback(handle: str) -> bool
+```
+
+**示例:**
+
+```python
+if sqlite.beginTransaction(db):
+    sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["a"])
+    sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["b"])
+    if not sqlite.commit(db):
+        sqlite.rollback(db)
+```
+
+## 完整使用示例
+
+```python
+from kuaijs import sqlite, file, logger
+
+db = sqlite.open(file.getInternalDir("documents") + "/app.db")
+if not db:
+    logger.error("打开失败")
+else:
+    sqlite.execute(
+        db,
+        "CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, name TEXT)",
+    )
+    sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["a"])
+    r = sqlite.query(db, "SELECT * FROM t WHERE id = ?", [1])
+    if r.success:
+        logger.info(str(r.rows))
+    sqlite.close(db)
+```

package/docs/apipython/zipFile.md

@@ -0,0 +1,117 @@
+# ZIP 模块 (zipFile)
+
+路径必须是绝对路径。只压缩、解压 ZIP；`zip` 只接受目录，不接受文件。
+
+## API 参考
+
+### getFileList - 获取 ZIP 内部文件列表
+
+```python
+from typing import List
+
+def getFileList(path: str) -> List[str]
+```
+
+**参数:**
+
+| 参数名 | 类型  | 是否必填 | 描述             |
+| ------ | ----- | -------- | ---------------- |
+| `path` | `str` | 是       | ZIP 文件绝对路径 |
+
+**返回值:**
+
+| 类型        | 描述                                                         |
+| ----------- | ------------------------------------------------------------ |
+| `List[str]` | 包内文件路径；不含目录项。不是合法 ZIP 时返回空列表 |
+
+**示例:**
+
+```python
+from kuaijs import file, zipFile
+path = file.getInternalDir("documents") + "/a.zip"
+names = zipFile.getFileList(path)
+```
+
+### isZip - 检查是否为合法 ZIP
+
+```python
+def isZip(path: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型  | 是否必填 | 描述         |
+| ------ | ----- | -------- | ------------ |
+| `path` | `str` | 是       | 文件绝对路径 |
+
+**返回值:**
+
+| 类型   | 描述                      |
+| ------ | ------------------------- |
+| `bool` | 能作为 ZIP 打开为 `True` |
+
+**示例:**
+
+```python
+from kuaijs import file, zipFile
+path = file.getInternalDir("documents") + "/a.zip"
+ok = zipFile.isZip(path)
+```
+
+### unzip - 解压到指定目录
+
+目标目录不存在会创建。包内路径必须落在目标目录内，否则失败。
+
+```python
+def unzip(zipPath: str, destDir: str) -> bool
+```
+
+**参数:**
+
+| 参数名    | 类型  | 是否必填 | 描述                 |
+| --------- | ----- | -------- | -------------------- |
+| `zipPath` | `str` | 是       | ZIP 文件绝对路径     |
+| `destDir` | `str` | 是       | 解压目标目录绝对路径 |
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 解压成功为 `True` |
+
+**示例:**
+
+```python
+from kuaijs import file, zipFile
+base = file.getInternalDir("documents")
+zipFile.unzip(base + "/a.zip", base + "/out")
+```
+
+### zip - 压缩目录为 ZIP
+
+包内根条目是该目录名。已有同名 ZIP 文件会先删再写。源路径必须是目录，不能是文件。输出 ZIP 不能落在源目录内。
+
+```python
+def zip(dirPath: str, zipPath: str) -> bool
+```
+
+**参数:**
+
+| 参数名    | 类型  | 是否必填 | 描述                                |
+| --------- | ----- | -------- | ----------------------------------- |
+| `dirPath` | `str` | 是       | 要压缩的目录绝对路径                |
+| `zipPath` | `str` | 是       | 输出 ZIP 绝对路径，不能落在源目录内 |
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 压缩成功为 `True` |
+
+**示例:**
+
+```python
+from kuaijs import file, zipFile
+base = file.getInternalDir("documents")
+zipFile.zip(base + "/out", base + "/out.zip")
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.5.12",
+  "version": "1.5.13",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {