@dav3/gql-of-power 1.2.0 → 1.3.0

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

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

@@ -1,5 +1,5 @@
 import { getMetadataStorage } from 'type-graphql';
-import { CustomFieldsSettings, FieldSettings, FieldsSettings, GQLEntityFilterInputFieldType, GQLEntityPaginationInputType, RelatedFieldSettings } from '../types';
+import { CountFieldMeta, CustomFieldsSettings, FieldSettings, FieldsSettings, GQLEntityFilterInputFieldType, GQLEntityPaginationInputType, RelatedFieldSettings } from '../types';
 import { AccessControlEntry } from '../types/access-control';
 export declare const setGlobalConfig: (config: {
     gqlTypesSuffix?: string;
@@ -8,6 +8,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 +54,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 +75,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 +162,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 +184,7 @@ export declare function createGQLTypes<T extends Object, K>(classType: new () =>
     GQLEntityOrderBy: {
         new (): {};
     };
+    GQLEntityInput: new () => any;
     FieldsResolver: {
         new (): {};
     };
@@ -177,13 +202,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().
  */