@atscript/db-postgres 0.1.164 → 0.1.165

package/dist/index.cjs

@@ -311,8 +311,8 @@ function buildInsert(table, data) {
 function buildInsertMany(table, rows, columns) {
 	return (0, _atscript_db_sql_tools.buildInsertMany)(pgDialect, table, rows, columns);
 }
-function buildSelect(table, where, controls, lock) {
-	return (0, _atscript_db_sql_tools.buildSelect)(pgDialect, table, where, controls, lock);
+function buildSelect(table, where, controls, lock, defaultOrder) {
+	return (0, _atscript_db_sql_tools.buildSelect)(pgDialect, table, where, controls, lock, defaultOrder);
 }
 function buildUpdate(table, data, where, limit, ops, versionColumn, expectedVersion) {
 	return (0, _atscript_db_sql_tools.buildUpdate)(pgDialect, table, data, where, limit, ops, versionColumn, expectedVersion);
@@ -931,11 +931,19 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	_mapConstraintError(error) {
 		if (error && typeof error === "object" && "code" in error) {
 			const err = error;
-			if (err.code === "23505") throw new _atscript_db.DbError("CONFLICT", [{
-				path: this._extractFieldFromConstraint(err.constraint) ?? "",
-				message: err.detail ?? err.message
-			}]);
-			if (err.code === "23503") throw new _atscript_db.DbError("FK_VIOLATION", this._mapFkError(err.detail ?? err.message, err.constraint));
+			if (err.code === "23505") throw (0, _atscript_db.constraintViolation)("CONFLICT", {
+				name: err.constraint,
+				columns: keyColumns(err.detail),
+				primaryKey: err.constraint?.endsWith("_pkey")
+			}, err.detail ?? err.message);
+			if (err.code === "23503") {
+				const detail = err.detail ?? err.message;
+				const referencedBy = detail.match(/is still referenced from table "([^"]+)"/)?.[1];
+				throw (0, _atscript_db.constraintViolation)("FK_VIOLATION", referencedBy ? { referencedBy } : {
+					name: err.constraint,
+					columns: keyColumns(detail)
+				}, detail);
+			}
 			const contention = PG_CONTENTION_CODES[err.code];
 			if (contention) throw new _atscript_db.DbError(contention, [{
 				path: "",
@@ -944,30 +952,6 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		}
 		throw error;
 	}
-	_extractFieldFromConstraint(constraint) {
-		if (!constraint) return;
-		const tableName = this._table.tableName;
-		if (constraint.startsWith(`${tableName}_`) && constraint.endsWith("_key")) {
-			const fieldPart = constraint.slice(tableName.length + 1, -4);
-			const fd = this._table.fieldDescriptors.find((f) => f.physicalName === fieldPart);
-			if (fd) return fd.path;
-		}
-		return constraint;
-	}
-	_mapFkError(detail, constraint) {
-		const fkMatch = detail.match(/Key \(([^)]+)\)/);
-		if (fkMatch) {
-			const physicalCol = fkMatch[1].split(",")[0].trim();
-			return [{
-				path: this._table.fieldDescriptors.find((f) => f.physicalName === physicalCol)?.path ?? physicalCol,
-				message: detail
-			}];
-		}
-		return [{
-			path: constraint ?? "",
-			message: detail
-		}];
-	}
 	async insertOne(data) {
 		const insert = buildInsert(this.resolveTableName(), data);
 		const sql = insert.sql + this._pk().returning;
@@ -1942,7 +1926,8 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		const indexes = [];
 		const { all: ftAll, def: ftDefault } = this._fulltextIndexes();
 		for (const index of ftAll) indexes.push({
-			name: index.key,
+			name: index.name,
+			aliases: [index.key],
 			description: (0, _atscript_db.describeFulltext)(index, (names) => `GIN tsvector index on ${names}`),
 			type: "text",
 			fields: this._indexLogicalPaths(index),
@@ -1964,7 +1949,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	async search(text, query, indexName) {
 		if (!text.trim()) return [];
 		const combinedWhere = this._buildSearchWhere(text, query, indexName);
-		const { sql, params } = buildSelect(this.resolveTableName(), combinedWhere, query.controls);
+		const { sql, params } = buildSelect(this.resolveTableName(), combinedWhere, query.controls, void 0, combinedWhere.rank);
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
@@ -1976,7 +1961,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		const combinedWhere = this._buildSearchWhere(text, query, indexName);
 		const tableName = this.resolveTableName();
 		const selectPromise = (async () => {
-			const { sql, params } = buildSelect(tableName, combinedWhere, query.controls);
+			const { sql, params } = buildSelect(tableName, combinedWhere, query.controls, void 0, combinedWhere.rank);
 			this._log(sql, params);
 			return this._exec().all(sql, params);
 		})();
@@ -1994,37 +1979,80 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			count
 		};
 	}
+	/**
+	* The search predicate (AND the request filter) and its relevance order
+	* (`rank`, since 0.1.165) — used as the ORDER BY when the read has no
+	* `$sort`: exact-number hits first, then `ts_rank` over the text members
+	* (per-field weights through `setweight` buckets), then the primary key.
+	* Grouped searches use only the predicate.
+	*/
 	_buildSearchWhere(text, query, indexName) {
 		const fulltextIndex = this._getFulltextIndex(indexName);
-		if (!fulltextIndex) throw new Error("No fulltext index found for search");
+		if (!fulltextIndex) throw new Error((0, _atscript_db.searchIndexNotFoundMessage)(indexName));
 		const { text: textFields, integer: integerFields } = (0, _atscript_db.splitFulltextFields)(fulltextIndex);
 		const where = buildWhere(query.filter);
 		const n = integerFields.length > 0 ? (0, _atscript_db.searchTermInteger)(text) : void 0;
 		const parts = [];
 		const params = [];
+		const equalities = n === void 0 ? [] : integerFields.map((f) => `${qi(f.name)} = CAST(? AS BIGINT)`);
+		let textRank;
 		if (textFields.length > 0) {
-			const tsvectorExpr = this._buildTsvectorExpr(textFields);
-			parts.push(`to_tsvector('english', ${tsvectorExpr}) @@ plainto_tsquery('english', ?)`);
+			const tsvector = `to_tsvector('english', ${this._buildTsvectorExpr(textFields)})`;
+			parts.push(`${tsvector} @@ plainto_tsquery('english', ?)`);
 			params.push(text);
+			textRank = {
+				sql: `${this._buildTsRankExpr(textFields, tsvector)} DESC`,
+				params: [text]
+			};
 		}
-		if (n !== void 0) for (const f of integerFields) {
-			parts.push(`${qi(f.name)} = CAST(? AS BIGINT)`);
+		for (const eq of equalities) {
+			parts.push(eq);
 			params.push(n);
 		}
 		const clause = (0, _atscript_db_sql_tools.orFragment)(parts, params);
 		return {
 			sql: where.sql === "1=1" ? clause.sql : `${where.sql} AND ${clause.sql}`,
-			params: [...where.params, ...clause.params]
+			params: [...where.params, ...clause.params],
+			rank: (0, _atscript_db_sql_tools.searchRankOrder)(pgDialect, {
+				exactEqualities: equalities,
+				n,
+				textRank,
+				pkColumns: this._table.primaryKeys.map((key) => this._table.physicalPath(key))
+			})
 		};
 	}
+	/**
+	* `ts_rank(…)` over the text members (one `?` — the search text). Without
+	* per-field weights it ranks `tsvector` — the indexed expression — itself; with them each
+	* member's vector is put in a `setweight` bucket (the distinct weights,
+	* highest first, map to A, B, C, then D for every lower one) and the bucket
+	* weights are passed relative to the highest (`{D, C, B, A}`). The match
+	* predicate keeps the unweighted indexed expression, so the GIN index serves
+	* it unchanged.
+	*/
+	_buildTsRankExpr(fields, tsvector) {
+		const query = `plainto_tsquery('english', ?)`;
+		const distinct = [...new Set(fields.map(weightOf))].toSorted((a, b) => b - a);
+		if (distinct.length <= 1) return `ts_rank(${tsvector}, ${query})`;
+		const letters = [
+			"A",
+			"B",
+			"C",
+			"D"
+		];
+		const bucketOf = (w) => Math.min(distinct.indexOf(w), 3);
+		const top = distinct[0];
+		const bucketWeights = letters.map((_, i) => distinct[Math.min(i, distinct.length - 1)] / top);
+		const vector = fields.map((f) => `setweight(to_tsvector('english', coalesce(${qi(f.name)}, '')), '${letters[bucketOf(weightOf(f))]}')`).join(" || ");
+		return `ts_rank('{${[...bucketWeights].toReversed().map((w) => Number(w.toFixed(6))).join(", ")}}', ${vector}, ${query})`;
+	}
 	/** Builds the tsvector SQL expression for a fulltext index's fields. Must match between index DDL and queries. */
 	_buildTsvectorExpr(fields) {
 		return fields.map((f) => `coalesce(${qi(f.name)}, '')`).join(" || ' ' || ");
 	}
 	_getFulltextIndex(indexName) {
 		const { all, def } = this._fulltextIndexes();
-		if (!indexName) return def;
-		return all.find((index) => index.key === indexName);
+		return indexName ? (0, _atscript_db.resolveFulltextIndex)(all, indexName) : def;
 	}
 	/** The table's fulltext indexes and the default one, built once per table. */
 	_fulltextIndexes() {
@@ -2383,6 +2411,14 @@ function similarityToPgOps(similarity) {
 function vectorToString(vector) {
 	return `[${vector.join(",")}]`;
 }
+/** The columns of a PostgreSQL `Key (a, b)=(…)` detail. */
+function keyColumns(detail) {
+	return (detail?.match(/Key \(([^)]+)\)=/)?.[1])?.split(",").map((c) => c.trim().replace(/^"|"$/g, ""));
+}
+/** A fulltext member's weight (`@db.index.fulltext 'idx', w`), `1` when unset. */
+function weightOf(f) {
+	return f.weight ?? 1;
+}
 //#endregion
 //#region src/pg-driver.ts
 const NO_PARAMS = [];

package/dist/index.d.cts

@@ -213,8 +213,6 @@ declare class PostgresAdapter extends BaseDbAdapter {
   private _wrapConstraintError;
   /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock timeout, else as is. */
   private _mapConstraintError;
-  private _extractFieldFromConstraint;
-  private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
   supportsInsertIgnore(): boolean;
@@ -388,7 +386,24 @@ declare class PostgresAdapter extends BaseDbAdapter {
     data: Array<Record<string, unknown>>;
     count: number;
   }>;
+  /**
+   * The search predicate (AND the request filter) and its relevance order
+   * (`rank`, since 0.1.165) — used as the ORDER BY when the read has no
+   * `$sort`: exact-number hits first, then `ts_rank` over the text members
+   * (per-field weights through `setweight` buckets), then the primary key.
+   * Grouped searches use only the predicate.
+   */
   private _buildSearchWhere;
+  /**
+   * `ts_rank(…)` over the text members (one `?` — the search text). Without
+   * per-field weights it ranks `tsvector` — the indexed expression — itself; with them each
+   * member's vector is put in a `setweight` bucket (the distinct weights,
+   * highest first, map to A, B, C, then D for every lower one) and the bucket
+   * weights are passed relative to the highest (`{D, C, B, A}`). The match
+   * predicate keeps the unweighted indexed expression, so the GIN index serves
+   * it unchanged.
+   */
+  private _buildTsRankExpr;
   /** Builds the tsvector SQL expression for a fulltext index's fields. Must match between index DDL and queries. */
   private _buildTsvectorExpr;
   private _getFulltextIndex;

package/dist/index.d.mts

@@ -213,8 +213,6 @@ declare class PostgresAdapter extends BaseDbAdapter {
   private _wrapConstraintError;
   /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock timeout, else as is. */
   private _mapConstraintError;
-  private _extractFieldFromConstraint;
-  private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
   supportsInsertIgnore(): boolean;
@@ -388,7 +386,24 @@ declare class PostgresAdapter extends BaseDbAdapter {
     data: Array<Record<string, unknown>>;
     count: number;
   }>;
+  /**
+   * The search predicate (AND the request filter) and its relevance order
+   * (`rank`, since 0.1.165) — used as the ORDER BY when the read has no
+   * `$sort`: exact-number hits first, then `ts_rank` over the text members
+   * (per-field weights through `setweight` buckets), then the primary key.
+   * Grouped searches use only the predicate.
+   */
   private _buildSearchWhere;
+  /**
+   * `ts_rank(…)` over the text members (one `?` — the search text). Without
+   * per-field weights it ranks `tsvector` — the indexed expression — itself; with them each
+   * member's vector is put in a `setweight` bucket (the distinct weights,
+   * highest first, map to A, B, C, then D for every lower one) and the bucket
+   * weights are passed relative to the highest (`{D, C, B, A}`). The match
+   * predicate keeps the unweighted indexed expression, so the GIN index serves
+   * it unchanged.
+   */
+  private _buildTsRankExpr;
   /** Builds the tsvector SQL expression for a fulltext index's fields. Must match between index DDL and queries. */
   private _buildTsvectorExpr;
   private _getFulltextIndex;

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, createChangeRecorder, defaultFulltextIndex, describeFulltext, fkKey, isColumnTypeChanged, searchTermInteger, splitFulltextFields, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, constraintViolation, createChangeRecorder, defaultFulltextIndex, describeFulltext, fkKey, isColumnTypeChanged, resolveFulltextIndex, searchIndexNotFoundMessage, searchTermInteger, splitFulltextFields, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, chunkInsertRows, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, parseRegexString, quotedJsonPathSegments, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, unquoteSqlStringLiteral, vectorDistanceSource, writeLimitWhere } from "@atscript/db-sql-tools";
+import { SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, chunkInsertRows, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, parseRegexString, quotedJsonPathSegments, renameGeoDistance, replaceColumnsFor, searchRankOrder, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, unquoteSqlStringLiteral, vectorDistanceSource, writeLimitWhere } from "@atscript/db-sql-tools";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/insert-ignore.ts
 /**
@@ -310,8 +310,8 @@ function buildInsert$1(table, data) {
 function buildInsertMany$1(table, rows, columns) {
 	return buildInsertMany(pgDialect, table, rows, columns);
 }
-function buildSelect$1(table, where, controls, lock) {
-	return buildSelect(pgDialect, table, where, controls, lock);
+function buildSelect$1(table, where, controls, lock, defaultOrder) {
+	return buildSelect(pgDialect, table, where, controls, lock, defaultOrder);
 }
 function buildUpdate$1(table, data, where, limit, ops, versionColumn, expectedVersion) {
 	return buildUpdate(pgDialect, table, data, where, limit, ops, versionColumn, expectedVersion);
@@ -930,11 +930,19 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	_mapConstraintError(error) {
 		if (error && typeof error === "object" && "code" in error) {
 			const err = error;
-			if (err.code === "23505") throw new DbError("CONFLICT", [{
-				path: this._extractFieldFromConstraint(err.constraint) ?? "",
-				message: err.detail ?? err.message
-			}]);
-			if (err.code === "23503") throw new DbError("FK_VIOLATION", this._mapFkError(err.detail ?? err.message, err.constraint));
+			if (err.code === "23505") throw constraintViolation("CONFLICT", {
+				name: err.constraint,
+				columns: keyColumns(err.detail),
+				primaryKey: err.constraint?.endsWith("_pkey")
+			}, err.detail ?? err.message);
+			if (err.code === "23503") {
+				const detail = err.detail ?? err.message;
+				const referencedBy = detail.match(/is still referenced from table "([^"]+)"/)?.[1];
+				throw constraintViolation("FK_VIOLATION", referencedBy ? { referencedBy } : {
+					name: err.constraint,
+					columns: keyColumns(detail)
+				}, detail);
+			}
 			const contention = PG_CONTENTION_CODES[err.code];
 			if (contention) throw new DbError(contention, [{
 				path: "",
@@ -943,30 +951,6 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		}
 		throw error;
 	}
-	_extractFieldFromConstraint(constraint) {
-		if (!constraint) return;
-		const tableName = this._table.tableName;
-		if (constraint.startsWith(`${tableName}_`) && constraint.endsWith("_key")) {
-			const fieldPart = constraint.slice(tableName.length + 1, -4);
-			const fd = this._table.fieldDescriptors.find((f) => f.physicalName === fieldPart);
-			if (fd) return fd.path;
-		}
-		return constraint;
-	}
-	_mapFkError(detail, constraint) {
-		const fkMatch = detail.match(/Key \(([^)]+)\)/);
-		if (fkMatch) {
-			const physicalCol = fkMatch[1].split(",")[0].trim();
-			return [{
-				path: this._table.fieldDescriptors.find((f) => f.physicalName === physicalCol)?.path ?? physicalCol,
-				message: detail
-			}];
-		}
-		return [{
-			path: constraint ?? "",
-			message: detail
-		}];
-	}
 	async insertOne(data) {
 		const insert = buildInsert$1(this.resolveTableName(), data);
 		const sql = insert.sql + this._pk().returning;
@@ -1941,7 +1925,8 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		const indexes = [];
 		const { all: ftAll, def: ftDefault } = this._fulltextIndexes();
 		for (const index of ftAll) indexes.push({
-			name: index.key,
+			name: index.name,
+			aliases: [index.key],
 			description: describeFulltext(index, (names) => `GIN tsvector index on ${names}`),
 			type: "text",
 			fields: this._indexLogicalPaths(index),
@@ -1963,7 +1948,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	async search(text, query, indexName) {
 		if (!text.trim()) return [];
 		const combinedWhere = this._buildSearchWhere(text, query, indexName);
-		const { sql, params } = buildSelect$1(this.resolveTableName(), combinedWhere, query.controls);
+		const { sql, params } = buildSelect$1(this.resolveTableName(), combinedWhere, query.controls, void 0, combinedWhere.rank);
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
@@ -1975,7 +1960,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		const combinedWhere = this._buildSearchWhere(text, query, indexName);
 		const tableName = this.resolveTableName();
 		const selectPromise = (async () => {
-			const { sql, params } = buildSelect$1(tableName, combinedWhere, query.controls);
+			const { sql, params } = buildSelect$1(tableName, combinedWhere, query.controls, void 0, combinedWhere.rank);
 			this._log(sql, params);
 			return this._exec().all(sql, params);
 		})();
@@ -1993,37 +1978,80 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			count
 		};
 	}
+	/**
+	* The search predicate (AND the request filter) and its relevance order
+	* (`rank`, since 0.1.165) — used as the ORDER BY when the read has no
+	* `$sort`: exact-number hits first, then `ts_rank` over the text members
+	* (per-field weights through `setweight` buckets), then the primary key.
+	* Grouped searches use only the predicate.
+	*/
 	_buildSearchWhere(text, query, indexName) {
 		const fulltextIndex = this._getFulltextIndex(indexName);
-		if (!fulltextIndex) throw new Error("No fulltext index found for search");
+		if (!fulltextIndex) throw new Error(searchIndexNotFoundMessage(indexName));
 		const { text: textFields, integer: integerFields } = splitFulltextFields(fulltextIndex);
 		const where = buildWhere(query.filter);
 		const n = integerFields.length > 0 ? searchTermInteger(text) : void 0;
 		const parts = [];
 		const params = [];
+		const equalities = n === void 0 ? [] : integerFields.map((f) => `${qi(f.name)} = CAST(? AS BIGINT)`);
+		let textRank;
 		if (textFields.length > 0) {
-			const tsvectorExpr = this._buildTsvectorExpr(textFields);
-			parts.push(`to_tsvector('english', ${tsvectorExpr}) @@ plainto_tsquery('english', ?)`);
+			const tsvector = `to_tsvector('english', ${this._buildTsvectorExpr(textFields)})`;
+			parts.push(`${tsvector} @@ plainto_tsquery('english', ?)`);
 			params.push(text);
+			textRank = {
+				sql: `${this._buildTsRankExpr(textFields, tsvector)} DESC`,
+				params: [text]
+			};
 		}
-		if (n !== void 0) for (const f of integerFields) {
-			parts.push(`${qi(f.name)} = CAST(? AS BIGINT)`);
+		for (const eq of equalities) {
+			parts.push(eq);
 			params.push(n);
 		}
 		const clause = orFragment(parts, params);
 		return {
 			sql: where.sql === "1=1" ? clause.sql : `${where.sql} AND ${clause.sql}`,
-			params: [...where.params, ...clause.params]
+			params: [...where.params, ...clause.params],
+			rank: searchRankOrder(pgDialect, {
+				exactEqualities: equalities,
+				n,
+				textRank,
+				pkColumns: this._table.primaryKeys.map((key) => this._table.physicalPath(key))
+			})
 		};
 	}
+	/**
+	* `ts_rank(…)` over the text members (one `?` — the search text). Without
+	* per-field weights it ranks `tsvector` — the indexed expression — itself; with them each
+	* member's vector is put in a `setweight` bucket (the distinct weights,
+	* highest first, map to A, B, C, then D for every lower one) and the bucket
+	* weights are passed relative to the highest (`{D, C, B, A}`). The match
+	* predicate keeps the unweighted indexed expression, so the GIN index serves
+	* it unchanged.
+	*/
+	_buildTsRankExpr(fields, tsvector) {
+		const query = `plainto_tsquery('english', ?)`;
+		const distinct = [...new Set(fields.map(weightOf))].toSorted((a, b) => b - a);
+		if (distinct.length <= 1) return `ts_rank(${tsvector}, ${query})`;
+		const letters = [
+			"A",
+			"B",
+			"C",
+			"D"
+		];
+		const bucketOf = (w) => Math.min(distinct.indexOf(w), 3);
+		const top = distinct[0];
+		const bucketWeights = letters.map((_, i) => distinct[Math.min(i, distinct.length - 1)] / top);
+		const vector = fields.map((f) => `setweight(to_tsvector('english', coalesce(${qi(f.name)}, '')), '${letters[bucketOf(weightOf(f))]}')`).join(" || ");
+		return `ts_rank('{${[...bucketWeights].toReversed().map((w) => Number(w.toFixed(6))).join(", ")}}', ${vector}, ${query})`;
+	}
 	/** Builds the tsvector SQL expression for a fulltext index's fields. Must match between index DDL and queries. */
 	_buildTsvectorExpr(fields) {
 		return fields.map((f) => `coalesce(${qi(f.name)}, '')`).join(" || ' ' || ");
 	}
 	_getFulltextIndex(indexName) {
 		const { all, def } = this._fulltextIndexes();
-		if (!indexName) return def;
-		return all.find((index) => index.key === indexName);
+		return indexName ? resolveFulltextIndex(all, indexName) : def;
 	}
 	/** The table's fulltext indexes and the default one, built once per table. */
 	_fulltextIndexes() {
@@ -2382,6 +2410,14 @@ function similarityToPgOps(similarity) {
 function vectorToString(vector) {
 	return `[${vector.join(",")}]`;
 }
+/** The columns of a PostgreSQL `Key (a, b)=(…)` detail. */
+function keyColumns(detail) {
+	return (detail?.match(/Key \(([^)]+)\)=/)?.[1])?.split(",").map((c) => c.trim().replace(/^"|"$/g, ""));
+}
+/** A fulltext member's weight (`@db.index.fulltext 'idx', w`), `1` when unset. */
+function weightOf(f) {
+	return f.weight ?? 1;
+}
 //#endregion
 //#region src/pg-driver.ts
 const NO_PARAMS = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-postgres",
-  "version": "0.1.164",
+  "version": "0.1.165",
   "description": "PostgreSQL adapter for @atscript/db with pg (node-postgres) driver support.",
   "keywords": [
     "atscript",
@@ -43,20 +43,20 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.109",
-    "@atscript/typescript": "^0.1.109",
+    "@atscript/core": "^0.2.1",
+    "@atscript/typescript": "^0.2.1",
     "@types/pg": "^8.11.0",
     "@uniqu/core": "^0.1.15",
     "pg": "^8.13.0",
-    "unplugin-atscript": "^0.1.109"
+    "unplugin-atscript": "^0.2.1"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.109",
-    "@atscript/typescript": "^0.1.109",
+    "@atscript/core": "^0.2.1",
+    "@atscript/typescript": "^0.2.1",
     "@uniqu/core": "^0.1.15",
     "pg": ">=8.0.0",
-    "@atscript/db": "^0.1.164",
-    "@atscript/db-sql-tools": "^0.1.164"
+    "@atscript/db": "^0.1.165",
+    "@atscript/db-sql-tools": "^0.1.165"
   },
   "peerDependenciesMeta": {
     "pg": {