never-jscore 1.0.0__cp38-abi3-win_amd64.whl

never_jscore/__init__.py

@@ -0,0 +1,5 @@
+from .never_jscore import *
+
+__doc__ = never_jscore.__doc__
+if hasattr(never_jscore, "__all__"):
+    __all__ = never_jscore.__all__

never_jscore/__init__.pyi

@@ -0,0 +1,223 @@
+"""
+PyExecJS-RS - 基于 Deno Core 的 JavaScript 运行时
+
+完整支持 Promise 和 async/await，适合 JS 逆向分析。
+"""
+
+from typing import Any, List, Union
+
+class Context:
+    """
+    JavaScript 执行上下文（支持异步）
+
+    每个 Context 包含一个独立的 V8 isolate 和 JavaScript 运行时环境。
+    默认自动等待 Promise，可以无缝调用异步 JavaScript 函数。
+
+    注意：由于 V8 限制，多个 Context 不能交叉使用。
+    建议在一个 Context 中定义所有需要的函数。
+
+    Example:
+        >>> # 同步函数
+        >>> ctx = compile("function add(a, b) { return a + b; }")
+        >>> result = ctx.call("add", [1, 2])
+        >>> print(result)
+        3
+
+        >>> # 异步函数（自动等待）
+        >>> ctx = compile("async function asyncAdd(a, b) { return a + b; }")
+        >>> result = ctx.call("asyncAdd", [5, 3])
+        >>> print(result)
+        8
+    """
+
+    def call(self, name: str, args: List[Any], auto_await: bool = True) -> Any:
+        """
+        调用 JavaScript 函数（支持 Promise）
+
+        Args:
+            name: 函数名称
+            args: 参数列表
+            auto_await: 是否自动等待 Promise（默认 True）
+
+        Returns:
+            函数返回值，自动转换为 Python 对象
+
+        Raises:
+            Exception: 当函数调用失败时
+
+        Example:
+            >>> ctx = compile("async function decrypt(data) { return data.split('').reverse().join(''); }")
+            >>> result = ctx.call("decrypt", ["olleh"])
+            >>> print(result)
+            hello
+        """
+        ...
+
+    def eval(self, code: str, auto_await: bool = True) -> Any:
+        """
+        在当前上下文中执行 JavaScript 代码（支持 Promise）
+
+        Args:
+            code: JavaScript 代码字符串
+            auto_await: 是否自动等待 Promise（默认 True）
+
+        Returns:
+            执行结果，自动转换为 Python 对象
+
+        Raises:
+            Exception: 当代码执行失败时
+
+        Example:
+            >>> # 同步执行
+            >>> ctx = compile("var x = 10;")
+            >>> result = ctx.eval("x * 2")
+            >>> print(result)
+            20
+
+            >>> # Promise（自动等待）
+            >>> result = ctx.eval("Promise.resolve(42)")
+            >>> print(result)
+            42
+        """
+        ...
+
+    def gc(self) -> None:
+        """
+        请求 V8 垃圾回收
+
+        注意：这只是向 V8 发送 GC 请求，V8 会根据自己的策略决定是否执行。
+        在大多数情况下，V8 的自动 GC 已经足够好，无需手动调用。
+        """
+        ...
+
+    def get_stats(self) -> tuple[int]:
+        """
+        获取执行统计信息
+
+        Returns:
+            包含执行次数的元组 (exec_count,)
+        """
+        ...
+
+    def reset_stats(self) -> None:
+        """
+        重置统计信息
+        """
+        ...
+
+def compile(code: str) -> Context:
+    """
+    编译 JavaScript 代码并返回执行上下文
+
+    Args:
+        code: JavaScript 代码字符串
+
+    Returns:
+        Context 对象，可用于调用函数和执行代码
+
+    Raises:
+        Exception: 当代码编译失败时
+
+    Example:
+        >>> ctx = compile('''
+        ...     function greet(name) {
+        ...         return "Hello, " + name + "!";
+        ...     }
+        ... ''')
+        >>> result = ctx.call("greet", ["World"])
+        >>> print(result)
+        Hello, World!
+    """
+    ...
+
+def eval(code: str, auto_await: bool = True) -> Any:
+    """
+    直接执行 JavaScript 代码并返回结果（支持 Promise）
+
+    默认自动等待 Promise。适合执行简单的一次性代码。
+    对于需要多次调用的场景，建议使用 compile() + Context.call()。
+
+    Args:
+        code: JavaScript 代码字符串
+        auto_await: 是否自动等待 Promise（默认 True）
+
+    Returns:
+        执行结果，自动转换为 Python 对象
+
+    Raises:
+        Exception: 当代码执行失败时
+
+    Example:
+        >>> # 同步代码
+        >>> result = eval("1 + 2 + 3")
+        >>> print(result)
+        6
+
+        >>> # Promise（自动等待）
+        >>> result = eval("Promise.resolve(42)")
+        >>> print(result)
+        42
+
+        >>> # async 函数
+        >>> result = eval("(async () => { return await Promise.resolve(100); })()")
+        >>> print(result)
+        100
+    """
+    ...
+
+def compile_file(path: str) -> Context:
+    """
+    从文件读取并编译 JavaScript 代码
+
+    Args:
+        path: JavaScript 文件路径
+
+    Returns:
+        Context 对象
+
+    Raises:
+        Exception: 当文件读取或编译失败时
+
+    Example:
+        >>> # 假设 script.js 包含: function add(a, b) { return a + b; }
+        >>> ctx = compile_file("script.js")
+        >>> result = ctx.call("add", [5, 3])
+        >>> print(result)
+        8
+    """
+    ...
+
+def eval_file(path: str, auto_await: bool = True) -> Any:
+    """
+    从文件读取并执行 JavaScript 代码（支持 Promise）
+
+    Args:
+        path: JavaScript 文件路径
+        auto_await: 是否自动等待 Promise（默认 True）
+
+    Returns:
+        执行结果
+
+    Raises:
+        Exception: 当文件读取或执行失败时
+
+    Example:
+        >>> result = eval_file("script.js")
+        >>> print(result)
+    """
+    ...
+
+# 类型别名
+JSValue = Union[None, bool, int, float, str, List[Any], dict[str, Any]]
+"""JavaScript 值的 Python 类型表示"""
+
+__version__: str
+"""模块版本号"""
+
+__all__ = [
+    "Context",
+    "compile",
+    "eval",
+    "compile_file",
+    "eval_file",
+]

never_jscore-1.0.0.dist-info/METADATA

@@ -0,0 +1,472 @@
+Metadata-Version: 2.4
+Name: never-jscore
+Version: 1.0.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Summary: Fast JavaScript execution in Python using Deno Core (PyExecJS replacement)
+Keywords: javascript,execjs,deno,v8,js,python,rust
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/neverl805/never-jscore
+Project-URL: Repository, https://github.com/neverl805/never-jscore
+
+# never_jscore 中文文档
+
+基于 Deno Core (V8) 的高性能 Python JavaScript 执行引擎。
+
+## 项目特点
+
+- ⚡ **极致性能**:
+  - 使用 Rust + Deno Core (V8 引擎)
+  - thread_local Context 缓存优化
+  - **比 PyExecJS 快 100-300倍**
+  - **与 PyMiniRacer 性能相当，部分场景更快**
+- 🔄 **Promise/async 支持**:
+  - 完整支持 Promise 和 async/await
+  - 自动等待异步结果
+  - **唯一高性能 Promise 方案**（PyMiniRacer 不支持）
+- 📦 **上下文隔离**: 每个 Context 独立的 V8 执行环境，互不干扰
+- 🎯 **PyExecJS 兼容**: API 设计兼容 PyExecJS，可直接替换使用
+- 🧹 **自动内存管理**: 基于 Rust 的自动垃圾回收，无内存泄漏
+- 🛡️ **类型安全**: 提供完整的类型提示（.pyi 文件）
+- 🎮 **JS逆向首选**: 专为 JS 逆向工程优化，支持批量函数调用
+
+## 性能对比
+
+| 测试项目 | never_jscore | PyMiniRacer | PyExecJS |
+|---------|-------------|-------------|----------|
+| 简单计算 | 0.012ms | 0.005ms | 2.3ms |
+| 字符串操作 | **0.004ms** 🏆 | 0.008ms | 2.3ms |
+| 数组操作 | **0.004ms** 🏆 | 0.006ms | 2.3ms |
+| Promise | **✅ 0.003ms** | ❌ 不支持 | ❌ 不支持 |
+
+
+## 安装
+
+### 从源码安装
+
+```bash
+pip install maturin
+maturin develop --release
+```
+
+## 快速开始
+
+### 1. 基本用法
+
+```python
+import never_jscore as execjs
+
+# 一次性执行
+result = execjs.eval("1 + 2 + 3")
+print(result)  # 6
+
+# 字符串操作
+result = execjs.eval("'Hello'.toUpperCase()")
+print(result)  # HELLO
+
+# 数组操作
+result = execjs.eval("[1, 2, 3].map(x => x * 2)")
+print(result)  # [2, 4, 6]
+```
+
+### 2. 编译和调用
+
+```python
+# 编译 JavaScript 代码
+ctx = execjs.compile("""
+    function add(a, b) {
+        return a + b;
+    }
+
+    function greet(name) {
+        return "Hello, " + name + "!";
+    }
+""")
+
+# 调用函数
+print(ctx.call("add", [5, 3]))        # 8
+print(ctx.call("greet", ["World"]))   # Hello, World!
+```
+
+### 3. 异步支持（Promise/async/await）
+
+```python
+# Promise 自动等待
+result = execjs.eval("Promise.resolve(42)")
+print(result)  # 42
+
+# async 函数
+ctx = execjs.compile("""
+    async function fetchData(id) {
+        // 模拟异步操作
+        return await Promise.resolve({id: id, name: "User" + id});
+    }
+""")
+
+result = ctx.call("fetchData", [123])
+print(result)  # {'id': 123, 'name': 'User123'}
+
+# Promise 链
+result = execjs.eval("""
+    Promise.resolve(10)
+        .then(x => x * 2)
+        .then(x => x + 5)
+""")
+print(result)  # 25
+
+# Promise.all 并发
+result = execjs.eval("""
+    Promise.all([
+        Promise.resolve(1),
+        Promise.resolve(2),
+        Promise.resolve(3)
+    ])
+""")
+print(result)  # [1, 2, 3]
+```
+
+### 4. 上下文状态管理
+
+```python
+ctx = execjs.compile("""
+    var counter = 0;
+
+    function increment() {
+        return ++counter;
+    }
+
+    function getCounter() {
+        return counter;
+    }
+""")
+
+print(ctx.call("increment", []))  # 1
+print(ctx.call("increment", []))  # 2
+print(ctx.call("getCounter", []))  # 2
+```
+
+### 5. 复杂对象处理
+
+```python
+ctx = execjs.compile("""
+    function processUser(name, age, tags) {
+        return {
+            name: name,
+            age: age,
+            isAdult: age >= 18,
+            tags: tags,
+            summary: name + ' (' + age + '岁)'
+        };
+    }
+""")
+
+result = ctx.call("processUser", ["张三", 25, ["Python", "JavaScript"]])
+print(result)
+# {
+#     'name': '张三',
+#     'age': 25,
+#     'isAdult': True,
+#     'tags': ['Python', 'JavaScript'],
+#     'summary': '张三 (25岁)'
+# }
+```
+
+### 6. 从文件加载
+
+```python
+# 从文件编译
+ctx = execjs.compile_file("script.js")
+result = ctx.call("myFunction", [arg1, arg2])
+
+# 从文件执行
+result = execjs.eval_file("script.js")
+```
+
+### 7. 性能监控
+
+```python
+ctx = execjs.compile("function compute(n) { return n * n; }")
+
+# 执行多次
+for i in range(100):
+    ctx.call("compute", [i])
+
+# 查看统计
+stats = ctx.get_stats()
+print(f"执行次数: {stats[0]}")  # 100
+
+# 请求垃圾回收（可选）
+ctx.gc()
+
+# 重置统计
+ctx.reset_stats()
+```
+
+## API 参考
+
+### 模块函数
+
+#### `compile(code: str) -> Context`
+
+编译 JavaScript 代码并返回执行上下文。
+
+**参数**:
+- `code`: JavaScript 代码字符串
+
+**返回**: Context 对象
+
+**示例**:
+```python
+ctx = execjs.compile('''
+    function add(a, b) { return a + b; }
+''')
+```
+
+#### `eval(code: str, auto_await: bool = True) -> Any`
+
+一次性执行 JavaScript 代码。
+
+**参数**:
+- `code`: JavaScript 代码字符串
+- `auto_await`: 是否自动等待 Promise（默认 True）
+
+**返回**: 执行结果
+
+**示例**:
+```python
+result = execjs.eval("1 + 2 + 3")  # 6
+result = execjs.eval("Promise.resolve(42)")  # 42
+```
+
+#### `compile_file(path: str) -> Context`
+
+从文件读取并编译 JavaScript 代码。
+
+#### `eval_file(path: str, auto_await: bool = True) -> Any`
+
+从文件读取并执行 JavaScript 代码。
+
+### Context 类
+
+#### `call(name: str, args: list, auto_await: bool = True) -> Any`
+
+调用 JavaScript 函数。
+
+**参数**:
+- `name`: 函数名称
+- `args`: 参数列表
+- `auto_await`: 是否自动等待 Promise（默认 True）
+
+**返回**: 函数返回值
+
+**示例**:
+```python
+result = ctx.call("add", [1, 2])
+result = ctx.call("asyncFunc", [arg], auto_await=True)
+```
+
+#### `eval(code: str, auto_await: bool = True) -> Any`
+
+在当前上下文执行代码。
+
+**参数**:
+- `code`: JavaScript 代码字符串
+- `auto_await`: 是否自动等待 Promise（默认 True）
+
+**返回**: 执行结果
+
+#### `gc() -> None`
+
+请求 V8 垃圾回收。
+
+**注意**: 这只是提示，V8 会根据自己的策略决定是否执行。在大多数情况下无需手动调用。
+
+#### `get_stats() -> tuple[int]`
+
+获取执行统计信息。
+
+**返回**: `(exec_count,)` 执行次数元组
+
+#### `reset_stats() -> None`
+
+重置统计信息。
+
+## 类型转换
+
+Python 和 JavaScript 之间的类型自动转换：
+
+| Python 类型 | JavaScript 类型 | 说明 |
+|------------|----------------|------|
+| None       | null           | 空值 |
+| bool       | boolean        | 布尔值 |
+| int        | number         | 整数 |
+| float      | number         | 浮点数 |
+| str        | string         | 字符串 |
+| list       | Array          | 数组 |
+| dict       | Object         | 对象 |
+
+**示例**:
+```python
+# Python -> JavaScript
+ctx.call("func", [None, True, 42, 3.14, "hello", [1, 2], {"key": "value"}])
+
+# JavaScript -> Python
+result = execjs.eval("{name: 'John', age: 30}")  # dict
+result = execjs.eval("[1, 2, 3]")  # list
+result = execjs.eval("null")  # None
+```
+
+## 使用限制
+
+### 多 Context 限制
+
+⚠️ **重要**: 由于 V8 引擎限制，**不能交叉使用多个 Context 实例**。
+
+```python
+# ❌ 错误用法：交叉使用会崩溃
+ctx1 = execjs.compile("function f1() { return 1; }")
+ctx2 = execjs.compile("function f2() { return 2; }")
+ctx1.call("f1", [])  # OK
+ctx2.call("f2", [])  # OK
+ctx1.call("f1", [])  # ❌ 崩溃！
+
+# ✅ 正确用法：单个 Context 包含所有函数
+ctx = execjs.compile("""
+    function f1() { return 1; }
+    function f2() { return 2; }
+""")
+ctx.call("f1", [])  # OK
+ctx.call("f2", [])  # OK
+ctx.call("f1", [])  # OK
+```
+
+**推荐做法**:
+1. **单 Context 模式**（最推荐）: 将所有函数定义在一个 Context 中
+2. **顺序使用**: 用完一个 Context 再创建下一个
+3. **eval() 模式**: 使用 `execjs.eval()` 进行一次性执行
+
+详见项目文档 `MULTI_CONTEXT_LIMITATION.md`。
+
+## 适用场景
+
+### JavaScript 逆向分析
+
+```python
+# 加载目标网站的加密 JS
+with open("target_crypto.js") as f:
+    js_code = f.read()
+
+ctx = execjs.compile(js_code)
+
+# 调用加密函数
+encrypted = ctx.call("encrypt", [plain_text, key])
+
+# 调用解密函数
+decrypted = ctx.call("decrypt", [cipher_text, key])
+
+# 解析响应
+parsed = ctx.call("parseResponse", [response_data])
+```
+
+### 前端工具集成
+
+```python
+# 使用 JavaScript 工具库
+ctx = execjs.compile_file("lodash.min.js")
+result = ctx.call("_.uniq", [[1, 2, 2, 3, 3, 3]])
+print(result)  # [1, 2, 3]
+```
+
+### 异步数据处理
+
+```python
+ctx = execjs.compile("""
+    async function processBatch(items) {
+        const results = await Promise.all(
+            items.map(async item => {
+                // 模拟异步处理
+                return await Promise.resolve(item * 2);
+            })
+        );
+        return results;
+    }
+""")
+
+result = ctx.call("processBatch", [[1, 2, 3, 4, 5]])
+print(result)  # [2, 4, 6, 8, 10]
+```
+
+## 性能优化建议
+
+1. **重复执行使用 compile()**: 对于需要多次调用的代码，使用 `compile()` 而不是 `eval()`
+2. **批量处理**: 在 JavaScript 端批量处理数据，减少 Python-JS 调用次数
+3. **避免频繁创建 Context**: 尽可能复用同一个 Context
+4. **合理使用 auto_await**: 对于不需要等待的同步代码，设置 `auto_await=False` 可略微提升性能
+
+## 模块化架构
+
+项目采用清晰的模块化设计：
+
+```
+src/
+├── lib.rs        # 模块入口，导出 Python API
+├── context.rs    # Context 实现
+├── runtime.rs    # V8/Tokio runtime 管理
+├── ops.rs        # Deno Core ops 定义
+├── convert.rs    # Python ↔ JavaScript 类型转换
+└── storage.rs    # 结果存储
+```
+
+## 测试
+
+```bash
+# 基本功能测试
+python test_single_ctx.py
+
+# 模块化测试
+python test_modular.py
+```
+
+## 技术细节
+
+- **V8 引擎**: 使用 Deno Core 提供的 V8 bindings
+- **Tokio Runtime**: 全局单线程 runtime，支持异步操作
+- **类型转换**: Python ↔ JSON ↔ JavaScript 三层转换
+- **内存管理**: Rust 自动管理，每 100 次执行提示 GC
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 相关项目
+
+- [PyExecJS](https://github.com/doloopwhile/PyExecJS) - 原 Python ExecJS 实现
+- [Deno](https://github.com/denoland/deno) - 现代 JavaScript/TypeScript 运行时
+- [PyO3](https://github.com/PyO3/pyo3) - Rust Python bindings
+
+## 更新日志
+
+### v0.1.0
+
+- ✅ 基于 Deno Core 的 JavaScript 执行
+- ✅ Promise/async/await 完整支持
+- ✅ Python ↔ JavaScript 类型自动转换
+- ✅ 模块化代码架构
+- ✅ 完整的类型提示支持
+- ✅ 性能监控和统计
+

never_jscore-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+never_jscore-1.0.0.dist-info/METADATA,sha256=WubZM1NBLnlhK5EiJLMQ6etFkurSEkAqYdH036ayIMg,11709
+never_jscore-1.0.0.dist-info/WHEEL,sha256=CG8OzNtm0LMpJ2zhrjswlO8N-965OeMLklsQAG-nMvQ,94
+never_jscore.pyi,sha256=yq9KEl5FtPyUGEpTN4CMX80-mK3RdUhTlV9jZGYySiw,5885
+never_jscore/__init__.py,sha256=840GIz4OE9B6lYUQRN7o0IV9cFEr6-siQBjigt002Ic,131
+never_jscore/__init__.pyi,sha256=yq9KEl5FtPyUGEpTN4CMX80-mK3RdUhTlV9jZGYySiw,5885
+never_jscore/never_jscore.pyd,sha256=mim8VxQXg3SK1SMNPE9j-bNCbwGSb3HCLHDue5rmPgQ,43345920
+never_jscore/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py.typed,sha256=a5K6xx9qkO2ovz5hHopVYtLfXXtb1or--wJahADDHGU,87
+never_jscore-1.0.0.dist-info/RECORD,,

never_jscore-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.6)
+Root-Is-Purelib: false
+Tag: cp38-abi3-win_amd64

never_jscore.pyi

@@ -0,0 +1,223 @@
+"""
+PyExecJS-RS - 基于 Deno Core 的 JavaScript 运行时
+
+完整支持 Promise 和 async/await，适合 JS 逆向分析。
+"""
+
+from typing import Any, List, Union
+
+class Context:
+    """
+    JavaScript 执行上下文（支持异步）
+
+    每个 Context 包含一个独立的 V8 isolate 和 JavaScript 运行时环境。
+    默认自动等待 Promise，可以无缝调用异步 JavaScript 函数。
+
+    注意：由于 V8 限制，多个 Context 不能交叉使用。
+    建议在一个 Context 中定义所有需要的函数。
+
+    Example:
+        >>> # 同步函数
+        >>> ctx = compile("function add(a, b) { return a + b; }")
+        >>> result = ctx.call("add", [1, 2])
+        >>> print(result)
+        3
+
+        >>> # 异步函数（自动等待）
+        >>> ctx = compile("async function asyncAdd(a, b) { return a + b; }")
+        >>> result = ctx.call("asyncAdd", [5, 3])
+        >>> print(result)
+        8
+    """
+
+    def call(self, name: str, args: List[Any], auto_await: bool = True) -> Any:
+        """
+        调用 JavaScript 函数（支持 Promise）
+
+        Args:
+            name: 函数名称
+            args: 参数列表
+            auto_await: 是否自动等待 Promise（默认 True）
+
+        Returns:
+            函数返回值，自动转换为 Python 对象
+
+        Raises:
+            Exception: 当函数调用失败时
+
+        Example:
+            >>> ctx = compile("async function decrypt(data) { return data.split('').reverse().join(''); }")
+            >>> result = ctx.call("decrypt", ["olleh"])
+            >>> print(result)
+            hello
+        """
+        ...
+
+    def eval(self, code: str, auto_await: bool = True) -> Any:
+        """
+        在当前上下文中执行 JavaScript 代码（支持 Promise）
+
+        Args:
+            code: JavaScript 代码字符串
+            auto_await: 是否自动等待 Promise（默认 True）
+
+        Returns:
+            执行结果，自动转换为 Python 对象
+
+        Raises:
+            Exception: 当代码执行失败时
+
+        Example:
+            >>> # 同步执行
+            >>> ctx = compile("var x = 10;")
+            >>> result = ctx.eval("x * 2")
+            >>> print(result)
+            20
+
+            >>> # Promise（自动等待）
+            >>> result = ctx.eval("Promise.resolve(42)")
+            >>> print(result)
+            42
+        """
+        ...
+
+    def gc(self) -> None:
+        """
+        请求 V8 垃圾回收
+
+        注意：这只是向 V8 发送 GC 请求，V8 会根据自己的策略决定是否执行。
+        在大多数情况下，V8 的自动 GC 已经足够好，无需手动调用。
+        """
+        ...
+
+    def get_stats(self) -> tuple[int]:
+        """
+        获取执行统计信息
+
+        Returns:
+            包含执行次数的元组 (exec_count,)
+        """
+        ...
+
+    def reset_stats(self) -> None:
+        """
+        重置统计信息
+        """
+        ...
+
+def compile(code: str) -> Context:
+    """
+    编译 JavaScript 代码并返回执行上下文
+
+    Args:
+        code: JavaScript 代码字符串
+
+    Returns:
+        Context 对象，可用于调用函数和执行代码
+
+    Raises:
+        Exception: 当代码编译失败时
+
+    Example:
+        >>> ctx = compile('''
+        ...     function greet(name) {
+        ...         return "Hello, " + name + "!";
+        ...     }
+        ... ''')
+        >>> result = ctx.call("greet", ["World"])
+        >>> print(result)
+        Hello, World!
+    """
+    ...
+
+def eval(code: str, auto_await: bool = True) -> Any:
+    """
+    直接执行 JavaScript 代码并返回结果（支持 Promise）
+
+    默认自动等待 Promise。适合执行简单的一次性代码。
+    对于需要多次调用的场景，建议使用 compile() + Context.call()。
+
+    Args:
+        code: JavaScript 代码字符串
+        auto_await: 是否自动等待 Promise（默认 True）
+
+    Returns:
+        执行结果，自动转换为 Python 对象
+
+    Raises:
+        Exception: 当代码执行失败时
+
+    Example:
+        >>> # 同步代码
+        >>> result = eval("1 + 2 + 3")
+        >>> print(result)
+        6
+
+        >>> # Promise（自动等待）
+        >>> result = eval("Promise.resolve(42)")
+        >>> print(result)
+        42
+
+        >>> # async 函数
+        >>> result = eval("(async () => { return await Promise.resolve(100); })()")
+        >>> print(result)
+        100
+    """
+    ...
+
+def compile_file(path: str) -> Context:
+    """
+    从文件读取并编译 JavaScript 代码
+
+    Args:
+        path: JavaScript 文件路径
+
+    Returns:
+        Context 对象
+
+    Raises:
+        Exception: 当文件读取或编译失败时
+
+    Example:
+        >>> # 假设 script.js 包含: function add(a, b) { return a + b; }
+        >>> ctx = compile_file("script.js")
+        >>> result = ctx.call("add", [5, 3])
+        >>> print(result)
+        8
+    """
+    ...
+
+def eval_file(path: str, auto_await: bool = True) -> Any:
+    """
+    从文件读取并执行 JavaScript 代码（支持 Promise）
+
+    Args:
+        path: JavaScript 文件路径
+        auto_await: 是否自动等待 Promise（默认 True）
+
+    Returns:
+        执行结果
+
+    Raises:
+        Exception: 当文件读取或执行失败时
+
+    Example:
+        >>> result = eval_file("script.js")
+        >>> print(result)
+    """
+    ...
+
+# 类型别名
+JSValue = Union[None, bool, int, float, str, List[Any], dict[str, Any]]
+"""JavaScript 值的 Python 类型表示"""
+
+__version__: str
+"""模块版本号"""
+
+__all__ = [
+    "Context",
+    "compile",
+    "eval",
+    "compile_file",
+    "eval_file",
+]

py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This file indicates that the package supports type hints