@dav3/gql-of-power 1.4.0 → 1.5.0

package/README.md

@@ -293,6 +293,68 @@ Returns `null` when the FK column is null (LEFT JOIN).
 
 ---
 
+## Three Ways to Define an Entity
+
+There are three APIs for registering a GQL entity. They differ in **when** the generated types (FilterInput, PaginationInput, FieldsResolver, etc.) are registered — that difference matters for filter-type resolution (see [Troubleshooting](#troubleshooting)).
+
+### Quick comparison
+
+| API                 | When to use                                                                                              | Calls `buildResolvers()`?                                    | FilterInput registered   |
+| ------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------ |
+| `@GQLEntityClass`   | **Default.** No circular imports between entity files.                                                   | ✅ Automatically (at decoration time)                        | ✅ Yes                   |
+| `createGQLTypes()`  | Same as `@GQLEntityClass` but as a function call (can't decorate a class, or prefer the explicit style). | ✅ Automatically (internally)                                | ✅ Yes                   |
+| `createGQLEntity()` | **Circular imports** between entity definitions — you need to defer resolver registration.               | ❌ **Deferred** — you must call `.buildResolvers()` yourself | ❌ No, until you call it |
+
+### `@GQLEntityClass` — the default (recommended)
+
+The decorator registers the entity **and** its FilterInput/FieldsResolver immediately at decoration time. All generated statics (`FilterInput`, `PaginationInput`, `FieldsResolver`) are available on the class.
+
+```typescript
+@GQLEntityClass(Book, bookFields)
+export class BookGQL extends GQLEntityBase {}
+// BookGQL.FilterInput is ready. Done.
+```
+
+### `createGQLTypes()` — function-call equivalent
+
+Same behaviour as the decorator — it calls `createGQLEntity().buildResolvers()` internally (see `gql-entity.ts:1221-1222`). Use it when you can't or don't want to decorate a class.
+
+```typescript
+export const BookGQL = createGQLTypes(Book, bookFields);
+// BookGQL.FilterInput is ready. Done.
+```
+
+### `createGQLEntity()` — for circular imports (advanced)
+
+Returns the entity definition **without** registering the FilterInput or FieldsResolver. You must call `.buildResolvers()` yourself before `buildSchema()` runs. This split exists so two entity files can reference each other's `GQLEntity` type thunks without a circular-import deadlock at module-load time.
+
+```typescript
+// book.entity.ts
+export const BookEntity = createGQLEntity(Book, bookFields);
+//   ↑ FilterInput NOT registered yet
+
+// author.entity.ts — can import BookEntity for the thunk even if Book imports Author
+export const AuthorEntity = createGQLEntity(Author, authorFields, {
+	customFields: {/* ... uses () => BookEntity.GQLEntity ... */},
+});
+
+// schema/index.ts — YOU must call buildResolvers() on EVERY entity
+export const BookGQL = BookEntity.buildResolvers(); // ← registers BookFilterInput
+export const AuthorGQL = AuthorEntity.buildResolvers(); // ← registers AuthorFilterInput
+```
+
+> ⚠️ **If you forget a `.buildResolvers()` call**, any filter that references that entity (relationship fields, mapping custom-field filters, `_exists` filters) will throw at schema-build time:
+>
+> ```
+> gql-of-power: FilterInput for referenced entity "Book" (BookFilterInput) is not registered.
+> Make sure Book's buildResolvers() is called (or use createGQLTypes / @GQLEntityClass)
+> before building the schema.
+> ```
+>
+> The error names the missing entity so you know exactly which file to fix.
+
+---
+
 ## Filtering
 
 Filter at any nesting level:
@@ -560,6 +622,88 @@ No `limit` or `offset` parameters are accepted — `LIMIT 1` is always applied.
 
 ---
 
+## Troubleshooting
+
+### `FilterInput for referenced entity "X" is not registered`
+
+This error fires at `buildSchema()` time when a relationship field, mapping custom-field filter, or `_exists` filter references an entity whose FilterInput was never registered.
+
+**Cause:** You used `createGQLEntity()` (the deferred API) for entity `X` but forgot to call `X.buildResolvers()` before building the schema. The entity's ObjectType is registered, but its FilterInput is not.
+
+**Fix:** Either switch the entity to `@GQLEntityClass` / `createGQLTypes()` (which call `buildResolvers()` automatically), or add the missing call:
+
+```typescript
+// schema/index.ts — collect ALL entities and call buildResolvers()
+const BookGQL = BookEntity.buildResolvers();
+const AuthorGQL = AuthorEntity.buildResolvers();
+```
+
+Before August 2026 this was a **silent wrong-type bug**: the missing FilterInput fell back to the parent entity's FilterInput, so `Author.books` would generate `AuthorFilterInput` instead of `BookFilterInput`. The library now throws with the message above.
+
+### Mapping custom-field filter is missing from the schema
+
+If a `customFields` entry with `mapping` doesn't produce its nested filter (e.g. `HomeRegion: { name_eq: '...' }` is absent), check whether `resolve` was **also** set on the same field:
+
+```typescript
+customFields: {
+	homeRegion: {
+		type: () => RegionGQL.GQLEntity,
+		mapping: { refEntity: Region, refFields: 'id', fields: 'homeRegionId' },
+		generateFilter: true,
+		resolve: (root) => ...,  // ← THIS makes the filter silently disappear
+	},
+},
+```
+
+`resolve` and `mapping` are **mutually exclusive** on the same custom field. When both are set, only the resolver registers — the mapping filter is skipped. TypeScript's `CustomFieldSettings<T>` union enforces this at the type level, but `as any` bypasses it. Remove `resolve` (and `resolveDecorators`/`requires`) from a mapping-strategy field.
+
+### Filter key is PascalCase, not camelCase
+
+Mapping custom-field filters appear in the FilterInput under a **capitalized** key:
+
+```graphql
+# ✅ Correct — PascalCase filter key
+persons(filter: { HomeRegion: { name_eq: 'Gondor' } }) { ... }
+
+# ❌ Wrong — camelCase doesn't exist on the FilterInput
+persons(filter: { homeRegion: { name_eq: 'Gondor' } })
+# Field "homeRegion" is not defined by type "PersonFilterInput". Did you mean "HomeRegion"?
+```
+
+The field **selection** in the query stays camelCase (`homeRegion { ... }`); only the filter key is capitalized. Count-field nested filters follow the same rule (`BookCount: { _gte: 2 }`).
+
+### Relationship-field filters aren't statically typed
+
+`GQLEntityFilterInputFieldType<T>` surfaces filter operators for scalar fields but does **not** statically include nested relationship sub-filters (they're generated at runtime). Cast the filter object `as any` when using relationship filters:
+
+```typescript
+queryManager.getQueryResultsForInfo(provider, PersonGQL, info, {
+	fellowship: { id_in: [1, 2] }, // works at runtime, not statically typed
+} as any);
+```
+
+This is the library's own test-suite pattern.
+
+### `mapNumericEnum` filter values silently fail inside nested/inline filters
+
+If a `mapNumericEnum` field filters correctly at the **top level** but silently returns no results (or the wrong rows) when placed inside an inline field-argument filter on a nested relation — e.g.:
+
+```graphql
+# Works: top-level filter → 'InProgress' converted to 1
+bearers(filter: { questState: InProgress }) { name }
+
+# Silently failed before August 2026: inline filter → 'InProgress' passed as a string
+rings { bearer(filter: { questState: InProgress }) { name } }
+```
+
+**Cause:** enum conversion (`convertFilterEnumValues`) was historically applied only to top-level filters in `GQLQueryManager`. Inline field-argument filters (`books(filter: {...})`), count-field filters (`bookCount(filter: {...})`), and multi-level nested filters entered the SQL mapper through a different code path that bypassed conversion entirely. The `mapNumericEnum` string key went straight to SQL as a string instead of being converted to the numeric DB value, so the `WHERE` clause silently matched nothing.
+
+**Fix (August 2026):** `handleFieldArguments` and `mapCountField` in the SQL mapper now call `convertFilterEnumValues` on inline filter args before SQL generation. The conversion resolves the target entity's `mapNumericEnum` fields through the parent entity's relation-field registry and recurses to arbitrary depth. This means filters now behave identically at the top level, inside `relation(filter:)`, inside nested `relation(filter: { nested: {...} })`, inside count subqueries, and inside `_or`/`_and` arrays at any level.
+
+**If you still see this pattern:** ensure the target entity is decorator-registered (`@GQLEntityClass` / `createGQLTypes`) so its `mapNumericEnum` fields appear in the `MapEnumFieldsMap` registry — conversion silently passes values through for unregistered entities.
+
+---
+
 ## Known Limitations
 
 - ⚠️ Class-level `_not` conditions not yet supported

package/dist/entities/gql-entity.d.ts

@@ -29,6 +29,8 @@ export declare const clearMapEnumFields: () => void;
 export declare const getParseJsonFieldsFor: (name: string) => Set<string>;
 export declare const registerParseJsonField: (gqlEntityName: string, fieldName: string) => void;
 export declare const clearParseJsonFields: () => void;
+export declare const getRelationFieldsFor: (name: string) => Record<string, () => string>;
+export declare const clearRelationFields: () => void;
 export declare const getACLFor: (name: string) => AccessControlEntry<any, any>;
 export declare const getGQLEntityNameFor: (name: string) => string;
 export declare const getGQLEntityNameForClass: <T>(classType: new () => T) => string;

package/dist/entities/gql-entity.js

@@ -6,7 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGQLEntityFields = exports.GQLEntityBase = exports.getGQLEntityTypeFor = exports.getGQLEntityFieldResolverNameFor = exports.getGQLEntityFieldResolverName = exports.getGQLEntityNameForClass = exports.getGQLEntityNameFor = exports.getACLFor = exports.clearParseJsonFields = exports.registerParseJsonField = exports.getParseJsonFieldsFor = exports.clearMapEnumFields = exports.getMapEnumFieldsFor = exports.clearCountFields = exports.registerCountField = exports.getCountFieldsFor = exports.getCustomFieldsFor = exports.getFieldByAlias = exports.getFieldsOptionsFor = exports.setGlobalConfig = void 0;
+exports.createGQLEntityFields = exports.GQLEntityBase = exports.getGQLEntityTypeFor = exports.getGQLEntityFieldResolverNameFor = exports.getGQLEntityFieldResolverName = exports.getGQLEntityNameForClass = exports.getGQLEntityNameFor = exports.getACLFor = exports.clearRelationFields = exports.getRelationFieldsFor = exports.clearParseJsonFields = exports.registerParseJsonField = exports.getParseJsonFieldsFor = exports.clearMapEnumFields = exports.getMapEnumFieldsFor = exports.clearCountFields = exports.registerCountField = exports.getCountFieldsFor = exports.getCustomFieldsFor = exports.getFieldByAlias = exports.getFieldsOptionsFor = exports.setGlobalConfig = void 0;
 exports.getAutoResolvers = getAutoResolvers;
 exports.defineFields = defineFields;
 exports.GQLEntityClass = GQLEntityClass;
@@ -24,6 +24,14 @@ const CustomFieldsMap = {};
 const CountFieldsMap = {};
 const MapEnumFieldsMap = {};
 const ParseJsonFieldsMap = {};
+/**
+ * Relation fields declared via the plain `defineFields` pattern (not via
+ * `customFields`/`mapping`). Keyed by gqlEntityName → field name → target
+ * entity's ORM name (the raw string returned by `relatedEntityName()`). Used by
+ * `convertFilterEnumValues` to recurse into nested relation filters and apply
+ * the target entity's mapNumericEnum conversions.
+ */
+const RelationFieldsMap = {};
 const aclMap = {};
 /**
  * Shared field-metadata registration used by both the @GQLEntityClass decorator
@@ -167,6 +175,14 @@ const clearParseJsonFields = () => {
     }
 };
 exports.clearParseJsonFields = clearParseJsonFields;
+const getRelationFieldsFor = (name) => RelationFieldsMap[name] ?? {};
+exports.getRelationFieldsFor = getRelationFieldsFor;
+const clearRelationFields = () => {
+    for (const key of Object.keys(RelationFieldsMap)) {
+        delete RelationFieldsMap[key];
+    }
+};
+exports.clearRelationFields = clearRelationFields;
 const getACLFor = (name) => aclMap[name] ?? {};
 exports.getACLFor = getACLFor;
 const getGQLEntityNameFor = (name) => `${name}${gqlTypesSuffix || process.env['D3GOP_TYPES_SUFFIX'] || ''}`;
@@ -436,7 +452,15 @@ function _buildInputType(gqlEntityName, fields, opts, metadata, customFields) {
     return GQLEntityInput;
 }
 // ─── Shared resolver builder ─────────────────────────────────────────────────
-/** Phase 2: attach @FieldResolver methods for fields with `mapNumericEnum` (reverse-maps DB number → enum string). */
+/**
+ * Phase 2: attach @FieldResolver methods for fields with `mapNumericEnum`.
+ *
+ * The resolver returns the raw DB value unchanged. graphql-js's
+ * `GraphQLEnumType.serialize()` performs the value→name conversion itself
+ * (e.g. 100 → "Forged") using the internal values registered by
+ * `registerEnumType`. Returning the string key here would cause
+ * "Enum cannot represent value" errors at serialization time.
+ */
 function _registerMapNumericEnumResolvers(rawFields, FieldsResolver) {
     for (const fieldName of Object.keys(rawFields)) {
         const fieldOpts = rawFields[fieldName];
@@ -448,20 +472,7 @@ function _registerMapNumericEnumResolvers(rawFields, FieldsResolver) {
             const value = root[fieldNameToUse];
             if (value === null || value === undefined)
                 return null;
-            try {
-                const enumObj = enumTypeThunk();
-                const key = enumObj[value];
-                if (typeof key === 'string')
-                    return key;
-                for (const enumKey of Object.keys(enumObj)) {
-                    if (enumObj[enumKey] === value)
-                        return enumKey;
-                }
-                return value;
-            }
-            catch {
-                return value;
-            }
+            return value;
         };
         Object.defineProperty(FieldsResolver.prototype, fieldNameToUse, {
             value: resolveFn,
@@ -597,7 +608,15 @@ function _registerMappingFieldFilter(fieldNameToUse, fieldOptions, GQLEntityFilt
         target: GQLEntityFilterInput,
         name: UppercasedFieldName,
         schemaName: UppercasedFieldName,
-        getType: () => TypeMap[refFilterTypeName] ?? GQLEntityFilterInput,
+        getType: () => {
+            const type = TypeMap[refFilterTypeName];
+            if (!type) {
+                throw new Error(`gql-of-power: FilterInput for referenced entity "${refGqlEntityName}" (${refFilterTypeName}) ` +
+                    `is not registered. Make sure ${refGqlEntityName}'s buildResolvers() is called ` +
+                    `(or use createGQLTypes / @GQLEntityClass) before building the schema.`);
+            }
+            return type;
+        },
         typeOptions: { nullable: true },
         complexity: undefined,
         description: `Filter by ${fieldNameToUse} fields`,
@@ -788,7 +807,15 @@ function _registerExistsFilters(gqlEntityName, fields, opts, metadata, GQLEntity
                 target: GQLEntityExistsFilterInput,
                 name: relFieldName,
                 schemaName: relFieldName,
-                getType: () => TypeMap[relFilterTypeName] ?? GQLEntityFilterInput,
+                getType: () => {
+                    const type = TypeMap[relFilterTypeName];
+                    if (!type) {
+                        throw new Error(`gql-of-power: FilterInput for related entity "${relGQLEntityName}" (${relFilterTypeName}) ` +
+                            `is not registered. Make sure ${relGQLEntityName}'s buildResolvers() is called ` +
+                            `(or use createGQLTypes / @GQLEntityClass) before building the schema.`);
+                    }
+                    return type;
+                },
                 typeOptions: { nullable: true },
                 complexity: undefined,
                 description: `Filter ${relFieldName} by their fields for existence check`,
@@ -1003,6 +1030,16 @@ function createGQLEntityFilters(fieldOptions, fieldName, GQLEntity, metadata, GQ
             deprecationReason: undefined,
         };
         metadata.collectClassFieldMetadata(fieldFilter);
+        // Register relation fields for nested-filter enum conversion. The nested
+        // FilterInput is exposed under both the camelCased fieldName (above) and the
+        // UppercasedFieldName — record both so convertFilterEnumValues can resolve
+        // whichever key the caller uses.
+        if ('relatedEntityName' in fieldOptions && fieldOptions.relatedEntityName) {
+            RelationFieldsMap[gqlEntityName] = RelationFieldsMap[gqlEntityName] || {};
+            const relThunk = fieldOptions.relatedEntityName;
+            RelationFieldsMap[gqlEntityName][fieldName] = relThunk;
+            RelationFieldsMap[gqlEntityName][UppercasedFieldName] = relThunk;
+        }
         if ('array' in fieldOptions && 'relatedEntityName' in fieldOptions) {
             const relatedEntityName = (0, exports.getGQLEntityNameFor)(fieldOptions.relatedEntityName());
             metadata.collectHandlerParamMetadata({

package/dist/queries/enum-filter-converter.d.ts

@@ -0,0 +1,29 @@
+export declare function toDbValue(value: any, enumObj: any, isArray: boolean): any;
+export declare function findEnumFieldName(key: string, enumFields: Record<string, any>): string | null;
+/** Convert an operator-keyed object (e.g. { _eq: 'X', _in: [...] }) whose target is an enum field. */
+export declare function convertOperatorObject(operatorObject: Record<string, any>, enumObj: any): Record<string, any>;
+/** Recurse into a mapped custom-field nested filter using the referenced entity's enums. */
+export declare function convertMappedCustomField(key: string, value: any, mappedCustomFields: Record<string, {
+    mapping: {
+        refEntity: new () => any;
+    };
+}>): any;
+/**
+ * Recurse into a plain-`defineFields` relation nested filter using the target
+ * entity's enums. The relation field is looked up in `RelationFieldsMap`
+ * (registered by `createGQLEntityFilters`), which stores the target entity's
+ * ORM name thunk. Falls back to returning the value untouched if the key isn't
+ * a known relation field.
+ */
+export declare function convertRelationField(key: string, value: any, relationFields: Record<string, () => string>): any;
+export declare function convertFilterEnumValues(filter: any, enumFields: Record<string, any>, mappedCustomFields?: Record<string, {
+    mapping: {
+        refEntity: new () => any;
+    };
+}>, relationFields?: Record<string, () => string>): any;
+/** Resolve a single filter key/value to its enum-converted form. */
+export declare function convertFilterEntry(key: string, value: any, enumFields: Record<string, any>, mappedCustomFields?: Record<string, {
+    mapping: {
+        refEntity: new () => any;
+    };
+}>, relationFields?: Record<string, () => string>): any;

package/dist/queries/enum-filter-converter.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDbValue = toDbValue;
+exports.findEnumFieldName = findEnumFieldName;
+exports.convertOperatorObject = convertOperatorObject;
+exports.convertMappedCustomField = convertMappedCustomField;
+exports.convertRelationField = convertRelationField;
+exports.convertFilterEnumValues = convertFilterEnumValues;
+exports.convertFilterEntry = convertFilterEntry;
+/**
+ * Enum filter value conversion — shared module.
+ *
+ * Converts GraphQL enum string keys (e.g. `'Active'`) into their raw DB values
+ * (e.g. `0`) inside filter objects before they reach SQL generation.
+ *
+ * Extracted from `query-manager.ts` so that both `GQLQueryManager` (top-level
+ * filter path) and `GQLtoSQLMapper` (inline field-argument filter path) can
+ * import it without a circular dependency:
+ *
+ *   gql-to-sql-mapper ← (would cycle) ← query-manager
+ *   gql-to-sql-mapper ← enum-filter-converter → gql-entity
+ *   query-manager     ← enum-filter-converter → gql-entity
+ */
+const gql_entity_1 = require("../entities/gql-entity");
+const ENUM_OPERATORS = [
+    '_eq',
+    '_ne',
+    '_gt',
+    '_gte',
+    '_lt',
+    '_lte',
+    '_like',
+    '_re',
+    '_ilike',
+    '_fulltext',
+    '_in',
+    '_nin',
+    '_between',
+];
+/** Keys whose (array) value should be recursively enum-converted element-by-element. */
+const LOGICAL_KEYS = new Set(['_and', '_or', '_not']);
+/** Keys that are always passed through verbatim (existence subquery shapes). */
+const PASSTHROUGH_KEYS = new Set(['_exists', '_not_exists']);
+function toDbValue(value, enumObj, isArray) {
+    if (value === null || value === undefined)
+        return value;
+    if (isArray && Array.isArray(value)) {
+        return value.map((v) => {
+            if (typeof v === 'string' && v in enumObj)
+                return enumObj[v];
+            return v;
+        });
+    }
+    if (typeof value === 'string' && value in enumObj)
+        return enumObj[value];
+    return value;
+}
+function findEnumFieldName(key, enumFields) {
+    if (key in enumFields)
+        return key;
+    for (const op of ENUM_OPERATORS) {
+        if (key.endsWith(op)) {
+            const fieldName = key.slice(0, -op.length);
+            if (fieldName in enumFields)
+                return fieldName;
+        }
+    }
+    const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
+    if (lowercased in enumFields)
+        return lowercased;
+    return null;
+}
+/** Convert an operator-keyed object (e.g. { _eq: 'X', _in: [...] }) whose target is an enum field. */
+function convertOperatorObject(operatorObject, enumObj) {
+    const converted = {};
+    for (const [op, opVal] of Object.entries(operatorObject)) {
+        const isArr = op === '_in' || op === '_nin';
+        converted[op] = toDbValue(opVal, enumObj, isArr);
+    }
+    return converted;
+}
+/** Recurse into a mapped custom-field nested filter using the referenced entity's enums. */
+function convertMappedCustomField(key, value, mappedCustomFields) {
+    const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
+    const mappedField = mappedCustomFields[key] ??
+        mappedCustomFields[lowercased];
+    if (!mappedField)
+        return value;
+    const refGqlEntityName = (0, gql_entity_1.getGQLEntityNameFor)(mappedField.mapping.refEntity.name);
+    const refEnumFields = (0, gql_entity_1.getMapEnumFieldsFor)(refGqlEntityName);
+    const refCustomFields = (0, gql_entity_1.getCustomFieldsFor)(refGqlEntityName);
+    const refRelationFields = (0, gql_entity_1.getRelationFieldsFor)(refGqlEntityName);
+    return convertFilterEnumValues(value, refEnumFields, refCustomFields, refRelationFields);
+}
+/**
+ * Recurse into a plain-`defineFields` relation nested filter using the target
+ * entity's enums. The relation field is looked up in `RelationFieldsMap`
+ * (registered by `createGQLEntityFilters`), which stores the target entity's
+ * ORM name thunk. Falls back to returning the value untouched if the key isn't
+ * a known relation field.
+ */
+function convertRelationField(key, value, relationFields) {
+    const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
+    const relThunk = relationFields[key] ?? relationFields[lowercased];
+    if (!relThunk)
+        return value;
+    const targetGqlEntityName = (0, gql_entity_1.getGQLEntityNameFor)(relThunk());
+    const targetEnumFields = (0, gql_entity_1.getMapEnumFieldsFor)(targetGqlEntityName);
+    const targetCustomFields = (0, gql_entity_1.getCustomFieldsFor)(targetGqlEntityName);
+    const targetRelationFields = (0, gql_entity_1.getRelationFieldsFor)(targetGqlEntityName);
+    return convertFilterEnumValues(value, targetEnumFields, targetCustomFields, targetRelationFields);
+}
+function convertFilterEnumValues(filter, enumFields, mappedCustomFields, relationFields) {
+    if (!filter || typeof filter !== 'object' || Array.isArray(filter))
+        return filter;
+    if (Object.keys(enumFields).length === 0 &&
+        !mappedCustomFields &&
+        (!relationFields || Object.keys(relationFields).length === 0))
+        return filter;
+    const result = {};
+    for (const [key, value] of Object.entries(filter)) {
+        result[key] = convertFilterEntry(key, value, enumFields, mappedCustomFields, relationFields);
+    }
+    return result;
+}
+/** Resolve a single filter key/value to its enum-converted form. */
+function convertFilterEntry(key, value, enumFields, mappedCustomFields, relationFields) {
+    if (LOGICAL_KEYS.has(key)) {
+        return Array.isArray(value)
+            ? value.map((v) => convertFilterEnumValues(v, enumFields, mappedCustomFields, relationFields))
+            : value;
+    }
+    if (PASSTHROUGH_KEYS.has(key))
+        return value;
+    const enumFieldName = findEnumFieldName(key, enumFields);
+    if (enumFieldName) {
+        const enumObj = enumFields[enumFieldName];
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            return convertOperatorObject(value, enumObj);
+        }
+        const isArr = key.endsWith('_in') || key.endsWith('_nin');
+        return toDbValue(value, enumObj, isArr);
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        if (mappedCustomFields) {
+            const converted = convertMappedCustomField(key, value, mappedCustomFields);
+            if (converted !== value)
+                return converted;
+        }
+        if (relationFields) {
+            return convertRelationField(key, value, relationFields);
+        }
+    }
+    return value;
+}

package/dist/queries/gql-to-sql-mapper.js

@@ -7,6 +7,7 @@ const gql_to_sql_types_1 = require("../types/gql-to-sql-types");
 const object_1 = require("../utils/object");
 const variables_1 = require("../variables");
 const alias_1 = require("./alias");
+const enum_filter_converter_1 = require("./enum-filter-converter");
 const filter_processor_1 = require("./filter-processor");
 const relationship_handler_1 = require("./relationship-handler");
 const sql_builder_1 = require("./sql-builder");
@@ -411,11 +412,13 @@ class GQLtoSQLMapper {
         let filterOuterJoin = [];
         let filterOr = [];
         if (args?.filter) {
+            const countGqlEntityName = (0, gql_entity_1.getGQLEntityNameFor)(relatedMetadata.name ?? '');
+            const countConvertedFilter = (0, enum_filter_converter_1.convertFilterEnumValues)(args.filter, (0, gql_entity_1.getMapEnumFieldsFor)(countGqlEntityName), (0, gql_entity_1.getCustomFieldsFor)(countGqlEntityName), (0, gql_entity_1.getRelationFieldsFor)(countGqlEntityName));
             const filterMapped = this.recursiveMap({
                 entityMetadata: relatedMetadata,
                 parentAlias: countAlias,
                 alias: countAlias,
-                gqlFilters: [args.filter],
+                gqlFilters: [countConvertedFilter],
                 isFieldFilter: true,
             });
             const reduced = utils_1.QueriesUtils.mappingsReducer(filterMapped);
@@ -526,12 +529,29 @@ class GQLtoSQLMapper {
         const { filter, pagination } = args ?? {};
         variables_1.logger.log(prefix, 'args', parentGqlFieldNameKey, { ...filter }, JSON.stringify(pagination));
         if (filter || pagination) {
+            // Convert mapNumericEnum string keys → raw DB values for inline field
+            // filter args. The top-level filter goes through convertFilterEnumValues
+            // in GQLQueryManager, but inline filter args (e.g. `books(filter: {...})`)
+            // enter here and would otherwise bypass enum conversion, causing
+            // mapNumericEnum fields in sub-entity filters to fail silently.
+            //
+            // The filter keys belong to the TARGET entity (e.g. Book), not the parent
+            // (e.g. Author). We WRAP the filter under the field name and convert using
+            // the PARENT entity's registries — convertRelationField /
+            // convertMappedCustomField then resolve the target entity and recurse into
+            // its enum fields, handling arbitrary nesting depth.
+            const gqlEntityName = (0, gql_entity_1.getGQLEntityNameFor)(entityMetadata.name ?? '');
+            const parentEnumFields = (0, gql_entity_1.getMapEnumFieldsFor)(gqlEntityName);
+            const parentCustomFields = (0, gql_entity_1.getCustomFieldsFor)(gqlEntityName);
+            const parentRelationFields = (0, gql_entity_1.getRelationFieldsFor)(gqlEntityName);
+            const wrappedConverted = (0, enum_filter_converter_1.convertFilterEnumValues)({ [parentGqlFieldNameKey]: filter }, parentEnumFields, parentCustomFields, parentRelationFields);
+            const convertedFilter = wrappedConverted[parentGqlFieldNameKey] ?? filter;
             const mapped = this.recursiveMap({
                 entityMetadata,
                 parentAlias: alias,
                 alias,
                 gqlFilters: [
-                    { [parentGqlFieldNameKey]: { ...filter } },
+                    { [parentGqlFieldNameKey]: { ...convertedFilter } },
                 ],
                 isFieldFilter: true,
             });

package/dist/query-manager.d.ts

@@ -1,14 +1,11 @@
 import { GraphQLResolveInfo } from 'graphql';
+import { convertFilterEnumValues } from './queries/enum-filter-converter';
 import { DatabaseDriver, FieldSelection, MetadataProviderType } from './types/sql-types';
 import { GQLEntityFilterInputFieldType, GQLEntityOrderByInputType, GQLEntityPaginationInputType } from './types/gql-types';
+export { convertFilterEnumValues };
 export declare const getGQLFields: (info: GraphQLResolveInfo) => Partial<{
     [x: string]: {} | import("./types/sql-types").FieldDetails<any, string> | undefined;
 }>;
-export declare function convertFilterEnumValues(filter: any, enumFields: Record<string, any>, mappedCustomFields?: Record<string, {
-    mapping: {
-        refEntity: new () => any;
-    };
-}>): any;
 export declare class GQLQueryManager {
     private opts?;
     constructor(opts?: {

package/dist/query-manager.js

@@ -3,13 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GQLQueryManager = exports.getGQLFields = void 0;
-exports.convertFilterEnumValues = convertFilterEnumValues;
+exports.GQLQueryManager = exports.getGQLFields = exports.convertFilterEnumValues = void 0;
 const graphql_fields_1 = __importDefault(require("graphql-fields"));
 const graphql_parse_resolve_info_1 = require("graphql-parse-resolve-info");
 const knex_1 = __importDefault(require("knex"));
 const gql_entity_1 = require("./entities/gql-entity");
 const gql_to_sql_mapper_1 = require("./queries/gql-to-sql-mapper");
+const enum_filter_converter_1 = require("./queries/enum-filter-converter");
+Object.defineProperty(exports, "convertFilterEnumValues", { enumerable: true, get: function () { return enum_filter_converter_1.convertFilterEnumValues; } });
 const variables_1 = require("./variables");
 const getGQLFields = (info) => {
     graphql_fields_1.default;
@@ -34,108 +35,6 @@ const getGQLFields = (info) => {
     }
 };
 exports.getGQLFields = getGQLFields;
-const ENUM_OPERATORS = [
-    '_eq',
-    '_ne',
-    '_gt',
-    '_gte',
-    '_lt',
-    '_lte',
-    '_like',
-    '_re',
-    '_ilike',
-    '_fulltext',
-    '_in',
-    '_nin',
-    '_between',
-];
-/** Keys whose (array) value should be recursively enum-converted element-by-element. */
-const LOGICAL_KEYS = new Set(['_and', '_or', '_not']);
-/** Keys that are always passed through verbatim (existence subquery shapes). */
-const PASSTHROUGH_KEYS = new Set(['_exists', '_not_exists']);
-function toDbValue(value, enumObj, isArray) {
-    if (value === null || value === undefined)
-        return value;
-    if (isArray && Array.isArray(value)) {
-        return value.map((v) => {
-            if (typeof v === 'string' && v in enumObj)
-                return enumObj[v];
-            return v;
-        });
-    }
-    if (typeof value === 'string' && value in enumObj)
-        return enumObj[value];
-    return value;
-}
-function findEnumFieldName(key, enumFields) {
-    if (key in enumFields)
-        return key;
-    for (const op of ENUM_OPERATORS) {
-        if (key.endsWith(op)) {
-            const fieldName = key.slice(0, -op.length);
-            if (fieldName in enumFields)
-                return fieldName;
-        }
-    }
-    const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
-    if (lowercased in enumFields)
-        return lowercased;
-    return null;
-}
-/** Convert an operator-keyed object (e.g. { _eq: 'X', _in: [...] }) whose target is an enum field. */
-function convertOperatorObject(operatorObject, enumObj) {
-    const converted = {};
-    for (const [op, opVal] of Object.entries(operatorObject)) {
-        const isArr = op === '_in' || op === '_nin';
-        converted[op] = toDbValue(opVal, enumObj, isArr);
-    }
-    return converted;
-}
-/** Recurse into a mapped custom-field nested filter using the referenced entity's enums. */
-function convertMappedCustomField(key, value, mappedCustomFields) {
-    const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
-    const mappedField = mappedCustomFields[key] ??
-        mappedCustomFields[lowercased];
-    if (!mappedField)
-        return value;
-    const refGqlEntityName = (0, gql_entity_1.getGQLEntityNameFor)(mappedField.mapping.refEntity.name);
-    const refEnumFields = (0, gql_entity_1.getMapEnumFieldsFor)(refGqlEntityName);
-    return convertFilterEnumValues(value, refEnumFields);
-}
-function convertFilterEnumValues(filter, enumFields, mappedCustomFields) {
-    if (!filter || typeof filter !== 'object' || Array.isArray(filter))
-        return filter;
-    if (Object.keys(enumFields).length === 0 && !mappedCustomFields)
-        return filter;
-    const result = {};
-    for (const [key, value] of Object.entries(filter)) {
-        result[key] = convertFilterEntry(key, value, enumFields, mappedCustomFields);
-    }
-    return result;
-}
-/** Resolve a single filter key/value to its enum-converted form. */
-function convertFilterEntry(key, value, enumFields, mappedCustomFields) {
-    if (LOGICAL_KEYS.has(key)) {
-        return Array.isArray(value)
-            ? value.map((v) => convertFilterEnumValues(v, enumFields, mappedCustomFields))
-            : value;
-    }
-    if (PASSTHROUGH_KEYS.has(key))
-        return value;
-    const enumFieldName = findEnumFieldName(key, enumFields);
-    if (enumFieldName) {
-        const enumObj = enumFields[enumFieldName];
-        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-            return convertOperatorObject(value, enumObj);
-        }
-        const isArr = key.endsWith('_in') || key.endsWith('_nin');
-        return toDbValue(value, enumObj, isArr);
-    }
-    if (typeof value === 'object' && value !== null && !Array.isArray(value) && mappedCustomFields) {
-        return convertMappedCustomField(key, value, mappedCustomFields);
-    }
-    return value;
-}
 class GQLQueryManager {
     opts;
     constructor(opts) {
@@ -178,6 +77,7 @@ class GQLQueryManager {
             }
             const customFields = (0, gql_entity_1.getCustomFieldsFor)((0, gql_entity_1.getGQLEntityNameFor)(entityName));
             const enumFields = (0, gql_entity_1.getMapEnumFieldsFor)((0, gql_entity_1.getGQLEntityNameFor)(entityName));
+            const relationFields = (0, gql_entity_1.getRelationFieldsFor)((0, gql_entity_1.getGQLEntityNameFor)(entityName));
             const mapper = new gql_to_sql_mapper_1.GQLtoSQLMapper(provider, this.opts);
             let entityForMapper = entity;
             if (entityName !== entity.name) {
@@ -186,7 +86,7 @@ class GQLQueryManager {
                 Object.defineProperty(entityForMapper, 'name', { value: entityName });
                 Object.setPrototypeOf(entityForMapper, entity);
             }
-            const convertedFilter = convertFilterEnumValues(filter, enumFields, customFields);
+            const convertedFilter = (0, enum_filter_converter_1.convertFilterEnumValues)(filter, enumFields, customFields, relationFields);
             const { bindings, querySQL } = mapper.buildQueryAndBindingsFor({
                 fields,
                 customFields,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dav3/gql-of-power",
-	"version": "1.4.0",
+	"version": "1.5.0",
 	"description": "Generate a single optimized SQL query from GraphQL operations — eliminate N+1 with recursive field-to-SQL mapping.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/entities/gql-entity.ts

@@ -34,6 +34,14 @@ const CustomFieldsMap: Record<string, CustomFieldsSettings<any>> = {};
 const CountFieldsMap: Record<string, Record<string, CountFieldMeta>> = {};
 const MapEnumFieldsMap: Record<string, Record<string, any>> = {};
 const ParseJsonFieldsMap: Record<string, Set<string>> = {};
+/**
+ * Relation fields declared via the plain `defineFields` pattern (not via
+ * `customFields`/`mapping`). Keyed by gqlEntityName → field name → target
+ * entity's ORM name (the raw string returned by `relatedEntityName()`). Used by
+ * `convertFilterEnumValues` to recurse into nested relation filters and apply
+ * the target entity's mapNumericEnum conversions.
+ */
+const RelationFieldsMap: Record<string, Record<string, () => string>> = {};
 
 const aclMap: AccessControlList<any, any> = {};
 
@@ -205,6 +213,15 @@ export const clearParseJsonFields = (): void => {
 	}
 };
 
+export const getRelationFieldsFor = (name: string): Record<string, () => string> =>
+	RelationFieldsMap[name] ?? {};
+
+export const clearRelationFields = (): void => {
+	for (const key of Object.keys(RelationFieldsMap)) {
+		delete RelationFieldsMap[key];
+	}
+};
+
 export const getACLFor = (name: string) => aclMap[name] ?? {};
 
 export const getGQLEntityNameFor = (name: string) =>
@@ -574,7 +591,15 @@ function _buildInputType<T>(
 
 // ─── Shared resolver builder ─────────────────────────────────────────────────
 
-/** Phase 2: attach @FieldResolver methods for fields with `mapNumericEnum` (reverse-maps DB number → enum string). */
+/**
+ * Phase 2: attach @FieldResolver methods for fields with `mapNumericEnum`.
+ *
+ * The resolver returns the raw DB value unchanged. graphql-js's
+ * `GraphQLEnumType.serialize()` performs the value→name conversion itself
+ * (e.g. 100 → "Forged") using the internal values registered by
+ * `registerEnumType`. Returning the string key here would cause
+ * "Enum cannot represent value" errors at serialization time.
+ */
 function _registerMapNumericEnumResolvers<T>(
 	rawFields: Partial<FieldsSettings<T>>,
 	FieldsResolver: any
@@ -589,17 +614,7 @@ function _registerMapNumericEnumResolvers<T>(
 		const resolveFn = (root: any) => {
 			const value = root[fieldNameToUse];
 			if (value === null || value === undefined) return null;
-			try {
-				const enumObj = enumTypeThunk();
-				const key = enumObj[value];
-				if (typeof key === 'string') return key;
-				for (const enumKey of Object.keys(enumObj)) {
-					if (enumObj[enumKey] === value) return enumKey;
-				}
-				return value;
-			} catch {
-				return value;
-			}
+			return value;
 		};
 
 		Object.defineProperty(FieldsResolver.prototype, fieldNameToUse, {
@@ -819,7 +834,17 @@ function _registerMappingFieldFilter<T>(
 		target: GQLEntityFilterInput,
 		name: UppercasedFieldName,
 		schemaName: UppercasedFieldName,
-		getType: () => TypeMap[refFilterTypeName] ?? GQLEntityFilterInput,
+		getType: () => {
+			const type = TypeMap[refFilterTypeName];
+			if (!type) {
+				throw new Error(
+					`gql-of-power: FilterInput for referenced entity "${refGqlEntityName}" (${refFilterTypeName}) ` +
+						`is not registered. Make sure ${refGqlEntityName}'s buildResolvers() is called ` +
+						`(or use createGQLTypes / @GQLEntityClass) before building the schema.`
+				);
+			}
+			return type;
+		},
 		typeOptions: { nullable: true },
 		complexity: undefined,
 		description: `Filter by ${fieldNameToUse} fields`,
@@ -1051,7 +1076,17 @@ function _registerExistsFilters<T>(
 				target: GQLEntityExistsFilterInput,
 				name: relFieldName,
 				schemaName: relFieldName,
-				getType: () => TypeMap[relFilterTypeName] ?? GQLEntityFilterInput,
+				getType: () => {
+					const type = TypeMap[relFilterTypeName];
+					if (!type) {
+						throw new Error(
+							`gql-of-power: FilterInput for related entity "${relGQLEntityName}" (${relFilterTypeName}) ` +
+								`is not registered. Make sure ${relGQLEntityName}'s buildResolvers() is called ` +
+								`(or use createGQLTypes / @GQLEntityClass) before building the schema.`
+						);
+					}
+					return type;
+				},
 				typeOptions: { nullable: true },
 				complexity: undefined,
 				description: `Filter ${relFieldName} by their fields for existence check`,
@@ -1348,6 +1383,17 @@ export function createGQLEntityFilters<T, K>(
 		} as FieldParameter;
 		metadata.collectClassFieldMetadata(fieldFilter);
 
+		// Register relation fields for nested-filter enum conversion. The nested
+		// FilterInput is exposed under both the camelCased fieldName (above) and the
+		// UppercasedFieldName — record both so convertFilterEnumValues can resolve
+		// whichever key the caller uses.
+		if ('relatedEntityName' in fieldOptions && fieldOptions.relatedEntityName) {
+			RelationFieldsMap[gqlEntityName] = RelationFieldsMap[gqlEntityName] || {};
+			const relThunk = fieldOptions.relatedEntityName as () => string;
+			RelationFieldsMap[gqlEntityName][fieldName] = relThunk;
+			RelationFieldsMap[gqlEntityName][UppercasedFieldName] = relThunk;
+		}
+
 		if ('array' in fieldOptions && 'relatedEntityName' in fieldOptions) {
 			const relatedEntityName = getGQLEntityNameFor(fieldOptions.relatedEntityName());
 

package/src/queries/enum-filter-converter.ts

@@ -0,0 +1,179 @@
+/**
+ * Enum filter value conversion — shared module.
+ *
+ * Converts GraphQL enum string keys (e.g. `'Active'`) into their raw DB values
+ * (e.g. `0`) inside filter objects before they reach SQL generation.
+ *
+ * Extracted from `query-manager.ts` so that both `GQLQueryManager` (top-level
+ * filter path) and `GQLtoSQLMapper` (inline field-argument filter path) can
+ * import it without a circular dependency:
+ *
+ *   gql-to-sql-mapper ← (would cycle) ← query-manager
+ *   gql-to-sql-mapper ← enum-filter-converter → gql-entity
+ *   query-manager     ← enum-filter-converter → gql-entity
+ */
+import {
+	getCustomFieldsFor,
+	getGQLEntityNameFor,
+	getMapEnumFieldsFor,
+	getRelationFieldsFor,
+} from '../entities/gql-entity';
+
+const ENUM_OPERATORS = [
+	'_eq',
+	'_ne',
+	'_gt',
+	'_gte',
+	'_lt',
+	'_lte',
+	'_like',
+	'_re',
+	'_ilike',
+	'_fulltext',
+	'_in',
+	'_nin',
+	'_between',
+] as const;
+
+/** Keys whose (array) value should be recursively enum-converted element-by-element. */
+const LOGICAL_KEYS = new Set(['_and', '_or', '_not']);
+/** Keys that are always passed through verbatim (existence subquery shapes). */
+const PASSTHROUGH_KEYS = new Set(['_exists', '_not_exists']);
+
+export function toDbValue(value: any, enumObj: any, isArray: boolean): any {
+	if (value === null || value === undefined) return value;
+	if (isArray && Array.isArray(value)) {
+		return value.map((v) => {
+			if (typeof v === 'string' && v in enumObj) return enumObj[v];
+			return v;
+		});
+	}
+	if (typeof value === 'string' && value in enumObj) return enumObj[value];
+	return value;
+}
+
+export function findEnumFieldName(key: string, enumFields: Record<string, any>): string | null {
+	if (key in enumFields) return key;
+	for (const op of ENUM_OPERATORS) {
+		if (key.endsWith(op)) {
+			const fieldName = key.slice(0, -op.length);
+			if (fieldName in enumFields) return fieldName;
+		}
+	}
+	const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
+	if (lowercased in enumFields) return lowercased;
+	return null;
+}
+
+/** Convert an operator-keyed object (e.g. { _eq: 'X', _in: [...] }) whose target is an enum field. */
+export function convertOperatorObject(
+	operatorObject: Record<string, any>,
+	enumObj: any
+): Record<string, any> {
+	const converted: Record<string, any> = {};
+	for (const [op, opVal] of Object.entries(operatorObject)) {
+		const isArr = op === '_in' || op === '_nin';
+		converted[op] = toDbValue(opVal, enumObj, isArr);
+	}
+	return converted;
+}
+
+/** Recurse into a mapped custom-field nested filter using the referenced entity's enums. */
+export function convertMappedCustomField(
+	key: string,
+	value: any,
+	mappedCustomFields: Record<string, { mapping: { refEntity: new () => any } }>
+): any {
+	const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
+	const mappedField =
+		mappedCustomFields[key as keyof typeof mappedCustomFields] ??
+		mappedCustomFields[lowercased as keyof typeof mappedCustomFields];
+	if (!mappedField) return value;
+	const refGqlEntityName = getGQLEntityNameFor(mappedField.mapping.refEntity.name);
+	const refEnumFields = getMapEnumFieldsFor(refGqlEntityName);
+	const refCustomFields = getCustomFieldsFor(refGqlEntityName);
+	const refRelationFields = getRelationFieldsFor(refGqlEntityName);
+	return convertFilterEnumValues(value, refEnumFields, refCustomFields, refRelationFields);
+}
+
+/**
+ * Recurse into a plain-`defineFields` relation nested filter using the target
+ * entity's enums. The relation field is looked up in `RelationFieldsMap`
+ * (registered by `createGQLEntityFilters`), which stores the target entity's
+ * ORM name thunk. Falls back to returning the value untouched if the key isn't
+ * a known relation field.
+ */
+export function convertRelationField(
+	key: string,
+	value: any,
+	relationFields: Record<string, () => string>
+): any {
+	const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
+	const relThunk = relationFields[key] ?? relationFields[lowercased];
+	if (!relThunk) return value;
+	const targetGqlEntityName = getGQLEntityNameFor(relThunk());
+	const targetEnumFields = getMapEnumFieldsFor(targetGqlEntityName);
+	const targetCustomFields = getCustomFieldsFor(targetGqlEntityName);
+	const targetRelationFields = getRelationFieldsFor(targetGqlEntityName);
+	return convertFilterEnumValues(value, targetEnumFields, targetCustomFields, targetRelationFields);
+}
+
+export function convertFilterEnumValues(
+	filter: any,
+	enumFields: Record<string, any>,
+	mappedCustomFields?: Record<string, { mapping: { refEntity: new () => any } }>,
+	relationFields?: Record<string, () => string>
+): any {
+	if (!filter || typeof filter !== 'object' || Array.isArray(filter)) return filter;
+	if (
+		Object.keys(enumFields).length === 0 &&
+		!mappedCustomFields &&
+		(!relationFields || Object.keys(relationFields).length === 0)
+	)
+		return filter;
+
+	const result: any = {};
+	for (const [key, value] of Object.entries(filter)) {
+		result[key] = convertFilterEntry(key, value, enumFields, mappedCustomFields, relationFields);
+	}
+	return result;
+}
+
+/** Resolve a single filter key/value to its enum-converted form. */
+export function convertFilterEntry(
+	key: string,
+	value: any,
+	enumFields: Record<string, any>,
+	mappedCustomFields?: Record<string, { mapping: { refEntity: new () => any } }>,
+	relationFields?: Record<string, () => string>
+): any {
+	if (LOGICAL_KEYS.has(key)) {
+		return Array.isArray(value)
+			? value.map((v: any) =>
+					convertFilterEnumValues(v, enumFields, mappedCustomFields, relationFields)
+				)
+			: value;
+	}
+	if (PASSTHROUGH_KEYS.has(key)) return value;
+
+	const enumFieldName = findEnumFieldName(key, enumFields);
+	if (enumFieldName) {
+		const enumObj = enumFields[enumFieldName];
+		if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+			return convertOperatorObject(value as Record<string, any>, enumObj);
+		}
+		const isArr = key.endsWith('_in') || key.endsWith('_nin');
+		return toDbValue(value, enumObj, isArr);
+	}
+
+	if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+		if (mappedCustomFields) {
+			const converted = convertMappedCustomField(key, value, mappedCustomFields);
+			if (converted !== value) return converted;
+		}
+		if (relationFields) {
+			return convertRelationField(key, value, relationFields);
+		}
+	}
+	return value;
+}

package/src/queries/gql-to-sql-mapper.ts

@@ -1,8 +1,11 @@
 import {
 	getCountFieldsFor,
+	getCustomFieldsFor,
 	getFieldByAlias,
 	getGQLEntityNameFor,
+	getMapEnumFieldsFor,
 	getParseJsonFieldsFor,
+	getRelationFieldsFor,
 } from '../entities/gql-entity';
 import {
 	CountFieldMeta,
@@ -22,6 +25,7 @@ import { MappingsType, mappingsTypeToString } from '../types/gql-to-sql-types';
 import { keys } from '../utils/object';
 import { logger } from '../variables';
 import { Alias, AliasManager, AliasType } from './alias';
+import { convertFilterEnumValues } from './enum-filter-converter';
 import { FilterProcessor } from './filter-processor';
 import { RelationshipHandler } from './relationship-handler';
 import { SQLBuilder } from './sql-builder';
@@ -840,11 +844,18 @@ export class GQLtoSQLMapper {
 		let filterOr: MappingsType[] = [];
 
 		if (args?.filter) {
+			const countGqlEntityName = getGQLEntityNameFor(relatedMetadata.name ?? '');
+			const countConvertedFilter = convertFilterEnumValues(
+				args.filter,
+				getMapEnumFieldsFor(countGqlEntityName),
+				getCustomFieldsFor(countGqlEntityName),
+				getRelationFieldsFor(countGqlEntityName)
+			);
 			const filterMapped = this.recursiveMap({
 				entityMetadata: relatedMetadata,
 				parentAlias: countAlias,
 				alias: countAlias,
-				gqlFilters: [args.filter],
+				gqlFilters: [countConvertedFilter],
 				isFieldFilter: true,
 			});
 
@@ -1120,12 +1131,35 @@ export class GQLtoSQLMapper {
 
 		logger.log(prefix, 'args', parentGqlFieldNameKey, { ...filter }, JSON.stringify(pagination));
 		if (filter || pagination) {
+			// Convert mapNumericEnum string keys → raw DB values for inline field
+			// filter args. The top-level filter goes through convertFilterEnumValues
+			// in GQLQueryManager, but inline filter args (e.g. `books(filter: {...})`)
+			// enter here and would otherwise bypass enum conversion, causing
+			// mapNumericEnum fields in sub-entity filters to fail silently.
+			//
+			// The filter keys belong to the TARGET entity (e.g. Book), not the parent
+			// (e.g. Author). We WRAP the filter under the field name and convert using
+			// the PARENT entity's registries — convertRelationField /
+			// convertMappedCustomField then resolve the target entity and recurse into
+			// its enum fields, handling arbitrary nesting depth.
+			const gqlEntityName = getGQLEntityNameFor(entityMetadata.name ?? '');
+			const parentEnumFields = getMapEnumFieldsFor(gqlEntityName);
+			const parentCustomFields = getCustomFieldsFor(gqlEntityName);
+			const parentRelationFields = getRelationFieldsFor(gqlEntityName);
+			const wrappedConverted = convertFilterEnumValues(
+				{ [parentGqlFieldNameKey]: filter },
+				parentEnumFields,
+				parentCustomFields,
+				parentRelationFields
+			);
+			const convertedFilter = wrappedConverted[parentGqlFieldNameKey] ?? filter;
+
 			const mapped = this.recursiveMap({
 				entityMetadata,
 				parentAlias: alias,
 				alias,
 				gqlFilters: [
-					{ [parentGqlFieldNameKey]: { ...filter } } as GQLEntityFilterInputFieldType<T>,
+					{ [parentGqlFieldNameKey]: { ...convertedFilter } } as GQLEntityFilterInputFieldType<T>,
 				],
 				isFieldFilter: true,
 			});

package/src/query-manager.ts

@@ -9,8 +9,10 @@ import {
 	getCustomFieldsFor,
 	getGQLEntityNameFor,
 	getMapEnumFieldsFor,
+	getRelationFieldsFor,
 } from './entities/gql-entity';
 import { GQLtoSQLMapper } from './queries/gql-to-sql-mapper';
+import { convertFilterEnumValues } from './queries/enum-filter-converter';
 import { DatabaseDriver, FieldSelection, MetadataProviderType } from './types/sql-types';
 import {
 	GQLEntityFilterInputFieldType,
@@ -19,6 +21,10 @@ import {
 } from './types/gql-types';
 import { logger } from './variables';
 
+// Re-export for backwards compatibility — consumers and tests import
+// convertFilterEnumValues from here.
+export { convertFilterEnumValues };
+
 export const getGQLFields = (info: GraphQLResolveInfo) => {
 	graphqlFields;
 	try {
@@ -44,126 +50,6 @@ export const getGQLFields = (info: GraphQLResolveInfo) => {
 	}
 };
 
-const ENUM_OPERATORS = [
-	'_eq',
-	'_ne',
-	'_gt',
-	'_gte',
-	'_lt',
-	'_lte',
-	'_like',
-	'_re',
-	'_ilike',
-	'_fulltext',
-	'_in',
-	'_nin',
-	'_between',
-] as const;
-
-/** Keys whose (array) value should be recursively enum-converted element-by-element. */
-const LOGICAL_KEYS = new Set(['_and', '_or', '_not']);
-/** Keys that are always passed through verbatim (existence subquery shapes). */
-const PASSTHROUGH_KEYS = new Set(['_exists', '_not_exists']);
-
-function toDbValue(value: any, enumObj: any, isArray: boolean): any {
-	if (value === null || value === undefined) return value;
-	if (isArray && Array.isArray(value)) {
-		return value.map((v) => {
-			if (typeof v === 'string' && v in enumObj) return enumObj[v];
-			return v;
-		});
-	}
-	if (typeof value === 'string' && value in enumObj) return enumObj[value];
-	return value;
-}
-
-function findEnumFieldName(key: string, enumFields: Record<string, any>): string | null {
-	if (key in enumFields) return key;
-	for (const op of ENUM_OPERATORS) {
-		if (key.endsWith(op)) {
-			const fieldName = key.slice(0, -op.length);
-			if (fieldName in enumFields) return fieldName;
-		}
-	}
-	const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
-	if (lowercased in enumFields) return lowercased;
-	return null;
-}
-
-/** Convert an operator-keyed object (e.g. { _eq: 'X', _in: [...] }) whose target is an enum field. */
-function convertOperatorObject(
-	operatorObject: Record<string, any>,
-	enumObj: any
-): Record<string, any> {
-	const converted: Record<string, any> = {};
-	for (const [op, opVal] of Object.entries(operatorObject)) {
-		const isArr = op === '_in' || op === '_nin';
-		converted[op] = toDbValue(opVal, enumObj, isArr);
-	}
-	return converted;
-}
-
-/** Recurse into a mapped custom-field nested filter using the referenced entity's enums. */
-function convertMappedCustomField(
-	key: string,
-	value: any,
-	mappedCustomFields: Record<string, { mapping: { refEntity: new () => any } }>
-): any {
-	const lowercased = key.charAt(0).toLowerCase() + key.slice(1);
-	const mappedField =
-		mappedCustomFields[key as keyof typeof mappedCustomFields] ??
-		mappedCustomFields[lowercased as keyof typeof mappedCustomFields];
-	if (!mappedField) return value;
-	const refGqlEntityName = getGQLEntityNameFor(mappedField.mapping.refEntity.name);
-	const refEnumFields = getMapEnumFieldsFor(refGqlEntityName);
-	return convertFilterEnumValues(value, refEnumFields);
-}
-
-export function convertFilterEnumValues(
-	filter: any,
-	enumFields: Record<string, any>,
-	mappedCustomFields?: Record<string, { mapping: { refEntity: new () => any } }>
-): any {
-	if (!filter || typeof filter !== 'object' || Array.isArray(filter)) return filter;
-	if (Object.keys(enumFields).length === 0 && !mappedCustomFields) return filter;
-
-	const result: any = {};
-	for (const [key, value] of Object.entries(filter)) {
-		result[key] = convertFilterEntry(key, value, enumFields, mappedCustomFields);
-	}
-	return result;
-}
-
-/** Resolve a single filter key/value to its enum-converted form. */
-function convertFilterEntry(
-	key: string,
-	value: any,
-	enumFields: Record<string, any>,
-	mappedCustomFields?: Record<string, { mapping: { refEntity: new () => any } }>
-): any {
-	if (LOGICAL_KEYS.has(key)) {
-		return Array.isArray(value)
-			? value.map((v: any) => convertFilterEnumValues(v, enumFields, mappedCustomFields))
-			: value;
-	}
-	if (PASSTHROUGH_KEYS.has(key)) return value;
-
-	const enumFieldName = findEnumFieldName(key, enumFields);
-	if (enumFieldName) {
-		const enumObj = enumFields[enumFieldName];
-		if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-			return convertOperatorObject(value as Record<string, any>, enumObj);
-		}
-		const isArr = key.endsWith('_in') || key.endsWith('_nin');
-		return toDbValue(value, enumObj, isArr);
-	}
-
-	if (typeof value === 'object' && value !== null && !Array.isArray(value) && mappedCustomFields) {
-		return convertMappedCustomField(key, value, mappedCustomFields);
-	}
-	return value;
-}
-
 export class GQLQueryManager {
 	constructor(private opts?: { namedParameterPrefix?: string }) {}
 	async getQueryResultsForInfo<T, FilterT = T, K = any>(
@@ -229,6 +115,7 @@ export class GQLQueryManager {
 			}
 			const customFields = getCustomFieldsFor(getGQLEntityNameFor(entityName));
 			const enumFields = getMapEnumFieldsFor(getGQLEntityNameFor(entityName));
+			const relationFields = getRelationFieldsFor(getGQLEntityNameFor(entityName));
 			const mapper = new GQLtoSQLMapper(provider, this.opts);
 
 			let entityForMapper: new () => T = entity;
@@ -238,7 +125,12 @@ export class GQLQueryManager {
 				Object.setPrototypeOf(entityForMapper, entity);
 			}
 
-			const convertedFilter = convertFilterEnumValues(filter, enumFields, customFields);
+			const convertedFilter = convertFilterEnumValues(
+				filter,
+				enumFields,
+				customFields,
+				relationFields
+			);
 
 			const { bindings, querySQL } = mapper.buildQueryAndBindingsFor({
 				fields,