A pretty-printed SyntaxError for compilers/tokenizers/lexers

pretty-syntax-error.js

/*
Pretty Syntax Errors

> @nicholaswmin, MIT License

A SyntaxError that pretty-prints the and higlights error line & column, 
in your source.
This is only useful if you're building a compiler/lexer/tokenizer.  
Although it is an `instanceof SyntaxError`, their similarities end there.

- Isomorphic, pretty prints in Node.js + browser.
- Respects `FORCE_COLOR`, `NO_COLOR` env. variables.

Additional Notes:

 - Node.js: The `error.message` is populated with the additional 
   pretty-printing. Includes colors if appropriate.

 - In browsers, the `err.cause` is used instead. No colors.
   Browsers immediately call the `message.toString()` method on `new Error()`, 
   instead of waiting until it's actually thrown and that looks awkward.  

 - Safari does not show `error.cause` in it's DevTools so we `console.error`
   the pretty-printed error on `new Error()`. There's no workaround to this,
   although it shouldn't realistically be an issue for most use-cases.
  
## Usage:

Example: highlight the problematic `3` in `3foo`: 

```
import { PrettySyntaxError } from './pretty-syntax-error.js'

const offset = 41 // position of error in the source string
const source = ` // the string you're parsing
  let exponentiation = => 3 ** 4;
  let 3foo = 'bar';
  let bang_bang_ure_boolean = x => !!x;
`

throw new PrettySyntaxError('Invalid token', { source, offset })

' Error: SyntaxError  '
'                     '
'  Invalid token      '
'      ⇩              '
'..let 3foo = 'bar';  ' 
'      ⇧              '
'                     '
'  Line: 2            '
'  Column: 4          '
```
*/

const envIsBrowser = () => globalThis !== 'undefined' && 
  Object.hasOwn(globalThis, 'window')

const browserIsSafari = () => {
  return envIsBrowser() && 
    globalThis?.window
      ?.navigator?.vendor
      ?.toLowerCase().includes('apple')
}

class Lines {
  constructor(message, lines) {
    this.message = message
    this.lines = lines
  }
    
  toString() {
    // Safari doesn't display `err.cause` in its DevTools,
    // so we gotta log it to the console at least
    return browserIsSafari() 
      ? this.logAndJoin(this.lines)
      : this.join(this.lines)  
  }
  
  join(lines) {
    return lines.reduce((acc, l) => acc + 
      (this.constructor.canColor() ? 
        l.toANSIString() : 
        l.toString()), '')
  }
  
  logAndJoin(lines) {
    const joined = this.join(lines)
    
    // log in monospace to avoid alignemnt issues
    globalThis.console.error(`%c${joined}`, 'font-family: monospace;')

    return joined
  }
  
  // - Normally we'd use `process.stdout.isTTY` but, 
  //   theres an issue: https://github.com/nodejs/help/issues/4507
  // - Follows guidelines: https://no-color.org/
  static canColor() {
    const defined = v => typeof v !== 'undefined'
    
    const IS_TEST = () => defined(process)
      && process.env?.NODE_ENV === 'test'

    const NO_COLOR = () => defined(process.env.NO_COLOR) 
      || process?.argv?.includes('--no-color')

    const FORCE_COLOR = () => defined(process.env.FORCE_COLOR) 
      || process?.argv?.includes('--color')

    const isTTY = () => !!process.stdout?.isTTY || 
      typeof process.env.NODE_TEST_CONTEXT !== 'undefined'

    return envIsBrowser() || NO_COLOR() 
      ? false : FORCE_COLOR() || isTTY() || IS_TEST()
  }
}

class Line {
  static colors = {
    'reset': '0', 'red': '31', 'green': '32', 'yellow': '33', 
    'blue': '34', 'magenta': '35', 'cyan': '36', 'white': '37'
  }

  constructor(str, color = 'white', offset, { center = false } = {}) {
    this.str = this.pad(str, offset, { center })
    this.color = color
  }
  
  toString() {
    return this.str
  }

  toANSIString() {
    return `\x1b[${Line.colors[this.color] || '37'}m${this.str}\x1b[0m` 
  }

  pad(str, offset, { center }) {
    return ' '.repeat(Math.max(0, offset - (center ? str.length / 2 : 0))) + str
  }
}

class Linebreak extends Line {
  constructor(lines = 1) {
    super('\n'.repeat(Math.max(1, lines)), 'white', 0)
  }
}

class PrettySyntaxError extends SyntaxError {
  constructor(message, { cause, source, offset }) {
    const splat = source.slice(0, offset).split('\n')
    const prior = splat.at(-1).trim()
    const after = source.slice(offset + 1, source.indexOf('\n', offset))
    const error = source.at(offset)
    const lines = new Lines(message, [
      new Linebreak(2),
      new Line(message, 'red', prior.length, { center: true }),
      new Linebreak(),
      new Line('⇩', 'red', prior.length),
      new Linebreak(),
      new Line(prior, 'green'), new Line(error, 'red'), new Line(after),
      new Linebreak(),
      new Line('⇧', 'red', prior.length),
      new Linebreak(),
      new Line(`Line: ${splat.length}`),
      new Linebreak(),
      new Line(`Column: ${prior.length + 1}`),
      new Linebreak()
    ])

    super(envIsBrowser() ? message : lines.toString(), { 
      cause: envIsBrowser() ? lines.toString() : 'parsing syntax error'
    })

    this.name = 'SyntaxError'
  }
}

export { PrettySyntaxError }

Tests:

no test runner, just node --test:

import test from 'node:test'
import { PrettySyntaxError } from '../errors.js'

// note: dont ident `source`
const noAnsi = err => err.replace(/\u001b\[.*?m/g, '')
const source = `LoremipsumdemipsumdolorLorem
mipsumdolormipsumdolormipsumdolor
dol3rLomipsumdolor
ipsumdolor
sumdolor
`

test('SyntaxError: pretty printing', async t => {  
  const err = new PrettySyntaxError('Foobars Foob', { source, offset: 63 })
  const lines = noAnsi(err.message).split('\n')

  await t.test('nodejs', async t => {
    await t.test('is an instanceof SyntaxError', t => {
      t.assert.strictEqual(err instanceof SyntaxError, true)
    })

    await t.test('logs the error message', t => {
      t.assert.ok(err.message.includes('Foobars Foo'))
    })
  
    await t.test('logs the line number', async t => {
      t.assert.ok(err.message.includes('Line: 3'), err.message)
    })
    
    await t.test('logs the column number', async t => {
      t.assert.ok(err.message.includes('Column: 1'), err.message)
    })
  
    await t.test('column is close to gutter', async t => {
      await t.test('visually points the correct source column', async t => {
        t.assert.strictEqual(lines.at(2), 'Foobars Foob')
        t.assert.strictEqual(lines.at(3), '⇩')
        t.assert.strictEqual(lines.at(4), 'dol3rLomipsumdolor')
      })
    })   
    
    await t.test('column is far from gutter', async t => {
      const err = new PrettySyntaxError('Foobars Foob', { source, offset: 70 })
      const lines = noAnsi(err.message).split('\n')
  
      await t.test('visually points the correct source column', async t => {
        t.assert.strictEqual(lines.at(2), ' Foobars Foob')
        t.assert.strictEqual(lines.at(3), '       ⇩')
        t.assert.strictEqual(lines.at(4), 'dol3rLomipsumdolor')
      })
    })  
  })

  await t.test('browser', async t => {
    let err, window = {}, vendors = ['Apple Computer, Inc.', 'Google Inc.']

    t.after(() => delete globalThis.window )   
    t.before(() => { 
      // trick it so it thinks env = browser
      globalThis.window = { 
        console: { log: () => {} },
        navigator: { vendor: vendors[0] } 
      }
    })
  
    t.beforeEach(() => {
      err = new PrettySyntaxError('foo', { source, offset: 1 })
    })
    
    for (const vendor of vendors)  {
      await t.test(vendor, async t => {
        globalThis.window.navigator.vendor = vendor
        
        await t.test('is an instanceof SyntaxError', t => {
          t.assert.strictEqual(err instanceof SyntaxError, true)
        })
    
        await t.test('logs the error message', t => {
          t.assert.strictEqual(err.message, 'foo')
        })
        
        await t.test('logs the line number', async t => {
          t.assert.ok(err.cause.includes('Line: 1'), err.message)
        })
        
        await t.test('logs the column number', async t => {
          t.assert.ok(err.cause.includes('Column: 2'), err.message)
        })
        
        await t.test('visually points the correct source column', async t => {
          const lines = err.cause.split('\n')
          t.assert.strictEqual(lines.at(2), 'foo')
          t.assert.strictEqual(lines.at(3), ' ⇩')
          t.assert.strictEqual(lines.at(4), 'LoremipsumdemipsumdolorLorem')
          t.assert.strictEqual(lines.at(5), ' ⇧')
        }) 
      }) 
    }
  })
  
  await t.test('colors', async t => {
    const err = new PrettySyntaxError('foo', { source, offset: 1 })
  
    await t.test('is ANSI-code colored', async t => {
      // 31m is ANSI CODE for red, if included, it's colored.
      t.assert.ok(err.message.includes('31m'))
    })
    
    await t.test('respects color env. variables', async t => {
      t.before(() => t.originalEnv = { ...process.env })     
      t.after(() => process.env = t.originalEnv)   
      t.beforeEach(() => {
        delete process.env.FORCE_COLOR
        delete process.env.NO_COLOR
      })       
    
    
      await t.test('NO_COLOR nor FORCE_COLOR is set', async t => {
        await t.test('is ANSI-code colored', async t => {
          t.assert.ok(err.message.includes('31m'))
        })
      }) 
  
      await t.test('NO_COLOR is set', async t => {
        process.env.NO_COLOR = '1'          
        const err = new PrettySyntaxError('foo', { source, offset: 1 })
  
        await t.test('skips colors', async t => {             
          t.assert.ok(!err.message.includes('31m'))
        })
      })
      
      await t.test('both NO_COLOR and FORCE_COLOR are set', async t => {
        process.env.FORCE_COLOR = '1'
        process.env.NO_COLOR = '1'
        const err = new PrettySyntaxError('foo', { source, offset: 1})
  
        await t.test('skips colors', async t => {    
          t.assert.ok(!err.message.includes('31m'))
        })
      })
    })
  })
})

Looks like this:

... almost, this rendering looks shit and misaligned.