@atscript/db-sql-tools 0.1.163 → 0.1.165

package/dist/index.cjs

@@ -245,6 +245,32 @@ function orFragment(parts, params) {
 		params
 	};
 }
+/**
+* The relevance ORDER BY of a fulltext search with no `$sort` (since 0.1.165):
+* rows an exact-number equality matched first (`CASE WHEN … THEN 0 ELSE 1 END`,
+* only next to a text rank — `n` binds each equality once), then `textRank`
+* (its direction included, e.g. `ts_rank(…) DESC`), then the primary-key
+* columns ascending (quoted, after `prefix`). Params: the CASE's, then the
+* text rank's.
+*/
+function searchRankOrder(dialect, opts) {
+	const parts = [];
+	const params = [];
+	const { exactEqualities: eqs, n, textRank } = opts;
+	if (textRank && n !== void 0 && eqs.length > 0) {
+		parts.push(`CASE WHEN ${eqs.join(" OR ")} THEN 0 ELSE 1 END`);
+		for (let i = 0; i < eqs.length; i++) params.push(n);
+	}
+	if (textRank) {
+		parts.push(textRank.sql);
+		params.push(...textRank.params);
+	}
+	for (const col of opts.pkColumns) parts.push(`${opts.prefix ?? ""}${dialect.quoteIdentifier(col)} ASC`);
+	return {
+		sql: parts.join(", "),
+		params
+	};
+}
 //#endregion
 //#region src/arith.ts
 /**
@@ -501,10 +527,140 @@ function getVisitor(dialect) {
 */
 function buildWhere(dialect, filter, opts) {
 	if (!filter || Object.keys(filter).length === 0) return EMPTY_AND;
-	return (0, _uniqu_core.walkFilter)(filter, opts || (0, _atscript_db.containsRelationFilter)(filter) ? createFilterVisitor(dialect, {
+	const visitor = opts || (0, _atscript_db.containsRelationFilter)(filter) ? createFilterVisitor(dialect, {
 		...opts,
 		aliasSeq: opts?.aliasSeq ?? { n: 0 }
-	}) : getVisitor(dialect)) ?? EMPTY_AND;
+	}) : getVisitor(dialect);
+	return (0, _uniqu_core.walkFilter)(collapseOrEqualities(filter), visitor) ?? EMPTY_AND;
+}
+/**
+* Rewrites every `$or` whose branches include several equalities on ONE
+* field (`{ f: v }`, `{ f: { $eq: v } }`, `{ f: { $in: [...] } }`, v a
+* non-null scalar, all of one JS type) into one `{ f: { $in: [...] } }`
+* branch (since 0.1.165).
+* Same rows, but one predicate instead of an OR chain whose depth grows with
+* the batch: SQLite refuses an expression tree deeper than 1000, which a
+* per-row key filter over a large batch reached. Composite, null, operator
+* and lone branches are kept as they are. Returns `filter` itself when
+* nothing changes.
+*/
+function collapseOrEqualities(filter) {
+	if (!filter || typeof filter !== "object") return filter;
+	const node = filter;
+	let out;
+	const and = node.$and;
+	if (Array.isArray(and)) {
+		const next = collapseEach(and);
+		if (next !== and) (out ??= { ...node }).$and = next;
+	}
+	const or = node.$or;
+	if (Array.isArray(or)) {
+		let next = collapseEach(or);
+		if (next.length > 1 && mayRepeatField(next)) next = mergeEqualityBranches(next);
+		if (next !== or) (out ??= { ...node }).$or = next;
+	}
+	const not = node.$not;
+	if (not && typeof not === "object") {
+		const next = collapseOrEqualities(not);
+		if (next !== not) (out ??= { ...node }).$not = next;
+	}
+	return out ?? filter;
+}
+/** `list` with each object child collapsed — the same array when none changed (copied on the first change). */
+function collapseEach(list) {
+	let copy;
+	for (let i = 0; i < list.length; i++) {
+		const child = list[i];
+		const next = child && typeof child === "object" ? collapseOrEqualities(child) : child;
+		if (next !== child) (copy ??= list.slice())[i] = next;
+	}
+	return copy ?? list;
+}
+/** The sole key of a one-key, non-operator branch — allocation-free. */
+function soleField(branch) {
+	if (!branch || typeof branch !== "object" || Array.isArray(branch)) return void 0;
+	let field;
+	for (const key in branch) {
+		if (field !== void 0) return void 0;
+		field = key;
+	}
+	return field === void 0 || field.startsWith("$") ? void 0 : field;
+}
+/**
+* Cheap pre-check for {@link mergeEqualityBranches}: whether two branches
+* share a sole field (long lists go straight to the merge pass).
+*/
+function mayRepeatField(branches) {
+	if (branches.length > 64) return true;
+	for (let i = 1; i < branches.length; i++) {
+		const field = soleField(branches[i]);
+		if (field === void 0) continue;
+		for (let j = 0; j < i; j++) if (soleField(branches[j]) === field) return true;
+	}
+	return false;
+}
+/** The `$or` branches with the equalities of each repeated field merged into one `$in`. */
+function mergeEqualityBranches(branches) {
+	const eqs = branches.map(equalityOf);
+	const fields = /* @__PURE__ */ new Map();
+	for (const eq of eqs) {
+		if (!eq) continue;
+		let entry = fields.get(eq.field);
+		if (!entry) fields.set(eq.field, entry = { count: 0 });
+		entry.count++;
+		for (const v of eq.values) {
+			const t = typeof v;
+			entry.type = entry.type === void 0 || entry.type === t ? t : "mixed";
+		}
+	}
+	const merges = (field) => {
+		const entry = fields.get(field);
+		return entry.count > 1 && entry.type !== "mixed";
+	};
+	if (!eqs.some((eq) => eq && merges(eq.field))) return branches;
+	const out = [];
+	for (let i = 0; i < branches.length; i++) {
+		const eq = eqs[i];
+		if (!eq || !merges(eq.field)) {
+			out.push(branches[i]);
+			continue;
+		}
+		const entry = fields.get(eq.field);
+		if (!entry.values) {
+			entry.values = [];
+			out.push({ [eq.field]: { $in: entry.values } });
+		}
+		entry.values.push(...eq.values);
+	}
+	return out;
+}
+/** `{ field, values }` of a one-field equality branch, else `undefined`. */
+function equalityOf(branch) {
+	if (!branch || typeof branch !== "object" || Array.isArray(branch)) return void 0;
+	const keys = Object.keys(branch);
+	if (keys.length !== 1 || keys[0].startsWith("$")) return void 0;
+	const field = keys[0];
+	const value = branch[field];
+	if (isScalar(value)) return {
+		field,
+		values: [value]
+	};
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const ops = Object.keys(value);
+	if (ops.length !== 1) return void 0;
+	const operand = value[ops[0]];
+	if (ops[0] === "$eq" && isScalar(operand)) return {
+		field,
+		values: [operand]
+	};
+	if (ops[0] === "$in" && Array.isArray(operand) && operand.every(isScalar)) return {
+		field,
+		values: operand
+	};
+}
+function isScalar(value) {
+	const t = typeof value;
+	return t === "string" || t === "number" || t === "boolean" || t === "bigint";
 }
 //#endregion
 //#region src/from-source.ts
@@ -1255,13 +1411,19 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 * `table` may be a derived source (a pruned view read, since 0.1.153).
 * `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
+* `defaultOrder` (since 0.1.165) is the ORDER BY list used when `$sort` orders
+* nothing — a search's relevance order; its params bind after the WHERE's.
 */
-function buildSelect(dialect, table, where, controls, lock) {
+function buildSelect(dialect, table, where, controls, lock, defaultOrder) {
 	const cols = buildProjection(dialect, controls?.$select);
 	let sql = `SELECT ${fromSourceHint(table)}${cols} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const params = [...where.params];
 	const orderBy = orderByList(dialect, controls?.$sort, controls?.$nulls);
 	if (orderBy) sql += ` ORDER BY ${orderBy}`;
+	else if (defaultOrder?.sql) {
+		sql += ` ORDER BY ${defaultOrder.sql}`;
+		params.push(...defaultOrder.params);
+	}
 	if (controls?.$limit !== void 0) {
 		sql += ` LIMIT ?`;
 		params.push(controls.$limit);
@@ -1357,12 +1519,14 @@ const SQL_DEFAULT = Symbol("SQL_DEFAULT");
 * and an omitted PK must never be nulled or re-defaulted. Static value
 * defaults are filled SDK-side before the adapter sees the row, so only
 * native function defaults are flagged. Ignored and derived descriptors in
-* `fields` are skipped, so `fieldDescriptors` works too.
+* `fields` are skipped, so `fieldDescriptors` works too. Insert-only columns
+* (`number.timestamp.created`, since 0.1.165) are left out: a replace keeps
+* their stored value.
 */
 function replaceColumnsFor(fields, nativeFns) {
 	const out = [];
 	for (const fd of fields) {
-		if (fd.ignored || fd.isPrimaryKey || fd.derived) continue;
+		if (fd.ignored || fd.isPrimaryKey || fd.derived || fd.insertOnly) continue;
 		const def = fd.defaultValue;
 		out.push({
 			name: fd.physicalName,
@@ -1911,6 +2075,7 @@ exports.refActionToSql = refActionToSql;
 exports.renameGeoDistance = renameGeoDistance;
 exports.renderArith = renderArith;
 exports.replaceColumnsFor = replaceColumnsFor;
+exports.searchRankOrder = searchRankOrder;
 exports.sqlStringLiteral = sqlStringLiteral;
 exports.sqlTimeZoneLiteral = sqlTimeZoneLiteral;
 exports.stripPartitionRowNumber = stripPartitionRowNumber;

package/dist/index.d.cts

@@ -269,6 +269,21 @@ declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 /** ORs predicate parts (parenthesized when several); no parts matches nothing. */
 declare function orFragment(parts: string[], params: unknown[]): TSqlFragment;
+/**
+ * The relevance ORDER BY of a fulltext search with no `$sort` (since 0.1.165):
+ * rows an exact-number equality matched first (`CASE WHEN … THEN 0 ELSE 1 END`,
+ * only next to a text rank — `n` binds each equality once), then `textRank`
+ * (its direction included, e.g. `ts_rank(…) DESC`), then the primary-key
+ * columns ascending (quoted, after `prefix`). Params: the CASE's, then the
+ * text rank's.
+ */
+declare function searchRankOrder(dialect: Pick<SqlDialect, "quoteIdentifier">, opts: {
+  /** One `?`-equality per integer member (`"ref_no" = ?`). */exactEqualities: readonly string[]; /** The whole-number term, when the search term is one. */
+  n: number | undefined;
+  textRank?: TSqlFragment;
+  pkColumns: readonly string[]; /** Prepended to each quoted primary-key column (`t.`). */
+  prefix?: string;
+}): TSqlFragment;
 //#endregion
 //#region src/arith.d.ts
 /** Why {@link renderArith} cannot render an expression. */
@@ -566,8 +581,10 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  * `table` may be a derived source (a pruned view read, since 0.1.153).
  * `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
+ * `defaultOrder` (since 0.1.165) is the ORDER BY list used when `$sort` orders
+ * nothing — a search's relevance order; its params bind after the WHERE's.
  */
-declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls, lock?: TDbReadLock): TSqlFragment;
+declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls, lock?: TDbReadLock, defaultOrder?: TSqlFragment): TSqlFragment;
 /**
  * The row-locking clause of a locking read — `" FOR UPDATE"`,
  * `" FOR SHARE NOWAIT"`, `" FOR UPDATE SKIP LOCKED"`, … (PostgreSQL and
@@ -627,7 +644,9 @@ interface TReplaceColumn {
  * and an omitted PK must never be nulled or re-defaulted. Static value
  * defaults are filled SDK-side before the adapter sees the row, so only
  * native function defaults are flagged. Ignored and derived descriptors in
- * `fields` are skipped, so `fieldDescriptors` works too.
+ * `fields` are skipped, so `fieldDescriptors` works too. Insert-only columns
+ * (`number.timestamp.created`, since 0.1.165) are left out: a replace keeps
+ * their stored value.
  */
 declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: ReadonlySet<TDbDefaultFn>): TReplaceColumn[];
 /**
@@ -882,4 +901,4 @@ declare function buildJsonColumnCopy(dialect: SqlDialect, table: string, source:
  */
 declare function buildJsonifyText(dialect: SqlDialect, table: string, column: string): string;
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, type TSqlWriteLimit, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, type TSqlWriteLimit, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, searchRankOrder, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };

package/dist/index.d.mts

@@ -269,6 +269,21 @@ declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 /** ORs predicate parts (parenthesized when several); no parts matches nothing. */
 declare function orFragment(parts: string[], params: unknown[]): TSqlFragment;
+/**
+ * The relevance ORDER BY of a fulltext search with no `$sort` (since 0.1.165):
+ * rows an exact-number equality matched first (`CASE WHEN … THEN 0 ELSE 1 END`,
+ * only next to a text rank — `n` binds each equality once), then `textRank`
+ * (its direction included, e.g. `ts_rank(…) DESC`), then the primary-key
+ * columns ascending (quoted, after `prefix`). Params: the CASE's, then the
+ * text rank's.
+ */
+declare function searchRankOrder(dialect: Pick<SqlDialect, "quoteIdentifier">, opts: {
+  /** One `?`-equality per integer member (`"ref_no" = ?`). */exactEqualities: readonly string[]; /** The whole-number term, when the search term is one. */
+  n: number | undefined;
+  textRank?: TSqlFragment;
+  pkColumns: readonly string[]; /** Prepended to each quoted primary-key column (`t.`). */
+  prefix?: string;
+}): TSqlFragment;
 //#endregion
 //#region src/arith.d.ts
 /** Why {@link renderArith} cannot render an expression. */
@@ -566,8 +581,10 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  * `table` may be a derived source (a pruned view read, since 0.1.153).
  * `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
+ * `defaultOrder` (since 0.1.165) is the ORDER BY list used when `$sort` orders
+ * nothing — a search's relevance order; its params bind after the WHERE's.
  */
-declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls, lock?: TDbReadLock): TSqlFragment;
+declare function buildSelect(dialect: SqlDialect, table: TSqlFromSource, where: TSqlFragment, controls?: DbControls, lock?: TDbReadLock, defaultOrder?: TSqlFragment): TSqlFragment;
 /**
  * The row-locking clause of a locking read — `" FOR UPDATE"`,
  * `" FOR SHARE NOWAIT"`, `" FOR UPDATE SKIP LOCKED"`, … (PostgreSQL and
@@ -627,7 +644,9 @@ interface TReplaceColumn {
  * and an omitted PK must never be nulled or re-defaulted. Static value
  * defaults are filled SDK-side before the adapter sees the row, so only
  * native function defaults are flagged. Ignored and derived descriptors in
- * `fields` are skipped, so `fieldDescriptors` works too.
+ * `fields` are skipped, so `fieldDescriptors` works too. Insert-only columns
+ * (`number.timestamp.created`, since 0.1.165) are left out: a replace keeps
+ * their stored value.
  */
 declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: ReadonlySet<TDbDefaultFn>): TReplaceColumn[];
 /**
@@ -882,4 +901,4 @@ declare function buildJsonColumnCopy(dialect: SqlDialect, table: string, source:
  */
 declare function buildJsonifyText(dialect: SqlDialect, table: string, column: string): string;
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, type TSqlWriteLimit, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlDerivedSource, type TSqlFragment, type TSqlFromSource, type TSqlWriteLimit, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, searchRankOrder, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };

package/dist/index.mjs

@@ -244,6 +244,32 @@ function orFragment(parts, params) {
 		params
 	};
 }
+/**
+* The relevance ORDER BY of a fulltext search with no `$sort` (since 0.1.165):
+* rows an exact-number equality matched first (`CASE WHEN … THEN 0 ELSE 1 END`,
+* only next to a text rank — `n` binds each equality once), then `textRank`
+* (its direction included, e.g. `ts_rank(…) DESC`), then the primary-key
+* columns ascending (quoted, after `prefix`). Params: the CASE's, then the
+* text rank's.
+*/
+function searchRankOrder(dialect, opts) {
+	const parts = [];
+	const params = [];
+	const { exactEqualities: eqs, n, textRank } = opts;
+	if (textRank && n !== void 0 && eqs.length > 0) {
+		parts.push(`CASE WHEN ${eqs.join(" OR ")} THEN 0 ELSE 1 END`);
+		for (let i = 0; i < eqs.length; i++) params.push(n);
+	}
+	if (textRank) {
+		parts.push(textRank.sql);
+		params.push(...textRank.params);
+	}
+	for (const col of opts.pkColumns) parts.push(`${opts.prefix ?? ""}${dialect.quoteIdentifier(col)} ASC`);
+	return {
+		sql: parts.join(", "),
+		params
+	};
+}
 //#endregion
 //#region src/arith.ts
 /**
@@ -500,10 +526,140 @@ function getVisitor(dialect) {
 */
 function buildWhere(dialect, filter, opts) {
 	if (!filter || Object.keys(filter).length === 0) return EMPTY_AND;
-	return walkFilter(filter, opts || containsRelationFilter(filter) ? createFilterVisitor(dialect, {
+	const visitor = opts || containsRelationFilter(filter) ? createFilterVisitor(dialect, {
 		...opts,
 		aliasSeq: opts?.aliasSeq ?? { n: 0 }
-	}) : getVisitor(dialect)) ?? EMPTY_AND;
+	}) : getVisitor(dialect);
+	return walkFilter(collapseOrEqualities(filter), visitor) ?? EMPTY_AND;
+}
+/**
+* Rewrites every `$or` whose branches include several equalities on ONE
+* field (`{ f: v }`, `{ f: { $eq: v } }`, `{ f: { $in: [...] } }`, v a
+* non-null scalar, all of one JS type) into one `{ f: { $in: [...] } }`
+* branch (since 0.1.165).
+* Same rows, but one predicate instead of an OR chain whose depth grows with
+* the batch: SQLite refuses an expression tree deeper than 1000, which a
+* per-row key filter over a large batch reached. Composite, null, operator
+* and lone branches are kept as they are. Returns `filter` itself when
+* nothing changes.
+*/
+function collapseOrEqualities(filter) {
+	if (!filter || typeof filter !== "object") return filter;
+	const node = filter;
+	let out;
+	const and = node.$and;
+	if (Array.isArray(and)) {
+		const next = collapseEach(and);
+		if (next !== and) (out ??= { ...node }).$and = next;
+	}
+	const or = node.$or;
+	if (Array.isArray(or)) {
+		let next = collapseEach(or);
+		if (next.length > 1 && mayRepeatField(next)) next = mergeEqualityBranches(next);
+		if (next !== or) (out ??= { ...node }).$or = next;
+	}
+	const not = node.$not;
+	if (not && typeof not === "object") {
+		const next = collapseOrEqualities(not);
+		if (next !== not) (out ??= { ...node }).$not = next;
+	}
+	return out ?? filter;
+}
+/** `list` with each object child collapsed — the same array when none changed (copied on the first change). */
+function collapseEach(list) {
+	let copy;
+	for (let i = 0; i < list.length; i++) {
+		const child = list[i];
+		const next = child && typeof child === "object" ? collapseOrEqualities(child) : child;
+		if (next !== child) (copy ??= list.slice())[i] = next;
+	}
+	return copy ?? list;
+}
+/** The sole key of a one-key, non-operator branch — allocation-free. */
+function soleField(branch) {
+	if (!branch || typeof branch !== "object" || Array.isArray(branch)) return void 0;
+	let field;
+	for (const key in branch) {
+		if (field !== void 0) return void 0;
+		field = key;
+	}
+	return field === void 0 || field.startsWith("$") ? void 0 : field;
+}
+/**
+* Cheap pre-check for {@link mergeEqualityBranches}: whether two branches
+* share a sole field (long lists go straight to the merge pass).
+*/
+function mayRepeatField(branches) {
+	if (branches.length > 64) return true;
+	for (let i = 1; i < branches.length; i++) {
+		const field = soleField(branches[i]);
+		if (field === void 0) continue;
+		for (let j = 0; j < i; j++) if (soleField(branches[j]) === field) return true;
+	}
+	return false;
+}
+/** The `$or` branches with the equalities of each repeated field merged into one `$in`. */
+function mergeEqualityBranches(branches) {
+	const eqs = branches.map(equalityOf);
+	const fields = /* @__PURE__ */ new Map();
+	for (const eq of eqs) {
+		if (!eq) continue;
+		let entry = fields.get(eq.field);
+		if (!entry) fields.set(eq.field, entry = { count: 0 });
+		entry.count++;
+		for (const v of eq.values) {
+			const t = typeof v;
+			entry.type = entry.type === void 0 || entry.type === t ? t : "mixed";
+		}
+	}
+	const merges = (field) => {
+		const entry = fields.get(field);
+		return entry.count > 1 && entry.type !== "mixed";
+	};
+	if (!eqs.some((eq) => eq && merges(eq.field))) return branches;
+	const out = [];
+	for (let i = 0; i < branches.length; i++) {
+		const eq = eqs[i];
+		if (!eq || !merges(eq.field)) {
+			out.push(branches[i]);
+			continue;
+		}
+		const entry = fields.get(eq.field);
+		if (!entry.values) {
+			entry.values = [];
+			out.push({ [eq.field]: { $in: entry.values } });
+		}
+		entry.values.push(...eq.values);
+	}
+	return out;
+}
+/** `{ field, values }` of a one-field equality branch, else `undefined`. */
+function equalityOf(branch) {
+	if (!branch || typeof branch !== "object" || Array.isArray(branch)) return void 0;
+	const keys = Object.keys(branch);
+	if (keys.length !== 1 || keys[0].startsWith("$")) return void 0;
+	const field = keys[0];
+	const value = branch[field];
+	if (isScalar(value)) return {
+		field,
+		values: [value]
+	};
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const ops = Object.keys(value);
+	if (ops.length !== 1) return void 0;
+	const operand = value[ops[0]];
+	if (ops[0] === "$eq" && isScalar(operand)) return {
+		field,
+		values: [operand]
+	};
+	if (ops[0] === "$in" && Array.isArray(operand) && operand.every(isScalar)) return {
+		field,
+		values: operand
+	};
+}
+function isScalar(value) {
+	const t = typeof value;
+	return t === "string" || t === "number" || t === "boolean" || t === "bigint";
 }
 //#endregion
 //#region src/from-source.ts
@@ -1254,13 +1410,19 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 * `table` may be a derived source (a pruned view read, since 0.1.153).
 * `lock` (since 0.1.162) appends a row-locking clause — see {@link readLockSql}.
+* `defaultOrder` (since 0.1.165) is the ORDER BY list used when `$sort` orders
+* nothing — a search's relevance order; its params bind after the WHERE's.
 */
-function buildSelect(dialect, table, where, controls, lock) {
+function buildSelect(dialect, table, where, controls, lock, defaultOrder) {
 	const cols = buildProjection(dialect, controls?.$select);
 	let sql = `SELECT ${fromSourceHint(table)}${cols} FROM ${fromSourceSql(dialect, table)} WHERE ${where.sql}`;
 	const params = [...where.params];
 	const orderBy = orderByList(dialect, controls?.$sort, controls?.$nulls);
 	if (orderBy) sql += ` ORDER BY ${orderBy}`;
+	else if (defaultOrder?.sql) {
+		sql += ` ORDER BY ${defaultOrder.sql}`;
+		params.push(...defaultOrder.params);
+	}
 	if (controls?.$limit !== void 0) {
 		sql += ` LIMIT ?`;
 		params.push(controls.$limit);
@@ -1356,12 +1518,14 @@ const SQL_DEFAULT = Symbol("SQL_DEFAULT");
 * and an omitted PK must never be nulled or re-defaulted. Static value
 * defaults are filled SDK-side before the adapter sees the row, so only
 * native function defaults are flagged. Ignored and derived descriptors in
-* `fields` are skipped, so `fieldDescriptors` works too.
+* `fields` are skipped, so `fieldDescriptors` works too. Insert-only columns
+* (`number.timestamp.created`, since 0.1.165) are left out: a replace keeps
+* their stored value.
 */
 function replaceColumnsFor(fields, nativeFns) {
 	const out = [];
 	for (const fd of fields) {
-		if (fd.ignored || fd.isPrimaryKey || fd.derived) continue;
+		if (fd.ignored || fd.isPrimaryKey || fd.derived || fd.insertOnly) continue;
 		const def = fd.defaultValue;
 		out.push({
 			name: fd.physicalName,
@@ -1850,4 +2014,4 @@ function buildJsonifyText(dialect, table, column) {
 	return `UPDATE ${dialect.quoteTable(table)} SET ${col} = ${dialect.jsonFromText(col)} WHERE ${col} IS NOT NULL`;
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, InsertSqlCache, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildViewSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, nullsOrderSql, nullsPlacementOf, numericOutOfRangeError, orFragment, orderByList, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, readLockSql, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, searchRankOrder, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount, writeLimitWhere };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.163",
+  "version": "0.1.165",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -38,11 +38,11 @@
   },
   "devDependencies": {
     "@uniqu/core": "^0.1.15",
-    "unplugin-atscript": "^0.1.109"
+    "unplugin-atscript": "^0.2.1"
   },
   "peerDependencies": {
     "@uniqu/core": "^0.1.15",
-    "@atscript/db": "^0.1.163"
+    "@atscript/db": "^0.1.165"
   },
   "scripts": {
     "build": "vp pack",