Widen query parameters type to support named placeholders?

[cduff]

Feature Description

The Problem

The mysql2 driver supports named placeholders. These can currently be used via typeorm as follows:

const dataSource = new DataSource({
  ...
  extra: { namedPlaceholders: true },
});

const result = await dataSource.manager.query("SELECT :msg", { msg: "hello world" } as any);
// note usage of 'as any' to work around limited parameters typing
console.log(result);
// output: [ { 'hello world': 'hello world' } ]

Named placeholders are much nicer/easier/clearer to work with compared to the base supported ?/array syntax. It is also aligned with the way parameters are passed to typeorm when working with createQueryBuilder (docs).

The problem is that the query function has the following limited typing:

query(query: string, parameters?: any[]): Promise<any>;

It is therefore not possible to pass an object literal to parameters without some workaround like using as any.

The Solution

Could the typing for parameters of the query function be extended to support object literals? E.g.

query(query: string, parameters?: any[] | ObjectLiteral): Promise<any>;

Note: ObjectLiteral is already used in a similar context here:

typeorm/src/driver/Driver.ts

Line 137 in c5dfc11

parameters: ObjectLiteral,

It is defined here:

typeorm/src/common/ObjectLiteral.ts

Line 4 in c5dfc11

export interface ObjectLiteral {

This could cause confusion as to which parameter format to use but this has already been stated to be driver-dependant. So perhaps confusion could be avoided through improved documentation around the query function.

Considered Alternatives

Working around the type issue using as any is possible but not clean/desirable.

Another workaround is to override the typing for the query function in a given project using declare module "typeorm"... approach, but again this is not clean/desirable.

Additional Context

#556

Relevant Database Driver(s)

DB Type	Relevant
aurora-mysql	no
aurora-postgres	no
better-sqlite3	no
cockroachdb	no
cordova	no
expo	no
mongodb	no
mysql	yes
nativescript	no
oracle	no
postgres	no
react-native	no
sap	no
sqlite	no
sqlite-abstract	no
sqljs	no
sqlserver	no

Are you willing to resolve this issue by submitting a Pull Request?

• ✖️ Yes, I have the time, and I know how to start.
• ✖️ Yes, I have the time, but I don't know how to start. I would need guidance.
• ✖️ No, I don’t have the time, but I can support (using donations) development.
• ✅ No, I don’t have the time and I’m okay to wait for the community / maintainers to resolve this issue.

[cduff]

FYI I'm currently working around this by inserting the following in my dataSource.ts file:

declare module "typeorm" {
  interface EntityManager {
    /**
     * As per normal EntityManager.query but with object literal parameters.
     * Workaround to https://github.com/typeorm/typeorm/issues/8828.
     */
    query(query: string, parameters?: ObjectLiteral): Promise<any>;
  }
}

[pleerock]

query is common for all drivers and not all of them support named parameters. That's why we have this limitation.

[cduff]

query is common for all drivers and not all of them support named parameters. That's why we have this limitation.

Understood. But it would be nice to be able to take advantage of the superior named placeholder capability of a driver where available.

I guess at worst this issue may serve as an FYI for anyone who goes looking for typeorm query named placeholders support.