{"id":17650,"library":"fiql-parser","title":"FIQL Parser","description":"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.","status":"maintenance","version":"0.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/vmoebius/node-fiql-parser","tags":["javascript","FIQL","parser"],"install":[{"cmd":"npm install fiql-parser","lang":"bash","label":"npm"},{"cmd":"yarn add fiql-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add fiql-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import { parser } from 'fiql-parser';","symbol":"parser","correct":"import parser from 'fiql-parser';"},{"note":"This is the documented and intended way to import the parser for CommonJS modules. No named exports are provided.","symbol":"parser","correct":"const parser = require('fiql-parser');"},{"note":"There is no `Parser` class or named `Parser` export. The package exports a single function as its default.","wrong":"import { Parser } from 'fiql-parser';","symbol":"Parser","correct":"/* The package exports a direct parser function, not a class or named export. */"}],"quickstart":{"code":"const parser = require('fiql-parser');\n\nconst fiqlQuery = 'title==foo*;(updated=lt=-P1D,author==*bar*)';\n\ntry {\n  const ast = parser.parse(fiqlQuery);\n  console.log('Successfully parsed FIQL query:');\n  // In a real application, you would now traverse the AST\n  // For example, convert it to SQL, MongoDB query, or filter an array.\n  console.log(JSON.stringify(ast, null, 2));\n\n  const anotherQuery = 'price=gt=100;category==electronics';\n  const anotherAst = parser.parse(anotherQuery);\n  console.log('\\nSuccessfully parsed another query:');\n  console.log(JSON.stringify(anotherAst, null, 2));\n\n} catch (error) {\n  console.error('Error parsing FIQL query:', error.message);\n  console.error(error);\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.1.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always wrap calls to `parser.parse(query)` within a `try...catch` block to gracefully handle syntax errors in user-provided query strings.","message":"Being a parser, the library will throw errors for malformed FIQL query strings. Robust applications must implement comprehensive error handling around `parser.parse()` calls.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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).","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.","error":"TypeError: parser.parse is not a function"},{"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.","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.","error":"SyntaxError: Expected \"==\" or \"!=\" or \"=lt=\" or \"=\" or \">=\" or \">\" or \"<=\" or \"<\" but \"@\" found."},{"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');`.","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.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/fiql-parser/index.js"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}