prqlc-js

JavaScript bindings for prqlc.

Installation

npm install prqlc

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_prql(pl_json: string): string; function pl_to_rq(pl_json: string): string; function rq_to_sql(rq_json: string): string;

From Node.js

Direct usage

const prqlc = require("prqlc"); const sql = prqlc.compile(`from employees | select first_name`); console.log(sql);

Options

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);

Template literal

const prqlc = require("prqlc"); const prql = (string) => prqlc.compile(string[0] || ""); const sql = prql`from employees | select first_name`; console.log(sql);

Template literal with newlines

const prqlc = require("prqlc"); const prql = (string) => prqlc.compile(string[0] || ""); const sql = prql` from employees select first_name `; console.log(sql);

From a browser

<html> <head> <script type="module"> import init, { compile } from "./dist/web/prql_js.js"; await init(); const sql = compile("from employees | select first_name"); console.log(sql); </script> </head> <body></body> </html>

From a framework or a bundler

import compile from "prqlc/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 { /// 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 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

By default the wasm binaries are optimized on each run, even if the underlying code hasn’t changed, which can be slow. For a lower-latency dev loop, pass --profile=dev to npm install for a faster, less optimized build.

npm install prqlc --profile=dev

Notes

  • This uses wasm-pack to generate bindings1.
  • We’ve added an npm layer on top of the usual approach of just using wasm-pack, so we can distribute a single package with targets of node, bundler and no-modules — somewhat inverting the approach recommended by wasm-pack. The build instruction goes in a build script, rather than a pack 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. See <https://github.com/PRQL/prql/issues/1836> for more details.