Processor#process silent errors

I’d like to start by saying PostCSS is an invaluable tool and thank you for all the work 🙌

I’ve recently started digging into PostCSS and it’s API and I’ve been running into a challenge with error handling using Process#process. It appears when there is an error, it’s not thrown nor provided via public API. This is likely due to an error in how I’m using the API but I haven’t been able to find the root cause after several hours of digging through the source and docs.

I started with postcss.parse because I didn’t need any plugins or syntaxes (parsers/stringifiers). When passing invalid code, it throws CssSyntaxError as I would expect.

const postcss = require('postcss');

// Intentionally invalid CSS comment.
const source = '// Inline comment.';

try {
  // This throws `CssSyntaxError`, as expected.
  const root = postcss.parse(source);
  console.log(root);
} catch (err) {
  console.error({ example: 'parse', err });
}

When switching to Process#process to begin working with plugins, etc. this error is no longer being surfaced. I understand as of v8.4 PostCSS switched to lazy evaluation and I’m wondering if it’s related to that?

const postcss = require('postcss');

// Intentionally invalid CSS comment.
const source = '// Inline comment.';

// First case.
const noWorkResult = postcss().process(source);
// No errors. This appears to be considered private API since it's not defined in type definitions.
console.log({ example: '1-before-root', error: noWorkResult.error }); // undefined
// Root is unexpectedly `undefined`.
console.log({ example: '1-root', root: noWorkResult.root }); // undefined
// Checking errors again now supplies the error, but this isn't public API?
console.log({ example: '1-after-root', error: noWorkResult.error }); // CssSyntaxError

// Second case (using sync)
const result = postcss()
  .process(source)
  .sync();
console.log({ example: '2-root', root: result.root }); // undefined

// Third case (using async)
postcss()
  .process(source)
  .then(
    result => console.log({ example: '3-root', root: result.root }) // undefined
  );

Am I using the API correctly? What is the recommended approach for catching errors and surfacing them in Processor#process?

[ai]

In first case there is a mistake of using result.error since it is not public API.

The second case is not very right. You do not need to call .sync() (it is a public API but for hacks). Seems like we have an error here.

Async case is not right. You should have:

postcss()
  .process(source)
  .then(
    result => console.log({ example: '3-root', root: result.root }) // undefined
  )
  .catch(e => {
    throw e
  })

But looks like we have a bug of not throwing an error in lazyResult.root and

[ai]

Released in 8.4.6.