feat(prefer-throw-if-no-entry): add rule

[webpro]

Summary

• add opt-in prefer-throw-if-no-entry
• report statSync/lstatSync calls inside try/catch when they do not pass { throwIfNoEntry: false }
• provide suggestions to add { throwIfNoEntry: false } where the stat options object can be safely edited

Notes

This is suggestion-only and not part of the recommended config. It skips try/finally without catch, nested functions, calls that already pass { throwIfNoEntry: false }, and fstatSync because file-descriptor stat calls do not have a missing path entry case.

Node v24.9.0 benchmark for 200,000 missing statSync calls:

• try/catch miss path: 679.6ms
• { throwIfNoEntry: false } miss path: 147.3ms

Test plan

• npm test -- src/rules/prefer-throw-if-no-entry.test.ts
• npm run lint
• npm run build

[43081j]

can you explain this one a bit more?

what's the benefit of try/catching it with throwIfNoEntry: false? to ensure the only thrown errors are fatal ones?

[webpro]

can you explain this one a bit more?

It's a performance rule, to promote { throwIfNoEntry: false }. This (only) suppresses the ENOENT case and saves the expensive Error obj + stack trace. It's a bit of a niche rule perhaps, but when probing lots of files/dirs might save significant time (benchmarked) and memory (stack traces are large objects?).

what's the benefit of try/catching it with throwIfNoEntry: false? to ensure the only thrown errors are fatal ones?

Exactly. Real errors such as EACCES still throw.

[43081j]

It's a performance rule, to promote { throwIfNoEntry: false }.

this is the "how", but what is the "why"?

try { statSync(p, {throwIfNoEntry: false}); } catch {}

this is one of the fixed outputs, but in what situation would someone do this? wouldn't the reason to set it to false be to remove the try/catch?

[webpro]

It only "suppresses" ENOENT (the common case), we still need to catch EACCES and other errors.

Edit: btw statSync returns undefined if file does not exist.

[43081j]

i think i'm missing some context still though.

yes this is a rule to promote throwIfNoEntry: false. But why?

statSync does indeed return undefined.

stat and promises.stat both use this flag to decide if to return undefined when not found, or if to throw.

we both fully understand how they work. i'm not asking that, i'm asking why someone would migrate from throwing to not throwing.

[webpro]

Performance: statSync is a lot faster (and presumably memory-efficient) if it does not throw in case the file does not exist. If the logic is probing many (potentially missing) files this adds up. Did a quick benchmark which is in the description.

Granted, might be a bit of a niche rule but a shame to overlook in certain fs-heavy situations.

References:

• Reasoning to introduce it to Node.js: lib: add throws option to fs.f/l/statSync nodejs/node#33716
• Node.js uses this internally: nodejs/node@175f6f0be3
• TypeScript too: microsoft/TypeScript@ebeafcf
• The cost of capturing stack traces in https://marvinh.dev/blog/speeding-up-javascript-ecosystem-part-2/
• For completeness' sake while I'm at it, Node.js docs:
  • https://nodejs.org/api/fs.html#fspromisesstatpath-options
  • https://nodejs.org/api/fs.html#fsstatpath-options-callback
  • https://nodejs.org/api/fs.html#fslstatsyncpath-options
  • https://nodejs.org/api/fs.html#fsstatsyncpath-options

[43081j]

aha i understand my source of confusion now.

given this as a "before":

try {
  fs.statSync(...);
} catch {
  // if ENOENT do something because it wasn't found
  // otherwise, rethrow
}

the "after" is actually this:

const stat = fs.statSync(..., { throwIfNoEntry: false });
if (!stat) {
  // do something because it wasn't found
}

i.e. the real benefit is when you're using a try/catch to determine if a file exists or not. you can now do that faster with this option and just compare the result against undefined.

the example in the test cases isn't this. it would gain still because it is unconditionally throwing away all errors anyway, so never throwing the not-found one will speed it up. but it doesn't seem like code anyone would write (doing a stat where you don't check the result OR the error, is just no-op).

maybe its worth making this clearer somehow in the description. the message already touches on it

[webpro]

Added an example and tried to clarify in docs.

Regardless of nested try/catch blocks, I think we should always catch such known errors. Another way to look at it:

Before:

try {
  use(statSync(p));
} catch (err) {
  if (err.code === 'ENOENT') return; // missing
  logger.warn(err);                  // real error
}

After:

try {
  const stat = statSync(p, { throwIfNoEntry: false });
  if (!stat) return;                 // missing, no throw
  use(stat);
} catch (err) {
  logger.warn(err);                  // real error, still caught
}

it doesn't seem like code anyone would write (doing a stat where you don't check the result OR the error, is just no-op).

Maybe the before/after example above is more clear. It's what Node.js and TS internally do because it's faster.

[43081j]

new messaging looks much better! seems a lot clearer now.

thanks a bunch for helping me better understand 🙏

[webpro]

Should've clarified intent/reasoning better in the description right away. Anyway, thanks for merging! Like how this plugin is evolving 😇