Add support for bind params

[blakeembrey]

Follow up from #41 (comment), prototyping a backward compatible way to add bind parameters.

TL;DR adds BIND_PARAM symbol, when seen it increments a counter, counter is used in a new .bind method to output a values list.

[blakeembrey]

@PhilippSalvisberg here's a simple prototype that's backward compatible.

[blakeembrey]

The only question to myself is whether values should now become a getter that throws when bindParams > 0? That would ensure the instance isn't incorrectly used without binding params.

[blakeembrey]

Doesn't technically need this method if you know what you're doing, but the array length safety and merging with any non-params seems like a good pattern to enforce.

[blakeembrey]

Name options:

• BIND_PARAMETER
• BIND_VALUE
• BIND
• BIND_KEY
• PARAM

[PhilippSalvisberg]

Thanks for the follow-up.

AFAIU the cases I mentioned in #41 (comment) (bind definitions e.g. for output parameters and executeMany) are not simplified by this change.

I can see that this change simplifies some code for a series of similar SQL statements (bind/execute in a loop). However, using executeMany in OracleDB or a single SQL statement would probably be more efficient.

Maybe I didn't understand the intention and the use case.

[blakeembrey]

However, using executeMany in OracleDB or a single SQL statement would probably be more efficient.

Good question. I was trying to make it easier to use executeMany. You'd be able to do something like:

const query = sql`UPDATE x SET y = ${BIND_PARAM} WHERE z = ${BIND_PARAM}`;
const result = db.executeMany(query.statement, [[1, 1], [2, 2], [3, 4]]);

However, if you wanted better safety for the params:

const result = db.executeMany(query.statement, [query.bind(1, 1), query.bind(2, 2), query.bind(3, 3)]);

[blakeembrey]

You are right that it's a very marginal improvement, and you could just use 1 or something and ignore values anyway and it'd work the same as the first example. The only difference would be if you happened to have something like this mixing positions you want to bind later and bind now:

const query = sql`UPDATE x SET y = ${true} WHERE z = ${BIND_PARAM}`;
const result = db.executeMany(query.statement, [query.bind(1), query.bind(2), query.bind(3)]); 
// Would be `[[true, 1], [true, 2], [true, 3]]`.

[PhilippSalvisberg]

(...)

const query = sql`UPDATE x SET y = ${true} WHERE z = ${BIND_PARAM}`;
const result = db.executeMany(query.statement, [query.bind(1), query.bind(2), query.bind(3)]); 
// Would be `[[true, 1], [true, 2], [true, 3]]`.

Excellent example. Thanks for the explanation. I agree. This new feature can simplify the code, especially with many "fixed" bind values and a few delayed bindings.