@atscript/db-sql-tools 0.1.135 → 0.1.137

package/dist/index.cjs

@@ -15,6 +15,37 @@ function finalizeParams(dialect, fragment) {
 		params: fragment.params
 	};
 }
+/**
+* How HAVING references a grouped NON-column expression (a calendar bucket, a
+* view's JSON-extracted dimension): its quoted SELECT `alias` on dialects that
+* set {@link SqlDialect.bucketAliasInHaving}, else the expression itself.
+*/
+function havingGroupRef(dialect, expr, alias) {
+	return dialect.bucketAliasInHaving ? dialect.quoteIdentifier(alias) : expr;
+}
+/**
+* Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
+* {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
+*
+* A segment containing `"`, `\` or a control character has no quoting that
+* reads the same on every dialect (SQLite's quoted path labels have no escape
+* syntax), so it is rejected rather than escaped.
+*
+* @since 0.1.136
+* @throws for an empty path or a segment that is empty or holds such a character.
+*/
+function quotedJsonPathSegments(path) {
+	if (path.length === 0) throw new Error("JSON extraction needs a path below the JSON column");
+	return path.map((seg) => {
+		let ok = seg.length > 0;
+		for (let i = 0; ok && i < seg.length; i++) {
+			const code = seg.charCodeAt(i);
+			ok = code >= 32 && code !== 34 && code !== 92;
+		}
+		if (!ok) throw new Error(`JSON path segment ${JSON.stringify(seg)} can't be extracted — segments must be non-empty and free of '"', '\\' and control characters`);
+		return `"${seg}"`;
+	});
+}
 const EMPTY_AND = {
 	sql: "1=1",
 	params: []
@@ -255,6 +286,17 @@ function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
 /**
+* The SQL string literal of a `$`-rooted JSON path with every segment quoted
+* (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
+* `json_type`.
+*
+* @since 0.1.136
+* @throws as {@link quotedJsonPathSegments}.
+*/
+function jsonDollarPath(path) {
+	return sqlStringLiteral(`$.${quotedJsonPathSegments(path).join(".")}`);
+}
+/**
 * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
 *
 * The zone is already canonical (the core normalizer ran uniqu's
@@ -324,23 +366,65 @@ const queryOpToSql = {
 	$lt: "<",
 	$lte: "<="
 };
+/** An inlined SQL literal for a view-predicate value (DDL — no parameters). */
+function predicateLiteral(value) {
+	if (value === null || value === void 0) return "NULL";
+	if (typeof value === "string") return sqlStringLiteral(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`Non-finite number ${value} in a view predicate`);
+		return String(value);
+	}
+	if (typeof value === "boolean") return value ? "true" : "false";
+	throw new Error(`Unsupported literal ${JSON.stringify(value)} in a view predicate`);
+}
 /**
 * Renders an AtscriptQueryNode tree to raw SQL (no parameters -- for DDL use only).
+*
+* Operators: `=`/`!=`/`<`/`<=`/`>`/`>=` (a `null` operand becomes `IS [NOT] NULL`),
+* `in` / `not in` (inlined literals; an empty `in` is `0=1`, an empty
+* `not in` `1=1`), `exists` → `IS NOT NULL`, `not exists` → `IS NULL`.
+*
+* @throws for `matches` (`$regex`) and any other operator — a view predicate
+*   that cannot be rendered fails at sync instead of rendering wrong SQL.
 */
 function queryNodeToSql(node, resolveFieldRef) {
-	if ("$and" in node) return node.$and.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
-	if ("$or" in node) return `(${node.$or.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+	if ("$and" in node) {
+		const children = node.$and;
+		if (children.length === 0) return EMPTY_AND.sql;
+		return children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
+	}
+	if ("$or" in node) {
+		const children = node.$or;
+		if (children.length === 0) return EMPTY_OR.sql;
+		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+	}
 	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef)})`;
 	const comp = node;
 	const leftSql = resolveFieldRef(comp.left);
-	const sqlOp = queryOpToSql[comp.op] || "=";
-	if (comp.right && typeof comp.right === "object" && "field" in comp.right) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
+	switch (comp.op) {
+		case "$exists": return comp.right === false ? `${leftSql} IS NULL` : `${leftSql} IS NOT NULL`;
+		case "$in":
+		case "$nin": {
+			const values = Array.isArray(comp.right) ? comp.right : [comp.right];
+			if (values.length === 0) return comp.op === "$in" ? EMPTY_OR.sql : EMPTY_AND.sql;
+			const list = values.map((v) => predicateLiteral(v)).join(", ");
+			return `${leftSql} ${comp.op === "$in" ? "IN" : "NOT IN"} (${list})`;
+		}
+		case "$regex": throw new Error("matches is not supported in view predicates");
+		default:
+	}
+	const sqlOp = queryOpToSql[comp.op];
+	if (!sqlOp) throw new Error(`Operator "${comp.op}" is not supported in view predicates`);
+	if ((0, _atscript_db.isFieldRef)(comp.right)) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
 	if (comp.right === null || comp.right === void 0) return comp.op === "$ne" ? `${leftSql} IS NOT NULL` : `${leftSql} IS NULL`;
-	if (typeof comp.right === "string") return `${leftSql} ${sqlOp} '${comp.right.replace(/'/g, "''")}'`;
-	return `${leftSql} ${sqlOp} ${comp.right}`;
+	return `${leftSql} ${sqlOp} ${predicateLiteral(comp.right)}`;
 }
 //#endregion
 //#region src/agg.ts
+/**
+* SQL function name of each single-name aggregate. `countDistinct` is not a
+* name but a form (`COUNT(DISTINCT x)`) — see {@link renderAggCall}.
+*/
 const AGG_FN_SQL = {
 	sum: "SUM",
 	avg: "AVG",
@@ -348,14 +432,20 @@ const AGG_FN_SQL = {
 	min: "MIN",
 	max: "MAX"
 };
-/** The SQL function for an aggregate name; throws `INVALID_QUERY` on an unsupported one. */
-function aggFnName(fn, path) {
+/**
+* Renders one aggregate call over an already-rendered argument (`*`, a quoted
+* column, a `CASE` expression): `SUM(x)`, `COUNT(DISTINCT x)`, …
+* Re-asserts the name first (`INVALID_QUERY` on an unknown one), so nothing
+* unchecked reaches SQL.
+*/
+function renderAggCall(fn, arg, path) {
 	(0, _atscript_db_agg.assertAggregateFn)(fn, path);
-	return AGG_FN_SQL[fn];
+	return fn === "countDistinct" ? `COUNT(DISTINCT ${arg})` : `${AGG_FN_SQL[fn]}(${arg})`;
 }
-/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)`. */
+/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)` / `COUNT(DISTINCT "region")`. */
 function aggFnSql(dialect, expr) {
-	return `${aggFnName(expr.$fn)}(${expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field)})`;
+	const field = expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field);
+	return renderAggCall(expr.$fn, field);
 }
 function buildAggExpr(dialect, expr) {
 	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier((0, _atscript_db_agg.resolveAlias)(expr))}`;
@@ -416,7 +506,7 @@ function groupKeySql(dialect, controls, key) {
 * not allow a SELECT alias in HAVING (MySQL and SQLite tolerate it, so the
 * expression form keeps all three identical). A calendar-bucket alias renders
 * its bucket expression ({@link groupKeySql}), or its quoted alias when the
-* dialect sets `SqlDialect.bucketAliasInHaving` (why: see there). Other keys
+* dialect sets `SqlDialect.bucketAliasInHaving` (`havingGroupRef`). Other keys
 * (grouped columns) render as plain columns.
 */
 function havingClause(dialect, controls) {
@@ -427,8 +517,8 @@ function havingClause(dialect, controls) {
 	const fragment = (0, _uniqu_core.walkFilter)(having, createFilterVisitor(dialect, { columnRef: (field) => {
 		const aggExpr = exprByAlias.get(field);
 		if (aggExpr) return aggExpr;
-		if (dialect.bucketAliasInHaving && controls.$select?.bucketByAlias(field)) return dialect.quoteIdentifier(field);
-		return groupKeySql(dialect, controls, field);
+		const bucket = controls.$select?.bucketByAlias(field);
+		return bucket ? havingGroupRef(dialect, bucketSql(dialect, bucket), field) : dialect.quoteIdentifier(field);
 	} }));
 	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
 	return {
@@ -509,6 +599,90 @@ function buildAggregateCount(dialect, table, where, controls) {
 	});
 }
 //#endregion
+//#region src/view-builder.ts
+/**
+* The SQL expression a view column reads: `"table"."column"` — the physical
+* source column resolved by `AtscriptDbView.getViewColumnMappings()` — or,
+* for a primitive leaf inside a JSON column (`mapping.json`), the dialect's
+* typed {@link SqlDialect.jsonExtract} over that column. Used for SELECT
+* columns, GROUP BY / HAVING dimensions and as an aggregate's source.
+*
+* @throws when the column reads a JSON leaf and the dialect has no `jsonExtract`.
+*/
+function viewSourceExpr(dialect, mapping) {
+	const col = `${dialect.quoteIdentifier(mapping.sourceTable)}.${dialect.quoteIdentifier(mapping.sourceColumn)}`;
+	if (!mapping.json) return col;
+	if (!dialect.jsonExtract) throw new Error(`View column "${mapping.viewColumn}": JSON extraction is not supported by this adapter`);
+	return dialect.jsonExtract(col, mapping.json.path, mapping.json.type);
+}
+/**
+* The SQL expression of one aggregate view column, e.g. `SUM("orders"."amount")`,
+* `COUNT(*)` or `COUNT(DISTINCT "orders"."customer_id")`, over
+* {@link viewSourceExpr}. The mapping's aggregate rules (`*` only for count, …)
+* are validated where the core builds it.
+*
+* A conditional aggregate (`aggFilter`, rendered with the view's predicate
+* resolver) aggregates `CASE WHEN <predicate> THEN <src> END` — NULL for the
+* rows the predicate rejects, which every aggregate skips:
+* - `COUNT(*)` → `COUNT(CASE WHEN p THEN 1 END)`;
+* - `countDistinct` → `COUNT(DISTINCT CASE WHEN p THEN src END)`;
+* - `sum` → `COALESCE(SUM(CASE WHEN p THEN src END), 0)` — a group with no
+*   matching row sums to 0, not NULL (MongoDB's `$sum` answer too);
+* - `avg` / `min` / `max` stay NULL when no row matches.
+*/
+function viewAggExpr(dialect, c, resolveFieldRef) {
+	const star = c.aggField === "*";
+	const src = star ? "*" : viewSourceExpr(dialect, c);
+	if (!c.aggFilter) return renderAggCall(c.aggFn, src, c.viewColumn);
+	const predicate = queryNodeToSql(c.aggFilter, resolveFieldRef);
+	const call = renderAggCall(c.aggFn, `CASE WHEN ${predicate} THEN ${star ? "1" : src} END`, c.viewColumn);
+	return c.aggFn === "sum" ? `COALESCE(${call}, 0)` : call;
+}
+/**
+* Builds a CREATE VIEW statement from a view plan and column mappings.
+*
+* Joins render in declaration order — `JOIN` (inner, the default) or
+* `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
+* names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
+* fallbacks) as `"table"."column"`.
+*/
+function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+	const selectCols = columns.map((c) => {
+		return `${c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
+	}).join(", ");
+	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
+	for (const join of plan.joins) {
+		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
+		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
+		sql += ` ${keyword} ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
+	}
+	if (plan.filter) {
+		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
+		sql += ` WHERE ${whereClause}`;
+	}
+	if (columns.some((c) => c.aggFn)) {
+		const dimensionCols = columns.filter((c) => !c.aggFn);
+		if (dimensionCols.length > 0) {
+			const groupByCols = dimensionCols.map((c) => viewSourceExpr(dialect, c)).join(", ");
+			sql += ` GROUP BY ${groupByCols}`;
+		}
+		if (plan.having) {
+			const columnByPath = /* @__PURE__ */ new Map();
+			for (const c of columns) columnByPath.set(c.viewPath, c);
+			const havingResolver = (ref) => {
+				const col = ref.type ? void 0 : columnByPath.get(ref.field);
+				if (!col) return resolveFieldRef(ref);
+				if (col.aggFn) return viewAggExpr(dialect, col, resolveFieldRef);
+				const expr = viewSourceExpr(dialect, col);
+				return col.json ? havingGroupRef(dialect, expr, col.viewColumn) : expr;
+			};
+			const havingClause = queryNodeToSql(plan.having, havingResolver);
+			sql += ` HAVING ${havingClause}`;
+		}
+	}
+	return sql;
+}
+//#endregion
 //#region src/sql-builder.ts
 /**
 * Builds an INSERT statement.
@@ -706,50 +880,6 @@ function buildProjection(dialect, select) {
 	}
 	return sql || "*";
 }
-/** Builds the SQL expression for a single aggregate column. */
-function buildAggColExpr(dialect, c) {
-	return `${aggFnName(c.aggFn, c.viewColumn)}(${c.aggField === "*" ? "*" : `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`})`;
-}
-/**
-* Builds a CREATE VIEW statement from a view plan and column mappings.
-*/
-function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
-	const selectCols = columns.map((c) => {
-		if (c.aggFn) return `${buildAggColExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
-		return `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
-	}).join(", ");
-	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
-	for (const join of plan.joins) {
-		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
-		sql += ` JOIN ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
-	}
-	if (plan.filter) {
-		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
-		sql += ` WHERE ${whereClause}`;
-	}
-	if (columns.some((c) => c.aggFn)) {
-		const dimensionCols = columns.filter((c) => !c.aggFn);
-		if (dimensionCols.length > 0) {
-			const groupByCols = dimensionCols.map((c) => `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`).join(", ");
-			sql += ` GROUP BY ${groupByCols}`;
-		}
-		if (plan.having) {
-			const columnMap = /* @__PURE__ */ new Map();
-			for (const c of columns) columnMap.set(c.viewColumn, c);
-			const havingResolver = (ref) => {
-				if (!ref.type) {
-					const col = columnMap.get(ref.field);
-					if (col?.aggFn) return buildAggColExpr(dialect, col);
-					if (col) return `${dialect.quoteIdentifier(col.sourceTable)}.${dialect.quoteIdentifier(col.sourceColumn)}`;
-				}
-				return resolveFieldRef(ref);
-			};
-			const havingClause = queryNodeToSql(plan.having, havingResolver);
-			sql += ` HAVING ${havingClause}`;
-		}
-	}
-	return sql;
-}
 //#endregion
 //#region src/regex.ts
 /**
@@ -801,10 +931,12 @@ exports.finalizeParams = finalizeParams;
 exports.geoWindowFromControls = geoWindowFromControls;
 exports.groupKeySql = groupKeySql;
 exports.insertManyColumns = insertManyColumns;
+exports.jsonDollarPath = jsonDollarPath;
 exports.normalizeGeoPointValue = normalizeGeoPointValue;
 exports.parseRegexString = parseRegexString;
 exports.queryNodeToSql = queryNodeToSql;
 exports.queryOpToSql = queryOpToSql;
+exports.quotedJsonPathSegments = quotedJsonPathSegments;
 exports.refActionToSql = refActionToSql;
 exports.renameGeoDistance = renameGeoDistance;
 exports.replaceColumnsFor = replaceColumnsFor;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
@@ -48,9 +48,10 @@ interface SqlDialect {
    */
   calendarBucket?(quotedCol: string, b: TResolvedBucket): string;
   /**
-   * HAVING references a calendar bucket by its quoted SELECT alias instead of
-   * re-rendering the bucket expression (the aggregate count query's inner
-   * SELECT lists `<bucket expr> AS alias`, so the alias exists there too).
+   * HAVING references a calendar bucket — and a view's JSON-extracted
+   * dimension ({@link jsonExtract}) — by its quoted SELECT alias instead of
+   * re-rendering the expression (the aggregate count query's inner SELECT
+   * lists `<bucket expr> AS alias`, so the alias exists there too).
    *
    * MySQL needs this: the bucket expression reads the raw source column, which
    * is not itself in GROUP BY (only the expression is), so HAVING rejects it
@@ -61,6 +62,27 @@ interface SqlDialect {
    * Since 0.1.132.
    */
   bucketAliasInHaving?: boolean;
+  /**
+   * Typed extraction of one primitive leaf inside a JSON column — how a view
+   * field that references a descendant of a `@db.json` column reads it.
+   *
+   * Semantics (identical on every dialect): the result is the declared
+   * primitive, or NULL when the path is missing, the value is JSON `null`, or
+   * the value has another JSON type — never a coercion (the JSON string
+   * `"5"` is NULL for a `number` leaf). Numbers come back as doubles (integers
+   * beyond 2^53 lose precision); booleans as the dialect's boolean
+   * representation (0/1 where booleans are integers).
+   *
+   * `quotedCol` is already quoted (`"table"."column"`); `path` holds the
+   * segments below it. The expression must be PARAMETER-FREE — it renders in
+   * CREATE VIEW DDL, repeated in SELECT, GROUP BY, HAVING and aggregate
+   * arguments. Quote every segment via {@link quotedJsonPathSegments}.
+   * Dialects without JSON extraction omit this; view sync then fails with
+   * `JSON extraction is not supported by this adapter`.
+   *
+   * @since 0.1.136
+   */
+  jsonExtract?(quotedCol: string, path: readonly string[], type: TViewJsonType): string;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -71,6 +93,18 @@ interface SqlDialect {
  * (e.g. `$1, $2, ...` for PostgreSQL). No-op when `dialect.paramPlaceholder` is not set.
  */
 declare function finalizeParams(dialect: SqlDialect, fragment: TSqlFragment): TSqlFragment;
+/**
+ * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
+ * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
+ *
+ * A segment containing `"`, `\` or a control character has no quoting that
+ * reads the same on every dialect (SQLite's quoted path labels have no escape
+ * syntax), so it is rejected rather than escaped.
+ *
+ * @since 0.1.136
+ * @throws for an empty path or a segment that is empty or holds such a character.
+ */
+declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 //#endregion
@@ -143,6 +177,17 @@ declare function normalizeGeoPointValue(value: unknown): [number, number] | unde
 /** Renames the internal distance alias to the public `$distance` field (in place). */
 declare function renameGeoDistance(row: Record<string, unknown>): Record<string, unknown>;
 //#endregion
+//#region src/view-builder.d.ts
+/**
+ * Builds a CREATE VIEW statement from a view plan and column mappings.
+ *
+ * Joins render in declaration order — `JOIN` (inner, the default) or
+ * `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
+ * names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
+ * fallbacks) as `"table"."column"`.
+ */
+declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+//#endregion
 //#region src/sql-builder.d.ts
 /**
  * Builds an INSERT statement.
@@ -227,14 +272,19 @@ declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFrag
  * Builds a column projection (SELECT clause fields).
  */
 declare function buildProjection(dialect: SqlDialect, select?: UniquSelect): string;
-/**
- * Builds a CREATE VIEW statement from a view plan and column mappings.
- */
-declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
 //#region src/common.d.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 declare function sqlStringLiteral(value: string): string;
+/**
+ * The SQL string literal of a `$`-rooted JSON path with every segment quoted
+ * (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
+ * `json_type`.
+ *
+ * @since 0.1.136
+ * @throws as {@link quotedJsonPathSegments}.
+ */
+declare function jsonDollarPath(path: readonly string[]): string;
 /**
  * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
  *
@@ -260,11 +310,22 @@ declare function defaultValueToSqlLiteral(designType: string, value: string): st
 declare const queryOpToSql: Record<string, string>;
 /**
  * Renders an AtscriptQueryNode tree to raw SQL (no parameters -- for DDL use only).
+ *
+ * Operators: `=`/`!=`/`<`/`<=`/`>`/`>=` (a `null` operand becomes `IS [NOT] NULL`),
+ * `in` / `not in` (inlined literals; an empty `in` is `0=1`, an empty
+ * `not in` `1=1`), `exists` → `IS NOT NULL`, `not exists` → `IS NULL`.
+ *
+ * @throws for `matches` (`$regex`) and any other operator — a view predicate
+ *   that cannot be rendered fails at sync instead of rendering wrong SQL.
  */
 declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
 //#region src/agg.d.ts
-declare const AGG_FN_SQL: Readonly<Record<TDbAggregateFn, string>>;
+/**
+ * SQL function name of each single-name aggregate. `countDistinct` is not a
+ * name but a form (`COUNT(DISTINCT x)`) — see {@link renderAggCall}.
+ */
+declare const AGG_FN_SQL: Readonly<Record<Exclude<TDbAggregateFn, "countDistinct">, string>>;
 /**
  * The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
  * bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
@@ -307,4 +368,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
 //#region src/dialect.d.ts
@@ -48,9 +48,10 @@ interface SqlDialect {
    */
   calendarBucket?(quotedCol: string, b: TResolvedBucket): string;
   /**
-   * HAVING references a calendar bucket by its quoted SELECT alias instead of
-   * re-rendering the bucket expression (the aggregate count query's inner
-   * SELECT lists `<bucket expr> AS alias`, so the alias exists there too).
+   * HAVING references a calendar bucket — and a view's JSON-extracted
+   * dimension ({@link jsonExtract}) — by its quoted SELECT alias instead of
+   * re-rendering the expression (the aggregate count query's inner SELECT
+   * lists `<bucket expr> AS alias`, so the alias exists there too).
    *
    * MySQL needs this: the bucket expression reads the raw source column, which
    * is not itself in GROUP BY (only the expression is), so HAVING rejects it
@@ -61,6 +62,27 @@ interface SqlDialect {
    * Since 0.1.132.
    */
   bucketAliasInHaving?: boolean;
+  /**
+   * Typed extraction of one primitive leaf inside a JSON column — how a view
+   * field that references a descendant of a `@db.json` column reads it.
+   *
+   * Semantics (identical on every dialect): the result is the declared
+   * primitive, or NULL when the path is missing, the value is JSON `null`, or
+   * the value has another JSON type — never a coercion (the JSON string
+   * `"5"` is NULL for a `number` leaf). Numbers come back as doubles (integers
+   * beyond 2^53 lose precision); booleans as the dialect's boolean
+   * representation (0/1 where booleans are integers).
+   *
+   * `quotedCol` is already quoted (`"table"."column"`); `path` holds the
+   * segments below it. The expression must be PARAMETER-FREE — it renders in
+   * CREATE VIEW DDL, repeated in SELECT, GROUP BY, HAVING and aggregate
+   * arguments. Quote every segment via {@link quotedJsonPathSegments}.
+   * Dialects without JSON extraction omit this; view sync then fails with
+   * `JSON extraction is not supported by this adapter`.
+   *
+   * @since 0.1.136
+   */
+  jsonExtract?(quotedCol: string, path: readonly string[], type: TViewJsonType): string;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -71,6 +93,18 @@ interface SqlDialect {
  * (e.g. `$1, $2, ...` for PostgreSQL). No-op when `dialect.paramPlaceholder` is not set.
  */
 declare function finalizeParams(dialect: SqlDialect, fragment: TSqlFragment): TSqlFragment;
+/**
+ * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
+ * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
+ *
+ * A segment containing `"`, `\` or a control character has no quoting that
+ * reads the same on every dialect (SQLite's quoted path labels have no escape
+ * syntax), so it is rejected rather than escaped.
+ *
+ * @since 0.1.136
+ * @throws for an empty path or a segment that is empty or holds such a character.
+ */
+declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 //#endregion
@@ -143,6 +177,17 @@ declare function normalizeGeoPointValue(value: unknown): [number, number] | unde
 /** Renames the internal distance alias to the public `$distance` field (in place). */
 declare function renameGeoDistance(row: Record<string, unknown>): Record<string, unknown>;
 //#endregion
+//#region src/view-builder.d.ts
+/**
+ * Builds a CREATE VIEW statement from a view plan and column mappings.
+ *
+ * Joins render in declaration order — `JOIN` (inner, the default) or
+ * `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
+ * names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
+ * fallbacks) as `"table"."column"`.
+ */
+declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+//#endregion
 //#region src/sql-builder.d.ts
 /**
  * Builds an INSERT statement.
@@ -227,14 +272,19 @@ declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFrag
  * Builds a column projection (SELECT clause fields).
  */
 declare function buildProjection(dialect: SqlDialect, select?: UniquSelect): string;
-/**
- * Builds a CREATE VIEW statement from a view plan and column mappings.
- */
-declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
 //#region src/common.d.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 declare function sqlStringLiteral(value: string): string;
+/**
+ * The SQL string literal of a `$`-rooted JSON path with every segment quoted
+ * (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
+ * `json_type`.
+ *
+ * @since 0.1.136
+ * @throws as {@link quotedJsonPathSegments}.
+ */
+declare function jsonDollarPath(path: readonly string[]): string;
 /**
  * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
  *
@@ -260,11 +310,22 @@ declare function defaultValueToSqlLiteral(designType: string, value: string): st
 declare const queryOpToSql: Record<string, string>;
 /**
  * Renders an AtscriptQueryNode tree to raw SQL (no parameters -- for DDL use only).
+ *
+ * Operators: `=`/`!=`/`<`/`<=`/`>`/`>=` (a `null` operand becomes `IS [NOT] NULL`),
+ * `in` / `not in` (inlined literals; an empty `in` is `0=1`, an empty
+ * `not in` `1=1`), `exists` → `IS NOT NULL`, `not exists` → `IS NULL`.
+ *
+ * @throws for `matches` (`$regex`) and any other operator — a view predicate
+ *   that cannot be rendered fails at sync instead of rendering wrong SQL.
  */
 declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
 //#region src/agg.d.ts
-declare const AGG_FN_SQL: Readonly<Record<TDbAggregateFn, string>>;
+/**
+ * SQL function name of each single-name aggregate. `countDistinct` is not a
+ * name but a form (`COUNT(DISTINCT x)`) — see {@link renderAggCall}.
+ */
+declare const AGG_FN_SQL: Readonly<Record<Exclude<TDbAggregateFn, "countDistinct">, string>>;
 /**
  * The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
  * bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
@@ -307,4 +368,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { BUCKET_UNITS, TIME_ZONE_NAME_RE, WEEK_STARTS, walkFilter } from "@uniqu/core";
-import { DbError } from "@atscript/db";
+import { DbError, isFieldRef } from "@atscript/db";
 import { assertAggregateFn, resolveAlias } from "@atscript/db/agg";
 //#region src/dialect.ts
 /**
@@ -14,6 +14,37 @@ function finalizeParams(dialect, fragment) {
 		params: fragment.params
 	};
 }
+/**
+* How HAVING references a grouped NON-column expression (a calendar bucket, a
+* view's JSON-extracted dimension): its quoted SELECT `alias` on dialects that
+* set {@link SqlDialect.bucketAliasInHaving}, else the expression itself.
+*/
+function havingGroupRef(dialect, expr, alias) {
+	return dialect.bucketAliasInHaving ? dialect.quoteIdentifier(alias) : expr;
+}
+/**
+* Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
+* {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
+*
+* A segment containing `"`, `\` or a control character has no quoting that
+* reads the same on every dialect (SQLite's quoted path labels have no escape
+* syntax), so it is rejected rather than escaped.
+*
+* @since 0.1.136
+* @throws for an empty path or a segment that is empty or holds such a character.
+*/
+function quotedJsonPathSegments(path) {
+	if (path.length === 0) throw new Error("JSON extraction needs a path below the JSON column");
+	return path.map((seg) => {
+		let ok = seg.length > 0;
+		for (let i = 0; ok && i < seg.length; i++) {
+			const code = seg.charCodeAt(i);
+			ok = code >= 32 && code !== 34 && code !== 92;
+		}
+		if (!ok) throw new Error(`JSON path segment ${JSON.stringify(seg)} can't be extracted — segments must be non-empty and free of '"', '\\' and control characters`);
+		return `"${seg}"`;
+	});
+}
 const EMPTY_AND = {
 	sql: "1=1",
 	params: []
@@ -254,6 +285,17 @@ function sqlStringLiteral(value) {
 	return `'${value.replace(/'/g, "''")}'`;
 }
 /**
+* The SQL string literal of a `$`-rooted JSON path with every segment quoted
+* (`'$."a"."b"'`) — the path argument of SQLite's and MySQL's `json_extract` /
+* `json_type`.
+*
+* @since 0.1.136
+* @throws as {@link quotedJsonPathSegments}.
+*/
+function jsonDollarPath(path) {
+	return sqlStringLiteral(`$.${quotedJsonPathSegments(path).join(".")}`);
+}
+/**
 * A calendar bucket's time zone as an inlined SQL string literal (`'Europe/Berlin'`).
 *
 * The zone is already canonical (the core normalizer ran uniqu's
@@ -323,23 +365,65 @@ const queryOpToSql = {
 	$lt: "<",
 	$lte: "<="
 };
+/** An inlined SQL literal for a view-predicate value (DDL — no parameters). */
+function predicateLiteral(value) {
+	if (value === null || value === void 0) return "NULL";
+	if (typeof value === "string") return sqlStringLiteral(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`Non-finite number ${value} in a view predicate`);
+		return String(value);
+	}
+	if (typeof value === "boolean") return value ? "true" : "false";
+	throw new Error(`Unsupported literal ${JSON.stringify(value)} in a view predicate`);
+}
 /**
 * Renders an AtscriptQueryNode tree to raw SQL (no parameters -- for DDL use only).
+*
+* Operators: `=`/`!=`/`<`/`<=`/`>`/`>=` (a `null` operand becomes `IS [NOT] NULL`),
+* `in` / `not in` (inlined literals; an empty `in` is `0=1`, an empty
+* `not in` `1=1`), `exists` → `IS NOT NULL`, `not exists` → `IS NULL`.
+*
+* @throws for `matches` (`$regex`) and any other operator — a view predicate
+*   that cannot be rendered fails at sync instead of rendering wrong SQL.
 */
 function queryNodeToSql(node, resolveFieldRef) {
-	if ("$and" in node) return node.$and.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
-	if ("$or" in node) return `(${node.$or.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+	if ("$and" in node) {
+		const children = node.$and;
+		if (children.length === 0) return EMPTY_AND.sql;
+		return children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" AND ");
+	}
+	if ("$or" in node) {
+		const children = node.$or;
+		if (children.length === 0) return EMPTY_OR.sql;
+		return `(${children.map((n) => queryNodeToSql(n, resolveFieldRef)).join(" OR ")})`;
+	}
 	if ("$not" in node) return `NOT (${queryNodeToSql(node.$not, resolveFieldRef)})`;
 	const comp = node;
 	const leftSql = resolveFieldRef(comp.left);
-	const sqlOp = queryOpToSql[comp.op] || "=";
-	if (comp.right && typeof comp.right === "object" && "field" in comp.right) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
+	switch (comp.op) {
+		case "$exists": return comp.right === false ? `${leftSql} IS NULL` : `${leftSql} IS NOT NULL`;
+		case "$in":
+		case "$nin": {
+			const values = Array.isArray(comp.right) ? comp.right : [comp.right];
+			if (values.length === 0) return comp.op === "$in" ? EMPTY_OR.sql : EMPTY_AND.sql;
+			const list = values.map((v) => predicateLiteral(v)).join(", ");
+			return `${leftSql} ${comp.op === "$in" ? "IN" : "NOT IN"} (${list})`;
+		}
+		case "$regex": throw new Error("matches is not supported in view predicates");
+		default:
+	}
+	const sqlOp = queryOpToSql[comp.op];
+	if (!sqlOp) throw new Error(`Operator "${comp.op}" is not supported in view predicates`);
+	if (isFieldRef(comp.right)) return `${leftSql} ${sqlOp} ${resolveFieldRef(comp.right)}`;
 	if (comp.right === null || comp.right === void 0) return comp.op === "$ne" ? `${leftSql} IS NOT NULL` : `${leftSql} IS NULL`;
-	if (typeof comp.right === "string") return `${leftSql} ${sqlOp} '${comp.right.replace(/'/g, "''")}'`;
-	return `${leftSql} ${sqlOp} ${comp.right}`;
+	return `${leftSql} ${sqlOp} ${predicateLiteral(comp.right)}`;
 }
 //#endregion
 //#region src/agg.ts
+/**
+* SQL function name of each single-name aggregate. `countDistinct` is not a
+* name but a form (`COUNT(DISTINCT x)`) — see {@link renderAggCall}.
+*/
 const AGG_FN_SQL = {
 	sum: "SUM",
 	avg: "AVG",
@@ -347,14 +431,20 @@ const AGG_FN_SQL = {
 	min: "MIN",
 	max: "MAX"
 };
-/** The SQL function for an aggregate name; throws `INVALID_QUERY` on an unsupported one. */
-function aggFnName(fn, path) {
+/**
+* Renders one aggregate call over an already-rendered argument (`*`, a quoted
+* column, a `CASE` expression): `SUM(x)`, `COUNT(DISTINCT x)`, …
+* Re-asserts the name first (`INVALID_QUERY` on an unknown one), so nothing
+* unchecked reaches SQL.
+*/
+function renderAggCall(fn, arg, path) {
 	assertAggregateFn(fn, path);
-	return AGG_FN_SQL[fn];
+	return fn === "countDistinct" ? `COUNT(DISTINCT ${arg})` : `${AGG_FN_SQL[fn]}(${arg})`;
 }
-/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)`. */
+/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)` / `COUNT(DISTINCT "region")`. */
 function aggFnSql(dialect, expr) {
-	return `${aggFnName(expr.$fn)}(${expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field)})`;
+	const field = expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field);
+	return renderAggCall(expr.$fn, field);
 }
 function buildAggExpr(dialect, expr) {
 	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier(resolveAlias(expr))}`;
@@ -415,7 +505,7 @@ function groupKeySql(dialect, controls, key) {
 * not allow a SELECT alias in HAVING (MySQL and SQLite tolerate it, so the
 * expression form keeps all three identical). A calendar-bucket alias renders
 * its bucket expression ({@link groupKeySql}), or its quoted alias when the
-* dialect sets `SqlDialect.bucketAliasInHaving` (why: see there). Other keys
+* dialect sets `SqlDialect.bucketAliasInHaving` (`havingGroupRef`). Other keys
 * (grouped columns) render as plain columns.
 */
 function havingClause(dialect, controls) {
@@ -426,8 +516,8 @@ function havingClause(dialect, controls) {
 	const fragment = walkFilter(having, createFilterVisitor(dialect, { columnRef: (field) => {
 		const aggExpr = exprByAlias.get(field);
 		if (aggExpr) return aggExpr;
-		if (dialect.bucketAliasInHaving && controls.$select?.bucketByAlias(field)) return dialect.quoteIdentifier(field);
-		return groupKeySql(dialect, controls, field);
+		const bucket = controls.$select?.bucketByAlias(field);
+		return bucket ? havingGroupRef(dialect, bucketSql(dialect, bucket), field) : dialect.quoteIdentifier(field);
 	} }));
 	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
 	return {
@@ -508,6 +598,90 @@ function buildAggregateCount(dialect, table, where, controls) {
 	});
 }
 //#endregion
+//#region src/view-builder.ts
+/**
+* The SQL expression a view column reads: `"table"."column"` — the physical
+* source column resolved by `AtscriptDbView.getViewColumnMappings()` — or,
+* for a primitive leaf inside a JSON column (`mapping.json`), the dialect's
+* typed {@link SqlDialect.jsonExtract} over that column. Used for SELECT
+* columns, GROUP BY / HAVING dimensions and as an aggregate's source.
+*
+* @throws when the column reads a JSON leaf and the dialect has no `jsonExtract`.
+*/
+function viewSourceExpr(dialect, mapping) {
+	const col = `${dialect.quoteIdentifier(mapping.sourceTable)}.${dialect.quoteIdentifier(mapping.sourceColumn)}`;
+	if (!mapping.json) return col;
+	if (!dialect.jsonExtract) throw new Error(`View column "${mapping.viewColumn}": JSON extraction is not supported by this adapter`);
+	return dialect.jsonExtract(col, mapping.json.path, mapping.json.type);
+}
+/**
+* The SQL expression of one aggregate view column, e.g. `SUM("orders"."amount")`,
+* `COUNT(*)` or `COUNT(DISTINCT "orders"."customer_id")`, over
+* {@link viewSourceExpr}. The mapping's aggregate rules (`*` only for count, …)
+* are validated where the core builds it.
+*
+* A conditional aggregate (`aggFilter`, rendered with the view's predicate
+* resolver) aggregates `CASE WHEN <predicate> THEN <src> END` — NULL for the
+* rows the predicate rejects, which every aggregate skips:
+* - `COUNT(*)` → `COUNT(CASE WHEN p THEN 1 END)`;
+* - `countDistinct` → `COUNT(DISTINCT CASE WHEN p THEN src END)`;
+* - `sum` → `COALESCE(SUM(CASE WHEN p THEN src END), 0)` — a group with no
+*   matching row sums to 0, not NULL (MongoDB's `$sum` answer too);
+* - `avg` / `min` / `max` stay NULL when no row matches.
+*/
+function viewAggExpr(dialect, c, resolveFieldRef) {
+	const star = c.aggField === "*";
+	const src = star ? "*" : viewSourceExpr(dialect, c);
+	if (!c.aggFilter) return renderAggCall(c.aggFn, src, c.viewColumn);
+	const predicate = queryNodeToSql(c.aggFilter, resolveFieldRef);
+	const call = renderAggCall(c.aggFn, `CASE WHEN ${predicate} THEN ${star ? "1" : src} END`, c.viewColumn);
+	return c.aggFn === "sum" ? `COALESCE(${call}, 0)` : call;
+}
+/**
+* Builds a CREATE VIEW statement from a view plan and column mappings.
+*
+* Joins render in declaration order — `JOIN` (inner, the default) or
+* `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
+* names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
+* fallbacks) as `"table"."column"`.
+*/
+function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+	const selectCols = columns.map((c) => {
+		return `${c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
+	}).join(", ");
+	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
+	for (const join of plan.joins) {
+		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
+		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
+		sql += ` ${keyword} ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
+	}
+	if (plan.filter) {
+		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
+		sql += ` WHERE ${whereClause}`;
+	}
+	if (columns.some((c) => c.aggFn)) {
+		const dimensionCols = columns.filter((c) => !c.aggFn);
+		if (dimensionCols.length > 0) {
+			const groupByCols = dimensionCols.map((c) => viewSourceExpr(dialect, c)).join(", ");
+			sql += ` GROUP BY ${groupByCols}`;
+		}
+		if (plan.having) {
+			const columnByPath = /* @__PURE__ */ new Map();
+			for (const c of columns) columnByPath.set(c.viewPath, c);
+			const havingResolver = (ref) => {
+				const col = ref.type ? void 0 : columnByPath.get(ref.field);
+				if (!col) return resolveFieldRef(ref);
+				if (col.aggFn) return viewAggExpr(dialect, col, resolveFieldRef);
+				const expr = viewSourceExpr(dialect, col);
+				return col.json ? havingGroupRef(dialect, expr, col.viewColumn) : expr;
+			};
+			const havingClause = queryNodeToSql(plan.having, havingResolver);
+			sql += ` HAVING ${havingClause}`;
+		}
+	}
+	return sql;
+}
+//#endregion
 //#region src/sql-builder.ts
 /**
 * Builds an INSERT statement.
@@ -705,50 +879,6 @@ function buildProjection(dialect, select) {
 	}
 	return sql || "*";
 }
-/** Builds the SQL expression for a single aggregate column. */
-function buildAggColExpr(dialect, c) {
-	return `${aggFnName(c.aggFn, c.viewColumn)}(${c.aggField === "*" ? "*" : `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`})`;
-}
-/**
-* Builds a CREATE VIEW statement from a view plan and column mappings.
-*/
-function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
-	const selectCols = columns.map((c) => {
-		if (c.aggFn) return `${buildAggColExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
-		return `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
-	}).join(", ");
-	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
-	for (const join of plan.joins) {
-		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
-		sql += ` JOIN ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
-	}
-	if (plan.filter) {
-		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
-		sql += ` WHERE ${whereClause}`;
-	}
-	if (columns.some((c) => c.aggFn)) {
-		const dimensionCols = columns.filter((c) => !c.aggFn);
-		if (dimensionCols.length > 0) {
-			const groupByCols = dimensionCols.map((c) => `${dialect.quoteIdentifier(c.sourceTable)}.${dialect.quoteIdentifier(c.sourceColumn)}`).join(", ");
-			sql += ` GROUP BY ${groupByCols}`;
-		}
-		if (plan.having) {
-			const columnMap = /* @__PURE__ */ new Map();
-			for (const c of columns) columnMap.set(c.viewColumn, c);
-			const havingResolver = (ref) => {
-				if (!ref.type) {
-					const col = columnMap.get(ref.field);
-					if (col?.aggFn) return buildAggColExpr(dialect, col);
-					if (col) return `${dialect.quoteIdentifier(col.sourceTable)}.${dialect.quoteIdentifier(col.sourceColumn)}`;
-				}
-				return resolveFieldRef(ref);
-			};
-			const havingClause = queryNodeToSql(plan.having, havingResolver);
-			sql += ` HAVING ${havingClause}`;
-		}
-	}
-	return sql;
-}
 //#endregion
 //#region src/regex.ts
 /**
@@ -775,4 +905,4 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.135",
+  "version": "0.1.137",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -42,7 +42,7 @@
   },
   "peerDependencies": {
     "@uniqu/core": "^0.1.11",
-    "@atscript/db": "^0.1.135"
+    "@atscript/db": "^0.1.137"
   },
   "scripts": {
     "build": "vp pack",