@dav3/gql-of-power 1.7.0 → 1.9.0

package/README.md

@@ -14,6 +14,8 @@ But what if there was another way? What if, with the power of a single SQL query
 
 Like the One Ring wielding dominion over all other Rings, GQL of Power commands your database with singular authority.
 
+> 🎮 **[Try the Live Demo](https://dave-palt.github.io/gql-of-power/)** — Write GraphQL queries in the browser and watch the SQL generate in real time. 100% client-side, no database needed.
+
 ---
 
 ## Features
@@ -554,13 +556,13 @@ pagination: {
 
 ### Environment Variables
 
-| Variable                     | Purpose                                                                                     |
-| ---------------------------- | ------------------------------------------------------------------------------------------- |
-| `D3GOP_TYPES_SUFFIX`         | Suffix appended to all generated GQL entity type names (e.g. `'V2'` → `BookV2`, `AuthorV2`) |
-| `D3GOP_SORT_SUFFIX`          | Suffix appended to sort/pagination types only (e.g. `'V2'` → `SortV2`, `BookV2OrderBy`)     |
-| `D3GOP_LOG_TYPE`             | Logging level: `debug` or `disabled`                                                        |
-| `D3GOP_DEFAULT_QUERY_LIMIT`  | Default query limit when pagination is not specified (default: `3000`)                      |
-| `D3GOP_USE_STRING_FOR_JSONB` | Toggle between JSONB and string concatenation for JSON aggregation                          |
+| Variable                       | Purpose                                                                                                   |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `D3GOP_TYPES_SUFFIX`           | Suffix appended to all generated GQL entity type names (e.g. `'V2'` → `BookV2`, `AuthorV2`)               |
+| `D3GOP_SORT_SUFFIX`            | Suffix appended to sort/pagination types only (e.g. `'V2'` → `SortV2`, `BookV2OrderBy`)                   |
+| `D3GOP_LOG_TYPE`               | Logging level: `debug` or `disabled`                                                                      |
+| `D3GOP_DEFAULT_QUERY_LIMIT`    | Default query limit when pagination is not specified (default: `3000`)                                    |
+| `D3GOP_USE_STRING_FOR_JSONB`   | Toggle between JSONB and string concatenation for JSON aggregation                                        |
 | `GQL_OF_POWER_MAP_ENUM_OUTPUT` | Enum output mode: `raw` (default) or `key`. See [mapEnumOutput](#mapenumoutput-sdl-schema-support) below. |
 
 > **Type name collision**: If you have both v1 (`createGQLTypes`) and v2 (`@GQLEntityClass`) entities in the same schema, set `D3GOP_TYPES_SUFFIX` so v2 entity names are distinct (e.g. `Hobbit` → `HobbitV2`). Use `D3GOP_SORT_SUFFIX` separately if sort/pagination types also need a suffix. No `setGlobalConfig()` call is required — the env vars are read automatically.
@@ -777,19 +779,19 @@ setGlobalConfig({ mapEnumOutput: 'key' });
 ```typescript
 // Or per-field
 const fields = defineFields(MyEntity, {
-  stateCode: {
-    type: () => StateCode,
-    mapNumericEnum: true,
-    mapEnumOutput: 'key',   // override per field
-    generateFilter: true,
-  },
+	stateCode: {
+		type: () => StateCode,
+		mapNumericEnum: true,
+		mapEnumOutput: 'key', // override per field
+		generateFilter: true,
+	},
 });
 ```
 
-| Mode | SQL output | Works with |
-|------|-----------|------------|
-| `'raw'` (default) | `e_a1.state_code AS "stateCode"` | Live `buildSchema()` — graphql-js has `{ value: 0 }` |
-| `'key'` | `CASE e_a1.state_code WHEN 0 THEN 'ACTIVE' ... END AS "stateCode"` | SDL-rebuilt schema — graphql-js has `{ value: "ACTIVE" }` |
+| Mode              | SQL output                                                         | Works with                                                |
+| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
+| `'raw'` (default) | `e_a1.state_code AS "stateCode"`                                   | Live `buildSchema()` — graphql-js has `{ value: 0 }`      |
+| `'key'`           | `CASE e_a1.state_code WHEN 0 THEN 'ACTIVE' ... END AS "stateCode"` | SDL-rebuilt schema — graphql-js has `{ value: "ACTIVE" }` |
 
 Both modes produce identical JSON output: enum fields come back as string keys (`"ACTIVE"`).
 
@@ -837,7 +839,7 @@ If you are an AI agent that has been asked to set up or use this library:
 
 1. **Read `AGENTS.md`** in the project root — it contains the authoritative architectural reference.
 2. **Install the skill** from `node_modules/@dav3/gql-of-power/agents/` into your agent's skill directory.
-3. **Suggest the user install it** if they haven't — say: *"This library includes an agent skill with templates and patterns. Want me to install it?"*
+3. **Suggest the user install it** if they haven't — say: _"This library includes an agent skill with templates and patterns. Want me to install it?"_
 4. Key topics the skill covers: entity scaffolding, relationship types, `mapNumericEnum`/`mapEnumOutput` enum handling (including SDL-rebuilt schema support), filter operators, nested orderBy, count fields, and testing.
 
 ---

package/agents/templates/entity-skeleton.ts.txt

@@ -14,7 +14,7 @@ import {
 	GQLEntityFilterInputFieldType,
 	FieldsSettings,
 } from '@dav3/gql-of-power';
-import { EntityMetadata, EntityProperty, ReferenceType } from '@dav3/gql-of-power';
+import { EntityMetadata, EntityProperty, ReferenceType, RelationOwnership } from '@dav3/gql-of-power';
 import { Arg, Info, Int, Query, Resolver } from 'type-graphql';
 import { queryManager, provider } from './your-app-setup'; // <-- your wiring
 
@@ -50,13 +50,12 @@ const prop = (
 		referenceType: ReferenceType;
 		joinColumns?: string[];
 		referencedColumnNames?: string[];
-		mappedBy?: string;
-	}
+	} & RelationOwnership
 ): EntityProperty => ({
 	type,
 	name,
 	fieldNames,
-	mappedBy: reference?.mappedBy || '',
+	...reference,
 	joinColumns: reference?.joinColumns || [],
 	referencedColumnNames: reference?.referencedColumnNames || [],
 	inverseJoinColumns: [],

package/dist/queries/filter-processor.js

@@ -488,7 +488,7 @@ class FilterProcessor extends operations_1.ClassOperations {
         const countAlias = this.aliasManager.next(alias_1.AliasType.entity, 'w');
         let joinCondition = '';
         if (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_MANY ||
-            fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE) {
+            (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)) {
             const refFieldProps = relatedMetadata.properties[fieldProps.mappedBy];
             const ons = refFieldProps.joinColumns;
             const entityOns = refFieldProps.referencedColumnNames;
@@ -496,7 +496,8 @@ class FilterProcessor extends operations_1.ClassOperations {
                 .map((o, i) => `${parentAlias.toColumnName(o)} = ${countAlias.toColumnName(ons[i])}`)
                 .join(' and ');
         }
-        else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE) {
+        else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE ||
+            (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)) {
             const ons = fieldProps.referencedColumnNames.length > 0
                 ? fieldProps.referencedColumnNames
                 : relatedMetadata.primaryKeys;
@@ -574,10 +575,11 @@ class FilterProcessor extends operations_1.ClassOperations {
         variables_1.logger.log('FilterProcessor - handleReferenceFieldFilter: referenceField', referenceField.name, fieldProps.reference, 'recursiveMapResults', recursiveMapResults, '_or', _or, alias.toString(), childAlias.toString());
         // Handle different relationship types
         if (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_MANY ||
-            fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE) {
+            (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)) {
             this.mapFilterOneToX(referenceField, fieldProps, alias, childAlias, gqlFieldName, whereWithValues, outerJoin, innerJoin, values, mapping, _or);
         }
-        else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE) {
+        else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE ||
+            (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)) {
             this.mapFilterManyToOne(fieldProps, referenceField, alias, childAlias, whereWithValues, outerJoin, innerJoin, mapping, values, _or);
         }
         else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_MANY) {
@@ -791,13 +793,16 @@ class FilterProcessor extends operations_1.ClassOperations {
      */
     mapFilterManyToOne(fieldProps, referenceField, parentAlias, alias, whereWithValues, outerJoin, innerJoin, mapping, values, _or) {
         if (fieldProps.fieldNames.length && referenceField.tableName) {
+            // On the owning side (m:1 or owning 1:1), mappedBy is empty and
+            // referenceField.properties[''] is undefined — only used for the
+            // error message below. Resolve defensively.
             const referenceFieldProps = referenceField.properties[fieldProps.mappedBy];
             const ons = fieldProps.referencedColumnNames.length > 0
                 ? fieldProps.referencedColumnNames
                 : referenceField.primaryKeys;
             const entityOns = fieldProps.fieldNames;
             if (ons.length !== entityOns.length) {
-                throw new Error(`m:1 join with different number of columns ${ons.length} !== ${entityOns.length} on ${referenceFieldProps.name}`);
+                throw new Error(`m:1 join with different number of columns ${ons.length} !== ${entityOns.length} on ${referenceFieldProps?.name ?? fieldProps.name}`);
             }
             const whereSQL = entityOns
                 .map((o, i) => {

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

@@ -366,11 +366,11 @@ class GQLtoSQLMapper {
     _dispatchRequiredRelationMapping(relFieldProps, refMetadata, mapping, latestAlias, childAlias, whereWithValues, refValues, refInnerJoin, refOuterJoin, refSelect, refJson, limit, offset, orderBy, config, ownerMetadata) {
         const primaryKeys = ownerMetadata?.primaryKeys ?? [];
         if (relFieldProps.reference === sql_types_1.ReferenceType.ONE_TO_MANY ||
-            (relFieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && relFieldProps.mappedBy)) {
+            (relFieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && !relFieldProps.inversedBy)) {
             this.relationshipHandler.mapOneToX(refMetadata, relFieldProps, mapping, latestAlias, childAlias, whereWithValues, refValues, limit, offset, orderBy, config.as, refJson, refSelect, refInnerJoin, refOuterJoin);
         }
         else if (relFieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE ||
-            (relFieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && !relFieldProps.mappedBy)) {
+            (relFieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && relFieldProps.inversedBy)) {
             this.relationshipHandler.mapManyToOne(relFieldProps, refMetadata, latestAlias, childAlias, mapping, whereWithValues, refValues, refInnerJoin, limit, offset, config.as, refSelect, refJson, refOuterJoin);
         }
         else if (relFieldProps.reference === sql_types_1.ReferenceType.MANY_TO_MANY) {
@@ -419,7 +419,7 @@ class GQLtoSQLMapper {
         // Build the join condition between parent and child, same logic as FilterProcessor
         let joinCondition = '';
         if (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_MANY ||
-            fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE) {
+            (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)) {
             const refFieldProps = relatedMetadata.properties[fieldProps.mappedBy];
             const ons = refFieldProps.joinColumns;
             const entityOns = refFieldProps.referencedColumnNames;
@@ -427,7 +427,8 @@ class GQLtoSQLMapper {
                 .map((o, i) => `${parentAlias.toColumnName(o)} = ${countAlias.toColumnName(ons[i])}`)
                 .join(' and ');
         }
-        else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE) {
+        else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE ||
+            (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)) {
             const ons = fieldProps.referencedColumnNames.length > 0
                 ? fieldProps.referencedColumnNames
                 : relatedMetadata.primaryKeys;
@@ -507,6 +508,10 @@ class GQLtoSQLMapper {
                 parentAlias: alias,
                 alias: childAlias,
                 parentGqlFieldNameKey: parentGqlFieldNameKey,
+                // Pass the inline filter (from `books(filter: {...})`) to the
+                // CHILD's recursiveMap so the WHERE lands inside the child's
+                // lateral join subquery — child-row filtering, NOT EXISTS on parent.
+                gqlFilters: mapping.inlineFilter ? [mapping.inlineFilter] : undefined,
             });
             variables_1.logger.log('NEW MAPPING:', { parentGqlFieldNameKey, gqlFieldName }, [...newMappings.keys()], (0, gql_to_sql_types_1.mappingsTypeToString)(mapping, true));
             const newMapping = utils_1.QueriesUtils.newMappings();
@@ -535,12 +540,12 @@ class GQLtoSQLMapper {
             }, true));
             variables_1.logger.log('GQLtoSQLMapper - recursiveMap - referenceField', referenceField.name, 'innerJoin', innerJoin, 'limit', limit, 'offset', offset, 'orderBy', mapping.orderBy, 'reference', fieldProps.reference, 'fields');
             if (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_MANY ||
-                (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && fieldProps.mappedBy)) {
+                (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)) {
                 variables_1.logger.warn('[DIAG mapField dispatch]', gqlFieldName, '→ mapOneToX');
                 this.relationshipHandler.mapOneToX(referenceField, fieldProps, mapping, alias, childAlias, whereWithValues, values, limit, offset, orderBy, gqlFieldName, json, select, innerJoin, outerJoin);
             }
             else if (fieldProps.reference === sql_types_1.ReferenceType.MANY_TO_ONE ||
-                (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && !fieldProps.mappedBy)) {
+                (fieldProps.reference === sql_types_1.ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)) {
                 variables_1.logger.warn('[DIAG mapField dispatch]', gqlFieldName, '→ mapManyToOne', 'fieldNames:', fieldProps.fieldNames, 'refTableName:', referenceField.tableName);
                 this.relationshipHandler.mapManyToOne(fieldProps, referenceField, alias, childAlias, mapping, whereWithValues, values, innerJoin, limit, offset, gqlFieldName, select, json, outerJoin);
             }
@@ -567,41 +572,28 @@ 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]: { ...convertedFilter } },
-                ],
-                isFieldFilter: true,
-            });
-            const { innerJoin, where: w, values, _or, _and, _not } = utils_1.QueriesUtils.mappingsReducer(mapped);
-            mapping.innerJoin.push(...innerJoin);
-            mapping.where.push(...w);
-            mapping.values = { ...mapping.values, ...values };
+            if (filter) {
+                // Convert mapNumericEnum string keys → raw DB values for inline
+                // field filter args. 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;
+                // Store the converted filter for mapField to pass to the child's
+                // recursiveMap. This ensures the WHERE clause lands inside the
+                // child's lateral join subquery (child-row filtering), NOT as an
+                // EXISTS on the parent.
+                mapping.inlineFilter = convertedFilter;
+            }
             mapping.limit = pagination?.limit;
             mapping.offset = pagination?.offset;
-            mapping._or.push(..._or);
-            mapping._and.push(..._and);
-            mapping._not.push(..._not);
             mapping.orderBy.push(...(pagination?.orderBy ?? []));
             variables_1.logger.log('GQLtoSQLMapper - handleFieldArguments - processed', filter, 'mapping', (0, gql_to_sql_types_1.mappingsTypeToString)(mapping, true));
         }

package/dist/types/gql-to-sql-types.d.ts

@@ -15,6 +15,15 @@ export type MappingsType = {
     _or: MappingsType[];
     _and: MappingsType[];
     _not: MappingsType[];
+    /**
+     * Converted inline filter args from a relation field's `filter` argument
+     * (e.g. `books(filter: { title_eq: "X" })`). Stored by
+     * `handleFieldArguments` and consumed by `mapField`, which passes it to the
+     * child entity's `recursiveMap` as `gqlFilters` so the WHERE lands inside
+     * the child's lateral join subquery (child-row filtering), NOT as an EXISTS
+     * on the parent.
+     */
+    inlineFilter?: any;
 };
 export declare const mappingsTypeToString: (m: MappingsType, full?: boolean) => string;
 export type FilterMappingType = {

package/dist/types/sql-types.d.ts

@@ -14,12 +14,26 @@ export type EntityProperty = {
     reference?: ReferenceType | string;
     name: string;
     fieldNames: string[];
-    mappedBy: string;
+} & RelationOwnership & {
     joinColumns: string[];
     referencedColumnNames: string[];
     inverseJoinColumns: string[];
     pivotTable: string;
 };
+/**
+ * Enforces mutual exclusivity between `mappedBy` and `inversedBy`.
+ * A relation is either:
+ *   - inverse side: `mappedBy` set, `inversedBy` absent
+ *   - owning side:  `inversedBy` set, `mappedBy` absent
+ * Scalar fields have neither (satisfies either branch since both are optional).
+ */
+export type RelationOwnership = {
+    mappedBy?: string;
+    inversedBy?: never;
+} | {
+    inversedBy?: string;
+    mappedBy?: never;
+};
 export type EntityMetadata<T> = {
     primaryKeys: string[];
     name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dav3/gql-of-power",
-	"version": "1.7.0",
+	"version": "1.9.0",
 	"description": "Generate a single optimized SQL query from GraphQL operations — eliminate N+1 with recursive field-to-SQL mapping. Ships with agent skill for AI coding assistants.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -28,7 +28,8 @@
 		"audit:dead-code": "fallow dead-code",
 		"audit:dupes": "fallow dupes",
 		"audit:health": "fallow health",
-		"audit:fix": "fallow fix"
+		"audit:fix": "fallow fix",
+		"build:demo": "bun build examples/demo/src/main.ts --target=browser --format=iife --outfile=examples/demo/dist/main.js --define process.env.D3GOP_LOG_TYPE='\"disabled\"'"
 	},
 	"keywords": [
 		"graphql",
@@ -48,6 +49,7 @@
 		"@graphql-tools/schema": "^10.0.38",
 		"@types/bun": "latest",
 		"@types/graphql-fields": "^1.3.9",
+		"class-validator": "^0.15.1",
 		"fallow": "^3.6.0",
 		"graphql-yoga": "^5.21.0",
 		"reflect-metadata": "^0.2.2",

package/src/queries/filter-processor.ts

@@ -844,7 +844,7 @@ export class FilterProcessor extends ClassOperations {
 		let joinCondition = '';
 		if (
 			fieldProps.reference === ReferenceType.ONE_TO_MANY ||
-			fieldProps.reference === ReferenceType.ONE_TO_ONE
+			(fieldProps.reference === ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)
 		) {
 			const refFieldProps = relatedMetadata.properties[
 				fieldProps.mappedBy as keyof typeof relatedMetadata.properties
@@ -854,7 +854,10 @@ export class FilterProcessor extends ClassOperations {
 			joinCondition = entityOns
 				.map((o, i) => `${parentAlias.toColumnName(o)} = ${countAlias.toColumnName(ons[i])}`)
 				.join(' and ');
-		} else if (fieldProps.reference === ReferenceType.MANY_TO_ONE) {
+		} else if (
+			fieldProps.reference === ReferenceType.MANY_TO_ONE ||
+			(fieldProps.reference === ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)
+		) {
 			const ons =
 				fieldProps.referencedColumnNames.length > 0
 					? fieldProps.referencedColumnNames
@@ -1039,7 +1042,7 @@ export class FilterProcessor extends ClassOperations {
 		// Handle different relationship types
 		if (
 			fieldProps.reference === ReferenceType.ONE_TO_MANY ||
-			fieldProps.reference === ReferenceType.ONE_TO_ONE
+			(fieldProps.reference === ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)
 		) {
 			this.mapFilterOneToX<T>(
 				referenceField,
@@ -1054,7 +1057,10 @@ export class FilterProcessor extends ClassOperations {
 				mapping,
 				_or
 			);
-		} else if (fieldProps.reference === ReferenceType.MANY_TO_ONE) {
+		} else if (
+			fieldProps.reference === ReferenceType.MANY_TO_ONE ||
+			(fieldProps.reference === ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)
+		) {
 			this.mapFilterManyToOne<T>(
 				fieldProps,
 				referenceField,
@@ -1548,9 +1554,12 @@ export class FilterProcessor extends ClassOperations {
 		_or: MappingsType[]
 	): void {
 		if (fieldProps.fieldNames.length && referenceField.tableName) {
+			// On the owning side (m:1 or owning 1:1), mappedBy is empty and
+			// referenceField.properties[''] is undefined — only used for the
+			// error message below. Resolve defensively.
 			const referenceFieldProps = referenceField.properties[
 				fieldProps.mappedBy as keyof typeof referenceField.properties
-			] as EntityProperty;
+			] as EntityProperty | undefined;
 
 			const ons =
 				fieldProps.referencedColumnNames.length > 0
@@ -1560,7 +1569,7 @@ export class FilterProcessor extends ClassOperations {
 
 			if (ons.length !== entityOns.length) {
 				throw new Error(
-					`m:1 join with different number of columns ${ons.length} !== ${entityOns.length} on ${referenceFieldProps.name}`
+					`m:1 join with different number of columns ${ons.length} !== ${entityOns.length} on ${referenceFieldProps?.name ?? fieldProps.name}`
 				);
 			}
 

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

@@ -735,7 +735,7 @@ export class GQLtoSQLMapper {
 		const primaryKeys = ownerMetadata?.primaryKeys ?? [];
 		if (
 			relFieldProps.reference === ReferenceType.ONE_TO_MANY ||
-			(relFieldProps.reference === ReferenceType.ONE_TO_ONE && relFieldProps.mappedBy)
+			(relFieldProps.reference === ReferenceType.ONE_TO_ONE && !relFieldProps.inversedBy)
 		) {
 			this.relationshipHandler.mapOneToX(
 				refMetadata,
@@ -756,7 +756,7 @@ export class GQLtoSQLMapper {
 			);
 		} else if (
 			relFieldProps.reference === ReferenceType.MANY_TO_ONE ||
-			(relFieldProps.reference === ReferenceType.ONE_TO_ONE && !relFieldProps.mappedBy)
+			(relFieldProps.reference === ReferenceType.ONE_TO_ONE && relFieldProps.inversedBy)
 		) {
 			this.relationshipHandler.mapManyToOne(
 				relFieldProps,
@@ -856,7 +856,7 @@ export class GQLtoSQLMapper {
 		let joinCondition = '';
 		if (
 			fieldProps.reference === ReferenceType.ONE_TO_MANY ||
-			fieldProps.reference === ReferenceType.ONE_TO_ONE
+			(fieldProps.reference === ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)
 		) {
 			const refFieldProps = relatedMetadata.properties[
 				fieldProps.mappedBy as keyof typeof relatedMetadata.properties
@@ -866,7 +866,10 @@ export class GQLtoSQLMapper {
 			joinCondition = entityOns
 				.map((o, i) => `${parentAlias.toColumnName(o)} = ${countAlias.toColumnName(ons[i])}`)
 				.join(' and ');
-		} else if (fieldProps.reference === ReferenceType.MANY_TO_ONE) {
+		} else if (
+			fieldProps.reference === ReferenceType.MANY_TO_ONE ||
+			(fieldProps.reference === ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)
+		) {
 			const ons =
 				fieldProps.referencedColumnNames.length > 0
 					? fieldProps.referencedColumnNames
@@ -998,6 +1001,10 @@ export class GQLtoSQLMapper {
 				parentAlias: alias,
 				alias: childAlias,
 				parentGqlFieldNameKey: parentGqlFieldNameKey,
+				// Pass the inline filter (from `books(filter: {...})`) to the
+				// CHILD's recursiveMap so the WHERE lands inside the child's
+				// lateral join subquery — child-row filtering, NOT EXISTS on parent.
+				gqlFilters: mapping.inlineFilter ? [mapping.inlineFilter] : undefined,
 			});
 
 			logger.log(
@@ -1068,7 +1075,7 @@ export class GQLtoSQLMapper {
 			);
 			if (
 				fieldProps.reference === ReferenceType.ONE_TO_MANY ||
-				(fieldProps.reference === ReferenceType.ONE_TO_ONE && fieldProps.mappedBy)
+				(fieldProps.reference === ReferenceType.ONE_TO_ONE && !fieldProps.inversedBy)
 			) {
 				logger.warn('[DIAG mapField dispatch]', gqlFieldName, '→ mapOneToX');
 				this.relationshipHandler.mapOneToX(
@@ -1090,7 +1097,7 @@ export class GQLtoSQLMapper {
 				);
 			} else if (
 				fieldProps.reference === ReferenceType.MANY_TO_ONE ||
-				(fieldProps.reference === ReferenceType.ONE_TO_ONE && !fieldProps.mappedBy)
+				(fieldProps.reference === ReferenceType.ONE_TO_ONE && fieldProps.inversedBy)
 			) {
 				logger.warn(
 					'[DIAG mapField dispatch]',
@@ -1182,49 +1189,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]: { ...convertedFilter } } as GQLEntityFilterInputFieldType<T>,
-				],
-				isFieldFilter: true,
-			});
+			if (filter) {
+				// Convert mapNumericEnum string keys → raw DB values for inline
+				// field filter args. 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 { innerJoin, where: w, values, _or, _and, _not } = QueriesUtils.mappingsReducer(mapped);
+				// Store the converted filter for mapField to pass to the child's
+				// recursiveMap. This ensures the WHERE clause lands inside the
+				// child's lateral join subquery (child-row filtering), NOT as an
+				// EXISTS on the parent.
+				mapping.inlineFilter = convertedFilter;
+			}
 
-			mapping.innerJoin.push(...innerJoin);
-			mapping.where.push(...w);
-			mapping.values = { ...mapping.values, ...values };
 			mapping.limit = pagination?.limit;
 			mapping.offset = pagination?.offset;
-			mapping._or.push(..._or);
-			mapping._and.push(..._and);
-			mapping._not.push(..._not);
 			mapping.orderBy.push(...(pagination?.orderBy ?? []));
 			logger.log(
 				'GQLtoSQLMapper - handleFieldArguments - processed',

package/src/types/gql-to-sql-types.ts

@@ -19,6 +19,15 @@ export type MappingsType = {
 	_or: MappingsType[];
 	_and: MappingsType[];
 	_not: MappingsType[];
+	/**
+	 * Converted inline filter args from a relation field's `filter` argument
+	 * (e.g. `books(filter: { title_eq: "X" })`). Stored by
+	 * `handleFieldArguments` and consumed by `mapField`, which passes it to the
+	 * child entity's `recursiveMap` as `gqlFilters` so the WHERE lands inside
+	 * the child's lateral join subquery (child-row filtering), NOT as an EXISTS
+	 * on the parent.
+	 */
+	inlineFilter?: any;
 };
 
 export const mappingsTypeToString = (m: MappingsType, full = false) => {

package/src/types/sql-types.ts

@@ -15,12 +15,22 @@ export type EntityProperty = {
 	reference?: ReferenceType | string;
 	name: string;
 	fieldNames: string[];
-	mappedBy: string;
-	joinColumns: string[];
-	referencedColumnNames: string[];
-	inverseJoinColumns: string[];
-	pivotTable: string;
-};
+} & RelationOwnership & {
+		joinColumns: string[];
+		referencedColumnNames: string[];
+		inverseJoinColumns: string[];
+		pivotTable: string;
+	};
+
+/**
+ * Enforces mutual exclusivity between `mappedBy` and `inversedBy`.
+ * A relation is either:
+ *   - inverse side: `mappedBy` set, `inversedBy` absent
+ *   - owning side:  `inversedBy` set, `mappedBy` absent
+ * Scalar fields have neither (satisfies either branch since both are optional).
+ */
+export type RelationOwnership =
+	{ mappedBy?: string; inversedBy?: never } | { inversedBy?: string; mappedBy?: never };
 
 export type EntityMetadata<T> = {
 	primaryKeys: string[];