fiql-parser

library1.0jsnpmunverified

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.

serialization

npm install fiql-parser

github ↗package ↗

INSTALL

IMPORT

SIG · FIQL-PARSER

fiql-parser

serializationjavascriptv1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parser

✓ import parser from 'fiql-parser';

✗ 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

✓ /* The package exports a direct parser function, not a class or named export. */

✗ import { Parser } from 'fiql-parser';

There is no `Parser` class or named `Parser` export. The package exports a single function as its default.

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

Debug

Known issues

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

affects: <=0.1.5

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

affects: >=0.1.0

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

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: parser.parse is not a function

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

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

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.

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

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');`.

Upgrade

Version history

1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/vmoebius/node-fiql-parser ↗

packagehttps://www.npmjs.com/package/fiql-parser ↗