joist-core 2.3.0 → 2.4.0

package/build/queries/find/Aliases.cjs

@@ -0,0 +1,301 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_keys = require("../../keys.cjs");
+const require_queries_skipCondition = require("../skipCondition.cjs");
+const require_queries_find_DeferredAlias = require("./DeferredAlias.cjs");
+const require_queries_valueFilters = require("../valueFilters.cjs");
+const require_utils = require("../../utils.cjs");
+const require_configure = require("../../configure.cjs");
+const require_EntityMetadata = require("../../EntityMetadata.cjs");
+let joist_utils = require("joist-utils");
+//#region src/queries/find/Aliases.ts
+/** Creates an alias for complex domain filtering in `em.find`. */
+function alias(cstr) {
+	return newAliasProxy(cstr);
+}
+/** Creates multiple aliases for complex filtering. */
+function aliases(...types) {
+	return types.map((t) => newAliasProxy(t));
+}
+const aliasMgmt = Symbol("aliasMgmt");
+/** Returns the runtime identity bound by the find parser. */
+function getAliasMgmt(alias) {
+	return alias[aliasMgmt];
+}
+/** Returns the original metadata, preserving STI subtype identity. */
+function getAliasMetadata(alias) {
+	return alias[aliasMgmt].meta;
+}
+/** Creates domain predicates lazily from entity field metadata. */
+function newAliasProxy(cstr) {
+	const meta = require_EntityMetadata.getMetadata(cstr);
+	const mgmt = {
+		tableName: meta.tableName,
+		meta,
+		condition(build) {
+			return require_queries_find_DeferredAlias.withDeferredAlias({
+				kind: "raw",
+				aliases: [],
+				condition: "unset",
+				bindings: [],
+				pruneable: false
+			}, (resolve, copy) => {
+				const bound = resolve(mgmt);
+				Object.assign(copy, build(bound.meta, bound.alias));
+			});
+		}
+	};
+	return new Proxy(cstr, {
+		get(_, key) {
+			if (key === aliasMgmt) return mgmt;
+			if (typeof key !== "string") return void 0;
+			const field = meta.allFields[key] ?? require_utils.fail(`No field ${key} on ${cstr.name}`);
+			if (field.kind === "poly") return new PolyReferenceAlias(meta, mgmt, field);
+			if ([
+				"primaryKey",
+				"primitive",
+				"enum",
+				"m2o"
+			].includes(field.kind)) return new AliasColumnImpl(meta, field, field.serde.columns[0], mgmt);
+			return require_utils.fail(`Unsupported alias field kind ${field.kind}`);
+		},
+		has(_, key) {
+			return key === aliasMgmt || key in meta.allFields;
+		}
+	});
+}
+/** Recognizes only domain aliases, not physical tables. */
+function isAlias(value) {
+	return typeof value === "function" && aliasMgmt in value;
+}
+/** Builds field conditions without implementing the SQL expression protocol. */
+var AliasColumnImpl = class AliasColumnImpl {
+	meta;
+	field;
+	column;
+	mgmt;
+	constructor(meta, field, column, mgmt) {
+		this.meta = meta;
+		this.field = field;
+		this.column = column;
+		this.mgmt = mgmt;
+	}
+	eq(value) {
+		return this.compare("eq", "=", value);
+	}
+	ne(value) {
+		return this.compare("ne", "!=", value);
+	}
+	gt(value) {
+		return this.compare("gt", ">", value);
+	}
+	gte(value) {
+		return this.compare("gte", ">=", value);
+	}
+	lt(value) {
+		return this.compare("lt", "<", value);
+	}
+	lte(value) {
+		return this.compare("lte", "<=", value);
+	}
+	contains(value) {
+		return this.compare("contains", "@>", value);
+	}
+	ncontains(value) {
+		if (value instanceof AliasColumnImpl) return crossColumnCondition(this, value, "@>", true);
+		return this.addCondition({
+			kind: "ncontains",
+			value
+		});
+	}
+	overlaps(value) {
+		return this.compare("overlaps", "&&", value);
+	}
+	noverlaps(value) {
+		if (value instanceof AliasColumnImpl) return crossColumnCondition(this, value, "&&", true);
+		return this.addCondition({
+			kind: "noverlaps",
+			value
+		});
+	}
+	in(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		if (values === null) return require_utils.fail("Unsupported");
+		if (values.includes(null)) return { or: [this.addCondition({ kind: "is-null" }), this.addCondition({
+			kind: "in",
+			value: values.filter((v) => v !== null)
+		})] };
+		return this.addCondition({
+			kind: "in",
+			value: [...values]
+		});
+	}
+	nin(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		if (values === null) return require_utils.fail("Unsupported");
+		return this.addCondition({
+			kind: "nin",
+			value: values.filter((v) => v !== null)
+		});
+	}
+	between(v1, v2) {
+		if (v1 === void 0 || v2 === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addCondition({
+			kind: "between",
+			value: [v1, v2]
+		});
+	}
+	like(value) {
+		return this.addCondition({
+			kind: "like",
+			value
+		});
+	}
+	ilike(value) {
+		return this.addCondition({
+			kind: "ilike",
+			value
+		});
+	}
+	search(value) {
+		return !value ? require_queries_skipCondition.skipCondition : this.addCondition({
+			kind: "ilike",
+			value: require_queries_valueFilters.makeLike(value)
+		});
+	}
+	pathExists(value) {
+		return this.addCondition({
+			kind: "jsonPathExists",
+			value
+		});
+	}
+	pathIsTrue(value) {
+		return this.addCondition({
+			kind: "jsonPathPredicate",
+			value
+		});
+	}
+	raw(exp, bindings) {
+		if (bindings === void 0) return require_queries_skipCondition.skipCondition;
+		return require_queries_find_DeferredAlias.withDeferredAlias({
+			kind: "raw",
+			aliases: [],
+			condition: "unset",
+			pruneable: false,
+			bindings
+		}, (resolve, copy) => {
+			const r = resolve(this.mgmt);
+			const alias = getMaybeCtiAlias(this.meta, this.field, r.meta, r.alias);
+			copy.aliases = [alias];
+			copy.condition = `${alias}.${this.column.columnName} ${exp}`;
+		});
+	}
+	/** Maps literal values through the field serde and binds aliases only when parsing. */
+	addCondition(value) {
+		if ("value" in value && value.value === void 0) return require_queries_skipCondition.skipCondition;
+		const cond = {
+			kind: "column",
+			alias: "unset",
+			column: this.column.columnName,
+			dbType: this.column.dbType,
+			cond: require_queries_valueFilters.mapToDb(this.column, value)
+		};
+		return require_queries_find_DeferredAlias.withDeferredAlias(cond, (resolve, copy) => {
+			const r = resolve(this.mgmt);
+			copy.alias = getMaybeCtiAlias(this.meta, this.field, r.meta, r.alias);
+		});
+	}
+	/** Handles literal values, NULL, and domain cross-alias comparisons. */
+	compare(kind, op, value) {
+		if (value === void 0) return require_queries_skipCondition.skipCondition;
+		if (value instanceof AliasColumnImpl) return crossColumnCondition(this, value, op);
+		if (value === null && (kind === "eq" || kind === "ne")) return this.addCondition({ kind: kind === "eq" ? "is-null" : "not-null" });
+		if (value === null && [
+			"gt",
+			"gte",
+			"lt",
+			"lte"
+		].includes(kind)) return require_utils.fail("Unsupported");
+		return this.addCondition({
+			kind,
+			value
+		});
+	}
+};
+/** Resolves polymorphic predicates to their physical component columns. */
+var PolyReferenceAlias = class {
+	meta;
+	mgmt;
+	field;
+	constructor(meta, mgmt, field) {
+		this.meta = meta;
+		this.mgmt = mgmt;
+		this.field = field;
+	}
+	eq(value) {
+		return this.addEqOrNe("eq", value);
+	}
+	ne(value) {
+		return this.addEqOrNe("ne", value);
+	}
+	in(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		const groups = (0, joist_utils.groupBy)(values, (id) => require_configure.getConstructorFromTaggedId(require_keys.maybeResolveReferenceToId(id)).name);
+		return { or: Object.entries(groups).map(([name, ids]) => {
+			const comp = this.field.components.find((c) => c.otherMetadata().cstr.name === name) ?? require_utils.fail(`No component for ${name}`);
+			return this.component(comp).addCondition({
+				kind: "in",
+				value: ids
+			});
+		}) };
+	}
+	/** Picks the component from an entity, tagged id, or another domain alias column. */
+	addEqOrNe(kind, value) {
+		if (value === void 0) return require_queries_skipCondition.skipCondition;
+		if (value === null) return { and: this.field.components.map((c) => this.component(c).addCondition({ kind: kind === "eq" ? "is-null" : "not-null" })) };
+		const otherMeta = value instanceof AliasColumnImpl ? value.field.kind === "m2o" ? value.field.otherMetadata() : value.meta : require_EntityMetadata.getMetadata(require_configure.getConstructorFromTaggedId(require_keys.maybeResolveReferenceToId(value)));
+		const comp = this.field.components.find((c) => require_EntityMetadata.getBaseAndSelfMetas(otherMeta).includes(c.otherMetadata())) ?? require_utils.fail(`${this.field.fieldName} has no component for ${otherMeta.type}`);
+		const column = this.component(comp);
+		return kind === "eq" ? column.eq(value) : column.ne(value);
+	}
+	/** Uses the component serde, not the first component's codec. */
+	component(comp) {
+		const column = this.field.serde.columns.find((c) => c.columnName === comp.columnName) ?? require_utils.fail("Missing column");
+		return new AliasColumnImpl(this.meta, this.field, column, this.mgmt);
+	}
+};
+/** Adjusts a field's SQL alias when a base alias is bound to a CTI subtype in the join tree. */
+function getMaybeCtiAlias(meta, field, newMeta, newAlias) {
+	if (newMeta !== meta && newMeta.inheritanceType === "cti") {
+		if (require_EntityMetadata.getBaseAndSelfMetas(newMeta).includes(newMeta)) return `${newAlias}_b0`;
+	}
+	return `${newAlias}${field.aliasSuffix}`;
+}
+/** Compares domain columns with per-parse aliases, preserving condition reuse across find calls. */
+function crossColumnCondition(left, right, op, negate = false) {
+	return require_queries_find_DeferredAlias.withDeferredAlias({
+		kind: "raw",
+		aliases: [],
+		condition: "unset",
+		bindings: [],
+		pruneable: false
+	}, (resolve, copy) => {
+		const l = resolve(left.mgmt);
+		const r = resolve(right.mgmt);
+		const a1 = getMaybeCtiAlias(left.meta, left.field, l.meta, l.alias);
+		const a2 = getMaybeCtiAlias(right.meta, right.field, r.meta, r.alias);
+		copy.aliases = [a1, a2];
+		const sql = `${a1}.${left.column.columnName} ${op} ${a2}.${right.column.columnName}`;
+		copy.condition = negate ? `NOT (${sql})` : sql;
+	});
+}
+//#endregion
+exports.alias = alias;
+exports.aliasMgmt = aliasMgmt;
+exports.aliases = aliases;
+exports.getAliasMetadata = getAliasMetadata;
+exports.getAliasMgmt = getAliasMgmt;
+exports.getMaybeCtiAlias = getMaybeCtiAlias;
+exports.isAlias = isAlias;
+exports.newAliasProxy = newAliasProxy;
+
+//# sourceMappingURL=Aliases.cjs.map

package/build/queries/find/Aliases.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aliases.cjs","names":["getMetadata","withDeferredAlias","fail","skipCondition","makeLike","mapToDb","groupBy","getConstructorFromTaggedId","maybeResolveReferenceToId","getBaseAndSelfMetas"],"sources":["../../../src/queries/find/Aliases.ts"],"sourcesContent":["import { groupBy } from \"joist-utils\";\n// Load configure first: relations must not evaluate before their base classes exist.\nimport { getConstructorFromTaggedId } from \"src/configure.ts\";\nimport type { Entity } from \"src/Entity.ts\";\nimport type { IdOf, MaybeAbstractEntityConstructor, TaggedId } from \"src/EntityManager.ts\";\nimport {\n  type EntityMetadata,\n  type Field,\n  type PolymorphicField,\n  type PolymorphicFieldComponent,\n  getBaseAndSelfMetas,\n  getMetadata,\n} from \"src/EntityMetadata.ts\";\nimport { maybeResolveReferenceToId } from \"src/keys.ts\";\nimport type { PredicateBrand } from \"src/queries/conditions.ts\";\nimport { withDeferredAlias } from \"src/queries/find/DeferredAlias.ts\";\nimport type { ExpressionCondition } from \"src/queries/find/EntityFilter.ts\";\nimport type { ColumnCondition, ParsedValueFilter, RawCondition } from \"src/queries/parsedConditions.ts\";\nimport { skipCondition } from \"src/queries/skipCondition.ts\";\nimport { makeLike, mapToDb } from \"src/queries/valueFilters.ts\";\nimport type { Column } from \"src/serde/columns.ts\";\nimport type { FieldsOf } from \"src/typeMap.ts\";\nimport { fail } from \"src/utils.ts\";\n\n/** Creates an alias for complex domain filtering in `em.find`. */\nexport function alias<T extends Entity>(cstr: MaybeAbstractEntityConstructor<T>): Alias<T> {\n  return newAliasProxy(cstr);\n}\n\n/** Creates multiple aliases for complex filtering. */\nexport function aliases<T extends readonly MaybeAbstractEntityConstructor<any>[]>(\n  ...types: T\n): { [P in keyof T]: T[P] extends MaybeAbstractEntityConstructor<infer E extends Entity> ? Alias<E> : never } {\n  return types.map((t) => newAliasProxy(t)) as any;\n}\n\nexport const aliasMgmt = Symbol(\"aliasMgmt\");\nconst aliasColumn = Symbol(\"aliasColumn\");\n\n/** The identity and original entity metadata of an `em.find` alias. */\nexport interface AliasMgmt {\n  tableName: string;\n  meta: EntityMetadata;\n  /**\n   * Builds a raw condition using each query's bound metadata and SQL alias, before join pruning.\n   * Return a fresh condition instead of mutating shared state; the callback runs only when used.\n   */\n  condition(build: (meta: EntityMetadata, alias: string) => RawCondition): RawCondition & PredicateBrand<\"domain\">;\n}\n\n/** Keeps domain aliases covariant in their entity type. */\nexport interface AliasBrand<T> extends AliasMgmt {\n  readonly __entity: T;\n}\n\n/**\n * Domain field predicates, deliberately separate from SQL table expressions.\n *\n * An Alias names a place in an em.find relationship tree, not a fixed SQL table occurrence.\n * I.e. with `a = alias(Author)`, `{ author: { as: a } }` binds `a` to the Book's Author;\n * binding it under `{ author: { mentor: { as: a } } }` instead makes it the Author's mentor.\n * The find parser builds those joins and knows which entity metadata and SQL name apply there,\n * including any inheritance joins. The Alias cannot know that when `a.firstName.eq(name)` is created.\n *\n * DeferredAlias therefore resolves each predicate to a fresh column/raw condition using that parse's\n * binding. The resolved condition records the SQL aliases it reads, including both sides of a\n * cross-alias comparison. Join pruning uses those references to retain the joins the filter needs.\n * An undefined predicate is skipped, so it does not keep an otherwise-unused join alive; explicit\n * keepAliases and other query dependencies can still retain that join.\n *\n * Table expressions solve a different problem: their sources are supplied directly in from/join,\n * so they render through ExprContext rather than asking the find parser to bind a relationship path.\n * Neither path stores a resolved SQL name on the reusable handle or predicate.\n */\nexport type Alias<T extends Entity> = { readonly [aliasMgmt]: AliasBrand<T> } & {\n  [P in keyof FieldsOf<T>]: P extends \"id\"\n    ? EntityAlias<T>\n    : FieldsOf<T>[P] extends { kind: \"primitive\" | \"enum\"; type: infer V; nullable: infer N }\n      ? PrimitiveAlias<V, N extends undefined ? null : never>\n      : FieldsOf<T>[P] extends { kind: \"m2o\"; type: infer U extends Entity; nullable: infer N }\n        ? EntityAlias<U, N extends undefined ? null : never>\n        : FieldsOf<T>[P] extends { kind: \"poly\"; type: infer U extends Entity }\n          ? PolyAlias<U>\n          : never;\n};\n\n/** A domain column accepted on the other side of a cross-alias comparison. */\nexport interface AliasColumn<V> {\n  readonly [aliasColumn]: V;\n}\n\nexport interface PrimitiveAlias<V, N extends null | never = never> extends AliasColumn<V | N> {\n  eq(value: V | N | AliasColumn<V | null> | undefined): ExpressionCondition;\n  ne(value: V | N | AliasColumn<V | null> | undefined): ExpressionCondition;\n  in(values: readonly (V | null)[] | undefined): ExpressionCondition;\n  nin(values: readonly (V | null)[] | undefined): ExpressionCondition;\n  gt(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;\n  gte(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;\n  lt(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;\n  lte(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;\n  like(value: V | undefined): ExpressionCondition;\n  ilike(value: V | undefined): ExpressionCondition;\n  search(value: V | undefined): ExpressionCondition;\n  between(v1: V | undefined, v2: V | undefined): ExpressionCondition;\n  // V is already an array; strings also support jsonb contains.\n  contains(value: string | V | AliasColumn<V | null> | N | undefined): ExpressionCondition;\n  ncontains(value: string | V | AliasColumn<V | null> | N | undefined): ExpressionCondition;\n  overlaps(value: V | AliasColumn<V | null> | N | undefined): ExpressionCondition;\n  noverlaps(value: V | AliasColumn<V | null> | N | undefined): ExpressionCondition;\n  /** Adds a parameterized JSON path existence condition using `@?`. */\n  pathExists(jsonPath: string | undefined): ExpressionCondition;\n  /** Adds a parameterized JSON path predicate condition using `@@`. */\n  pathIsTrue(jsonPath: string | undefined): ExpressionCondition;\n  /** Adds an operator and expression with knex-style placeholders, without the column name. */\n  raw(exp: string, bindings: readonly unknown[] | undefined): ExpressionCondition;\n}\n\nexport interface EntityAlias<T, N extends null | never = never> extends AliasColumn<IdOf<T> | N> {\n  eq(value: T | IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  ne(value: T | IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  // Adding `| null` for GraphQL support\n  in(values: readonly (T | IdOf<T> | null)[] | null | undefined): ExpressionCondition;\n  nin(values: readonly (T | IdOf<T> | null)[] | null | undefined): ExpressionCondition;\n  gt(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  gte(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  lt(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  lte(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  raw(exp: string, bindings: readonly unknown[] | undefined): ExpressionCondition;\n}\n\nexport interface PolyAlias<T extends Entity> {\n  eq(value: T | TaggedId | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  ne(value: T | TaggedId | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;\n  in(values: readonly (T | TaggedId)[] | undefined): ExpressionCondition;\n}\n\n/** Returns the runtime identity bound by the find parser. */\nexport function getAliasMgmt(alias: { readonly [aliasMgmt]: AliasMgmt }): AliasMgmt {\n  return alias[aliasMgmt];\n}\n\n/** Returns the original metadata, preserving STI subtype identity. */\nexport function getAliasMetadata<T extends Entity>(alias: Alias<T>): EntityMetadata<T> {\n  return alias[aliasMgmt].meta as EntityMetadata<T>;\n}\n\n/** Creates domain predicates lazily from entity field metadata. */\nexport function newAliasProxy<T extends Entity>(cstr: MaybeAbstractEntityConstructor<T>): Alias<T> {\n  const meta = getMetadata(cstr);\n  const mgmt: AliasMgmt = {\n    tableName: meta.tableName,\n    meta,\n    condition(build) {\n      const cond: RawCondition = { kind: \"raw\", aliases: [], condition: \"unset\", bindings: [], pruneable: false };\n      return withDeferredAlias(cond, (resolve, copy) => {\n        const bound = resolve(mgmt);\n        Object.assign(copy, build(bound.meta, bound.alias));\n      });\n    },\n  };\n  return new Proxy(cstr, {\n    get(_, key) {\n      if (key === aliasMgmt) return mgmt;\n      if (typeof key !== \"string\") return undefined;\n      const field = meta.allFields[key] ?? fail(`No field ${key} on ${cstr.name}`);\n      if (field.kind === \"poly\") return new PolyReferenceAlias(meta, mgmt, field);\n      if ([\"primaryKey\", \"primitive\", \"enum\", \"m2o\"].includes(field.kind)) {\n        return new AliasColumnImpl(meta, field, field.serde!.columns[0], mgmt);\n      }\n      return fail(`Unsupported alias field kind ${field.kind}`);\n    },\n    has(_, key) {\n      return key === aliasMgmt || key in meta.allFields;\n    },\n  }) as unknown as Alias<T>;\n}\n\n/** Recognizes only domain aliases, not physical tables. */\nexport function isAlias(value: unknown): value is Alias<Entity> {\n  return typeof value === \"function\" && aliasMgmt in value;\n}\n\n/** Builds field conditions without implementing the SQL expression protocol. */\nclass AliasColumnImpl {\n  declare readonly [aliasColumn]: unknown;\n\n  constructor(\n    readonly meta: EntityMetadata,\n    readonly field: Field & { aliasSuffix: string },\n    readonly column: Column,\n    readonly mgmt: AliasMgmt,\n  ) {}\n\n  eq(value: unknown): ExpressionCondition {\n    return this.compare(\"eq\", \"=\", value);\n  }\n  ne(value: unknown): ExpressionCondition {\n    return this.compare(\"ne\", \"!=\", value);\n  }\n  gt(value: unknown): ExpressionCondition {\n    return this.compare(\"gt\", \">\", value);\n  }\n  gte(value: unknown): ExpressionCondition {\n    return this.compare(\"gte\", \">=\", value);\n  }\n  lt(value: unknown): ExpressionCondition {\n    return this.compare(\"lt\", \"<\", value);\n  }\n  lte(value: unknown): ExpressionCondition {\n    return this.compare(\"lte\", \"<=\", value);\n  }\n  contains(value: unknown): ExpressionCondition {\n    return this.compare(\"contains\", \"@>\", value);\n  }\n  ncontains(value: unknown): ExpressionCondition {\n    if (value instanceof AliasColumnImpl) return crossColumnCondition(this, value, \"@>\", true);\n    return this.addCondition({ kind: \"ncontains\", value: value as readonly unknown[] });\n  }\n  overlaps(value: unknown): ExpressionCondition {\n    return this.compare(\"overlaps\", \"&&\", value);\n  }\n  noverlaps(value: unknown): ExpressionCondition {\n    if (value instanceof AliasColumnImpl) return crossColumnCondition(this, value, \"&&\", true);\n    return this.addCondition({ kind: \"noverlaps\", value: value as readonly unknown[] });\n  }\n\n  in(values: readonly unknown[] | null | undefined): ExpressionCondition {\n    if (values === undefined) return skipCondition;\n    if (values === null) return fail(\"Unsupported\");\n    if (values.includes(null)) {\n      return {\n        or: [\n          this.addCondition({ kind: \"is-null\" }),\n          this.addCondition({ kind: \"in\", value: values.filter((v) => v !== null) }),\n        ],\n      };\n    }\n    return this.addCondition({ kind: \"in\", value: [...values] });\n  }\n\n  nin(values: readonly unknown[] | null | undefined): ExpressionCondition {\n    if (values === undefined) return skipCondition;\n    if (values === null) return fail(\"Unsupported\");\n    return this.addCondition({ kind: \"nin\", value: values.filter((v) => v !== null) });\n  }\n\n  between(v1: unknown, v2: unknown): ExpressionCondition {\n    if (v1 === undefined || v2 === undefined) return skipCondition;\n    return this.addCondition({ kind: \"between\", value: [v1, v2] });\n  }\n\n  like(value: unknown): ExpressionCondition {\n    return this.addCondition({ kind: \"like\", value });\n  }\n  ilike(value: unknown): ExpressionCondition {\n    return this.addCondition({ kind: \"ilike\", value });\n  }\n  search(value: unknown): ExpressionCondition {\n    // Check !value so that empty strings are pruned\n    return !value ? skipCondition : this.addCondition({ kind: \"ilike\", value: makeLike(value) });\n  }\n  pathExists(value: string | undefined): ExpressionCondition {\n    return this.addCondition({ kind: \"jsonPathExists\", value: value! });\n  }\n  pathIsTrue(value: string | undefined): ExpressionCondition {\n    return this.addCondition({ kind: \"jsonPathPredicate\", value: value! });\n  }\n\n  raw(exp: string, bindings: readonly unknown[] | undefined): ExpressionCondition {\n    if (bindings === undefined) return skipCondition;\n    const cond: RawCondition = { kind: \"raw\", aliases: [], condition: \"unset\", pruneable: false, bindings };\n    return withDeferredAlias(cond, (resolve, copy) => {\n      const r = resolve(this.mgmt);\n      const alias = getMaybeCtiAlias(this.meta, this.field, r.meta, r.alias);\n      copy.aliases = [alias];\n      copy.condition = `${alias}.${this.column.columnName} ${exp}`;\n    });\n  }\n\n  /** Maps literal values through the field serde and binds aliases only when parsing. */\n  addCondition(value: ParsedValueFilter<unknown>): ExpressionCondition {\n    if (\"value\" in value && value.value === undefined) return skipCondition;\n    const cond: ColumnCondition = {\n      kind: \"column\",\n      alias: \"unset\",\n      column: this.column.columnName,\n      dbType: this.column.dbType,\n      cond: mapToDb(this.column, value),\n    };\n    return withDeferredAlias(cond, (resolve, copy) => {\n      const r = resolve(this.mgmt);\n      copy.alias = getMaybeCtiAlias(this.meta, this.field, r.meta, r.alias);\n    });\n  }\n\n  /** Handles literal values, NULL, and domain cross-alias comparisons. */\n  private compare(\n    kind: \"eq\" | \"ne\" | \"gt\" | \"gte\" | \"lt\" | \"lte\" | \"contains\" | \"ncontains\" | \"overlaps\",\n    op: string,\n    value: unknown,\n  ): ExpressionCondition {\n    if (value === undefined) return skipCondition;\n    if (value instanceof AliasColumnImpl) return crossColumnCondition(this, value, op);\n    if (value === null && (kind === \"eq\" || kind === \"ne\"))\n      return this.addCondition({ kind: kind === \"eq\" ? \"is-null\" : \"not-null\" });\n    if (value === null && [\"gt\", \"gte\", \"lt\", \"lte\"].includes(kind)) return fail(\"Unsupported\");\n    return this.addCondition({ kind, value } as ParsedValueFilter<unknown>);\n  }\n}\n\n/** Resolves polymorphic predicates to their physical component columns. */\nclass PolyReferenceAlias {\n  constructor(\n    private meta: EntityMetadata,\n    private mgmt: AliasMgmt,\n    private field: PolymorphicField & { aliasSuffix: string },\n  ) {}\n\n  eq(value: unknown): ExpressionCondition {\n    return this.addEqOrNe(\"eq\", value);\n  }\n  ne(value: unknown): ExpressionCondition {\n    return this.addEqOrNe(\"ne\", value);\n  }\n\n  in(values: readonly (Entity | TaggedId)[] | undefined): ExpressionCondition {\n    if (values === undefined) return skipCondition;\n    // Split up the ids by constructor\n    const groups = groupBy(values, (id) => getConstructorFromTaggedId(maybeResolveReferenceToId(id)!).name);\n    // Or together `parent_book_id in (1,2,3) OR parent_author_id IN (4,5,6)`\n    return {\n      or: Object.entries(groups).map(([name, ids]) => {\n        const comp =\n          this.field.components.find((c) => c.otherMetadata().cstr.name === name) ?? fail(`No component for ${name}`);\n        return this.component(comp).addCondition({ kind: \"in\", value: ids });\n      }),\n    };\n  }\n\n  /** Picks the component from an entity, tagged id, or another domain alias column. */\n  private addEqOrNe(kind: \"eq\" | \"ne\", value: unknown): ExpressionCondition {\n    if (value === undefined) return skipCondition;\n    if (value === null) {\n      // We can AND each of the components as many conditions\n      return {\n        and: this.field.components.map((c) =>\n          this.component(c).addCondition({ kind: kind === \"eq\" ? \"is-null\" : \"not-null\" }),\n        ),\n      };\n    }\n    const otherMeta =\n      value instanceof AliasColumnImpl\n        ? value.field.kind === \"m2o\"\n          ? value.field.otherMetadata()\n          : value.meta\n        : getMetadata(getConstructorFromTaggedId(maybeResolveReferenceToId(value as Entity | TaggedId)!));\n    const comp =\n      this.field.components.find((c) => getBaseAndSelfMetas(otherMeta).includes(c.otherMetadata())) ??\n      fail(`${this.field.fieldName} has no component for ${otherMeta.type}`);\n    const column = this.component(comp);\n    return kind === \"eq\" ? column.eq(value) : column.ne(value);\n  }\n\n  /** Uses the component serde, not the first component's codec. */\n  private component(comp: PolymorphicFieldComponent): AliasColumnImpl {\n    const column = this.field.serde.columns.find((c) => c.columnName === comp.columnName) ?? fail(\"Missing column\");\n    return new AliasColumnImpl(this.meta, this.field, column, this.mgmt);\n  }\n}\n\n/** Adjusts a field's SQL alias when a base alias is bound to a CTI subtype in the join tree. */\nexport function getMaybeCtiAlias(\n  meta: EntityMetadata,\n  field: Field & { aliasSuffix: string },\n  newMeta: EntityMetadata,\n  newAlias: string,\n): string {\n  // Do we have mismatched `em.find(ChildMeta)` with a `alias(BaseMeta)`? If so, the\n  // usual `${field.aliasSuffix}` won't know it should have a suffix, so we need to calc it.\n  if (newMeta !== meta && newMeta.inheritanceType === \"cti\") {\n    const bases = getBaseAndSelfMetas(newMeta);\n    const fieldIsFromBase = bases.includes(newMeta);\n    if (fieldIsFromBase) return `${newAlias}_b0`;\n  }\n  return `${newAlias}${field.aliasSuffix}`;\n}\n\n/** Compares domain columns with per-parse aliases, preserving condition reuse across find calls. */\nfunction crossColumnCondition(\n  left: AliasColumnImpl,\n  right: AliasColumnImpl,\n  op: string,\n  negate = false,\n): RawCondition & PredicateBrand<\"domain\"> {\n  const cond: RawCondition = { kind: \"raw\", aliases: [], condition: \"unset\", bindings: [], pruneable: false };\n  return withDeferredAlias(cond, (resolve, copy) => {\n    const l = resolve(left.mgmt);\n    const r = resolve(right.mgmt);\n    const a1 = getMaybeCtiAlias(left.meta, left.field, l.meta, l.alias);\n    const a2 = getMaybeCtiAlias(right.meta, right.field, r.meta, r.alias);\n    copy.aliases = [a1, a2];\n    const sql = `${a1}.${left.column.columnName} ${op} ${a2}.${right.column.columnName}`;\n    copy.condition = negate ? `NOT (${sql})` : sql;\n  });\n}\n"],"mappings":"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"}

package/build/queries/find/Aliases.d.cts

@@ -0,0 +1,122 @@
+import { FieldsOf } from "../../typeMap.cjs";
+import { RawCondition } from "../parsedConditions.cjs";
+import { PredicateBrand } from "../conditions.cjs";
+import { ExpressionCondition } from "./EntityFilter.cjs";
+import { EntityMetadata, Field } from "../../EntityMetadata.cjs";
+import { IdOf, MaybeAbstractEntityConstructor, TaggedId } from "../../EntityManager.cjs";
+import { Entity } from "../../Entity.cjs";
+//#region src/queries/find/Aliases.d.ts
+/** Creates an alias for complex domain filtering in `em.find`. */
+declare function alias<T extends Entity>(cstr: MaybeAbstractEntityConstructor<T>): Alias<T>;
+/** Creates multiple aliases for complex filtering. */
+declare function aliases<T extends readonly MaybeAbstractEntityConstructor<any>[]>(...types: T): { [P in keyof T]: T[P] extends MaybeAbstractEntityConstructor<infer E extends Entity> ? Alias<E> : never; };
+declare const aliasMgmt: unique symbol;
+declare const aliasColumn: unique symbol;
+/** The identity and original entity metadata of an `em.find` alias. */
+interface AliasMgmt {
+  tableName: string;
+  meta: EntityMetadata;
+  /**
+   * Builds a raw condition using each query's bound metadata and SQL alias, before join pruning.
+   * Return a fresh condition instead of mutating shared state; the callback runs only when used.
+   */
+  condition(build: (meta: EntityMetadata, alias: string) => RawCondition): RawCondition & PredicateBrand<"domain">;
+}
+/** Keeps domain aliases covariant in their entity type. */
+interface AliasBrand<T> extends AliasMgmt {
+  readonly __entity: T;
+}
+/**
+ * Domain field predicates, deliberately separate from SQL table expressions.
+ *
+ * An Alias names a place in an em.find relationship tree, not a fixed SQL table occurrence.
+ * I.e. with `a = alias(Author)`, `{ author: { as: a } }` binds `a` to the Book's Author;
+ * binding it under `{ author: { mentor: { as: a } } }` instead makes it the Author's mentor.
+ * The find parser builds those joins and knows which entity metadata and SQL name apply there,
+ * including any inheritance joins. The Alias cannot know that when `a.firstName.eq(name)` is created.
+ *
+ * DeferredAlias therefore resolves each predicate to a fresh column/raw condition using that parse's
+ * binding. The resolved condition records the SQL aliases it reads, including both sides of a
+ * cross-alias comparison. Join pruning uses those references to retain the joins the filter needs.
+ * An undefined predicate is skipped, so it does not keep an otherwise-unused join alive; explicit
+ * keepAliases and other query dependencies can still retain that join.
+ *
+ * Table expressions solve a different problem: their sources are supplied directly in from/join,
+ * so they render through ExprContext rather than asking the find parser to bind a relationship path.
+ * Neither path stores a resolved SQL name on the reusable handle or predicate.
+ */
+type Alias<T extends Entity> = {
+  readonly [aliasMgmt]: AliasBrand<T>;
+} & { [P in keyof FieldsOf<T>]: P extends "id" ? EntityAlias<T> : FieldsOf<T>[P] extends {
+  kind: "primitive" | "enum";
+  type: infer V;
+  nullable: infer N;
+} ? PrimitiveAlias<V, N extends undefined ? null : never> : FieldsOf<T>[P] extends {
+  kind: "m2o";
+  type: infer U extends Entity;
+  nullable: infer N;
+} ? EntityAlias<U, N extends undefined ? null : never> : FieldsOf<T>[P] extends {
+  kind: "poly";
+  type: infer U extends Entity;
+} ? PolyAlias<U> : never; };
+/** A domain column accepted on the other side of a cross-alias comparison. */
+interface AliasColumn<V> {
+  readonly [aliasColumn]: V;
+}
+interface PrimitiveAlias<V, N extends null | never = never> extends AliasColumn<V | N> {
+  eq(value: V | N | AliasColumn<V | null> | undefined): ExpressionCondition;
+  ne(value: V | N | AliasColumn<V | null> | undefined): ExpressionCondition;
+  in(values: readonly (V | null)[] | undefined): ExpressionCondition;
+  nin(values: readonly (V | null)[] | undefined): ExpressionCondition;
+  gt(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  gte(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  lt(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  lte(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  like(value: V | undefined): ExpressionCondition;
+  ilike(value: V | undefined): ExpressionCondition;
+  search(value: V | undefined): ExpressionCondition;
+  between(v1: V | undefined, v2: V | undefined): ExpressionCondition;
+  contains(value: string | V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  ncontains(value: string | V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  overlaps(value: V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  noverlaps(value: V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  /** Adds a parameterized JSON path existence condition using `@?`. */
+  pathExists(jsonPath: string | undefined): ExpressionCondition;
+  /** Adds a parameterized JSON path predicate condition using `@@`. */
+  pathIsTrue(jsonPath: string | undefined): ExpressionCondition;
+  /** Adds an operator and expression with knex-style placeholders, without the column name. */
+  raw(exp: string, bindings: readonly unknown[] | undefined): ExpressionCondition;
+}
+interface EntityAlias<T, N extends null | never = never> extends AliasColumn<IdOf<T> | N> {
+  eq(value: T | IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  ne(value: T | IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  in(values: readonly (T | IdOf<T> | null)[] | null | undefined): ExpressionCondition;
+  nin(values: readonly (T | IdOf<T> | null)[] | null | undefined): ExpressionCondition;
+  gt(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  gte(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  lt(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  lte(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  raw(exp: string, bindings: readonly unknown[] | undefined): ExpressionCondition;
+}
+interface PolyAlias<T extends Entity> {
+  eq(value: T | TaggedId | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  ne(value: T | TaggedId | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  in(values: readonly (T | TaggedId)[] | undefined): ExpressionCondition;
+}
+/** Returns the runtime identity bound by the find parser. */
+declare function getAliasMgmt(alias: {
+  readonly [aliasMgmt]: AliasMgmt;
+}): AliasMgmt;
+/** Returns the original metadata, preserving STI subtype identity. */
+declare function getAliasMetadata<T extends Entity>(alias: Alias<T>): EntityMetadata<T>;
+/** Creates domain predicates lazily from entity field metadata. */
+declare function newAliasProxy<T extends Entity>(cstr: MaybeAbstractEntityConstructor<T>): Alias<T>;
+/** Recognizes only domain aliases, not physical tables. */
+declare function isAlias(value: unknown): value is Alias<Entity>;
+/** Adjusts a field's SQL alias when a base alias is bound to a CTI subtype in the join tree. */
+declare function getMaybeCtiAlias(meta: EntityMetadata, field: Field & {
+  aliasSuffix: string;
+}, newMeta: EntityMetadata, newAlias: string): string;
+//#endregion
+export { Alias, AliasBrand, AliasColumn, AliasMgmt, EntityAlias, PolyAlias, PrimitiveAlias, alias, aliasMgmt, aliases, getAliasMetadata, getAliasMgmt, getMaybeCtiAlias, isAlias, newAliasProxy };
+//# sourceMappingURL=Aliases.d.cts.map

package/build/queries/find/Aliases.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aliases.d.cts","names":[],"sources":["../../../src/queries/find/Aliases.ts"],"mappings":";;;;;;;;;iBAyBgB,MAAM,UAAU,QAAQ,MAAM,+BAA+B,KAAK,MAAM;;iBAKxE,QAAQ,mBAAmB,0CACtC,OAAO,OACN,WAAW,IAAI,EAAE,WAAW,qCAAqC,UAAU,UAAU,MAAM;cAIpF;cACP;;UAGW;EACf;EACA,MAAM;;;;;EAKN,UAAU,QAAQ,MAAM,gBAAgB,kBAAkB,eAAe,eAAe;;;UAIzE,WAAW,WAAW;WAC5B,UAAU;;;;;;;;;;;;;;;;;;;;;KAsBT,MAAM,UAAU;YAAsB,YAAY,WAAW;OACtE,WAAW,SAAS,KAAK,iBACtB,YAAY,KACZ,SAAS,GAAG;EAAa;EAA4B,YAAY;EAAG,gBAAgB;IAClF,eAAe,GAAG,sCAClB,SAAS,GAAG;EAAa;EAAa,YAAY,UAAU;EAAQ,gBAAgB;IAClF,YAAY,GAAG,sCACf,SAAS,GAAG;EAAa;EAAc,YAAY,UAAU;IAC3D,UAAU;;UAKL,YAAY;YACjB,cAAc;;UAGT,eAAe,GAAG,wCAAwC,YAAY,IAAI;EACzF,GAAG,OAAO,IAAI,IAAI,YAAY,wBAAwB;EACtD,GAAG,OAAO,IAAI,IAAI,YAAY,wBAAwB;EACtD,GAAG,kBAAkB,0BAA0B;EAC/C,IAAI,kBAAkB,0BAA0B;EAChD,GAAG,OAAO,IAAI,YAAY,wBAAwB;EAClD,IAAI,OAAO,IAAI,YAAY,wBAAwB;EACnD,GAAG,OAAO,IAAI,YAAY,wBAAwB;EAClD,IAAI,OAAO,IAAI,YAAY,wBAAwB;EACnD,KAAK,OAAO,gBAAgB;EAC5B,MAAM,OAAO,gBAAgB;EAC7B,OAAO,OAAO,gBAAgB;EAC9B,QAAQ,IAAI,eAAe,IAAI,gBAAgB;EAE/C,SAAS,gBAAgB,IAAI,YAAY,YAAY,gBAAgB;EACrE,UAAU,gBAAgB,IAAI,YAAY,YAAY,gBAAgB;EACtE,SAAS,OAAO,IAAI,YAAY,YAAY,gBAAgB;EAC5D,UAAU,OAAO,IAAI,YAAY,YAAY,gBAAgB;;EAE7D,WAAW,+BAA+B;;EAE1C,WAAW,+BAA+B;;EAE1C,IAAI,aAAa,2CAA2C;;UAG7C,YAAY,GAAG,wCAAwC,YAAY,KAAK,KAAK;EAC5F,GAAG,OAAO,IAAI,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACzE,GAAG,OAAO,IAAI,KAAK,KAAK,YAAY,KAAK,gCAAgC;EAEzE,GAAG,kBAAkB,IAAI,KAAK,kCAAkC;EAChE,IAAI,kBAAkB,IAAI,KAAK,kCAAkC;EACjE,GAAG,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACrE,IAAI,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACtE,GAAG,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACrE,IAAI,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACtE,IAAI,aAAa,2CAA2C;;UAG7C,UAAU,UAAU;EACnC,GAAG,OAAO,IAAI,WAAW,YAAY,KAAK,gCAAgC;EAC1E,GAAG,OAAO,IAAI,WAAW,YAAY,KAAK,gCAAgC;EAC1E,GAAG,kBAAkB,IAAI,0BAA0B;;;iBAIrC,aAAa;YAAmB,YAAY;IAAc;;iBAK1D,iBAAiB,UAAU,QAAQ,OAAO,MAAM,KAAK,eAAe;;iBAKpE,cAAc,UAAU,QAAQ,MAAM,+BAA+B,KAAK,MAAM;;iBA+BhF,QAAQ,iBAAiB,SAAS,MAAM;;iBAiMxC,iBACd,MAAM,gBACN,OAAO;EAAU;GACjB,SAAS,gBACT"}

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

@@ -0,0 +1,122 @@
+import { FieldsOf } from "../../typeMap.mjs";
+import { RawCondition } from "../parsedConditions.mjs";
+import { PredicateBrand } from "../conditions.mjs";
+import { ExpressionCondition } from "./EntityFilter.mjs";
+import { EntityMetadata, Field } from "../../EntityMetadata.mjs";
+import { IdOf, MaybeAbstractEntityConstructor, TaggedId } from "../../EntityManager.mjs";
+import { Entity } from "../../Entity.mjs";
+//#region src/queries/find/Aliases.d.ts
+/** Creates an alias for complex domain filtering in `em.find`. */
+declare function alias<T extends Entity>(cstr: MaybeAbstractEntityConstructor<T>): Alias<T>;
+/** Creates multiple aliases for complex filtering. */
+declare function aliases<T extends readonly MaybeAbstractEntityConstructor<any>[]>(...types: T): { [P in keyof T]: T[P] extends MaybeAbstractEntityConstructor<infer E extends Entity> ? Alias<E> : never; };
+declare const aliasMgmt: unique symbol;
+declare const aliasColumn: unique symbol;
+/** The identity and original entity metadata of an `em.find` alias. */
+interface AliasMgmt {
+  tableName: string;
+  meta: EntityMetadata;
+  /**
+   * Builds a raw condition using each query's bound metadata and SQL alias, before join pruning.
+   * Return a fresh condition instead of mutating shared state; the callback runs only when used.
+   */
+  condition(build: (meta: EntityMetadata, alias: string) => RawCondition): RawCondition & PredicateBrand<"domain">;
+}
+/** Keeps domain aliases covariant in their entity type. */
+interface AliasBrand<T> extends AliasMgmt {
+  readonly __entity: T;
+}
+/**
+ * Domain field predicates, deliberately separate from SQL table expressions.
+ *
+ * An Alias names a place in an em.find relationship tree, not a fixed SQL table occurrence.
+ * I.e. with `a = alias(Author)`, `{ author: { as: a } }` binds `a` to the Book's Author;
+ * binding it under `{ author: { mentor: { as: a } } }` instead makes it the Author's mentor.
+ * The find parser builds those joins and knows which entity metadata and SQL name apply there,
+ * including any inheritance joins. The Alias cannot know that when `a.firstName.eq(name)` is created.
+ *
+ * DeferredAlias therefore resolves each predicate to a fresh column/raw condition using that parse's
+ * binding. The resolved condition records the SQL aliases it reads, including both sides of a
+ * cross-alias comparison. Join pruning uses those references to retain the joins the filter needs.
+ * An undefined predicate is skipped, so it does not keep an otherwise-unused join alive; explicit
+ * keepAliases and other query dependencies can still retain that join.
+ *
+ * Table expressions solve a different problem: their sources are supplied directly in from/join,
+ * so they render through ExprContext rather than asking the find parser to bind a relationship path.
+ * Neither path stores a resolved SQL name on the reusable handle or predicate.
+ */
+type Alias<T extends Entity> = {
+  readonly [aliasMgmt]: AliasBrand<T>;
+} & { [P in keyof FieldsOf<T>]: P extends "id" ? EntityAlias<T> : FieldsOf<T>[P] extends {
+  kind: "primitive" | "enum";
+  type: infer V;
+  nullable: infer N;
+} ? PrimitiveAlias<V, N extends undefined ? null : never> : FieldsOf<T>[P] extends {
+  kind: "m2o";
+  type: infer U extends Entity;
+  nullable: infer N;
+} ? EntityAlias<U, N extends undefined ? null : never> : FieldsOf<T>[P] extends {
+  kind: "poly";
+  type: infer U extends Entity;
+} ? PolyAlias<U> : never; };
+/** A domain column accepted on the other side of a cross-alias comparison. */
+interface AliasColumn<V> {
+  readonly [aliasColumn]: V;
+}
+interface PrimitiveAlias<V, N extends null | never = never> extends AliasColumn<V | N> {
+  eq(value: V | N | AliasColumn<V | null> | undefined): ExpressionCondition;
+  ne(value: V | N | AliasColumn<V | null> | undefined): ExpressionCondition;
+  in(values: readonly (V | null)[] | undefined): ExpressionCondition;
+  nin(values: readonly (V | null)[] | undefined): ExpressionCondition;
+  gt(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  gte(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  lt(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  lte(value: V | AliasColumn<V | null> | undefined): ExpressionCondition;
+  like(value: V | undefined): ExpressionCondition;
+  ilike(value: V | undefined): ExpressionCondition;
+  search(value: V | undefined): ExpressionCondition;
+  between(v1: V | undefined, v2: V | undefined): ExpressionCondition;
+  contains(value: string | V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  ncontains(value: string | V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  overlaps(value: V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  noverlaps(value: V | AliasColumn<V | null> | N | undefined): ExpressionCondition;
+  /** Adds a parameterized JSON path existence condition using `@?`. */
+  pathExists(jsonPath: string | undefined): ExpressionCondition;
+  /** Adds a parameterized JSON path predicate condition using `@@`. */
+  pathIsTrue(jsonPath: string | undefined): ExpressionCondition;
+  /** Adds an operator and expression with knex-style placeholders, without the column name. */
+  raw(exp: string, bindings: readonly unknown[] | undefined): ExpressionCondition;
+}
+interface EntityAlias<T, N extends null | never = never> extends AliasColumn<IdOf<T> | N> {
+  eq(value: T | IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  ne(value: T | IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  in(values: readonly (T | IdOf<T> | null)[] | null | undefined): ExpressionCondition;
+  nin(values: readonly (T | IdOf<T> | null)[] | null | undefined): ExpressionCondition;
+  gt(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  gte(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  lt(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  lte(value: IdOf<T> | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  raw(exp: string, bindings: readonly unknown[] | undefined): ExpressionCondition;
+}
+interface PolyAlias<T extends Entity> {
+  eq(value: T | TaggedId | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  ne(value: T | TaggedId | AliasColumn<IdOf<T> | null> | null | undefined): ExpressionCondition;
+  in(values: readonly (T | TaggedId)[] | undefined): ExpressionCondition;
+}
+/** Returns the runtime identity bound by the find parser. */
+declare function getAliasMgmt(alias: {
+  readonly [aliasMgmt]: AliasMgmt;
+}): AliasMgmt;
+/** Returns the original metadata, preserving STI subtype identity. */
+declare function getAliasMetadata<T extends Entity>(alias: Alias<T>): EntityMetadata<T>;
+/** Creates domain predicates lazily from entity field metadata. */
+declare function newAliasProxy<T extends Entity>(cstr: MaybeAbstractEntityConstructor<T>): Alias<T>;
+/** Recognizes only domain aliases, not physical tables. */
+declare function isAlias(value: unknown): value is Alias<Entity>;
+/** Adjusts a field's SQL alias when a base alias is bound to a CTI subtype in the join tree. */
+declare function getMaybeCtiAlias(meta: EntityMetadata, field: Field & {
+  aliasSuffix: string;
+}, newMeta: EntityMetadata, newAlias: string): string;
+//#endregion
+export { Alias, AliasBrand, AliasColumn, AliasMgmt, EntityAlias, PolyAlias, PrimitiveAlias, alias, aliasMgmt, aliases, getAliasMetadata, getAliasMgmt, getMaybeCtiAlias, isAlias, newAliasProxy };
+//# sourceMappingURL=Aliases.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Aliases.d.mts","names":[],"sources":["../../../src/queries/find/Aliases.ts"],"mappings":";;;;;;;;;iBAyBgB,MAAM,UAAU,QAAQ,MAAM,+BAA+B,KAAK,MAAM;;iBAKxE,QAAQ,mBAAmB,0CACtC,OAAO,OACN,WAAW,IAAI,EAAE,WAAW,qCAAqC,UAAU,UAAU,MAAM;cAIpF;cACP;;UAGW;EACf;EACA,MAAM;;;;;EAKN,UAAU,QAAQ,MAAM,gBAAgB,kBAAkB,eAAe,eAAe;;;UAIzE,WAAW,WAAW;WAC5B,UAAU;;;;;;;;;;;;;;;;;;;;;KAsBT,MAAM,UAAU;YAAsB,YAAY,WAAW;OACtE,WAAW,SAAS,KAAK,iBACtB,YAAY,KACZ,SAAS,GAAG;EAAa;EAA4B,YAAY;EAAG,gBAAgB;IAClF,eAAe,GAAG,sCAClB,SAAS,GAAG;EAAa;EAAa,YAAY,UAAU;EAAQ,gBAAgB;IAClF,YAAY,GAAG,sCACf,SAAS,GAAG;EAAa;EAAc,YAAY,UAAU;IAC3D,UAAU;;UAKL,YAAY;YACjB,cAAc;;UAGT,eAAe,GAAG,wCAAwC,YAAY,IAAI;EACzF,GAAG,OAAO,IAAI,IAAI,YAAY,wBAAwB;EACtD,GAAG,OAAO,IAAI,IAAI,YAAY,wBAAwB;EACtD,GAAG,kBAAkB,0BAA0B;EAC/C,IAAI,kBAAkB,0BAA0B;EAChD,GAAG,OAAO,IAAI,YAAY,wBAAwB;EAClD,IAAI,OAAO,IAAI,YAAY,wBAAwB;EACnD,GAAG,OAAO,IAAI,YAAY,wBAAwB;EAClD,IAAI,OAAO,IAAI,YAAY,wBAAwB;EACnD,KAAK,OAAO,gBAAgB;EAC5B,MAAM,OAAO,gBAAgB;EAC7B,OAAO,OAAO,gBAAgB;EAC9B,QAAQ,IAAI,eAAe,IAAI,gBAAgB;EAE/C,SAAS,gBAAgB,IAAI,YAAY,YAAY,gBAAgB;EACrE,UAAU,gBAAgB,IAAI,YAAY,YAAY,gBAAgB;EACtE,SAAS,OAAO,IAAI,YAAY,YAAY,gBAAgB;EAC5D,UAAU,OAAO,IAAI,YAAY,YAAY,gBAAgB;;EAE7D,WAAW,+BAA+B;;EAE1C,WAAW,+BAA+B;;EAE1C,IAAI,aAAa,2CAA2C;;UAG7C,YAAY,GAAG,wCAAwC,YAAY,KAAK,KAAK;EAC5F,GAAG,OAAO,IAAI,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACzE,GAAG,OAAO,IAAI,KAAK,KAAK,YAAY,KAAK,gCAAgC;EAEzE,GAAG,kBAAkB,IAAI,KAAK,kCAAkC;EAChE,IAAI,kBAAkB,IAAI,KAAK,kCAAkC;EACjE,GAAG,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACrE,IAAI,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACtE,GAAG,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACrE,IAAI,OAAO,KAAK,KAAK,YAAY,KAAK,gCAAgC;EACtE,IAAI,aAAa,2CAA2C;;UAG7C,UAAU,UAAU;EACnC,GAAG,OAAO,IAAI,WAAW,YAAY,KAAK,gCAAgC;EAC1E,GAAG,OAAO,IAAI,WAAW,YAAY,KAAK,gCAAgC;EAC1E,GAAG,kBAAkB,IAAI,0BAA0B;;;iBAIrC,aAAa;YAAmB,YAAY;IAAc;;iBAK1D,iBAAiB,UAAU,QAAQ,OAAO,MAAM,KAAK,eAAe;;iBAKpE,cAAc,UAAU,QAAQ,MAAM,+BAA+B,KAAK,MAAM;;iBA+BhF,QAAQ,iBAAiB,SAAS,MAAM;;iBAiMxC,iBACd,MAAM,gBACN,OAAO;EAAU;GACjB,SAAS,gBACT"}