@dav3/gql-of-power 1.2.0 → 1.4.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

@@ -1,6 +1,6 @@
 # ⚔️ GQL of Power
 
-> **"One Query to Rule Them All"** — Master your data with the power of a single GraphQL query
+> **"One Query to Rule Them All"** — Master your data with the power of a single optimized SQL query
 
 ---
 
@@ -8,9 +8,9 @@
 
 In the age of microservices and data loaders, a shadow falls upon performance: _the N+1 query problem_. Weary developers traverse the lands of Middleware-earth, orchestrating countless queries to fetch interconnected data.
 
-But what if there was another way? What if, with the power of a single query, you could bind all your data together?
+But what if there was another way? What if, with the power of a single SQL query, you could bind all your data together?
 
-**GQL of Power** is a TypeScript library that harnesses ancient sorcery to generate perfectly optimized SQL queries from your GraphQL operations. It eliminates the need for data loaders entirely — one query to fetch your complete data structure, no matter how deeply nested your relationships run.
+**GQL of Power** is a TypeScript library that harnesses ancient sorcery to generate perfectly optimized SQL queries from your GraphQL operations. It eliminates the need for data loaders entirely — one SQL query to fetch your complete data structure, no matter how deeply nested your relationships run.
 
 Like the One Ring wielding dominion over all other Rings, GQL of Power commands your database with singular authority.
 
@@ -157,6 +157,7 @@ const fields = defineFields(Book, {
 | `alias`             | `string`            | Override the GQL field name                                                           |
 | `array`             | `true`              | Mark as array return type                                                             |
 | `relatedEntityName` | `() => string`      | ORM entity name for array relation fields (auto-derived when using `@GQLEntityClass`) |
+| `countFieldName`    | `string`            | Generate a count field for this relationship (see [Count Fields](#count-fields))      |
 | `enum`              | `EnumData`          | Register an enum type                                                                 |
 
 ### `@GQLEntityClass(OrmClass, fields, extra?)`
@@ -317,17 +318,114 @@ filter: {
 
 ### Filter operations
 
-| Operation      | Meaning                              |
-| -------------- | ------------------------------------ |
-| `_eq`          | Equal                                |
-| `_ne`          | Not equal                            |
-| `_in`          | In array                             |
-| `_nin`         | Not in array                         |
-| `_like`        | ILIKE (case-insensitive contains)    |
-| `_gt` / `_gte` | Greater than / greater than or equal |
-| `_lt` / `_lte` | Less than / less than or equal       |
-| `_and`         | Logical AND                          |
-| `_or`          | Logical OR (generates UNION ALL)     |
+| Operation      | Meaning                                                |
+| -------------- | ------------------------------------------------------ |
+| `_eq`          | Equal                                                  |
+| `_ne`          | Not equal                                              |
+| `_in`          | In array                                               |
+| `_nin`         | Not in array                                           |
+| `_like`        | ILIKE (case-insensitive contains)                      |
+| `_gt` / `_gte` | Greater than / greater than or equal                   |
+| `_lt` / `_lte` | Less than / less than or equal                         |
+| `_and`         | Logical AND                                            |
+| `_or`          | Logical OR (generates UNION ALL)                       |
+| `_exists`      | Check related entities exist (AND-combined per key)    |
+| `_not_exists`  | Check no related entities exist (AND-combined per key) |
+
+### Existence Filters (`_exists` / `_not_exists`)
+
+Check whether related entities match a set of conditions. Each key is a relationship field name; the value is a filter applied to that related entity. Multiple keys are AND-combined.
+
+```graphql
+# Authors that have at least one book titled "The Hobbit"
+filter: {
+  _exists: {
+    books: { title: "The Hobbit" }
+  }
+}
+
+# Authors that have a book titled "The Hobbit" AND no books in the "Horror" genre
+filter: {
+  _and: [
+    { _exists: { books: { title: "The Hobbit" } } }
+    { _not_exists: { books: { genre: "Horror" } } }
+  ]
+}
+
+# Persons who fought in a victory battle AND wrote a book about it
+filter: {
+  _exists: {
+    battles: { outcome: "Victory" }
+    books: { title: { _like: "%War%" } }
+  }
+}
+```
+
+`_exists` generates `EXISTS (SELECT 1 FROM ... WHERE ...)` subqueries. `_not_exists` generates `NOT EXISTS (...)`. Multiple keys within one `_exists`/`_not_exists` each produce a separate `EXISTS`/`NOT EXISTS` clause, AND-combined in the WHERE. OR across exists conditions is achieved via `_or`.
+
+---
+
+## Count Fields
+
+Add `countFieldName` to any relationship field with `array: true` to auto-generate an Int count field. The count is computed via a correlated `COUNT(*)` subquery — no JOINs in the outer query.
+
+### Definition
+
+```typescript
+const authorFields = defineFields(Author, {
+	id: { type: () => ID, generateFilter: true },
+	name: { type: () => String, generateFilter: true },
+	books: {
+		type: () => BookGQL,
+		array: true,
+		relatedEntityName: () => 'Book',
+		countFieldName: 'bookCount', // generates an `bookCount: Int` field
+	},
+});
+```
+
+### Querying
+
+```graphql
+query {
+	authors {
+		name
+		bookCount # total books
+		bookCount(filter: { publishedYear: { _gt: 1950 } }) # filtered count
+	}
+}
+```
+
+### Filtering by Count
+
+The count field is also available as a filter key with numeric operators:
+
+```graphql
+# Authors with exactly 4 books
+filter: { bookCount: 4 }
+
+# Authors with more than 3 books
+filter: { bookCount_gt: 3 }
+
+# Nested object form
+filter: { BookCount: { _gte: 2, _lte: 10 } }
+```
+
+Supported operators: `_eq`, `_ne`, `_gt`, `_gte`, `_lt`, `_lte`.
+
+### Generated SQL
+
+```sql
+-- bookCount (select)
+SELECT ...,
+  (SELECT COUNT(*) FROM "books" AS e_w1 WHERE e_w1.author_id = a_1.id) AS "bookCount"
+FROM authors AS a_1 ...
+
+-- bookCount_gt (filter)
+WHERE (SELECT COUNT(*) FROM "books" AS e_w1 WHERE e_w1.author_id = a_1.id) > :v_bookCount_gt__1
+```
+
+Works for all relationship types (1:m, m:1, m:n). For m:n, the pivot table is included in the subquery.
 
 ---
 
@@ -409,6 +507,34 @@ const results = await queryManager.getQueryResultsForFields(
 
 `BookGQL.relatedEntityName` (`'Book'`) is used automatically to look up ORM metadata — no need to pass the ORM class separately.
 
+### Singular Queries
+
+For fetching a single record, use the singular variants. These enforce `LIMIT 1` internally and return `K | null` instead of `K[]`:
+
+```typescript
+// From a GraphQL resolver
+const ring = await queryManager.getQueryResultForInfo(
+	metadataProvider,
+	RingGQL,
+	info,
+	{ forgedBy: 'Sauron' },
+	[{ forgedYear: 'desc' }] // optional orderBy — controls *which* record is returned
+);
+// ring: Ring | null
+
+// With explicit field selection
+const ring = await queryManager.getQueryResultForFields(
+	metadataProvider,
+	RingGQL,
+	{ id: {}, name: {} },
+	{ forgedBy: 'Sauron' },
+	[{ forgedYear: 'desc' }]
+);
+// ring: Ring | null
+```
+
+No `limit` or `offset` parameters are accepted — `LIMIT 1` is always applied.
+
 ---
 
 ## Architecture
@@ -442,6 +568,27 @@ const results = await queryManager.getQueryResultsForFields(
 
 ---
 
+## 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
@@ -449,8 +596,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 { 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;
@@ -8,6 +9,26 @@ export declare const setGlobalConfig: (config: {
 export declare const getFieldsOptionsFor: (name: string) => Record<string, string>;
 export declare const getFieldByAlias: (entityName: string | undefined, alias: string) => string;
 export declare const getCustomFieldsFor: (name: string) => CustomFieldsSettings<any>;
+/**
+ * Returns the count fields registered for the given GQL entity name.
+ * Keyed by the count field name (e.g. 'bookCount'), value is the count field metadata.
+ */
+export declare const getCountFieldsFor: (name: string) => Record<string, CountFieldMeta>;
+/**
+ * Manually registers a count field for an entity.
+ * Useful for testing without the @GQLEntityClass decorator.
+ * In production, count fields are auto-registered by the decorator when `countFieldName` is set.
+ */
+export declare const registerCountField: (gqlEntityName: string, countFieldName: string, relationshipFieldName: string, relatedEntityName: () => string) => void;
+/**
+ * Clears all registered count fields. Intended for test teardown.
+ */
+export declare const clearCountFields: () => void;
+export declare const getMapEnumFieldsFor: (name: string) => Record<string, any>;
+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 getACLFor: (name: string) => AccessControlEntry<any, any>;
 export declare const getGQLEntityNameFor: (name: string) => string;
 export declare const getGQLEntityNameForClass: <T>(classType: new () => T) => string;
@@ -34,6 +55,7 @@ export type GQLEntityStaticMembers = {
     readonly FilterInput: new () => any;
     readonly PaginationInput: new () => any;
     readonly OrderBy: new () => any;
+    readonly Input: new () => any;
     readonly FieldsResolver: new () => any;
     readonly gqlEntityName: string;
     readonly relatedEntityName: string;
@@ -54,6 +76,7 @@ export declare abstract class GQLEntityBase {
     static FilterInput: new () => any;
     static PaginationInput: new () => any;
     static OrderBy: new () => any;
+    static Input: new () => any;
     static FieldsResolver: new () => any;
     static gqlEntityName: string;
     static relatedEntityName: string;
@@ -140,12 +163,14 @@ export declare function createGQLEntity<T extends Object, K>(classType: new () =
         GQLEntityOrderBy: {
             new (): {};
         };
+        GQLEntityInput: new () => any;
         FieldsResolver: {
             new (): {};
         };
         bindFieldResolvers: (_c: any) => void;
     };
 };
+type TypeGQLMetadataStorage = ReturnType<typeof getMetadataStorage>;
 /**
  * Convenience wrapper — creates entity, builds resolvers, and returns everything merged.
  * Equivalent to calling `createGQLEntity(...).buildResolvers()` and merging results.
@@ -160,6 +185,7 @@ export declare function createGQLTypes<T extends Object, K>(classType: new () =>
     GQLEntityOrderBy: {
         new (): {};
     };
+    GQLEntityInput: new () => any;
     FieldsResolver: {
         new (): {};
     };
@@ -177,13 +203,13 @@ export declare function createGQLTypes<T extends Object, K>(classType: new () =>
         GQLEntityOrderBy: {
             new (): {};
         };
+        GQLEntityInput: new () => any;
         FieldsResolver: {
             new (): {};
         };
         bindFieldResolvers: (_c: any) => void;
     };
 };
-type TypeGQLMetadataStorage = ReturnType<typeof getMetadataStorage>;
 /**
  * Creates filter and sorting metadata for a field. Called during buildResolvers().
  */