Improvements to the $queryRaw function's type signature

[LinusU]

Problem

Using $queryRaw currently gives you no type safety at all. This is frustrating in a number of scenarios, where it would be perfectly possible to get the information without compromising on type accuracy.

Here are some examples:

const rows = await postgres.$queryRaw`SELECT "id" FROM "User" WHERE "email" = ${email}`
const emailExists = rows.length > 0 // ERROR: cannot read property length of unknown

const rows = await postgres.$queryRaw`SELECT "name" FROM "User"`

for (const row of rows) { // ERROR: cannot iterate over unknown
  console.log(row)
}

There is also some frustration when specifying the type of the rows using the functions type parameters. $queryRaw will always return an array, yet it's possible to use the type parameters to specify something that isn't an array:

// The problem starts here, in order to work with Prisma 5.x you need to specify Array<{ name: string }> as the type parameter, not just the object
const rows = `await postgres.$queryRaw<{ name: string }>`SELECT "name" FROM "User"`

for (const row of rows) { // ERROR: cannot iterate over object
  console.log(row)
}

Suggested solution

I propose that we change the function signature as follows:

- $queryRaw<T = unknown>(query: TemplateStringsArray | Prisma.Sql, ...values: any[]): Prisma.PrismaPromise<T>
+ $queryRaw<T = unknown>(query: TemplateStringsArray | Prisma.Sql, ...values: any[]): Prisma.PrismaPromise<T[]>

This would make all the examples above work.

Note that this would be a breaking change, since users of the current type parameter already specifies the extra Array<...> that would be superfluous after this change.

Alternatives

Another alternativ would be to go one step further, as discussed in #15263. However, my experience with Record is that it's not always desired, since it can potentially lead to some problems when trying to do guarded type casts. I think that this would need additional investigation before pursuing:

- $queryRaw<T = unknown>(query: TemplateStringsArray | Prisma.Sql, ...values: any[]): Prisma.PrismaPromise<T>
+ $queryRaw<T extends Record<string, unknown> = Record<string, unknown>>(query: TemplateStringsArray | Prisma.Sql, ...values: any[]): Prisma.PrismaPromise<T[]>

---

Another alternative would be to remove the ability to specify a type parameter. I actually would prefer this solution since the current disguises a type assertion, and is even listed as a common misstake in the DefinitelyTyped guide.

This is especially problematic for serious organizations that use linting to disallow unsafe type casts, since this usage cannot be checked by the linter.

- $queryRaw<T = unknown>(query: TemplateStringsArray | Prisma.Sql, ...values: any[]): Prisma.PrismaPromise<T>
+ $queryRaw(query: TemplateStringsArray | Prisma.Sql, ...values: any[]): Prisma.PrismaPromise<unknown[]>

For current users, this would be slightly more work to update, but the upside would be that they would be made aware of their unchecked type assertions! It would be something like this:

- await postgres.$queryRaw<Array<{ id: string }>>`SELECT "id" FROM "User"`
+ await postgres.$queryRaw`SELECT "id" FROM "User"` as Array<{ id: string }>

Personally, I think that this would be the best approach. But unfortunately, when maintaining types, I've seen a lot of pushback from users that prefer things to be easy rather than correct. And since this would be a (slightly) larger change for current users, I'm including it as an alternative instead of the main proposal.

Additional context

Related bug: #15263