@atscript/db-sql-tools 0.1.152 → 0.1.154

package/dist/index.cjs

@@ -157,15 +157,53 @@ async function mapQueryErrors(dialect, fn, controls) {
 	}
 }
 /**
-* One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
-* `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
-* dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
-* Shared by first-row joins and `first` / `last` aggregates.
-* @since 0.1.148
+* The `$nulls` entry of one `ORDER BY` key (`controls.$nulls` is keyed like
+* `controls.$sort`), or `undefined`.
+* @since 0.1.153
+*/
+function nullsPlacementOf(nulls, key) {
+	if (!nulls) return void 0;
+	const map = nulls;
+	return Object.hasOwn(map, key) ? map[key] : void 0;
+}
+/**
+* One `ORDER BY` key with a requested NULL placement. Without `nulls`, the
+* plain `<expr> ASC|DESC` (the engine's native placement). With it:
+*
+* - the engine's native placement already matches (NULL is the smallest
+*   value — `ASC` → first, `DESC` → last — unless
+*   {@link SqlDialect.nullsSortLargest}, where it is the opposite) → the plain
+*   key, so an index on `expr` still serves the order;
+* - else `<expr> ASC|DESC NULLS FIRST|LAST` on a dialect with
+*   {@link SqlDialect.nullsPlacementSyntax} (or `nullsSortLargest`);
+* - else (MySQL) a leading NULL-ness key: `(<expr> IS NULL) DESC, <expr> DIR`
+*   for `first`, `(<expr> IS NULL) ASC, <expr> DIR` for `last`.
+*
+* May render two comma-separated keys — only valid inside an `ORDER BY` list.
+* `nullTest` renders the `IS NULL` operand when it must differ from `expr`
+* (MySQL resolves a name inside an expression to a table column before a
+* SELECT alias, so a grouped `ORDER BY` tests the alias's own expression).
+* @since 0.1.153
+*/
+function nullsOrderSql(dialect, expr, desc, nulls, nullTest) {
+	const key = `${expr} ${desc ? "DESC" : "ASC"}`;
+	if (!nulls) return key;
+	const nativeFirst = desc === (dialect.nullsSortLargest === true);
+	if (nulls === "first" === nativeFirst) return key;
+	if (dialect.nullsPlacementSyntax || dialect.nullsSortLargest) return `${key} NULLS ${nulls === "first" ? "FIRST" : "LAST"}`;
+	return `(${nullTest ? nullTest() : expr} IS NULL) ${nulls === "first" ? "DESC" : "ASC"}, ${key}`;
+}
+/**
+* One `ORDER BY` key with the uniform "NULL is the smallest value" ordering
+* (`ASC` → NULL first, `DESC` → NULL last) unless `nulls` asks for another
+* placement — {@link nullsOrderSql}. Without `nulls`: `<expr> ASC` /
+* `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a dialect where NULL
+* sorts largest ({@link SqlDialect.nullsSortLargest}). Shared by first-row
+* joins, `first` / `last` aggregates and the grouped `ORDER BY`.
+* @since 0.1.148 (`nulls` since 0.1.153)
 */
-function orderKeySql(dialect, expr, desc) {
-	const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
-	return `${expr} ${desc ? "DESC" : "ASC"}${nulls}`;
+function orderKeySql(dialect, expr, desc, nulls, nullTest) {
+	return nullsOrderSql(dialect, expr, desc, nulls ?? (desc ? "last" : "first"), nullTest);
 }
 /**
 * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
@@ -468,6 +506,16 @@ function buildWhere(dialect, filter, opts) {
 	}) : getVisitor(dialect)) ?? EMPTY_AND;
 }
 //#endregion
+//#region src/from-source.ts
+/** The FROM text of `source`: the quoted table name, or the derived table. */
+function fromSourceSql(dialect, source) {
+	return typeof source === "string" ? dialect.quoteTable(source) : source.sql;
+}
+/** The hint the SELECT directly reading `source` carries (`""` for a table). */
+function fromSourceHint(source) {
+	return typeof source === "string" ? "" : source.hint;
+}
+//#endregion
 //#region src/common.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 function sqlStringLiteral(value) {
@@ -815,17 +863,24 @@ function rowColumns(controls) {
 * WHERE moves inside unchanged, so the bind parameters keep their order.
 */
 function aggSource(dialect, table, where, controls, withRows) {
-	const quotedTable = dialect.quoteTable(table);
+	const quotedTable = fromSourceSql(dialect, table);
 	const firstLast = controls.$select?.firstLast;
 	const rowOrder = controls.$select?.rowOrder;
-	if (!withRows || !firstLast?.length || !rowOrder?.length) return `FROM ${quotedTable} WHERE ${where.sql}`;
+	if (!withRows || !firstLast?.length || !rowOrder?.length) return {
+		hint: fromSourceHint(table),
+		sql: `FROM ${quotedTable} WHERE ${where.sql}`
+	};
 	const groupBy = controls.$groupBy;
 	const partition = groupBy?.length ? `PARTITION BY ${groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ")} ` : "";
-	const order = (reverse) => rowOrder.map((k) => orderKeySql(dialect, dialect.quoteIdentifier(k.column), k.desc !== reverse)).join(", ");
-	return `FROM (SELECT ${[...rowColumns(controls).map((column) => dialect.quoteIdentifier(column)), ...firstLast.map((fl, i) => {
+	const order = (reverse) => rowOrder.map((k) => orderKeySql(dialect, dialect.quoteIdentifier(k.column), k.desc !== reverse, k.nulls && reverse ? k.nulls === "first" ? "last" : "first" : k.nulls)).join(", ");
+	const columns = [...rowColumns(controls).map((column) => dialect.quoteIdentifier(column)), ...firstLast.map((fl, i) => {
 		const col = dialect.quoteIdentifier(firstLastColumn(i));
 		return `FIRST_VALUE(${dialect.quoteIdentifier(fl.column)}) OVER (${partition}ORDER BY ${order(fl.fn === "last")}) AS ${col}`;
-	})].join(", ")} FROM ${quotedTable} WHERE ${where.sql}) AS ${dialect.quoteIdentifier(ROWS_ALIAS)}`;
+	})];
+	return {
+		hint: "",
+		sql: `FROM (SELECT ${fromSourceHint(table)}${columns.join(", ")} FROM ${quotedTable} WHERE ${where.sql}) AS ${dialect.quoteIdentifier(ROWS_ALIAS)}`
+	};
 }
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
@@ -847,7 +902,9 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		aliasSql = aliasSqlMap(dialect, controls);
 		for (const alias of select.computedAliases) selectParts.push(`${aliasSql.get(alias)} AS ${dialect.quoteIdentifier(alias)}`);
 	} else for (const expr of select?.aggregates ?? []) selectParts.push(`${aggFnSql(dialect, select, expr)} AS ${dialect.quoteIdentifier((0, _atscript_db_agg.resolveAlias)(expr))}`);
-	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} ${aggSource(dialect, table, where, controls, true)}${groupByClause(dialect, controls)}`;
+	const cols = selectParts.length > 0 ? selectParts.join(", ") : "*";
+	const source = aggSource(dialect, table, where, controls, true);
+	let sql = `SELECT ${source.hint}${cols} ${source.sql}${groupByClause(dialect, controls)}`;
 	const params = [...where.params];
 	const having = havingClause(dialect, controls, aliasSql);
 	if (having) {
@@ -855,8 +912,12 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		params.push(...having.params);
 	}
 	if (controls.$sort) {
+		const nullTest = (col) => () => {
+			aliasSql ??= aliasSqlMap(dialect, controls);
+			return aliasSql.get(col) ?? dialect.quoteIdentifier(col);
+		};
 		const orderParts = [];
-		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(orderKeySql(dialect, dialect.quoteIdentifier(col), dir === -1));
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(orderKeySql(dialect, dialect.quoteIdentifier(col), dir === -1, nullsPlacementOf(controls.$nulls, col), nullTest(col)));
 		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
 	}
 	if (controls.$limit !== void 0) {
@@ -891,7 +952,7 @@ function buildAggregateCount(dialect, table, where, controls) {
 			params: []
 		});
 		return finalizeParams(dialect, {
-			sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
+			sql: `SELECT ${fromSourceHint(table)}${countCol} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`,
 			params: where.params
 		});
 	}
@@ -900,7 +961,7 @@ function buildAggregateCount(dialect, table, where, controls) {
 	let inner = "COUNT(*)";
 	if (groupBy) inner = bucketSelectParts(dialect, controls).join(", ") || "1";
 	return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM (SELECT ${inner} ${from}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		sql: `SELECT ${countCol} FROM (SELECT ${from.hint}${inner} ${from.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
 		params: [...where.params, ...having?.params ?? []]
 	});
 }
@@ -1002,7 +1063,17 @@ function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
 	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => orderKeySql(dialect, resolveFieldRef(ref), desc)).join(", ")} LIMIT 1)`;
 }
 /**
-* Builds a CREATE VIEW statement from a view plan and column mappings.
+* Builds a CREATE VIEW statement from a view plan and column mappings:
+* `<dialect.createViewPrefix> <view> AS <buildViewSelect(…)>`.
+*/
+function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+	return `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS ${buildViewSelect(dialect, plan, columns, resolveFieldRef)}`;
+}
+/**
+* The SELECT of a managed view — the body of its CREATE VIEW, and (since
+* 0.1.153) the inline definition a pruned view read selects from (with a
+* `AtscriptDbView.readPlan` variant's plan and columns), so the two can never
+* drift. Parameter-free: predicate literals are inlined.
 *
 * Joins render in declaration order — `JOIN` (inner, the default) or
 * `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
@@ -1011,15 +1082,15 @@ function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
 * name for an aliased join); `resolveFieldRef` renders predicate refs (join
 * ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
 * join target may be views.
+* @since 0.1.153
 */
-function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+function buildViewSelect(dialect, plan, columns, resolveFieldRef) {
 	const columnByPath = new Map(columns.map((c) => [c.viewPath, c]));
 	const hasAggregates = columns.some((c) => c.aggFn);
 	const computedSql = /* @__PURE__ */ new Map();
 	/** A column's SELECT expression: computed, aggregate or plain source. */
 	const columnExpr = (c) => c.expr !== void 0 ? viewComputeExpr(dialect, c, columnByPath, resolveFieldRef, hasAggregates, computedSql) : c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c);
-	const selectCols = columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ");
-	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
+	let sql = `SELECT ${columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ")} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
 	for (const join of plan.joins) {
 		const condition = queryNodeToSql(join.condition, resolveFieldRef);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
@@ -1172,11 +1243,13 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 }
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
+* `table` may be a derived source (a pruned view read, since 0.1.153).
 */
 function buildSelect(dialect, table, where, controls) {
-	let sql = `SELECT ${buildProjection(dialect, controls?.$select)} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const cols = buildProjection(dialect, controls?.$select);
+	let sql = `SELECT ${fromSourceHint(table)}${cols} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const params = [...where.params];
-	const orderBy = orderByList(dialect, controls?.$sort);
+	const orderBy = orderByList(dialect, controls?.$sort, controls?.$nulls);
 	if (orderBy) sql += ` ORDER BY ${orderBy}`;
 	if (controls?.$limit !== void 0) {
 		sql += ` LIMIT ?`;
@@ -1192,11 +1265,17 @@ function buildSelect(dialect, table, where, controls) {
 		params
 	});
 }
-/** `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders nothing. */
-function orderByList(dialect, sort) {
+/**
+* `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
+* nothing. A key with a `$nulls` entry places NULL as asked
+* ({@link nullsOrderSql}); `prefix` is prepended verbatim to each quoted
+* column (`t.` → `t."col"`).
+* @since 0.1.153 (exported)
+*/
+function orderByList(dialect, sort, nulls, prefix = "") {
 	if (!sort) return "";
 	const parts = [];
-	for (const [col, dir] of Object.entries(sort)) parts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+	for (const [col, dir] of Object.entries(sort)) parts.push(nullsOrderSql(dialect, prefix + dialect.quoteIdentifier(col), dir === -1, nullsPlacementOf(nulls, col)));
 	return parts.join(", ");
 }
 /**
@@ -1217,9 +1296,9 @@ const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
 */
 function buildPartitionedSelect(dialect, table, where, controls, partitionBy) {
 	const rn = dialect.quoteIdentifier(PARTITION_ROW_NUMBER_ALIAS);
-	const orderBy = orderByList(dialect, controls.$sort);
+	const orderBy = orderByList(dialect, controls.$sort, controls.$nulls);
 	const window = `PARTITION BY ${partitionBy.map((col) => dialect.quoteIdentifier(col)).join(", ")}` + (orderBy ? ` ORDER BY ${orderBy}` : "");
-	const inner = `SELECT ${buildProjection(dialect, controls.$select)}, ROW_NUMBER() OVER (${window}) AS ${rn} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const inner = `SELECT ${fromSourceHint(table)}${buildProjection(dialect, controls.$select)}, ROW_NUMBER() OVER (${window}) AS ${rn} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const skip = controls.$skip ?? 0;
 	const limit = controls.$limit;
 	const params = [...where.params, skip];
@@ -1626,6 +1705,49 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
+//#region src/view-read.ts
+/** Rendered pruned definitions per read variant (variants are memoised by their view). */
+const rendered = /* @__PURE__ */ new WeakMap();
+/**
+* The FROM source of a read of `readable` (the adapter's registered table or
+* view): `tableName` unchanged, except for a managed view whose read does
+* not need some of its LEFT joins (`AtscriptDbView.readPlan` over the
+* columns `query` reads — {@link queryReadColumns}): then the view's own
+* definition without those joins ({@link buildViewSelect}), aliased as the
+* bare view name so every column reference — and the correlation of a
+* relational predicate — stays valid. A column of a dropped join is absent
+* from the derived table, so a reference the collector missed fails with
+* "unknown column" rather than reading wrong data.
+*
+* Never pruned: a table, an external view, a view read under another name
+* than its own (`tableName` schema-qualified — its definition's unqualified
+* names resolve against that schema, the derived table's against the
+* connection's — or renamed by an adapter subclass), or anything `readPlan`
+* keeps whole.
+* @since 0.1.153
+*/
+function viewReadSource(dialect, readable, tableName, query, kind, partitionBy) {
+	if (!readable.isView || tableName !== readable.tableName) return tableName;
+	const view = readable;
+	const variant = view.readPlan((0, _atscript_db.queryReadColumns)(query, kind, partitionBy));
+	if (!variant) return tableName;
+	let byDialect = rendered.get(variant);
+	if (!byDialect) {
+		byDialect = /* @__PURE__ */ new Map();
+		rendered.set(variant, byDialect);
+	}
+	let source = byDialect.get(dialect);
+	if (!source) {
+		const qi = (name) => dialect.quoteIdentifier(name);
+		source = {
+			sql: `(${buildViewSelect(dialect, variant.plan, variant.columns, (ref) => view.resolveFieldRef(ref, qi))}) AS ${qi(readable.tableName)}`,
+			hint: dialect.derivedMergeHint ? `${dialect.derivedMergeHint(readable.tableName)} ` : ""
+		};
+		byDialect.set(dialect, source);
+	}
+	return source;
+}
+//#endregion
 exports.AGG_FN_SQL = AGG_FN_SQL;
 exports.EMPTY_AND = EMPTY_AND;
 exports.EMPTY_OR = EMPTY_OR;
@@ -1650,6 +1772,7 @@ exports.buildSelect = buildSelect;
 exports.buildUpdate = buildUpdate;
 exports.buildVectorSearchCount = buildVectorSearchCount;
 exports.buildVectorSearchSelect = buildVectorSearchSelect;
+exports.buildViewSelect = buildViewSelect;
 exports.buildWhere = buildWhere;
 exports.chunkInsertRows = chunkInsertRows;
 exports.createFilterVisitor = createFilterVisitor;
@@ -1659,14 +1782,19 @@ exports.derivedColumnExpr = derivedColumnExpr;
 exports.fillReplacePayload = fillReplacePayload;
 exports.finalizeParams = finalizeParams;
 exports.foreignKeySql = foreignKeySql;
+exports.fromSourceHint = fromSourceHint;
+exports.fromSourceSql = fromSourceSql;
 exports.geoWindowFromControls = geoWindowFromControls;
 exports.groupKeySql = groupKeySql;
 exports.insertManyColumns = insertManyColumns;
 exports.jsonDollarPath = jsonDollarPath;
 exports.mapQueryErrors = mapQueryErrors;
 exports.normalizeGeoPointValue = normalizeGeoPointValue;
+exports.nullsOrderSql = nullsOrderSql;
+exports.nullsPlacementOf = nullsPlacementOf;
 exports.numericOutOfRangeError = numericOutOfRangeError;
 exports.orFragment = orFragment;
+exports.orderByList = orderByList;
 exports.orderKeySql = orderKeySql;
 exports.parseRegexString = parseRegexString;
 exports.queryNodeToSql = queryNodeToSql;
@@ -1681,3 +1809,4 @@ exports.sqlTimeZoneLiteral = sqlTimeZoneLiteral;
 exports.stripPartitionRowNumber = stripPartitionRowNumber;
 exports.toSqlValue = toSqlValue;
 exports.vectorDistanceSource = vectorDistanceSource;
+exports.viewReadSource = viewReadSource;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
-import { FilterExpr, FilterVisitor } from "@uniqu/core";
+import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, DbQuery, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TReadColumnsKind, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
+import { FilterExpr, FilterVisitor, NullsPlacement } from "@uniqu/core";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
 //#region src/dialect.d.ts
@@ -19,6 +19,14 @@ interface SqlDialect {
   quoteTable(name: string): string;
   /** SQL literal for unlimited LIMIT (SQLite: '-1', MySQL: '18446744073709551615') */
   unlimitedLimit: string;
+  /**
+   * The optimizer hint asking the engine to MERGE the derived table `alias`
+   * into the SELECT reading it (MySQL: `/*+ MERGE(\`alias\`) *\/`) — carried
+   * by pruned view reads (`viewReadSource`), so the inline definition merges
+   * even in a session with `derived_merge=off`. Omitted: no hint.
+   * @since 0.1.153
+   */
+  derivedMergeHint?(alias: string): string;
   /** Convert JS value to SQL-bindable param for DML */
   toValue(value: unknown): unknown;
   /** Convert JS value to SQL-bindable param for filters (lighter) */
@@ -142,6 +150,14 @@ interface SqlDialect {
    * @since 0.1.147
    */
   nullsSortLargest?: boolean;
+  /**
+   * `true` when the engine accepts `NULLS FIRST` / `NULLS LAST` on an
+   * `ORDER BY` key (PostgreSQL, SQLite ≥ 3.30). Without it a requested NULL
+   * placement that differs from the native one renders as an extra
+   * `(<expr> IS NULL)` key ({@link nullsOrderSql}).
+   * @since 0.1.153
+   */
+  nullsPlacementSyntax?: boolean;
   /** 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. */
@@ -169,13 +185,41 @@ declare function finalizeParams(dialect: SqlDialect, fragment: TSqlFragment): TS
  */
 declare function mapQueryErrors<R>(dialect: SqlDialect, fn: () => Promise<R>, controls?: DbControls): Promise<R>;
 /**
- * One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
- * `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
- * dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
- * Shared by first-row joins and `first` / `last` aggregates.
- * @since 0.1.148
+ * The `$nulls` entry of one `ORDER BY` key (`controls.$nulls` is keyed like
+ * `controls.$sort`), or `undefined`.
+ * @since 0.1.153
+ */
+declare function nullsPlacementOf(nulls: DbControls["$nulls"], key: string): NullsPlacement | undefined;
+/**
+ * One `ORDER BY` key with a requested NULL placement. Without `nulls`, the
+ * plain `<expr> ASC|DESC` (the engine's native placement). With it:
+ *
+ * - the engine's native placement already matches (NULL is the smallest
+ *   value — `ASC` → first, `DESC` → last — unless
+ *   {@link SqlDialect.nullsSortLargest}, where it is the opposite) → the plain
+ *   key, so an index on `expr` still serves the order;
+ * - else `<expr> ASC|DESC NULLS FIRST|LAST` on a dialect with
+ *   {@link SqlDialect.nullsPlacementSyntax} (or `nullsSortLargest`);
+ * - else (MySQL) a leading NULL-ness key: `(<expr> IS NULL) DESC, <expr> DIR`
+ *   for `first`, `(<expr> IS NULL) ASC, <expr> DIR` for `last`.
+ *
+ * May render two comma-separated keys — only valid inside an `ORDER BY` list.
+ * `nullTest` renders the `IS NULL` operand when it must differ from `expr`
+ * (MySQL resolves a name inside an expression to a table column before a
+ * SELECT alias, so a grouped `ORDER BY` tests the alias's own expression).
+ * @since 0.1.153
+ */
+declare function nullsOrderSql(dialect: SqlDialect, expr: string, desc: boolean, nulls?: NullsPlacement, nullTest?: () => string): string;
+/**
+ * One `ORDER BY` key with the uniform "NULL is the smallest value" ordering
+ * (`ASC` → NULL first, `DESC` → NULL last) unless `nulls` asks for another
+ * placement — {@link nullsOrderSql}. Without `nulls`: `<expr> ASC` /
+ * `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a dialect where NULL
+ * sorts largest ({@link SqlDialect.nullsSortLargest}). Shared by first-row
+ * joins, `first` / `last` aggregates and the grouped `ORDER BY`.
+ * @since 0.1.148 (`nulls` since 0.1.153)
  */
-declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean): string;
+declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean, nulls?: NullsPlacement, nullTest?: () => string): string;
 /**
  * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
  * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
@@ -394,9 +438,39 @@ declare function buildVectorSearchCount(dialect: SqlDialect, source: TSqlFragmen
   residual?: TSqlFragment;
 }): TSqlFragment;
 //#endregion
+//#region src/from-source.d.ts
+/**
+ * A pre-rendered derived table — `(<select>) AS "alias"` — read in place of
+ * a table name, plus the optimizer hint the SELECT that reads it carries
+ * (`/*+ MERGE(…) *\/ `, or `""`).
+ * @since 0.1.153
+ */
+interface TSqlDerivedSource {
+  readonly sql: string;
+  readonly hint: string;
+}
+/**
+ * The FROM source of a read builder: a table / view name (quoted by the
+ * dialect) or a {@link TSqlDerivedSource}.
+ * @since 0.1.153
+ */
+type TSqlFromSource = string | TSqlDerivedSource;
+/** The FROM text of `source`: the quoted table name, or the derived table. */
+declare function fromSourceSql(dialect: SqlDialect, source: TSqlFromSource): string;
+/** The hint the SELECT directly reading `source` carries (`""` for a table). */
+declare function fromSourceHint(source: TSqlFromSource): string;
+//#endregion
 //#region src/view-builder.d.ts
 /**
- * Builds a CREATE VIEW statement from a view plan and column mappings.
+ * Builds a CREATE VIEW statement from a view plan and column mappings:
+ * `<dialect.createViewPrefix> <view> AS <buildViewSelect(…)>`.
+ */
+declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+/**
+ * The SELECT of a managed view — the body of its CREATE VIEW, and (since
+ * 0.1.153) the inline definition a pruned view read selects from (with a
+ * `AtscriptDbView.readPlan` variant's plan and columns), so the two can never
+ * drift. Parameter-free: predicate literals are inlined.
  *
  * Joins render in declaration order — `JOIN` (inner, the default) or
  * `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
@@ -405,8 +479,9 @@ declare function buildVectorSearchCount(dialect: SqlDialect, source: TSqlFragmen
  * name for an aliased join); `resolveFieldRef` renders predicate refs (join
  * ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
  * join target may be views.
+ * @since 0.1.153
  */
-declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+declare function buildViewSelect(dialect: SqlDialect, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
 //#region src/sql-builder.d.ts
 /**
@@ -456,8 +531,17 @@ declare function chunkInsertRows(rows: readonly Record<string, unknown>[], maxPa
 declare function buildInsertMany(dialect: SqlDialect, table: string, rows: readonly Record<string, unknown>[], columns?: readonly string[]): TSqlFragment;
 /**
  * Builds a SELECT statement with optional sort, limit, offset, projection.
+ * `table` may be a derived source (a pruned view read, since 0.1.153).
  */
-declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
+ * nothing. A key with a `$nulls` entry places NULL as asked
+ * ({@link nullsOrderSql}); `prefix` is prepended verbatim to each quoted
+ * column (`t.` → `t."col"`).
+ * @since 0.1.153 (exported)
+ */
+declare function orderByList(dialect: SqlDialect, sort: DbControls["$sort"], nulls?: DbControls["$nulls"], prefix?: string): string;
 /**
  * The row-number column {@link buildPartitionedSelect} adds to every row;
  * {@link stripPartitionRowNumber} removes it from the result rows.
@@ -474,7 +558,7 @@ declare const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
  * SQLite ≥ 3.25, MySQL ≥ 8.0 or MariaDB ≥ 10.2.
  * @since 0.1.147
  */
-declare function buildPartitionedSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
+declare function buildPartitionedSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
 /** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
 declare function stripPartitionRowNumber<R extends Record<string, unknown>>(rows: R[]): R[];
 /**
@@ -641,7 +725,7 @@ declare function groupKeySql(dialect: SqlDialect, controls: DbControls, key: str
  * parameter-free, so the bind parameters are exactly those of the same query
  * without buckets (WHERE, HAVING, LIMIT, OFFSET).
  */
-declare function buildAggregateSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
+declare function buildAggregateSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls: DbControls): TSqlFragment;
 /**
  * Builds a COUNT query for the number of distinct groups — the groups that
  * survive `$having` when one is given (the same predicate the row query
@@ -650,7 +734,7 @@ declare function buildAggregateSelect(dialect: SqlDialect, table: string, where:
  * `first` / `last` value (or an expression over one): only then the window
  * derived table is built.
  */
-declare function buildAggregateCount(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
+declare function buildAggregateCount(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls: DbControls): TSqlFragment;
 //#endregion
 //#region src/regex.d.ts
 /**
@@ -665,4 +749,30 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+//#region src/view-read.d.ts
+/** The structural view surface {@link viewReadSource} needs from an adapter's readable. */
+interface TReadableLike {
+  readonly isView: boolean;
+  readonly tableName: string;
+}
+/**
+ * The FROM source of a read of `readable` (the adapter's registered table or
+ * view): `tableName` unchanged, except for a managed view whose read does
+ * not need some of its LEFT joins (`AtscriptDbView.readPlan` over the
+ * columns `query` reads — {@link queryReadColumns}): then the view's own
+ * definition without those joins ({@link buildViewSelect}), aliased as the
+ * bare view name so every column reference — and the correlation of a
+ * relational predicate — stays valid. A column of a dropped join is absent
+ * from the derived table, so a reference the collector missed fails with
+ * "unknown column" rather than reading wrong data.
+ *
+ * Never pruned: a table, an external view, a view read under another name
+ * than its own (`tableName` schema-qualified — its definition's unqualified
+ * names resolve against that schema, the derived table's against the
+ * connection's — or renamed by an adapter subclass), or anything `readPlan`
+ * keeps whole.
+ * @since 0.1.153
+ */
+declare function viewReadSource(dialect: SqlDialect, readable: TReadableLike, tableName: string, query: DbQuery, kind: TReadColumnsKind, partitionBy?: readonly string[]): TSqlFromSource;
+//#endregion
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
-import { FilterExpr, FilterVisitor } from "@uniqu/core";
+import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, DbQuery, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TReadColumnsKind, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
+import { FilterExpr, FilterVisitor, NullsPlacement } from "@uniqu/core";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
 //#region src/dialect.d.ts
@@ -19,6 +19,14 @@ interface SqlDialect {
   quoteTable(name: string): string;
   /** SQL literal for unlimited LIMIT (SQLite: '-1', MySQL: '18446744073709551615') */
   unlimitedLimit: string;
+  /**
+   * The optimizer hint asking the engine to MERGE the derived table `alias`
+   * into the SELECT reading it (MySQL: `/*+ MERGE(\`alias\`) *\/`) — carried
+   * by pruned view reads (`viewReadSource`), so the inline definition merges
+   * even in a session with `derived_merge=off`. Omitted: no hint.
+   * @since 0.1.153
+   */
+  derivedMergeHint?(alias: string): string;
   /** Convert JS value to SQL-bindable param for DML */
   toValue(value: unknown): unknown;
   /** Convert JS value to SQL-bindable param for filters (lighter) */
@@ -142,6 +150,14 @@ interface SqlDialect {
    * @since 0.1.147
    */
   nullsSortLargest?: boolean;
+  /**
+   * `true` when the engine accepts `NULLS FIRST` / `NULLS LAST` on an
+   * `ORDER BY` key (PostgreSQL, SQLite ≥ 3.30). Without it a requested NULL
+   * placement that differs from the native one renders as an extra
+   * `(<expr> IS NULL)` key ({@link nullsOrderSql}).
+   * @since 0.1.153
+   */
+  nullsPlacementSyntax?: boolean;
   /** 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. */
@@ -169,13 +185,41 @@ declare function finalizeParams(dialect: SqlDialect, fragment: TSqlFragment): TS
  */
 declare function mapQueryErrors<R>(dialect: SqlDialect, fn: () => Promise<R>, controls?: DbControls): Promise<R>;
 /**
- * One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
- * `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
- * dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
- * Shared by first-row joins and `first` / `last` aggregates.
- * @since 0.1.148
+ * The `$nulls` entry of one `ORDER BY` key (`controls.$nulls` is keyed like
+ * `controls.$sort`), or `undefined`.
+ * @since 0.1.153
+ */
+declare function nullsPlacementOf(nulls: DbControls["$nulls"], key: string): NullsPlacement | undefined;
+/**
+ * One `ORDER BY` key with a requested NULL placement. Without `nulls`, the
+ * plain `<expr> ASC|DESC` (the engine's native placement). With it:
+ *
+ * - the engine's native placement already matches (NULL is the smallest
+ *   value — `ASC` → first, `DESC` → last — unless
+ *   {@link SqlDialect.nullsSortLargest}, where it is the opposite) → the plain
+ *   key, so an index on `expr` still serves the order;
+ * - else `<expr> ASC|DESC NULLS FIRST|LAST` on a dialect with
+ *   {@link SqlDialect.nullsPlacementSyntax} (or `nullsSortLargest`);
+ * - else (MySQL) a leading NULL-ness key: `(<expr> IS NULL) DESC, <expr> DIR`
+ *   for `first`, `(<expr> IS NULL) ASC, <expr> DIR` for `last`.
+ *
+ * May render two comma-separated keys — only valid inside an `ORDER BY` list.
+ * `nullTest` renders the `IS NULL` operand when it must differ from `expr`
+ * (MySQL resolves a name inside an expression to a table column before a
+ * SELECT alias, so a grouped `ORDER BY` tests the alias's own expression).
+ * @since 0.1.153
+ */
+declare function nullsOrderSql(dialect: SqlDialect, expr: string, desc: boolean, nulls?: NullsPlacement, nullTest?: () => string): string;
+/**
+ * One `ORDER BY` key with the uniform "NULL is the smallest value" ordering
+ * (`ASC` → NULL first, `DESC` → NULL last) unless `nulls` asks for another
+ * placement — {@link nullsOrderSql}. Without `nulls`: `<expr> ASC` /
+ * `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a dialect where NULL
+ * sorts largest ({@link SqlDialect.nullsSortLargest}). Shared by first-row
+ * joins, `first` / `last` aggregates and the grouped `ORDER BY`.
+ * @since 0.1.148 (`nulls` since 0.1.153)
  */
-declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean): string;
+declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean, nulls?: NullsPlacement, nullTest?: () => string): string;
 /**
  * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
  * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
@@ -394,9 +438,39 @@ declare function buildVectorSearchCount(dialect: SqlDialect, source: TSqlFragmen
   residual?: TSqlFragment;
 }): TSqlFragment;
 //#endregion
+//#region src/from-source.d.ts
+/**
+ * A pre-rendered derived table — `(<select>) AS "alias"` — read in place of
+ * a table name, plus the optimizer hint the SELECT that reads it carries
+ * (`/*+ MERGE(…) *\/ `, or `""`).
+ * @since 0.1.153
+ */
+interface TSqlDerivedSource {
+  readonly sql: string;
+  readonly hint: string;
+}
+/**
+ * The FROM source of a read builder: a table / view name (quoted by the
+ * dialect) or a {@link TSqlDerivedSource}.
+ * @since 0.1.153
+ */
+type TSqlFromSource = string | TSqlDerivedSource;
+/** The FROM text of `source`: the quoted table name, or the derived table. */
+declare function fromSourceSql(dialect: SqlDialect, source: TSqlFromSource): string;
+/** The hint the SELECT directly reading `source` carries (`""` for a table). */
+declare function fromSourceHint(source: TSqlFromSource): string;
+//#endregion
 //#region src/view-builder.d.ts
 /**
- * Builds a CREATE VIEW statement from a view plan and column mappings.
+ * Builds a CREATE VIEW statement from a view plan and column mappings:
+ * `<dialect.createViewPrefix> <view> AS <buildViewSelect(…)>`.
+ */
+declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+/**
+ * The SELECT of a managed view — the body of its CREATE VIEW, and (since
+ * 0.1.153) the inline definition a pruned view read selects from (with a
+ * `AtscriptDbView.readPlan` variant's plan and columns), so the two can never
+ * drift. Parameter-free: predicate literals are inlined.
  *
  * Joins render in declaration order — `JOIN` (inner, the default) or
  * `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
@@ -405,8 +479,9 @@ declare function buildVectorSearchCount(dialect: SqlDialect, source: TSqlFragmen
  * name for an aliased join); `resolveFieldRef` renders predicate refs (join
  * ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
  * join target may be views.
+ * @since 0.1.153
  */
-declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
+declare function buildViewSelect(dialect: SqlDialect, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
 //#region src/sql-builder.d.ts
 /**
@@ -456,8 +531,17 @@ declare function chunkInsertRows(rows: readonly Record<string, unknown>[], maxPa
 declare function buildInsertMany(dialect: SqlDialect, table: string, rows: readonly Record<string, unknown>[], columns?: readonly string[]): TSqlFragment;
 /**
  * Builds a SELECT statement with optional sort, limit, offset, projection.
+ * `table` may be a derived source (a pruned view read, since 0.1.153).
  */
-declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
+ * nothing. A key with a `$nulls` entry places NULL as asked
+ * ({@link nullsOrderSql}); `prefix` is prepended verbatim to each quoted
+ * column (`t.` → `t."col"`).
+ * @since 0.1.153 (exported)
+ */
+declare function orderByList(dialect: SqlDialect, sort: DbControls["$sort"], nulls?: DbControls["$nulls"], prefix?: string): string;
 /**
  * The row-number column {@link buildPartitionedSelect} adds to every row;
  * {@link stripPartitionRowNumber} removes it from the result rows.
@@ -474,7 +558,7 @@ declare const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
  * SQLite ≥ 3.25, MySQL ≥ 8.0 or MariaDB ≥ 10.2.
  * @since 0.1.147
  */
-declare function buildPartitionedSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
+declare function buildPartitionedSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
 /** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
 declare function stripPartitionRowNumber<R extends Record<string, unknown>>(rows: R[]): R[];
 /**
@@ -641,7 +725,7 @@ declare function groupKeySql(dialect: SqlDialect, controls: DbControls, key: str
  * parameter-free, so the bind parameters are exactly those of the same query
  * without buckets (WHERE, HAVING, LIMIT, OFFSET).
  */
-declare function buildAggregateSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
+declare function buildAggregateSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls: DbControls): TSqlFragment;
 /**
  * Builds a COUNT query for the number of distinct groups — the groups that
  * survive `$having` when one is given (the same predicate the row query
@@ -650,7 +734,7 @@ declare function buildAggregateSelect(dialect: SqlDialect, table: string, where:
  * `first` / `last` value (or an expression over one): only then the window
  * derived table is built.
  */
-declare function buildAggregateCount(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
+declare function buildAggregateCount(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls: DbControls): TSqlFragment;
 //#endregion
 //#region src/regex.d.ts
 /**
@@ -665,4 +749,30 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+//#region src/view-read.d.ts
+/** The structural view surface {@link viewReadSource} needs from an adapter's readable. */
+interface TReadableLike {
+  readonly isView: boolean;
+  readonly tableName: string;
+}
+/**
+ * The FROM source of a read of `readable` (the adapter's registered table or
+ * view): `tableName` unchanged, except for a managed view whose read does
+ * not need some of its LEFT joins (`AtscriptDbView.readPlan` over the
+ * columns `query` reads — {@link queryReadColumns}): then the view's own
+ * definition without those joins ({@link buildViewSelect}), aliased as the
+ * bare view name so every column reference — and the correlation of a
+ * relational predicate — stays valid. A column of a dropped join is absent
+ * from the derived table, so a reference the collector missed fails with
+ * "unknown column" rather than reading wrong data.
+ *
+ * Never pruned: a table, an external view, a view read under another name
+ * than its own (`tableName` schema-qualified — its definition's unqualified
+ * names resolve against that schema, the derived table's against the
+ * connection's — or renamed by an adapter subclass), or anything `readPlan`
+ * keeps whole.
+ * @since 0.1.153
+ */
+declare function viewReadSource(dialect: SqlDialect, readable: TReadableLike, tableName: string, query: DbQuery, kind: TReadColumnsKind, partitionBy?: readonly string[]): TSqlFromSource;
+//#endregion
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { DbError, INTEGER_REGEX_OP, aggregateExpressionsNotSupported, containsRelationFilter, fkColumns, isFieldRef, isResolvedRelationFilter } from "@atscript/db";
+import { DbError, INTEGER_REGEX_OP, aggregateExpressionsNotSupported, containsRelationFilter, fkColumns, isFieldRef, isResolvedRelationFilter, queryReadColumns } from "@atscript/db";
 import { BUCKET_UNITS, TIME_ZONE_NAME_RE, WEEK_STARTS, walkFilter } from "@uniqu/core";
 import { assertAggregateFn, resolveAlias } from "@atscript/db/agg";
 //#region src/dialect.ts
@@ -156,15 +156,53 @@ async function mapQueryErrors(dialect, fn, controls) {
 	}
 }
 /**
-* One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
-* `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
-* dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
-* Shared by first-row joins and `first` / `last` aggregates.
-* @since 0.1.148
+* The `$nulls` entry of one `ORDER BY` key (`controls.$nulls` is keyed like
+* `controls.$sort`), or `undefined`.
+* @since 0.1.153
+*/
+function nullsPlacementOf(nulls, key) {
+	if (!nulls) return void 0;
+	const map = nulls;
+	return Object.hasOwn(map, key) ? map[key] : void 0;
+}
+/**
+* One `ORDER BY` key with a requested NULL placement. Without `nulls`, the
+* plain `<expr> ASC|DESC` (the engine's native placement). With it:
+*
+* - the engine's native placement already matches (NULL is the smallest
+*   value — `ASC` → first, `DESC` → last — unless
+*   {@link SqlDialect.nullsSortLargest}, where it is the opposite) → the plain
+*   key, so an index on `expr` still serves the order;
+* - else `<expr> ASC|DESC NULLS FIRST|LAST` on a dialect with
+*   {@link SqlDialect.nullsPlacementSyntax} (or `nullsSortLargest`);
+* - else (MySQL) a leading NULL-ness key: `(<expr> IS NULL) DESC, <expr> DIR`
+*   for `first`, `(<expr> IS NULL) ASC, <expr> DIR` for `last`.
+*
+* May render two comma-separated keys — only valid inside an `ORDER BY` list.
+* `nullTest` renders the `IS NULL` operand when it must differ from `expr`
+* (MySQL resolves a name inside an expression to a table column before a
+* SELECT alias, so a grouped `ORDER BY` tests the alias's own expression).
+* @since 0.1.153
+*/
+function nullsOrderSql(dialect, expr, desc, nulls, nullTest) {
+	const key = `${expr} ${desc ? "DESC" : "ASC"}`;
+	if (!nulls) return key;
+	const nativeFirst = desc === (dialect.nullsSortLargest === true);
+	if (nulls === "first" === nativeFirst) return key;
+	if (dialect.nullsPlacementSyntax || dialect.nullsSortLargest) return `${key} NULLS ${nulls === "first" ? "FIRST" : "LAST"}`;
+	return `(${nullTest ? nullTest() : expr} IS NULL) ${nulls === "first" ? "DESC" : "ASC"}, ${key}`;
+}
+/**
+* One `ORDER BY` key with the uniform "NULL is the smallest value" ordering
+* (`ASC` → NULL first, `DESC` → NULL last) unless `nulls` asks for another
+* placement — {@link nullsOrderSql}. Without `nulls`: `<expr> ASC` /
+* `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a dialect where NULL
+* sorts largest ({@link SqlDialect.nullsSortLargest}). Shared by first-row
+* joins, `first` / `last` aggregates and the grouped `ORDER BY`.
+* @since 0.1.148 (`nulls` since 0.1.153)
 */
-function orderKeySql(dialect, expr, desc) {
-	const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
-	return `${expr} ${desc ? "DESC" : "ASC"}${nulls}`;
+function orderKeySql(dialect, expr, desc, nulls, nullTest) {
+	return nullsOrderSql(dialect, expr, desc, nulls ?? (desc ? "last" : "first"), nullTest);
 }
 /**
 * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
@@ -467,6 +505,16 @@ function buildWhere(dialect, filter, opts) {
 	}) : getVisitor(dialect)) ?? EMPTY_AND;
 }
 //#endregion
+//#region src/from-source.ts
+/** The FROM text of `source`: the quoted table name, or the derived table. */
+function fromSourceSql(dialect, source) {
+	return typeof source === "string" ? dialect.quoteTable(source) : source.sql;
+}
+/** The hint the SELECT directly reading `source` carries (`""` for a table). */
+function fromSourceHint(source) {
+	return typeof source === "string" ? "" : source.hint;
+}
+//#endregion
 //#region src/common.ts
 /** Formats a string value as a SQL literal with single-quote escaping. */
 function sqlStringLiteral(value) {
@@ -814,17 +862,24 @@ function rowColumns(controls) {
 * WHERE moves inside unchanged, so the bind parameters keep their order.
 */
 function aggSource(dialect, table, where, controls, withRows) {
-	const quotedTable = dialect.quoteTable(table);
+	const quotedTable = fromSourceSql(dialect, table);
 	const firstLast = controls.$select?.firstLast;
 	const rowOrder = controls.$select?.rowOrder;
-	if (!withRows || !firstLast?.length || !rowOrder?.length) return `FROM ${quotedTable} WHERE ${where.sql}`;
+	if (!withRows || !firstLast?.length || !rowOrder?.length) return {
+		hint: fromSourceHint(table),
+		sql: `FROM ${quotedTable} WHERE ${where.sql}`
+	};
 	const groupBy = controls.$groupBy;
 	const partition = groupBy?.length ? `PARTITION BY ${groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ")} ` : "";
-	const order = (reverse) => rowOrder.map((k) => orderKeySql(dialect, dialect.quoteIdentifier(k.column), k.desc !== reverse)).join(", ");
-	return `FROM (SELECT ${[...rowColumns(controls).map((column) => dialect.quoteIdentifier(column)), ...firstLast.map((fl, i) => {
+	const order = (reverse) => rowOrder.map((k) => orderKeySql(dialect, dialect.quoteIdentifier(k.column), k.desc !== reverse, k.nulls && reverse ? k.nulls === "first" ? "last" : "first" : k.nulls)).join(", ");
+	const columns = [...rowColumns(controls).map((column) => dialect.quoteIdentifier(column)), ...firstLast.map((fl, i) => {
 		const col = dialect.quoteIdentifier(firstLastColumn(i));
 		return `FIRST_VALUE(${dialect.quoteIdentifier(fl.column)}) OVER (${partition}ORDER BY ${order(fl.fn === "last")}) AS ${col}`;
-	})].join(", ")} FROM ${quotedTable} WHERE ${where.sql}) AS ${dialect.quoteIdentifier(ROWS_ALIAS)}`;
+	})];
+	return {
+		hint: "",
+		sql: `FROM (SELECT ${fromSourceHint(table)}${columns.join(", ")} FROM ${quotedTable} WHERE ${where.sql}) AS ${dialect.quoteIdentifier(ROWS_ALIAS)}`
+	};
 }
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
@@ -846,7 +901,9 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		aliasSql = aliasSqlMap(dialect, controls);
 		for (const alias of select.computedAliases) selectParts.push(`${aliasSql.get(alias)} AS ${dialect.quoteIdentifier(alias)}`);
 	} else for (const expr of select?.aggregates ?? []) selectParts.push(`${aggFnSql(dialect, select, expr)} AS ${dialect.quoteIdentifier(resolveAlias(expr))}`);
-	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} ${aggSource(dialect, table, where, controls, true)}${groupByClause(dialect, controls)}`;
+	const cols = selectParts.length > 0 ? selectParts.join(", ") : "*";
+	const source = aggSource(dialect, table, where, controls, true);
+	let sql = `SELECT ${source.hint}${cols} ${source.sql}${groupByClause(dialect, controls)}`;
 	const params = [...where.params];
 	const having = havingClause(dialect, controls, aliasSql);
 	if (having) {
@@ -854,8 +911,12 @@ function buildAggregateSelect(dialect, table, where, controls) {
 		params.push(...having.params);
 	}
 	if (controls.$sort) {
+		const nullTest = (col) => () => {
+			aliasSql ??= aliasSqlMap(dialect, controls);
+			return aliasSql.get(col) ?? dialect.quoteIdentifier(col);
+		};
 		const orderParts = [];
-		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(orderKeySql(dialect, dialect.quoteIdentifier(col), dir === -1));
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(orderKeySql(dialect, dialect.quoteIdentifier(col), dir === -1, nullsPlacementOf(controls.$nulls, col), nullTest(col)));
 		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
 	}
 	if (controls.$limit !== void 0) {
@@ -890,7 +951,7 @@ function buildAggregateCount(dialect, table, where, controls) {
 			params: []
 		});
 		return finalizeParams(dialect, {
-			sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
+			sql: `SELECT ${fromSourceHint(table)}${countCol} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`,
 			params: where.params
 		});
 	}
@@ -899,7 +960,7 @@ function buildAggregateCount(dialect, table, where, controls) {
 	let inner = "COUNT(*)";
 	if (groupBy) inner = bucketSelectParts(dialect, controls).join(", ") || "1";
 	return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM (SELECT ${inner} ${from}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		sql: `SELECT ${countCol} FROM (SELECT ${from.hint}${inner} ${from.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
 		params: [...where.params, ...having?.params ?? []]
 	});
 }
@@ -1001,7 +1062,17 @@ function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
 	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => orderKeySql(dialect, resolveFieldRef(ref), desc)).join(", ")} LIMIT 1)`;
 }
 /**
-* Builds a CREATE VIEW statement from a view plan and column mappings.
+* Builds a CREATE VIEW statement from a view plan and column mappings:
+* `<dialect.createViewPrefix> <view> AS <buildViewSelect(…)>`.
+*/
+function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+	return `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS ${buildViewSelect(dialect, plan, columns, resolveFieldRef)}`;
+}
+/**
+* The SELECT of a managed view — the body of its CREATE VIEW, and (since
+* 0.1.153) the inline definition a pruned view read selects from (with a
+* `AtscriptDbView.readPlan` variant's plan and columns), so the two can never
+* drift. Parameter-free: predicate literals are inlined.
 *
 * Joins render in declaration order — `JOIN` (inner, the default) or
 * `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
@@ -1010,15 +1081,15 @@ function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
 * name for an aliased join); `resolveFieldRef` renders predicate refs (join
 * ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
 * join target may be views.
+* @since 0.1.153
 */
-function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
+function buildViewSelect(dialect, plan, columns, resolveFieldRef) {
 	const columnByPath = new Map(columns.map((c) => [c.viewPath, c]));
 	const hasAggregates = columns.some((c) => c.aggFn);
 	const computedSql = /* @__PURE__ */ new Map();
 	/** A column's SELECT expression: computed, aggregate or plain source. */
 	const columnExpr = (c) => c.expr !== void 0 ? viewComputeExpr(dialect, c, columnByPath, resolveFieldRef, hasAggregates, computedSql) : c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c);
-	const selectCols = columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ");
-	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
+	let sql = `SELECT ${columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ")} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
 	for (const join of plan.joins) {
 		const condition = queryNodeToSql(join.condition, resolveFieldRef);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
@@ -1171,11 +1242,13 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 }
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
+* `table` may be a derived source (a pruned view read, since 0.1.153).
 */
 function buildSelect(dialect, table, where, controls) {
-	let sql = `SELECT ${buildProjection(dialect, controls?.$select)} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const cols = buildProjection(dialect, controls?.$select);
+	let sql = `SELECT ${fromSourceHint(table)}${cols} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const params = [...where.params];
-	const orderBy = orderByList(dialect, controls?.$sort);
+	const orderBy = orderByList(dialect, controls?.$sort, controls?.$nulls);
 	if (orderBy) sql += ` ORDER BY ${orderBy}`;
 	if (controls?.$limit !== void 0) {
 		sql += ` LIMIT ?`;
@@ -1191,11 +1264,17 @@ function buildSelect(dialect, table, where, controls) {
 		params
 	});
 }
-/** `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders nothing. */
-function orderByList(dialect, sort) {
+/**
+* `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders
+* nothing. A key with a `$nulls` entry places NULL as asked
+* ({@link nullsOrderSql}); `prefix` is prepended verbatim to each quoted
+* column (`t.` → `t."col"`).
+* @since 0.1.153 (exported)
+*/
+function orderByList(dialect, sort, nulls, prefix = "") {
 	if (!sort) return "";
 	const parts = [];
-	for (const [col, dir] of Object.entries(sort)) parts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+	for (const [col, dir] of Object.entries(sort)) parts.push(nullsOrderSql(dialect, prefix + dialect.quoteIdentifier(col), dir === -1, nullsPlacementOf(nulls, col)));
 	return parts.join(", ");
 }
 /**
@@ -1216,9 +1295,9 @@ const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
 */
 function buildPartitionedSelect(dialect, table, where, controls, partitionBy) {
 	const rn = dialect.quoteIdentifier(PARTITION_ROW_NUMBER_ALIAS);
-	const orderBy = orderByList(dialect, controls.$sort);
+	const orderBy = orderByList(dialect, controls.$sort, controls.$nulls);
 	const window = `PARTITION BY ${partitionBy.map((col) => dialect.quoteIdentifier(col)).join(", ")}` + (orderBy ? ` ORDER BY ${orderBy}` : "");
-	const inner = `SELECT ${buildProjection(dialect, controls.$select)}, ROW_NUMBER() OVER (${window}) AS ${rn} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const inner = `SELECT ${fromSourceHint(table)}${buildProjection(dialect, controls.$select)}, ROW_NUMBER() OVER (${window}) AS ${rn} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const skip = controls.$skip ?? 0;
 	const limit = controls.$limit;
 	const params = [...where.params, skip];
@@ -1625,4 +1704,47 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+//#region src/view-read.ts
+/** Rendered pruned definitions per read variant (variants are memoised by their view). */
+const rendered = /* @__PURE__ */ new WeakMap();
+/**
+* The FROM source of a read of `readable` (the adapter's registered table or
+* view): `tableName` unchanged, except for a managed view whose read does
+* not need some of its LEFT joins (`AtscriptDbView.readPlan` over the
+* columns `query` reads — {@link queryReadColumns}): then the view's own
+* definition without those joins ({@link buildViewSelect}), aliased as the
+* bare view name so every column reference — and the correlation of a
+* relational predicate — stays valid. A column of a dropped join is absent
+* from the derived table, so a reference the collector missed fails with
+* "unknown column" rather than reading wrong data.
+*
+* Never pruned: a table, an external view, a view read under another name
+* than its own (`tableName` schema-qualified — its definition's unqualified
+* names resolve against that schema, the derived table's against the
+* connection's — or renamed by an adapter subclass), or anything `readPlan`
+* keeps whole.
+* @since 0.1.153
+*/
+function viewReadSource(dialect, readable, tableName, query, kind, partitionBy) {
+	if (!readable.isView || tableName !== readable.tableName) return tableName;
+	const view = readable;
+	const variant = view.readPlan(queryReadColumns(query, kind, partitionBy));
+	if (!variant) return tableName;
+	let byDialect = rendered.get(variant);
+	if (!byDialect) {
+		byDialect = /* @__PURE__ */ new Map();
+		rendered.set(variant, byDialect);
+	}
+	let source = byDialect.get(dialect);
+	if (!source) {
+		const qi = (name) => dialect.quoteIdentifier(name);
+		source = {
+			sql: `(${buildViewSelect(dialect, variant.plan, variant.columns, (ref) => view.resolveFieldRef(ref, qi))}) AS ${qi(readable.tableName)}`,
+			hint: dialect.derivedMergeHint ? `${dialect.derivedMergeHint(readable.tableName)} ` : ""
+		};
+		byDialect.set(dialect, source);
+	}
+	return source;
+}
+//#endregion
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.152",
+  "version": "0.1.154",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -37,12 +37,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@uniqu/core": "^0.1.14",
-    "unplugin-atscript": "^0.1.102"
+    "@uniqu/core": "^0.1.15",
+    "unplugin-atscript": "^0.1.103"
   },
   "peerDependencies": {
-    "@uniqu/core": "^0.1.14",
-    "@atscript/db": "^0.1.152"
+    "@uniqu/core": "^0.1.15",
+    "@atscript/db": "^0.1.154"
   },
   "scripts": {
     "build": "vp pack",