doc: correct and expand documentation for SQLTagStore

[Renegade334]

Cleaning up a few issues:

• The documentation talks about "interpolating" values into the string literal. The whole point of these functions is that they don't just perform string interpolation; they prepare a query string with placeholders and then bind the values passed into the template string.
• The template string parameter binding behaviour was generally not really explained.
• The argument types for the tagged query methods were incorrect.
• .reset() was never implemented, only .clear(). There's no need for both to exist; the easiest thing is just to remove the dead reference.
• The class definition block for StatementSync was sliced in half, messing with the doc tooling.

[nodejs-github-bot]

Review requested:

• @nodejs/sqlite

[bnb]

Would it be possible to explain why you shouldn't add parameter binding placeholders to the SQL query string?

[Renegade334]

Just to clarify, is that a suggestion for the docs, or a question?

[louwers]

I think it would be good to explain that the tag store inserts these placeholders in the prepared statement.

Maybe there should be a reference to SQL Injection, because

sql.get`SELECT * FROM t1 WHERE id = ${id}`

looks really similar to

db.prepare(`SELECT * FROM t1 WHERE id = ${id}`).get();

but of course the second one is susceptible to SQL Injection.

[louwers]

OK, I didn't read until the bottom, I see SQL Injection is mentioned below.

[Renegade334]

Maybe there should be a reference to SQL Injection

I've added an insert regarding the difference between ${value} in tagged and untagged literals. Hopefully that should suffice.

[Renegade334]

Rebased for merge conflict.

[louwers]

tagStore should be defined, otherwise it is unclear how it is created.

Also I would recommend naming it sql or something else that is concise, since that is the whole point of the tagged literal API right?

[Renegade334]

If anything it should be sqlTagStore to match the class block. I don't think the meaning is ambiguous, though.

[louwers]

I think adding a

const tagStore = db.createTagStore();

at the top would be helpful.

[Renegade334]

Turtle problem, no? db isn't explicitly defined either!

This is really only intended to be an inline comment to show the difference between the two styles, and the full example block below still contains the concrete self-contained demonstration. I don't think there's much benefit to bloating these.

[louwers]

There are other examples that use db as a name for a DatabaseSync handle.

This is really only intended to be an inline comment to show the difference between the two styles, and the full example block below still contains the concrete self-contained demonstration.

Fair point, maybe they can be swapped? First show the general usage, and then the difference?

I still think naming it sql would make the elegance of the API show, but I trust your judgement.