@dav3/gql-of-power 1.3.0 → 1.5.0

package/.fallowrc.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "./node_modules/fallow/schema.json",
+	"entry": [
+		"src/index.{ts,tsx,js,jsx}",
+		"scripts/update-version.ts",
+		"tests/run-sample-tests.ts",
+		"tests/regression/generate-sql-snapshots.ts"
+	],
+	"ignorePatterns": ["dist/**", "coverage/**", "tests/fixtures/**", "examples/**"],
+	"ignoreDependencies": [],
+	"ignoreExports": [
+		{
+			"file": "src/types/gql-types.ts",
+			"exports": ["*"],
+			"reason": "Generated filter/pagination input type shapes consumed via type-graphql decorators, not direct imports."
+		}
+	],
+	"audit": {
+		"deadCodeBaseline": "fallow-baselines/dead-code.json",
+		"healthBaseline": "fallow-baselines/health.json",
+		"dupesBaseline": "fallow-baselines/dupes.json"
+	}
+}

package/.prettierignore

@@ -0,0 +1,13 @@
+# Build output
+dist/
+coverage/
+
+# Lockfiles (binary / auto-generated)
+bun.lockb
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+
+# fallow caches (auto-managed) + machine-generated baselines
+.fallow/
+fallow-baselines/

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
@@ -568,6 +712,27 @@ No `limit` or `offset` parameters are accepted — `LIMIT 1` is always applied.
 
 ---
 
+## Agent Integration
+
+This library ships an **agent skill** (`agents/`) that teaches AI coding assistants (Claude Code, Cursor, Hermes, or any agent reading `AGENTS.md`) how to scaffold gql-of-power entities, relationships, and advanced features correctly — using copy-paste templates, annotated relationship examples, and a decision tree for picking the right relationship type.
+
+To install it in a consumer project (one-time setup):
+
+```bash
+# Claude Code
+mkdir -p .claude/skills && cp -R node_modules/@dav3/gql-of-power/agents/ .claude/skills/gql-of-power/
+
+# Cursor
+mkdir -p .cursor/rules && cp node_modules/@dav3/gql-of-power/agents/SKILL.md .cursor/rules/gql-of-power.mdc
+
+# Hermes
+ln -s node_modules/@dav3/gql-of-power/agents ~/.hermes/skills/gql-of-power
+```
+
+See [`agents/install.md`](./agents/install.md) for full instructions (including a symlink option that tracks gql-of-power updates, slash-command setup, and a generic `AGENTS.md` snippet). Once installed, ask your agent to "add a gql-of-power entity" and it will follow the library's intended patterns.
+
+---
+
 ## Development
 
 ```bash
@@ -575,8 +740,11 @@ bun install        # Install dependencies
 bun run build      # Compile TypeScript → dist/
 bun run test       # Run all tests
 bun run test:watch # Watch mode
+bun run audit      # Codebase-intelligence gate (fallow): dead code, duplication, complexity
 ```
 
+`bun run audit` runs the changed-file gate against saved baselines in `.fallow/` and fails only on **new** findings it introduces. Use `bun run audit:full` for the complete report, or `bun run audit:dead-code` / `audit:dupes` / `audit:health` for individual analyses. See `AGENTS.md` for the full audit workflow.
+
 ---
 
 ## License

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

@@ -0,0 +1,136 @@
+// gql-of-power entity skeleton — copy, rename, and adapt.
+// Middle-earth themed example: a "Weapon" entity with a m:1 to its Bearer.
+//
+// This file is a template, not importable code. Place your real files in:
+//   schema/entities.ts   (ORM class + EntityMetadata)
+//   schema/fields.ts     (FieldsSettings)
+//   graphql/entities.ts  (createGQLTypes calls)
+//   graphql/resolvers.ts (@Resolver + @Query classes)
+
+import 'reflect-metadata';
+import { GraphQLResolveInfo } from 'graphql';
+import {
+	createGQLTypes,
+	GQLEntityFilterInputFieldType,
+	FieldsSettings,
+} from '@dav3/gql-of-power';
+import { EntityMetadata, EntityProperty, ReferenceType } from '@dav3/gql-of-power';
+import { Arg, Info, Int, Query, Resolver } from 'type-graphql';
+import { queryManager, provider } from './your-app-setup'; // <-- your wiring
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 1. ORM ENTITY CLASS  (schema/entities.ts)
+//    Plain TS class. Property names = JS names. Relationship fields optional.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class Weapon {
+	id!: number;
+	name!: string;
+	damage!: number;
+	// m:1 relationship — Weapon holds bearerId
+	bearerId?: number;
+	bearer?: Person;
+}
+
+export class Person {
+	id!: number;
+	name!: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2. ENTITY METADATA  (schema/entities.ts)
+//    SQL reality: table, PKs, column names, relationship join columns.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const prop = (
+	type: string,
+	name: string,
+	fieldNames: string[],
+	reference?: {
+		referenceType: ReferenceType;
+		joinColumns?: string[];
+		referencedColumnNames?: string[];
+		mappedBy?: string;
+	}
+): EntityProperty => ({
+	type,
+	name,
+	fieldNames,
+	mappedBy: reference?.mappedBy || '',
+	joinColumns: reference?.joinColumns || [],
+	referencedColumnNames: reference?.referencedColumnNames || [],
+	inverseJoinColumns: [],
+	pivotTable: '',
+	reference: reference?.referenceType,
+});
+
+export const WeaponMetadata: EntityMetadata<Weapon> = {
+	name: 'Weapon',
+	tableName: 'weapons',
+	primaryKeys: ['id'],
+	properties: {
+		id: prop('number', 'id', ['id']),
+		name: prop('string', 'name', ['weapon_name']),
+		damage: prop('number', 'damage', ['damage']),
+		bearerId: prop('number', 'bearerId', ['bearer_id']),
+		bearer: prop('Person', 'bearer', ['bearer_id'], {
+			referenceType: ReferenceType.MANY_TO_ONE,
+			joinColumns: ['bearer_id'],
+			referencedColumnNames: ['id'],
+		}),
+	},
+};
+
+export const PersonMetadata: EntityMetadata<Person> = {
+	name: 'Person',
+	tableName: 'persons',
+	primaryKeys: ['id'],
+	properties: {
+		id: prop('number', 'id', ['id']),
+		name: prop('string', 'name', ['person_name']),
+	},
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. FIELDS SETTINGS  (schema/fields.ts)
+//    How each field maps to GraphQL. Pass to createGQLTypes.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Create PersonGQL first (Weapon references it)
+export const PersonGQL = createGQLTypes(Person, {
+	id: { type: () => Number, generateFilter: true },
+	name: { type: () => String, generateFilter: true },
+});
+
+export const WeaponFields: Partial<FieldsSettings<Weapon>> = {
+	id: { type: () => Number, generateFilter: true },
+	name: { type: () => String, generateFilter: true },
+	damage: { type: () => Int, generateFilter: true },
+	bearer: {
+		type: () => PersonGQL.GQLEntity,
+		options: { nullable: true },
+		generateFilter: true,
+		relatedEntityName: () => Person.name,
+		getFilterType: () => Int,
+	},
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 4. WIRE + RESOLVE  (graphql/entities.ts, graphql/resolvers.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const WeaponGQL = createGQLTypes(Weapon, WeaponFields);
+
+@Resolver(() => WeaponGQL.GQLEntity || Object)
+export class WeaponResolver extends WeaponGQL.FieldsResolver {
+	@Query(() => [WeaponGQL.GQLEntity])
+	async weapons(
+		@Info() info: GraphQLResolveInfo,
+		@Arg('filter', () => WeaponGQL.GQLEntityFilterInput || Object, { nullable: true })
+		filter?: GQLEntityFilterInputFieldType<Weapon>
+	) {
+		// Relationship-field filters need `as any` (the type doesn't surface them):
+		//   { bearer: { name: 'Aragorn' } } as any
+		return await queryManager.getQueryResultsForInfo(provider, Weapon, info, filter);
+	}
+}

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

@@ -1,5 +1,6 @@
 import { getMetadataStorage } from 'type-graphql';
-import { CountFieldMeta, CustomFieldsSettings, FieldSettings, FieldsSettings, GQLEntityFilterInputFieldType, GQLEntityPaginationInputType, RelatedFieldSettings } from '../types';
+import { CountFieldMeta, CustomFieldsSettings, FieldSettings, FieldsSettings, RelatedFieldSettings } from '../types/sql-types';
+import { GQLEntityFilterInputFieldType, GQLEntityPaginationInputType } from '../types/gql-types';
 import { AccessControlEntry } from '../types/access-control';
 export declare const setGlobalConfig: (config: {
     gqlTypesSuffix?: string;
@@ -28,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;