OData v4 Parser

Common errors

• require is not defined in ESM module scope

  cause Attempting to use `require()` in an ES module (`.mjs` file or `type: "module"` in `package.json`).
  fix Change your module to CommonJS (`.cjs` file or remove `type: "module"`) or use a tool like `createRequire` for legacy modules (not recommended for an abandoned package). Better yet, migrate to a modern OData parser that supports ESM.

• TypeError: parser.filter is not a function

  cause The `odata-v4-parser` object returned by `require` might not have the expected methods, or there's a misunderstanding of the API for this specific version.
  fix Ensure you are calling the methods on the correct `parser` object, as demonstrated in the quickstart. Inspect `console.log(parser)` to see its available properties. If the methods are truly missing, the library might not support the intended parsing action or the version is corrupted.

• Error: Expected `(` or whitespace but `$` found.

  cause The parser might not correctly handle certain valid OData v4 syntax or extended features due to its age and lack of updates, leading to unexpected parsing failures for seemingly correct queries.
  fix Simplify your OData query string to isolate the problematic part. Refer to the OData v4 specification and cross-reference with known limitations of older parsers. This package may not support all aspects of the full OData v4 grammar.

Warnings

• breaking The `odata-v4-parser` package is effectively abandoned, with its last publish dating back several years. This means it lacks updates for new OData v4 specification features, compatibility with recent Node.js versions, and critical security patches.
  Fix: Migrate to an actively maintained OData parser library, such as `@odata/parser` or a more recent community fork like `@jwstott/odata-v4-parser` if robust OData parsing is critical for your application.
• gotcha This package was developed in a CommonJS-first era. Attempting to use ESM `import` statements will result in runtime errors in modern Node.js environments configured for ESM, or if `type: module` is set in `package.json`.
  Fix: Always use `const parser = require('odata-v4-parser');` for importing the library in environments where it is still supported. For ESM projects, consider a modern alternative.
• gotcha Due to its abandoned status, `odata-v4-parser` may contain unfixed security vulnerabilities, including potential regex denial-of-service (ReDoS) attacks or other input-related exploits common in parsing libraries.
  Fix: Avoid using this library in production environments where security is a concern. If unavoidable, strictly sanitize all OData query inputs before passing them to the parser.
• gotcha The internal Abstract Syntax Tree (AST) structure generated by `odata-v4-parser` is specific to this legacy version and may differ significantly from ASTs generated by other OData parsers or newer versions. There is no official, comprehensive documentation for the AST structure.
  Fix: Thoroughly inspect the generated AST by logging it and write extensive unit tests if you rely on its specific structure. Be prepared for manual migration if switching to a different parser.

Install

• npm install odata-v4-parser npm
• yarn add odata-v4-parser yarn
• pnpm add odata-v4-parser pnpm

Imports

• parser
  wrong:

  import parser from 'odata-v4-parser'

  correct:

  const parser = require('odata-v4-parser');

  The package is CommonJS-first and effectively abandoned. Direct `require` is the intended import pattern for v0.1.29.
• parser.parse
  wrong:

  import { parse } from 'odata-v4-parser'

  correct:

  const parser = require('odata-v4-parser');
  const ast = parser.parse('$filter=...');

  The `parse` method is accessed directly from the default-exported parser object, handling full OData URI segments.
• parser.filter
  wrong:

  import { filter } from 'odata-v4-parser'

  correct:

  const parser = require('odata-v4-parser');
  const filterAst = parser.filter('Title eq \'Article1\'');

  The `filter` method provides a specific entry point for parsing $filter expressions, as shown in the package's GitHub README.

Quickstart

Demonstrates parsing OData $filter expressions and full OData URI query strings into an Abstract Syntax Tree (AST).

const parser = require('odata-v4-parser');

// Example 1: Parsing a simple $filter expression
const filterQuery = "$filter=Name eq 'John Doe' and Age gt 30";
try {
  const filterAst = parser.filter(filterQuery);
  console.log('Parsed Filter AST:', JSON.stringify(filterAst, null, 2));
} catch (e) {
  console.error(`Error parsing filter '${filterQuery}':`, e.message);
}

// Example 2: Parsing a full OData URI (assuming a 'parse' method is available)
const fullODataQuery = "$filter=Category/Name eq 'Books'&$orderby=Price desc&$top=5&$skip=10";
try {
  const fullAst = parser.parse(fullODataQuery);
  console.log('Parsed Full Query AST:', JSON.stringify(fullAst, null, 2));
} catch (e) {
  console.error(`Error parsing full query '${fullODataQuery}':`, e.message);
  console.log("Note: If 'parser.parse' is not available, you might need to parse sections individually.");
}

console.log("\nNote: The output AST structure depends on the internal implementation of this specific parser version.");