@mikro-orm/knex 7.0.0-dev.47 → 7.0.0-dev.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/knex",
-  "version": "7.0.0-dev.47",
+  "version": "7.0.0-dev.48",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "type": "module",
   "exports": {
@@ -57,6 +57,6 @@
     "@mikro-orm/core": "^6.6.0"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.0.0-dev.47"
+    "@mikro-orm/core": "7.0.0-dev.48"
   }
 }

package/query/index.d.ts

@@ -7,4 +7,4 @@ export * from './ObjectCriteriaNode.js';
 export * from './ScalarCriteriaNode.js';
 export * from './CriteriaNodeFactory.js';
 export * from './NativeQueryBuilder.js';
-export { rawKnex as raw } from './raw.js';
+export * from './raw.js';

package/query/index.js

@@ -7,4 +7,4 @@ export * from './ObjectCriteriaNode.js';
 export * from './ScalarCriteriaNode.js';
 export * from './CriteriaNodeFactory.js';
 export * from './NativeQueryBuilder.js';
-export { rawKnex as raw } from './raw.js';
+export * from './raw.js';

package/query/raw.d.ts

@@ -1,4 +1,5 @@
 import { type AnyString, type Dictionary, type EntityKey, type RawQueryFragment } from '@mikro-orm/core';
+import type { SelectQueryBuilder } from 'kysely';
 import { QueryBuilder } from './QueryBuilder.js';
 /**
  * Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented
@@ -55,4 +56,4 @@ import { QueryBuilder } from './QueryBuilder.js';
  * export class Author { ... }
  * ```
  */
-export declare function rawKnex<T extends object = any, R = any>(sql: QueryBuilder<T> | EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): NoInfer<R>;
+export declare function raw<T extends object = any, R = any>(sql: SelectQueryBuilder<any, any, any> | QueryBuilder<T> | EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): NoInfer<R>;

package/query/raw.js

@@ -1,5 +1,4 @@
-import { raw } from '@mikro-orm/core';
-// import type { Knex } from 'knex';
+import { raw as raw_, Utils } from '@mikro-orm/core';
 import { QueryBuilder } from './QueryBuilder.js';
 /**
  * Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented
@@ -56,17 +55,14 @@ import { QueryBuilder } from './QueryBuilder.js';
  * export class Author { ... }
  * ```
  */
-export function rawKnex(sql, params) {
-    // export function rawKnex<T extends object = any, R = any>(sql: Knex.QueryBuilder | Knex.Raw | QueryBuilder<T> | EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): NoInfer<R> {
-    // if (Utils.isObject<Knex.QueryBuilder | Knex.Raw>(sql) && 'toSQL' in sql) {
-    //   const query = sql.toSQL();
-    //   return raw(query.sql, query.bindings);
-    // }
+export function raw(sql, params) {
+    if (Utils.isObject(sql) && 'compile' in sql) {
+        const query = sql.compile();
+        return raw_(query.sql, query.parameters);
+    }
     if (sql instanceof QueryBuilder) {
-        // FIXME this should live in the `knex` compat package, while what we have now should live in `sql` package
-        // @ts-ignore
-        const query = sql.toQuery()._sql;
-        return raw(query.sql, query.bindings);
+        const query = sql.toQuery();
+        return raw_(query.sql, query.params);
     }
-    return raw(sql, params);
+    return raw_(sql, params);
 }

package/query/rawKnex.d.ts

@@ -0,0 +1,58 @@
+import { type AnyString, type Dictionary, type EntityKey, type RawQueryFragment } from '@mikro-orm/core';
+import { QueryBuilder } from './QueryBuilder.js';
+/**
+ * Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented
+ * by `RawQueryFragment` class instance that can be serialized to a string, so it can be used both as an object value
+ * and key. When serialized, the fragment key gets cached and only such cached key will be recognized by the ORM.
+ * This adds a runtime safety to the raw query fragments.
+ *
+ * > **`raw()` helper is required since v6 to use a raw fragment in your query, both through EntityManager and QueryBuilder.**
+ *
+ * ```ts
+ * // as a value
+ * await em.find(User, { time: raw('now()') });
+ *
+ * // as a key
+ * await em.find(User, { [raw('lower(name)')]: name.toLowerCase() });
+ *
+ * // value can be empty array
+ * await em.find(User, { [raw('(select 1 = 1)')]: [] });
+ * ```
+ *
+ * The `raw` helper supports several signatures, you can pass in a callback that receives the current property alias:
+ *
+ * ```ts
+ * await em.find(User, { [raw(alias => `lower(${alias}.name)`)]: name.toLowerCase() });
+ * ```
+ *
+ * You can also use the `sql` tagged template function, which works the same, but supports only the simple string signature:
+ *
+ * ```ts
+ * await em.find(User, { [sql`lower(name)`]: name.toLowerCase() });
+ * ```
+ *
+ * When using inside filters, you might have to use a callback signature to create new raw instance for every filter usage.
+ *
+ * ```ts
+ * @Filter({ name: 'long', cond: () => ({ [raw('length(perex)')]: { $gt: 10000 } }) })
+ * ```
+ *
+ * The `raw` helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use `'??'` to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to the `raw` helper. Internally, those will automatically be quoted according to the database in use:
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("country")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`country`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => raw(`create index ?? on ?? (??)`, ['custom_idx_on_name', table, columns.name]) })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ *
+ * You can also use the `quote` tag function to write database-agnostic SQL expressions. The end-result is the same as using the `raw` function regarding database identifiers quoting, only to have a more elegant expression syntax:
+ *
+ * ```ts
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+export declare function rawKnex<T extends object = any, R = any>(sql: QueryBuilder<T> | EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): NoInfer<R>;

package/query/rawKnex.js

@@ -0,0 +1,72 @@
+import { raw } from '@mikro-orm/core';
+// import type { Knex } from 'knex';
+import { QueryBuilder } from './QueryBuilder.js';
+/**
+ * Creates raw SQL query fragment that can be assigned to a property or part of a filter. This fragment is represented
+ * by `RawQueryFragment` class instance that can be serialized to a string, so it can be used both as an object value
+ * and key. When serialized, the fragment key gets cached and only such cached key will be recognized by the ORM.
+ * This adds a runtime safety to the raw query fragments.
+ *
+ * > **`raw()` helper is required since v6 to use a raw fragment in your query, both through EntityManager and QueryBuilder.**
+ *
+ * ```ts
+ * // as a value
+ * await em.find(User, { time: raw('now()') });
+ *
+ * // as a key
+ * await em.find(User, { [raw('lower(name)')]: name.toLowerCase() });
+ *
+ * // value can be empty array
+ * await em.find(User, { [raw('(select 1 = 1)')]: [] });
+ * ```
+ *
+ * The `raw` helper supports several signatures, you can pass in a callback that receives the current property alias:
+ *
+ * ```ts
+ * await em.find(User, { [raw(alias => `lower(${alias}.name)`)]: name.toLowerCase() });
+ * ```
+ *
+ * You can also use the `sql` tagged template function, which works the same, but supports only the simple string signature:
+ *
+ * ```ts
+ * await em.find(User, { [sql`lower(name)`]: name.toLowerCase() });
+ * ```
+ *
+ * When using inside filters, you might have to use a callback signature to create new raw instance for every filter usage.
+ *
+ * ```ts
+ * @Filter({ name: 'long', cond: () => ({ [raw('length(perex)')]: { $gt: 10000 } }) })
+ * ```
+ *
+ * The `raw` helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use `'??'` to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to the `raw` helper. Internally, those will automatically be quoted according to the database in use:
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("country")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`country`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => raw(`create index ?? on ?? (??)`, ['custom_idx_on_name', table, columns.name]) })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ *
+ * You can also use the `quote` tag function to write database-agnostic SQL expressions. The end-result is the same as using the `raw` function regarding database identifiers quoting, only to have a more elegant expression syntax:
+ *
+ * ```ts
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+export function rawKnex(sql, params) {
+    // export function rawKnex<T extends object = any, R = any>(sql: Knex.QueryBuilder | Knex.Raw | QueryBuilder<T> | EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): NoInfer<R> {
+    // if (Utils.isObject<Knex.QueryBuilder | Knex.Raw>(sql) && 'toSQL' in sql) {
+    //   const query = sql.toSQL();
+    //   return raw(query.sql, query.bindings);
+    // }
+    if (sql instanceof QueryBuilder) {
+        // FIXME this should live in the `knex` compat package, while what we have now should live in `sql` package
+        // @ts-ignore
+        const query = sql.toQuery()._sql;
+        return raw(query.sql, query.bindings);
+    }
+    return raw(sql, params);
+}