joist-knex 1.228.0

package/README.md

@@ -0,0 +1,8 @@
+
+# joist-knex
+
+`joist-knex` provides a `buildQuery` function that takes `em.find`-style input and returns a Knex `QueryBuilder`.
+
+This is useful for creating the "last 5%" of queries that need SQL features that `em.find` doesn't support, i.e. primarily aggregation, but also more complicated joins, query conditions, etc.
+
+Knex itself is well-suited to this task, because it has structured methods like `clearOrder`, `select`, etc. to help munge the initial `buildQuery`-created query into the custom query, without tedious string parsing.

package/build/buildKnexQuery.d.ts

@@ -0,0 +1,9 @@
+import { ParsedFindQuery } from "joist-orm";
+import { Knex } from "knex";
+import QueryBuilder = Knex.QueryBuilder;
+/** Transforms Joist's internal `ParsedFindQuery` AST into a Knex query builder. */
+export declare function buildKnexQuery(knex: Knex, parsed: ParsedFindQuery, settings: {
+    limit?: number;
+    offset?: number;
+}): QueryBuilder<{}, unknown[]>;
+//# sourceMappingURL=buildKnexQuery.d.ts.map

package/build/buildKnexQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildKnexQuery.d.ts","sourceRoot":"","sources":["../src/buildKnexQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,eAAe,EAAe,MAAM,WAAW,CAAC;AAC/E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;AAExC,mFAAmF;AACnF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CA2D7B"}

package/build/buildKnexQuery.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildKnexQuery = buildKnexQuery;
+const joist_orm_1 = require("joist-orm");
+const utils_1 = require("./utils");
+/** Transforms Joist's internal `ParsedFindQuery` AST into a Knex query builder. */
+function buildKnexQuery(knex, parsed, settings) {
+    const { limit, offset } = settings;
+    // If we're doing o2m joins, add a `DISTINCT` clause to avoid duplicates
+    const needsDistinct = parsed.tables.some((t) => t.join === "outer" && t.distinct !== false);
+    // We need the `knex` param to call `knex.raw`
+    const asRaw = (t) => knex.raw(`${(0, joist_orm_1.kq)(t.table)} as ${(0, joist_orm_1.kq)(t.alias)}`);
+    const primary = parsed.tables.find((t) => t.join === "primary");
+    let query = knex.from(asRaw(primary));
+    parsed.selects.forEach((s, i) => {
+        const maybeDistinct = i === 0 && needsDistinct ? "distinct " : "";
+        query.select(knex.raw(`${maybeDistinct}${s}`));
+    });
+    parsed.tables.forEach((t) => {
+        switch (t.join) {
+            case "inner":
+                query.join(asRaw(t), knex.raw(t.col1), knex.raw(t.col2));
+                break;
+            case "outer":
+                query.leftOuterJoin(asRaw(t), knex.raw(t.col1), knex.raw(t.col2));
+                break;
+            case "primary":
+                // ignore
+                break;
+            default:
+                (0, utils_1.assertNever)(t);
+        }
+    });
+    if (parsed.lateralJoins) {
+        query.joinRaw(parsed.lateralJoins.joins.join("\n"), parsed.lateralJoins.bindings);
+    }
+    if (parsed.condition) {
+        const where = joist_orm_1.internals.buildWhereClause(parsed.condition, true);
+        if (where) {
+            const [sql, bindings] = where;
+            query.whereRaw(sql, bindings);
+        }
+    }
+    parsed.orderBys &&
+        parsed.orderBys.forEach(({ alias, column, order }) => {
+            // If we're doing "select distinct" for o2m joins, then all order bys must be selects
+            if (needsDistinct) {
+                query.select(knex.raw((0, joist_orm_1.kqDot)(alias, column)));
+            }
+            query.orderBy(knex.raw((0, joist_orm_1.kqDot)(alias, column)), order);
+        });
+    if (limit)
+        query.limit(limit);
+    if (offset)
+        query.offset(offset);
+    return query;
+}
+//# sourceMappingURL=buildKnexQuery.js.map

package/build/buildKnexQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildKnexQuery.js","sourceRoot":"","sources":["../src/buildKnexQuery.ts"],"names":[],"mappings":";;AAMA,wCA+DC;AArED,yCAA+E;AAE/E,mCAAsC;AAGtC,mFAAmF;AACnF,SAAgB,cAAc,CAC5B,IAAU,EACV,MAAuB,EACvB,QAA6C;IAE7C,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;IAEnC,wEAAwE;IACxE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC;IAE5F,8CAA8C;IAC9C,MAAM,KAAK,GAAG,CAAC,CAAc,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAA,cAAE,EAAC,CAAC,CAAC,KAAK,CAAC,OAAO,IAAA,cAAE,EAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAE/E,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAE,CAAC;IAEjE,IAAI,KAAK,GAAgC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAEnE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9B,MAAM,aAAa,GAAG,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,aAAa,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1B,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,OAAO;gBACV,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;gBAChE,MAAM;YACR,KAAK,OAAO;gBACV,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;gBACzE,MAAM;YACR,KAAK,SAAS;gBACZ,SAAS;gBACT,MAAM;YACR;gBACE,IAAA,mBAAW,EAAC,CAAC,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,qBAAS,CAAC,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACjE,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,KAAK,CAAC;YAC9B,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,MAAM,CAAC,QAAQ;QACb,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE;YACnD,qFAAqF;YACrF,IAAI,aAAa,EAAE,CAAC;gBAClB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAA,iBAAK,EAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;YAC/C,CAAC;YACD,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAA,iBAAK,EAAC,KAAK,EAAE,MAAM,CAAC,CAAQ,EAAE,KAAK,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;IAEL,IAAI,KAAK;QAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,MAAM;QAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,29 @@
+import { Entity, FilterAndSettings, MaybeAbstractEntityConstructor } from "joist-orm";
+import { Knex } from "knex";
+/**
+ * Builds the Knex queries from `em.find`-style parameters.
+ *
+ * This is useful for the "last 5%" of SQL queries that require SQL features that `em.find`
+ * itself doesn't support, i.e. primarily aggregation, but also complicated joins. etc.
+ *
+ * You can also `buildQuery` to get the regular `em.find` niceties around great join syntax,
+ * join pruning, inline conditions, etc., but then take the `QueryBuilder` that it produces
+ * and "muck with it". I.e. add different order bys, group bys, etc.
+ *
+ * The Knex API is actually well-suited for this, as it provides structure-aware methods like
+ * `clearOrder`, `clearSelect`, etc. that mean you can munge the initial query without any
+ * complicated string parsing.
+ *
+ * @param knex The Knex instance to use for building the query.
+ * @param type The primary entity type that `filter` is based on.
+ * @param filter[keepAliases] Marks specific aliases to keep in the query, even if they are not used
+ *   by any selects or conditions, i.e. because you plan on adding your own joins/conditions
+ *   against the `QueryBuilder` directly.
+ * @param filter[pruneJoins] Disables removing any unused joins, i.e. because you plan on adding your
+ *   own joins/conditions against the `QueryBuilder` directly.
+ */
+export declare function buildQuery<T extends Entity>(knex: Knex, type: MaybeAbstractEntityConstructor<T>, filter: FilterAndSettings<T> & {
+    pruneJoins?: boolean;
+    keepAliases?: string[];
+}): Knex.QueryBuilder<{}, unknown[]>;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAe,8BAA8B,EAAkB,MAAM,WAAW,CAAC;AACnH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,8BAA8B,CAAC,CAAC,CAAC,EACvC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,GACA,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAclC"}

package/build/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildQuery = buildQuery;
+const joist_orm_1 = require("joist-orm");
+const buildKnexQuery_1 = require("./buildKnexQuery");
+/**
+ * Builds the Knex queries from `em.find`-style parameters.
+ *
+ * This is useful for the "last 5%" of SQL queries that require SQL features that `em.find`
+ * itself doesn't support, i.e. primarily aggregation, but also complicated joins. etc.
+ *
+ * You can also `buildQuery` to get the regular `em.find` niceties around great join syntax,
+ * join pruning, inline conditions, etc., but then take the `QueryBuilder` that it produces
+ * and "muck with it". I.e. add different order bys, group bys, etc.
+ *
+ * The Knex API is actually well-suited for this, as it provides structure-aware methods like
+ * `clearOrder`, `clearSelect`, etc. that mean you can munge the initial query without any
+ * complicated string parsing.
+ *
+ * @param knex The Knex instance to use for building the query.
+ * @param type The primary entity type that `filter` is based on.
+ * @param filter[keepAliases] Marks specific aliases to keep in the query, even if they are not used
+ *   by any selects or conditions, i.e. because you plan on adding your own joins/conditions
+ *   against the `QueryBuilder` directly.
+ * @param filter[pruneJoins] Disables removing any unused joins, i.e. because you plan on adding your
+ *   own joins/conditions against the `QueryBuilder` directly.
+ */
+function buildQuery(knex, type, filter) {
+    const meta = (0, joist_orm_1.getMetadata)(type);
+    const { where, conditions, orderBy, limit, offset, pruneJoins = true, keepAliases = [], softDeletes = "exclude", } = filter;
+    const parsed = (0, joist_orm_1.parseFindQuery)(meta, where, { conditions, orderBy, pruneJoins, keepAliases, softDeletes });
+    return (0, buildKnexQuery_1.buildKnexQuery)(knex, parsed, { limit, offset });
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AA0BA,gCAqBC;AA/CD,yCAAmH;AAEnH,qDAAkD;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,UAAU,CACxB,IAAU,EACV,IAAuC,EACvC,MAGC;IAED,MAAM,IAAI,GAAG,IAAA,uBAAW,EAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,EACJ,KAAK,EACL,UAAU,EACV,OAAO,EACP,KAAK,EACL,MAAM,EACN,UAAU,GAAG,IAAI,EACjB,WAAW,GAAG,EAAE,EAChB,WAAW,GAAG,SAAS,GACxB,GAAG,MAAM,CAAC;IACX,MAAM,MAAM,GAAG,IAAA,0BAAc,EAAC,IAAI,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;IAC1G,OAAO,IAAA,+BAAc,EAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AACzD,CAAC"}

package/build/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function assertNever(x: never): never;
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAE3C"}

package/build/utils.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNever = assertNever;
+function assertNever(x) {
+    throw new Error("Unexpected object: " + x);
+}
+//# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";;AAAA,kCAEC;AAFD,SAAgB,WAAW,CAAC,CAAQ;IAClC,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "joist-knex",
+  "version": "1.228.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joist-orm/joist-orm.git",
+    "directory": "packages/knex"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "format": "prettier --ignore-path ../../.prettierignore --write '{schema,migrations,src}/**/*.{ts,js,tsx,jsx,graphql}'"
+  },
+  "files": [
+    "build"
+  ],
+  "dependencies": {
+    "knex": "^3.1.0",
+    "pg": "^8.13.3"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.10.16",
+    "@swc/jest": "^0.2.37",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.4",
+    "jest": "30.0.0-alpha.7",
+    "prettier": "^3.5.1",
+    "prettier-plugin-organize-imports": "^4.1.0",
+    "ts-node-dev": "^2.0.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "5.7.3"
+  }
+}