@atscript/db 0.1.129 → 0.1.130

package/dist/agg.cjs

@@ -4,5 +4,36 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 function resolveAlias(expr) {
 	return expr.$as ?? `${expr.$fn}_${expr.$field}`;
 }
+/**
+* Reads the `$search` / `$index` controls of an aggregate query.
+*
+* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+* shapes what is left. Every adapter must therefore apply the search predicate
+* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+* describe rows that matched. An adapter that silently ignored the term would
+* report totals for rows the same search excludes from the leaf list.
+*
+* Two rules the leaf search path applies and the grouped path must NOT:
+* - **No implicit relevance ordering.** Relevance is a property of a row, not
+*   of a group; after `$group` there is no per-row score left to sort on.
+*   Grouped results order by `$sort` or not at all.
+* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+*   rows; applying that before `$group` would silently truncate group counts.
+*
+* Returns `undefined` when there is nothing to search for, so callers fall
+* straight through to the plain grouped path.
+*/
+function resolveAggregateSearch(controls) {
+	const raw = controls?.$search;
+	if (typeof raw !== "string") return;
+	const text = raw.trim();
+	if (!text) return;
+	const index = controls?.$index;
+	return {
+		text,
+		indexName: typeof index === "string" && index ? index : void 0
+	};
+}
 //#endregion
+exports.resolveAggregateSearch = resolveAggregateSearch;
 exports.resolveAlias = resolveAlias;

package/dist/agg.d.cts

@@ -3,5 +3,34 @@ import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, Agg
 //#region src/agg.d.ts
 /** Resolves output alias: $as if provided, otherwise `{fn}_{field}`. */
 declare function resolveAlias(expr: AggregateExpr$1): string;
+/** The text-search request a grouped query carries, once normalised. */
+interface TAggregateSearch {
+  /** Non-empty, trimmed search term. */
+  text: string;
+  /** Named search index to target, when the caller picked one. */
+  indexName?: string;
+}
+/**
+ * Reads the `$search` / `$index` controls of an aggregate query.
+ *
+ * Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+ * shapes what is left. Every adapter must therefore apply the search predicate
+ * BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+ * describe rows that matched. An adapter that silently ignored the term would
+ * report totals for rows the same search excludes from the leaf list.
+ *
+ * Two rules the leaf search path applies and the grouped path must NOT:
+ * - **No implicit relevance ordering.** Relevance is a property of a row, not
+ *   of a group; after `$group` there is no per-row score left to sort on.
+ *   Grouped results order by `$sort` or not at all.
+ * - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+ *   rows; applying that before `$group` would silently truncate group counts.
+ *
+ * Returns `undefined` when there is nothing to search for, so callers fall
+ * straight through to the plain grouped path.
+ */
+declare function resolveAggregateSearch(controls: {
+  [key: `$${string}`]: unknown;
+} | undefined): TAggregateSearch | undefined;
 //#endregion
-export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAlias };
+export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAggregateSearch, resolveAlias };

package/dist/agg.d.mts

@@ -3,5 +3,34 @@ import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, Agg
 //#region src/agg.d.ts
 /** Resolves output alias: $as if provided, otherwise `{fn}_{field}`. */
 declare function resolveAlias(expr: AggregateExpr$1): string;
+/** The text-search request a grouped query carries, once normalised. */
+interface TAggregateSearch {
+  /** Non-empty, trimmed search term. */
+  text: string;
+  /** Named search index to target, when the caller picked one. */
+  indexName?: string;
+}
+/**
+ * Reads the `$search` / `$index` controls of an aggregate query.
+ *
+ * Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+ * shapes what is left. Every adapter must therefore apply the search predicate
+ * BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+ * describe rows that matched. An adapter that silently ignored the term would
+ * report totals for rows the same search excludes from the leaf list.
+ *
+ * Two rules the leaf search path applies and the grouped path must NOT:
+ * - **No implicit relevance ordering.** Relevance is a property of a row, not
+ *   of a group; after `$group` there is no per-row score left to sort on.
+ *   Grouped results order by `$sort` or not at all.
+ * - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+ *   rows; applying that before `$group` would silently truncate group counts.
+ *
+ * Returns `undefined` when there is nothing to search for, so callers fall
+ * straight through to the plain grouped path.
+ */
+declare function resolveAggregateSearch(controls: {
+  [key: `$${string}`]: unknown;
+} | undefined): TAggregateSearch | undefined;
 //#endregion
-export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAlias };
+export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAggregateSearch, resolveAlias };

package/dist/agg.mjs

@@ -3,5 +3,35 @@
 function resolveAlias(expr) {
 	return expr.$as ?? `${expr.$fn}_${expr.$field}`;
 }
+/**
+* Reads the `$search` / `$index` controls of an aggregate query.
+*
+* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+* shapes what is left. Every adapter must therefore apply the search predicate
+* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+* describe rows that matched. An adapter that silently ignored the term would
+* report totals for rows the same search excludes from the leaf list.
+*
+* Two rules the leaf search path applies and the grouped path must NOT:
+* - **No implicit relevance ordering.** Relevance is a property of a row, not
+*   of a group; after `$group` there is no per-row score left to sort on.
+*   Grouped results order by `$sort` or not at all.
+* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+*   rows; applying that before `$group` would silently truncate group counts.
+*
+* Returns `undefined` when there is nothing to search for, so callers fall
+* straight through to the plain grouped path.
+*/
+function resolveAggregateSearch(controls) {
+	const raw = controls?.$search;
+	if (typeof raw !== "string") return;
+	const text = raw.trim();
+	if (!text) return;
+	const index = controls?.$index;
+	return {
+		text,
+		indexName: typeof index === "string" && index ? index : void 0
+	};
+}
 //#endregion
-export { resolveAlias };
+export { resolveAggregateSearch, resolveAlias };

package/dist/{db-view-Dl0aDTiT.mjs → db-view-BkF2xEGd.mjs}

@@ -1027,13 +1027,11 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return {
 			filter,
 			controls: {
+				...controls,
 				$groupBy: groupBy,
 				$select: select ? new UniquSelect(select, meta.allPhysicalFields) : void 0,
 				$sort: sort,
-				$having: having,
-				$skip: controls.$skip,
-				$limit: controls.$limit,
-				$count: controls.$count
+				$having: having
 			},
 			insights: query.insights
 		};
@@ -2047,6 +2045,11 @@ var AtscriptDbReadable = class {
 				}]);
 			}
 		}
+		const searchTerm = query.controls.$search;
+		if (typeof searchTerm === "string" && searchTerm) {
+			this._ensureSearchable();
+			if (!searchTerm.trim()) return query.controls.$count ? [{ count: 0 }] : [];
+		}
 		guardAggregate(this._meta, this.adapter, query);
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
 		return (await this.adapter.aggregate(dbQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));

package/dist/{db-view-CRBgkEp0.cjs → db-view-hkwQ-fHJ.cjs}

@@ -1027,13 +1027,11 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return {
 			filter,
 			controls: {
+				...controls,
 				$groupBy: groupBy,
 				$select: select ? new UniquSelect(select, meta.allPhysicalFields) : void 0,
 				$sort: sort,
-				$having: having,
-				$skip: controls.$skip,
-				$limit: controls.$limit,
-				$count: controls.$count
+				$having: having
 			},
 			insights: query.insights
 		};
@@ -2047,6 +2045,11 @@ var AtscriptDbReadable = class {
 				}]);
 			}
 		}
+		const searchTerm = query.controls.$search;
+		if (typeof searchTerm === "string" && searchTerm) {
+			this._ensureSearchable();
+			if (!searchTerm.trim()) return query.controls.$count ? [{ count: 0 }] : [];
+		}
 		guardAggregate(this._meta, this.adapter, query);
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
 		return (await this.adapter.aggregate(dbQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-C4JuLcvb.cjs");
-const require_db_view = require("./db-view-CRBgkEp0.cjs");
+const require_db_view = require("./db-view-hkwQ-fHJ.cjs");
 const require_validator = require("./validator-lkCJKuoo.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { n as CasMismatchError, r as DbError, t as CasExhaustedError } from "./db-error-COrO58t5.mjs";
-import { A as isGeoIndexableType, C as unsupportedOperatorMessage, D as UniquSelect, E as FieldMappingStrategy, M as NoopLogger, O as TableMetadata, S as sortFieldNames, T as DocumentFieldMapper, _ as guardAggregate, a as decomposePatch, b as guardPaths, c as createFailureCollector, d as AtscriptDbReadable, f as resolveDesignType, g as collectQueryPaths, h as classifyQueryPath, i as assertNoVersionWrites, j as isGeoPointType, k as findAncestorInSet, l as IntegrityStrategy, m as checkHavingKeys, n as isAtscriptDbView, o as ApplicationIntegrity, p as assertGeoPoint, r as AtscriptDbTable, s as BaseDbAdapter, t as AtscriptDbView, u as NativeIntegrity, v as guardFilter, w as RelationalFieldMapper, x as guardQuery, y as guardPath } from "./db-view-Dl0aDTiT.mjs";
+import { A as isGeoIndexableType, C as unsupportedOperatorMessage, D as UniquSelect, E as FieldMappingStrategy, M as NoopLogger, O as TableMetadata, S as sortFieldNames, T as DocumentFieldMapper, _ as guardAggregate, a as decomposePatch, b as guardPaths, c as createFailureCollector, d as AtscriptDbReadable, f as resolveDesignType, g as collectQueryPaths, h as classifyQueryPath, i as assertNoVersionWrites, j as isGeoPointType, k as findAncestorInSet, l as IntegrityStrategy, m as checkHavingKeys, n as isAtscriptDbView, o as ApplicationIntegrity, p as assertGeoPoint, r as AtscriptDbTable, s as BaseDbAdapter, t as AtscriptDbView, u as NativeIntegrity, v as guardFilter, w as RelationalFieldMapper, x as guardQuery, y as guardPath } from "./db-view-BkF2xEGd.mjs";
 import { a as forceNavNonOptional, c as getKeyProps, l as isEmptyObject, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator, u as isPlainObject } from "./validator-CeD_fqyW.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";

package/dist/sync.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_view = require("./db-view-CRBgkEp0.cjs");
+const require_db_view = require("./db-view-hkwQ-fHJ.cjs");
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {

package/dist/sync.mjs

@@ -1,4 +1,4 @@
-import { M as NoopLogger } from "./db-view-Dl0aDTiT.mjs";
+import { M as NoopLogger } from "./db-view-BkF2xEGd.mjs";
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db",
-  "version": "0.1.129",
+  "version": "0.1.130",
   "description": "Database adapter utilities for atscript.",
   "keywords": [
     "atscript",