@mikro-orm/knex 6.5.10-dev.14 → 6.5.10-dev.16

package/index.d.ts

@@ -16,4 +16,5 @@ export { SqlEntityManager as EntityManager } from './SqlEntityManager';
 export { SqlEntityRepository as EntityRepository } from './SqlEntityRepository';
 /** @ignore */
 export { Knex, knex } from 'knex';
+/** @ts-ignore */
 export * from '@mikro-orm/core';

package/index.js

@@ -38,4 +38,5 @@ Object.defineProperty(exports, "EntityRepository", { enumerable: true, get: func
 var knex_1 = require("knex");
 Object.defineProperty(exports, "Knex", { enumerable: true, get: function () { return knex_1.Knex; } });
 Object.defineProperty(exports, "knex", { enumerable: true, get: function () { return knex_1.knex; } });
+/** @ts-ignore */
 __exportStar(require("@mikro-orm/core"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/knex",
-  "version": "6.5.10-dev.14",
+  "version": "6.5.10-dev.16",
   "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.",
   "main": "index.js",
   "module": "index.mjs",
@@ -66,7 +66,7 @@
     "@mikro-orm/core": "^6.5.9"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "6.5.10-dev.14",
+    "@mikro-orm/core": "6.5.10-dev.16",
     "better-sqlite3": "*",
     "libsql": "*",
     "mariadb": "*"

package/query/index.d.ts

@@ -6,3 +6,4 @@ export * from './ArrayCriteriaNode';
 export * from './ObjectCriteriaNode';
 export * from './ScalarCriteriaNode';
 export * from './CriteriaNodeFactory';
+export { rawKnex as raw } from './raw';

package/query/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.raw = void 0;
 __exportStar(require("./enums"), exports);
 __exportStar(require("./QueryBuilderHelper"), exports);
 __exportStar(require("./QueryBuilder"), exports);
@@ -22,3 +23,5 @@ __exportStar(require("./ArrayCriteriaNode"), exports);
 __exportStar(require("./ObjectCriteriaNode"), exports);
 __exportStar(require("./ScalarCriteriaNode"), exports);
 __exportStar(require("./CriteriaNodeFactory"), exports);
+var raw_1 = require("./raw");
+Object.defineProperty(exports, "raw", { enumerable: true, get: function () { return raw_1.rawKnex; } });

package/query/raw.d.ts

@@ -0,0 +1,59 @@
+import { type AnyString, type Dictionary, type EntityKey, type RawQueryFragment } from '@mikro-orm/core';
+import type { Knex } from 'knex';
+import { QueryBuilder } from './QueryBuilder';
+/**
+ * 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: Knex.QueryBuilder | Knex.Raw | QueryBuilder<T> | EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): NoInfer<R>;

package/query/raw.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rawKnex = rawKnex;
+const core_1 = require("@mikro-orm/core");
+const QueryBuilder_1 = require("./QueryBuilder");
+/**
+ * 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 { ... }
+ * ```
+ */
+function rawKnex(sql, params) {
+    if (core_1.Utils.isObject(sql) && 'toSQL' in sql) {
+        const query = sql.toSQL();
+        return (0, core_1.raw)(query.sql, query.bindings);
+    }
+    if (sql instanceof QueryBuilder_1.QueryBuilder) {
+        const query = sql.toQuery()._sql;
+        return (0, core_1.raw)(query.sql, query.bindings);
+    }
+    return (0, core_1.raw)(sql, params);
+}