graphile-search-plugin 1.1.1 → 3.0.0

package/plugin.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgSearchPlugin = void 0;
+exports.createPgSearchPlugin = createPgSearchPlugin;
+require("graphile-build");
+require("graphile-build-pg");
+const pg_1 = require("@dataplan/pg");
+const ftsRankSlots = new WeakMap();
+/**
+ * FinalizationRegistry for defensive cleanup of ftsRankSlots entries.
+ * WeakMap entries are already eligible for GC when keys are unreachable,
+ * but this provides explicit cleanup and a hook for debugging leaks.
+ */
+const ftsRankCleanup = new FinalizationRegistry((heldValue) => {
+    ftsRankSlots.delete(heldValue);
+});
+function isTsvectorCodec(codec) {
+    return (codec?.extensions?.pg?.schemaName === 'pg_catalog' &&
+        codec?.extensions?.pg?.name === 'tsvector');
+}
+/**
+ * Navigates from a PgSelectSingleStep up to the PgSelectStep.
+ * Uses duck-typing to avoid dependency on exact class names across rc versions.
+ */
+function getPgSelectStep($someStep) {
+    let $step = $someStep;
+    if ($step && typeof $step.getClassStep === 'function') {
+        $step = $step.getClassStep();
+    }
+    if ($step && typeof $step.orderBy === 'function' && $step.id !== undefined) {
+        return $step;
+    }
+    return null;
+}
+/**
+ * Creates the search plugin with the given options.
+ */
+function createPgSearchPlugin(options = {}) {
+    const { pgSearchPrefix = 'tsv', fullTextScalarName = 'FullText', tsConfig = 'english' } = options;
+    return {
+        name: 'PgSearchPlugin',
+        version: '2.0.0',
+        description: 'Generates search conditions for tsvector columns in PostGraphile v5',
+        after: ['PgAttributesPlugin', 'PgConnectionArgFilterPlugin', 'PgConnectionArgFilterOperatorsPlugin', 'AddConnectionFilterOperatorPlugin'],
+        schema: {
+            hooks: {
+                init(_, build) {
+                    const { sql, graphql: { GraphQLString }, } = build;
+                    // Register the `matches` filter operator for the FullText scalar.
+                    // Requires postgraphile-plugin-connection-filter; skip if not loaded.
+                    const addConnectionFilterOperator = build
+                        .addConnectionFilterOperator;
+                    if (typeof addConnectionFilterOperator === 'function') {
+                        const TYPES = build.dataplanPg?.TYPES;
+                        addConnectionFilterOperator(fullTextScalarName, 'matches', {
+                            description: 'Performs a full text search on the field.',
+                            resolveType: () => GraphQLString,
+                            resolveInputCodec: TYPES ? () => TYPES.text : undefined,
+                            resolve(sqlIdentifier, sqlValue, _input, _$where, _details) {
+                                return sql `${sqlIdentifier} @@ websearch_to_tsquery(${sql.literal(tsConfig)}, ${sqlValue})`;
+                            },
+                        });
+                    }
+                    return _;
+                },
+                GraphQLObjectType_fields(fields, build, context) {
+                    const { sql, inflection, graphql: { GraphQLFloat }, grafast: { constant, lambda }, } = build;
+                    const { scope: { isPgClassType, pgCodec }, fieldWithHooks, } = context;
+                    if (!isPgClassType || !pgCodec?.attributes) {
+                        return fields;
+                    }
+                    let newFields = fields;
+                    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                        if (!isTsvectorCodec(attribute.codec))
+                            continue;
+                        const baseFieldName = inflection.attribute({ codec: pgCodec, attributeName });
+                        const fieldName = inflection.camelCase(`${baseFieldName}-rank`);
+                        newFields = build.extend(newFields, {
+                            [fieldName]: fieldWithHooks({ fieldName }, () => ({
+                                description: `Full-text search ranking when filtered by \`${baseFieldName}\`. Returns null when no search condition is active.`,
+                                type: GraphQLFloat,
+                                plan($step) {
+                                    const $select = getPgSelectStep($step);
+                                    if (!$select)
+                                        return constant(null);
+                                    if (typeof $select.setInliningForbidden === 'function') {
+                                        $select.setInliningForbidden();
+                                    }
+                                    // Initialise the WeakMap slot for this query, keyed by the
+                                    // SQL alias (same object ref on PgSelectStep and the proxy).
+                                    const alias = $select.alias;
+                                    if (!ftsRankSlots.has(alias)) {
+                                        ftsRankSlots.set(alias, {
+                                            indices: Object.create(null),
+                                        });
+                                        ftsRankCleanup.register($select, alias);
+                                    }
+                                    // Return a lambda that reads the rank value from the result
+                                    // row at a dynamically-determined index. The index is set
+                                    // by the condition apply (deferred phase) via the proxy's
+                                    // selectAndReturnIndex, and stored in the WeakMap slot.
+                                    const capturedField = baseFieldName;
+                                    const capturedAlias = alias;
+                                    return lambda($step, (row) => {
+                                        if (row == null)
+                                            return null;
+                                        const slot = ftsRankSlots.get(capturedAlias);
+                                        if (!slot || slot.indices[capturedField] === undefined)
+                                            return null;
+                                        const rawValue = row[slot.indices[capturedField]];
+                                        return rawValue == null ? null : parseFloat(rawValue);
+                                    }, true);
+                                },
+                            })),
+                        }, `PgSearchPlugin adding rank field '${fieldName}' for '${attributeName}' on '${pgCodec.name}'`);
+                    }
+                    return newFields;
+                },
+                GraphQLEnumType_values(values, build, context) {
+                    const { sql, inflection, } = build;
+                    const { scope: { isPgRowSortEnum, pgCodec }, } = context;
+                    if (!isPgRowSortEnum || !pgCodec?.attributes) {
+                        return values;
+                    }
+                    let newValues = values;
+                    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                        if (!isTsvectorCodec(attribute.codec))
+                            continue;
+                        const fieldName = inflection.attribute({ codec: pgCodec, attributeName });
+                        const metaKey = `fts_order_${fieldName}`;
+                        const makePlan = (direction) => (step) => {
+                            // The enum apply runs during the PLANNING phase on PgSelectStep.
+                            // Store the requested direction in PgSelectStep._meta so that
+                            // the condition apply (deferred phase) can read it via the
+                            // proxy's getMetaRaw and add the actual ORDER BY clause.
+                            if (typeof step.setMeta === 'function') {
+                                step.setMeta(metaKey, direction);
+                            }
+                        };
+                        const ascName = inflection.constantCase(`${attributeName}_rank_asc`);
+                        const descName = inflection.constantCase(`${attributeName}_rank_desc`);
+                        newValues = build.extend(newValues, {
+                            [ascName]: {
+                                extensions: {
+                                    grafast: {
+                                        apply: makePlan('ASC'),
+                                    },
+                                },
+                            },
+                            [descName]: {
+                                extensions: {
+                                    grafast: {
+                                        apply: makePlan('DESC'),
+                                    },
+                                },
+                            },
+                        }, `PgSearchPlugin adding rank orderBy for '${attributeName}' on '${pgCodec.name}'`);
+                    }
+                    return newValues;
+                },
+                GraphQLInputObjectType_fields(fields, build, context) {
+                    const { inflection, sql, graphql: { GraphQLString }, } = build;
+                    const { scope: { isPgCondition, pgCodec }, fieldWithHooks, } = context;
+                    if (!isPgCondition ||
+                        !pgCodec ||
+                        !pgCodec.attributes ||
+                        pgCodec.isAnonymous) {
+                        return fields;
+                    }
+                    const tsvectorAttributes = Object.entries(pgCodec.attributes).filter(([_name, attr]) => isTsvectorCodec(attr.codec));
+                    if (tsvectorAttributes.length === 0) {
+                        return fields;
+                    }
+                    let newFields = fields;
+                    for (const [attributeName] of tsvectorAttributes) {
+                        const fieldName = inflection.camelCase(`${pgSearchPrefix}_${attributeName}`);
+                        const baseFieldName = inflection.attribute({ codec: pgCodec, attributeName });
+                        newFields = build.extend(newFields, {
+                            [fieldName]: fieldWithHooks({
+                                fieldName,
+                                isPgConnectionConditionInputField: true,
+                            }, {
+                                description: build.wrapDescription(`Full-text search on the \`${attributeName}\` tsvector column using \`websearch_to_tsquery\`.`, 'field'),
+                                type: GraphQLString,
+                                apply: function plan($condition, val) {
+                                    if (val == null)
+                                        return;
+                                    const tsquery = sql `websearch_to_tsquery(${sql.literal(tsConfig)}, ${sql.value(val)})`;
+                                    const columnExpr = sql `${$condition.alias}.${sql.identifier(attributeName)}`;
+                                    // WHERE: column @@ tsquery
+                                    $condition.where(sql `${columnExpr} @@ ${tsquery}`);
+                                    // Add ts_rank to the SELECT list via the proxy's
+                                    // selectAndReturnIndex. This runs during the deferred
+                                    // SQL-generation phase, so the expression goes into
+                                    // info.selects (the live array used for SQL generation).
+                                    const $parent = $condition.dangerouslyGetParent();
+                                    if (typeof $parent.selectAndReturnIndex === 'function') {
+                                        const rankSql = sql `ts_rank(${columnExpr}, ${tsquery})`;
+                                        const wrappedRankSql = sql `${sql.parens(rankSql)}::text`;
+                                        const rankIndex = $parent.selectAndReturnIndex(wrappedRankSql);
+                                        // Store the index in the alias-keyed WeakMap slot so
+                                        // the rank field's lambda can read it at execute time.
+                                        const slot = ftsRankSlots.get($condition.alias);
+                                        if (slot) {
+                                            slot.indices[baseFieldName] = rankIndex;
+                                        }
+                                    }
+                                    // ORDER BY ts_rank: check if the user provided an
+                                    // explicit rank orderBy enum (stored in meta during
+                                    // planning). If so, use their direction. Otherwise add
+                                    // automatic DESC ordering for relevance.
+                                    const metaKey = `fts_order_${baseFieldName}`;
+                                    const explicitDir = typeof $parent.getMetaRaw === 'function'
+                                        ? $parent.getMetaRaw(metaKey)
+                                        : undefined;
+                                    const orderDirection = explicitDir ?? 'DESC';
+                                    $parent.orderBy({
+                                        fragment: sql `ts_rank(${columnExpr}, ${tsquery})`,
+                                        codec: pg_1.TYPES.float4,
+                                        direction: orderDirection,
+                                    });
+                                },
+                            }),
+                        }, `PgSearchPlugin adding condition field '${fieldName}' for tsvector column '${attributeName}' on '${pgCodec.name}'`);
+                    }
+                    return newFields;
+                },
+            },
+        },
+    };
+}
+/**
+ * Creates a PgSearchPlugin with the given options.
+ * This is the main entry point for using the plugin.
+ */
+exports.PgSearchPlugin = createPgSearchPlugin;
+exports.default = exports.PgSearchPlugin;

package/preset.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PostGraphile v5 Search Preset
+ *
+ * Provides a convenient preset for including search support in PostGraphile.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PgSearchPluginOptions } from './types';
+/**
+ * Creates a preset that includes the search plugin with the given options.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export declare function PgSearchPreset(options?: PgSearchPluginOptions): GraphileConfig.Preset;
+export default PgSearchPreset;

package/preset.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * PostGraphile v5 Search Preset
+ *
+ * Provides a convenient preset for including search support in PostGraphile.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgSearchPreset = PgSearchPreset;
+const plugin_1 = require("./plugin");
+const tsvector_codec_1 = require("./tsvector-codec");
+/**
+ * Creates a preset that includes the search plugin with the given options.
+ *
+ * @example
+ * ```typescript
+ * import { PgSearchPreset } from 'graphile-search-plugin';
+ *
+ * const preset = {
+ *   extends: [
+ *     PgSearchPreset({
+ *       pgSearchPrefix: 'fullText',
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+function PgSearchPreset(options = {}) {
+    return {
+        plugins: [(0, tsvector_codec_1.createTsvectorCodecPlugin)(options), (0, plugin_1.createPgSearchPlugin)(options)],
+    };
+}
+exports.default = PgSearchPreset;

package/tsvector-codec.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 type { GraphileConfig } from 'graphile-config';
+import type { PgSearchPluginOptions } from './types';
+/**
+ * Creates a TsvectorCodecPlugin with the given options.
+ *
+ * @param options - Plugin configuration
+ * @returns GraphileConfig.Plugin
+ */
+export declare function createTsvectorCodecPlugin(options?: PgSearchPluginOptions): GraphileConfig.Plugin;
+/**
+ * Default static instance using default options.
+ * Maps tsvector to the "FullText" scalar.
+ */
+export declare const TsvectorCodecPlugin: GraphileConfig.Plugin;
+export declare const TsvectorCodecPreset: GraphileConfig.Preset;

package/tsvector-codec.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * 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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TsvectorCodecPreset = exports.TsvectorCodecPlugin = void 0;
+exports.createTsvectorCodecPlugin = createTsvectorCodecPlugin;
+const graphql_1 = require("graphql");
+const pg_sql2_1 = __importDefault(require("pg-sql2"));
+/**
+ * Creates a TsvectorCodecPlugin with the given options.
+ *
+ * @param options - Plugin configuration
+ * @returns GraphileConfig.Plugin
+ */
+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: pg_sql2_1.default.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: pg_sql2_1.default.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', graphql_1.GraphQLString.name);
+                                setGraphQLTypeForPgCodec(codec, 'output', graphql_1.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.
+ */
+exports.TsvectorCodecPlugin = createTsvectorCodecPlugin();
+exports.TsvectorCodecPreset = {
+    plugins: [exports.TsvectorCodecPlugin],
+};

package/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/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * PgSearch Plugin Types
+ *
+ * Type definitions for the PostGraphile v5 search plugin configuration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });