I think we should just have one way to type the query to avoid introducing complexity and more documentation.

Yeah, I totally agree. Two ways of doing it would add needless complexity.

In your approach, the generator creates the type because you referenced it, which feels weird.

They both feel a bit weird IMO. Either way your code is invalid until the generator runs because whatever you're writing is the canonical reference (slight caveat: in the typed version of this PR the code would be executable, but have invalid types).

Some prior art I know of is TanStack Router's createFileRoute function that the generator will automatically populate based on the file's path (and generate the corresponding types). It's a bit different… but maybe there's some inspiration there?

Another idea I had (and I'm not sure it's even viable) would be to use the query itself as the way of identifying it (so the developer doesn't need to name it at all). The idea is the types that are generated overload Bun's sql function with signatures based on the actual SQL strings and arguments. Very crudely, something like this:

type sql = (strings: ["SELECT 'foo' as bar"]) => Promise<{ bar: string }[]>;

Also, I'm a bit scared that we would have to handle many edge cases like type aliases (e.g. import type { Queries as Q }...).

Yeah, that's a valid concern. I guess that problem can exist irrespective of the approach though? For example, someone can do something like this:

import { SQL as Blah } from "bun";
const { MyQuery } = withTypes(new Blah(DATABASE_URL));
const result = await MyQuery`SELECT now()`;

By the way, #40 moved all the advanced cases from the simple (which has also been renamed into "basic" in #42) example to the advanced example, in case you want to update your branch.

Got you. I'll update this PR when I get a chance.

Thinking about it more, I’m leaning toward your native generics as the single approach, especially for the zero runtime dependencies.

They both feel a bit weird IMO. Either way your code is invalid until the generator runs because whatever you're writing is the canonical reference (slight caveat: in the typed version of this PR the code would be executable, but have invalid types).

Fair point!

Another idea I had (and I'm not sure it's even viable) would be to use the query itself as the way of identifying it (so the developer doesn't need to name it at all). The idea is the types that are generated overload Bun's sql function with signatures based on the actual SQL strings and arguments.

Yeah it would be nice but I think this is not possible with the current version of TypeScript (see microsoft/TypeScript#33304)

Yeah, that's a valid concern. I guess that problem can exist irrespective of the approach though?

Yeah, I should have been more specific: SQL as Blah already works because we resolve Bun’s SQL type semantically, although your example does expose a separate gap with destructured query tags. My concern here is that the PR matches the identifier Queries literally, so import type { Queries as Q } would stop discovery.

Could we handle that import alias and verify discovery still works before the generated file exists? Those are the main cases I’d want to check before moving toward native generics as the single approach.

Yeah it would be nice but I think this is not possible with the current version of TypeScript (see microsoft/TypeScript#33304)

Dang. Yeah, that's a nonstarter.

Could we handle that import alias and verify discovery still works before the generated file exists? Those are the main cases I’d want to check before moving toward native generics as the single approach.

Got you. This sounds doable. I should have some time to take a look into it this weekend.