feat: consolidate search packages into unified graphile-search plugin

[pyramation]

feat: consolidate search packages into unified graphile-search plugin

Summary

Consolidates 4 individual search packages (graphile-tsvector, graphile-bm25, graphile-trgm, graphile-pgvector) into the single graphile-search package. All 4 packages are deleted with no deprecation — codec plugins, operator factories, and adapters now live inside graphile-search with tree-shakable exports.

This builds on the original v1 unified search plugin (adapter pattern) and promotes it from standalone proof-of-concept to the canonical search package.

What was deleted

• graphile/graphile-tsvector/ — entire package
• graphile/graphile-bm25/ — entire package
• graphile/graphile-trgm/ — entire package
• graphile/graphile-pgvector/ — entire package
• CI test jobs for graphile-search-plugin and graphile-pgvector-plugin

What was moved into graphile-search/

• src/codecs/tsvector-codec.ts — tsvector/tsquery type registration (from graphile-tsvector)
• src/codecs/bm25-codec.ts — BM25 index discovery + codec (from graphile-bm25)
• src/codecs/vector-codec.ts — pgvector type registration (from graphile-pgvector)
• src/codecs/operator-factories.ts — createMatchesOperatorFactory + createTrgmOperatorFactories (from graphile-tsvector/graphile-trgm)
• src/codecs/index.ts — barrel re-exports

What was updated

• graphile-search/src/index.ts — tree-shakable exports for all codecs, types, and operator factories
• graphile-search/src/preset.ts — UnifiedSearchPreset now includes codec plugins + operator factories
• graphile-search/src/adapters/bm25.ts — imports from ../codecs/bm25-codec instead of graphile-bm25
• graphile-settings/src/presets/constructive-preset.ts — imports from graphile-search instead of 4 packages
• graphile-settings/src/plugins/index.ts — consolidated re-exports from graphile-search only
• graphile-settings/package.json — removed 4 old deps, added graphile-search
• .github/workflows/run-tests.yaml — removed old package test entries, added graphile-search + graphile-settings
• Test file — added mega query v2 (fullTextSearch + searchScore with composite ordering)
• Snapshot files — updated graphql/server-test and graphql/test snapshots to match unified plugin output (description format changes, new fields/enums)

Architecture (unchanged from v1)

┌─────────────────────────────────────┐
│      createUnifiedSearchPlugin      │
│   (iterates adapters, wires hooks)  │
├─────────────────────────────────────┤
│ tsvectorAdapter │ bm25Adapter       │
│ trgmAdapter     │ pgvectorAdapter   │
├─────────────────────────────────────┤
│           src/codecs/               │
│  tsvector-codec │ bm25-codec        │
│  vector-codec   │ operator-factories│
└─────────────────────────────────────┘

Tree-shakable imports

// Full preset (includes codecs + adapters + operator factories)
import { UnifiedSearchPreset } from 'graphile-search';

// Individual codecs (tree-shakable)
import { TsvectorCodecPlugin, Bm25CodecPlugin, VectorCodecPlugin } from 'graphile-search';

// Operator factories for connection filter integration
import { createMatchesOperatorFactory, createTrgmOperatorFactories } from 'graphile-search';

Generated GraphQL fields (unchanged from v1)

• Filter inputs: {algorithm}{Column} (e.g. bm25Body, trgmTitle, vectorEmbedding)
• Composite filter: fullTextSearch: String — fans out to all text-compatible adapters
• Score fields: {column}{Algorithm}{Metric} (e.g. bodyBm25Score, titleTrgmSimilarity)
• OrderBy enums: {COLUMN}_{ALGORITHM}_{METRIC}_ASC/DESC + SEARCH_SCORE_ASC/DESC
• Composite searchScore: Normalized 0..1 aggregating all active search signals

Updates since last revision (consolidation + integration tests)

1. Moved codec plugins internally — tsvector, bm25, pgvector codecs now live in graphile-search/src/codecs/ instead of separate packages
2. Moved operator factories — createMatchesOperatorFactory and createTrgmOperatorFactories extracted into graphile-search/src/codecs/operator-factories.ts
3. Deleted 4 packages — graphile-tsvector, graphile-bm25, graphile-trgm, graphile-pgvector removed entirely (68 files deleted, 6719 lines removed)
4. Updated all imports — ConstructivePreset, graphile-settings plugins, test files now import from graphile-search
5. Added mega query v2 — New test demonstrating fullTextSearch composite filter + searchScore composite ordering
6. Tree-shakable exports — codec plugins, types, and operator factories can be imported individually from graphile-search
7. CI cleanup — removed test jobs for deleted packages
8. Snapshot updates — Fixed test snapshots for graphql/server-test and graphql/test to match unified plugin output (TRGM description format changes, new searchScore fields, new orderBy enums, fullTextSearch composite filter)
9. Field naming fix — Renamed test references from fullTextTsv → tsvTsv to match new adapter naming convention
10. NEW: Search integration test — Added comprehensive end-to-end test suite (search.integration.test.ts) with SQL fixture (search-seed/) that validates:
    • tsvector full-text search (filter, score, orderBy)
    • pg_trgm fuzzy matching (filter, score, orderBy)
    • pgvector similarity search (filter, score, orderBy — conditional on extension availability)
    • Composite searchScore and fullTextSearch fields
    • Mega query v1 (per-algorithm filters + multi-column orderBy)
    • Mega query v2 (fullTextSearch composite + SEARCH_SCORE_DESC)
    • Schema introspection (validates all expected fields/filters/enums are present)

Review & Testing Checklist for Human

• Verify no external consumers — confirm nothing outside the monorepo imports graphile-tsvector, graphile-bm25, graphile-trgm, or graphile-pgvector (breaking change with no deprecation)
• Verify snapshot changes are correct — CI snapshots were manually edited to match expected output. Review the snapshot diffs carefully to ensure no unintended schema changes slipped through (especially TRGM descriptions, searchScore fields, new orderBy enums, fullTextSearch filter)
• Verify BM25 module-level store fallback — the BM25 adapter relies on bm25IndexStore from ../codecs/bm25-codec (module-level shared state). If the codec plugin doesn't populate it during gather phase, BM25 filters will silently fail
• Review search integration test — the new search.integration.test.ts creates a real PostgreSQL database, spins up an HTTP server, and executes GraphQL queries. Verify the SQL fixture and test queries accurately represent real-world usage
• Run codegen — regenerate GraphQL types since field names changed ({column}{Algorithm}{Metric} naming convention)

Test Plan

1. ✅ CI is green — 41/41 checks passing (includes all 21 unified search tests + 61 new search integration tests)
2. ✅ Local pnpm build completed successfully with no type errors
3. ✅ Search integration tests validate end-to-end behavior:
   • SQL fixture creates articles table with tsvector, text (trgm), and vector columns
   • Tests run against real PostgreSQL with extensions (pg_trgm, pgvector when available)
   • Validates all filter inputs, score fields, orderBy enums, composite fields
   • Tests both mega query v1 (per-algorithm) and v2 (fullTextSearch + searchScore)
4. ⚠️ BM25 NOT tested in integration suite (no pg_textsearch extension in CI image) — manual testing recommended if BM25 is critical
5. ⏳ Manual testing recommended:
   • Test fullTextSearch composite filter against multiple columns
   • Test searchScore composite ordering with various combinations
   • Verify null handling (vector/geom columns when filters don't apply)
   • Test with missing extensions to ensure graceful degradation
   • Verify the search fixture creates correct indexes (GIN on tsvector, GIN on trgm)

Notes

• Breaking change: No deprecation period — the 4 individual packages are deleted entirely
• Module-level state: BM25 adapter relies on module-level bm25IndexStore populated by codec plugin during gather phase
• Cumulative diff: This PR builds on feat: add v5-native graphile-connection-filter plugin #797–feat: v5-native filter system — complete rewrite with declarative API, full test coverage, and new plugins #813 (connection filter rewrite, plugin renames). The diff includes ~50 files changed, but only the graphile-search/ consolidation + integration tests are new to this PR
• Snapshot testing: Snapshots were manually edited based on CI diff output rather than regenerated from a local DB. Extra scrutiny recommended during review.
• Field naming convention: The tsvTsv stutter (algorithm prefix + column name collision) is intentional and unavoidable when DB columns are named after their types (e.g. a tsvector column named tsv)
• Grafast behavior: Grafast (v5) silently ignores unknown input fields rather than returning validation errors (intentional v5 behavior)
• Integration test coverage: The new search integration test validates tsvector, trgm, and pgvector (when available) but does NOT test BM25 (pg_textsearch extension not available in CI). BM25 is tested via the existing graphile-search unit tests only.
• SQL fixture design: The search-seed fixture uses triggers to auto-populate tsvector columns from title+body. Verify the trigger fires correctly before queries execute.

---

⚠️ Note: This PR builds on top of PRs #797–#813. The cumulative diff includes the entire PR chain (connection filter rewrite, plugin renames, etc.). The NEW code specific to this PR is the consolidation of the 4 packages into graphile-search/ + the search integration test suite.

Devin Session: https://app.devin.ai/sessions/cf88f3fd383b4421a5169ed01612899d
Requested by: @pyramation

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Devin Review found 2 potential issues.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🔴 trgm operator resolve returns null which is passed unchecked to $where.where()

The similarTo and wordSimilarTo operators in graphile-trgm/src/preset.ts:38-41 and graphile-trgm/src/preset.ts:63-66 can return null when the input value is an empty string (e.g., { value: "" }). The TrgmSearchInput.value field is String! (non-null), but an empty string passes GraphQL validation. When resolve returns null, graphile-connection-filter/src/plugins/operatorApply.ts:110 calls $where.where(null) without checking for null, which will pass null to PgCondition.where() — a method that expects a SQL fragment. This can cause a runtime error or produce invalid SQL.

Trace through the code path

1. User sends filter: { name: { similarTo: { value: "" } } }
2. operatorApply.ts:45-89 validates the outer value object (non-null ✓)
3. operatorApply.ts:105 calls resolve(sqlIdentifier, sqlValue, {value: "", threshold: undefined}, ...)
4. preset.ts:40: !value evaluates !"" → true → returns null
5. operatorApply.ts:110: $where.where(null) is called

Suggested change

	const fragment = resolve(sqlIdentifier, sqlValue, value, $where, {
	fieldName: parentFieldName ?? null,
	operatorName: fieldName,
	});
	$where.where(fragment);
	// Generate the WHERE clause fragment and apply it
	const fragment = resolve(sqlIdentifier, sqlValue, value, $where, {
	fieldName: parentFieldName ?? null,
	operatorName: fieldName,
	});
	if (fragment != null) {
	$where.where(fragment);
	}

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 Duplicate connectionFilterOperatorFactories from sub-presets are silently lost when used standalone

Each sub-preset (PgSearchPreset, TrgmSearchPreset, GraphilePostgisPreset) defines its own connectionFilterOperatorFactories array. When these presets are composed via extends, graphile-config replaces arrays (not concatenates). In ConstructivePreset this is handled by explicitly collecting all factories at graphile/graphile-settings/src/presets/constructive-preset.ts:159-163. However, if a user composes the sub-presets directly (e.g., extends: [PgSearchPreset(), TrgmSearchPreset(), GraphilePostgisPreset]), only the last preset's factories survive — the earlier presets' matches and similarTo/wordSimilarTo operators would be silently dropped. The TrgmSearchPreset() preset at graphile/graphile-trgm/src/preset.ts:96-99 and PgSearchPreset() at graphile/graphile-tsvector/src/preset.ts:72-75 each declare their factories independently with no guidance that they'll be overwritten when combined.

---

Was this helpful? React with 👍 or 👎 to provide feedback.