@haathie/postgraphile-targeted-conditions 0.1.0

package/lib/filter-implementations/declaration.d.ts

@@ -0,0 +1,24 @@
+import type { FilterApply, FilterImplementation, FilterMethod, FilterMethodConfig, FilterType } from '../types.ts';
+/**
+ * Store configuration for each filter method.
+ */
+export declare const FILTER_METHODS_CONFIG: {
+    [K in FilterMethod]?: FilterMethodConfig;
+};
+/**
+ * Store implementations for each filter type.
+ */
+export declare const FILTER_TYPES_MAP: {
+    [K in FilterType]?: FilterImplementation;
+};
+/**
+ * Register implementations for the given filter types.
+ * If a filter type is already registered, and you attempt to re-register it,
+ * it will throw an error.
+ */
+export declare function registerFilterImplementations(impls: {
+    [K in FilterType]?: FilterImplementation;
+}): void;
+export declare function registerFilterMethod<T = unknown>(method: FilterMethod, config: FilterMethodConfig, applys: {
+    [K in FilterType]?: FilterApply<T>;
+}): void;

package/lib/filter-implementations/declaration.js

@@ -0,0 +1,83 @@
+/**
+ * Store configuration for each filter method.
+ */
+export const FILTER_METHODS_CONFIG = {};
+/**
+ * Store implementations for each filter type.
+ */
+export const FILTER_TYPES_MAP = {};
+/**
+ * Register implementations for the given filter types.
+ * If a filter type is already registered, and you attempt to re-register it,
+ * it will throw an error.
+ */
+export function registerFilterImplementations(impls) {
+    for (const [type, impl] of Object.entries(impls)) {
+        if (FILTER_TYPES_MAP[type]) {
+            throw new Error(`Filter type ${type} is already registered.`);
+        }
+        FILTER_TYPES_MAP[type] = impl;
+    }
+}
+export function registerFilterMethod(method, config, applys) {
+    if (FILTER_METHODS_CONFIG[method]) {
+        throw new Error(`Filter method ${method} is already registered.`);
+    }
+    FILTER_METHODS_CONFIG[method] = config;
+    for (const [type, apply] of Object.entries(applys)) {
+        const impl = FILTER_TYPES_MAP[type];
+        if (!impl) {
+            continue;
+        }
+        impl.applys ||= {};
+        impl.applys[method] = apply;
+    }
+}
+registerFilterImplementations({
+    'eq': {
+        getType(codec, getGraphQlType) {
+            // for eq -- we just return the field type
+            return getGraphQlType();
+        },
+    },
+    'eqIn': {
+        getType(codec, getGraphQlType, { graphql: { GraphQLList } }) {
+            return new GraphQLList(getGraphQlType());
+        },
+    },
+    'range': {
+        getRegisterTypeInfo(fieldCodec, getGraphQlType, { inflection }) {
+            return {
+                name: inflection.rangeConditionTypeName(fieldCodec),
+                spec: () => ({
+                    description: 'Filter values falling in an inclusive range',
+                    fields() {
+                        const fieldType = getGraphQlType();
+                        if (!('name' in fieldType)) {
+                            throw new Error('Cannot build range condition on a non-named type');
+                        }
+                        return {
+                            from: { type: fieldType },
+                            to: { type: fieldType }
+                        };
+                    }
+                }),
+            };
+        },
+        getType(fieldCodec, _, { inflection, getInputTypeByName }) {
+            return getInputTypeByName(inflection.rangeConditionTypeName(fieldCodec));
+        },
+    },
+    'icontains': {
+        getType(fieldCodec, getGraphQlType, { graphql: { GraphQLNonNull, GraphQLScalarType } }) {
+            let fieldType = getGraphQlType();
+            fieldType = fieldType instanceof GraphQLNonNull
+                ? fieldType.ofType
+                : fieldType;
+            if (!(fieldType instanceof GraphQLScalarType)) {
+                throw new Error('Cannot build contains condition on a non-scalar type');
+            }
+            return fieldType;
+        },
+    }
+});

package/lib/filter-implementations/index.d.ts

@@ -0,0 +1,3 @@
+export * from './declaration.ts';
+import './paradedb.ts';
+import './plain-sql.ts';

package/lib/filter-implementations/index.js

@@ -0,0 +1,3 @@
+export * from "./declaration.js";
+import "./paradedb.js";
+import "./plain-sql.js";

package/lib/filter-implementations/paradedb.d.ts

@@ -0,0 +1,8 @@
+declare global {
+    namespace GraphileBuild {
+        interface FilterMethodMap {
+            paradedb: true;
+        }
+    }
+}
+export {};

package/lib/filter-implementations/paradedb.js

@@ -0,0 +1,54 @@
+import { sql } from 'postgraphile/pg-sql2';
+import { registerFilterMethod } from "./declaration.js";
+registerFilterMethod('paradedb', { supportedOnSubscription: false }, {
+    'eq': (cond, input, { scope: { attrName, attr } }) => {
+        const codec = attr.codec.arrayOfCodec || attr.codec;
+        const id = sql `${cond.alias}.${sql.identifier(attrName)}`;
+        if (input === null) {
+            return cond.where(sql `NOT ${id} @@@ paradedb.exists(${sql.literal(attrName)})`);
+        }
+        return cond.where(sql `${id} @@@ paradedb.term(${sql.literal(attrName)}, ${sql.value(input)}::${codec.sqlType})`);
+    },
+    'eqIn': (cond, input, { scope: { attr, attrName } }) => {
+        const codec = attr.codec.arrayOfCodec || attr.codec;
+        const id = sql `${cond.alias}.${sql.identifier(attrName)}`;
+        const whereClause = sql `${id} @@@ paradedb.term_set(
+				(SELECT ARRAY_AGG(paradedb.term(${sql.literal(attrName)}, value))
+				FROM unnest(${sql.value(input)}::${codec.sqlType}[]) value)
+			)`;
+        const hasNull = input.includes(null);
+        if (!hasNull) {
+            return cond.where(whereClause);
+        }
+        return cond.where(sql `(
+				${whereClause}
+				OR NOT ${id} @@@ paradedb.exists(${sql.literal(attrName)})
+			)`);
+    },
+    'range': (cond, { from, to }, { scope: { attr, attrName, config } }) => {
+        const id = sql `${cond.alias}.${sql.identifier(attrName)}`;
+        const { sqlType } = attr.codec.arrayOfCodec || attr.codec;
+        const fieldName = config?.fieldName || attrName;
+        const fromSql = from
+            ? sql `jsonb_build_object('included', ${sql.value(from)}::${sqlType})`
+            : sql.null;
+        const toSql = to
+            ? sql `jsonb_build_object('included', ${sql.value(to)}::${sqlType})`
+            : sql.null;
+        cond.where(sql `${id} @@@ 
+				jsonb_build_object(
+					'range',
+					jsonb_build_object(
+						'field', ${sql.literal(fieldName)}, 
+						'lower_bound', ${fromSql},
+						'upper_bound', ${toSql}
+					)
+				)	
+			`);
+    },
+    'icontains': (cond, input, { scope: { attrName, config } }) => {
+        const fieldName = config?.fieldName || attrName;
+        const id = sql `${cond.alias}.${sql.identifier(attrName)}`;
+        return cond.where(sql `${id} @@@ paradedb.parse(${sql.value(`${fieldName}:"${input}"`)})`);
+    }
+});

package/lib/filter-implementations/plain-sql.d.ts

@@ -0,0 +1,8 @@
+declare global {
+    namespace GraphileBuild {
+        interface FilterMethodMap {
+            plainSql: true;
+        }
+    }
+}
+export {};

package/lib/filter-implementations/plain-sql.js

@@ -0,0 +1,49 @@
+import { sql } from 'postgraphile/pg-sql2';
+import { registerFilterMethod } from "./declaration.js";
+registerFilterMethod('plainSql', { supportedOnSubscription: true }, {
+    eq: (cond, input, { scope: { attrName, attr, serialiseToSql } }) => {
+        const id = sql `${cond.alias}.${sql.identifier(attrName)}`;
+        const codec = attr.codec.arrayOfCodec || attr.codec;
+        if (input === null) {
+            return cond.where(sql `${id} IS NULL`);
+        }
+        if (attr.codec.arrayOfCodec) {
+            // If the attribute is an array, we need to check for equality
+            return cond
+                .where(sql `${serialiseToSql()}::${codec.sqlType} = ANY(${id})`);
+        }
+        return cond.where(sql `${id} = ${serialiseToSql()}::${codec.sqlType}`);
+    },
+    eqIn: (cond, input, { scope: { attrName, attr, serialiseToSql } }) => {
+        const id = sql `${cond.alias}.${sql.identifier(attrName)}`;
+        const codec = attr.codec.arrayOfCodec || attr.codec;
+        const whereClause = attr.codec.arrayOfCodec
+            ? sql `${id} && ${serialiseToSql()}::${codec.sqlType}[] -- TRUE`
+            : sql `${id} IN (
+					SELECT arr FROM unnest(${serialiseToSql()}::${codec.sqlType}[]) arr
+				)`;
+        const hasNull = Array.isArray(input) && input.includes(null);
+        if (!hasNull) {
+            return cond.where(whereClause);
+        }
+        return cond.where(sql `(${whereClause} OR ${id} IS NULL)`);
+    },
+    range: (cond, { from, to }, { scope: { attrName, attr } }) => {
+        if (from !== undefined) {
+            cond.where(sql `${cond.alias}.${sql.identifier(attrName)} >= ${sql.value(from)}::${attr.codec.sqlType}`);
+        }
+        if (to !== undefined) {
+            cond.where(sql `${cond.alias}.${sql.identifier(attrName)} <= ${sql.value(to)}::${attr.codec.sqlType}`);
+        }
+    },
+    'icontains': (cond, input, { scope: { attr, attrName } }) => {
+        const id = sql `${cond.alias}.${sql.identifier(attrName)}`;
+        if (attr.codec.arrayOfCodec) {
+            return cond.where(sql `EXISTS (
+						SELECT 1 FROM unnest(${id}) AS elem 
+						WHERE elem ILIKE ${sql.value(`%${input}%`)}
+					)`);
+        }
+        return cond.where(sql `${id} ILIKE ${sql.value(`%${input}%`)}`);
+    }
+});

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './filter-implementations/declaration.ts';
+export * from './types.ts';
+export declare const TargetedConditionsPlugin: GraphileConfig.Plugin;

package/lib/index.js

@@ -0,0 +1,46 @@
+export * from "./filter-implementations/declaration.js";
+export * from "./types.js";
+import { FILTER_METHODS_CONFIG, FILTER_TYPES_MAP } from "./filter-implementations/index.js";
+import { inflection } from "./inflection.js";
+import { fields } from "./schema-fields.js";
+import { init } from "./schema-init.js";
+export const TargetedConditionsPlugin = {
+    name: 'TargetedConditionsPlugin',
+    version: '0.0.1',
+    inflection,
+    schema: {
+        behaviorRegistry: {
+            add: {
+                'filterable': {
+                    description: 'Allow filtering using by fields on this relation',
+                    entities: ['pgCodecRef', 'pgRefDefinition']
+                },
+                ...Object.entries(FILTER_TYPES_MAP).reduce((acc, [filterType, { description }]) => {
+                    const behaviourName = `filterType:${filterType}`;
+                    acc[behaviourName] = {
+                        description: description || `Add ${filterType} filter type`,
+                        entities: ['pgCodecAttribute'],
+                    };
+                    return acc;
+                }, {}),
+                ...Object.entries(FILTER_METHODS_CONFIG).reduce((acc, [filterMethod, { description }]) => {
+                    const name = `filterMethod:${filterMethod}`;
+                    acc[name] = {
+                        description: description
+                            || `Allow filtering this field using ${filterMethod} operators`,
+                        entities: ['pgCodecAttribute'],
+                    };
+                    return acc;
+                }, {})
+            },
+        },
+        hooks: {
+            build(build) {
+                return build
+                    .extend(build, { inputConditionTypes: {} }, 'TargetedConditionsPlugin');
+            },
+            init: init,
+            'GraphQLInputObjectType_fields': fields,
+        }
+    }
+};

package/lib/inflection.d.ts

@@ -0,0 +1 @@
+export declare const inflection: GraphileConfig.PluginInflectionConfig;

package/lib/inflection.js

@@ -0,0 +1,14 @@
+export const inflection = {
+    add: {
+        conditionContainerTypeName(options, resource, attrName) {
+            const attrFieldName = this._attributeName({
+                codec: resource.codec,
+                attributeName: attrName,
+            });
+            return this.upperCamelCase(`${this._resourceName(resource)}_${attrFieldName}_condition`);
+        },
+        rangeConditionTypeName(options, codec) {
+            return this.upperCamelCase(`${this._codecName(codec)}_range_condition`);
+        },
+    }
+};

package/lib/schema-fields.d.ts

@@ -0,0 +1,3 @@
+type Hook = NonNullable<NonNullable<GraphileConfig.Plugin['schema']>['hooks']>['GraphQLInputObjectType_fields'];
+export declare const fields: Hook;
+export {};

package/lib/schema-fields.js

@@ -0,0 +1,79 @@
+import { getInputConditionForResource } from '@haathie/postgraphile-common-utils';
+import { sql } from 'postgraphile/pg-sql2';
+import { getFilterTypesForAttribute } from "./utils.js";
+export const fields = (fieldMap, build, ctx) => {
+    const { behavior, inflection, getTypeByName } = build;
+    const { scope: { pgCodec: _codec, isPgCondition }, fieldWithHooks } = ctx;
+    if (!isPgCondition || !_codec?.extensions?.isTableLike) {
+        return fieldMap;
+    }
+    const pgCodec = _codec;
+    const pgResource = build.pgTableResource(pgCodec);
+    for (const attrName in pgCodec.attributes) {
+        const hasFilter = getFilterTypesForAttribute(pgCodec, attrName, build)
+            .next()
+            .value;
+        if (!hasFilter) {
+            continue;
+        }
+        const typeName = inflection.conditionContainerTypeName(pgResource, attrName);
+        const type = getTypeByName(typeName);
+        if (!type) {
+            throw new Error(`Condition type ${typeName} for attribute "${attrName}" `
+                + `not found in codec "${pgCodec.name}".`);
+        }
+        const fieldName = inflection
+            .attribute({ attributeName: attrName, codec: pgCodec });
+        fieldMap[fieldName] = fieldWithHooks({ fieldName, isConditionContainer: true }, () => ({ extensions: { grafast: { apply: passThroughApply } }, type }));
+    }
+    // add queries via refs
+    for (const [refName, { paths }] of Object.entries(pgCodec.refs || {})) {
+        if (!behavior.pgCodecRefMatches([pgCodec, refName], 'filterable')) {
+            continue;
+        }
+        if (!paths.length) {
+            throw new Error(`Ref ${refName} on codec ${pgCodec.name} has no paths defined.`);
+        }
+        if (paths.length > 1) {
+            throw new Error('Refs w multiple paths are not supported yet.');
+        }
+        const { relationName } = paths[0][0];
+        const field = buildRelationSearch(relationName);
+        if (!field) {
+            continue;
+        }
+        const fieldName = inflection.camelCase(refName);
+        fieldMap[fieldName] = field;
+    }
+    return fieldMap;
+    function buildRelationSearch(relationName) {
+        const relation = pgResource?.getRelation(relationName);
+        if (!relation) {
+            return;
+        }
+        const rmtRrsc = relation.remoteResource;
+        const rmtRrscFrom = rmtRrsc.from;
+        const remoteResourceCond = getInputConditionForResource(
+        // @ts-expect-error
+        rmtRrsc, build);
+        if (!remoteResourceCond) {
+            throw new Error('The remote resource does not have a condition type defined.');
+        }
+        return {
+            type: remoteResourceCond,
+            extensions: {
+                grafast: {
+                    apply(target) {
+                        const wherePlan = target
+                            .existsPlan({ alias: 't', tableExpression: rmtRrscFrom });
+                        const localAttrsJoined = sql.join(relation.localAttributes.map(attr => (sql `${target.alias}.${sql.identifier(attr)}`)), ',');
+                        const remoteAttrsJoined = sql.join(relation.remoteAttributes.map(attr => (sql `${wherePlan.alias}.${sql.identifier(attr)}`)), ',');
+                        wherePlan.where(sql `(${localAttrsJoined}) = (${remoteAttrsJoined})`);
+                        return wherePlan;
+                    }
+                }
+            }
+        };
+    }
+};
+const passThroughApply = p => p;

package/lib/schema-init.d.ts

@@ -0,0 +1,3 @@
+type Hook = NonNullable<NonNullable<GraphileConfig.Plugin['schema']>['hooks']>['init'];
+export declare const init: Hook;
+export {};

package/lib/schema-init.js

@@ -0,0 +1,140 @@
+import { buildFieldNameToAttrNameMap, isSubscriptionPlan, mapFieldsToAttrs } from '@haathie/postgraphile-common-utils';
+import { FILTER_METHODS_CONFIG, FILTER_TYPES_MAP } from "./filter-implementations/index.js";
+import { getBuildGraphQlTypeByCodec, getFilterMethodsForAttribute, getFilterTypesForAttribute } from "./utils.js";
+const DEFAULT_FILTER_METHOD = 'plainSql';
+export const init = (_, build) => {
+    const { input: { pgRegistry: { pgResources } }, inflection, registerInputObjectType, sql, } = build;
+    const registeredTypes = new Set();
+    for (const resource of Object.values(pgResources)) {
+        const codec = resource.codec;
+        if (!codec.extensions?.isTableLike) {
+            continue;
+        }
+        for (const [attrName, attr] of Object.entries(resource.codec.attributes)) {
+            const info = {
+                types: [],
+                method: getFilterMethodsForAttribute(codec, attrName, build)
+                    .next().value || undefined
+            };
+            for (const filterType of getFilterTypesForAttribute(codec, attrName, build)) {
+                info.types.push(filterType);
+                const filterInfo = FILTER_TYPES_MAP[filterType];
+                if (!filterInfo) {
+                    throw new Error(`INTERNAL: Filter type "${filterType}" is not registered.`
+                        + ' Please register it before using `registerFilterImplementations`');
+                }
+                if (!filterInfo.getRegisterTypeInfo) {
+                    continue;
+                }
+                const { name, spec } = filterInfo.getRegisterTypeInfo(attr.codec, getBuildGraphQlTypeByCodec(attr.codec, build), build);
+                if (registeredTypes.has(name)) {
+                    continue;
+                }
+                registerInputObjectType(name, { conditionFilterType: filterType, pgCodec: attr.codec }, spec, `${attr.codec.name}_${filterType}_condition`);
+                registeredTypes.add(name);
+            }
+            registerConditionType(resource, attrName, info);
+        }
+    }
+    return _;
+    function registerConditionType(pgResource, attrName, { types: filterTypes, method }) {
+        const attr = pgResource.codec.attributes[attrName];
+        const filterConfigs = getFilterConfigs(attr.extensions?.tags);
+        const typeName = inflection._resourceName(pgResource);
+        registerInputObjectType(inflection.conditionContainerTypeName(pgResource, attrName), {
+            isConditionContainer: true,
+            pgResource,
+            pgAttribute: attr,
+        }, () => ({
+            description: `Conditions for filtering by ${typeName}'s ${attrName}`,
+            isOneOf: true,
+            fields() {
+                return filterTypes.reduce((fields, filterType) => {
+                    const condType = buildConditionField(attrName, attr, filterType, method, filterConfigs[filterType]);
+                    fields[filterType] = condType;
+                    return fields;
+                }, {});
+            }
+        }), `${pgResource.name}_${attrName}_condition_container`);
+    }
+    function buildConditionField(attrName, attr, filter, method = DEFAULT_FILTER_METHOD, config = {}) {
+        const { getType, applys } = FILTER_TYPES_MAP[filter];
+        const builtType = getType(attr.codec, getBuildGraphQlTypeByCodec(attr.codec, build), build);
+        const fieldMap = buildFieldNameToAttrNameMap(attr.codec, inflection);
+        const applyMethod = applys?.[method];
+        if (!applyMethod) {
+            throw new Error(`No apply fn available for filter type ${filter} and method ${method}.`);
+        }
+        const applyDefault = applys?.[DEFAULT_FILTER_METHOD];
+        return {
+            type: builtType,
+            extensions: {
+                grafast: {
+                    apply: buildMethodApply(method)
+                }
+            }
+        };
+        function buildMethodApply(method) {
+            return (plan, args, info) => {
+                const newInfo = {
+                    ...info,
+                    scope: {
+                        ...info.scope,
+                        attrName: attrName,
+                        attr: attr,
+                        config,
+                        serialiseToSql: () => serialiseToSql(args),
+                    }
+                };
+                const isSubscription = isSubscriptionPlan(plan);
+                if (isSubscription
+                    && !FILTER_METHODS_CONFIG[method]?.supportedOnSubscription) {
+                    if (!applyDefault) {
+                        throw new Error(`Filter method "${method}" is not supported on subscriptions.`);
+                    }
+                    return applyDefault(plan, args, newInfo);
+                }
+                return applyMethod(plan, args, newInfo);
+            };
+        }
+        function serialiseToSql(input) {
+            if (input === null || input === undefined) {
+                return sql.null;
+            }
+            // so if the input isn't a compound type, we can just return it
+            // we'll assume it's a scalar value or an array of scalars
+            if (!fieldMap) {
+                return sql.value(input);
+            }
+            const mapped = mapFieldsToAttrs(input, fieldMap);
+            const mainCodec = attr.codec.arrayOfCodec || attr.codec;
+            if (Array.isArray(mapped)) {
+                return sql.value(mapped.map(v => mainCodec.toPg(v)));
+            }
+            return sql.value(mainCodec.toPg(mapped));
+        }
+    }
+};
+function getFilterConfigs(tags) {
+    const filterConfigs = {};
+    const configTag = typeof tags?.filterConfig === 'string' ? [tags.filterConfig] : tags?.filterConfig;
+    if (!configTag) {
+        return filterConfigs;
+    }
+    for (const configStr of configTag) {
+        const colonIdx = configStr.indexOf(':');
+        if (colonIdx === -1) {
+            throw new Error(`Invalid filter config tag: ${configStr}`);
+        }
+        const filterType = configStr.slice(0, colonIdx);
+        const configJsonStr = configStr.slice(colonIdx + 1);
+        try {
+            const configJson = JSON.parse(configJsonStr);
+            filterConfigs[filterType] = configJson;
+        }
+        catch (e) {
+            throw new Error(`Invalid JSON in filter config tag: ${configStr}, ${e.message}`);
+        }
+    }
+    return filterConfigs;
+}

package/lib/types.d.ts

@@ -0,0 +1,85 @@
+import type { PgCodec, PgCodecAttribute, PgCondition, PgResource } from 'postgraphile/@dataplan/pg';
+import type { InputObjectFieldApplyResolver } from 'postgraphile/grafast';
+import type { GraphQLInputType } from 'postgraphile/graphql';
+import type { SQL } from 'postgraphile/pg-sql2';
+export type FilterType = keyof GraphileBuild.FilterTypeMap;
+export type FilterMethod = keyof GraphileBuild.FilterMethodMap;
+export type FilterApply<T = unknown> = InputObjectFieldApplyResolver<PgCondition, any, {
+    attrName: string;
+    attr: PgCodecAttribute;
+    serialiseToSql: () => SQL;
+    config?: T;
+}>;
+export type FilterImplementation = {
+    description?: string;
+    /**
+     * Register the type used to filter the attribute.
+     * @param fieldCodec The codec of the field being filtered.
+     * @param getGraphQlType A function that returns the GraphQL type of the
+     *  field. Only use in `registerInputObjectType` method or you'll get an
+     *  error from Graphile
+     * @param build The build object.
+     */
+    getRegisterTypeInfo?(fieldCodec: PgCodec, getGraphQlType: () => GraphQLInputType, build: GraphileBuild.Build): {
+        name: string;
+        spec: () => Omit<GraphileBuild.GrafastInputObjectTypeConfig, 'name'>;
+    };
+    getType(fieldCodec: PgCodec, getGraphQlType: () => GraphQLInputType, build: GraphileBuild.Build): GraphQLInputType;
+    applys?: {
+        [M in FilterMethod]?: FilterApply;
+    };
+};
+export type FilterMethodConfig = {
+    /**
+     * Optionally add a human-readable description for the filter method.
+     * Used in the behaviour registry
+     */
+    description?: string;
+    /**
+     * Should this filter method be used on subscriptions?
+     * If false, the `plainSql` method will be used instead.
+     */
+    supportedOnSubscription: boolean;
+};
+interface FilterBehaviours extends Record<`filterType:${FilterType}`, true>, Record<`filterMethod:${FilterMethod}`, true> {
+    'filterable': true;
+}
+declare global {
+    namespace GraphileBuild {
+        interface FilterTypeMap {
+            eq: true;
+            eqIn: true;
+            range: true;
+            icontains: true;
+        }
+        /**
+         * Method used to apply filters -- useful for different index types like
+         * GIN, paradedb, zombodb, etc.
+         */
+        interface FilterMethodMap {
+        }
+        interface FilterTypeMap {
+            eq: true;
+            eqIn: true;
+            range: true;
+            icontains: true;
+        }
+        interface BehaviorStrings extends FilterBehaviours {
+        }
+        interface Inflection {
+            conditionContainerTypeName(resource: PgResource, attrName: string): string;
+            rangeConditionTypeName(codec: PgCodec): string;
+        }
+        interface ScopeInputObject {
+            conditionFilterType?: FilterType;
+            isConditionContainer?: boolean;
+        }
+        interface ScopeInputObjectFieldsField {
+            isConditionContainer?: boolean;
+        }
+        interface PgCodecAttributeTags {
+            filterConfig?: string[];
+        }
+    }
+}
+export {};

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/lib/utils.d.ts

@@ -0,0 +1,5 @@
+import type { PgCodec, PgCodecWithAttributes } from 'postgraphile/@dataplan/pg';
+import type { GraphQLInputType } from 'postgraphile/graphql';
+export declare function getBuildGraphQlTypeByCodec(codec: PgCodec, build: GraphileBuild.Build): () => GraphQLInputType;
+export declare function getFilterTypesForAttribute(pgCodec: PgCodecWithAttributes, attrName: string, { behavior }: GraphileBuild.Build): Generator<keyof GraphileBuild.FilterTypeMap, void, unknown>;
+export declare function getFilterMethodsForAttribute(pgCodec: PgCodecWithAttributes, attrName: string, { behavior }: GraphileBuild.Build): Generator<keyof GraphileBuild.FilterMethodMap, void, unknown>;

package/lib/utils.js

@@ -0,0 +1,31 @@
+import { FILTER_METHODS_CONFIG, FILTER_TYPES_MAP } from "./filter-implementations/index.js";
+export function getBuildGraphQlTypeByCodec(codec, build) {
+    codec = codec.arrayOfCodec || codec;
+    return () => {
+        const type = build.getGraphQLTypeByPgCodec(codec, 'input');
+        if (!type) {
+            throw new Error(`No input type found for codec ${codec.name}`);
+        }
+        return type;
+    };
+}
+export function* getFilterTypesForAttribute(pgCodec, attrName, { behavior }) {
+    for (const _filterType in FILTER_TYPES_MAP) {
+        const filterType = _filterType;
+        if (!behavior
+            .pgCodecAttributeMatches([pgCodec, attrName], `filterType:${filterType}`)) {
+            continue;
+        }
+        yield filterType;
+    }
+}
+export function* getFilterMethodsForAttribute(pgCodec, attrName, { behavior }) {
+    for (const _method in FILTER_METHODS_CONFIG) {
+        const method = _method;
+        if (!behavior
+            .pgCodecAttributeMatches([pgCodec, attrName], `filterMethod:${method}`)) {
+            continue;
+        }
+        yield method;
+    }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "@haathie/postgraphile-targeted-conditions",
+	"version": "0.1.0",
+	"type": "module",
+	"files": ["lib"],
+	"main": "lib/index.js",
+	"types": "lib/index.d.ts",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/haathie/graphile-tools.git"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json"
+	},
+	"dependencies": {
+		"@haathie/postgraphile-common-utils": "*"
+	},
+	"peerDependencies": {
+		"postgraphile": "*"
+	}
+}

package/readme.md

@@ -0,0 +1,210 @@
+# Postgraphile Targeted Conditions
+
+Opt-in & configurable conditions plugin for Postgraphile. This plugin is designed to allow you to quickly enable conditions on fields for your Postgraphile queries without having to write custom SQL or GraphQL plans. It also supports adding conditions on fields in related tables.
+
+Please read through [the Caveats section](#caveats) before using this plugin.
+
+## Setup
+
+Install:
+``` bash
+npm i @haathie/postgraphile-targeted-conditions
+```
+
+Add the plugin to your Postgraphile configuration:
+``` ts
+import { TargetedConditionsPlugin } from '@haathie/postgraphile-targeted-conditions'
+
+export const config: GraphileBuild.Preset = {
+	...otherOptions,
+	plugins: [
+		...otherPlugins,
+		TargetedConditionsPlugin,
+	],
+}
+```
+
+## Usage
+
+By default, the plugin will not add any conditions to any connection queries. You can enable conditions for a specific field by adding a "filterType" behaviour to the field in your schema.
+
+``` sql
+-- will add a case-insensitive "icontains" filter, and an "eq" filter 
+-- to the "name" column of the "contacts" table
+comment on column app.contacts.name is $$
+@behaviour filterType:icontains filterType:eq
+$$;
+```
+
+This will allow you to filter the "contacts" table by the "name" column using the following GraphQL query:
+
+``` graphql
+query GetContacts {
+	allContacts(condition: { name: { icontains: "john" } }) {
+		nodes {
+			id
+			name
+		}
+	}
+}
+```
+
+The plugin will always create a `oneOf` Input Object type for the filter type of each field. Eg.
+``` graphql
+input ContactNameCondition @oneOf {
+	icontains: String
+	eq: String
+}
+```
+
+This allows for adding/removing filter types without breaking existing queries. For example, if you add a new filter type for "equals in" to the "name" column, and the above query will still work without any changes.
+
+## Relational Conditions
+
+Let's say we have a `contacts` table and a `tags` table, with each contact having multiple tags. We can add a filter to the `contacts` table to filter by tags. We'll create a ref and add `filterable` behaviour to it.
+This will give the contacts relation the ability to filter by all filterable fields in the `tags` table.
+
+``` sql
+-- will add a "tags" filter to the "contacts" table
+-- for more info on refs, see: https://postgraphile.org/postgraphile/5/refs/#ref-and-refvia
+comment on table "conditions_test"."authors" is $$
+@ref tags via:(id)->tags(contact_id) behavior:filterable
+$$;
+
+-- we'll also add an "eq" filter to the "name" column of the "tags" table
+comment on column app.tags.name is $$
+@behaviour filterType:eq
+$$;
+```
+
+This now enables us to query `contacts` by `tags` in the following way:
+``` graphql
+query GetContacts {
+	allContacts(condition: { tags: { name: { eq: "important" } } }) {
+		nodes {
+			id
+			name
+			# also return the tags for each contact
+			# (not related to the conditions plugin, but useful)
+			tags {
+				nodes {
+					id
+					name
+				}
+			}
+		}
+	}
+}
+```
+
+## Available Filter Types
+
+- `eq`: Exact match, with null handling
+- `eqIn`: Check if the value is in a list of values, with null handling
+- `icontains`: Case-insensitive contains
+- `range`: Check if a value is within an inclusive range
+
+## Filter Methods
+
+Postgres has a bunch of popular extensions that implement a different syntax for filtering -- eg. GIN indices, ZomboDB, ParadeDB, etc. This plugin is extensible to support these extensions.
+
+Presently, the plugin supports the following filter methods:
+- [paradedb](https://github.com/paradedb/paradedb): ParadeDB is a PostgreSQL extension that allows you to have ES-level query capabilities in your Postgres database. This plugin supports using ParadeDB's query syntax to filter your queries.
+
+## Adding a Custom Filter Type
+
+Let's implement a `startsWith` filter type that allows filtering strings that start with a given value.
+
+``` ts
+import { registerFilterImplementations } from '@haathie/postgraphile-targeted-conditions'
+
+// extend the "FilterTypeMap" interface to add the new filter type
+declare global {
+  namespace GraphileBuild {
+    interface FilterTypeMap {
+      startsWith: true
+    }
+  }
+}
+
+// write the filter implementation
+registerFilterImplementations({
+  'startsWith': {
+    // the getType method is used to get the GraphQL type for the filter
+    // in this case, it'll just be the same type as the field being filtered.
+    // Also since startsWith only makes sense for string fields -- we can throw
+    // an error if the field is not a string.
+    getType(codec, getGraphQlType, { graphql: { GraphQLNonNull, GraphQLString } }) {
+      const type = getGraphQlType()
+      if(type !== GraphQLString) {
+        throw new Error(`The "startsWith" filter type can only be used on string fields, but the field "${codec.name}" is of type "${type.name}".`)
+      }
+
+      return new GraphQLNonNull(type)
+    },
+    // in the applys method, we define how the filter gets converted to SQL
+    // using a specified method. By default, "plainSql" is used, but you can
+    // implement other methods like "paradedb" or "zombodb" to use their
+    // query syntax.
+    applys: {
+      plainSql: (cond, input, { scope: { attrName, attr } }) => {
+        const id = sql`${cond.alias}.${sql.identifier(attrName)}`
+        // handle postgres array types
+        if(attr.codec.arrayOfCodec) {
+          return cond.where(
+            sql`EXISTS (
+              SELECT 1 FROM unnest(${id}) AS elem 
+              WHERE elem LIKE ${sql.value(`${input}%`)}
+            )`
+          )
+        }
+
+        return cond.where(sql`${id} LIKE ${sql.value(`${input}%`)}`)
+      },
+    }
+  },
+})
+```
+
+See how other filter types are implemented [here](src/filter-implementations/declaration.ts#L51).
+
+## Adding a Custom Filter Method
+
+To add a custom filter method, you can use the `registerFilterMethod` function. This allows you to define how the filter type should be applied in SQL.
+
+``` ts
+import { registerFilterMethod } from '@haathie/postgraphile-targeted-conditions'
+
+// extend the "FilterMethodMap" interface to add the new filter method
+declare global {
+  namespace GraphileBuild {
+    interface FilterMethodMap {
+      zombodb: true
+    }
+  }
+}
+
+registerFilterMethod(
+  'zombodb',
+  // can this be used in subscriptions? This flag is present as some filter
+  // methods may not be well suited or even supported in realtime scenarios.
+  { supportedOnSubscription: false },
+  {
+    eq: (cond, input, { scope: { attrName, attr } }) => {
+      // implement
+    },
+    eqIn: (cond, input, { scope: { attrName, attr } }) => {
+      // implement
+    },
+    // ... other filter types
+  }
+)
+```
+
+See how [paradedb method](src/filter-implementations/paradedb.ts) is implemented for a more detailed example.
+
+## Caveats
+
+- Adding relational conditions can lead to performance issues, especially if the related table has a large number of rows. Use with caution and please ensure you have the necessary indices in place.
+- Apart from relations, adding arbitrary conditions on fields for vibes only is not a good idea. It can cause unexpected performance issues, and it is recommended to only add conditions that are necessary for your application. The plugin is meant for you to quickly add targeted conditions to your queries, and only the ones you want -- so we spend more time writing mission-critical code rather than boilerplate SQL or GraphQL plans.
+- This plugin does not work with Postgres compound types at the moment. Only the `eq` and `eqIn` filter types are supported for compound types.