JQL2SQL

0.0.14 verified Fri May 01 auth: no javascript

JQL2SQL (v0.0.14) transpiles JQL (Jira Query Language) into parameterized SQL queries for safe, flexible searching. It uses a custom parser built with nearley to convert JQL to an AST, then transpiles to SQL WHERE clauses. This package is in early development with irregular releases. Key differentiators: focused solely on JQL-to-SQL conversion, no query execution, and aims for SQL injection safety by generating parameterized queries. Alternatives like jql-parser or custom lexers require more boilerplate.

Common errors

error TypeError: jql2sql is not a function ↓

cause Attempted to use CommonJS require on an ESM-only package or incorrect import.

fix

Use import jql2sql from 'jql2sql' or in CommonJS: const { default: jql2sql } = require('jql2sql');

error SyntaxError: Unexpected token: operator 'does' ↓

cause JQL operator 'does' is not supported. Only 'is', '=', '!=', '<', '>', etc.

fix

Replace 'does' with 'is' or '=' depending on intended meaning.

error Error: Unsupported function: myfunction ↓

cause Extended functions are not yet implemented.

fix

Remove custom functions from JQL string or wait for feature update.

Warnings

breaking Version 0.x: API may change without notice; breaking changes expected. ↓

fix Pin to exact version and test upgrades thoroughly.

deprecated Function 'myfunction(arg1, arg2)' in JQL is documented but not yet supported; trying to use it will throw an error. ↓

fix Avoid custom functions or wait for future release.

gotcha The `is` operator maps to SQL LIKE with wildcards, not `=`. For exact match use `field = 'value'`. ↓

fix Use `=` for exact match, `is` for partial match (adds %).

gotcha Field names and values are case-insensitive? Check actual behavior: `select count(*) from items where ${sql}` may need quote handling. ↓

fix Verify SQL dialect compatibility; test against your DB.

Install

npm install jql2sql

yarn add jql2sql

pnpm add jql2sql

Imports

default
wrong
```
const jql2sql = require('jql2sql');
```
correct
```
import jql2sql from 'jql2sql';
```
Package exports a default function. ESM is preferred; CommonJS require works but may not be fully supported.
{ transpile }
wrong
```
import transpile from 'jql2sql';
```
correct
```
import { transpile } from 'jql2sql';
```
Named export is available (undocumented). Ensure correct destructured import.
JQLParser
wrong
```
import { JQLParser } from 'jql2sql';
```
correct
```
import JQLParser from 'jql2sql/parser';
```
The parser is exported as a separate entry point. Not part of main export.

Quickstart

Transpile a JQL string into a parameterized SQL WHERE clause and parameters array.

import jql2sql from 'jql2sql';

const jql = "(item is 'good' or item is 'so so') and date < now()";
const { sql, params } = jql2sql(jql);

console.log(sql);
// Output: (ITEM LIKE ? OR ITEM LIKE ?) AND DATE < NOW()
console.log(params);
// Output: ['%good%', '%so so%']

// Use with parameterized query in DB driver:
// db.query(sql, params).then(rows => ...);