FIQL Parser

0.1.5 verified Thu Apr 23 auth: no javascript maintenance

The `fiql-parser` library by `vmoebius` provides a foundational parser for FIQL (Feed Item Query Language) expressions within Node.js environments. FIQL is a URI-friendly syntax primarily designed for filtering entries in syndicated feeds, and it serves as the basis for the more comprehensive RSQL (RESTful Service Query Language) commonly employed in RESTful API query parameters. Currently at version `0.1.5`, this package saw its most recent publish around late 2025/early 2026. Its low version number suggests a lightweight or early-stage development focus, offering a direct implementation of the FIQL grammar for JavaScript applications. While a formal release cadence is not established, the recent publishing activity indicates a minimal level of ongoing attention or re-publishing, differentiating it as a dedicated FIQL parsing utility.

Common errors

error TypeError: parser.parse is not a function ↓

cause Attempting to call `.parse()` on an undefined or incorrect import. This often happens when trying a named import for a package that provides a default export, especially in ESM contexts.

fix

Ensure you are using the correct CommonJS require syntax: const parser = require('fiql-parser'); or, if using ESM with bundler support, import parser from 'fiql-parser'; (though CJS is the primary documented method).

error SyntaxError: Expected "==" or "!=" or "=lt=" or "=" or ">=" or ">" or "<=" or "<" but "@" found. ↓

cause The input FIQL query string contains a syntax error, meaning it does not conform to the expected FIQL grammar rules at the indicated position.

fix

Review the FIQL query string for typos, incorrect operators, or missing delimiters. Refer to the FIQL specification (e.g., RFC 4287 extensions or draft-nottingham-atompub-fiql-00) for correct syntax.

error ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/fiql-parser/index.js ↓

cause This error occurs when a Node.js ESM module tries to `require()` a package that is itself an ES Module, or in this case, a CJS module being loaded in an ESM context without proper interoperability setup.

fix

Ensure your project is configured correctly for CommonJS/ESM interoperability, or if your project is purely ESM, use dynamic import('fiql-parser') or consider an alternative parser with native ESM support. For older Node.js versions or strict ESM, sticking to CJS for this package is safest: const parser = require('fiql-parser');.

Warnings

gotcha The package is at a low major version (0.1.5), indicating that the API might not be fully stable and could introduce breaking changes in minor versions, or may lack advanced features found in more mature RSQL/FIQL parsers. ↓

fix Always pin the exact version in `package.json` (e.g., `"fiql-parser": "0.1.5"`) and thoroughly test when updating to new versions, even patch releases.

gotcha This library is primarily designed for CommonJS (`require`) environments. While modern bundlers might polyfill or adapt, direct ESM (`import`) usage is not explicitly documented or guaranteed to work without configuration or wrapper code. ↓

fix For CommonJS, use `const parser = require('fiql-parser');`. For ESM projects, consider a CommonJS wrapper or check if your build tool handles CJS interoperability. Alternative, more modern RSQL/FIQL parsers often offer native ESM support.

gotcha Being a parser, the library will throw errors for malformed FIQL query strings. Robust applications must implement comprehensive error handling around `parser.parse()` calls. ↓

fix Always wrap calls to `parser.parse(query)` within a `try...catch` block to gracefully handle syntax errors in user-provided query strings.

Install

npm install fiql-parser

yarn add fiql-parser

pnpm add fiql-parser

Imports

parser
wrong
```
import { parser } from 'fiql-parser';
```
correct
```
import parser from 'fiql-parser';
```
This package primarily uses a CommonJS default export. While direct ESM default import might work in some bundlers, the original intent and explicit README example use CommonJS `require`.
parser
```
const parser = require('fiql-parser');
```
This is the documented and intended way to import the parser for CommonJS modules. No named exports are provided.
Parser
wrong
```
import { Parser } from 'fiql-parser';
```
correct
```
/* The package exports a direct parser function, not a class or named export. */
```
There is no `Parser` class or named `Parser` export. The package exports a single function as its default.

Quickstart

This example demonstrates how to import the `fiql-parser` and parse two sample FIQL query strings, logging the resulting Abstract Syntax Tree (AST). It includes basic error handling for malformed queries.

const parser = require('fiql-parser');

const fiqlQuery = 'title==foo*;(updated=lt=-P1D,author==*bar*)';

try {
  const ast = parser.parse(fiqlQuery);
  console.log('Successfully parsed FIQL query:');
  // In a real application, you would now traverse the AST
  // For example, convert it to SQL, MongoDB query, or filter an array.
  console.log(JSON.stringify(ast, null, 2));

  const anotherQuery = 'price=gt=100;category==electronics';
  const anotherAst = parser.parse(anotherQuery);
  console.log('\nSuccessfully parsed another query:');
  console.log(JSON.stringify(anotherAst, null, 2));

} catch (error) {
  console.error('Error parsing FIQL query:', error.message);
  console.error(error);
}