sqlite: add StatementSync.prototype.close() and [Symbol.dispose]()

[araujogui]

No description provided.

[nodejs-github-bot]

Review requested:

• @nodejs/sqlite

[Renegade334]

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

[araujogui]

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

[jasnell]

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

[Renegade334]

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

[Renegade334]

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

[codecov]

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #64232      +/-   ##
==========================================
- Coverage   90.25%   90.24%   -0.02%     
==========================================
  Files         741      741              
  Lines      241165   241177      +12     
  Branches    45428    45426       -2     
==========================================
- Hits       217667   217643      -24     
- Misses      15069    15114      +45     
+ Partials     8429     8420       -9     

Files with missing lines	Coverage Δ
src/node_sqlite.h	80.64% <ø> (ø)
src/node_sqlite.cc	81.06% <87.50%> (+0.34%)	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.