feat: add named params support

[ibilux]

Hello,

This is a work-in-progress for #91 aiming to add support for named parameters.
I’ve added tests, and they’re all passing so far. However, the current implementation is not perfect (far from it, actually), there’s definitely room for improvement.

Any feedback or suggestions for a cleaner or more efficient approach would be very welcome.

Thank you.

[DallasHoff]

This is looking really good so far.

[ibilux]

This is looking really good so far.

What do you think about using BindingSpec type instead of unknown[] | Record<string, unknown> in the Statement params:

export type Statement = {
	sql: string;
	params: unknown[] | Record<string, unknown>;
};

The BindingSpec is the bind type in db.exec:

sqlocal/src/drivers/sqlite-memory-driver.ts

Line 213 in c105867

bind: statement.params,

Referenced from SQLite wasm:
https://github.com/sqlite/sqlite-wasm/blob/31e4b6e478a3f10a11b477feb08f1e54b53c791a/index.d.ts#L318

[ibilux]

• I have a updated the named parameters extraction method for all cases with more tests.
• I have add tests for the numbered positional parameters ?NNN.
• The last commit is just for testing the sqlite/wasm Bindable types (we can revert it if it's out of this PR scope).

[ibilux]

• I have a updated the named parameters extraction method for all cases with more tests.
• I have add tests for the numbered positional parameters ?NNN.
• The last commit is just for testing the sqlite/wasm Bindable types (we can revert it if it's out of this PR scope).

We can also export the normalizeNamedParams as a helper function and give the user the option to chose if he wants to use the helper function of provide a valid named parameters object:

// Use the `normalizeNamedParams` helper function
await sql('INSERT INTO groceries (name) VALUES (:name)', normalizeNamedParams({ name: 'bread' }));

// Or provide a valid binding object instead
await sql('INSERT INTO groceries (name) VALUES (:name)', { ':name': 'bread' });

This provide more flexibility, but may introduce some confusion.

[DallasHoff]

Let's not use BindingSpec or BindableValue. Simpler types will suffice.

[DallasHoff]

If you finish making changes, please feel free to request re-review or remove the draft status from the PR.

[ibilux]

Let's not use BindingSpec or BindableValue. Simpler types will suffice.

I reverted that commit.

If you finish making changes, please feel free to request re-review or remove the draft status from the PR.

Yes, it should be ready for review.

[DallasHoff]

I also left this comment last night. Did you see it and does it make sense?

[ibilux]

I also left this comment last night. Did you see it and does it make sense?

I didn't notice it. I think that would be better.

I meant that normalizeSql should be renamed to sqlTag, and the old implementation of sqlTag should be deleted. normalizeSql can take its place.

The last commit merges normalizeSql into sqlTag, now there is one entry for handling SQL queries.

[DallasHoff]

Why is all of this new logic that parses the SQL necessary? Ideally, any SQL parsing should be SQLite's job. SQLocal should just be taking the user's SQL and parameters, passing them to SQLite, and returning the results. We shouldn't be duplicating work that SQLite was going to do anyway. Is there a reason it won't work without this preprocessing?

[ibilux]

Why is all of this new logic that parses the SQL necessary? Ideally, any SQL parsing should be SQLite's job. SQLocal should just be taking the user's SQL and parameters, passing them to SQLite, and returning the results. We shouldn't be duplicating work that SQLite was going to do anyway. Is there a reason it won't work without this preprocessing?

The SQLite wasm uses BindingSpec which is defined as:

/** Specifies parameter bindings. */
declare type BindingSpec =
  | readonly BindableValue[]
  | { [paramName: string]: BindableValue }
  /** Assumed to have binding index `1` */
  | (SqlValue | boolean);

we can use it or adapt it somehow to make things cleaner.

Referenced from SQLite wasm:
https://github.com/sqlite/sqlite-wasm/blob/31e4b6e478a3f10a11b477feb08f1e54b53c791a/index.d.ts#L27C1-L32C26

[DallasHoff]

It's not about the types. The types are fine. Record<string, any> is compatible with BindingSpec. I'm saying that all the extraction and normalization logic that the last commit added is not necessary. SQLite does that itself already, so you can just pass the parameter object to the driver directly without modifying it, and SQLite will handle validating it.

[DallasHoff]

You can remove this block. It's just retesting logic that already has tests.