joist-core 2.3.0 → 2.4.0

package/build/queries/find/QueryParser.d.mts

@@ -0,0 +1,192 @@
+import { ParsedExpressionFilter } from "../parsedConditions.mjs";
+import { ExpressionFilter, OrderBy } from "./EntityFilter.mjs";
+import { EntityMetadata, Field } from "../../EntityMetadata.mjs";
+//#region src/queries/find/QueryParser.d.ts
+interface PrimaryTable {
+  join: "primary";
+  alias: string;
+  table: string;
+}
+interface JoinTable {
+  join: "inner" | "outer";
+  alias: string;
+  table: string;
+  col1: string;
+  col2: string;
+  distinct?: boolean;
+  /**
+   * Metadata used by `optimizeCollectionJoins` to rewrite collection joins into EXISTS.
+   *
+   * I.e. for `Author.books.reviews`:
+   * ```sql
+   * authors a
+   * LEFT JOIN books b ON a.id = b.author_id
+   * LEFT JOIN book_reviews br ON b.id = br.book_id
+   * ```
+   * `books b` has `parentAlias: "a"` and `rootAlias: "b"`, while `book_reviews br` has
+   * `parentAlias: "b"` and `rootAlias: "br"`.
+   *
+   * I.e. for `Author.tags`, the m2m join table is the collection root:
+   * ```sql
+   * authors a
+   * LEFT JOIN authors_to_tags att ON a.id = att.author_id
+   * LEFT JOIN tags t ON att.tag_id = t.id
+   * ```
+   * `authors_to_tags att` has `alias: "att"` and `rootAlias: "att"`, while `tags t` has `alias: "t"`
+   * but still has `rootAlias: "att"` because it belongs to the m2m subtree rooted at the join table.
+   */
+  collection?: {
+    /** The collection relation type, i.e. `o2m` for `Author.books`, or `m2m` for `Author.tags`. */
+    kind: "o2m" | "m2m";
+    /** The alias that owns this collection path, i.e. `a` for `Author.books`, or `att` for `Author.tags -> tags`. */
+    parentAlias: string;
+    /** The top-level alias in this collection subtree, i.e. `b` for `Author.books.reviews`, or `att` for `Author.tags`. */
+    rootAlias: string;
+  };
+}
+/**
+ * Creates a `CROSS JOIN`, currently used for our `em.find` batching.
+ *
+ * I.e. queries like:
+ *
+ * ```sql
+ * WITH _find (tag, arg1, arg2) AS (VALUES
+ *   (0::int, 'a'::varchar, 'a'::varchar),
+ *   (1, 'b', 'b'),
+ *   (2, 'c', 'c')
+ * )
+ * SELECT a.*, array_agg(_find.tag) AS _tags
+ * FROM authors a
+ * CROSS JOIN _find AS _find
+ * WHERE a.first_name = _find.arg0 OR a.last_name = _find.arg1
+ * GROUP BY a.id
+ * ```
+ */
+interface CrossJoinTable {
+  join: "cross";
+  /** The new alias for the joined table. */
+  alias: string;
+  /** The table name to join into the query. */
+  table: string;
+}
+/**
+ * Adds `WITH` CTE clauses to the query.
+ *
+ * I.e. queries like:
+ *
+ * ```sql
+ * WITH _find (tag, arg0, arg1) AS (
+ *   VALUES ($1::int, $2::character varying, $3::character varying), ($4, $5, $6)
+ * )
+ * ```
+ */
+interface ParsedCteClause {
+  /** The new alias for the CTE, i.e. `_find` in the above query. */
+  alias: string;
+  /** The columns, i.e. `tag, arg0, arg1` in the above query. */
+  columns?: {
+    columnName: string;
+    dbType: string;
+  }[];
+  /** The subquery for the AS of the CTE clause. */
+  query: {
+    kind: "raw";
+    sql: string;
+    bindings: readonly any[];
+  } | {
+    kind: "ast";
+    query: ParsedFindQuery;
+  };
+  /** Whether to include a `RECURSIVE` keyword after the `WITH`. */
+  recursive?: boolean;
+}
+/**
+ * Creates `LATERAL JOIN`s, currently used by `findCount` and JSON preloading.
+ */
+interface LateralJoinTable {
+  join: "lateral";
+  alias: string;
+  /** Used for join dependency tracking. */
+  fromAlias: string;
+  /** Used more for bookkeeping/consistency with other join tables than the query itself. */
+  table: string;
+  /** The subquery that will look for/roll-up N children. */
+  query: ParsedFindQuery;
+  /** Optional settings for the subquery, i.e. per-parent pagination. */
+  settings?: {
+    limit?: number;
+    offset?: number;
+  };
+}
+type ParsedTable = PrimaryTable | JoinTable | CrossJoinTable | LateralJoinTable;
+interface ParsedOrderBy {
+  alias: string;
+  column: string;
+  order: OrderBy;
+}
+type ParsedGroupBy = {
+  alias: string;
+  column: string;
+} | {
+  expression: string;
+};
+type ParsedSelect = string | ParsedSelectWithBindings;
+type ParsedSelectWithBindings = {
+  sql: string;
+  bindings: any[];
+  aliases: string[];
+};
+/** The result of parsing an `em.find` filter. */
+interface ParsedFindQuery {
+  selects: ParsedSelect[];
+  /** The primary table plus any joins. */
+  tables: ParsedTable[];
+  /** The query's conditions. */
+  condition?: ParsedExpressionFilter;
+  /** Extremely optional group bys; we generally don't support adhoc/aggregate queries, but the auto-batching infra uses these. */
+  groupBys?: ParsedGroupBy[];
+  /** Any optional orders to add before the default 'order by id'. */
+  orderBys: ParsedOrderBy[];
+  /** Optional CTE to prefix to the query, i.e. for recursive relations. */
+  ctes?: ParsedCteClause[];
+}
+/**
+ * Parses an `em.find` filter into a logical `ParsedFindQuery` AST, leaving optimization/pruning to callers.
+ *
+ * The main execution flow is:
+ * parseFindQuery -> beforeFind plugins -> optimizeCollectionJoins -> pruneUnusedJoins -> execute SQL.
+ */
+declare function parseFindQuery(meta: EntityMetadata, filter: any, opts?: {
+  conditions?: ExpressionFilter;
+  orderBy?: any;
+  pruneJoins?: boolean;
+  keepAliases?: string[];
+  softDeletes?: "include" | "exclude";
+  allowMultipleLeftJoins?: boolean;
+  optimizeJoinsToExists?: boolean;
+}): ParsedFindQuery;
+/**
+ * Look for conditions doing `some_column IS NULL` in an outer join that
+ * need an `id IS NOT NULL` to make sure they don't match inadvertently on
+ * the child row simply not existing.
+ *
+ * Note: Instead of injecting an extra `id IS NOT NULL` condition, I had tried
+ * using all INNER JOINs and flipping joins to OUTER only if the user explicit
+ * had `id IS NULL` in their filter, but that didn't work for queries that wanted
+ * to do an `OR` across two different children (which queries both children being
+ * OUTER JOINs, and detecting that case seemed complicated).
+ */
+declare function maybeAddIdNotNulls(query: ParsedFindQuery): void;
+/** Returns the `a` from `"a".*`. */
+declare function parseAlias(alias: string): string;
+/** Finds a filter field by fieldName or generated fieldIdName. */
+declare function findFilterField(meta: EntityMetadata, key: string): (Field & {
+  aliasSuffix: string;
+}) | undefined;
+/** Adds any user-configured default order, plus an "always order by id" for determinism. */
+declare function maybeAddOrderBy(query: ParsedFindQuery, meta: EntityMetadata, alias: string): void;
+declare function addTablePerClassJoinsAndClassTag(query: ParsedFindQuery, meta: EntityMetadata, alias: string, isPrimary: boolean): void;
+declare function getTables(query: ParsedFindQuery): [PrimaryTable, JoinTable[], LateralJoinTable[], CrossJoinTable[]];
+//#endregion
+export { CrossJoinTable, JoinTable, LateralJoinTable, ParsedCteClause, ParsedFindQuery, ParsedGroupBy, ParsedOrderBy, ParsedSelect, ParsedTable, PrimaryTable, addTablePerClassJoinsAndClassTag, findFilterField, getTables, maybeAddIdNotNulls, maybeAddOrderBy, parseAlias, parseFindQuery };
+//# sourceMappingURL=QueryParser.d.mts.map

package/build/queries/find/QueryParser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryParser.d.mts","names":[],"sources":["../../../src/queries/find/QueryParser.ts"],"mappings":";;;;UA6BiB;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;;;;EAsBA;;IAEE;;IAEA;;IAEA;;;;;;;;;;;;;;;;;;;;;UAsBa;EACf;;EAEA;;EAEA;;;;;;;;;;;;;UAce;;EAEf;;EAEA;IAAY;IAAoB;;;EAEhC;IAAS;IAAa;IAAa;;IAA+B;IAAa,OAAO;;;EAEtF;;;;;UAMe;EACf;EACA;;EAEA;;EAEA;;EAEA,OAAO;;EAEP;IAAa;IAAgB;;;KAGnB,cAAc,eAAe,YAAY,iBAAiB;UAErD;EACf;EACA;EACA,OAAO;;KAGG;EAAkB;EAAe;;EAAqB;;KAEtD,wBAAwB;KAC/B;EAA6B;EAAa;EAAiB;;;UAG/C;EACf,SAAS;;EAET,QAAQ;;EAER,YAAY;;EAEZ,WAAW;;EAEX,UAAU;;EAEV,OAAO;;;;;;;;iBASO,eACd,MAAM,gBACN,aACA;EACE,aAAa;EACb;EACA;EACA;EACA;EACA;EACA;IAED;;;;;;;;;;;;iBAqhBa,mBAAmB,OAAO;;iBAgC1B,WAAW;;iBAKX,gBAAgB,MAAM,gBAAgB,eAAe;EAAU;;;iBAU/D,gBAAgB,OAAO,iBAAiB,MAAM,gBAAgB;iBAiB9D,iCACd,OAAO,iBACP,MAAM,gBACN,eACA;iBA8Fc,UAAU,OAAO,mBAAmB,cAAc,aAAa,oBAAoB"}