joist-core 2.3.0 → 2.4.0

package/build/queries/sql/expressions/case.cjs

@@ -0,0 +1,71 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_queries_sql_Expr = require("../Expr.cjs");
+const require_queries_sql_expressions_parseExpression = require("./parseExpression.cjs");
+const require_queries_sql_expressions_expression = require("./expression.cjs");
+//#region src/queries/sql/expressions/case.ts
+/**
+* Parses WHEN entries and an optional final ELSE into a ParsedCaseExpression.
+* Requires at least one WHEN, even if its condition may later be pruned.
+*/
+function parseCaseExpression(input) {
+	const entries = Array.isArray(input) ? input : [input];
+	const whens = [];
+	let fallback;
+	for (const [i, entry] of entries.entries()) if (require_queries_sql_expressions_parseExpression.isObject(entry) && "else" in entry) {
+		require_queries_sql_expressions_parseExpression.checkKeys(entry, ["else"]);
+		if (whens.length === 0) throw new Error("CASE needs a WHEN arm before ELSE");
+		if (i !== entries.length - 1) throw new Error("CASE ELSE must be last");
+		fallback = require_queries_sql_expressions_parseExpression.parseExpression(entry.else);
+	} else {
+		if (!require_queries_sql_expressions_parseExpression.isObject(entry) || !("when" in entry) || !("then" in entry)) throw new Error("A CASE arm needs when and then");
+		require_queries_sql_expressions_parseExpression.checkKeys(entry, ["when", "then"]);
+		whens.push({
+			when: entry.when,
+			then: require_queries_sql_expressions_parseExpression.parseExpression(entry.then)
+		});
+	}
+	if (whens.length === 0) throw new Error("CASE needs at least one arm");
+	const [first, ...rest] = whens;
+	return {
+		kind: "case",
+		whens: [first, ...rest],
+		else: fallback
+	};
+}
+/** Removes CASE entries with omitted conditions, falling back to ELSE or SQL NULL if none remain. */
+function caseToSql(parsed, ctx, codec) {
+	const parts = [];
+	for (const entry of parsed.whens) {
+		const when = entry.when === void 0 ? void 0 : ctx.conditionToSql(entry.when);
+		if (!when) continue;
+		const branch = require_queries_sql_Expr.joinFragments([when, require_queries_sql_expressions_expression.expressionToSql(entry.then, ctx, codec)], " THEN ");
+		parts.push({
+			...branch,
+			sql: `WHEN ${branch.sql}`
+		});
+	}
+	const otherwise = require_queries_sql_expressions_expression.expressionToSql(parsed.else ?? {
+		kind: "literal",
+		value: null
+	}, ctx, codec);
+	if (parts.length === 0) return otherwise;
+	if (parsed.else) parts.push({
+		...otherwise,
+		sql: `ELSE ${otherwise.sql}`
+	});
+	const body = require_queries_sql_Expr.joinFragments(parts, " ");
+	return {
+		...body,
+		sql: `(CASE ${body.sql} END)`
+	};
+}
+/** CASE is definitely non-null only when every THEN value and the ELSE value are non-null. */
+function caseNullable(parsed) {
+	return parsed.else && require_queries_sql_expressions_expression.expressionNullable(parsed.else) === false && parsed.whens.every((entry) => require_queries_sql_expressions_expression.expressionNullable(entry.then) === false) ? false : void 0;
+}
+//#endregion
+exports.caseNullable = caseNullable;
+exports.caseToSql = caseToSql;
+exports.parseCaseExpression = parseCaseExpression;
+
+//# sourceMappingURL=case.cjs.map

package/build/queries/sql/expressions/case.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.cjs","names":["isObject","parseExpression","joinFragments","expressionToSql","expressionNullable"],"sources":["../../../../src/queries/sql/expressions/case.ts"],"sourcesContent":["import { type ExprContext, type SqlFragment, joinFragments } from \"src/queries/sql/Expr.ts\";\nimport { expressionNullable, expressionToSql } from \"src/queries/sql/expressions/expression.ts\";\nimport { checkKeys, isObject, parseExpression } from \"src/queries/sql/expressions/parseExpression.ts\";\nimport type { CheckExpression, ParsedExpression, ResultCodec } from \"src/queries/sql/expressions/types.ts\";\nimport type { QueryCondition } from \"src/queries/sql/query.ts\";\n\n/** One condition and the value to return when it is true. */\nexport interface CaseWhen {\n  readonly when: QueryCondition | undefined;\n  readonly then: unknown;\n  readonly else?: never;\n}\n\n/** The fallback value, allowed only as the last entry in a CASE array. */\nexport interface CaseElse {\n  readonly else: unknown;\n  readonly when?: never;\n  readonly then?: never;\n}\n\n/** A single WHEN or an ordered array of WHEN entries with an optional final ELSE. */\nexport interface CaseInput {\n  readonly case: CaseWhen | readonly (CaseWhen | CaseElse)[];\n}\n\n/** The values returned by CASE's THEN and ELSE entries. */\nexport type CaseArmValue<A> = A extends readonly unknown[]\n  ? CaseArmValue<A[number]>\n  : A extends { readonly then: infer V }\n    ? V\n    : A extends { readonly else: infer V }\n      ? V\n      : never;\n\n/** A single CASE entry must be WHEN; an array can also have a final ELSE. */\nexport type CheckCase<A, R> = A extends readonly []\n  ? \"CASE needs at least one arm\"\n  : A extends readonly unknown[]\n    ? { readonly [K in keyof A]: CheckCaseEntry<A[K], R> } & CheckCaseOrder<A>\n    : A extends CaseWhen\n      ? CheckCaseEntry<A, R>\n      : never;\n\n/** Checks THEN/ELSE values and rejects extra keys on an entry. */\ntype CheckCaseEntry<A, R> = A extends CaseWhen\n  ? { readonly [K in keyof A]: K extends \"then\" ? CheckExpression<A[K], R> : K extends \"when\" ? unknown : never }\n  : A extends CaseElse\n    ? { readonly [K in keyof A]: K extends \"else\" ? CheckExpression<A[K], R> : never }\n    : never;\n\n/** Fixed CASE arrays can be checked now; dynamic arrays get the same checks at runtime. */\ntype CheckCaseOrder<A extends readonly unknown[], HasWhen extends boolean = false> = A extends readonly [\n  infer H,\n  ...infer T,\n]\n  ? H extends { readonly else: unknown }\n    ? HasWhen extends true\n      ? T extends readonly []\n        ? unknown\n        : \"CASE ELSE must be last\"\n      : \"CASE needs a WHEN arm before ELSE\"\n    : CheckCaseOrder<T, true>\n  : unknown;\n\n/** A CASE has at least one WHEN and an optional ELSE; no ELSE means SQL NULL. */\nexport interface ParsedCaseExpression {\n  kind: \"case\";\n  whens: [ParsedCaseWhen, ...ParsedCaseWhen[]];\n  else?: ParsedExpression;\n}\n\n/** A CASE condition and its parsed result expression. */\ninterface ParsedCaseWhen {\n  when: QueryCondition | undefined;\n  then: ParsedExpression;\n}\n\n/**\n * Parses WHEN entries and an optional final ELSE into a ParsedCaseExpression.\n * Requires at least one WHEN, even if its condition may later be pruned.\n */\nexport function parseCaseExpression(input: unknown): ParsedCaseExpression {\n  const entries = Array.isArray(input) ? input : [input];\n  const whens: ParsedCaseWhen[] = [];\n  let fallback: ParsedExpression | undefined;\n  for (const [i, entry] of entries.entries()) {\n    if (isObject(entry) && \"else\" in entry) {\n      checkKeys(entry, [\"else\"]);\n      if (whens.length === 0) throw new Error(\"CASE needs a WHEN arm before ELSE\");\n      if (i !== entries.length - 1) throw new Error(\"CASE ELSE must be last\");\n      fallback = parseExpression(entry.else);\n    } else {\n      if (!isObject(entry) || !(\"when\" in entry) || !(\"then\" in entry))\n        throw new Error(\"A CASE arm needs when and then\");\n      checkKeys(entry, [\"when\", \"then\"]);\n      whens.push({ when: entry.when as QueryCondition | undefined, then: parseExpression(entry.then) });\n    }\n  }\n  if (whens.length === 0) throw new Error(\"CASE needs at least one arm\");\n  const [first, ...rest] = whens;\n  return { kind: \"case\", whens: [first, ...rest], else: fallback };\n}\n\n/** Removes CASE entries with omitted conditions, falling back to ELSE or SQL NULL if none remain. */\nexport function caseToSql(parsed: ParsedCaseExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment {\n  const parts: SqlFragment[] = [];\n  for (const entry of parsed.whens) {\n    const when = entry.when === undefined ? undefined : ctx.conditionToSql(entry.when);\n    if (!when) continue;\n    const branch = joinFragments([when, expressionToSql(entry.then, ctx, codec)], \" THEN \");\n    parts.push({ ...branch, sql: `WHEN ${branch.sql}` });\n  }\n  const otherwise = expressionToSql(parsed.else ?? { kind: \"literal\", value: null }, ctx, codec);\n  if (parts.length === 0) return otherwise;\n  if (parsed.else) parts.push({ ...otherwise, sql: `ELSE ${otherwise.sql}` });\n  const body = joinFragments(parts, \" \");\n  return { ...body, sql: `(CASE ${body.sql} END)` };\n}\n\n/** CASE is definitely non-null only when every THEN value and the ELSE value are non-null. */\nexport function caseNullable(parsed: ParsedCaseExpression): boolean | undefined {\n  return parsed.else &&\n    expressionNullable(parsed.else) === false &&\n    parsed.whens.every((entry) => expressionNullable(entry.then) === false)\n    ? false\n    : undefined;\n}\n"],"mappings":";;;;;;;;;AAiFA,SAAgB,oBAAoB,OAAsC;CACxE,MAAM,UAAU,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACrD,MAAM,QAA0B,CAAC;CACjC,IAAI;CACJ,KAAK,MAAM,CAAC,GAAG,UAAU,QAAQ,QAAQ,GACvC,IAAIA,gDAAAA,SAAS,KAAK,KAAK,UAAU,OAAO;EACtC,gDAAA,UAAU,OAAO,CAAC,MAAM,CAAC;EACzB,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,mCAAmC;EAC3E,IAAI,MAAM,QAAQ,SAAS,GAAG,MAAM,IAAI,MAAM,wBAAwB;EACtE,WAAWC,gDAAAA,gBAAgB,MAAM,IAAI;CACvC,OAAO;EACL,IAAI,CAACD,gDAAAA,SAAS,KAAK,KAAK,EAAE,UAAU,UAAU,EAAE,UAAU,QACxD,MAAM,IAAI,MAAM,gCAAgC;EAClD,gDAAA,UAAU,OAAO,CAAC,QAAQ,MAAM,CAAC;EACjC,MAAM,KAAK;GAAE,MAAM,MAAM;GAAoC,MAAMC,gDAAAA,gBAAgB,MAAM,IAAI;EAAE,CAAC;CAClG;CAEF,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,6BAA6B;CACrE,MAAM,CAAC,OAAO,GAAG,QAAQ;CACzB,OAAO;EAAE,MAAM;EAAQ,OAAO,CAAC,OAAO,GAAG,IAAI;EAAG,MAAM;CAAS;AACjE;;AAGA,SAAgB,UAAU,QAA8B,KAAkB,OAAiC;CACzG,MAAM,QAAuB,CAAC;CAC9B,KAAK,MAAM,SAAS,OAAO,OAAO;EAChC,MAAM,OAAO,MAAM,SAAS,KAAA,IAAY,KAAA,IAAY,IAAI,eAAe,MAAM,IAAI;EACjF,IAAI,CAAC,MAAM;EACX,MAAM,SAASC,yBAAAA,cAAc,CAAC,MAAMC,2CAAAA,gBAAgB,MAAM,MAAM,KAAK,KAAK,CAAC,GAAG,QAAQ;EACtF,MAAM,KAAK;GAAE,GAAG;GAAQ,KAAK,QAAQ,OAAO;EAAM,CAAC;CACrD;CACA,MAAM,YAAYA,2CAAAA,gBAAgB,OAAO,QAAQ;EAAE,MAAM;EAAW,OAAO;CAAK,GAAG,KAAK,KAAK;CAC7F,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,IAAI,OAAO,MAAM,MAAM,KAAK;EAAE,GAAG;EAAW,KAAK,QAAQ,UAAU;CAAM,CAAC;CAC1E,MAAM,OAAOD,yBAAAA,cAAc,OAAO,GAAG;CACrC,OAAO;EAAE,GAAG;EAAM,KAAK,SAAS,KAAK,IAAI;CAAO;AAClD;;AAGA,SAAgB,aAAa,QAAmD;CAC9E,OAAO,OAAO,QACZE,2CAAAA,mBAAmB,OAAO,IAAI,MAAM,SACpC,OAAO,MAAM,OAAO,UAAUA,2CAAAA,mBAAmB,MAAM,IAAI,MAAM,KAAK,IACpE,QACA,KAAA;AACN"}

package/build/queries/sql/expressions/case.d.cts

@@ -0,0 +1,57 @@
+import { CheckExpression, ParsedExpression, ResultCodec } from "./types.cjs";
+import { QueryCondition } from "../query.cjs";
+import { ExprContext, SqlFragment } from "../Expr.cjs";
+//#region src/queries/sql/expressions/case.d.ts
+/** One condition and the value to return when it is true. */
+interface CaseWhen {
+  readonly when: QueryCondition | undefined;
+  readonly then: unknown;
+  readonly else?: never;
+}
+/** The fallback value, allowed only as the last entry in a CASE array. */
+interface CaseElse {
+  readonly else: unknown;
+  readonly when?: never;
+  readonly then?: never;
+}
+/** A single WHEN or an ordered array of WHEN entries with an optional final ELSE. */
+interface CaseInput {
+  readonly case: CaseWhen | readonly (CaseWhen | CaseElse)[];
+}
+/** The values returned by CASE's THEN and ELSE entries. */
+type CaseArmValue<A> = A extends readonly unknown[] ? CaseArmValue<A[number]> : A extends {
+  readonly then: infer V;
+} ? V : A extends {
+  readonly else: infer V;
+} ? V : never;
+/** A single CASE entry must be WHEN; an array can also have a final ELSE. */
+type CheckCase<A, R> = A extends readonly [] ? "CASE needs at least one arm" : A extends readonly unknown[] ? { readonly [K in keyof A]: CheckCaseEntry<A[K], R>; } & CheckCaseOrder<A> : A extends CaseWhen ? CheckCaseEntry<A, R> : never;
+/** Checks THEN/ELSE values and rejects extra keys on an entry. */
+type CheckCaseEntry<A, R> = A extends CaseWhen ? { readonly [K in keyof A]: K extends "then" ? CheckExpression<A[K], R> : K extends "when" ? unknown : never; } : A extends CaseElse ? { readonly [K in keyof A]: K extends "else" ? CheckExpression<A[K], R> : never; } : never;
+/** Fixed CASE arrays can be checked now; dynamic arrays get the same checks at runtime. */
+type CheckCaseOrder<A extends readonly unknown[], HasWhen extends boolean = false> = A extends readonly [infer H, ...infer T] ? H extends {
+  readonly else: unknown;
+} ? HasWhen extends true ? T extends readonly [] ? unknown : "CASE ELSE must be last" : "CASE needs a WHEN arm before ELSE" : CheckCaseOrder<T, true> : unknown;
+/** A CASE has at least one WHEN and an optional ELSE; no ELSE means SQL NULL. */
+interface ParsedCaseExpression {
+  kind: "case";
+  whens: [ParsedCaseWhen, ...ParsedCaseWhen[]];
+  else?: ParsedExpression;
+}
+/** A CASE condition and its parsed result expression. */
+interface ParsedCaseWhen {
+  when: QueryCondition | undefined;
+  then: ParsedExpression;
+}
+/**
+ * Parses WHEN entries and an optional final ELSE into a ParsedCaseExpression.
+ * Requires at least one WHEN, even if its condition may later be pruned.
+ */
+declare function parseCaseExpression(input: unknown): ParsedCaseExpression;
+/** Removes CASE entries with omitted conditions, falling back to ELSE or SQL NULL if none remain. */
+declare function caseToSql(parsed: ParsedCaseExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment;
+/** CASE is definitely non-null only when every THEN value and the ELSE value are non-null. */
+declare function caseNullable(parsed: ParsedCaseExpression): boolean | undefined;
+//#endregion
+export { CaseArmValue, CaseElse, CaseInput, CaseWhen, CheckCase, ParsedCaseExpression, caseNullable, caseToSql, parseCaseExpression };
+//# sourceMappingURL=case.d.cts.map

package/build/queries/sql/expressions/case.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.d.cts","names":[],"sources":["../../../../src/queries/sql/expressions/case.ts"],"mappings":";;;;;UAOiB;WACN,MAAM;WACN;WACA;;;UAIM;WACN;WACA;WACA;;;UAIM;WACN,MAAM,qBAAqB,WAAW;;;KAIrC,aAAa,KAAK,+BAC1B,aAAa,aACb;WAAqB,YAAY;IAC/B,IACA;WAAqB,YAAY;IAC/B;;KAII,UAAU,GAAG,KAAK,wDAE1B,2CACc,WAAW,IAAI,eAAe,EAAE,IAAI,QAAO,eAAe,KACtE,UAAU,WACR,eAAe,GAAG;;KAIrB,eAAe,GAAG,KAAK,UAAU,uBACtB,WAAW,IAAI,mBAAmB,gBAAgB,EAAE,IAAI,KAAK,wCACzE,UAAU,uBACI,WAAW,IAAI,mBAAmB,gBAAgB,EAAE,IAAI;;KAIrE,eAAe,8BAA8B,mCAAmC,0BAC7E,YACG,KAEP;WAAqB;IACnB,uBACE,mGAIF,eAAe;;UAIJ;EACf;EACA,QAAQ,mBAAmB;EAC3B,OAAO;;;UAIC;EACR,MAAM;EACN,MAAM;;;;;;iBAOQ,oBAAoB,iBAAiB;;iBAuBrC,UAAU,QAAQ,sBAAsB,KAAK,aAAa,OAAO,cAAc;;iBAgB/E,aAAa,QAAQ"}

package/build/queries/sql/expressions/case.d.mts

@@ -0,0 +1,57 @@
+import { CheckExpression, ParsedExpression, ResultCodec } from "./types.mjs";
+import { QueryCondition } from "../query.mjs";
+import { ExprContext, SqlFragment } from "../Expr.mjs";
+//#region src/queries/sql/expressions/case.d.ts
+/** One condition and the value to return when it is true. */
+interface CaseWhen {
+  readonly when: QueryCondition | undefined;
+  readonly then: unknown;
+  readonly else?: never;
+}
+/** The fallback value, allowed only as the last entry in a CASE array. */
+interface CaseElse {
+  readonly else: unknown;
+  readonly when?: never;
+  readonly then?: never;
+}
+/** A single WHEN or an ordered array of WHEN entries with an optional final ELSE. */
+interface CaseInput {
+  readonly case: CaseWhen | readonly (CaseWhen | CaseElse)[];
+}
+/** The values returned by CASE's THEN and ELSE entries. */
+type CaseArmValue<A> = A extends readonly unknown[] ? CaseArmValue<A[number]> : A extends {
+  readonly then: infer V;
+} ? V : A extends {
+  readonly else: infer V;
+} ? V : never;
+/** A single CASE entry must be WHEN; an array can also have a final ELSE. */
+type CheckCase<A, R> = A extends readonly [] ? "CASE needs at least one arm" : A extends readonly unknown[] ? { readonly [K in keyof A]: CheckCaseEntry<A[K], R>; } & CheckCaseOrder<A> : A extends CaseWhen ? CheckCaseEntry<A, R> : never;
+/** Checks THEN/ELSE values and rejects extra keys on an entry. */
+type CheckCaseEntry<A, R> = A extends CaseWhen ? { readonly [K in keyof A]: K extends "then" ? CheckExpression<A[K], R> : K extends "when" ? unknown : never; } : A extends CaseElse ? { readonly [K in keyof A]: K extends "else" ? CheckExpression<A[K], R> : never; } : never;
+/** Fixed CASE arrays can be checked now; dynamic arrays get the same checks at runtime. */
+type CheckCaseOrder<A extends readonly unknown[], HasWhen extends boolean = false> = A extends readonly [infer H, ...infer T] ? H extends {
+  readonly else: unknown;
+} ? HasWhen extends true ? T extends readonly [] ? unknown : "CASE ELSE must be last" : "CASE needs a WHEN arm before ELSE" : CheckCaseOrder<T, true> : unknown;
+/** A CASE has at least one WHEN and an optional ELSE; no ELSE means SQL NULL. */
+interface ParsedCaseExpression {
+  kind: "case";
+  whens: [ParsedCaseWhen, ...ParsedCaseWhen[]];
+  else?: ParsedExpression;
+}
+/** A CASE condition and its parsed result expression. */
+interface ParsedCaseWhen {
+  when: QueryCondition | undefined;
+  then: ParsedExpression;
+}
+/**
+ * Parses WHEN entries and an optional final ELSE into a ParsedCaseExpression.
+ * Requires at least one WHEN, even if its condition may later be pruned.
+ */
+declare function parseCaseExpression(input: unknown): ParsedCaseExpression;
+/** Removes CASE entries with omitted conditions, falling back to ELSE or SQL NULL if none remain. */
+declare function caseToSql(parsed: ParsedCaseExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment;
+/** CASE is definitely non-null only when every THEN value and the ELSE value are non-null. */
+declare function caseNullable(parsed: ParsedCaseExpression): boolean | undefined;
+//#endregion
+export { CaseArmValue, CaseElse, CaseInput, CaseWhen, CheckCase, ParsedCaseExpression, caseNullable, caseToSql, parseCaseExpression };
+//# sourceMappingURL=case.d.mts.map

package/build/queries/sql/expressions/case.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.d.mts","names":[],"sources":["../../../../src/queries/sql/expressions/case.ts"],"mappings":";;;;;UAOiB;WACN,MAAM;WACN;WACA;;;UAIM;WACN;WACA;WACA;;;UAIM;WACN,MAAM,qBAAqB,WAAW;;;KAIrC,aAAa,KAAK,+BAC1B,aAAa,aACb;WAAqB,YAAY;IAC/B,IACA;WAAqB,YAAY;IAC/B;;KAII,UAAU,GAAG,KAAK,wDAE1B,2CACc,WAAW,IAAI,eAAe,EAAE,IAAI,QAAO,eAAe,KACtE,UAAU,WACR,eAAe,GAAG;;KAIrB,eAAe,GAAG,KAAK,UAAU,uBACtB,WAAW,IAAI,mBAAmB,gBAAgB,EAAE,IAAI,KAAK,wCACzE,UAAU,uBACI,WAAW,IAAI,mBAAmB,gBAAgB,EAAE,IAAI;;KAIrE,eAAe,8BAA8B,mCAAmC,0BAC7E,YACG,KAEP;WAAqB;IACnB,uBACE,mGAIF,eAAe;;UAIJ;EACf;EACA,QAAQ,mBAAmB;EAC3B,OAAO;;;UAIC;EACR,MAAM;EACN,MAAM;;;;;;iBAOQ,oBAAoB,iBAAiB;;iBAuBrC,UAAU,QAAQ,sBAAsB,KAAK,aAAa,OAAO,cAAc;;iBAgB/E,aAAa,QAAQ"}

package/build/queries/sql/expressions/case.js

@@ -0,0 +1,68 @@
+import { joinFragments } from "../Expr.js";
+import { checkKeys, isObject, parseExpression } from "./parseExpression.js";
+import { expressionNullable, expressionToSql } from "./expression.js";
+//#region src/queries/sql/expressions/case.ts
+/**
+* Parses WHEN entries and an optional final ELSE into a ParsedCaseExpression.
+* Requires at least one WHEN, even if its condition may later be pruned.
+*/
+function parseCaseExpression(input) {
+	const entries = Array.isArray(input) ? input : [input];
+	const whens = [];
+	let fallback;
+	for (const [i, entry] of entries.entries()) if (isObject(entry) && "else" in entry) {
+		checkKeys(entry, ["else"]);
+		if (whens.length === 0) throw new Error("CASE needs a WHEN arm before ELSE");
+		if (i !== entries.length - 1) throw new Error("CASE ELSE must be last");
+		fallback = parseExpression(entry.else);
+	} else {
+		if (!isObject(entry) || !("when" in entry) || !("then" in entry)) throw new Error("A CASE arm needs when and then");
+		checkKeys(entry, ["when", "then"]);
+		whens.push({
+			when: entry.when,
+			then: parseExpression(entry.then)
+		});
+	}
+	if (whens.length === 0) throw new Error("CASE needs at least one arm");
+	const [first, ...rest] = whens;
+	return {
+		kind: "case",
+		whens: [first, ...rest],
+		else: fallback
+	};
+}
+/** Removes CASE entries with omitted conditions, falling back to ELSE or SQL NULL if none remain. */
+function caseToSql(parsed, ctx, codec) {
+	const parts = [];
+	for (const entry of parsed.whens) {
+		const when = entry.when === void 0 ? void 0 : ctx.conditionToSql(entry.when);
+		if (!when) continue;
+		const branch = joinFragments([when, expressionToSql(entry.then, ctx, codec)], " THEN ");
+		parts.push({
+			...branch,
+			sql: `WHEN ${branch.sql}`
+		});
+	}
+	const otherwise = expressionToSql(parsed.else ?? {
+		kind: "literal",
+		value: null
+	}, ctx, codec);
+	if (parts.length === 0) return otherwise;
+	if (parsed.else) parts.push({
+		...otherwise,
+		sql: `ELSE ${otherwise.sql}`
+	});
+	const body = joinFragments(parts, " ");
+	return {
+		...body,
+		sql: `(CASE ${body.sql} END)`
+	};
+}
+/** CASE is definitely non-null only when every THEN value and the ELSE value are non-null. */
+function caseNullable(parsed) {
+	return parsed.else && expressionNullable(parsed.else) === false && parsed.whens.every((entry) => expressionNullable(entry.then) === false) ? false : void 0;
+}
+//#endregion
+export { caseNullable, caseToSql, parseCaseExpression };
+
+//# sourceMappingURL=case.js.map

package/build/queries/sql/expressions/case.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.js","names":[],"sources":["../../../../src/queries/sql/expressions/case.ts"],"sourcesContent":["import { type ExprContext, type SqlFragment, joinFragments } from \"src/queries/sql/Expr.ts\";\nimport { expressionNullable, expressionToSql } from \"src/queries/sql/expressions/expression.ts\";\nimport { checkKeys, isObject, parseExpression } from \"src/queries/sql/expressions/parseExpression.ts\";\nimport type { CheckExpression, ParsedExpression, ResultCodec } from \"src/queries/sql/expressions/types.ts\";\nimport type { QueryCondition } from \"src/queries/sql/query.ts\";\n\n/** One condition and the value to return when it is true. */\nexport interface CaseWhen {\n  readonly when: QueryCondition | undefined;\n  readonly then: unknown;\n  readonly else?: never;\n}\n\n/** The fallback value, allowed only as the last entry in a CASE array. */\nexport interface CaseElse {\n  readonly else: unknown;\n  readonly when?: never;\n  readonly then?: never;\n}\n\n/** A single WHEN or an ordered array of WHEN entries with an optional final ELSE. */\nexport interface CaseInput {\n  readonly case: CaseWhen | readonly (CaseWhen | CaseElse)[];\n}\n\n/** The values returned by CASE's THEN and ELSE entries. */\nexport type CaseArmValue<A> = A extends readonly unknown[]\n  ? CaseArmValue<A[number]>\n  : A extends { readonly then: infer V }\n    ? V\n    : A extends { readonly else: infer V }\n      ? V\n      : never;\n\n/** A single CASE entry must be WHEN; an array can also have a final ELSE. */\nexport type CheckCase<A, R> = A extends readonly []\n  ? \"CASE needs at least one arm\"\n  : A extends readonly unknown[]\n    ? { readonly [K in keyof A]: CheckCaseEntry<A[K], R> } & CheckCaseOrder<A>\n    : A extends CaseWhen\n      ? CheckCaseEntry<A, R>\n      : never;\n\n/** Checks THEN/ELSE values and rejects extra keys on an entry. */\ntype CheckCaseEntry<A, R> = A extends CaseWhen\n  ? { readonly [K in keyof A]: K extends \"then\" ? CheckExpression<A[K], R> : K extends \"when\" ? unknown : never }\n  : A extends CaseElse\n    ? { readonly [K in keyof A]: K extends \"else\" ? CheckExpression<A[K], R> : never }\n    : never;\n\n/** Fixed CASE arrays can be checked now; dynamic arrays get the same checks at runtime. */\ntype CheckCaseOrder<A extends readonly unknown[], HasWhen extends boolean = false> = A extends readonly [\n  infer H,\n  ...infer T,\n]\n  ? H extends { readonly else: unknown }\n    ? HasWhen extends true\n      ? T extends readonly []\n        ? unknown\n        : \"CASE ELSE must be last\"\n      : \"CASE needs a WHEN arm before ELSE\"\n    : CheckCaseOrder<T, true>\n  : unknown;\n\n/** A CASE has at least one WHEN and an optional ELSE; no ELSE means SQL NULL. */\nexport interface ParsedCaseExpression {\n  kind: \"case\";\n  whens: [ParsedCaseWhen, ...ParsedCaseWhen[]];\n  else?: ParsedExpression;\n}\n\n/** A CASE condition and its parsed result expression. */\ninterface ParsedCaseWhen {\n  when: QueryCondition | undefined;\n  then: ParsedExpression;\n}\n\n/**\n * Parses WHEN entries and an optional final ELSE into a ParsedCaseExpression.\n * Requires at least one WHEN, even if its condition may later be pruned.\n */\nexport function parseCaseExpression(input: unknown): ParsedCaseExpression {\n  const entries = Array.isArray(input) ? input : [input];\n  const whens: ParsedCaseWhen[] = [];\n  let fallback: ParsedExpression | undefined;\n  for (const [i, entry] of entries.entries()) {\n    if (isObject(entry) && \"else\" in entry) {\n      checkKeys(entry, [\"else\"]);\n      if (whens.length === 0) throw new Error(\"CASE needs a WHEN arm before ELSE\");\n      if (i !== entries.length - 1) throw new Error(\"CASE ELSE must be last\");\n      fallback = parseExpression(entry.else);\n    } else {\n      if (!isObject(entry) || !(\"when\" in entry) || !(\"then\" in entry))\n        throw new Error(\"A CASE arm needs when and then\");\n      checkKeys(entry, [\"when\", \"then\"]);\n      whens.push({ when: entry.when as QueryCondition | undefined, then: parseExpression(entry.then) });\n    }\n  }\n  if (whens.length === 0) throw new Error(\"CASE needs at least one arm\");\n  const [first, ...rest] = whens;\n  return { kind: \"case\", whens: [first, ...rest], else: fallback };\n}\n\n/** Removes CASE entries with omitted conditions, falling back to ELSE or SQL NULL if none remain. */\nexport function caseToSql(parsed: ParsedCaseExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment {\n  const parts: SqlFragment[] = [];\n  for (const entry of parsed.whens) {\n    const when = entry.when === undefined ? undefined : ctx.conditionToSql(entry.when);\n    if (!when) continue;\n    const branch = joinFragments([when, expressionToSql(entry.then, ctx, codec)], \" THEN \");\n    parts.push({ ...branch, sql: `WHEN ${branch.sql}` });\n  }\n  const otherwise = expressionToSql(parsed.else ?? { kind: \"literal\", value: null }, ctx, codec);\n  if (parts.length === 0) return otherwise;\n  if (parsed.else) parts.push({ ...otherwise, sql: `ELSE ${otherwise.sql}` });\n  const body = joinFragments(parts, \" \");\n  return { ...body, sql: `(CASE ${body.sql} END)` };\n}\n\n/** CASE is definitely non-null only when every THEN value and the ELSE value are non-null. */\nexport function caseNullable(parsed: ParsedCaseExpression): boolean | undefined {\n  return parsed.else &&\n    expressionNullable(parsed.else) === false &&\n    parsed.whens.every((entry) => expressionNullable(entry.then) === false)\n    ? false\n    : undefined;\n}\n"],"mappings":";;;;;;;;AAiFA,SAAgB,oBAAoB,OAAsC;CACxE,MAAM,UAAU,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACrD,MAAM,QAA0B,CAAC;CACjC,IAAI;CACJ,KAAK,MAAM,CAAC,GAAG,UAAU,QAAQ,QAAQ,GACvC,IAAI,SAAS,KAAK,KAAK,UAAU,OAAO;EACtC,UAAU,OAAO,CAAC,MAAM,CAAC;EACzB,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,mCAAmC;EAC3E,IAAI,MAAM,QAAQ,SAAS,GAAG,MAAM,IAAI,MAAM,wBAAwB;EACtE,WAAW,gBAAgB,MAAM,IAAI;CACvC,OAAO;EACL,IAAI,CAAC,SAAS,KAAK,KAAK,EAAE,UAAU,UAAU,EAAE,UAAU,QACxD,MAAM,IAAI,MAAM,gCAAgC;EAClD,UAAU,OAAO,CAAC,QAAQ,MAAM,CAAC;EACjC,MAAM,KAAK;GAAE,MAAM,MAAM;GAAoC,MAAM,gBAAgB,MAAM,IAAI;EAAE,CAAC;CAClG;CAEF,IAAI,MAAM,WAAW,GAAG,MAAM,IAAI,MAAM,6BAA6B;CACrE,MAAM,CAAC,OAAO,GAAG,QAAQ;CACzB,OAAO;EAAE,MAAM;EAAQ,OAAO,CAAC,OAAO,GAAG,IAAI;EAAG,MAAM;CAAS;AACjE;;AAGA,SAAgB,UAAU,QAA8B,KAAkB,OAAiC;CACzG,MAAM,QAAuB,CAAC;CAC9B,KAAK,MAAM,SAAS,OAAO,OAAO;EAChC,MAAM,OAAO,MAAM,SAAS,KAAA,IAAY,KAAA,IAAY,IAAI,eAAe,MAAM,IAAI;EACjF,IAAI,CAAC,MAAM;EACX,MAAM,SAAS,cAAc,CAAC,MAAM,gBAAgB,MAAM,MAAM,KAAK,KAAK,CAAC,GAAG,QAAQ;EACtF,MAAM,KAAK;GAAE,GAAG;GAAQ,KAAK,QAAQ,OAAO;EAAM,CAAC;CACrD;CACA,MAAM,YAAY,gBAAgB,OAAO,QAAQ;EAAE,MAAM;EAAW,OAAO;CAAK,GAAG,KAAK,KAAK;CAC7F,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,IAAI,OAAO,MAAM,MAAM,KAAK;EAAE,GAAG;EAAW,KAAK,QAAQ,UAAU;CAAM,CAAC;CAC1E,MAAM,OAAO,cAAc,OAAO,GAAG;CACrC,OAAO;EAAE,GAAG;EAAM,KAAK,SAAS,KAAK,IAAI;CAAO;AAClD;;AAGA,SAAgB,aAAa,QAAmD;CAC9E,OAAO,OAAO,QACZ,mBAAmB,OAAO,IAAI,MAAM,SACpC,OAAO,MAAM,OAAO,UAAU,mBAAmB,MAAM,IAAI,MAAM,KAAK,IACpE,QACA,KAAA;AACN"}

package/build/queries/sql/expressions/coalesce.cjs

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_queries_sql_expressions_parseExpression = require("./parseExpression.cjs");
+const require_queries_sql_expressions_expression = require("./expression.cjs");
+//#region src/queries/sql/expressions/coalesce.ts
+/** Parses COALESCE candidates and requires at least one value. */
+function parseCoalesceExpression(input) {
+	return {
+		kind: "coalesce",
+		candidates: require_queries_sql_expressions_parseExpression.parseNonEmptyOperands(input, "COALESCE")
+	};
+}
+/** Renders COALESCE candidates in their original order. */
+function coalesceToSql(parsed, ctx, codec) {
+	return require_queries_sql_expressions_expression.functionToSql("COALESCE", parsed.candidates, ctx, codec);
+}
+/** One non-null candidate guarantees a non-null COALESCE result. */
+function coalesceNullable(parsed) {
+	return parsed.candidates.some((candidate) => require_queries_sql_expressions_expression.expressionNullable(candidate) === false) ? false : void 0;
+}
+//#endregion
+exports.coalesceNullable = coalesceNullable;
+exports.coalesceToSql = coalesceToSql;
+exports.parseCoalesceExpression = parseCoalesceExpression;
+
+//# sourceMappingURL=coalesce.cjs.map

package/build/queries/sql/expressions/coalesce.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.cjs","names":["parseNonEmptyOperands","functionToSql","expressionNullable"],"sources":["../../../../src/queries/sql/expressions/coalesce.ts"],"sourcesContent":["import type { ExprContext, SqlFragment } from \"src/queries/sql/Expr.ts\";\nimport { expressionNullable, functionToSql } from \"src/queries/sql/expressions/expression.ts\";\nimport { parseNonEmptyOperands } from \"src/queries/sql/expressions/parseExpression.ts\";\nimport type { ParsedExpression, ResultCodec } from \"src/queries/sql/expressions/types.ts\";\n\n/** Candidates in order of preference; COALESCE returns the first non-null value. */\nexport interface CoalesceInput {\n  readonly coalesce: readonly unknown[];\n}\n\n/** A COALESCE with at least one candidate, in SQL evaluation order. */\nexport interface ParsedCoalesceExpression {\n  kind: \"coalesce\";\n  candidates: [ParsedExpression, ...ParsedExpression[]];\n}\n\n/** Parses COALESCE candidates and requires at least one value. */\nexport function parseCoalesceExpression(input: unknown): ParsedCoalesceExpression {\n  return { kind: \"coalesce\", candidates: parseNonEmptyOperands(input, \"COALESCE\") };\n}\n\n/** Renders COALESCE candidates in their original order. */\nexport function coalesceToSql(parsed: ParsedCoalesceExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment {\n  return functionToSql(\"COALESCE\", parsed.candidates, ctx, codec);\n}\n\n/** One non-null candidate guarantees a non-null COALESCE result. */\nexport function coalesceNullable(parsed: ParsedCoalesceExpression): boolean | undefined {\n  return parsed.candidates.some((candidate) => expressionNullable(candidate) === false) ? false : undefined;\n}\n"],"mappings":";;;;;AAiBA,SAAgB,wBAAwB,OAA0C;CAChF,OAAO;EAAE,MAAM;EAAY,YAAYA,gDAAAA,sBAAsB,OAAO,UAAU;CAAE;AAClF;;AAGA,SAAgB,cAAc,QAAkC,KAAkB,OAAiC;CACjH,OAAOC,2CAAAA,cAAc,YAAY,OAAO,YAAY,KAAK,KAAK;AAChE;;AAGA,SAAgB,iBAAiB,QAAuD;CACtF,OAAO,OAAO,WAAW,MAAM,cAAcC,2CAAAA,mBAAmB,SAAS,MAAM,KAAK,IAAI,QAAQ,KAAA;AAClG"}

package/build/queries/sql/expressions/coalesce.d.cts

@@ -0,0 +1,21 @@
+import { ParsedExpression, ResultCodec } from "./types.cjs";
+import { ExprContext, SqlFragment } from "../Expr.cjs";
+//#region src/queries/sql/expressions/coalesce.d.ts
+/** Candidates in order of preference; COALESCE returns the first non-null value. */
+interface CoalesceInput {
+  readonly coalesce: readonly unknown[];
+}
+/** A COALESCE with at least one candidate, in SQL evaluation order. */
+interface ParsedCoalesceExpression {
+  kind: "coalesce";
+  candidates: [ParsedExpression, ...ParsedExpression[]];
+}
+/** Parses COALESCE candidates and requires at least one value. */
+declare function parseCoalesceExpression(input: unknown): ParsedCoalesceExpression;
+/** Renders COALESCE candidates in their original order. */
+declare function coalesceToSql(parsed: ParsedCoalesceExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment;
+/** One non-null candidate guarantees a non-null COALESCE result. */
+declare function coalesceNullable(parsed: ParsedCoalesceExpression): boolean | undefined;
+//#endregion
+export { CoalesceInput, ParsedCoalesceExpression, coalesceNullable, coalesceToSql, parseCoalesceExpression };
+//# sourceMappingURL=coalesce.d.cts.map

package/build/queries/sql/expressions/coalesce.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.d.cts","names":[],"sources":["../../../../src/queries/sql/expressions/coalesce.ts"],"mappings":";;;;UAMiB;WACN;;;UAIM;EACf;EACA,aAAa,qBAAqB;;;iBAIpB,wBAAwB,iBAAiB;;iBAKzC,cAAc,QAAQ,0BAA0B,KAAK,aAAa,OAAO,cAAc;;iBAKvF,iBAAiB,QAAQ"}

package/build/queries/sql/expressions/coalesce.d.mts

@@ -0,0 +1,21 @@
+import { ParsedExpression, ResultCodec } from "./types.mjs";
+import { ExprContext, SqlFragment } from "../Expr.mjs";
+//#region src/queries/sql/expressions/coalesce.d.ts
+/** Candidates in order of preference; COALESCE returns the first non-null value. */
+interface CoalesceInput {
+  readonly coalesce: readonly unknown[];
+}
+/** A COALESCE with at least one candidate, in SQL evaluation order. */
+interface ParsedCoalesceExpression {
+  kind: "coalesce";
+  candidates: [ParsedExpression, ...ParsedExpression[]];
+}
+/** Parses COALESCE candidates and requires at least one value. */
+declare function parseCoalesceExpression(input: unknown): ParsedCoalesceExpression;
+/** Renders COALESCE candidates in their original order. */
+declare function coalesceToSql(parsed: ParsedCoalesceExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment;
+/** One non-null candidate guarantees a non-null COALESCE result. */
+declare function coalesceNullable(parsed: ParsedCoalesceExpression): boolean | undefined;
+//#endregion
+export { CoalesceInput, ParsedCoalesceExpression, coalesceNullable, coalesceToSql, parseCoalesceExpression };
+//# sourceMappingURL=coalesce.d.mts.map

package/build/queries/sql/expressions/coalesce.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.d.mts","names":[],"sources":["../../../../src/queries/sql/expressions/coalesce.ts"],"mappings":";;;;UAMiB;WACN;;;UAIM;EACf;EACA,aAAa,qBAAqB;;;iBAIpB,wBAAwB,iBAAiB;;iBAKzC,cAAc,QAAQ,0BAA0B,KAAK,aAAa,OAAO,cAAc;;iBAKvF,iBAAiB,QAAQ"}

package/build/queries/sql/expressions/coalesce.js

@@ -0,0 +1,22 @@
+import { parseNonEmptyOperands } from "./parseExpression.js";
+import { expressionNullable, functionToSql } from "./expression.js";
+//#region src/queries/sql/expressions/coalesce.ts
+/** Parses COALESCE candidates and requires at least one value. */
+function parseCoalesceExpression(input) {
+	return {
+		kind: "coalesce",
+		candidates: parseNonEmptyOperands(input, "COALESCE")
+	};
+}
+/** Renders COALESCE candidates in their original order. */
+function coalesceToSql(parsed, ctx, codec) {
+	return functionToSql("COALESCE", parsed.candidates, ctx, codec);
+}
+/** One non-null candidate guarantees a non-null COALESCE result. */
+function coalesceNullable(parsed) {
+	return parsed.candidates.some((candidate) => expressionNullable(candidate) === false) ? false : void 0;
+}
+//#endregion
+export { coalesceNullable, coalesceToSql, parseCoalesceExpression };
+
+//# sourceMappingURL=coalesce.js.map

package/build/queries/sql/expressions/coalesce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.js","names":[],"sources":["../../../../src/queries/sql/expressions/coalesce.ts"],"sourcesContent":["import type { ExprContext, SqlFragment } from \"src/queries/sql/Expr.ts\";\nimport { expressionNullable, functionToSql } from \"src/queries/sql/expressions/expression.ts\";\nimport { parseNonEmptyOperands } from \"src/queries/sql/expressions/parseExpression.ts\";\nimport type { ParsedExpression, ResultCodec } from \"src/queries/sql/expressions/types.ts\";\n\n/** Candidates in order of preference; COALESCE returns the first non-null value. */\nexport interface CoalesceInput {\n  readonly coalesce: readonly unknown[];\n}\n\n/** A COALESCE with at least one candidate, in SQL evaluation order. */\nexport interface ParsedCoalesceExpression {\n  kind: \"coalesce\";\n  candidates: [ParsedExpression, ...ParsedExpression[]];\n}\n\n/** Parses COALESCE candidates and requires at least one value. */\nexport function parseCoalesceExpression(input: unknown): ParsedCoalesceExpression {\n  return { kind: \"coalesce\", candidates: parseNonEmptyOperands(input, \"COALESCE\") };\n}\n\n/** Renders COALESCE candidates in their original order. */\nexport function coalesceToSql(parsed: ParsedCoalesceExpression, ctx: ExprContext, codec: ResultCodec): SqlFragment {\n  return functionToSql(\"COALESCE\", parsed.candidates, ctx, codec);\n}\n\n/** One non-null candidate guarantees a non-null COALESCE result. */\nexport function coalesceNullable(parsed: ParsedCoalesceExpression): boolean | undefined {\n  return parsed.candidates.some((candidate) => expressionNullable(candidate) === false) ? false : undefined;\n}\n"],"mappings":";;;;AAiBA,SAAgB,wBAAwB,OAA0C;CAChF,OAAO;EAAE,MAAM;EAAY,YAAY,sBAAsB,OAAO,UAAU;CAAE;AAClF;;AAGA,SAAgB,cAAc,QAAkC,KAAkB,OAAiC;CACjH,OAAO,cAAc,YAAY,OAAO,YAAY,KAAK,KAAK;AAChE;;AAGA,SAAgB,iBAAiB,QAAuD;CACtF,OAAO,OAAO,WAAW,MAAM,cAAc,mBAAmB,SAAS,MAAM,KAAK,IAAI,QAAQ,KAAA;AAClG"}

package/build/queries/sql/expressions/codecs.cjs

@@ -0,0 +1,126 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_serde_TypeInfo = require("../../../serde/TypeInfo.cjs");
+const require_queries_sql_Expr = require("../Expr.cjs");
+const require_utils = require("../../../utils.cjs");
+let node_util = require("node:util");
+//#region src/queries/sql/expressions/codecs.ts
+/**
+* Chooses one decoder for all possible result values. Columns must agree on a compatible SQL type and domain;
+* literals use that column's encoder. This is conservative: PostgreSQL may accept other combinations,
+* but Joist cannot safely choose their decoder. I.e. Author.id and Book.id both store integers but use different tags.
+*/
+function chooseExpressionCodec(parsed) {
+	const leaves = expressionLeaves(parsed);
+	const expressions = leaves.flatMap((leaf) => "codec" in leaf ? [leaf.codec] : []);
+	const first = expressions[0];
+	if (first) {
+		for (const other of expressions.slice(1)) {
+			if (other === first) continue;
+			const a = first.outputType;
+			const b = other.outputType;
+			if (!a || !b || !compatibleDbTypes(a.dbType, b.dbType) || a.domain !== b.domain || a.idMeta !== b.idMeta) {
+				const mismatches = !a || !b ? ["unknown codec"] : [
+					...!compatibleDbTypes(a.dbType, b.dbType) ? ["SQL type"] : [],
+					...a.domain !== b.domain ? ["domain"] : [],
+					...a.idMeta !== b.idMeta ? ["ID target"] : []
+				];
+				throw new Error(`Expression operands need matching SQL types and codecs: ${describeType(a)} vs ${describeType(b)}; mismatched ${mismatches.join(", ")}`);
+			}
+		}
+		for (const leaf of leaves) if ("literal" in leaf) checkLiteral(leaf.literal.value, first.outputType);
+		return first;
+	}
+	const literals = leaves.flatMap((leaf) => "literal" in leaf ? [leaf.literal] : []);
+	const types = literals.map((v) => literalType(v.value)).filter((v) => v !== void 0);
+	for (const literal of literals) checkLiteral(literal.value, types[0]);
+	return new LiteralCodec(types[0] ?? {
+		dbType: "text",
+		domain: String
+	});
+}
+/** Gives literal-only expressions a SQL type so PostgreSQL does not return numbers as text. */
+var LiteralCodec = class {
+	outputType;
+	constructor(outputType) {
+		this.outputType = outputType;
+	}
+	encode(value) {
+		return value;
+	}
+	decode(value) {
+		return this.outputType.domain === BigInt ? BigInt(value) : value;
+	}
+};
+/**
+* Finds parsed operands that share a codec, including NULLIF's comparison operand but not CASE conditions.
+* Each kind selects its own value fields; only CASE's THEN and ELSE expressions contribute a result codec.
+*/
+function expressionLeaves(parsed) {
+	if (parsed instanceof require_queries_sql_Expr.BaseExpr) return [{ codec: parsed }];
+	switch (parsed.kind) {
+		case "literal": return [{ literal: parsed }];
+		case "arrayAgg": {
+			const valueCodec = chooseExpressionCodec(parsed.value);
+			return [{ codec: {
+				outputType: require_serde_TypeInfo.arrayOutputType(valueCodec.outputType),
+				encode: (value) => Array.isArray(value) ? value.map((element) => valueCodec.encode(element)) : value,
+				decode: (value) => Array.isArray(value) ? value.map((element) => valueCodec.decode(element)) : value
+			} }];
+		}
+		case "coalesce": return parsed.candidates.flatMap((candidate) => expressionLeaves(candidate));
+		case "nullIf": return [...expressionLeaves(parsed.value), ...expressionLeaves(parsed.equals)];
+		case "greatest":
+		case "least": return parsed.values.flatMap((value) => expressionLeaves(value));
+		case "case": return [...parsed.whens.flatMap((entry) => expressionLeaves(entry.then)), ...parsed.else ? expressionLeaves(parsed.else) : []];
+		default: return require_utils.assertNever(parsed);
+	}
+}
+/** Supplies predictable PostgreSQL types for standalone primitive literals. */
+function literalType(value) {
+	if (value === null) return void 0;
+	if (typeof value === "string") return {
+		dbType: "text",
+		domain: String,
+		arrayElementSafe: true
+	};
+	if (typeof value === "number") return {
+		dbType: "float8",
+		domain: Number,
+		arrayElementSafe: true
+	};
+	if (typeof value === "boolean") return {
+		dbType: "bool",
+		domain: Boolean,
+		arrayElementSafe: true
+	};
+	if (typeof value === "bigint") return {
+		dbType: "int8",
+		domain: BigInt
+	};
+	if (value instanceof Date) return {
+		dbType: "timestamptz",
+		domain: Date
+	};
+	throw new Error("Object and array literals need an expression with a matching codec");
+}
+/** Rejects primitive literals that disagree with the column; custom values are checked by their encoder. */
+function checkLiteral(value, type) {
+	if (value === null || !type) return;
+	const domain = type.domain;
+	if (domain === String && typeof value !== "string" || domain === Number && typeof value !== "number" || domain === Boolean && typeof value !== "boolean" || domain === BigInt && typeof value !== "bigint" || domain === Date && !(value instanceof Date)) throw new Error(`Expression values must have compatible types: expected ${describeType(type)}, got ${(0, node_util.inspect)(value)} (${typeof value})`);
+}
+/** Names the storage type, conversion domain, and entity tag involved in a codec mismatch. */
+function describeType(type) {
+	if (!type) return "unknown codec";
+	const domain = typeof type.domain === "function" ? type.domain.name : (0, node_util.inspect)(type.domain, { depth: 0 });
+	return `${type.dbType} (domain ${domain}${type.idMeta ? `, ID target ${type.idMeta.type}` : ""})`;
+}
+const compatibleStringDbTypes = /* @__PURE__ */ new Set(["text", "varchar"]);
+/** Allows PostgreSQL scalar string types that resolve to a common string result. */
+function compatibleDbTypes(a, b) {
+	return a === b || compatibleStringDbTypes.has(a) && compatibleStringDbTypes.has(b);
+}
+//#endregion
+exports.chooseExpressionCodec = chooseExpressionCodec;
+
+//# sourceMappingURL=codecs.cjs.map

package/build/queries/sql/expressions/codecs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.cjs","names":["BaseExpr","arrayOutputType","assertNever","inspect"],"sources":["../../../../src/queries/sql/expressions/codecs.ts"],"sourcesContent":["import { inspect } from \"node:util\";\n\nimport { BaseExpr } from \"src/queries/sql/Expr.ts\";\nimport type { ParsedExpression, ParsedLiteralExpression, ResultCodec } from \"src/queries/sql/expressions/types.ts\";\nimport { type TypeInfo, arrayOutputType } from \"src/serde/TypeInfo.ts\";\nimport { assertNever } from \"src/utils.ts\";\n\n/**\n * Chooses one decoder for all possible result values. Columns must agree on a compatible SQL type and domain;\n * literals use that column's encoder. This is conservative: PostgreSQL may accept other combinations,\n * but Joist cannot safely choose their decoder. I.e. Author.id and Book.id both store integers but use different tags.\n */\nexport function chooseExpressionCodec(parsed: ParsedExpression): ResultCodec {\n  const leaves = expressionLeaves(parsed);\n  const expressions = leaves.flatMap((leaf) => (\"codec\" in leaf ? [leaf.codec] : []));\n  const first = expressions[0];\n  if (first) {\n    for (const other of expressions.slice(1)) {\n      if (other === first) continue;\n      const a = first.outputType;\n      const b = other.outputType;\n      if (!a || !b || !compatibleDbTypes(a.dbType, b.dbType) || a.domain !== b.domain || a.idMeta !== b.idMeta) {\n        const mismatches =\n          !a || !b\n            ? [\"unknown codec\"]\n            : [\n                ...(!compatibleDbTypes(a.dbType, b.dbType) ? [\"SQL type\"] : []),\n                ...(a.domain !== b.domain ? [\"domain\"] : []),\n                ...(a.idMeta !== b.idMeta ? [\"ID target\"] : []),\n              ];\n        throw new Error(\n          `Expression operands need matching SQL types and codecs: ${describeType(a)} vs ${describeType(b)}; mismatched ${mismatches.join(\", \")}`,\n        );\n      }\n    }\n    for (const leaf of leaves) if (\"literal\" in leaf) checkLiteral(leaf.literal.value, first.outputType);\n    return first;\n  }\n  const literals = leaves.flatMap((leaf) => (\"literal\" in leaf ? [leaf.literal] : []));\n  const types = literals.map((v) => literalType(v.value)).filter((v) => v !== undefined);\n  for (const literal of literals) checkLiteral(literal.value, types[0]);\n  return new LiteralCodec(types[0] ?? { dbType: \"text\", domain: String });\n}\n\n/** Gives literal-only expressions a SQL type so PostgreSQL does not return numbers as text. */\nclass LiteralCodec {\n  constructor(readonly outputType: TypeInfo) {}\n\n  encode(value: unknown): unknown {\n    return value;\n  }\n\n  decode(value: unknown): unknown {\n    return this.outputType.domain === BigInt ? BigInt(value as string) : value;\n  }\n}\n\n/**\n * Finds parsed operands that share a codec, including NULLIF's comparison operand but not CASE conditions.\n * Each kind selects its own value fields; only CASE's THEN and ELSE expressions contribute a result codec.\n */\nfunction expressionLeaves(parsed: ParsedExpression): CodecLeaf[] {\n  if (parsed instanceof BaseExpr) return [{ codec: parsed }];\n  switch (parsed.kind) {\n    case \"literal\":\n      return [{ literal: parsed }];\n    case \"arrayAgg\": {\n      const valueCodec = chooseExpressionCodec(parsed.value);\n      return [\n        {\n          codec: {\n            outputType: arrayOutputType(valueCodec.outputType),\n            encode: (value) => (Array.isArray(value) ? value.map((element) => valueCodec.encode(element)) : value),\n            decode: (value) => (Array.isArray(value) ? value.map((element) => valueCodec.decode(element)) : value),\n          },\n        },\n      ];\n    }\n    case \"coalesce\":\n      return parsed.candidates.flatMap((candidate) => expressionLeaves(candidate));\n    case \"nullIf\":\n      return [...expressionLeaves(parsed.value), ...expressionLeaves(parsed.equals)];\n    case \"greatest\":\n    case \"least\":\n      return parsed.values.flatMap((value) => expressionLeaves(value));\n    case \"case\":\n      return [\n        ...parsed.whens.flatMap((entry) => expressionLeaves(entry.then)),\n        ...(parsed.else ? expressionLeaves(parsed.else) : []),\n      ];\n    default:\n      return assertNever(parsed);\n  }\n}\n\n/** One result codec or one literal that will adopt a sibling codec. */\ntype CodecLeaf = { codec: ResultCodec } | { literal: ParsedLiteralExpression };\n\n/** Supplies predictable PostgreSQL types for standalone primitive literals. */\nfunction literalType(value: unknown): TypeInfo | undefined {\n  if (value === null) return undefined;\n  if (typeof value === \"string\") return { dbType: \"text\", domain: String, arrayElementSafe: true };\n  if (typeof value === \"number\") return { dbType: \"float8\", domain: Number, arrayElementSafe: true };\n  if (typeof value === \"boolean\") return { dbType: \"bool\", domain: Boolean, arrayElementSafe: true };\n  if (typeof value === \"bigint\") return { dbType: \"int8\", domain: BigInt };\n  if (value instanceof Date) return { dbType: \"timestamptz\", domain: Date };\n  throw new Error(\"Object and array literals need an expression with a matching codec\");\n}\n\n/** Rejects primitive literals that disagree with the column; custom values are checked by their encoder. */\nfunction checkLiteral(value: unknown, type: TypeInfo | undefined): void {\n  if (value === null || !type) return;\n  const domain = type.domain;\n  if (\n    (domain === String && typeof value !== \"string\") ||\n    (domain === Number && typeof value !== \"number\") ||\n    (domain === Boolean && typeof value !== \"boolean\") ||\n    (domain === BigInt && typeof value !== \"bigint\") ||\n    (domain === Date && !(value instanceof Date))\n  ) {\n    throw new Error(\n      `Expression values must have compatible types: expected ${describeType(type)}, got ${inspect(value)} (${typeof value})`,\n    );\n  }\n}\n\n/** Names the storage type, conversion domain, and entity tag involved in a codec mismatch. */\nfunction describeType(type: TypeInfo | undefined): string {\n  if (!type) return \"unknown codec\";\n  const domain = typeof type.domain === \"function\" ? type.domain.name : inspect(type.domain, { depth: 0 });\n  return `${type.dbType} (domain ${domain}${type.idMeta ? `, ID target ${type.idMeta.type}` : \"\"})`;\n}\n\nconst compatibleStringDbTypes = new Set([\"text\", \"varchar\"]);\n\n/** Allows PostgreSQL scalar string types that resolve to a common string result. */\nfunction compatibleDbTypes(a: string, b: string): boolean {\n  return a === b || (compatibleStringDbTypes.has(a) && compatibleStringDbTypes.has(b));\n}\n"],"mappings":"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"}

package/build/queries/sql/expressions/codecs.d.cts

@@ -0,0 +1,11 @@
+import { ParsedExpression, ResultCodec } from "./types.cjs";
+//#region src/queries/sql/expressions/codecs.d.ts
+/**
+ * Chooses one decoder for all possible result values. Columns must agree on a compatible SQL type and domain;
+ * literals use that column's encoder. This is conservative: PostgreSQL may accept other combinations,
+ * but Joist cannot safely choose their decoder. I.e. Author.id and Book.id both store integers but use different tags.
+ */
+declare function chooseExpressionCodec(parsed: ParsedExpression): ResultCodec;
+//#endregion
+export { chooseExpressionCodec };
+//# sourceMappingURL=codecs.d.cts.map

package/build/queries/sql/expressions/codecs.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.cts","names":[],"sources":["../../../../src/queries/sql/expressions/codecs.ts"],"mappings":";;;;;;;iBAYgB,sBAAsB,QAAQ,mBAAmB"}

package/build/queries/sql/expressions/codecs.d.mts

@@ -0,0 +1,11 @@
+import { ParsedExpression, ResultCodec } from "./types.mjs";
+//#region src/queries/sql/expressions/codecs.d.ts
+/**
+ * Chooses one decoder for all possible result values. Columns must agree on a compatible SQL type and domain;
+ * literals use that column's encoder. This is conservative: PostgreSQL may accept other combinations,
+ * but Joist cannot safely choose their decoder. I.e. Author.id and Book.id both store integers but use different tags.
+ */
+declare function chooseExpressionCodec(parsed: ParsedExpression): ResultCodec;
+//#endregion
+export { chooseExpressionCodec };
+//# sourceMappingURL=codecs.d.mts.map

package/build/queries/sql/expressions/codecs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.mts","names":[],"sources":["../../../../src/queries/sql/expressions/codecs.ts"],"mappings":";;;;;;;iBAYgB,sBAAsB,QAAQ,mBAAmB"}