joist-core 2.3.0 → 2.4.0

package/build/queries/sql/JoinTree.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinTree.cjs","names":["isEntityTable","getTableMgmt","fail","tableWhere","newTableProxy","tableEntityWhere","isEntity"],"sources":["../../../src/queries/sql/JoinTree.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport type { IdOf } from \"src/EntityManager.ts\";\nimport type { InnerJoin, LeftJoin } from \"src/queries/sql/Expr.ts\";\nimport type { QueryCondition, QueryJoin, QueryJoinInput } from \"src/queries/sql/query.ts\";\nimport {\n  type CollectionJoin,\n  type TableFilter,\n  type TableFor,\n  getTableMgmt,\n  isEntityTable,\n  newTableProxy,\n  tableEntityWhere,\n  tableWhere,\n} from \"src/queries/sql/Tables.ts\";\nimport type { FieldsOf } from \"src/typeMap.ts\";\nimport { fail } from \"src/utils.ts\";\n\n/** Domain filters and optional table bindings for one node in a relationship tree. */\nexport type JoinTree<T extends Entity> = Omit<TableFilter<T>, RelationNames<T>> & {\n  readonly as?: TableFor<T>;\n} & {\n  readonly [K in RelationNames<T>]?: FieldsOf<T>[K] extends {\n    kind: \"m2o\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\";\n    type: infer U extends Entity;\n  }\n    ? JoinTree<U> | (K extends keyof TableFilter<T> ? TableFilter<T>[K] : JoinedEntityFilter<U>)\n    : never;\n};\n\n/**\n * Filters entities, e.g. `{ books: \"b:1\" }` filters Book.id to 1.\n *\n * Adapted from `em.find`s EntityFilter, rather than a direct copy:\n *\n * - Keeps entity/ID, list, boolean, and `ne` filters, but omits scopes, find aliases, nested objects, and logical groups.\n *   - JoinTree supplies nested objects and table bindings separately.\n * - Lists can mix entities and IDs, unlike EntityFilter's separate entity[] and ID[] alternatives.\n * - Null is always allowed because these relationships use LEFT joins.\n * - undefined comes from JoinTree's optional relationship keys.\n */\ntype JoinedEntityFilter<T extends Entity> =\n  | IdOf<T>\n  | T\n  | readonly (IdOf<T> | T)[]\n  | boolean\n  | null\n  | { ne: IdOf<T> | T | null | undefined };\n\ntype RelationNames<T extends Entity> = {\n  [K in keyof FieldsOf<T>]: FieldsOf<T>[K] extends { kind: \"m2o\" | \"poly\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\" }\n    ? K\n    : never;\n}[keyof FieldsOf<T>];\n\n/**\n * Validates a join tree against the entity in `from`, preserving its exact table bindings.\n *\n * I.e. given:\n *\n * ```ts\n * const [a, b] = tables(Author, Book);\n * em.query({\n *   from: a,\n *   join: { books: { as: b, title: \"One\" } },\n *   select: { title: b.title },\n * });\n * // F = typeof a\n * // J = { books: { as: typeof b; title: string } }\n * ```\n *\n * We:\n *\n * - Infer `T = Author` from `F`,\n * - Validate `books` against `Author`,\n * - Validate `title` against `Book`, and\n * - Retain `typeof b` for result typing.\n */\nexport type CheckJoinInput<F, J> =\n  // If J accepts the entire list-or-tree union, its annotation erased the join shape.\n  // Queries with no join infer [] and use the list branch below.\n  QueryJoinInput extends J\n    ? { join?: \"join was typed too generically; use `satisfies Query` instead of `: Query`\" }\n    : // If J is an array, then it's a QueryJoinList and we can return unknown\n      [J] extends [readonly unknown[]]\n      ? unknown\n      : F extends TableFor<infer T extends Entity>\n        ? // Validate domain filters and bindings, including extra keys on variables and nested trees.\n          { join?: JoinTree<T> & CheckTree<T, J> }\n        : // This incompatible type reports why a tree can't start at a non-entity source.\n          { join?: \"join trees require an entity table in from\" };\n\n/**\n * Determines which tables a join tree binds and whether each uses an INNER or LEFT join.\n *\n * Query result types use these entries to identify available tables and columns that can be null.\n *\n * I.e. Author.books.author uses LEFT joins for both Book and its Author because an Author may have no Books.\n */\nexport type TreeEntries<T extends Entity, J, Nullable extends boolean = false> =\n  // If every string is valid keyof J, then we've lost our literal type (i.e. as const) and were\n  // passed an opaque type like Record<string, unknown> that doesn't expose its specific relationship\n  // keys or table bindings to collect, so just return never.\n  string extends keyof J\n    ? never\n    : // If J has an `as` key, it might be the general JoinTree<T> type, which we check for in the next ternary.\n      // If J doesn't have `as`, it can't be the general `JoinTree<T>` so we can jump straight to TreeEntriesImpl.\n      \"as\" extends keyof J\n      ? // If `JoinTree<T> extends J`, then we again have a board type. CheckTree will reject this input, but\n        // here we stop instead of following every relationship in the domain graph.\n        JoinTree<T> extends J\n        ? never\n        : TreeEntriesImpl<T, J, Nullable>\n      : TreeEntriesImpl<T, J, Nullable>;\n\n/** Collects join entries from the relationship keys supplied in this tree node. */\ntype TreeEntriesImpl<T extends Entity, J, Nullable extends boolean> = {\n  [K in keyof J & keyof FieldsOf<T>]: FieldsOf<T>[K] extends {\n    kind: \"m2o\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\";\n    type: infer U extends Entity;\n  }\n    ? TreeNodeJoins<\n        U,\n        Exclude<J[K], undefined>,\n        Nullable extends true ? true : FieldsOf<T>[K] extends { kind: \"m2o\"; nullable: never } ? false : true\n      >\n    : never;\n}[keyof J & keyof FieldsOf<T>];\n\n/**\n * Collects the join entries for this node's table binding and its nested relationships.\n *\n * An `as` binding contributes a LeftJoin or InnerJoin according to Nullable.\n * Without a binding, only nested relationship entries are included; entity, ID, and list filters add none.\n */\ntype TreeNodeJoins<T extends Entity, J, Nullable extends boolean> =\n  // If `J extends Entity | unknown[]`, then it's a leaf entity/id filter, so stop recursing\n  J extends Entity | readonly unknown[]\n    ? never\n    : // If `J extends object`, look for an `as` binding and nested relationships.\n      // If `J extends object` is false, this is a scalar filter like \"b:1\" in `{ books: \"b:1\" }` and we stop here.\n      J extends object\n      ?\n          | (J extends { readonly as: infer A extends TableFor<T> }\n              ? Nullable extends true\n                ? LeftJoin<A>\n                : InnerJoin<A>\n              : never)\n          | TreeEntries<T, J, Nullable>\n      : never;\n\n/** Rejects broad tree annotations before checking their supplied keys and values. */\ntype CheckTree<T extends Entity, J> =\n  // An entity or a list of entities/IDs is a filter value, so don't check its properties as tree keys.\n  J extends Entity | readonly unknown[]\n    ? unknown\n    : \"as\" extends keyof J\n      ? JoinTree<T> extends J\n        ? \"join tree bindings were typed too generically; use `satisfies JoinTree<T>` instead of `: JoinTree<T>`\"\n        : CheckTreeKeys<T, J>\n      : CheckTreeKeys<T, J>;\n\n/** Rejects unknown tree keys, including extra properties on objects stored in variables. */\ntype CheckTreeKeys<T extends Entity, J> = [Exclude<keyof J, keyof JoinTree<T>>] extends [never]\n  ? {\n      [K in keyof J]: K extends \"as\"\n        ? J[K] extends TableFor<T> | undefined\n          ? unknown\n          : never\n        : K extends keyof JoinTree<T>\n          ? K extends keyof FieldsOf<T>\n            ? FieldsOf<T>[K] extends { kind: \"m2o\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\"; type: infer U extends Entity }\n              ? (J[K] extends JoinTree<T>[K] ? unknown : never) & CheckRelationTree<U, J[K]>\n              : J[K] extends JoinTree<T>[K]\n                ? unknown\n                : never\n            : unknown\n          : never;\n      // Report the error on the tree object; intersecting a message with a boolean field would collapse to never.\n    }\n  : `unknown join tree field '${Exclude<keyof J, keyof JoinTree<T>> & string}'`;\n\n/** Checks each optional relationship alternative without treating entities or exclusion filters as trees. */\ntype CheckRelationTree<T extends Entity, J> = J extends object\n  ? \"ne\" extends keyof J\n    ? unknown\n    : CheckTree<T, J>\n  : unknown;\n\n/**\n * Walks domain relationship filters into ordinary SQL joins and WHERE predicates.\n * Handles remain query-local; no SQL aliases or caller objects are changed.\n * I.e. Author.books.author emits Book before its Author, even if only the final Author has an as binding.\n */\nexport function compileJoinTree(from: unknown, tree: unknown): { joins: QueryJoin[]; condition: QueryCondition } {\n  if (!isEntityTable(from)) fail(\"Join trees require an entity table in from\");\n  const joins: QueryJoin[] = [];\n  const conditions: QueryCondition[] = [];\n  const bound = new Set<object>([getTableMgmt(from)]);\n  visitTree(from, tree, joins, conditions, bound);\n  return { joins, condition: { and: conditions } };\n}\n\n/**\n * Compiles one node, leaving relationship conditions in WHERE rather than ON.\n * Each relationship gets one target handle; reusing a bound handle would merge distinct paths.\n * Owning-reference ID filters stay on the FK, while collection ID filters use the joined primary key.\n */\nfunction visitTree(\n  source: TableFor<Entity>,\n  tree: unknown,\n  joins: QueryJoin[],\n  conditions: QueryCondition[],\n  bound: Set<object>,\n): void {\n  if (!isTreeObject(tree)) fail(\"Expected a join tree object\");\n  const mgmt = getTableMgmt(source);\n  if (tree.as !== undefined && tree.as !== source) fail(\"Join tree root as must be the same table handle as from\");\n  for (const [key, value] of Object.entries(tree)) {\n    if (key === \"as\") continue;\n    const field = mgmt.meta.allFields[key] ?? fail(`Unknown join tree field ${mgmt.meta.type}.${key}`);\n    if (!(key in mgmt.meta.fields)) fail(`Join trees do not support inherited field ${mgmt.meta.type}.${key}`);\n    if (field.kind === \"poly\") fail(`Join trees do not support polymorphic field ${mgmt.meta.type}.${key}`);\n    if ([\"m2o\", \"o2m\", \"lo2m\", \"m2m\", \"o2o\"].includes(field.kind)) {\n      if (value === undefined) continue;\n      if (field.kind === \"m2o\" && !isTreeObject(value)) {\n        // Avoid joining the related table; add the condition directly to the FK column.\n        conditions.push(tableWhere(mgmt, { [key]: value }));\n        continue;\n      }\n      if (field.kind === \"m2o\" && isTreeObject(value) && Object.hasOwn(value, \"ne\")) {\n        // Exclusion filters also apply directly to the FK column without joining the related table.\n        conditions.push(tableWhere(mgmt, { [key]: value }));\n        continue;\n      }\n      // The field-kind check above establishes the relationship metadata and factory shape.\n      if (!(\"otherMetadata\" in field)) fail(`Unsupported join tree field ${mgmt.meta.type}.${key}`);\n      const meta = field.otherMetadata();\n      const target = isTreeObject(value) && value.as !== undefined ? value.as : newTableProxy(meta.cstr);\n      if (!isEntityTable(target) || getTableMgmt(target).meta !== meta) {\n        fail(`Join tree binding for ${mgmt.meta.type}.${key} must be a ${meta.type} table`);\n      }\n      const identity = getTableMgmt(target);\n      if (bound.has(identity))\n        fail(`Join tree table ${meta.type} is bound more than once; create a separate table handle`);\n      bound.add(identity);\n      const relation = (source as unknown as Record<string, CollectionJoin<Entity>>)[key];\n      joins.push(relation.as(target));\n      // Recurse into nested relationship filters, e.g. `{ books: { title: \"One\" } }`.\n      // A `{ ne: ... }` object instead filters the joined entity's ID, so handle it like an ID or entity value.\n      // We don't have to handle other keys like `gt`, etc. b/c we know this is an entity filter, not a value filter.\n      if (isTreeObject(value) && !Object.hasOwn(value, \"ne\")) {\n        visitTree(target, value, joins, conditions, bound);\n      } else {\n        conditions.push(tableEntityWhere(identity, value));\n      }\n    } else {\n      conditions.push(tableWhere(mgmt, { [key]: value }));\n    }\n  }\n}\n\n/** Separates nested relationship objects from entity, ID, and list filters. */\nfunction isTreeObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value) && !isEntity(value);\n}\n"],"mappings":";;;;;;;;;;AAiMA,SAAgB,gBAAgB,MAAe,MAAkE;CAC/G,IAAI,CAACA,2BAAAA,cAAc,IAAI,GAAG,cAAA,KAAK,4CAA4C;CAC3E,MAAM,QAAqB,CAAC;CAC5B,MAAM,aAA+B,CAAC;CAEtC,UAAU,MAAM,MAAM,OAAO,4BAAY,IADvB,IAAY,CAACC,2BAAAA,aAAa,IAAI,CAAC,CACJ,CAAC;CAC9C,OAAO;EAAE;EAAO,WAAW,EAAE,KAAK,WAAW;CAAE;AACjD;;;;;;AAOA,SAAS,UACP,QACA,MACA,OACA,YACA,OACM;CACN,IAAI,CAAC,aAAa,IAAI,GAAG,cAAA,KAAK,6BAA6B;CAC3D,MAAM,OAAOA,2BAAAA,aAAa,MAAM;CAChC,IAAI,KAAK,OAAO,KAAA,KAAa,KAAK,OAAO,QAAQ,cAAA,KAAK,yDAAyD;CAC/G,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,GAAG;EAC/C,IAAI,QAAQ,MAAM;EAClB,MAAM,QAAQ,KAAK,KAAK,UAAU,QAAQC,cAAAA,KAAK,2BAA2B,KAAK,KAAK,KAAK,GAAG,KAAK;EACjG,IAAI,EAAE,OAAO,KAAK,KAAK,SAAS,cAAA,KAAK,6CAA6C,KAAK,KAAK,KAAK,GAAG,KAAK;EACzG,IAAI,MAAM,SAAS,QAAQ,cAAA,KAAK,+CAA+C,KAAK,KAAK,KAAK,GAAG,KAAK;EACtG,IAAI;GAAC;GAAO;GAAO;GAAQ;GAAO;EAAK,CAAC,CAAC,SAAS,MAAM,IAAI,GAAG;GAC7D,IAAI,UAAU,KAAA,GAAW;GACzB,IAAI,MAAM,SAAS,SAAS,CAAC,aAAa,KAAK,GAAG;IAEhD,WAAW,KAAKC,2BAAAA,WAAW,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC;IAClD;GACF;GACA,IAAI,MAAM,SAAS,SAAS,aAAa,KAAK,KAAK,OAAO,OAAO,OAAO,IAAI,GAAG;IAE7E,WAAW,KAAKA,2BAAAA,WAAW,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC;IAClD;GACF;GAEA,IAAI,EAAE,mBAAmB,QAAQ,cAAA,KAAK,+BAA+B,KAAK,KAAK,KAAK,GAAG,KAAK;GAC5F,MAAM,OAAO,MAAM,cAAc;GACjC,MAAM,SAAS,aAAa,KAAK,KAAK,MAAM,OAAO,KAAA,IAAY,MAAM,KAAKC,2BAAAA,cAAc,KAAK,IAAI;GACjG,IAAI,CAACJ,2BAAAA,cAAc,MAAM,KAAKC,2BAAAA,aAAa,MAAM,CAAC,CAAC,SAAS,MAC1D,cAAA,KAAK,yBAAyB,KAAK,KAAK,KAAK,GAAG,IAAI,aAAa,KAAK,KAAK,OAAO;GAEpF,MAAM,WAAWA,2BAAAA,aAAa,MAAM;GACpC,IAAI,MAAM,IAAI,QAAQ,GACpB,cAAA,KAAK,mBAAmB,KAAK,KAAK,yDAAyD;GAC7F,MAAM,IAAI,QAAQ;GAClB,MAAM,WAAY,OAA6D;GAC/E,MAAM,KAAK,SAAS,GAAG,MAAM,CAAC;GAI9B,IAAI,aAAa,KAAK,KAAK,CAAC,OAAO,OAAO,OAAO,IAAI,GACnD,UAAU,QAAQ,OAAO,OAAO,YAAY,KAAK;QAEjD,WAAW,KAAKI,2BAAAA,iBAAiB,UAAU,KAAK,CAAC;EAErD,OACE,WAAW,KAAKF,2BAAAA,WAAW,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC;CAEtD;AACF;;AAGA,SAAS,aAAa,OAAkD;CACtE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK,KAAK,CAACG,eAAAA,SAAS,KAAK;AAChG"}

package/build/queries/sql/JoinTree.d.cts

@@ -0,0 +1,107 @@
+import { FieldsOf } from "../../typeMap.cjs";
+import { TableFilter, TableFor } from "./Tables.cjs";
+import { QueryCondition, QueryJoin, QueryJoinInput } from "./query.cjs";
+import { InnerJoin, LeftJoin } from "./Expr.cjs";
+import { IdOf } from "../../EntityManager.cjs";
+import { Entity } from "../../Entity.cjs";
+//#region src/queries/sql/JoinTree.d.ts
+/** Domain filters and optional table bindings for one node in a relationship tree. */
+type JoinTree<T extends Entity> = Omit<TableFilter<T>, RelationNames<T>> & {
+  readonly as?: TableFor<T>;
+} & { readonly [K in RelationNames<T>]?: FieldsOf<T>[K] extends {
+  kind: "m2o" | "o2m" | "lo2m" | "m2m" | "o2o";
+  type: infer U extends Entity;
+} ? JoinTree<U> | (K extends keyof TableFilter<T> ? TableFilter<T>[K] : JoinedEntityFilter<U>) : never; };
+/**
+ * Filters entities, e.g. `{ books: "b:1" }` filters Book.id to 1.
+ *
+ * Adapted from `em.find`s EntityFilter, rather than a direct copy:
+ *
+ * - Keeps entity/ID, list, boolean, and `ne` filters, but omits scopes, find aliases, nested objects, and logical groups.
+ *   - JoinTree supplies nested objects and table bindings separately.
+ * - Lists can mix entities and IDs, unlike EntityFilter's separate entity[] and ID[] alternatives.
+ * - Null is always allowed because these relationships use LEFT joins.
+ * - undefined comes from JoinTree's optional relationship keys.
+ */
+type JoinedEntityFilter<T extends Entity> = IdOf<T> | T | readonly (IdOf<T> | T)[] | boolean | null | {
+  ne: IdOf<T> | T | null | undefined;
+};
+type RelationNames<T extends Entity> = { [K in keyof FieldsOf<T>]: FieldsOf<T>[K] extends {
+  kind: "m2o" | "poly" | "o2m" | "lo2m" | "m2m" | "o2o";
+} ? K : never; }[keyof FieldsOf<T>];
+/**
+ * Validates a join tree against the entity in `from`, preserving its exact table bindings.
+ *
+ * I.e. given:
+ *
+ * ```ts
+ * const [a, b] = tables(Author, Book);
+ * em.query({
+ *   from: a,
+ *   join: { books: { as: b, title: "One" } },
+ *   select: { title: b.title },
+ * });
+ * // F = typeof a
+ * // J = { books: { as: typeof b; title: string } }
+ * ```
+ *
+ * We:
+ *
+ * - Infer `T = Author` from `F`,
+ * - Validate `books` against `Author`,
+ * - Validate `title` against `Book`, and
+ * - Retain `typeof b` for result typing.
+ */
+type CheckJoinInput<F, J> = QueryJoinInput extends J ? {
+  join?: "join was typed too generically; use `satisfies Query` instead of `: Query`";
+} : [J] extends [readonly unknown[]] ? unknown : F extends TableFor<infer T extends Entity> ? {
+  join?: JoinTree<T> & CheckTree<T, J>;
+} : {
+  join?: "join trees require an entity table in from";
+};
+/**
+ * Determines which tables a join tree binds and whether each uses an INNER or LEFT join.
+ *
+ * Query result types use these entries to identify available tables and columns that can be null.
+ *
+ * I.e. Author.books.author uses LEFT joins for both Book and its Author because an Author may have no Books.
+ */
+type TreeEntries<T extends Entity, J, Nullable extends boolean = false> = string extends keyof J ? never : "as" extends keyof J ? JoinTree<T> extends J ? never : TreeEntriesImpl<T, J, Nullable> : TreeEntriesImpl<T, J, Nullable>;
+/** Collects join entries from the relationship keys supplied in this tree node. */
+type TreeEntriesImpl<T extends Entity, J, Nullable extends boolean> = { [K in keyof J & keyof FieldsOf<T>]: FieldsOf<T>[K] extends {
+  kind: "m2o" | "o2m" | "lo2m" | "m2m" | "o2o";
+  type: infer U extends Entity;
+} ? TreeNodeJoins<U, Exclude<J[K], undefined>, Nullable extends true ? true : FieldsOf<T>[K] extends {
+  kind: "m2o";
+  nullable: never;
+} ? false : true> : never; }[keyof J & keyof FieldsOf<T>];
+/**
+ * Collects the join entries for this node's table binding and its nested relationships.
+ *
+ * An `as` binding contributes a LeftJoin or InnerJoin according to Nullable.
+ * Without a binding, only nested relationship entries are included; entity, ID, and list filters add none.
+ */
+type TreeNodeJoins<T extends Entity, J, Nullable extends boolean> = J extends Entity | readonly unknown[] ? never : J extends object ? (J extends {
+  readonly as: infer A extends TableFor<T>;
+} ? Nullable extends true ? LeftJoin<A> : InnerJoin<A> : never) | TreeEntries<T, J, Nullable> : never;
+/** Rejects broad tree annotations before checking their supplied keys and values. */
+type CheckTree<T extends Entity, J> = J extends Entity | readonly unknown[] ? unknown : "as" extends keyof J ? JoinTree<T> extends J ? "join tree bindings were typed too generically; use `satisfies JoinTree<T>` instead of `: JoinTree<T>`" : CheckTreeKeys<T, J> : CheckTreeKeys<T, J>;
+/** Rejects unknown tree keys, including extra properties on objects stored in variables. */
+type CheckTreeKeys<T extends Entity, J> = [Exclude<keyof J, keyof JoinTree<T>>] extends [never] ? { [K in keyof J]: K extends "as" ? J[K] extends TableFor<T> | undefined ? unknown : never : K extends keyof JoinTree<T> ? K extends keyof FieldsOf<T> ? FieldsOf<T>[K] extends {
+  kind: "m2o" | "o2m" | "lo2m" | "m2m" | "o2o";
+  type: infer U extends Entity;
+} ? (J[K] extends JoinTree<T>[K] ? unknown : never) & CheckRelationTree<U, J[K]> : J[K] extends JoinTree<T>[K] ? unknown : never : unknown : never; } : `unknown join tree field '${Exclude<keyof J, keyof JoinTree<T>> & string}'`;
+/** Checks each optional relationship alternative without treating entities or exclusion filters as trees. */
+type CheckRelationTree<T extends Entity, J> = J extends object ? "ne" extends keyof J ? unknown : CheckTree<T, J> : unknown;
+/**
+ * Walks domain relationship filters into ordinary SQL joins and WHERE predicates.
+ * Handles remain query-local; no SQL aliases or caller objects are changed.
+ * I.e. Author.books.author emits Book before its Author, even if only the final Author has an as binding.
+ */
+declare function compileJoinTree(from: unknown, tree: unknown): {
+  joins: QueryJoin[];
+  condition: QueryCondition;
+};
+//#endregion
+export { CheckJoinInput, JoinTree, TreeEntries, compileJoinTree };
+//# sourceMappingURL=JoinTree.d.cts.map

package/build/queries/sql/JoinTree.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinTree.d.cts","names":[],"sources":["../../../src/queries/sql/JoinTree.ts"],"mappings":";;;;;;;;KAkBY,SAAS,UAAU,UAAU,KAAK,YAAY,IAAI,cAAc;WACjE,KAAK,SAAS;gBAEb,KAAK,cAAc,MAAM,SAAS,GAAG;EAC7C;EACA,YAAY,UAAU;IAEpB,SAAS,MAAM,gBAAgB,YAAY,KAAK,YAAY,GAAG,KAAK,mBAAmB;;;;;;;;;;;;KAexF,mBAAmB,UAAU,UAC9B,KAAK,KACL,cACU,KAAK,KAAK;EAGlB,IAAI,KAAK,KAAK;;KAEf,cAAc,UAAU,aAC1B,WAAW,SAAS,KAAK,SAAS,GAAG;EAAa;IAC/C,mBAEE,SAAS;;;;;;;;;;;;;;;;;;;;;;;;KAyBL,eAAe,GAAG,KAG5B,uBAAuB;EACjB;KAED,4CAEC,UAAU,eAAe,UAAU;EAE/B,OAAO,SAAS,KAAK,UAAU,GAAG;;EAElC;;;;;;;;;KASA,YAAY,UAAU,QAAQ,GAAG,yDAItB,+BAIE,IAGjB,SAAS,WAAW,YAElB,gBAAgB,GAAG,GAAG,YACxB,gBAAgB,GAAG,GAAG;;KAGzB,gBAAgB,UAAU,QAAQ,GAAG,+BACvC,WAAW,UAAU,SAAS,KAAK,SAAS,GAAG;EAC9C;EACA,YAAY,UAAU;IAEpB,cACE,GACA,QAAQ,EAAE,gBACV,+BAA+B,SAAS,GAAG;EAAa;EAAa;mCAGrE,UAAU,SAAS;;;;;;;KAQtB,cAAc,UAAU,QAAQ,GAAG,4BAEtC,UAAU,sCAIN,oBAEO;WAAqB,UAAU,UAAU,SAAS;IAC/C,wBACE,SAAS,KACT,UAAU,cAEhB,YAAY,GAAG,GAAG;;KAIzB,UAAU,UAAU,QAAQ,KAE/B,UAAU,2DAEa,IACjB,SAAS,WAAW,8GAElB,cAAc,GAAG,KACnB,cAAc,GAAG;;KAGpB,cAAc,UAAU,QAAQ,MAAM,cAAc,SAAS,SAAS,0BAEpE,WAAW,IAAI,iBACZ,EAAE,WAAW,SAAS,mCAGtB,gBAAgB,SAAS,KACvB,gBAAgB,SAAS,KACvB,SAAS,GAAG;EAAa;EAA8C,YAAY,UAAU;KAC1F,EAAE,WAAW,SAAS,GAAG,wBAAwB,kBAAkB,GAAG,EAAE,MACzE,EAAE,WAAW,SAAS,GAAG,wEAOT,cAAc,SAAS,SAAS;;KAG3D,kBAAkB,UAAU,QAAQ,KAAK,sCACvB,cAEjB,UAAU,GAAG;;;;;;iBAQH,gBAAgB,eAAe;EAAkB,OAAO;EAAa,WAAW"}

package/build/queries/sql/JoinTree.d.mts

@@ -0,0 +1,107 @@
+import { FieldsOf } from "../../typeMap.mjs";
+import { TableFilter, TableFor } from "./Tables.mjs";
+import { QueryCondition, QueryJoin, QueryJoinInput } from "./query.mjs";
+import { InnerJoin, LeftJoin } from "./Expr.mjs";
+import { IdOf } from "../../EntityManager.mjs";
+import { Entity } from "../../Entity.mjs";
+//#region src/queries/sql/JoinTree.d.ts
+/** Domain filters and optional table bindings for one node in a relationship tree. */
+type JoinTree<T extends Entity> = Omit<TableFilter<T>, RelationNames<T>> & {
+  readonly as?: TableFor<T>;
+} & { readonly [K in RelationNames<T>]?: FieldsOf<T>[K] extends {
+  kind: "m2o" | "o2m" | "lo2m" | "m2m" | "o2o";
+  type: infer U extends Entity;
+} ? JoinTree<U> | (K extends keyof TableFilter<T> ? TableFilter<T>[K] : JoinedEntityFilter<U>) : never; };
+/**
+ * Filters entities, e.g. `{ books: "b:1" }` filters Book.id to 1.
+ *
+ * Adapted from `em.find`s EntityFilter, rather than a direct copy:
+ *
+ * - Keeps entity/ID, list, boolean, and `ne` filters, but omits scopes, find aliases, nested objects, and logical groups.
+ *   - JoinTree supplies nested objects and table bindings separately.
+ * - Lists can mix entities and IDs, unlike EntityFilter's separate entity[] and ID[] alternatives.
+ * - Null is always allowed because these relationships use LEFT joins.
+ * - undefined comes from JoinTree's optional relationship keys.
+ */
+type JoinedEntityFilter<T extends Entity> = IdOf<T> | T | readonly (IdOf<T> | T)[] | boolean | null | {
+  ne: IdOf<T> | T | null | undefined;
+};
+type RelationNames<T extends Entity> = { [K in keyof FieldsOf<T>]: FieldsOf<T>[K] extends {
+  kind: "m2o" | "poly" | "o2m" | "lo2m" | "m2m" | "o2o";
+} ? K : never; }[keyof FieldsOf<T>];
+/**
+ * Validates a join tree against the entity in `from`, preserving its exact table bindings.
+ *
+ * I.e. given:
+ *
+ * ```ts
+ * const [a, b] = tables(Author, Book);
+ * em.query({
+ *   from: a,
+ *   join: { books: { as: b, title: "One" } },
+ *   select: { title: b.title },
+ * });
+ * // F = typeof a
+ * // J = { books: { as: typeof b; title: string } }
+ * ```
+ *
+ * We:
+ *
+ * - Infer `T = Author` from `F`,
+ * - Validate `books` against `Author`,
+ * - Validate `title` against `Book`, and
+ * - Retain `typeof b` for result typing.
+ */
+type CheckJoinInput<F, J> = QueryJoinInput extends J ? {
+  join?: "join was typed too generically; use `satisfies Query` instead of `: Query`";
+} : [J] extends [readonly unknown[]] ? unknown : F extends TableFor<infer T extends Entity> ? {
+  join?: JoinTree<T> & CheckTree<T, J>;
+} : {
+  join?: "join trees require an entity table in from";
+};
+/**
+ * Determines which tables a join tree binds and whether each uses an INNER or LEFT join.
+ *
+ * Query result types use these entries to identify available tables and columns that can be null.
+ *
+ * I.e. Author.books.author uses LEFT joins for both Book and its Author because an Author may have no Books.
+ */
+type TreeEntries<T extends Entity, J, Nullable extends boolean = false> = string extends keyof J ? never : "as" extends keyof J ? JoinTree<T> extends J ? never : TreeEntriesImpl<T, J, Nullable> : TreeEntriesImpl<T, J, Nullable>;
+/** Collects join entries from the relationship keys supplied in this tree node. */
+type TreeEntriesImpl<T extends Entity, J, Nullable extends boolean> = { [K in keyof J & keyof FieldsOf<T>]: FieldsOf<T>[K] extends {
+  kind: "m2o" | "o2m" | "lo2m" | "m2m" | "o2o";
+  type: infer U extends Entity;
+} ? TreeNodeJoins<U, Exclude<J[K], undefined>, Nullable extends true ? true : FieldsOf<T>[K] extends {
+  kind: "m2o";
+  nullable: never;
+} ? false : true> : never; }[keyof J & keyof FieldsOf<T>];
+/**
+ * Collects the join entries for this node's table binding and its nested relationships.
+ *
+ * An `as` binding contributes a LeftJoin or InnerJoin according to Nullable.
+ * Without a binding, only nested relationship entries are included; entity, ID, and list filters add none.
+ */
+type TreeNodeJoins<T extends Entity, J, Nullable extends boolean> = J extends Entity | readonly unknown[] ? never : J extends object ? (J extends {
+  readonly as: infer A extends TableFor<T>;
+} ? Nullable extends true ? LeftJoin<A> : InnerJoin<A> : never) | TreeEntries<T, J, Nullable> : never;
+/** Rejects broad tree annotations before checking their supplied keys and values. */
+type CheckTree<T extends Entity, J> = J extends Entity | readonly unknown[] ? unknown : "as" extends keyof J ? JoinTree<T> extends J ? "join tree bindings were typed too generically; use `satisfies JoinTree<T>` instead of `: JoinTree<T>`" : CheckTreeKeys<T, J> : CheckTreeKeys<T, J>;
+/** Rejects unknown tree keys, including extra properties on objects stored in variables. */
+type CheckTreeKeys<T extends Entity, J> = [Exclude<keyof J, keyof JoinTree<T>>] extends [never] ? { [K in keyof J]: K extends "as" ? J[K] extends TableFor<T> | undefined ? unknown : never : K extends keyof JoinTree<T> ? K extends keyof FieldsOf<T> ? FieldsOf<T>[K] extends {
+  kind: "m2o" | "o2m" | "lo2m" | "m2m" | "o2o";
+  type: infer U extends Entity;
+} ? (J[K] extends JoinTree<T>[K] ? unknown : never) & CheckRelationTree<U, J[K]> : J[K] extends JoinTree<T>[K] ? unknown : never : unknown : never; } : `unknown join tree field '${Exclude<keyof J, keyof JoinTree<T>> & string}'`;
+/** Checks each optional relationship alternative without treating entities or exclusion filters as trees. */
+type CheckRelationTree<T extends Entity, J> = J extends object ? "ne" extends keyof J ? unknown : CheckTree<T, J> : unknown;
+/**
+ * Walks domain relationship filters into ordinary SQL joins and WHERE predicates.
+ * Handles remain query-local; no SQL aliases or caller objects are changed.
+ * I.e. Author.books.author emits Book before its Author, even if only the final Author has an as binding.
+ */
+declare function compileJoinTree(from: unknown, tree: unknown): {
+  joins: QueryJoin[];
+  condition: QueryCondition;
+};
+//#endregion
+export { CheckJoinInput, JoinTree, TreeEntries, compileJoinTree };
+//# sourceMappingURL=JoinTree.d.mts.map

package/build/queries/sql/JoinTree.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinTree.d.mts","names":[],"sources":["../../../src/queries/sql/JoinTree.ts"],"mappings":";;;;;;;;KAkBY,SAAS,UAAU,UAAU,KAAK,YAAY,IAAI,cAAc;WACjE,KAAK,SAAS;gBAEb,KAAK,cAAc,MAAM,SAAS,GAAG;EAC7C;EACA,YAAY,UAAU;IAEpB,SAAS,MAAM,gBAAgB,YAAY,KAAK,YAAY,GAAG,KAAK,mBAAmB;;;;;;;;;;;;KAexF,mBAAmB,UAAU,UAC9B,KAAK,KACL,cACU,KAAK,KAAK;EAGlB,IAAI,KAAK,KAAK;;KAEf,cAAc,UAAU,aAC1B,WAAW,SAAS,KAAK,SAAS,GAAG;EAAa;IAC/C,mBAEE,SAAS;;;;;;;;;;;;;;;;;;;;;;;;KAyBL,eAAe,GAAG,KAG5B,uBAAuB;EACjB;KAED,4CAEC,UAAU,eAAe,UAAU;EAE/B,OAAO,SAAS,KAAK,UAAU,GAAG;;EAElC;;;;;;;;;KASA,YAAY,UAAU,QAAQ,GAAG,yDAItB,+BAIE,IAGjB,SAAS,WAAW,YAElB,gBAAgB,GAAG,GAAG,YACxB,gBAAgB,GAAG,GAAG;;KAGzB,gBAAgB,UAAU,QAAQ,GAAG,+BACvC,WAAW,UAAU,SAAS,KAAK,SAAS,GAAG;EAC9C;EACA,YAAY,UAAU;IAEpB,cACE,GACA,QAAQ,EAAE,gBACV,+BAA+B,SAAS,GAAG;EAAa;EAAa;mCAGrE,UAAU,SAAS;;;;;;;KAQtB,cAAc,UAAU,QAAQ,GAAG,4BAEtC,UAAU,sCAIN,oBAEO;WAAqB,UAAU,UAAU,SAAS;IAC/C,wBACE,SAAS,KACT,UAAU,cAEhB,YAAY,GAAG,GAAG;;KAIzB,UAAU,UAAU,QAAQ,KAE/B,UAAU,2DAEa,IACjB,SAAS,WAAW,8GAElB,cAAc,GAAG,KACnB,cAAc,GAAG;;KAGpB,cAAc,UAAU,QAAQ,MAAM,cAAc,SAAS,SAAS,0BAEpE,WAAW,IAAI,iBACZ,EAAE,WAAW,SAAS,mCAGtB,gBAAgB,SAAS,KACvB,gBAAgB,SAAS,KACvB,SAAS,GAAG;EAAa;EAA8C,YAAY,UAAU;KAC1F,EAAE,WAAW,SAAS,GAAG,wBAAwB,kBAAkB,GAAG,EAAE,MACzE,EAAE,WAAW,SAAS,GAAG,wEAOT,cAAc,SAAS,SAAS;;KAG3D,kBAAkB,UAAU,QAAQ,KAAK,sCACvB,cAEjB,UAAU,GAAG;;;;;;iBAQH,gBAAgB,eAAe;EAAkB,OAAO;EAAa,WAAW"}

package/build/queries/sql/JoinTree.js

@@ -0,0 +1,71 @@
+import { fail } from "../../utils.js";
+import { getTableMgmt, isEntityTable, newTableProxy, tableEntityWhere, tableWhere } from "./Tables.js";
+import { isEntity } from "../../Entity.js";
+//#region src/queries/sql/JoinTree.ts
+/**
+* Walks domain relationship filters into ordinary SQL joins and WHERE predicates.
+* Handles remain query-local; no SQL aliases or caller objects are changed.
+* I.e. Author.books.author emits Book before its Author, even if only the final Author has an as binding.
+*/
+function compileJoinTree(from, tree) {
+	if (!isEntityTable(from)) fail("Join trees require an entity table in from");
+	const joins = [];
+	const conditions = [];
+	visitTree(from, tree, joins, conditions, /* @__PURE__ */ new Set([getTableMgmt(from)]));
+	return {
+		joins,
+		condition: { and: conditions }
+	};
+}
+/**
+* Compiles one node, leaving relationship conditions in WHERE rather than ON.
+* Each relationship gets one target handle; reusing a bound handle would merge distinct paths.
+* Owning-reference ID filters stay on the FK, while collection ID filters use the joined primary key.
+*/
+function visitTree(source, tree, joins, conditions, bound) {
+	if (!isTreeObject(tree)) fail("Expected a join tree object");
+	const mgmt = getTableMgmt(source);
+	if (tree.as !== void 0 && tree.as !== source) fail("Join tree root as must be the same table handle as from");
+	for (const [key, value] of Object.entries(tree)) {
+		if (key === "as") continue;
+		const field = mgmt.meta.allFields[key] ?? fail(`Unknown join tree field ${mgmt.meta.type}.${key}`);
+		if (!(key in mgmt.meta.fields)) fail(`Join trees do not support inherited field ${mgmt.meta.type}.${key}`);
+		if (field.kind === "poly") fail(`Join trees do not support polymorphic field ${mgmt.meta.type}.${key}`);
+		if ([
+			"m2o",
+			"o2m",
+			"lo2m",
+			"m2m",
+			"o2o"
+		].includes(field.kind)) {
+			if (value === void 0) continue;
+			if (field.kind === "m2o" && !isTreeObject(value)) {
+				conditions.push(tableWhere(mgmt, { [key]: value }));
+				continue;
+			}
+			if (field.kind === "m2o" && isTreeObject(value) && Object.hasOwn(value, "ne")) {
+				conditions.push(tableWhere(mgmt, { [key]: value }));
+				continue;
+			}
+			if (!("otherMetadata" in field)) fail(`Unsupported join tree field ${mgmt.meta.type}.${key}`);
+			const meta = field.otherMetadata();
+			const target = isTreeObject(value) && value.as !== void 0 ? value.as : newTableProxy(meta.cstr);
+			if (!isEntityTable(target) || getTableMgmt(target).meta !== meta) fail(`Join tree binding for ${mgmt.meta.type}.${key} must be a ${meta.type} table`);
+			const identity = getTableMgmt(target);
+			if (bound.has(identity)) fail(`Join tree table ${meta.type} is bound more than once; create a separate table handle`);
+			bound.add(identity);
+			const relation = source[key];
+			joins.push(relation.as(target));
+			if (isTreeObject(value) && !Object.hasOwn(value, "ne")) visitTree(target, value, joins, conditions, bound);
+			else conditions.push(tableEntityWhere(identity, value));
+		} else conditions.push(tableWhere(mgmt, { [key]: value }));
+	}
+}
+/** Separates nested relationship objects from entity, ID, and list filters. */
+function isTreeObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && !isEntity(value);
+}
+//#endregion
+export { compileJoinTree };
+
+//# sourceMappingURL=JoinTree.js.map

package/build/queries/sql/JoinTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinTree.js","names":[],"sources":["../../../src/queries/sql/JoinTree.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport type { IdOf } from \"src/EntityManager.ts\";\nimport type { InnerJoin, LeftJoin } from \"src/queries/sql/Expr.ts\";\nimport type { QueryCondition, QueryJoin, QueryJoinInput } from \"src/queries/sql/query.ts\";\nimport {\n  type CollectionJoin,\n  type TableFilter,\n  type TableFor,\n  getTableMgmt,\n  isEntityTable,\n  newTableProxy,\n  tableEntityWhere,\n  tableWhere,\n} from \"src/queries/sql/Tables.ts\";\nimport type { FieldsOf } from \"src/typeMap.ts\";\nimport { fail } from \"src/utils.ts\";\n\n/** Domain filters and optional table bindings for one node in a relationship tree. */\nexport type JoinTree<T extends Entity> = Omit<TableFilter<T>, RelationNames<T>> & {\n  readonly as?: TableFor<T>;\n} & {\n  readonly [K in RelationNames<T>]?: FieldsOf<T>[K] extends {\n    kind: \"m2o\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\";\n    type: infer U extends Entity;\n  }\n    ? JoinTree<U> | (K extends keyof TableFilter<T> ? TableFilter<T>[K] : JoinedEntityFilter<U>)\n    : never;\n};\n\n/**\n * Filters entities, e.g. `{ books: \"b:1\" }` filters Book.id to 1.\n *\n * Adapted from `em.find`s EntityFilter, rather than a direct copy:\n *\n * - Keeps entity/ID, list, boolean, and `ne` filters, but omits scopes, find aliases, nested objects, and logical groups.\n *   - JoinTree supplies nested objects and table bindings separately.\n * - Lists can mix entities and IDs, unlike EntityFilter's separate entity[] and ID[] alternatives.\n * - Null is always allowed because these relationships use LEFT joins.\n * - undefined comes from JoinTree's optional relationship keys.\n */\ntype JoinedEntityFilter<T extends Entity> =\n  | IdOf<T>\n  | T\n  | readonly (IdOf<T> | T)[]\n  | boolean\n  | null\n  | { ne: IdOf<T> | T | null | undefined };\n\ntype RelationNames<T extends Entity> = {\n  [K in keyof FieldsOf<T>]: FieldsOf<T>[K] extends { kind: \"m2o\" | \"poly\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\" }\n    ? K\n    : never;\n}[keyof FieldsOf<T>];\n\n/**\n * Validates a join tree against the entity in `from`, preserving its exact table bindings.\n *\n * I.e. given:\n *\n * ```ts\n * const [a, b] = tables(Author, Book);\n * em.query({\n *   from: a,\n *   join: { books: { as: b, title: \"One\" } },\n *   select: { title: b.title },\n * });\n * // F = typeof a\n * // J = { books: { as: typeof b; title: string } }\n * ```\n *\n * We:\n *\n * - Infer `T = Author` from `F`,\n * - Validate `books` against `Author`,\n * - Validate `title` against `Book`, and\n * - Retain `typeof b` for result typing.\n */\nexport type CheckJoinInput<F, J> =\n  // If J accepts the entire list-or-tree union, its annotation erased the join shape.\n  // Queries with no join infer [] and use the list branch below.\n  QueryJoinInput extends J\n    ? { join?: \"join was typed too generically; use `satisfies Query` instead of `: Query`\" }\n    : // If J is an array, then it's a QueryJoinList and we can return unknown\n      [J] extends [readonly unknown[]]\n      ? unknown\n      : F extends TableFor<infer T extends Entity>\n        ? // Validate domain filters and bindings, including extra keys on variables and nested trees.\n          { join?: JoinTree<T> & CheckTree<T, J> }\n        : // This incompatible type reports why a tree can't start at a non-entity source.\n          { join?: \"join trees require an entity table in from\" };\n\n/**\n * Determines which tables a join tree binds and whether each uses an INNER or LEFT join.\n *\n * Query result types use these entries to identify available tables and columns that can be null.\n *\n * I.e. Author.books.author uses LEFT joins for both Book and its Author because an Author may have no Books.\n */\nexport type TreeEntries<T extends Entity, J, Nullable extends boolean = false> =\n  // If every string is valid keyof J, then we've lost our literal type (i.e. as const) and were\n  // passed an opaque type like Record<string, unknown> that doesn't expose its specific relationship\n  // keys or table bindings to collect, so just return never.\n  string extends keyof J\n    ? never\n    : // If J has an `as` key, it might be the general JoinTree<T> type, which we check for in the next ternary.\n      // If J doesn't have `as`, it can't be the general `JoinTree<T>` so we can jump straight to TreeEntriesImpl.\n      \"as\" extends keyof J\n      ? // If `JoinTree<T> extends J`, then we again have a board type. CheckTree will reject this input, but\n        // here we stop instead of following every relationship in the domain graph.\n        JoinTree<T> extends J\n        ? never\n        : TreeEntriesImpl<T, J, Nullable>\n      : TreeEntriesImpl<T, J, Nullable>;\n\n/** Collects join entries from the relationship keys supplied in this tree node. */\ntype TreeEntriesImpl<T extends Entity, J, Nullable extends boolean> = {\n  [K in keyof J & keyof FieldsOf<T>]: FieldsOf<T>[K] extends {\n    kind: \"m2o\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\";\n    type: infer U extends Entity;\n  }\n    ? TreeNodeJoins<\n        U,\n        Exclude<J[K], undefined>,\n        Nullable extends true ? true : FieldsOf<T>[K] extends { kind: \"m2o\"; nullable: never } ? false : true\n      >\n    : never;\n}[keyof J & keyof FieldsOf<T>];\n\n/**\n * Collects the join entries for this node's table binding and its nested relationships.\n *\n * An `as` binding contributes a LeftJoin or InnerJoin according to Nullable.\n * Without a binding, only nested relationship entries are included; entity, ID, and list filters add none.\n */\ntype TreeNodeJoins<T extends Entity, J, Nullable extends boolean> =\n  // If `J extends Entity | unknown[]`, then it's a leaf entity/id filter, so stop recursing\n  J extends Entity | readonly unknown[]\n    ? never\n    : // If `J extends object`, look for an `as` binding and nested relationships.\n      // If `J extends object` is false, this is a scalar filter like \"b:1\" in `{ books: \"b:1\" }` and we stop here.\n      J extends object\n      ?\n          | (J extends { readonly as: infer A extends TableFor<T> }\n              ? Nullable extends true\n                ? LeftJoin<A>\n                : InnerJoin<A>\n              : never)\n          | TreeEntries<T, J, Nullable>\n      : never;\n\n/** Rejects broad tree annotations before checking their supplied keys and values. */\ntype CheckTree<T extends Entity, J> =\n  // An entity or a list of entities/IDs is a filter value, so don't check its properties as tree keys.\n  J extends Entity | readonly unknown[]\n    ? unknown\n    : \"as\" extends keyof J\n      ? JoinTree<T> extends J\n        ? \"join tree bindings were typed too generically; use `satisfies JoinTree<T>` instead of `: JoinTree<T>`\"\n        : CheckTreeKeys<T, J>\n      : CheckTreeKeys<T, J>;\n\n/** Rejects unknown tree keys, including extra properties on objects stored in variables. */\ntype CheckTreeKeys<T extends Entity, J> = [Exclude<keyof J, keyof JoinTree<T>>] extends [never]\n  ? {\n      [K in keyof J]: K extends \"as\"\n        ? J[K] extends TableFor<T> | undefined\n          ? unknown\n          : never\n        : K extends keyof JoinTree<T>\n          ? K extends keyof FieldsOf<T>\n            ? FieldsOf<T>[K] extends { kind: \"m2o\" | \"o2m\" | \"lo2m\" | \"m2m\" | \"o2o\"; type: infer U extends Entity }\n              ? (J[K] extends JoinTree<T>[K] ? unknown : never) & CheckRelationTree<U, J[K]>\n              : J[K] extends JoinTree<T>[K]\n                ? unknown\n                : never\n            : unknown\n          : never;\n      // Report the error on the tree object; intersecting a message with a boolean field would collapse to never.\n    }\n  : `unknown join tree field '${Exclude<keyof J, keyof JoinTree<T>> & string}'`;\n\n/** Checks each optional relationship alternative without treating entities or exclusion filters as trees. */\ntype CheckRelationTree<T extends Entity, J> = J extends object\n  ? \"ne\" extends keyof J\n    ? unknown\n    : CheckTree<T, J>\n  : unknown;\n\n/**\n * Walks domain relationship filters into ordinary SQL joins and WHERE predicates.\n * Handles remain query-local; no SQL aliases or caller objects are changed.\n * I.e. Author.books.author emits Book before its Author, even if only the final Author has an as binding.\n */\nexport function compileJoinTree(from: unknown, tree: unknown): { joins: QueryJoin[]; condition: QueryCondition } {\n  if (!isEntityTable(from)) fail(\"Join trees require an entity table in from\");\n  const joins: QueryJoin[] = [];\n  const conditions: QueryCondition[] = [];\n  const bound = new Set<object>([getTableMgmt(from)]);\n  visitTree(from, tree, joins, conditions, bound);\n  return { joins, condition: { and: conditions } };\n}\n\n/**\n * Compiles one node, leaving relationship conditions in WHERE rather than ON.\n * Each relationship gets one target handle; reusing a bound handle would merge distinct paths.\n * Owning-reference ID filters stay on the FK, while collection ID filters use the joined primary key.\n */\nfunction visitTree(\n  source: TableFor<Entity>,\n  tree: unknown,\n  joins: QueryJoin[],\n  conditions: QueryCondition[],\n  bound: Set<object>,\n): void {\n  if (!isTreeObject(tree)) fail(\"Expected a join tree object\");\n  const mgmt = getTableMgmt(source);\n  if (tree.as !== undefined && tree.as !== source) fail(\"Join tree root as must be the same table handle as from\");\n  for (const [key, value] of Object.entries(tree)) {\n    if (key === \"as\") continue;\n    const field = mgmt.meta.allFields[key] ?? fail(`Unknown join tree field ${mgmt.meta.type}.${key}`);\n    if (!(key in mgmt.meta.fields)) fail(`Join trees do not support inherited field ${mgmt.meta.type}.${key}`);\n    if (field.kind === \"poly\") fail(`Join trees do not support polymorphic field ${mgmt.meta.type}.${key}`);\n    if ([\"m2o\", \"o2m\", \"lo2m\", \"m2m\", \"o2o\"].includes(field.kind)) {\n      if (value === undefined) continue;\n      if (field.kind === \"m2o\" && !isTreeObject(value)) {\n        // Avoid joining the related table; add the condition directly to the FK column.\n        conditions.push(tableWhere(mgmt, { [key]: value }));\n        continue;\n      }\n      if (field.kind === \"m2o\" && isTreeObject(value) && Object.hasOwn(value, \"ne\")) {\n        // Exclusion filters also apply directly to the FK column without joining the related table.\n        conditions.push(tableWhere(mgmt, { [key]: value }));\n        continue;\n      }\n      // The field-kind check above establishes the relationship metadata and factory shape.\n      if (!(\"otherMetadata\" in field)) fail(`Unsupported join tree field ${mgmt.meta.type}.${key}`);\n      const meta = field.otherMetadata();\n      const target = isTreeObject(value) && value.as !== undefined ? value.as : newTableProxy(meta.cstr);\n      if (!isEntityTable(target) || getTableMgmt(target).meta !== meta) {\n        fail(`Join tree binding for ${mgmt.meta.type}.${key} must be a ${meta.type} table`);\n      }\n      const identity = getTableMgmt(target);\n      if (bound.has(identity))\n        fail(`Join tree table ${meta.type} is bound more than once; create a separate table handle`);\n      bound.add(identity);\n      const relation = (source as unknown as Record<string, CollectionJoin<Entity>>)[key];\n      joins.push(relation.as(target));\n      // Recurse into nested relationship filters, e.g. `{ books: { title: \"One\" } }`.\n      // A `{ ne: ... }` object instead filters the joined entity's ID, so handle it like an ID or entity value.\n      // We don't have to handle other keys like `gt`, etc. b/c we know this is an entity filter, not a value filter.\n      if (isTreeObject(value) && !Object.hasOwn(value, \"ne\")) {\n        visitTree(target, value, joins, conditions, bound);\n      } else {\n        conditions.push(tableEntityWhere(identity, value));\n      }\n    } else {\n      conditions.push(tableWhere(mgmt, { [key]: value }));\n    }\n  }\n}\n\n/** Separates nested relationship objects from entity, ID, and list filters. */\nfunction isTreeObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value) && !isEntity(value);\n}\n"],"mappings":";;;;;;;;;AAiMA,SAAgB,gBAAgB,MAAe,MAAkE;CAC/G,IAAI,CAAC,cAAc,IAAI,GAAG,KAAK,4CAA4C;CAC3E,MAAM,QAAqB,CAAC;CAC5B,MAAM,aAA+B,CAAC;CAEtC,UAAU,MAAM,MAAM,OAAO,4BAAY,IADvB,IAAY,CAAC,aAAa,IAAI,CAAC,CACJ,CAAC;CAC9C,OAAO;EAAE;EAAO,WAAW,EAAE,KAAK,WAAW;CAAE;AACjD;;;;;;AAOA,SAAS,UACP,QACA,MACA,OACA,YACA,OACM;CACN,IAAI,CAAC,aAAa,IAAI,GAAG,KAAK,6BAA6B;CAC3D,MAAM,OAAO,aAAa,MAAM;CAChC,IAAI,KAAK,OAAO,KAAA,KAAa,KAAK,OAAO,QAAQ,KAAK,yDAAyD;CAC/G,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,GAAG;EAC/C,IAAI,QAAQ,MAAM;EAClB,MAAM,QAAQ,KAAK,KAAK,UAAU,QAAQ,KAAK,2BAA2B,KAAK,KAAK,KAAK,GAAG,KAAK;EACjG,IAAI,EAAE,OAAO,KAAK,KAAK,SAAS,KAAK,6CAA6C,KAAK,KAAK,KAAK,GAAG,KAAK;EACzG,IAAI,MAAM,SAAS,QAAQ,KAAK,+CAA+C,KAAK,KAAK,KAAK,GAAG,KAAK;EACtG,IAAI;GAAC;GAAO;GAAO;GAAQ;GAAO;EAAK,CAAC,CAAC,SAAS,MAAM,IAAI,GAAG;GAC7D,IAAI,UAAU,KAAA,GAAW;GACzB,IAAI,MAAM,SAAS,SAAS,CAAC,aAAa,KAAK,GAAG;IAEhD,WAAW,KAAK,WAAW,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC;IAClD;GACF;GACA,IAAI,MAAM,SAAS,SAAS,aAAa,KAAK,KAAK,OAAO,OAAO,OAAO,IAAI,GAAG;IAE7E,WAAW,KAAK,WAAW,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC;IAClD;GACF;GAEA,IAAI,EAAE,mBAAmB,QAAQ,KAAK,+BAA+B,KAAK,KAAK,KAAK,GAAG,KAAK;GAC5F,MAAM,OAAO,MAAM,cAAc;GACjC,MAAM,SAAS,aAAa,KAAK,KAAK,MAAM,OAAO,KAAA,IAAY,MAAM,KAAK,cAAc,KAAK,IAAI;GACjG,IAAI,CAAC,cAAc,MAAM,KAAK,aAAa,MAAM,CAAC,CAAC,SAAS,MAC1D,KAAK,yBAAyB,KAAK,KAAK,KAAK,GAAG,IAAI,aAAa,KAAK,KAAK,OAAO;GAEpF,MAAM,WAAW,aAAa,MAAM;GACpC,IAAI,MAAM,IAAI,QAAQ,GACpB,KAAK,mBAAmB,KAAK,KAAK,yDAAyD;GAC7F,MAAM,IAAI,QAAQ;GAClB,MAAM,WAAY,OAA6D;GAC/E,MAAM,KAAK,SAAS,GAAG,MAAM,CAAC;GAI9B,IAAI,aAAa,KAAK,KAAK,CAAC,OAAO,OAAO,OAAO,IAAI,GACnD,UAAU,QAAQ,OAAO,OAAO,YAAY,KAAK;QAEjD,WAAW,KAAK,iBAAiB,UAAU,KAAK,CAAC;EAErD,OACE,WAAW,KAAK,WAAW,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC;CAEtD;AACF;;AAGA,SAAS,aAAa,OAAkD;CACtE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK,KAAK,CAAC,SAAS,KAAK;AAChG"}