Inaccurate Error Position Reporting

[runeb]

Summary

The parse() function reports error positions that don't correspond to the actual location of syntax errors in multi-line GROQ queries, making it difficult to provide accurate error highlighting in code editors.

Expected Behavior

Error positions should point to or near the actual syntax error location to help users identify and fix the issue.

Actual Behavior

Error positions point to much earlier locations in the query where the parser failed, which may be far from the actual syntax error.

Reproduction

const { parse } = require('groq-js')

const query = `*[_type == "article"]{
  body{
    _key,
    not: valid here
  }
}`

try {
  parse(query)
} catch (error) {
  console.log('Error message:', error.message)
  console.log('Error position:', error.position)
  console.log('Character at position:', JSON.stringify(query.charAt(error.position)))

  // Calculate line/column
  const lines = query.split('\n')
  let currentPos = 0
  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
    const lineLength = lines[lineIndex].length
    if (error.position >= currentPos && error.position < currentPos + lineLength) {
      console.log(`Error reported at line ${lineIndex + 1}, column ${error.position - currentPos + 1}`)
      console.log(`Line content: "${lines[lineIndex]}"`)
      break
    }
    currentPos += lineLength + 1 // +1 for newline
  }
}

Output:

Error message: Syntax error in GROQ query at position 28
Error position: 28
Character at position: "y"
Error reported at line 2, column 6
Line content: "  body{"

Problem Analysis

The actual syntax error is not: valid here on line 4, but the error position (28) points to the "y" in "body" on line 2. This happens because the parser fails early when it encounters the projection structure it can't parse, rather than pointing to the specific invalid syntax.

Impact

This makes it very difficult to implement accurate error highlighting in code editors and IDEs. Users see error markers far from the actual problem, making debugging confusing and inefficient.

Use Case

We may implement a GROQ linter for the Sanity Vision tool and IDE extensions, and accurate error positions are crucial for showing inline error indicators (squiggly underlines, gutter markers) at the correct location.

Possible Improvements

1. Better error context: Provide additional position information (e.g., range of problematic tokens)
2. Error categorization: Distinguish between parse failures and semantic errors
3. Lookahead improvements: Better detection of where the actual syntax issue occurs

Environment

• groq-js version: 1.17.1
• Node.js version: 22.14.0

[sgulseth]

GROQ ignores whitespaces, as a temp workaround you can skip whitespaces when searching for the character:

const query = `*[_type == "article"]{
  body{
    _key,
    not: valid here
  }
}`

try {
  parse(query)
} catch (error) {
  console.log('Error message:', error.message)
  console.log('Error position:', error.position)
  console.log('Character at position:', JSON.stringify(query.charAt(error.position)))

  // Calculate line/column
  let currentPosition = 0
  for (let i = 0; i < query.length; i++) {
    const ch = query[i]
    if (ch == ' ' || ch == '\t' || ch == '\n') {
      continue
    }
    if (currentPosition === error.position) {
      console.log(`found error: "-->${ch}<-- ${query.slice(i + 1, i + 10)}"`)
    }

    currentPosition++
  }
}

test/sourceloc.test.ts 1> Error position: 30
test/sourceloc.test.ts 1> Character at position: "y"
test/sourceloc.test.ts 1> found error: "-->n<-- ot: valid"

[runeb]

@sgulseth Running your code I get a different output

const {parse, format} = require('./dist/index.js')

const query = `*[_type == "article"]{
  body{
    _key,
    not: valid here
  }
}`

try {
  parse(query)
} catch (error) {
  console.log('Error message:', error.message)
  console.log('Error position:', error.position)
  console.log('Character at position:', JSON.stringify(query.charAt(error.position)))

  // Calculate line/column
  let currentPosition = 0
  for (let i = 0; i < query.length; i++) {
    const ch = query[i]
    if (ch == ' ' || ch == '\t' || ch == '\n') {
      continue
    }
    if (currentPosition === error.position) {
      console.log(`found error: "-->${ch}<-- ${query.slice(i + 1, i + 10)}"`)
    }

    currentPosition++
  }
}

Error message: Syntax error in GROQ query at position 28
Error position: 28
Character at position: "y"
found error: "-->y<-- ,
    not"

and if I add whitespace to the query, for example by prepending a space, the error moves, suggesting that whitespace is included?

const query = ` *[_type == "article"]{
  body{
    _key,
    not: valid here
  }
}`

Error message: Syntax error in GROQ query at position 29
Error position: 29
Character at position: "y"
found error: "-->,<--
    not:"

[runeb]

v22.14.0 on main branch