prqlc-js：在 Node.js 与浏览器中调用 PRQL 编译器（WASM JavaScript 绑定完整指南）

后端【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址https://gitcode.com/gh_mirrors/pr/prql点击查看免费下载导读prqlc-js是 PRQL 项目官方提供的 JavaScript/TypeScript 绑定它将 Rust 编写的prqlc编译器编译为 WebAssembly从而让开发者能在 Node.js 服务端、现代浏览器以及各类前端框架中直接完成「PRQL → SQL」的编译。读完本文你将掌握prqlcnpm 包的安装、compile与管道函数prql_to_pl、pl_to_rq、rq_to_sql的使用、CompileOptions三个核心参数target、format、signature_comment的语义与优先级以及编译错误的结构化解析方法。什么是 prqlc-jsPRQLPipelined Relational Query Language是一种面向数据转换的现代语言定位是简单、强大、管道化的 SQL 替代品。而prqlc是它的 Rust 编译器负责把 PRQL 源码解析为中间表示并最终生成 SQL。prqlc-js正是这条编译管线在 JavaScript 生态中的桥接层它通过wasm-bindgen把prqlc编译成wasm32目标见 Cargo.toml 中的cfg(target_familywasm)依赖声明再以 npm 包的形式对外分发。从源码结构看src/lib.rs整个绑定层只暴露了一组薄封装函数内部全部委托给 prqlc/prqlc/src/lib.rs 中 Rust 侧同名的编译入口例如compileRust 侧实现在 lib.rs 第 189 行内部依次执行parser::parse→semantic::resolve_and_lower→sql::compile三个阶段。因此 JS 调用方获得的能力与 Rust 原生 API 完全一致只是输入输出以字符串 / JSON 的形式在 WASM 边界传递。安装prqlc-js以prqlc为包名发布在 npm registry 上见 package.json安装方式与其他 npm 包无异npm install prqlc该包同时声明了 Node 与浏览器两套入口main指向dist/node/prqlc_js.jsNode.js CommonJS 入口browser指向dist/web/prqlc_js.js浏览器 ESM 入口types指向dist/node/prqlc_js.d.tsTypeScript 类型声明。files字段仅发布dist/**/*与package.json因此 npm 包体积只包含编译好的 WASM 产物与绑定代码。快速开始在 Node.js 中编译 PRQLcompile函数接受一段 PRQL 字符串返回对应的 SQL 字符串。最直接的用法如下const prqlc require(prqlc); const sql prqlc.compile(from employees | select first_name); console.log(sql);compile的完整签名TypeScript 视角function compile(prql_query: string, options?: CompileOptions): string;当查询跨多行时同样直接传入模板字符串即可PRQL 的管道语法天然适合这种写法const prqlc require(prqlc); const sql prqlc.compile( from employees select first_name ); console.log(sql);对应地Rust 侧compile的原型为fn compile(prql_query: str, options: OptionCompileOptions) - OptionString见 src/lib.rs 第 9 行Option参数在 JS 中表现为可省略省略时自动回退到CompileOptions::default()。使用 CompileOptions 控制编译行为通过new prqlc.CompileOptions()构造选项对象可以控制 SQL 生成的方言、格式与注释行为const opts new prqlc.CompileOptions(); opts.target sql.mssql; opts.format false; opts.signature_comment false; const sql prqlc.compile(from employees | take 10, opts); console.log(sql);三个字段的语义如下字段类型默认值说明targetstring空字符串目标 SQL 方言如sql.mssql、sql.sqlite、sql.duckdb、sql.postgres留空表示sql.any此时使用查询头prql target:...指定的方言formatbooleantrue是否将生成的 SQL 交给格式化器美化拆分成多行、整理缩进与间距signature_commentbooleantrue是否在生成的 SQL 末尾追加编译器的签名注释包含目标方言信息等这三个字段在 Rust 侧一一对应src/lib.rs 第 60-74 行并通过TryFromCompileOptions for prqlc::Options第 116-137 行转换为编译器内部使用的 Options 结构。target 的优先级与校验规则target的处理逻辑在绑定层是显式优先、留空回退若opts.target为空字符串则视为未设置使用Target::default()即sql.any最终方言从 PRQL 查询头部的prql target:sql.xxx指令解析若opts.target非空则必须能被Target::from_str成功解析否则直接抛出异常而不是静默回退到通用 SQL——源码注释明确说明这是为了防止sql.postgrez之类的拼写错误悄悄编译成泛化 SQL见 src/lib.rs 第 119-127 行。测试 tests/test_all.mjs 对这套规则做了完整覆盖CompileOptions显式设置target时即使 PRQL 头部写了不同的方言也以选项为准CompileOptions should be preferred...第 56-72 行未设置target时回退使用查询头方言should treat an unset target as sql.any第 83-96 行传入未知方言如sql.postgrez会抛出包含该字符串的错误第 74-81 行。Rust 侧Target枚举只支持Sql(OptionDialect)一种变体Target::names()会生成sql.any加全部方言变体的完整列表见 prqlc/prqlc/src/lib.rs 第 220-240 行。这些方言名同时也是prqlc-js暴露的get_targets()函数的返回值来源见 src/lib.rs 第 77-82 行可用于在 UI 中动态渲染方言下拉框。进阶 API分段使用编译管线除了端到端的compileprqlc-js还暴露了四个中间步骤函数便于调试或在编译链路中注入自定义逻辑function prql_to_pl(prql_query: string): string; function pl_to_prql(pl_json: string): string; function pl_to_rq(pl_json: string): string; function rq_to_sql(rq_json: string): string;对应 Rust 侧的调用链src/lib.rs 第 20-55 行prql_to_pl(prql_query)PRQL 文本 → PL管道语言中间表示JSON。实现为prqlc::prql_to_pl后接json::from_pl序列化pl_to_prql(pl_json)PL JSON → PRQL 文本反向格式化的逆操作先json::to_pl反序列化再调用pl_to_prqlpl_to_rq(pl_json)PL JSON → RQ关系查询中间表示JSON中间经过pl_to_rq与json::from_rqrq_to_sql(rq_json)RQ JSON → SQL此步骤以默认Options编译不接收用户自定义选项。测试中prql_to_pl对合法 PRQL 返回可被JSON.parse的字符串、对非法输入抛错tests/test_all.mjs 第 99-107 行验证了这些 API 的输入输出约定。从仓库结构看PL 与 RQ 的具体数据结构定义分别在 prqlc/prqlc/src/ir/pl 与 prqlc/prqlc/src/ir/rq 目录下。在浏览器中直接使用prqlc-js的 WASM 产物同样面向浏览器设计。最轻量的方式是作为 ES Module 引入dist/web/prqlc_js.js并先await init()完成 WASM 实例初始化html head script typemodule import init, { compile } from ./dist/web/prqlc_js.js; await init(); const sql compile(from employees | select first_name); console.log(sql); /script /head body/body /html这种场景特别适合构建纯前端的数据工具仓库中的 web/playground在线 PRQL Playground正是以file:../../prqlc/bindings/js的方式本地依赖该包见 web/playground/package.json 第 21 行配合 DuckDB WASM 在浏览器端完成 PRQL 编译与查询执行项目官方文档 web/book/src/project/bindings/javascript.md 也直接通过{{#include}}引入了本 README作为 JavaScript 绑定篇的正文。在框架或打包器Bundler中使用如果项目使用 Vite、Webpack 等打包工具应从专门为 bundler 场景生成的入口导入以获得正确的模块解析与 tree-shaking 支持import { compile } from prqlc/dist/bundler; const sql compile(from employees | select first_name); console.log(sql);这与package.json中browser字段指向dist/web的约定相辅相成node、web、bundler三个产物目录分别服务于三种运行时。错误处理结构化的编译诊断与很多把错误编码进字符串的方案不同prqlc-js将编译错误序列化为 JSON 数组后随异常抛出调用方可以解析出结构化的诊断信息。错误对象的 TypeScript 接口如下interface ErrorMessage { /// Message kind. Currently only Error is implemented. kind: Error | Warning | Lint; /// Machine-readable identifier of the error code: string | null; /// Plain text of the error reason: string; /// A list of suggestions of how to fix the error hints: string[]; /// Character offset of error origin within a source file span: [number, number] | null; /// Annotated code, containing cause and hints. display: string | null; /// Line and column number of error origin within a source file location: SourceLocation | null; } /// Location within the source file. /// Tuples contain: /// - line number (0-based), /// - column number within that line (0-based), interface SourceLocation { start: [number, number]; end: [number, number]; }关键字段速查kind错误类别当前仅实现Errorcode机器可读的错误码例如E0001语法错误reason纯文本的错误原因描述hints修复建议列表span错误在源文件中的字符偏移区间display带注解的代码片段含原因与提示多行文本location错误起止的行号与列号均为 0-based即行号从 0 开始计数。捕获方式如下try { const sql prqlc.compile(from employees | foo first_name); } catch (error) { const errorMessages JSON.parse(error.message).inner; console.log(errorMessages[0].display); console.log(errorMessages[0].location); }注意异常信息中的 JSON 结构带有一个inner键实际的ErrorMessage[]数组位于JSON.parse(error.message).inner。这一序列化行为源于绑定层return_or_throw的实现——编译失败时调用wasm_bindgen::throw_str(e.to_json())将prqlc::ErrorMessages内部为inner数组整体 JSON 化后作为异常消息抛出见 src/lib.rs 第 139-151 行。测试同样验证了错误结构display字段包含换行多行注解、reason为单行纯文本、code可精确匹配E0001tests/test_all.mjs 第 134-158 行。此外当启用console_error_panic_hookfeature默认开启见 Cargo.toml时WASM 内部的 panic 也会以console.error的形式输出便于开发期排查。本地开发与构建在仓库内对prqlc-js做二次开发时常用的命令如下npm run build该命令会依次产出 Node、bundler、web 三个平台的构建产物全部放入dist目录。实际构建脚本定义在 package.json底层依次执行build:nodewasm-pack build --target nodejs --out-dir dist/nodebuild:webwasm-pack build --target web --out-dir dist/webbuild:bundlerwasm-pack build --target bundler --out-dir dist/bundler。运行测试npm test测试框架为 mocha chai见devDependencies测试文件位于 tests/test_all.mjs直接加载dist/node/prqlc_js.js进行断言。加速开发循环PROFILE 环境变量默认情况下每次构建都会对 WASM 二进制做优化wasm-pack默认--release级别即使底层代码没有变化也很耗时。开发阶段可以设置PROFILE环境变量为dev以获得更快但优化程度较低的构建PROFILEdev npm run build其原理是构建脚本中--${PROFILE}的插值PROFILEdev时等价于wasm-pack build --dev。构建原理与注意事项绑定层基于wasm-pack生成README 脚注同时指出wasm-pack维护活跃度有限团队对替代方案持开放态度并倾向裁减其部分特性以构建三个目标产物项目在wasm-pack的常规用法之上叠加了一层 npm 封装不采用每个目标一个包的推荐做法而是把 Node、bundler、web 三个目标打包进同一个 npm 包的dist子目录构建指令写在buildscript 而非packscript 中见 package.json——这正是一个包、三入口设计得以实现的关键绑定层的 Rust 代码整体受#![cfg(target_family wasm)]约束src/lib.rs 第 1 行意味着该 crate 只在 WASM 目标下编译Rust 原生侧并不包含这些绑定代码CompileOptions中format与signature_comment的默认值均为truesrc/lib.rs 第 84-92 行与 Rust 侧 Options::default() 保持一致但绑定层强制使用DisplayOptions::Plain无 ANSI 颜色以适配终端之外的调用环境。小结prqlc-js用一个 npm 包同时覆盖了 Node.js、浏览器与打包器三种运行场景compile负责端到端编译四个管道函数暴露中间表示CompileOptions提供方言/格式/注释的精细控制而结构化错误对象则让 PRQL 的诊断信息可以被程序化消费。结合 tests/test_all.mjs 中覆盖方言优先级、未知方言报错、错误码解析等场景的用例以及 web/playground 这一真实消费方你可以放心地将它接入自己的数据工具链。赞分享后端【免费下载链接】prqlPRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement项目地址https://gitcode.com/gh_mirrors/pr/prql点击查看免费下载相关推荐rclone 编译为 WASM在浏览器中以 JavaScript 库方式调用 rclone RC 接口rclone 编译为 WASM在浏览器中以 JavaScript 库方式调用 rclone RC 接口 rclone 的 fs/rc/js/ https://CLI数据同步对象存储Rome JavaScript Bindings 实战指南在 Node.js 与浏览器中通过 WASM 调用 Rome 的格式化与 Lint 能力Rome JavaScript Bindings 实战指南在 Node.js 与浏览器中通过 WASM 调用 Rome 的格式化与 Lint 能力 rome开发工具CLILint格式化静态分析代码质量构建工具Lattigo加密安全指南理解IND-CPA与CPA-D安全机制的3个关键要点Lattigo加密安全指南理解IND CPA与CPA D安全机制的3个关键要点 Lattigo是一个基于格的多方同态加密Go语言库为开发者提供了强大的加密工密码学创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考