prqlc-js

prqlc-js

JavaScript bindings for prqlc.

Installation

1. npm install prqlc

Usage

Currently these functions are exposed

1. function compile(prql_query: string, options?: CompileOptions): string;

3. function prql_to_pl(prql_query: string): string;

5. function pl_to_prql(pl_json: string): string;

7. function pl_to_rq(pl_json: string): string;

9. function rq_to_sql(rq_json: string): string;

From Node.js

Direct usage

1. const prqlc = require("prqlc");

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

Options

1. const opts = new prqlc.CompileOptions();
2. opts.target = "sql.mssql";
3. opts.format = false;
4. opts.signature_comment = false;

6. const sql = prqlc.compile(`from employees | take 10`, opts);
7. console.log(sql);

Template literal

1. const prqlc = require("prqlc");
2. const prql = (string) => prqlc.compile(string[0] || "");

4. const sql = prql`from employees | select first_name`;
5. console.log(sql);

Template literal with newlines

1. const prqlc = require("prqlc");
2. const prql = (string) => prqlc.compile(string[0] || "");

4. const sql = prql`
5. from employees
6. select first_name
7. `;
8. console.log(sql);

From a browser

1. <html>
2. <head>
3. <script type="module">
4. import init, { compile } from "./dist/web/prql_js.js";
5. await init();

7. const sql = compile("from employees | select first_name");
8. console.log(sql);
9. </script>
10. </head>

12. <body></body>
13. </html>

From a framework or a bundler

1. import compile from "prqlc/dist/bundler";

3. const sql = compile(`from employees | select first_name`);
4. console.log(sql);

Errors

Errors are returned as following object, serialized as a JSON array:

1. interface ErrorMessage {
2. /// Message kind. Currently only Error is implemented.
3. kind: "Error" | "Warning" | "Lint";
4. /// Machine-readable identifier of the error
5. code: string | null;
6. /// Plain text of the error
7. reason: string;
8. /// A list of suggestions of how to fix the error
9. hint: string | null;
10. /// Character offset of error origin within a source file
11. span: [number, number] | null;

13. /// Annotated code, containing cause and hints.
14. display: string | null;
15. /// Line and column number of error origin within a source file
16. location: SourceLocation | null;
17. }

19. /// Location within the source file.
20. /// Tuples contain:
21. /// - line number (0-based),
22. /// - column number within that line (0-based),
23. interface SourceLocation {
24. start: [number, number];

26. end: [number, number];
27. }

These errors can be caught as such:

1. try {
2. const sql = prqlJs.compile(`from employees | foo first_name`);
3. } catch (error) {
4. const errorMessages = JSON.parse(error.message).inner;

6. console.log(errorMessages[0].display);
7. console.log(errorMessages[0].location);
8. }

Development

Build:

1. npm run build

This builds Node, bundler and web packages in the dist path.

Test:

1. 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.

1. 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
2. seem maintained, and we're eliding many of its features to build for three
3. targets. See <https://github.com/PRQL/prql/issues/1836> for more details.

11.4. JavaScript