@happyvertical/smrt-core 0.42.6 → 0.42.7

package/dist/collection.js

@@ -4,10 +4,11 @@ import { buildQueryCacheKey, ensureCacheInvalidationListener, getCacheGeneration
 import { toSafeInteger } from "./utils/safe-integer.js";
 import { isTenantScopedClassResolved, resolveDispatchTenantScope } from "./dispatch/tenant-resolver.js";
 import { GlobalInterceptors, createInterceptorContext, resolveGetStringFilter } from "./interceptors.js";
+import { detectEngine } from "./schema/ddl/index.js";
 import { SmrtClass } from "./class.js";
 import { EmbeddingProvider } from "./embeddings/provider.js";
 import { EmbeddingStorage } from "./embeddings/storage.js";
-import { QueryBoundsError, QueryOrderByError } from "./query-bounds.js";
+import { MAX_LIST_LIMIT, QueryBoundsError, QueryOrderByError } from "./query-bounds.js";
 import { verifyPersistenceTable } from "./schema/table-verifier.js";
 import { fieldsFromClass, formatDataJs, toCamelCase } from "./utils.js";
 import { ObjectRegistry } from "./registry.js";
@@ -22,6 +23,12 @@ var logger = createLogger({ level: "info" });
 * see {@link SmrtCollection.resolveCollectionMemoryOwnerId} (#2365).
 */
 var COLLECTION_MEMORY_OWNER_ID = "__collection__";
+/** Maximum number of independent facet fields accepted by one call. */
+var MAX_FACET_FIELDS = 20;
+/** Default number of distinct values returned for each facet field. */
+var DEFAULT_FACET_LIMIT = 50;
+/** Hard ceiling for distinct values returned for one facet field. */
+var MAX_FACET_LIMIT = MAX_LIST_LIMIT;
 /**
 * Validate an optional collection-level list bound (#2367).
 *
@@ -66,6 +73,7 @@ function assertQueryBound(value, parameterName) {
 * @returns Modified WHERE clause with qualified _meta_type, or original if no resolution needed
 */
 function resolveMetaTypeInWhere(where) {
+	if (Array.isArray(where)) return where.map((group) => group.map((condition) => resolveMetaTypeInWhere(condition)));
 	if (!where?._meta_type || typeof where._meta_type !== "string") return where;
 	const metaTypeValue = where._meta_type;
 	if (metaTypeValue.includes(":")) return where;
@@ -76,6 +84,14 @@ function resolveMetaTypeInWhere(where) {
 	};
 	return where;
 }
+/** Add an AND predicate without collapsing a caller's DNF OR branches. */
+function andWhereCondition(where, condition) {
+	if (Array.isArray(where)) return where.map((group) => [condition, ...group]);
+	return {
+		...where ?? {},
+		...condition
+	};
+}
 /**
 * Field names that carry a stored embedding vector for a class (Issue #2281)
 *
@@ -298,6 +314,13 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	* ```
 	*/
 	convertWhereKeys(where) {
+		if (Array.isArray(where)) {
+			if (where.length === 0 || where.some((group) => !Array.isArray(group) || group.length === 0)) throw new Error("Invalid DNF where clause: each OR branch must contain at least one condition.");
+			return where.map((group) => group.map((condition) => this.convertWhereKeysRecord(condition)));
+		}
+		return this.convertWhereKeysRecord(where);
+	}
+	convertWhereKeysRecord(where) {
 		const VALID_OPERATORS = [
 			"=",
 			">",
@@ -389,6 +412,20 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	hasCustomPrimaryKey(fields) {
 		return Object.values(fields).some((fieldDef) => fieldDef.primaryKey === true || fieldDef._meta?.primaryKey === true);
 	}
+	resolvePrimaryKeyField(fields, label) {
+		const declared = Object.entries(fields).filter(([, fieldDef]) => fieldDef.primaryKey === true || fieldDef._meta?.primaryKey === true).map(([field]) => field);
+		if (declared.length > 1) throw new Error(`${label} declares multiple primary-key fields (${declared.join(", ")}); listWithLatestRelated requires a single primary key.`);
+		const field = declared[0] ?? "id";
+		return {
+			field,
+			column: this.toDbColumnName(field)
+		};
+	}
+	getDatabaseEngine() {
+		const db = this.db;
+		const isDuckDbConnection = (db.client?.constructor?.name?.toLowerCase() ?? "").includes("duckdb") || typeof db.exportTable === "function" && db.client !== void 0 && "connection" in db.client;
+		return detectEngine(db.url || db.config?.url || "", this.getDatabaseEngineHint() || db.type || db.config?.type || (isDuckDbConnection ? "duckdb" : void 0));
+	}
 	isOmittedCustomPrimaryKeySystemField(fieldName, hasCustomPrimaryKey, explicitFieldNames) {
 		return hasCustomPrimaryKey && !explicitFieldNames.has(fieldName) && (fieldName === "id" || fieldName === "slug" || fieldName === "context");
 	}
@@ -436,6 +473,210 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 			outputFields
 		};
 	}
+	/**
+	* Parse and validate order terms while retaining the resolved database
+	* column. The normal list order builder remains the source of truth for
+	* field, sensitive-field, and permission validation; this companion shape
+	* lets the latest-row CTE qualify the same safe identifiers with its alias.
+	*/
+	resolveOrderByTerms(orderBy, fields, label) {
+		const validatedSql = this.buildOrderBySql(orderBy, fields);
+		const items = Array.isArray(orderBy) ? orderBy : [orderBy];
+		if (items.length === 0) throw new Error(`Invalid ${label}: at least one order field is required.`);
+		const validatedTerms = validatedSql.replace(/^ ORDER BY /, "").split(", ").map((term) => term.split(/\s+/));
+		return items.map((item, index) => {
+			const [field, direction = "ASC"] = String(item).trim().split(/\s+/);
+			if (!field) throw new Error(`Invalid ${label}: an order field is required.`);
+			const normalizedDirection = direction.toUpperCase();
+			if (normalizedDirection !== "ASC" && normalizedDirection !== "DESC") throw new Error(`Invalid ${label} direction: ${direction}. Must be ASC or DESC.`);
+			return {
+				column: validatedTerms[index]?.[0] ?? this.toDbColumnName(field),
+				direction: normalizedDirection,
+				field
+			};
+		});
+	}
+	qualifyLatestOrderTerms(alias, terms) {
+		return terms.flatMap((term) => {
+			const column = `${alias}.${this.quoteProjectionIdentifier(term.column)}`;
+			return [`CASE WHEN ${column} IS NULL THEN 1 ELSE 0 END ASC`, `${column} ${term.direction}`];
+		}).join(", ");
+	}
+	qualifyLatestParentOrderTerms(alias, terms) {
+		return terms.flatMap((term) => {
+			const column = `${alias}.${this.quoteProjectionIdentifier(term.column)}`;
+			return [`CASE WHEN ${column} IS NULL THEN 1 ELSE 0 END ASC`, `${column} ${term.direction}`];
+		}).join(", ");
+	}
+	resolveOneToManyInverseForeignKey(relationship) {
+		const inverseCandidates = ObjectRegistry.getInverseRelationshipsForSelf(this._itemClass.name).filter((candidate) => candidate.sourceClass === relationship.targetClass && candidate.type === "foreignKey");
+		const explicitForeignKey = relationship.options?.foreignKey;
+		const matchedForeignKey = explicitForeignKey ? inverseCandidates.find((candidate) => candidate.fieldName === explicitForeignKey) : void 0;
+		if (explicitForeignKey && !matchedForeignKey) throw new Error(`oneToMany ${relationship.fieldName} specifies foreignKey '${explicitForeignKey}', but ${relationship.targetClass} has no matching inverse foreignKey. Candidates: ${inverseCandidates.map((candidate) => candidate.fieldName).join(", ") || "(none)"}`);
+		const inverseForeignKey = matchedForeignKey ?? inverseCandidates.find((candidate) => candidate.targetClass === this._itemClass.name) ?? inverseCandidates[0];
+		if (!inverseForeignKey) throw new Error(`Could not find inverse foreignKey on ${relationship.targetClass} for oneToMany relationship ${relationship.fieldName}`);
+		return inverseForeignKey;
+	}
+	/**
+	* Load a page of hydrated parents with one selected latest row from a
+	* declared `@oneToMany` relation. The parent page is sliced only after the
+	* latest-row join and optional related sort are applied, so unrelated rows
+	* are never hydrated in application code.
+	*
+	* Missing related rows return `latestRelated: null`. Related order and sort
+	* fields place null values after non-null values consistently on all
+	* supported adapters. The related row is a plain projection and is never a
+	* full `SmrtObject` hydration.
+	*
+	* @example
+	* ```typescript
+	* const page = await opportunities.listWithLatestRelated({
+	*   latestRelated: {
+	*     relation: 'evaluations',
+	*     orderBy: 'evaluatedAt DESC',
+	*     select: ['score', 'evaluatedAt'],
+	*     sortBy: 'score DESC',
+	*   },
+	*   limit: 25,
+	*   offset: 0,
+	* });
+	* console.log(page[0].parent, page[0].latestRelated?.score);
+	* ```
+	*/
+	async listWithLatestRelated(options) {
+		await this.ensureStorageReady();
+		const itemClassName = this.getResolvedItemClassName();
+		const itemQualifiedName = this.getResolvedItemQualifiedName();
+		const interceptorContext = createInterceptorContext(itemClassName, "list", this.constructor.name);
+		const interceptedOptions = await GlobalInterceptors.executeBeforeList(itemClassName, options, interceptorContext) ?? options;
+		let { where, offset, limit, orderBy } = interceptedOptions;
+		const latestOptions = interceptedOptions.latestRelated ?? options.latestRelated;
+		const isSTI = ObjectRegistry.getTableStrategy(itemQualifiedName) === "sti";
+		if (isSTI) {
+			const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
+			if (stiBase && stiBase !== itemQualifiedName) where = {
+				_meta_type: itemQualifiedName,
+				...where || {}
+			};
+		}
+		where = resolveMetaTypeInWhere(where);
+		const relationship = ObjectRegistry.getRelationships(this._itemClass.name).find((candidate) => candidate.fieldName === latestOptions.relation && candidate.type === "oneToMany");
+		if (!relationship) throw new Error(`latestRelated.relation '${latestOptions.relation}' is not a declared oneToMany relationship on ${itemClassName}.`);
+		const inverseForeignKey = this.resolveOneToManyInverseForeignKey(relationship);
+		const relatedCollection = await ObjectRegistry.getCollection(relationship.targetClass, this.options);
+		await relatedCollection.ensureStorageReady();
+		const relatedFields = relatedCollection.getFieldsSync();
+		const relatedItemClassName = relatedCollection.getResolvedItemClassName();
+		const relatedQualifiedName = relatedCollection.getResolvedItemQualifiedName();
+		const relatedIsSTI = ObjectRegistry.getTableStrategy(relatedQualifiedName) === "sti";
+		const relatedInterceptorContext = createInterceptorContext(relatedItemClassName, "list", relatedCollection.constructor.name);
+		let relatedWhere = (await GlobalInterceptors.executeBeforeList(relatedItemClassName, { where: {} }, relatedInterceptorContext) ?? { where: {} }).where;
+		if (relatedIsSTI) {
+			const relatedStiBase = ObjectRegistry.getSTIBase(relatedQualifiedName);
+			if (relatedStiBase && relatedStiBase !== relatedQualifiedName) relatedWhere = {
+				_meta_type: relatedQualifiedName,
+				...relatedWhere || {}
+			};
+		}
+		relatedWhere = resolveMetaTypeInWhere(relatedWhere);
+		const { sql: relatedWhereSql, values: relatedWhereValues } = buildWhere(relatedCollection.convertWhereKeys(relatedWhere || {}));
+		const relatedPrimaryKey = relatedCollection.resolvePrimaryKeyField(relatedFields, `Related model ${relatedItemClassName}`);
+		const relatedSelect = latestOptions.select ?? [relatedPrimaryKey.field];
+		const relatedProjection = relatedCollection.resolveProjectionSelect(relatedSelect, relatedFields, relatedIsSTI);
+		const relatedOrderTerms = relatedCollection.resolveOrderByTerms(latestOptions.orderBy, relatedFields, "latestRelated.orderBy");
+		const relatedSortTerms = latestOptions.sortBy ? relatedCollection.resolveOrderByTerms(latestOptions.sortBy, relatedFields, "latestRelated.sortBy") : [];
+		const parentFields = this.getFieldsSync();
+		const parentPrimaryKey = this.resolvePrimaryKeyField(parentFields, `Parent model ${itemClassName}`);
+		const relatedOutputFields = new Set(relatedProjection.outputFields);
+		relatedOutputFields.add(relatedPrimaryKey.field);
+		relatedOutputFields.add(inverseForeignKey.fieldName);
+		if (parentFields.tenantId && relatedFields.tenantId) relatedOutputFields.add("tenantId");
+		for (const term of [...relatedOrderTerms, ...relatedSortTerms]) relatedOutputFields.add(term.field);
+		const relatedFieldColumns = new Map([...relatedOrderTerms, ...relatedSortTerms].map((term) => [term.field, term.column]));
+		const parentSchema = ObjectRegistry.getSchema(itemQualifiedName) ?? ObjectRegistry.getSchema(itemClassName);
+		const liveParentSchema = typeof this.db.getTableSchema === "function" ? await this.db.getTableSchema(this.tableName) : void 0;
+		const parentColumnNames = Object.keys(liveParentSchema?.columns ?? parentSchema?.columns ?? {});
+		const occupiedParentIdentifiers = /* @__PURE__ */ new Set([
+			...Object.keys(parentFields),
+			...Object.keys(parentFields).map((fieldName) => this.toDbColumnName(fieldName)),
+			...parentColumnNames,
+			...Object.keys(parentSchema?.columns ?? {})
+		]);
+		const relatedFieldAliases = /* @__PURE__ */ new Map();
+		let nextAliasIndex = 0;
+		for (const fieldName of relatedOutputFields) {
+			let alias;
+			do
+				alias = `__smrt_lr_${nextAliasIndex++}`;
+			while (occupiedParentIdentifiers.has(alias) || [...relatedFieldAliases.values()].includes(alias));
+			relatedFieldAliases.set(fieldName, alias);
+		}
+		const parentSelectSql = parentColumnNames.length > 0 ? parentColumnNames.map((columnName) => this.quoteProjectionIdentifier(columnName)).join(", ") : "*";
+		const relatedAlias = (fieldName) => {
+			const alias = relatedFieldAliases.get(fieldName);
+			if (!alias) throw new Error(`Missing latest-related alias for '${fieldName}'.`);
+			return alias;
+		};
+		const relatedSelectExpressions = Array.from(relatedOutputFields).map((fieldName) => {
+			const column = relatedFieldColumns.get(fieldName) ?? relatedCollection.toDbColumnName(fieldName);
+			const alias = relatedAlias(fieldName);
+			return `${relatedCollection.quoteProjectionIdentifier(column)} AS ${relatedCollection.quoteProjectionIdentifier(alias)}`;
+		});
+		const relatedRankOrder = [relatedCollection.qualifyLatestOrderTerms("r", relatedOrderTerms), `r.${relatedCollection.quoteProjectionIdentifier(relatedPrimaryKey.column)} DESC`].filter(Boolean).join(", ");
+		const latestRankAlias = relatedCollection.quoteProjectionIdentifier("__smrt_latest_rank");
+		const latestRelatedAlias = (fieldName) => relatedCollection.quoteProjectionIdentifier(relatedAlias(fieldName));
+		const relatedCte = `WITH ranked_latest_related AS (SELECT ${relatedSelectExpressions.map((expression) => `r.${expression}`).join(", ")}, ROW_NUMBER() OVER (PARTITION BY r.${relatedCollection.quoteProjectionIdentifier(relatedCollection.toDbColumnName(inverseForeignKey.fieldName))} ORDER BY ${relatedRankOrder}) AS ${latestRankAlias} FROM ${relatedCollection.tableName} r${relatedWhereSql ? ` ${relatedWhereSql}` : ""}) `;
+		const { sql: rawWhereSql, values: parentWhereValues } = buildWhere(this.convertWhereKeys(where || {}));
+		const parentWhereSql = rawWhereSql.replace(/\$(\d+)/g, (_match, index) => `$${Number(index) + relatedWhereValues.length}`);
+		const relatedJoinConditions = [`rr.${latestRankAlias} = 1`, `rr.${latestRelatedAlias(inverseForeignKey.fieldName)} = ${this.quoteProjectionIdentifier(parentPrimaryKey.column)}`];
+		if (parentFields.tenantId && relatedFields.tenantId) relatedJoinConditions.push(`(rr.${latestRelatedAlias("tenantId")} = ${this.quoteProjectionIdentifier("tenant_id")} OR (rr.${latestRelatedAlias("tenantId")} IS NULL AND ${this.quoteProjectionIdentifier("tenant_id")} IS NULL))`);
+		const orderFragments = [];
+		if (relatedSortTerms.length > 0) orderFragments.push(relatedCollection.qualifyLatestParentOrderTerms("rr", relatedSortTerms.map((term) => ({
+			...term,
+			column: relatedAlias(term.field)
+		}))));
+		if (orderBy) {
+			const parentOrderTerms = this.resolveOrderByTerms(orderBy, parentFields, "orderBy");
+			orderFragments.push(parentOrderTerms.map((term) => `${this.quoteProjectionIdentifier(term.column)} ${term.direction}`).join(", "));
+		}
+		orderFragments.push(`${this.quoteProjectionIdentifier(parentPrimaryKey.column)} ASC`);
+		const boundedLimit = this.applyListBounds(assertQueryBound(limit, "limit"));
+		const boundedOffset = assertQueryBound(offset, "offset");
+		let limitOffsetSql = "";
+		const limitOffsetValues = [];
+		let nextParameter = relatedWhereValues.length + parentWhereValues.length + 1;
+		if (boundedLimit !== void 0) {
+			limitOffsetSql += ` LIMIT $${nextParameter++}`;
+			limitOffsetValues.push(boundedLimit);
+		}
+		if (boundedOffset !== void 0) {
+			if (boundedLimit === void 0) limitOffsetSql += this.getDatabaseEngine() === "sqlite" ? " LIMIT -1" : " LIMIT ALL";
+			limitOffsetSql += ` OFFSET $${nextParameter++}`;
+			limitOffsetValues.push(boundedOffset);
+		}
+		const sql = `${relatedCte}SELECT ${parentSelectSql}, ${Array.from(relatedOutputFields).map((fieldName) => `rr.${latestRelatedAlias(fieldName)} AS ${this.quoteProjectionIdentifier(relatedAlias(fieldName))}`).join(", ")} FROM ${this.quoteProjectionIdentifier(this.tableName)} LEFT JOIN ranked_latest_related rr ON ${relatedJoinConditions.join(" AND ")} ${parentWhereSql} ${orderFragments.length > 0 ? `ORDER BY ${orderFragments.join(", ")}` : ""}${limitOffsetSql}`;
+		const rows = await this.db.query(sql, ...relatedWhereValues, ...parentWhereValues, ...limitOffsetValues);
+		const instances = [];
+		const relatedAliasNames = new Set(relatedFieldAliases.values());
+		for (const row of rows.rows) {
+			const parentRow = Object.fromEntries(Object.entries(row).filter(([key]) => !relatedAliasNames.has(key)));
+			instances.push(await this.hydrateResultRow(parentRow, parentFields, isSTI));
+		}
+		const relatedByParentId = /* @__PURE__ */ new Map();
+		for (const row of rows.rows) {
+			const parentId = row[parentPrimaryKey.column];
+			if (parentId === null || parentId === void 0) continue;
+			const relatedRow = Object.fromEntries(relatedProjection.outputFields.map((fieldName) => [fieldName, row[relatedAlias(fieldName)]]));
+			const relatedId = row[relatedAlias(relatedPrimaryKey.field)];
+			relatedByParentId.set(String(parentId), relatedId === null || relatedId === void 0 ? null : relatedCollection.formatProjectionRow(relatedRow, relatedFields, relatedProjection.outputFields));
+		}
+		return (await GlobalInterceptors.executeAfterList(itemClassName, instances, interceptorContext)).map((parent) => {
+			return {
+				latestRelated: parent[parentPrimaryKey.field] === null || parent[parentPrimaryKey.field] === void 0 ? null : relatedByParentId.get(String(parent[parentPrimaryKey.field])) ?? null,
+				parent
+			};
+		});
+	}
 	formatProjectionRow(row, fields, outputFields) {
 		const formattedData = this.withHydratedCoreFields(formatDataJs(row, fields));
 		const projected = {};
@@ -788,10 +1029,7 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 		const isSTI = ObjectRegistry.getTableStrategy(itemQualifiedName) === "sti";
 		if (isSTI) {
 			const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
-			if (stiBase && stiBase !== itemQualifiedName) where = {
-				_meta_type: itemQualifiedName,
-				...where || {}
-			};
+			if (stiBase && stiBase !== itemQualifiedName) where = andWhereCondition(where, { _meta_type: itemQualifiedName });
 		}
 		where = resolveMetaTypeInWhere(where);
 		const { sql: whereSql, values: whereValues } = buildWhere(this.convertWhereKeys(where || {}));
@@ -1360,16 +1598,113 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 		let { where } = await GlobalInterceptors.executeBeforeList(itemClassName, options, interceptorContext) ?? options ?? {};
 		if (ObjectRegistry.getTableStrategy(itemQualifiedName) === "sti") {
 			const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
-			if (stiBase && stiBase !== itemQualifiedName) where = {
-				_meta_type: itemQualifiedName,
-				...where || {}
-			};
+			if (stiBase && stiBase !== itemQualifiedName) where = andWhereCondition(where, { _meta_type: itemQualifiedName });
 		}
 		where = resolveMetaTypeInWhere(where);
 		const { sql: whereSql, values: whereValues } = buildWhere(this.convertWhereKeys(where || {}));
 		return toSafeInteger((await this.db.query(`SELECT COUNT(*) as count FROM ${this.tableName} ${whereSql}`, ...whereValues)).rows[0].count, "Collection count");
 	}
 	/**
+	* Return database-backed distinct values and row counts for one or more
+	* column-backed fields.
+	*
+	* Each requested field is executed as a bounded `GROUP BY` query. Keeping
+	* one query per field uses standard SQL while avoiding a full collection
+	* read or model hydration. Scalar facet behavior is covered on SQLite and
+	* DuckDB; optional PostgreSQL scalar coverage runs in the `test:postgres`
+	* lane when `SMRT_TEST_POSTGRES_URL` is configured.
+	* The same `beforeList` interceptors as `list()` and `count()` run first,
+	* so tenancy and other read scopes are applied to every facet query.
+	*
+	* Facets group by the value stored in the column. SMRT does not split,
+	* unnest, or otherwise interpret array/string-list fields; consumers that
+	* need a facet per array member should maintain a scalar join table or use
+	* a consumer-specific query. JSON fields are grouped by their stored JSON
+	* value and decoded in the returned `value` when the field metadata allows
+	* it. Array/JSON encoding behavior is adapter-specific and is covered by
+	* the SQLite/DuckDB tests only; the optional PostgreSQL test covers scalar
+	* grouping.
+	*
+	* @param options.fields One or more fields, optionally with per-field limits
+	* @param options.where Filter conditions using the same syntax as `list()`
+	* @returns One value/count list per requested field, in request order
+	*
+	* Limits are always bounded: an explicit per-field limit is clamped to
+	* {@link MAX_FACET_LIMIT}, the collection's `maxListLimit` when configured,
+	* and the lower of those ceilings. When omitted, the effective limit is the
+	* collection's `defaultListLimit` or {@link DEFAULT_FACET_LIMIT}, subject to
+	* the same ceilings. This keeps facet queries bounded even when collection
+	* list bounds are unset.
+	*/
+	async facets(options) {
+		await this.ensureStorageReady();
+		if (!options || !Array.isArray(options.fields)) throw new Error("Invalid facets option: fields must be an array.");
+		if (options.fields.length === 0) throw new Error("Invalid facets option: at least one field is required.");
+		if (options.fields.length > 20) throw new Error(`Invalid facets option: at most 20 fields are allowed.`);
+		const itemClassName = this.getResolvedItemClassName();
+		const itemQualifiedName = this.getResolvedItemQualifiedName();
+		const interceptorContext = createInterceptorContext(itemClassName, "list", this.constructor.name);
+		const interceptedOptions = await GlobalInterceptors.executeBeforeList(itemClassName, options, interceptorContext) ?? options ?? {};
+		let { where } = interceptedOptions;
+		const isSTI = ObjectRegistry.getTableStrategy(itemQualifiedName) === "sti";
+		if (isSTI) {
+			const stiBase = ObjectRegistry.getSTIBase(itemQualifiedName);
+			if (stiBase && stiBase !== itemQualifiedName) where = andWhereCondition(where, { _meta_type: itemQualifiedName });
+		}
+		where = resolveMetaTypeInWhere(where);
+		const { sql: whereSql, values: whereValues } = buildWhere(this.convertWhereKeys(where || {}));
+		const fields = this.getFieldsSync();
+		const effectiveFields = interceptedOptions.fields ?? options.fields;
+		if (!Array.isArray(effectiveFields) || effectiveFields.length === 0) throw new Error("Invalid facets option: at least one field is required after interception.");
+		if (effectiveFields.length > 20) throw new Error(`Invalid facets option: at most 20 fields are allowed after interception.`);
+		const requested = effectiveFields.map((entry) => typeof entry === "string" ? { field: entry } : entry);
+		const seen = /* @__PURE__ */ new Set();
+		const results = [];
+		for (const request of requested) {
+			if (!request || typeof request.field !== "string") throw new Error("Invalid facet field: expected a string or { field, limit }.");
+			const field = request.field;
+			if (seen.has(field)) throw new Error(`Invalid facet field: '${field}' was requested more than once.`);
+			seen.add(field);
+			this.resolveProjectionSelect([field], fields, isSTI);
+			const columnName = this.toDbColumnName(field);
+			const quotedColumn = this.quoteProjectionIdentifier(columnName);
+			const quotedField = this.quoteProjectionIdentifier(field);
+			const requestedLimit = request.limit === void 0 ? this._defaultListLimit ?? DEFAULT_FACET_LIMIT : assertQueryBound(request.limit, `facet limit for '${field}'`);
+			const collectionLimit = this._maxListLimit ?? MAX_FACET_LIMIT;
+			const limit = Math.min(requestedLimit ?? DEFAULT_FACET_LIMIT, collectionLimit, MAX_FACET_LIMIT);
+			const sql = `SELECT ${quotedColumn} AS ${quotedField}, COUNT(*) AS "__smrt_facet_count" FROM ${this.tableName} ${whereSql} GROUP BY ${quotedColumn} ORDER BY "__smrt_facet_count" DESC, CASE WHEN ${quotedColumn} IS NULL THEN 1 ELSE 0 END ASC, ${quotedColumn} ASC LIMIT $${whereValues.length + 1}`;
+			const params = [...whereValues, limit];
+			const queryResult = await this.db.query(sql, ...params);
+			results.push({
+				field,
+				values: queryResult.rows.map((row) => {
+					const rawValue = row[field];
+					const formatted = formatDataJs({ [columnName]: rawValue }, fields);
+					const formattedKey = Object.hasOwn(formatted, field) ? field : toCamelCase(field);
+					return {
+						value: Object.hasOwn(formatted, formattedKey) ? formatted[formattedKey] : rawValue,
+						count: toSafeInteger(row.__smrt_facet_count, `Facet count for '${field}'`)
+					};
+				})
+			});
+		}
+		return results;
+	}
+	/**
+	* Return both the tenant/read-scoped total and a filtered count.
+	*
+	* This intentionally issues two `COUNT(*)` queries rather than reading
+	* rows into application memory. `count()` applies `beforeList` for each
+	* query, so the unfiltered total remains tenant-scoped while the filtered
+	* count adds the caller's `where` conditions.
+	*/
+	async counts(options = {}) {
+		return {
+			total: await this.count(),
+			filtered: await this.count(options)
+		};
+	}
+	/**
 	* Resolve this collection's STI child discriminator — the qualified item
 	* class name to use as a `_meta_type` scope — when the collection's item is
 	* an STI **child** (shares a table with sibling subtypes), or `null` for STI
@@ -1971,6 +2306,6 @@ var SmrtCollection = class SmrtCollection extends SmrtClass {
 	}
 };
 //#endregion
-export { SmrtCollection };
+export { DEFAULT_FACET_LIMIT, MAX_FACET_FIELDS, MAX_FACET_LIMIT, SmrtCollection };
 
 //# sourceMappingURL=collection.js.map