prql-js
JavaScript bindings for prql-compiler
.
Installation
npm install prql-js
Usage
Currently these functions are exposed
function compile(prql_query: string, options?: CompileOptions): string;
function prql_to_pl(prql_query: string): string;
function pl_to_rq(pl_json: string): string;
function rq_to_sql(rq_json: string): string;
From NodeJS
Direct usage
const prqljs = require("prql-js");
const sql = prqljs.compile(`from employees | select first_name`);
console.log(sql.sql);
Template literal
const prqljs = require("prql-js");
const prql = (string) => prqljs.compile(string[0] || "");
const sql = prql`from employees | select first_name`;
console.log(sql.sql);
Template literal with newlines
const prqljs = require("prql-js");
const prql = (string) => prqljs.compile(string[0] || "");
const sql = prql`
from employees
select first_name
`;
console.log(sql.sql);
From a Browser
<html>
<head>
<script src="./node_modules/prql-js/dist/web/prql_js.js"></script>
<script>
const { compile } = wasm_bindgen;
async function run() {
await wasm_bindgen("./node_modules/prql-js/dist/web/prql_js_bg.wasm");
const sql = compile("from employees | select first_name");
console.log(sql);
}
run();
</script>
</head>
<body></body>
</html>
From a Framework or a Bundler
import compile from "prql-js/dist/bundler";
const sql = compile(`from employees | select first_name`);
console.log(sql);
Errors
Errors are returned as following object, serialized as a JSON array:
interface ErrorMessage {
/// Plain text of the error
reason: string;
/// A list of suggestions of how to fix the error
hint: string | null;
/// 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];
}
These errors can be caught as such:
try {
const sql = prqlJs.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);
}
Development
Build:
npm run build
This builds Node, bundler and web packages in the dist
path.
Test:
npm test
Notes
- This uses
wasm-pack
to generate bindings1. - We’ve added an
npm
layer on top of the usual approach of just usingwasm-pack
, so we can distribute a single package with targets ofnode
,bundler
andno-modules
— somewhat inverting the approach recommended bywasm-pack
. The build instruction goes in abuild
script, rather than apack
script.
1
Though we would be very open to other approaches, given wasm-pack does not
seem maintained, and we're eliding many of its features to build for three
targets.