graphile-search-plugin 1.1.1 → 3.0.0

package/esm/tsvector-codec.js

@@ -0,0 +1,155 @@
+/**
+ * TsvectorCodecPlugin
+ *
+ * Teaches PostGraphile v5 how to handle PostgreSQL's tsvector and tsquery types.
+ * Without this, tsvector columns are invisible to the schema builder and the
+ * search plugin cannot generate condition fields.
+ *
+ * This plugin:
+ * 1. Creates codecs for tsvector/tsquery via gather.hooks.pgCodecs_findPgCodec
+ * 2. Registers a custom "FullText" scalar type for tsvector columns
+ * 3. Maps tsvector codec to the FullText scalar (isolating filter operators)
+ * 4. Maps tsquery codec to GraphQL String
+ * 5. Optionally hides tsvector columns from output types
+ */
+import { GraphQLString } from 'graphql';
+import sql from 'pg-sql2';
+/**
+ * Creates a TsvectorCodecPlugin with the given options.
+ *
+ * @param options - Plugin configuration
+ * @returns GraphileConfig.Plugin
+ */
+export function createTsvectorCodecPlugin(options = {}) {
+    const { fullTextScalarName = 'FullText', hideTsvectorColumns = false, } = options;
+    return {
+        name: 'TsvectorCodecPlugin',
+        version: '1.0.0',
+        gather: {
+            hooks: {
+                async pgCodecs_findPgCodec(info, event) {
+                    if (event.pgCodec) {
+                        return;
+                    }
+                    const { pgType: type, serviceName } = event;
+                    const pgCatalog = await info.helpers.pgIntrospection.getNamespaceByName(serviceName, 'pg_catalog');
+                    if (!pgCatalog) {
+                        return;
+                    }
+                    if (type.typnamespace === pgCatalog._id && type.typname === 'tsvector') {
+                        event.pgCodec = {
+                            name: 'tsvector',
+                            sqlType: sql.identifier('pg_catalog', 'tsvector'),
+                            fromPg: (value) => value,
+                            toPg: (value) => value,
+                            attributes: undefined,
+                            executor: null,
+                            extensions: {
+                                oid: type._id,
+                                pg: {
+                                    serviceName,
+                                    schemaName: 'pg_catalog',
+                                    name: 'tsvector',
+                                },
+                            },
+                        };
+                        return;
+                    }
+                    if (type.typnamespace === pgCatalog._id && type.typname === 'tsquery') {
+                        event.pgCodec = {
+                            name: 'tsquery',
+                            sqlType: sql.identifier('pg_catalog', 'tsquery'),
+                            fromPg: (value) => value,
+                            toPg: (value) => value,
+                            attributes: undefined,
+                            executor: null,
+                            extensions: {
+                                oid: type._id,
+                                pg: {
+                                    serviceName,
+                                    schemaName: 'pg_catalog',
+                                    name: 'tsquery',
+                                },
+                            },
+                        };
+                        return;
+                    }
+                },
+            },
+        },
+        schema: {
+            hooks: {
+                // Must run before PgCodecsPlugin's init (to avoid "unknown codec" warning)
+                // and before PgConnectionArgFilterPlugin's init (which creates filter
+                // types like FullTextFilter based on codec→GraphQL type mappings).
+                init: {
+                    before: ['PgCodecs', 'PgConnectionArgFilterPlugin'],
+                    callback(_, build) {
+                        const { setGraphQLTypeForPgCodec } = build;
+                        // Register a custom scalar type for tsvector columns.
+                        // This ensures filter operators like `matches` only appear on
+                        // tsvector filters, not on all String filters.
+                        build.registerScalarType(fullTextScalarName, {}, () => ({
+                            description: 'A full-text search tsvector value represented as a string.',
+                            serialize(value) {
+                                return String(value);
+                            },
+                            parseValue(value) {
+                                if (typeof value === 'string') {
+                                    return value;
+                                }
+                                throw new Error(`${fullTextScalarName} must be a string`);
+                            },
+                            parseLiteral(lit) {
+                                if (lit.kind === 'NullValue')
+                                    return null;
+                                if (lit.kind !== 'StringValue') {
+                                    throw new Error(`${fullTextScalarName} must be a string`);
+                                }
+                                return lit.value;
+                            },
+                        }), `TsvectorCodecPlugin registering ${fullTextScalarName} scalar`);
+                        for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
+                            if (codec.name === 'tsvector') {
+                                setGraphQLTypeForPgCodec(codec, 'input', fullTextScalarName);
+                                setGraphQLTypeForPgCodec(codec, 'output', fullTextScalarName);
+                            }
+                            else if (codec.name === 'tsquery') {
+                                setGraphQLTypeForPgCodec(codec, 'input', GraphQLString.name);
+                                setGraphQLTypeForPgCodec(codec, 'output', GraphQLString.name);
+                            }
+                        }
+                        return _;
+                    },
+                },
+            },
+            ...(hideTsvectorColumns
+                ? {
+                    entityBehavior: {
+                        pgCodecAttribute: {
+                            inferred: {
+                                after: ['postInferred'],
+                                provides: ['hideTsvectorColumns'],
+                                callback(behavior, [codec, attributeName]) {
+                                    const attr = codec.attributes?.[attributeName];
+                                    if (attr?.codec?.name === 'tsvector') {
+                                        return [behavior, '-select'];
+                                    }
+                                    return behavior;
+                                },
+                            },
+                        },
+                    },
+                }
+                : {}),
+        },
+    };
+}
+/**
+ * Default static instance using default options.
+ * Maps tsvector to the "FullText" scalar.
+ */
+export const TsvectorCodecPlugin = createTsvectorCodecPlugin();
+export const TsvectorCodecPreset = {
+    plugins: [TsvectorCodecPlugin],
+};

package/esm/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PgSearch Plugin Types
+ *
+ * Type definitions for the PostGraphile v5 search plugin configuration.
+ */
+/**
+ * Plugin configuration options.
+ */
+export interface PgSearchPluginOptions {
+    /**
+     * Prefix for tsvector condition fields.
+     * For example, with prefix 'fullText' and a column named 'tsv',
+     * the generated condition field will be 'fullTextTsv'.
+     * @default 'tsv'
+     */
+    pgSearchPrefix?: string;
+    /**
+     * Whether to hide tsvector columns from output types.
+     * When true, tsvector columns won't appear as fields on the GraphQL object type.
+     * @default false
+     */
+    hideTsvectorColumns?: boolean;
+    /**
+     * Name of the custom GraphQL scalar for tsvector columns.
+     * This scalar isolates filter operators (like `matches`) to tsvector columns
+     * rather than all String fields.
+     * @default 'FullText'
+     */
+    fullTextScalarName?: string;
+    /**
+     * PostgreSQL text search configuration used with `websearch_to_tsquery`.
+     * Must match the configuration used when building your tsvector columns
+     * (e.g., `'english'`, `'simple'`, `'spanish'`).
+     * @default 'english'
+     */
+    tsConfig?: string;
+}

package/esm/types.js

@@ -0,0 +1,6 @@
+/**
+ * PgSearch Plugin Types
+ *
+ * Type definitions for the PostGraphile v5 search plugin configuration.
+ */
+export {};

package/index.d.ts

@@ -1,10 +1,26 @@
-export interface PgSearchPluginOptions {
-    /** Prefix for tsvector fields, default is 'tsv' */
-    pgSearchPrefix?: string;
-}
 /**
- * PgSearchPlugin - Generates search conditions for tsvector columns
+ * PostGraphile v5 Search Plugin
+ *
+ * Provides full-text search capabilities for tsvector columns.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPlugin, PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * // Option 1: Use the preset (recommended)
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ *
+ * // Option 2: Use the plugin directly
+ * const plugin = PgSearchPlugin({ pgSearchPrefix: 'fullText' });
+ * ```
  */
-declare const PgSearchPlugin: (builder: any, options?: PgSearchPluginOptions) => void;
-export { PgSearchPlugin };
-export default PgSearchPlugin;
+export { PgSearchPlugin, createPgSearchPlugin } from './plugin';
+export { PgSearchPreset } from './preset';
+export { TsvectorCodecPlugin, TsvectorCodecPreset, createTsvectorCodecPlugin, } from './tsvector-codec';
+export type { PgSearchPluginOptions } from './types';

package/index.js

@@ -1,60 +1,34 @@
 "use strict";
-// plugins/PgSearchPlugin.ts
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PgSearchPlugin = void 0;
 /**
- * PgSearchPlugin - Generates search conditions for tsvector columns
+ * PostGraphile v5 Search Plugin
+ *
+ * Provides full-text search capabilities for tsvector columns.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPlugin, PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * // Option 1: Use the preset (recommended)
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ *
+ * // Option 2: Use the plugin directly
+ * const plugin = PgSearchPlugin({ pgSearchPrefix: 'fullText' });
+ * ```
  */
-const PgSearchPlugin = (builder, options = {}) => {
-    const { pgSearchPrefix = 'tsv' } = options;
-    builder.hook('GraphQLInputObjectType:fields', (fields, build, context) => {
-        const { inflection } = build;
-        const { scope: { isPgCondition, pgIntrospection: table }, fieldWithHooks } = context;
-        if (!isPgCondition || !table || table.kind !== 'class')
-            return fields;
-        const tsvs = table.attributes.filter((attr) => attr.type.name === 'tsvector');
-        if (!tsvs.length)
-            return fields;
-        return build.extend(fields, tsvs.reduce((memo, attr) => {
-            const fieldName = inflection.camelCase(`${pgSearchPrefix}_${attr.name}`);
-            memo[fieldName] = fieldWithHooks(fieldName, { type: build.graphql.GraphQLString }, {});
-            return memo;
-        }, {}));
-    });
-    builder.hook('GraphQLObjectType:fields:field:args', (args, build, context) => {
-        const { pgSql: sql, inflection } = build;
-        const { scope: { isPgFieldConnection, isPgFieldSimpleCollection, pgFieldIntrospection: procOrTable, pgFieldIntrospectionTable: tableIfProc, }, addArgDataGenerator, } = context;
-        const table = tableIfProc || procOrTable;
-        if ((!isPgFieldConnection && !isPgFieldSimpleCollection) ||
-            !table ||
-            table.kind !== 'class') {
-            return args;
-        }
-        const tsvs = table.attributes.filter((attr) => attr.type.name === 'tsvector');
-        if (!tsvs.length)
-            return args;
-        tsvs.forEach((tsv) => {
-            const conditionFieldName = inflection.camelCase(`${pgSearchPrefix}_${tsv.name}`);
-            addArgDataGenerator(function addSearchCondition({ condition }) {
-                if (!condition || !(conditionFieldName in condition))
-                    return {};
-                const value = condition[conditionFieldName];
-                if (value == null)
-                    return {};
-                return {
-                    pgQuery: (queryBuilder) => {
-                        const tsquery = sql.fragment `websearch_to_tsquery('english', ${sql.value(value)})`;
-                        const tableAlias = queryBuilder.getTableAlias();
-                        // WHERE condition
-                        queryBuilder.where(sql.fragment `${tableAlias}.${sql.identifier(tsv.name)} @@ ${tsquery}`);
-                        // Automatically add ordering by relevance (descending)
-                        queryBuilder.orderBy(sql.fragment `ts_rank(${tableAlias}.${sql.identifier(tsv.name)}, ${tsquery})`, false);
-                    },
-                };
-            });
-        });
-        return args;
-    }, [], ['PgConnectionArgOrderBy']);
-};
-exports.PgSearchPlugin = PgSearchPlugin;
-exports.default = PgSearchPlugin;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTsvectorCodecPlugin = exports.TsvectorCodecPreset = exports.TsvectorCodecPlugin = exports.PgSearchPreset = exports.createPgSearchPlugin = exports.PgSearchPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "PgSearchPlugin", { enumerable: true, get: function () { return plugin_1.PgSearchPlugin; } });
+Object.defineProperty(exports, "createPgSearchPlugin", { enumerable: true, get: function () { return plugin_1.createPgSearchPlugin; } });
+var preset_1 = require("./preset");
+Object.defineProperty(exports, "PgSearchPreset", { enumerable: true, get: function () { return preset_1.PgSearchPreset; } });
+var tsvector_codec_1 = require("./tsvector-codec");
+Object.defineProperty(exports, "TsvectorCodecPlugin", { enumerable: true, get: function () { return tsvector_codec_1.TsvectorCodecPlugin; } });
+Object.defineProperty(exports, "TsvectorCodecPreset", { enumerable: true, get: function () { return tsvector_codec_1.TsvectorCodecPreset; } });
+Object.defineProperty(exports, "createTsvectorCodecPlugin", { enumerable: true, get: function () { return tsvector_codec_1.createTsvectorCodecPlugin; } });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "graphile-search-plugin",
-  "version": "1.1.1",
-  "description": "generate search conditions for your tsvector columns",
+  "version": "3.0.0",
+  "description": "Generate search conditions for your tsvector columns (PostGraphile v5)",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
   "license": "MIT",
@@ -10,8 +10,7 @@
   "types": "index.d.ts",
   "scripts": {
     "clean": "makage clean",
-    "copy": "makage assets",
-    "prepack": "pnpm run build",
+    "prepack": "npm run build",
     "build": "makage build",
     "build:dev": "makage build --dev",
     "lint": "eslint . --fix",
@@ -33,22 +32,37 @@
     "pgpm",
     "plugin",
     "postgres",
-    "graphql"
+    "graphql",
+    "search",
+    "tsvector",
+    "full-text-search"
   ],
   "bugs": {
     "url": "https://github.com/constructive-io/constructive/issues"
   },
   "devDependencies": {
-    "graphile-plugin-connection-filter": "^3.1.1",
-    "graphile-plugin-fulltext-filter": "^3.1.1",
-    "graphile-simple-inflector": "^1.1.1",
-    "graphile-test": "^3.1.1",
-    "makage": "^0.1.12",
-    "pgsql-test": "^3.1.1"
+    "@types/node": "^22.19.1",
+    "graphile-test": "^4.0.0",
+    "makage": "^0.1.10",
+    "pgsql-test": "^4.0.0",
+    "postgraphile-plugin-connection-filter": "^3.0.0-rc.1"
   },
   "dependencies": {
-    "graphile-build": "^4.14.1",
-    "graphql-tag": "2.12.6"
+    "@dataplan/pg": "1.0.0-rc.3",
+    "graphile-build": "^5.0.0-rc.3",
+    "graphile-build-pg": "^5.0.0-rc.3",
+    "graphile-config": "1.0.0-rc.3",
+    "pg-sql2": "^5.0.0-rc.3"
   },
-  "gitHead": "49049ad3ddd762d35625f657cb42fa0862b829a0"
+  "peerDependencies": {
+    "graphql": "^16.9.0",
+    "postgraphile": "^5.0.0-rc.4",
+    "postgraphile-plugin-connection-filter": "^3.0.0-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "postgraphile-plugin-connection-filter": {
+      "optional": true
+    }
+  },
+  "gitHead": "b2daeefe49cdefb3d01ea63cf778fb9b847ab5fe"
 }

package/plugin.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PostGraphile v5 Search Plugin
+ *
+ * Generates search condition fields for tsvector columns. When a search term
+ * is provided via the condition input, this plugin applies a
+ * `column @@ websearch_to_tsquery('english', $value)` WHERE clause and
+ * automatically orders results by `ts_rank` (descending) for relevance.
+ *
+ * Additionally provides:
+ * - `matches` filter operator for postgraphile-plugin-connection-filter
+ * - `fullTextRank` computed fields on output types (null when no search active)
+ * - `FULL_TEXT_RANK_ASC/DESC` orderBy enum values
+ *
+ * Uses the graphile-build hooks API to extend condition input types with
+ * search fields for each tsvector column found on a table's codec.
+ *
+ * ARCHITECTURE NOTE:
+ * Condition field apply functions run during a deferred phase (SQL generation)
+ * on a queryBuilder proxy — NOT on the real PgSelectStep. The rank field plan
+ * runs earlier, during Grafast's planning phase, on the real PgSelectStep.
+ *
+ * To bridge these two phases we use a module-level WeakMap keyed by the SQL
+ * alias object (shared between proxy and PgSelectStep via reference identity).
+ *
+ * The rank field plan creates a `lambda` step that reads the row tuple at a
+ * dynamically-determined index. The condition apply adds `ts_rank(...)` to
+ * the SQL SELECT list via `proxy.selectAndReturnIndex()` and stores the
+ * resulting index in the WeakMap slot. At execution time the lambda reads
+ * the rank value from that index.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+import type { PgSearchPluginOptions } from './types';
+/**
+ * Creates the search plugin with the given options.
+ */
+export declare function createPgSearchPlugin(options?: PgSearchPluginOptions): GraphileConfig.Plugin;
+/**
+ * Creates a PgSearchPlugin with the given options.
+ * This is the main entry point for using the plugin.
+ */
+export declare const PgSearchPlugin: typeof createPgSearchPlugin;
+export default PgSearchPlugin;