graphile-search 1.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# graphile-search
+
+Unified PostGraphile v5 search plugin — abstracts tsvector, BM25, pg_trgm, and pgvector behind a single adapter-based architecture with composite `searchScore`.
+
+## Overview
+
+Instead of separate plugins per algorithm, `graphile-search` uses an **adapter pattern** where each search algorithm (tsvector, BM25, pg_trgm, pgvector) implements a ~50-line adapter. A single core plugin iterates all adapters and wires them into the Graphile v5 hook system.
+
+## Usage
+
+```typescript
+import { UnifiedSearchPreset } from 'graphile-search';
+
+const preset = {
+  extends: [
+    UnifiedSearchPreset(),
+  ],
+};
+```
+
+### Custom configuration
+
+```typescript
+import { UnifiedSearchPreset } from 'graphile-search';
+
+const preset = {
+  extends: [
+    UnifiedSearchPreset({
+      tsvector: { filterPrefix: 'fullText', tsConfig: 'english' },
+      bm25: true,
+      trgm: { defaultThreshold: 0.2 },
+      pgvector: { defaultMetric: 'COSINE' },
+      searchScoreWeights: { bm25: 0.5, trgm: 0.3, tsv: 0.2 },
+    }),
+  ],
+};
+```
+
+## Features
+
+- **4 search algorithms** via adapters: tsvector (ts_rank), BM25 (pg_textsearch), pg_trgm (similarity), pgvector (distance)
+- **Per-algorithm score fields**: `{column}{Algorithm}{Metric}` (e.g. `bodyBm25Score`, `titleTrgmSimilarity`)
+- **Composite `searchScore`**: Normalized 0..1 aggregating all active search signals
+- **OrderBy enums**: `{COLUMN}_{ALGORITHM}_{METRIC}_ASC/DESC` + `SEARCH_SCORE_ASC/DESC`
+- **Filter fields**: `{algorithm}{Column}` on connection filter input types
+- **Hybrid search**: Combine multiple algorithms in a single query
+- **Zero config**: Auto-discovers columns and indexes per adapter
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│        Unified Search Plugin        │
+│  (iterates adapters, wires hooks)   │
+├─────────────────────────────────────┤
+│ Adapter: tsvector  │ Adapter: bm25  │
+│ Adapter: trgm      │ Adapter: vector│
+└─────────────────────────────────────┘
+```
+
+Each adapter implements the `SearchAdapter` interface:
+- `detectColumns()` — discover eligible columns on a table
+- `registerTypes()` — register custom GraphQL input types
+- `getFilterTypeName()` — return the filter input type name
+- `buildFilterApply()` — generate WHERE + score SQL fragments
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/adapters/bm25.d.ts

@@ -0,0 +1,32 @@
+/**
+ * BM25 Search Adapter
+ *
+ * Detects text columns with BM25 indexes (via pg_textsearch) and generates
+ * BM25 relevance scoring. Wraps the same SQL logic as graphile-bm25.
+ *
+ * Requires the Bm25CodecPlugin to be loaded first (for index discovery).
+ * The adapter reads from the bm25IndexStore populated during the gather phase.
+ */
+import type { SearchAdapter } from '../types';
+/**
+ * BM25 index info discovered during gather phase.
+ */
+export interface Bm25IndexInfo {
+    schemaName: string;
+    tableName: string;
+    columnName: string;
+    indexName: string;
+}
+export interface Bm25AdapterOptions {
+    /**
+     * Filter prefix for BM25 filter fields.
+     * @default 'bm25'
+     */
+    filterPrefix?: string;
+    /**
+     * External BM25 index store. If not provided, the adapter will attempt
+     * to read from the build object's `pgBm25IndexStore`.
+     */
+    bm25IndexStore?: Map<string, Bm25IndexInfo>;
+}
+export declare function createBm25Adapter(options?: Bm25AdapterOptions): SearchAdapter;

package/adapters/bm25.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * BM25 Search Adapter
+ *
+ * Detects text columns with BM25 indexes (via pg_textsearch) and generates
+ * BM25 relevance scoring. Wraps the same SQL logic as graphile-bm25.
+ *
+ * Requires the Bm25CodecPlugin to be loaded first (for index discovery).
+ * The adapter reads from the bm25IndexStore populated during the gather phase.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBm25Adapter = createBm25Adapter;
+const bm25_codec_1 = require("../codecs/bm25-codec");
+function isTextCodec(codec) {
+    const name = codec?.name;
+    return name === 'text' || name === 'varchar' || name === 'bpchar';
+}
+function createBm25Adapter(options = {}) {
+    const { filterPrefix = 'bm25', bm25IndexStore } = options;
+    function getIndexStore(build) {
+        if (bm25IndexStore)
+            return bm25IndexStore;
+        // Try build.pgBm25IndexStore (set by standalone Bm25SearchPlugin's build hook)
+        const buildStore = build.pgBm25IndexStore;
+        if (buildStore && buildStore.size > 0)
+            return buildStore;
+        // Fall back to module-level store populated by Bm25CodecPlugin's gather phase
+        if (bm25_codec_1.bm25IndexStore && bm25_codec_1.bm25IndexStore.size > 0)
+            return bm25_codec_1.bm25IndexStore;
+        return undefined;
+    }
+    function getBm25IndexForAttribute(codec, attributeName, build) {
+        const store = getIndexStore(build);
+        if (!store)
+            return undefined;
+        const pg = codec?.extensions?.pg;
+        if (!pg)
+            return undefined;
+        const key = `${pg.schemaName}.${pg.name}.${attributeName}`;
+        return store.get(key);
+    }
+    return {
+        name: 'bm25',
+        scoreSemantics: {
+            metric: 'score',
+            lowerIsBetter: true,
+            range: null, // unbounded negative
+        },
+        filterPrefix,
+        supportsTextSearch: true,
+        buildTextSearchInput(text) {
+            // BM25 filter takes { query: string }
+            return { query: text };
+        },
+        detectColumns(codec, build) {
+            if (!codec?.attributes)
+                return [];
+            const columns = [];
+            for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
+                if (!isTextCodec(attribute.codec))
+                    continue;
+                const bm25Index = getBm25IndexForAttribute(codec, attributeName, build);
+                if (!bm25Index)
+                    continue;
+                columns.push({ attributeName, adapterData: bm25Index });
+            }
+            return columns;
+        },
+        registerTypes(build) {
+            const { graphql: { GraphQLString, GraphQLFloat, GraphQLNonNull }, } = build;
+            // Register input type for BM25 search.
+            // Wrapped in try/catch because another plugin may have already
+            // registered 'Bm25SearchInput'. Graphile throws on duplicate
+            // registrations, so we catch and ignore.
+            try {
+                build.registerInputObjectType('Bm25SearchInput', {}, () => ({
+                    description: 'Input for BM25 ranked text search. Provide a search query string and optional score threshold.',
+                    fields: () => ({
+                        query: {
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'The search query text. Uses pg_textsearch BM25 ranking.',
+                        },
+                        threshold: {
+                            type: GraphQLFloat,
+                            description: 'Maximum BM25 score threshold (negative values). Only rows with score <= threshold are returned.',
+                        },
+                    }),
+                }), 'UnifiedSearchPlugin (bm25 adapter) registering Bm25SearchInput type');
+            }
+            catch {
+                // Already registered — safe to ignore
+            }
+        },
+        getFilterTypeName(_build) {
+            return 'Bm25SearchInput';
+        },
+        buildFilterApply(sql, alias, column, filterValue, _build) {
+            if (filterValue == null)
+                return null;
+            const { query, threshold } = filterValue;
+            if (!query || typeof query !== 'string' || query.trim().length === 0)
+                return null;
+            const bm25Index = column.adapterData;
+            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+            // Use quoteQualifiedIdentifier to produce the qualified index name
+            const qualifiedIndexName = `"${bm25Index.schemaName}"."${bm25Index.indexName}"`;
+            const bm25queryExpr = sql `to_bm25query(${sql.value(query)}, ${sql.value(qualifiedIndexName)})`;
+            const scoreExpr = sql `(${columnExpr} <@> ${bm25queryExpr})`;
+            let whereClause = null;
+            if (threshold !== undefined && threshold !== null) {
+                whereClause = sql `${scoreExpr} < ${sql.value(threshold)}`;
+            }
+            return {
+                whereClause,
+                scoreExpression: scoreExpr,
+            };
+        },
+    };
+}

package/adapters/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Search Adapter Exports
+ *
+ * Each adapter implements the SearchAdapter interface for a specific
+ * search algorithm. They are plain objects — not Graphile plugins.
+ */
+export { createTsvectorAdapter } from './tsvector';
+export type { TsvectorAdapterOptions } from './tsvector';
+export { createBm25Adapter } from './bm25';
+export type { Bm25AdapterOptions, Bm25IndexInfo } from './bm25';
+export { createTrgmAdapter } from './trgm';
+export type { TrgmAdapterOptions } from './trgm';
+export { createPgvectorAdapter } from './pgvector';
+export type { PgvectorAdapterOptions } from './pgvector';

package/adapters/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Search Adapter Exports
+ *
+ * Each adapter implements the SearchAdapter interface for a specific
+ * search algorithm. They are plain objects — not Graphile plugins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPgvectorAdapter = exports.createTrgmAdapter = exports.createBm25Adapter = exports.createTsvectorAdapter = void 0;
+var tsvector_1 = require("./tsvector");
+Object.defineProperty(exports, "createTsvectorAdapter", { enumerable: true, get: function () { return tsvector_1.createTsvectorAdapter; } });
+var bm25_1 = require("./bm25");
+Object.defineProperty(exports, "createBm25Adapter", { enumerable: true, get: function () { return bm25_1.createBm25Adapter; } });
+var trgm_1 = require("./trgm");
+Object.defineProperty(exports, "createTrgmAdapter", { enumerable: true, get: function () { return trgm_1.createTrgmAdapter; } });
+var pgvector_1 = require("./pgvector");
+Object.defineProperty(exports, "createPgvectorAdapter", { enumerable: true, get: function () { return pgvector_1.createPgvectorAdapter; } });

package/adapters/pgvector.d.ts

@@ -0,0 +1,21 @@
+/**
+ * pgvector Search Adapter
+ *
+ * Detects vector columns and generates distance-based scoring using
+ * pgvector operators (<=> cosine, <-> L2, <#> inner product).
+ * Wraps the same SQL logic as graphile-pgvector but as a SearchAdapter.
+ */
+import type { SearchAdapter } from '../types';
+export interface PgvectorAdapterOptions {
+    /**
+     * Filter prefix for vector filter fields.
+     * @default 'vector'
+     */
+    filterPrefix?: string;
+    /**
+     * Default similarity metric.
+     * @default 'COSINE'
+     */
+    defaultMetric?: 'COSINE' | 'L2' | 'IP';
+}
+export declare function createPgvectorAdapter(options?: PgvectorAdapterOptions): SearchAdapter;

package/adapters/pgvector.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * pgvector Search Adapter
+ *
+ * Detects vector columns and generates distance-based scoring using
+ * pgvector operators (<=> cosine, <-> L2, <#> inner product).
+ * Wraps the same SQL logic as graphile-pgvector but as a SearchAdapter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPgvectorAdapter = createPgvectorAdapter;
+/**
+ * pgvector distance operators.
+ */
+const METRIC_OPERATORS = {
+    COSINE: '<=>',
+    L2: '<->',
+    IP: '<#>',
+};
+function isVectorCodec(codec) {
+    return codec?.name === 'vector';
+}
+function createPgvectorAdapter(options = {}) {
+    const { filterPrefix = 'vector', defaultMetric = 'COSINE' } = options;
+    return {
+        name: 'vector',
+        scoreSemantics: {
+            metric: 'distance',
+            lowerIsBetter: true,
+            range: null, // 0 to infinity
+        },
+        filterPrefix,
+        supportsTextSearch: false,
+        // pgvector requires a vector array, not plain text — no buildTextSearchInput
+        detectColumns(codec, _build) {
+            if (!codec?.attributes)
+                return [];
+            const columns = [];
+            for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
+                if (isVectorCodec(attribute.codec)) {
+                    columns.push({ attributeName });
+                }
+            }
+            return columns;
+        },
+        registerTypes(build) {
+            const { graphql: { GraphQLList, GraphQLNonNull, GraphQLFloat }, } = build;
+            // Register types for vector search.
+            // Wrapped in try/catch because the standalone graphile-pgvector plugin may
+            // have already registered these types in its own init hook.
+            // Graphile throws on duplicate registrations, so we catch and ignore.
+            try {
+                build.registerEnumType('VectorMetric', {}, () => ({
+                    description: 'Similarity metric for vector search',
+                    values: {
+                        COSINE: {
+                            value: 'COSINE',
+                            description: 'Cosine distance (1 - cosine similarity). Range: 0 (identical) to 2 (opposite).',
+                        },
+                        L2: {
+                            value: 'L2',
+                            description: 'Euclidean (L2) distance. Range: 0 (identical) to infinity.',
+                        },
+                        IP: {
+                            value: 'IP',
+                            description: 'Negative inner product. Higher (less negative) = more similar.',
+                        },
+                    },
+                }), 'UnifiedSearchPlugin (pgvector adapter) registering VectorMetric enum');
+            }
+            catch {
+                // Already registered by standalone graphile-pgvector plugin — safe to ignore
+            }
+            try {
+                build.registerInputObjectType('VectorNearbyInput', {}, () => ({
+                    description: 'Input for vector similarity search. Provide a query vector, optional metric, and optional max distance threshold.',
+                    fields: () => {
+                        // getTypeByName is safe inside a thunk (fields callback) — called after init is complete
+                        const VectorMetricEnum = build.getTypeByName('VectorMetric');
+                        return {
+                            vector: {
+                                type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLFloat))),
+                                description: 'Query vector for similarity search.',
+                            },
+                            metric: {
+                                type: VectorMetricEnum,
+                                description: `Similarity metric to use (default: ${defaultMetric}).`,
+                            },
+                            distance: {
+                                type: GraphQLFloat,
+                                description: 'Maximum distance threshold. Only rows within this distance are returned.',
+                            },
+                        };
+                    },
+                }), 'UnifiedSearchPlugin (pgvector adapter) registering VectorNearbyInput type');
+            }
+            catch {
+                // Already registered by standalone graphile-pgvector plugin — safe to ignore
+            }
+        },
+        getFilterTypeName(_build) {
+            return 'VectorNearbyInput';
+        },
+        buildFilterApply(sql, alias, column, filterValue, _build) {
+            if (filterValue == null)
+                return null;
+            const { vector, metric, distance } = filterValue;
+            if (!vector || !Array.isArray(vector) || vector.length === 0)
+                return null;
+            const resolvedMetric = metric || defaultMetric;
+            const operator = METRIC_OPERATORS[resolvedMetric] || METRIC_OPERATORS.COSINE;
+            const vectorString = `[${vector.join(',')}]`;
+            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+            const vectorExpr = sql `${sql.value(vectorString)}::vector`;
+            const distanceExpr = sql `(${columnExpr} ${sql.raw(operator)} ${vectorExpr})`;
+            let whereClause = null;
+            if (distance !== undefined && distance !== null) {
+                whereClause = sql `${distanceExpr} <= ${sql.value(distance)}`;
+            }
+            return {
+                whereClause,
+                scoreExpression: distanceExpr,
+            };
+        },
+    };
+}

package/adapters/trgm.d.ts

@@ -0,0 +1,20 @@
+/**
+ * pg_trgm Search Adapter
+ *
+ * Detects text/varchar columns and generates trigram similarity scoring.
+ * Wraps the same SQL logic as graphile-trgm but as a SearchAdapter.
+ */
+import type { SearchAdapter } from '../types';
+export interface TrgmAdapterOptions {
+    /**
+     * Filter prefix for trgm filter fields.
+     * @default 'trgm'
+     */
+    filterPrefix?: string;
+    /**
+     * Default similarity threshold (0..1). Higher = stricter matching.
+     * @default 0.3
+     */
+    defaultThreshold?: number;
+}
+export declare function createTrgmAdapter(options?: TrgmAdapterOptions): SearchAdapter;

package/adapters/trgm.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * pg_trgm Search Adapter
+ *
+ * Detects text/varchar columns and generates trigram similarity scoring.
+ * Wraps the same SQL logic as graphile-trgm but as a SearchAdapter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrgmAdapter = createTrgmAdapter;
+function isTextCodec(codec) {
+    const name = codec?.name;
+    return name === 'text' || name === 'varchar' || name === 'bpchar';
+}
+function createTrgmAdapter(options = {}) {
+    const { filterPrefix = 'trgm', defaultThreshold = 0.3 } = options;
+    return {
+        name: 'trgm',
+        scoreSemantics: {
+            metric: 'similarity',
+            lowerIsBetter: false,
+            range: [0, 1],
+        },
+        filterPrefix,
+        supportsTextSearch: true,
+        buildTextSearchInput(text) {
+            // trgm filter takes { value: string } — threshold uses adapter default
+            return { value: text };
+        },
+        detectColumns(codec, _build) {
+            if (!codec?.attributes)
+                return [];
+            const columns = [];
+            for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
+                if (isTextCodec(attribute.codec)) {
+                    columns.push({ attributeName });
+                }
+            }
+            return columns;
+        },
+        registerTypes(build) {
+            const { graphql: { GraphQLString, GraphQLFloat, GraphQLNonNull }, } = build;
+            // Register input type for trgm search.
+            // Wrapped in try/catch because the standalone graphile-trgm plugin may
+            // have already registered 'TrgmSearchInput' in its own init hook.
+            // Graphile throws on duplicate registrations, so we catch and ignore.
+            try {
+                build.registerInputObjectType('TrgmSearchInput', {}, () => ({
+                    description: 'Input for pg_trgm fuzzy text matching. Provide a search value and optional similarity threshold.',
+                    fields: () => ({
+                        value: {
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'The text to fuzzy-match against. Typos and misspellings are tolerated.',
+                        },
+                        threshold: {
+                            type: GraphQLFloat,
+                            description: `Minimum similarity threshold (0.0 to 1.0). Higher = stricter matching. Default is ${defaultThreshold}.`,
+                        },
+                    }),
+                }), 'UnifiedSearchPlugin (trgm adapter) registering TrgmSearchInput type');
+            }
+            catch {
+                // Already registered by standalone graphile-trgm plugin — safe to ignore
+            }
+        },
+        getFilterTypeName(_build) {
+            return 'TrgmSearchInput';
+        },
+        buildFilterApply(sql, alias, column, filterValue, _build) {
+            if (filterValue == null)
+                return null;
+            const { value, threshold } = filterValue;
+            if (!value || typeof value !== 'string' || value.trim().length === 0)
+                return null;
+            const th = threshold != null ? threshold : defaultThreshold;
+            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+            const similarityExpr = sql `similarity(${columnExpr}, ${sql.value(value)})`;
+            return {
+                whereClause: sql `${similarityExpr} > ${sql.value(th)}`,
+                scoreExpression: similarityExpr,
+            };
+        },
+    };
+}

package/adapters/tsvector.d.ts

@@ -0,0 +1,20 @@
+/**
+ * tsvector Search Adapter
+ *
+ * Detects tsvector columns and generates ts_rank-based scoring.
+ * Wraps the same SQL logic as graphile-tsvector but as a SearchAdapter.
+ */
+import type { SearchAdapter } from '../types';
+export interface TsvectorAdapterOptions {
+    /**
+     * Filter prefix for tsvector filter fields.
+     * @default 'fullText'
+     */
+    filterPrefix?: string;
+    /**
+     * PostgreSQL text search configuration (e.g. 'english', 'simple').
+     * @default 'english'
+     */
+    tsConfig?: string;
+}
+export declare function createTsvectorAdapter(options?: TsvectorAdapterOptions): SearchAdapter;

package/adapters/tsvector.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * tsvector Search Adapter
+ *
+ * Detects tsvector columns and generates ts_rank-based scoring.
+ * Wraps the same SQL logic as graphile-tsvector but as a SearchAdapter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTsvectorAdapter = createTsvectorAdapter;
+function isTsvectorCodec(codec) {
+    return (codec?.extensions?.pg?.schemaName === 'pg_catalog' &&
+        codec?.extensions?.pg?.name === 'tsvector');
+}
+function createTsvectorAdapter(options = {}) {
+    const { filterPrefix = 'tsv', tsConfig = 'english' } = options;
+    return {
+        name: 'tsv',
+        scoreSemantics: {
+            metric: 'rank',
+            lowerIsBetter: false,
+            range: [0, 1],
+        },
+        filterPrefix,
+        supportsTextSearch: true,
+        buildTextSearchInput(text) {
+            // tsvector filter takes a plain string
+            return text;
+        },
+        detectColumns(codec, _build) {
+            if (!codec?.attributes)
+                return [];
+            const columns = [];
+            for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
+                if (isTsvectorCodec(attribute.codec)) {
+                    columns.push({ attributeName });
+                }
+            }
+            return columns;
+        },
+        registerTypes(_build) {
+            // tsvector uses plain GraphQL String — no custom types needed
+        },
+        getFilterTypeName(_build) {
+            return 'String';
+        },
+        buildFilterApply(sql, alias, column, filterValue, _build) {
+            if (filterValue == null)
+                return null;
+            const val = typeof filterValue === 'string' ? filterValue : String(filterValue);
+            if (val.trim().length === 0)
+                return null;
+            const tsquery = sql `websearch_to_tsquery(${sql.literal(tsConfig)}, ${sql.value(val)})`;
+            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+            return {
+                whereClause: sql `${columnExpr} @@ ${tsquery}`,
+                scoreExpression: sql `ts_rank(${columnExpr}, ${tsquery})`,
+            };
+        },
+    };
+}