@atscript/db 0.1.151 → 0.1.153

package/dist/{db-error-DRQH4sLY.cjs → db-error-JcfJqqpk.cjs}

@@ -1,4 +1,10 @@
 //#region src/db-error.ts
+/** Codes whose operation may succeed when the whole transaction is retried. */
+const RETRYABLE_CODES = new Set([
+	"DEADLOCK",
+	"LOCK_TIMEOUT",
+	"SERIALIZATION_FAILURE"
+]);
 var DbError = class extends Error {
 	code;
 	errors;
@@ -9,7 +15,24 @@ var DbError = class extends Error {
 		this.errors = errors;
 		this.stack = void 0;
 	}
+	/**
+	* `true` when retrying the whole transaction may succeed — a transient
+	* concurrency condition (`DEADLOCK`, `LOCK_TIMEOUT`,
+	* `SERIALIZATION_FAILURE`), not a fault of the
+	* request. @since 0.1.153
+	*/
+	get retryable() {
+		return RETRYABLE_CODES.has(this.code);
+	}
 };
+/**
+* Whether `error` is a retryable `DbError` (`DEADLOCK` / `LOCK_TIMEOUT` /
+* `SERIALIZATION_FAILURE`):
+* re-running the whole transaction may succeed. @since 0.1.153
+*/
+function isRetryableDbError(error) {
+	return error instanceof DbError && error.retryable;
+}
 /** Whether `error` is a `DbError` with code `CONFLICT` (unique / primary-key violation). */
 function isConflict(error) {
 	return error instanceof DbError && error.code === "CONFLICT";
@@ -163,6 +186,12 @@ Object.defineProperty(exports, "isConflict", {
 		return isConflict;
 	}
 });
+Object.defineProperty(exports, "isRetryableDbError", {
+	enumerable: true,
+	get: function() {
+		return isRetryableDbError;
+	}
+});
 Object.defineProperty(exports, "spaceClosedError", {
 	enumerable: true,
 	get: function() {

package/dist/{db-error-Az85UhTX.mjs → db-error-eSsQX7rt.mjs}

@@ -1,4 +1,10 @@
 //#region src/db-error.ts
+/** Codes whose operation may succeed when the whole transaction is retried. */
+const RETRYABLE_CODES = new Set([
+	"DEADLOCK",
+	"LOCK_TIMEOUT",
+	"SERIALIZATION_FAILURE"
+]);
 var DbError = class extends Error {
 	code;
 	errors;
@@ -9,7 +15,24 @@ var DbError = class extends Error {
 		this.errors = errors;
 		this.stack = void 0;
 	}
+	/**
+	* `true` when retrying the whole transaction may succeed — a transient
+	* concurrency condition (`DEADLOCK`, `LOCK_TIMEOUT`,
+	* `SERIALIZATION_FAILURE`), not a fault of the
+	* request. @since 0.1.153
+	*/
+	get retryable() {
+		return RETRYABLE_CODES.has(this.code);
+	}
 };
+/**
+* Whether `error` is a retryable `DbError` (`DEADLOCK` / `LOCK_TIMEOUT` /
+* `SERIALIZATION_FAILURE`):
+* re-running the whole transaction may succeed. @since 0.1.153
+*/
+function isRetryableDbError(error) {
+	return error instanceof DbError && error.retryable;
+}
 /** Whether `error` is a `DbError` with code `CONFLICT` (unique / primary-key violation). */
 function isConflict(error) {
 	return error instanceof DbError && error.code === "CONFLICT";
@@ -115,4 +138,4 @@ function aggregateExpressionsNotSupported() {
 	}]);
 }
 //#endregion
-export { aggregateExpressionsNotSupported as a, isConflict as c, DepthLimitExceededError as i, spaceClosedError as l, CasMismatchError as n, aggregateFailure as o, DbError as r, bucketTimeZoneUnavailable as s, CasExhaustedError as t };
+export { aggregateExpressionsNotSupported as a, isConflict as c, DepthLimitExceededError as i, isRetryableDbError as l, CasMismatchError as n, aggregateFailure as o, DbError as r, bucketTimeZoneUnavailable as s, CasExhaustedError as t, spaceClosedError as u };

package/dist/{fk-diff-Bw26lwSc.d.cts → fk-diff-BIJ8l_hF.d.mts}

@@ -1,4 +1,4 @@
-import { B as TDbDefaultValue, H as TDbFieldMeta, R as TDbCollation, U as TDbForeignKey, _t as TExistingTableOption, bn as AtscriptDbReadable, cn as AtscriptQueryFieldRef, en as AtscriptDbView, ht as TExistingColumn, k as TColumnDiff, ln as AtscriptQueryNode, pt as TDerivedColumn, rt as TDbStorageType } from "./buckets-tzd8iIM2.cjs";
+import { A as TColumnDiff, Cn as AtscriptDbReadable, U as TDbFieldMeta, V as TDbDefaultValue, W as TDbForeignKey, _t as TExistingColumn, at as TDbStorageType, dn as AtscriptQueryFieldRef, fn as AtscriptQueryNode, ht as TDerivedColumn, nn as AtscriptDbView, yt as TExistingTableOption, z as TDbCollation } from "./buckets-CBKL_ZWE.mjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {

package/dist/{fk-diff-lcAnwvm9.d.mts → fk-diff-D1mrLMjU.d.cts}

@@ -1,4 +1,4 @@
-import { B as TDbDefaultValue, H as TDbFieldMeta, R as TDbCollation, U as TDbForeignKey, _t as TExistingTableOption, bn as AtscriptDbReadable, cn as AtscriptQueryFieldRef, en as AtscriptDbView, ht as TExistingColumn, k as TColumnDiff, ln as AtscriptQueryNode, pt as TDerivedColumn, rt as TDbStorageType } from "./buckets-Cb0zmhDc.mjs";
+import { A as TColumnDiff, Cn as AtscriptDbReadable, U as TDbFieldMeta, V as TDbDefaultValue, W as TDbForeignKey, _t as TExistingColumn, at as TDbStorageType, dn as AtscriptQueryFieldRef, fn as AtscriptQueryNode, ht as TDerivedColumn, nn as AtscriptDbView, yt as TExistingTableOption, z as TDbCollation } from "./buckets-jy8BfswO.cjs";
 
 //#region src/schema/schema-hash.d.ts
 interface TFieldSnapshot {

package/dist/index.cjs

@@ -1,13 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DRQH4sLY.cjs");
-const require_column_diff = require("./column-diff-CU7KHj9-.cjs");
-const require_aggregate_fns = require("./aggregate-fns-C-UJRobm.cjs");
-const require_nested_writer = require("./nested-writer-BzbOPSUp.cjs");
+const require_db_error = require("./db-error-JcfJqqpk.cjs");
+const require_column_diff = require("./column-diff-CbdWi_uZ.cjs");
+const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
+const require_nested_writer = require("./nested-writer-Bl1SZS7x.cjs");
 const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-UcuJxHNT.cjs");
+const require_validator = require("./validator-BxWwh3wf.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
 let node_crypto = require("node:crypto");
@@ -204,6 +204,92 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 	throw new require_db_error.CasExhaustedError(maxAttempts, lastSeenVersion);
 }
 //#endregion
+//#region src/query/read-columns.ts
+/** Logical connectives whose operands are sub-filters. */
+const CONNECTIVES = new Set([
+	"$and",
+	"$or",
+	"$nor"
+]);
+/**
+* Adds every PHYSICAL column a translated filter reads to `out`: comparison
+* keys, and — for a resolved relational predicate (`$some` / `$none`) — the
+* source-side columns it correlates on. Returns `false` when the filter holds
+* a top-level operator this walker does not know (then every column must be
+* assumed read).
+*/
+function collectFilter(filter, out) {
+	if (!filter || typeof filter !== "object") return true;
+	for (const [key, value] of Object.entries(filter)) {
+		if (CONNECTIVES.has(key)) {
+			if (!Array.isArray(value)) return false;
+			for (const child of value) if (!collectFilter(child, out)) return false;
+			continue;
+		}
+		if (key === "$not") {
+			if (!collectFilter(value, out)) return false;
+			continue;
+		}
+		if (key.startsWith("$")) return false;
+		out.add(key);
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			for (const operand of Object.values(value)) if (require_nested_writer.isResolvedRelationFilter(operand)) {
+				for (const pair of operand.pairs) out.add(pair.source);
+				for (const pair of operand.junction?.toSource ?? []) out.add(pair.source);
+			} else if (operand && typeof operand === "object" && "$field" in operand) {
+				const other = operand.$field;
+				if (typeof other !== "string") return false;
+				out.add(other);
+			}
+		}
+	}
+	return true;
+}
+/**
+* The PHYSICAL columns of the queried table (or view) that a read of `kind`
+* renders — filter keys and relational-predicate correlation columns, sort
+* keys, `partitionBy`, the projection, and for an aggregate the group keys,
+* bucket / aggregate / expression / `first`-`last` sources and `$having`
+* keys. Names that are not columns (aggregate aliases) may be included — a
+* consumer ignores names it does not know.
+*
+* `undefined` means EVERY column: the read projects all columns (no
+* `$select`, so `SELECT *`), or its filter holds an operator this collector
+* does not recognise. A view read may drop a left join only when no returned
+* column reads it, so over-inclusion is always safe.
+* @since 0.1.153
+*/
+function queryReadColumns(query, kind, partitionBy) {
+	const out = /* @__PURE__ */ new Set();
+	if (!collectFilter(query.filter, out)) return void 0;
+	if (kind === "count") return out;
+	const controls = query.controls ?? {};
+	for (const key of Object.keys(controls.$sort ?? {})) out.add(key);
+	for (const key of Object.keys(controls.$nulls ?? {})) out.add(key);
+	for (const column of partitionBy ?? []) out.add(column);
+	const select = controls.$select;
+	const fields = select?.asArray;
+	if (kind === "rows") {
+		if (!fields || fields.length === 0) return void 0;
+		for (const field of fields) out.add(field);
+		return out;
+	}
+	const groupBy = controls.$groupBy ?? [];
+	const computed = select?.computedAliases.length ?? 0;
+	if (!fields?.length && !select?.buckets?.length && computed === 0) return;
+	for (const field of fields ?? []) out.add(field);
+	for (const key of groupBy) out.add(key);
+	for (const bucket of select?.buckets ?? []) out.add(bucket.field);
+	for (const expr of select?.aggregates ?? []) if (expr.$field !== "*") out.add(expr.$field);
+	for (const e of select?.exprAggregates ?? []) for (const name of e.names) out.add(name);
+	for (const e of select?.exprs ?? []) for (const name of e.names) out.add(name);
+	for (const fl of select?.firstLast ?? []) out.add(fl.column);
+	for (const key of select?.rowOrder ?? []) out.add(key.column);
+	for (const column of select?.sources.keys() ?? []) out.add(column);
+	if (controls.$having && !collectFilter(controls.$having, out)) return void 0;
+	return out;
+}
+//#endregion
 //#region src/table/db-space.ts
 /**
 * A `@db.alias` type only names a join scope inside a view definition — it
@@ -588,12 +674,14 @@ Object.defineProperty(exports, "isRelationOp", {
 	}
 });
 exports.isResolvedRelationFilter = require_nested_writer.isResolvedRelationFilter;
+exports.isRetryableDbError = require_db_error.isRetryableDbError;
 exports.isVersionExemptPatch = require_column_diff.isVersionExemptPatch;
 exports.isViewType = require_column_diff.isViewType;
 exports.jsonValueAncestor = require_column_diff.jsonValueAncestor;
 exports.narrowerFilterOps = require_column_diff.narrowerFilterOps;
 exports.normalizeComputedSelect = require_column_diff.normalizeComputedSelect;
 exports.numericOperandProblem = require_column_diff.numericOperandProblem;
+exports.queryReadColumns = queryReadColumns;
 exports.reconcileCas = require_ops.reconcileCas;
 exports.relationStaticFilter = require_nested_writer.relationStaticFilter;
 exports.resolveCalendarBuckets = require_column_diff.resolveCalendarBuckets;

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import { $ as TDbReferentialAction, $t as TDbSpaceOptions, A as TCrudOp, An as andFilters, At as TRowResolveOptions, B as TDbDefaultValue, Bn as TReadControls, Bt as TypedWithRelation, C as NavPropsOf, Cn as REL_FILTER_MAX_DEPTH, Ct as TIdentification, D as TCascadeResolver, Dn as TRelationFilterJunction, Dt as TPrimaryKeyChange, E as PrimaryKeyOf, En as TRelGuardState, Et as TMetadataOverrides, F as TDbActionProcessor, Fn as relationStaticFilter, Ft as TTouchManyOptions, G as TDbIndexField, Gn as TRowOrderKey, Gt as isGeoIndexableType, H as TDbFieldMeta, Hn as TGenericLogger, Ht as UniqueryControls, I as TDbActionTargetSummary, In as DbEncryption, It as TValueFormatterPair, J as TDbInsertIgnoreSlot, Jt as ALL_VIEW_CAPABILITIES, K as TDbIndexType, Kn as UniquSelect, Kt as isGeoPointType, L as TDbAvailableActions, Ln as TDbEncryptionOptions, Lt as TViewJsonType, M as TDbActionInfo, Mn as forEachResolvedRelation, Mt as TSyncColumnResult, N as TDbActionIntent, Nn as hasRelationOp, Nt as TTableOptionDiff, O as TCascadeTarget, On as TRelationFilterTable, Ot as TReferencingForeignKey, P as TDbActionLevel, Pn as isResolvedRelationFilter, Pt as TTableResolver, Q as TDbObjectKind, Qt as TAdapterFactory, R as TDbCollation, Rn as DocumentFieldMapper, Rt as TWriteOptions, S as FlatOf, Sn as resolveDesignType, St as TIdResolveOptions, T as OwnPropsOf, Tn as ResolvedRelationFilter, Tt as TMetaResponse, U as TDbForeignKey, Un as TExprAggregate, Ut as WithRelation, V as TDbDeleteResult, Vn as NoopLogger, Vt as Uniquery, W as TDbIndex, Wn as TFirstLast, Wt as TableMetadata, X as TDbInsertManyResult, Xt as TViewCapability, Y as TDbInsertManyIgnoreResult, Yt as BaseDbAdapter, Z as TDbInsertResult, Zt as DbSpace, _ as DbPatch, _n as IntegrityStrategy, _t as TExistingTableOption, a as isJsonValueField, an as AtscriptExprNode, at as TDbUpdateResult, b as FieldOpsFor, bn as AtscriptDbReadable, bt as TFkLookupTarget, c as resolveCalendarBuckets, cn as AtscriptQueryFieldRef, ct as TDbWriteCheckContext, d as AggregateFn, dn as TViewJoin, dt as TDeleteOptions, en as AtscriptDbView, et as TDbRelation, f as AggregateQuery, fn as TViewPlan, ft as TDerivedChangeReason, g as DbControls, gn as AtscriptDbTable, gt as TExistingForeignKey, h as AtscriptDbWritable, hn as translateQueryTree, ht as TExistingColumn, i as isBucketableField, in as aliasTargetOf, it as TDbUpdateOptions, j as TCrudPermissions, jn as containsRelationFilter, jt as TSearchIndexInfo, k as TColumnDiff, kn as TRelationStaticFilter, kt as TRelationInfo, l as AggregateControls, ln as AtscriptQueryNode, lt as TDbWriteGuard, mn as isFieldRef, mt as TEnsureTableOptions, n as TComputedSelect, nn as isAtscriptDbView, nt as TDbRemoveGuardContext, o as jsonValueAncestor, on as AtscriptOrderItem, ot as TDbWriteAction, p as AggregateResult, pn as evaluateExpr, pt as TDerivedColumn, q as TDbInsertIgnoreResult, qt as ALL_BUCKET_UNITS, r as TResolvedBucket, rn as isViewType, rt as TDbStorageType, s as normalizeComputedSelect, sn as AtscriptQueryComparison, st as TDbWriteCheck, t as TBucketFieldSource, tn as TViewColumnMapping, tt as TDbRemoveGuard, u as AggregateExpr, un as AtscriptRef, ut as TDbWriteGuardContext, v as DbQuery, vn as NativeIntegrity, vt as TFieldMeta, w as NullableOptional, wn as REL_FILTER_MAX_NODES, wt as TInsertOptions, x as FilterExpr, xn as DbResponse, xt as TIdDescriptor, y as DbRow, yn as TCascadePin, yt as TFkLookupResolver, z as TDbDefaultFn, zn as FieldMappingStrategy, zt as TWriteTableResolver } from "./buckets-tzd8iIM2.cjs";
+import { $ as TDbInsertResult, $t as DbSpace, A as TColumnDiff, An as TRelationFilterJunction, At as TReferencingForeignKey, B as TDbDefaultFn, Bn as TDbEncryptionOptions, Bt as TWriteOptions, C as NavPropsOf, Cn as AtscriptDbReadable, Ct as TIdDescriptor, D as PrimaryKeyOf, Dn as REL_FILTER_MAX_NODES, Dt as TMetaResponse, E as OwnPropsOf, En as REL_FILTER_MAX_DEPTH, Et as TInsertOptions, F as TDbActionLevel, Fn as forEachResolvedRelation, Ft as TTableOptionDiff, G as TDbIndex, Gn as TGenericLogger, Gt as WithRelation, H as TDbDeleteResult, Hn as FieldMappingStrategy, Ht as TypedWithRelation, I as TDbActionProcessor, In as hasRelationOp, It as TTableResolver, J as TDbInsertIgnoreOptions, Jn as TRowOrderKey, Jt as isGeoPointType, K as TDbIndexField, Kn as TExprAggregate, Kt as TableMetadata, L as TDbActionTargetSummary, Ln as isResolvedRelationFilter, Lt as TTouchManyOptions, M as TCrudPermissions, Mn as TRelationStaticFilter, Mt as TRowResolveOptions, N as TDbActionInfo, Nn as andFilters, Nt as TSearchIndexInfo, O as TCascadeResolver, On as ResolvedRelationFilter, Ot as TMetadataOverrides, P as TDbActionIntent, Pn as containsRelationFilter, Pt as TSyncColumnResult, Q as TDbInsertManyResult, Qt as TViewCapability, R as TDbAvailableActions, Rn as relationStaticFilter, Rt as TValueFormatterPair, S as FlatOf, Sn as TCascadePin, St as TFkLookupTarget, T as NullsPlacement, Tn as resolveDesignType, Tt as TIdentification, U as TDbFieldMeta, Un as TReadControls, Ut as Uniquery, V as TDbDefaultValue, Vn as DocumentFieldMapper, Vt as TWriteTableResolver, W as TDbForeignKey, Wn as NoopLogger, Wt as UniqueryControls, X as TDbInsertIgnoreSlot, Xt as ALL_VIEW_CAPABILITIES, Y as TDbInsertIgnoreResult, Yn as UniquSelect, Yt as ALL_BUCKET_UNITS, Z as TDbInsertManyIgnoreResult, Zt as BaseDbAdapter, _ as DbPatch, _n as isFieldRef, _t as TExistingColumn, a as isJsonValueField, an as isViewType, at as TDbStorageType, b as FieldOpsFor, bn as IntegrityStrategy, bt as TFieldMeta, c as resolveCalendarBuckets, cn as AtscriptExprNode, ct as TDbWriteAction, d as AggregateFn, dn as AtscriptQueryFieldRef, dt as TDbWriteGuard, en as TAdapterFactory, et as TDbObjectKind, f as AggregateQuery, fn as AtscriptQueryNode, ft as TDbWriteGuardContext, g as DbControls, gn as evaluateExpr, gt as TEnsureTableOptions, h as AtscriptDbWritable, hn as TViewPlan, ht as TDerivedColumn, i as isBucketableField, in as isAtscriptDbView, it as TDbRemoveGuardContext, j as TCrudOp, jn as TRelationFilterTable, jt as TRelationInfo, k as TCascadeTarget, kn as TRelGuardState, kt as TPrimaryKeyChange, l as AggregateControls, ln as AtscriptOrderItem, lt as TDbWriteCheck, mn as TViewJoin, mt as TDerivedChangeReason, n as TComputedSelect, nn as AtscriptDbView, nt as TDbRelation, o as jsonValueAncestor, on as TViewReadPlan, ot as TDbUpdateOptions, p as AggregateResult, pn as AtscriptRef, pt as TDeleteOptions, q as TDbIndexType, qn as TFirstLast, qt as isGeoIndexableType, r as TResolvedBucket, rn as TViewColumnMapping, rt as TDbRemoveGuard, s as normalizeComputedSelect, sn as aliasTargetOf, st as TDbUpdateResult, t as TBucketFieldSource, tn as TDbSpaceOptions, tt as TDbReferentialAction, u as AggregateExpr, un as AtscriptQueryComparison, ut as TDbWriteCheckContext, v as DbQuery, vn as translateQueryTree, vt as TExistingForeignKey, w as NullableOptional, wn as DbResponse, wt as TIdResolveOptions, x as FilterExpr, xn as NativeIntegrity, xt as TFkLookupResolver, y as DbRow, yn as AtscriptDbTable, yt as TExistingTableOption, z as TDbCollation, zn as DbEncryption, zt as TViewJsonType } from "./buckets-jy8BfswO.cjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-CtPYTIvy.cjs";
 import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-42CSpGDR.cjs";
-import { _ as aggregateFailure, a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-tBNvM1qc.cjs";
+import { _ as aggregateFailure, a as buildValidationContext, b as isRetryableDbError, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-B3xlbrWf.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-Bw26lwSc.cjs";
-import { i as tableNameOf } from "./relation-helpers-DxIZKvnJ.cjs";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-D1mrLMjU.cjs";
+import { i as tableNameOf } from "./relation-helpers-D_8bydc2.cjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedRowOrderKey, ResolvedSelectExpr, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 import { AtscriptExprNode as AtscriptExprNode$1, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
@@ -149,6 +149,7 @@ interface TGuardedQuery {
     $groupBy?: unknown;
     $having?: unknown;
     $rowOrder?: unknown;
+    $nulls?: unknown;
   };
 }
 /**
@@ -563,6 +564,29 @@ declare function searchMemberKind(type: TAtscriptAnnotatedType | undefined): TSe
   problem: string;
 };
 //#endregion
+//#region src/query/read-columns.d.ts
+/**
+ * What a read renders: rows (`findOne` / `findMany` / per-partition pages),
+ * a row count, or an aggregate (`aggregate`, with or without `$count`).
+ * @since 0.1.153
+ */
+type TReadColumnsKind = "rows" | "count" | "aggregate";
+/**
+ * The PHYSICAL columns of the queried table (or view) that a read of `kind`
+ * renders — filter keys and relational-predicate correlation columns, sort
+ * keys, `partitionBy`, the projection, and for an aggregate the group keys,
+ * bucket / aggregate / expression / `first`-`last` sources and `$having`
+ * keys. Names that are not columns (aggregate aliases) may be included — a
+ * consumer ignores names it does not know.
+ *
+ * `undefined` means EVERY column: the read projects all columns (no
+ * `$select`, so `SELECT *`), or its filter holds an operator this collector
+ * does not recognise. A view read may drop a left join only when no returned
+ * column reads it, so over-inclusion is always safe.
+ * @since 0.1.153
+ */
+declare function queryReadColumns(query: DbQuery, kind: TReadColumnsKind, partitionBy?: readonly string[]): Set<string> | undefined;
+//#endregion
 //#region src/patch/patch-decomposer.d.ts
 /**
  * Decomposes a patch payload into a flat update object for adapters
@@ -662,4 +686,4 @@ declare function createFailureCollector(what: string): {
  */
 declare function numericOperandProblem(fd: TDbFieldMeta): string | undefined;
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type NullsPlacement, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertIgnoreOptions, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadColumnsKind, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TViewReadPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { $ as TDbReferentialAction, $t as TDbSpaceOptions, A as TCrudOp, An as andFilters, At as TRowResolveOptions, B as TDbDefaultValue, Bn as TReadControls, Bt as TypedWithRelation, C as NavPropsOf, Cn as REL_FILTER_MAX_DEPTH, Ct as TIdentification, D as TCascadeResolver, Dn as TRelationFilterJunction, Dt as TPrimaryKeyChange, E as PrimaryKeyOf, En as TRelGuardState, Et as TMetadataOverrides, F as TDbActionProcessor, Fn as relationStaticFilter, Ft as TTouchManyOptions, G as TDbIndexField, Gn as TRowOrderKey, Gt as isGeoIndexableType, H as TDbFieldMeta, Hn as TGenericLogger, Ht as UniqueryControls, I as TDbActionTargetSummary, In as DbEncryption, It as TValueFormatterPair, J as TDbInsertIgnoreSlot, Jt as ALL_VIEW_CAPABILITIES, K as TDbIndexType, Kn as UniquSelect, Kt as isGeoPointType, L as TDbAvailableActions, Ln as TDbEncryptionOptions, Lt as TViewJsonType, M as TDbActionInfo, Mn as forEachResolvedRelation, Mt as TSyncColumnResult, N as TDbActionIntent, Nn as hasRelationOp, Nt as TTableOptionDiff, O as TCascadeTarget, On as TRelationFilterTable, Ot as TReferencingForeignKey, P as TDbActionLevel, Pn as isResolvedRelationFilter, Pt as TTableResolver, Q as TDbObjectKind, Qt as TAdapterFactory, R as TDbCollation, Rn as DocumentFieldMapper, Rt as TWriteOptions, S as FlatOf, Sn as resolveDesignType, St as TIdResolveOptions, T as OwnPropsOf, Tn as ResolvedRelationFilter, Tt as TMetaResponse, U as TDbForeignKey, Un as TExprAggregate, Ut as WithRelation, V as TDbDeleteResult, Vn as NoopLogger, Vt as Uniquery, W as TDbIndex, Wn as TFirstLast, Wt as TableMetadata, X as TDbInsertManyResult, Xt as TViewCapability, Y as TDbInsertManyIgnoreResult, Yt as BaseDbAdapter, Z as TDbInsertResult, Zt as DbSpace, _ as DbPatch, _n as IntegrityStrategy, _t as TExistingTableOption, a as isJsonValueField, an as AtscriptExprNode, at as TDbUpdateResult, b as FieldOpsFor, bn as AtscriptDbReadable, bt as TFkLookupTarget, c as resolveCalendarBuckets, cn as AtscriptQueryFieldRef, ct as TDbWriteCheckContext, d as AggregateFn, dn as TViewJoin, dt as TDeleteOptions, en as AtscriptDbView, et as TDbRelation, f as AggregateQuery, fn as TViewPlan, ft as TDerivedChangeReason, g as DbControls, gn as AtscriptDbTable, gt as TExistingForeignKey, h as AtscriptDbWritable, hn as translateQueryTree, ht as TExistingColumn, i as isBucketableField, in as aliasTargetOf, it as TDbUpdateOptions, j as TCrudPermissions, jn as containsRelationFilter, jt as TSearchIndexInfo, k as TColumnDiff, kn as TRelationStaticFilter, kt as TRelationInfo, l as AggregateControls, ln as AtscriptQueryNode, lt as TDbWriteGuard, mn as isFieldRef, mt as TEnsureTableOptions, n as TComputedSelect, nn as isAtscriptDbView, nt as TDbRemoveGuardContext, o as jsonValueAncestor, on as AtscriptOrderItem, ot as TDbWriteAction, p as AggregateResult, pn as evaluateExpr, pt as TDerivedColumn, q as TDbInsertIgnoreResult, qt as ALL_BUCKET_UNITS, r as TResolvedBucket, rn as isViewType, rt as TDbStorageType, s as normalizeComputedSelect, sn as AtscriptQueryComparison, st as TDbWriteCheck, t as TBucketFieldSource, tn as TViewColumnMapping, tt as TDbRemoveGuard, u as AggregateExpr, un as AtscriptRef, ut as TDbWriteGuardContext, v as DbQuery, vn as NativeIntegrity, vt as TFieldMeta, w as NullableOptional, wn as REL_FILTER_MAX_NODES, wt as TInsertOptions, x as FilterExpr, xn as DbResponse, xt as TIdDescriptor, y as DbRow, yn as TCascadePin, yt as TFkLookupResolver, z as TDbDefaultFn, zn as FieldMappingStrategy, zt as TWriteTableResolver } from "./buckets-Cb0zmhDc.mjs";
+import { $ as TDbInsertResult, $t as DbSpace, A as TColumnDiff, An as TRelationFilterJunction, At as TReferencingForeignKey, B as TDbDefaultFn, Bn as TDbEncryptionOptions, Bt as TWriteOptions, C as NavPropsOf, Cn as AtscriptDbReadable, Ct as TIdDescriptor, D as PrimaryKeyOf, Dn as REL_FILTER_MAX_NODES, Dt as TMetaResponse, E as OwnPropsOf, En as REL_FILTER_MAX_DEPTH, Et as TInsertOptions, F as TDbActionLevel, Fn as forEachResolvedRelation, Ft as TTableOptionDiff, G as TDbIndex, Gn as TGenericLogger, Gt as WithRelation, H as TDbDeleteResult, Hn as FieldMappingStrategy, Ht as TypedWithRelation, I as TDbActionProcessor, In as hasRelationOp, It as TTableResolver, J as TDbInsertIgnoreOptions, Jn as TRowOrderKey, Jt as isGeoPointType, K as TDbIndexField, Kn as TExprAggregate, Kt as TableMetadata, L as TDbActionTargetSummary, Ln as isResolvedRelationFilter, Lt as TTouchManyOptions, M as TCrudPermissions, Mn as TRelationStaticFilter, Mt as TRowResolveOptions, N as TDbActionInfo, Nn as andFilters, Nt as TSearchIndexInfo, O as TCascadeResolver, On as ResolvedRelationFilter, Ot as TMetadataOverrides, P as TDbActionIntent, Pn as containsRelationFilter, Pt as TSyncColumnResult, Q as TDbInsertManyResult, Qt as TViewCapability, R as TDbAvailableActions, Rn as relationStaticFilter, Rt as TValueFormatterPair, S as FlatOf, Sn as TCascadePin, St as TFkLookupTarget, T as NullsPlacement, Tn as resolveDesignType, Tt as TIdentification, U as TDbFieldMeta, Un as TReadControls, Ut as Uniquery, V as TDbDefaultValue, Vn as DocumentFieldMapper, Vt as TWriteTableResolver, W as TDbForeignKey, Wn as NoopLogger, Wt as UniqueryControls, X as TDbInsertIgnoreSlot, Xt as ALL_VIEW_CAPABILITIES, Y as TDbInsertIgnoreResult, Yn as UniquSelect, Yt as ALL_BUCKET_UNITS, Z as TDbInsertManyIgnoreResult, Zt as BaseDbAdapter, _ as DbPatch, _n as isFieldRef, _t as TExistingColumn, a as isJsonValueField, an as isViewType, at as TDbStorageType, b as FieldOpsFor, bn as IntegrityStrategy, bt as TFieldMeta, c as resolveCalendarBuckets, cn as AtscriptExprNode, ct as TDbWriteAction, d as AggregateFn, dn as AtscriptQueryFieldRef, dt as TDbWriteGuard, en as TAdapterFactory, et as TDbObjectKind, f as AggregateQuery, fn as AtscriptQueryNode, ft as TDbWriteGuardContext, g as DbControls, gn as evaluateExpr, gt as TEnsureTableOptions, h as AtscriptDbWritable, hn as TViewPlan, ht as TDerivedColumn, i as isBucketableField, in as isAtscriptDbView, it as TDbRemoveGuardContext, j as TCrudOp, jn as TRelationFilterTable, jt as TRelationInfo, k as TCascadeTarget, kn as TRelGuardState, kt as TPrimaryKeyChange, l as AggregateControls, ln as AtscriptOrderItem, lt as TDbWriteCheck, mn as TViewJoin, mt as TDerivedChangeReason, n as TComputedSelect, nn as AtscriptDbView, nt as TDbRelation, o as jsonValueAncestor, on as TViewReadPlan, ot as TDbUpdateOptions, p as AggregateResult, pn as AtscriptRef, pt as TDeleteOptions, q as TDbIndexType, qn as TFirstLast, qt as isGeoIndexableType, r as TResolvedBucket, rn as TViewColumnMapping, rt as TDbRemoveGuard, s as normalizeComputedSelect, sn as aliasTargetOf, st as TDbUpdateResult, t as TBucketFieldSource, tn as TDbSpaceOptions, tt as TDbReferentialAction, u as AggregateExpr, un as AtscriptQueryComparison, ut as TDbWriteCheckContext, v as DbQuery, vn as translateQueryTree, vt as TExistingForeignKey, w as NullableOptional, wn as DbResponse, wt as TIdResolveOptions, x as FilterExpr, xn as NativeIntegrity, xt as TFkLookupResolver, y as DbRow, yn as AtscriptDbTable, yt as TExistingTableOption, z as TDbCollation, zn as DbEncryption, zt as TViewJsonType } from "./buckets-CBKL_ZWE.mjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-CtPYTIvy.mjs";
 import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-Wo-smrYV.mjs";
-import { _ as aggregateFailure, a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-tBNvM1qc.mjs";
+import { _ as aggregateFailure, a as buildValidationContext, b as isRetryableDbError, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-B3xlbrWf.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-lcAnwvm9.mjs";
-import { i as tableNameOf } from "./relation-helpers-Bdo4NHPC.mjs";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-BIJ8l_hF.mjs";
+import { i as tableNameOf } from "./relation-helpers-BUsxNNGU.mjs";
 import { AtscriptExprNode as AtscriptExprNode$1, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedRowOrderKey, ResolvedSelectExpr, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 
@@ -149,6 +149,7 @@ interface TGuardedQuery {
     $groupBy?: unknown;
     $having?: unknown;
     $rowOrder?: unknown;
+    $nulls?: unknown;
   };
 }
 /**
@@ -563,6 +564,29 @@ declare function searchMemberKind(type: TAtscriptAnnotatedType | undefined): TSe
   problem: string;
 };
 //#endregion
+//#region src/query/read-columns.d.ts
+/**
+ * What a read renders: rows (`findOne` / `findMany` / per-partition pages),
+ * a row count, or an aggregate (`aggregate`, with or without `$count`).
+ * @since 0.1.153
+ */
+type TReadColumnsKind = "rows" | "count" | "aggregate";
+/**
+ * The PHYSICAL columns of the queried table (or view) that a read of `kind`
+ * renders — filter keys and relational-predicate correlation columns, sort
+ * keys, `partitionBy`, the projection, and for an aggregate the group keys,
+ * bucket / aggregate / expression / `first`-`last` sources and `$having`
+ * keys. Names that are not columns (aggregate aliases) may be included — a
+ * consumer ignores names it does not know.
+ *
+ * `undefined` means EVERY column: the read projects all columns (no
+ * `$select`, so `SELECT *`), or its filter holds an operator this collector
+ * does not recognise. A view read may drop a left join only when no returned
+ * column reads it, so over-inclusion is always safe.
+ * @since 0.1.153
+ */
+declare function queryReadColumns(query: DbQuery, kind: TReadColumnsKind, partitionBy?: readonly string[]): Set<string> | undefined;
+//#endregion
 //#region src/patch/patch-decomposer.d.ts
 /**
  * Decomposes a patch payload into a flat update object for adapters
@@ -662,4 +686,4 @@ declare function createFailureCollector(what: string): {
  */
 declare function numericOperandProblem(fd: TDbFieldMeta): string | undefined;
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type NullsPlacement, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertIgnoreOptions, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateOptions, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadColumnsKind, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSearchMemberKind, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TViewReadPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/index.mjs

@@ -1,12 +1,12 @@
-import { a as aggregateExpressionsNotSupported, c as isConflict, l as spaceClosedError, n as CasMismatchError, o as aggregateFailure, r as DbError, s as bucketTimeZoneUnavailable, t as CasExhaustedError } from "./db-error-Az85UhTX.mjs";
-import { $ as DocumentFieldMapper, A as resolveDesignType, B as checkHavingKeys, C as ALL_BUCKET_UNITS, D as IntegrityStrategy, E as createFailureCollector, F as ENCRYPTED_REASON, G as guardFilter, H as collectQueryPaths, I as acceptedOperatorsHint, J as guardQuery, K as guardPath, L as assertGeoPoint, M as searchIndexNotFoundMessage, N as vectorIndexNotFoundMessage, O as NativeIntegrity, P as ADAPTER_FILTER_REASON, Q as RelationalFieldMapper, R as bucketSourceVerdict, S as ApplicationIntegrity, T as BaseDbAdapter, U as groupSourceVerdict, V as classifyQueryPath, W as guardAggregate, X as sortFieldNames, Y as narrowerFilterOps, Z as unsupportedOperatorMessage, _ as isViewType, _t as NoopLogger, at as describeFulltext, b as assertNoVersionWrites, ct as TableMetadata, dt as aliasTargetOf, et as FieldMappingStrategy, f as fkColumns, ft as isBucketableField, g as isAtscriptDbView, gt as resolveCalendarBuckets, h as AtscriptDbView, ht as normalizeComputedSelect, it as defaultFulltextIndex, j as geoIndexNotFoundMessage, k as AtscriptDbReadable, lt as isGeoIndexableType, mt as jsonValueAncestor, n as isColumnTypeChanged, nt as numericOperandProblem, ot as searchTermInteger, pt as isJsonValueField, q as guardPaths, rt as INTEGER_REGEX_OP, st as splitFulltextFields, tt as UniquSelect, ut as isGeoPointType, v as AtscriptDbTable, w as ALL_VIEW_CAPABILITIES, x as decomposePatch, y as isVersionExemptPatch, z as canFilterLeaf } from "./column-diff-CnyLjbQ8.mjs";
-import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-CyaZyb9I.mjs";
-import { A as hasRelationOp, C as REL_FILTER_MAX_DEPTH, D as containsRelationFilter, E as andFilters, G as evaluateExpr, H as tableNameOf, K as isFieldRef, P as relationStaticFilter, S as uniqueKeyTuple, T as ResolvedRelationFilter, j as isResolvedRelationFilter, k as forEachResolvedRelation, q as translateQueryTree, w as REL_FILTER_MAX_NODES } from "./nested-writer-cvbVAkNo.mjs";
+import { a as aggregateExpressionsNotSupported, c as isConflict, l as isRetryableDbError, n as CasMismatchError, o as aggregateFailure, r as DbError, s as bucketTimeZoneUnavailable, t as CasExhaustedError, u as spaceClosedError } from "./db-error-eSsQX7rt.mjs";
+import { $ as DocumentFieldMapper, A as resolveDesignType, B as checkHavingKeys, C as ALL_BUCKET_UNITS, D as IntegrityStrategy, E as createFailureCollector, F as ENCRYPTED_REASON, G as guardFilter, H as collectQueryPaths, I as acceptedOperatorsHint, J as guardQuery, K as guardPath, L as assertGeoPoint, M as searchIndexNotFoundMessage, N as vectorIndexNotFoundMessage, O as NativeIntegrity, P as ADAPTER_FILTER_REASON, Q as RelationalFieldMapper, R as bucketSourceVerdict, S as ApplicationIntegrity, T as BaseDbAdapter, U as groupSourceVerdict, V as classifyQueryPath, W as guardAggregate, X as sortFieldNames, Y as narrowerFilterOps, Z as unsupportedOperatorMessage, _ as isViewType, _t as NoopLogger, at as describeFulltext, b as assertNoVersionWrites, ct as TableMetadata, dt as aliasTargetOf, et as FieldMappingStrategy, f as fkColumns, ft as isBucketableField, g as isAtscriptDbView, gt as resolveCalendarBuckets, h as AtscriptDbView, ht as normalizeComputedSelect, it as defaultFulltextIndex, j as geoIndexNotFoundMessage, k as AtscriptDbReadable, lt as isGeoIndexableType, mt as jsonValueAncestor, n as isColumnTypeChanged, nt as numericOperandProblem, ot as searchTermInteger, pt as isJsonValueField, q as guardPaths, rt as INTEGER_REGEX_OP, st as splitFulltextFields, tt as UniquSelect, ut as isGeoPointType, v as AtscriptDbTable, w as ALL_VIEW_CAPABILITIES, x as decomposePatch, y as isVersionExemptPatch, z as canFilterLeaf } from "./column-diff-DrE4ho_m.mjs";
+import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-B_sgl4mB.mjs";
+import { A as hasRelationOp, C as REL_FILTER_MAX_DEPTH, D as containsRelationFilter, E as andFilters, G as evaluateExpr, H as tableNameOf, K as isFieldRef, P as relationStaticFilter, S as uniqueKeyTuple, T as ResolvedRelationFilter, j as isResolvedRelationFilter, k as forEachResolvedRelation, q as translateQueryTree, w as REL_FILTER_MAX_NODES } from "./nested-writer-BOj_c_lI.mjs";
 import { i as DB_ENTITY_ANNOTATIONS, n as searchMemberKind } from "./search-fields-DBIZKwyb.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-TkiJQ-Dp.mjs";
 import { t as DEFAULT_DB_SPACE } from "./consts-C_-5_pFq.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps } from "./ops.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-BTiIOTKP.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-BACewoRj.mjs";
 import { isAnnotatedType } from "@atscript/typescript/utils";
 import { RELATION_OPS, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
@@ -203,6 +203,92 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 	throw new CasExhaustedError(maxAttempts, lastSeenVersion);
 }
 //#endregion
+//#region src/query/read-columns.ts
+/** Logical connectives whose operands are sub-filters. */
+const CONNECTIVES = new Set([
+	"$and",
+	"$or",
+	"$nor"
+]);
+/**
+* Adds every PHYSICAL column a translated filter reads to `out`: comparison
+* keys, and — for a resolved relational predicate (`$some` / `$none`) — the
+* source-side columns it correlates on. Returns `false` when the filter holds
+* a top-level operator this walker does not know (then every column must be
+* assumed read).
+*/
+function collectFilter(filter, out) {
+	if (!filter || typeof filter !== "object") return true;
+	for (const [key, value] of Object.entries(filter)) {
+		if (CONNECTIVES.has(key)) {
+			if (!Array.isArray(value)) return false;
+			for (const child of value) if (!collectFilter(child, out)) return false;
+			continue;
+		}
+		if (key === "$not") {
+			if (!collectFilter(value, out)) return false;
+			continue;
+		}
+		if (key.startsWith("$")) return false;
+		out.add(key);
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			for (const operand of Object.values(value)) if (isResolvedRelationFilter(operand)) {
+				for (const pair of operand.pairs) out.add(pair.source);
+				for (const pair of operand.junction?.toSource ?? []) out.add(pair.source);
+			} else if (operand && typeof operand === "object" && "$field" in operand) {
+				const other = operand.$field;
+				if (typeof other !== "string") return false;
+				out.add(other);
+			}
+		}
+	}
+	return true;
+}
+/**
+* The PHYSICAL columns of the queried table (or view) that a read of `kind`
+* renders — filter keys and relational-predicate correlation columns, sort
+* keys, `partitionBy`, the projection, and for an aggregate the group keys,
+* bucket / aggregate / expression / `first`-`last` sources and `$having`
+* keys. Names that are not columns (aggregate aliases) may be included — a
+* consumer ignores names it does not know.
+*
+* `undefined` means EVERY column: the read projects all columns (no
+* `$select`, so `SELECT *`), or its filter holds an operator this collector
+* does not recognise. A view read may drop a left join only when no returned
+* column reads it, so over-inclusion is always safe.
+* @since 0.1.153
+*/
+function queryReadColumns(query, kind, partitionBy) {
+	const out = /* @__PURE__ */ new Set();
+	if (!collectFilter(query.filter, out)) return void 0;
+	if (kind === "count") return out;
+	const controls = query.controls ?? {};
+	for (const key of Object.keys(controls.$sort ?? {})) out.add(key);
+	for (const key of Object.keys(controls.$nulls ?? {})) out.add(key);
+	for (const column of partitionBy ?? []) out.add(column);
+	const select = controls.$select;
+	const fields = select?.asArray;
+	if (kind === "rows") {
+		if (!fields || fields.length === 0) return void 0;
+		for (const field of fields) out.add(field);
+		return out;
+	}
+	const groupBy = controls.$groupBy ?? [];
+	const computed = select?.computedAliases.length ?? 0;
+	if (!fields?.length && !select?.buckets?.length && computed === 0) return;
+	for (const field of fields ?? []) out.add(field);
+	for (const key of groupBy) out.add(key);
+	for (const bucket of select?.buckets ?? []) out.add(bucket.field);
+	for (const expr of select?.aggregates ?? []) if (expr.$field !== "*") out.add(expr.$field);
+	for (const e of select?.exprAggregates ?? []) for (const name of e.names) out.add(name);
+	for (const e of select?.exprs ?? []) for (const name of e.names) out.add(name);
+	for (const fl of select?.firstLast ?? []) out.add(fl.column);
+	for (const key of select?.rowOrder ?? []) out.add(key.column);
+	for (const column of select?.sources.keys() ?? []) out.add(column);
+	if (controls.$having && !collectFilter(controls.$having, out)) return void 0;
+	return out;
+}
+//#endregion
 //#region src/table/db-space.ts
 /**
 * A `@db.alias` type only names a join scope inside a view definition — it
@@ -474,4 +560,4 @@ function isDbEntityType(value) {
 	return DB_ENTITY_ANNOTATIONS.some((name) => value.metadata.has(name));
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, NoopLogger, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, RelationalFieldMapper, ResolvedRelationFilter, TableMetadata, UniquSelect, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, INTEGER_REGEX_OP, IntegrityStrategy, NativeIntegrity, NoopLogger, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, RelationalFieldMapper, ResolvedRelationFilter, TableMetadata, UniquSelect, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, defaultFulltextIndex, deletePath, describeFulltext, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isRetryableDbError, isVersionExemptPatch, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, queryReadColumns, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, searchMemberKind, searchTermInteger, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, splitFulltextFields, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/{nested-writer-cvbVAkNo.mjs → nested-writer-BOj_c_lI.mjs}

@@ -1,4 +1,4 @@
-import { i as DepthLimitExceededError, r as DbError } from "./db-error-Az85UhTX.mjs";
+import { i as DepthLimitExceededError, r as DbError } from "./db-error-eSsQX7rt.mjs";
 import { a as isPlainObject, r as getPath } from "./object-TkiJQ-Dp.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
 import { isRelationOp } from "@uniqu/core";

package/dist/{nested-writer-BzbOPSUp.cjs → nested-writer-Bl1SZS7x.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-DRQH4sLY.cjs");
+const require_db_error = require("./db-error-JcfJqqpk.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");

package/dist/ops.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DRQH4sLY.cjs");
+const require_db_error = require("./db-error-JcfJqqpk.cjs");
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {

package/dist/ops.mjs

@@ -1,4 +1,4 @@
-import { r as DbError } from "./db-error-Az85UhTX.mjs";
+import { r as DbError } from "./db-error-eSsQX7rt.mjs";
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {