@dav3/gql-of-power 1.0.1 → 1.2.0

package/README.md

@@ -10,7 +10,7 @@ In the age of microservices and data loaders, a shadow falls upon performance: _
 
 But what if there was another way? What if, with the power of a single 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 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.
 
@@ -20,7 +20,7 @@ Like the One Ring wielding dominion over all other Rings, GQL of Power commands
 
 ### 🗡️ Query Unification
 
-Generate a **single, optimized SQL query** from any GraphQL query structure—no matter how complex your relationships are.
+Generate a **single, optimized SQL query** from any GraphQL query structure — no matter how complex your relationships are.
 
 - ✨ **Eliminate Data Loaders** – Replace the tedious choreography of multiple queries with one powerful statement
 - 🏰 **Intelligent Relationship Handling** – Navigate 1:1, 1:m, m:1, and m:m relationships seamlessly
@@ -33,391 +33,429 @@ Generate a **single, optimized SQL query** from any GraphQL query structure—no
 - **Recursive Query Mapping** – Transforms GraphQL field selections into SQL recursively
 - **Automatic Join Generation** – Intelligently creates JOINs based on ORM entity relationships
 - **Dynamic Filtering** – Support for field-level and class-level filter operations (`_eq`, `_in`, `_like`, `_gt`, `_and`, `_or`, etc.)
-- **Pagination Support** – Native limit and offset handling through generated input types
-- **Custom Fields** – Extend entities with computed properties, DataLoaders, and business logic
-- **Framework Agnostic** – Works with any ORM through a simple MetadataProvider interface
+- **Pagination & Sorting** – Native limit, offset, and order-by handling
+- **Custom Fields** – Extend entities with computed properties, DataLoaders, or automatic SQL JOINs for unmapped foreign keys
+- **Framework Agnostic** – Works with any ORM through a simple `MetadataProvider` interface
 
 ---
 
 ## Installation
 
 ```bash
-# Using pnpm (recommended)
 pnpm add @dav3/gql-of-power
-
-# Using npm
-npm install @dav3/gql-of-power
-
-# Using yarn
-yarn add @dav3/gql-of-power
 ```
 
 ---
 
 ## Quick Start
 
-### 1. Define Your Entities
+### 1. Define Your GQL Entities
+
+Use `defineFields` + `@GQLEntityClass` to declare GraphQL entities. `defineFields` is typed against the ORM class — invalid field names are caught at compile time.
 
 ```typescript
-import { GQLEntity } from '@dav3/gql-of-power';
-import { ObjectType, Field, Int } from 'type-graphql';
+import { defineFields, GQLEntityBase, GQLEntityClass } from '@dav3/gql-of-power';
+import { Author, Book } from './orm-entities';
+import { ID, Int } from 'type-graphql';
+
+// --- Author ---
+const authorFields = defineFields(Author, {
+	id: { type: () => ID, generateFilter: true },
+	name: { type: () => String, generateFilter: true },
+});
 
-@ObjectType()
-export class Author extends GQLEntity {
-	@Field(() => Int)
-	id: number;
+@GQLEntityClass(Author, authorFields)
+export class AuthorGQL extends GQLEntityBase {}
 
-	@Field()
-	name: string;
+// --- Book ---
+const bookFields = defineFields(Book, {
+	id: { type: () => ID, generateFilter: true },
+	title: { type: () => String, generateFilter: true },
+	publishedYear: { type: () => Int, generateFilter: true },
+	author: { type: () => AuthorGQL, options: { nullable: true } },
+});
 
-	@Field(() => [Book])
-	books: Book[];
-}
+@GQLEntityClass(Book, bookFields)
+export class BookGQL extends GQLEntityBase {}
+```
 
-@ObjectType()
-export class Book extends GQLEntity {
-	@Field(() => Int)
-	id: number;
+The decorator attaches generated statics to the class:
 
-	@Field()
-	title: string;
+| Static                      | Purpose                                   |
+| --------------------------- | ----------------------------------------- |
+| `BookGQL.FilterInput`       | Generated filter input type               |
+| `BookGQL.PaginationInput`   | Generated pagination input type           |
+| `BookGQL.OrderBy`           | Generated order-by input type             |
+| `BookGQL.FieldsResolver`    | Auto-generated field resolver class       |
+| `BookGQL.gqlEntityName`     | GQL type name (with suffix if configured) |
+| `BookGQL.relatedEntityName` | ORM entity class name (`'Book'`)          |
 
-	@Field()
-	publicationYear: number;
+### 2. Write Resolvers
 
-	@Field(() => Author)
-	author: Author;
+```typescript
+import { Resolver, Query, Arg, Info } from 'type-graphql';
+import { GQLResolver, getAutoResolvers } from '@dav3/gql-of-power';
+import { GraphQLResolveInfo } from 'graphql';
+
+@GQLResolver(BookGQL)
+export class BookResolver {
+	@Query(() => [BookGQL])
+	async books(
+		@Arg('filter', () => BookGQL.FilterInput, { nullable: true }) filter: any,
+		@Arg('pagination', () => BookGQL.PaginationInput, { nullable: true }) pagination: any,
+		@Info() info: GraphQLResolveInfo
+	) {
+		return queryManager.getQueryResultsForInfo(metadataProvider, BookGQL, info, filter, pagination);
+	}
 }
 ```
 
-### 2. Configure Metadata
-
-Provide ORM metadata that tells GQL of Power about your tables, columns, and relationships:
+### 3. Build the Schema
 
 ```typescript
-const metadataProvider = {
-	getEntityMetadata: (entity) => ({
-		tableName: 'authors',
-		primaryKey: 'id',
-		fields: {
-			id: { columnName: 'id' },
-			name: { columnName: 'name' },
-		},
-	}),
-	// ... implement for all entities
-};
+import { buildSchemaSync } from 'type-graphql';
+import { getAutoResolvers } from '@dav3/gql-of-power';
+import '../entities'; // trigger @GQLEntityClass decoration
+
+const schema = buildSchemaSync({
+	resolvers: [
+		BookResolver,
+		...getAutoResolvers(), // FieldsResolver for every @GQLEntityClass entity
+	],
+});
 ```
 
-### 3. Execute Your Query
+---
+
+## Examples
+
+For complete, LotR-themed walkthroughs of both mapping strategies (direct ORM relation and custom field mapping), see **[EXAMPLES.md](./EXAMPLES.md)**.
+
+---
+
+## Entity API
+
+### `defineFields<T>(OrmClass, config)`
+
+Typed wrapper that constrains config keys to `keyof T`. Identity function at runtime — it exists purely for TypeScript inference.
 
 ```typescript
-import { QueryManager } from '@dav3/gql-of-power';
+const fields = defineFields(Book, {
+	id: { type: () => ID, generateFilter: true },
+	title: { type: () => String, generateFilter: true },
+	typo: { type: () => String }, // TS error — 'typo' is not keyof Book ✗
+});
+```
 
-const queryManager = new QueryManager(metadataProvider, knexInstance);
+#### Field options
 
-// Execute a complex query with a single SQL statement
-const result = await queryManager.execute(
-	Author,
-	gqlInfo, // GraphQL resolve info
-	{
-		filter: { name: { _eq: 'Tolkien' } },
-		pagination: { limit: 10, offset: 0 },
-	}
-);
+| Option              | Type                | Purpose                                                                               |
+| ------------------- | ------------------- | ------------------------------------------------------------------------------------- |
+| `type`              | `() => GraphQLType` | GraphQL return type (required)                                                        |
+| `generateFilter`    | `boolean`           | Generate filter input fields for this property                                        |
+| `options`           | `FieldOptions`      | type-graphql field options (nullable, description, etc.)                              |
+| `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`) |
+| `enum`              | `EnumData`          | Register an enum type                                                                 |
 
-// Returns all authors with all their books, published authors, and nested relationships
+### `@GQLEntityClass(OrmClass, fields, extra?)`
+
+Class decorator that registers the entity with type-graphql and attaches generated statics.
+
+```typescript
+@GQLEntityClass(Book, fields, {
+  customFields: { ... }, // optional — see Custom Fields
+  acl: { ... },          // optional — access control
+})
+export class BookGQL extends GQLEntityBase {}
 ```
 
----
+### `extends GQLEntityBase`
 
-## Architecture: The Rings of Power
+Required base class. Provides TypeScript visibility of the decorator-attached statics (`FilterInput`, `PaginationInput`, etc.) without `declare static` boilerplate on each entity.
 
-### The Fellowship: Core Components
+### `@GQLResolver(EntityClass)`
 
-| Component          | Purpose                                                           |
-| ------------------ | ----------------------------------------------------------------- |
-| **GQLtoSQLMapper** | The main artifact—transforms GraphQL into SQL with proper joins   |
-| **QueryManager**   | The orchestrator—manages the entire query execution flow          |
-| **EntitySystem**   | The registry—defines GraphQL entities with auto-generated filters |
-| **Operations**     | The spells—defines all available filtering operations             |
+Marks a class as a custom resolver for the given GQL entity. Applies `@Resolver(() => EntityClass)` and integrates with type-graphql's resolver merging (the auto `FieldsResolver` and your custom query resolver coexist seamlessly).
 
-### The Fellowship's Journey: Query Flow
+### `getAutoResolvers()`
 
-1. **Parsing** – GraphQL field selections are parsed using `graphql-fields`
-2. **Mapping** – `GQLtoSQLMapper.recursiveMap()` builds SQL recursively
-3. **Aggregation** – JSON aggregation combines nested results efficiently
-4. **Execution** – Final SQL is executed against your database
+Returns all `FieldsResolver` classes registered by `@GQLEntityClass` decorators. Pass the result into `buildSchemaSync({ resolvers: [...getAutoResolvers()] })`.
 
 ---
 
-## Advanced Usage
+## Custom Fields
+
+Custom fields extend a GQL entity with fields that don't exist as direct ORM properties. There are two mutually exclusive strategies.
 
-### Comprehensive Filtering
+### Strategy 1: `resolve` — DataLoader / computed
 
-Filter at any nesting level with powerful operations:
+Provide a GraphQL `@FieldResolver` function. The library fetches field(s) listed in `requires` from the main query, then your `resolve` function runs at GraphQL resolution time.
 
 ```typescript
-// Find authors with published books
-await queryManager.execute(Author, gqlInfo, {
-	filter: {
-		books: {
-			publicationYear: { _gte: 2000 },
+@GQLEntityClass(Fellowship, fields, {
+	customFields: {
+		firstMember: {
+			type: () => GraphQLJSON,
+			options: { nullable: true },
+			requires: 'id', // ensure 'id' is fetched even if client didn't request it
+			resolveDecorators: [Root(), Ctx()],
+			resolve: (root: Fellowship, ctx: any) => {
+				return memberDataLoader.load(root.id);
+			},
 		},
 	},
-});
-
-// Complex nested AND/OR conditions
-await queryManager.execute(Author, gqlInfo, {
-	filter: {
-		_and: [{ name: { _like: '%Tolkien%' } }, { books: { publicationYear: { _gte: 1950 } } }],
-	},
-});
+})
+export class FellowshipGQL extends GQLEntityBase {}
 ```
 
-### Pagination & Sorting
+#### `resolve` field options
 
-```typescript
-await queryManager.execute(Author, gqlInfo, {
-	pagination: {
-		limit: 20,
-		offset: 40,
-		orderBy: 'name', // ASC by default
-		orderByDirection: 'DESC',
-	},
-});
-```
-
-### Filter Operations
+| Option              | Purpose                                                                |
+| ------------------- | ---------------------------------------------------------------------- |
+| `type`              | GraphQL return type                                                    |
+| `options`           | type-graphql field options                                             |
+| `requires`          | Field name(s) to ensure are fetched from DB                            |
+| `resolve`           | The resolver function (required)                                       |
+| `resolveDecorators` | type-graphql parameter decorators in order (`[Root(), Ctx(), Info()]`) |
 
-| Operation      | Example                           | Meaning                            |
-| -------------- | --------------------------------- | ---------------------------------- |
-| `_eq`          | `{ id: { _eq: 5 } }`              | Equal to                           |
-| `_ne`          | `{ status: { _ne: 'inactive' } }` | Not equal to                       |
-| `_in`          | `{ id: { _in: [1, 2, 3] } }`      | In array                           |
-| `_like`        | `{ name: { _like: '%Frodo%' } }`  | String contains (case-insensitive) |
-| `_gt` / `_gte` | `{ year: { _gte: 1900 } }`        | Greater than (or equal)            |
-| `_lt` / `_lte` | `{ year: { _lte: 2000 } }`        | Less than (or equal)               |
+### Strategy 2: `mapping` — automatic SQL JOIN
 
-### Custom Fields
+Provide a `FieldMappingConfig`. The library generates a SQL `LEFT JOIN LATERAL` automatically and returns the related object directly from the SQL result. No resolver function needed.
 
-Beyond GQL of Power's automated query generation, you can add **custom fields** that execute custom logic alongside your data fetching. Perfect for computed properties, cross-cutting concerns, or batch loading.
+Use this when the foreign key exists as a plain column on the entity (not declared as an ORM relation).
 
 ```typescript
-// Define custom fields when creating GraphQL types
-const FellowshipGQL = createGQLTypes(Fellowship, FellowshipFields, {
-  customFields: {
-    // Custom field that fetches the first fellowship member
-    firstMember: {
-      type: () => GraphQLJSON,
-      options: { nullable: true },
-      requires: ['id'], // Fields that must be fetched from the database for this resolver
-      resolveDecorators: [Root(), Ctx(), Info()], // TypeGraphQL parameter decorators for the resolve function
-      resolve: (root: Fellowship, ctx: any, info: any) => {
-        // Your custom logic—can use DataLoader for batch loading
-        return memberDataLoader.load(root.id);
-      },
-    },
-  },
-});
-
-// Export FieldsResolver to use in your resolver classes
-export const FellowshipFieldsResolver = FellowshipGQL.FieldsResolver;
+import { Kingdom } from './orm-entities';
+
+@GQLEntityClass(Hobbit, fields, {
+	customFields: {
+		kingdom: {
+			type: () => KingdomGQL,
+			options: { nullable: true },
+			mapping: {
+				refEntity: Kingdom, // ORM entity class to JOIN to
+				refFields: 'id', // column(s) on Kingdom — keyof Kingdom ✓
+				fields: 'kingdomId', // column(s) on Hobbit — keyof Hobbit ✓
+			},
+		},
+	},
+})
+export class HobbitGQL extends GQLEntityBase {}
 ```
 
-#### Custom Field Configuration
-
-| Property | Purpose | Connection |
-|----------|---------|------------|
-| `type` | Declares the GraphQL return type that appears in the schema | The type clients see when querying this field |
-| `options` | TypeGraphQL field options like nullable, deprecation, descriptions | Controls field behavior in the GraphQL schema |
-| `requires` | Specifies which fields from the main query must be present in the result | GQL of Power ensures these database columns are fetched alongside the optimized query |
-| `resolve` | Function that receives the root entity object and returns the custom field value | Executed after the main query completes, receiving the fetched entity data |
-| `resolveDecorators` | TypeGraphQL decorators that map function parameters | Determines which context parameters (`Root`, `Ctx`, `Info`) are injected into the resolve function |
-
-#### Use Cases
+Composite FK — use arrays (must have the same length):
 
-🧙 **DataLoader Integration** – Batch-load related data without N+1
 ```typescript
-firstMember: {
-  type: () => PersonGQL.GQLEntity,
-  resolve: (root: Fellowship) => memberDataLoader.load(root.id),
+mapping: {
+  refEntity: Weapon,
+  refFields: ['realmId', 'weaponCode'],
+  fields:    ['realmId', 'weaponExternalId'],
 }
 ```
 
-✨ **Computed Properties** – Calculate derived values
-```typescript
-memberCount: {
-  type: () => Number,
-  resolve: (root: Fellowship) => root.members?.length || 0,
-}
+#### `mapping` field options
+
+| Option              | Type                              | Purpose                                                        |
+| ------------------- | --------------------------------- | -------------------------------------------------------------- |
+| `type`              | `() => GraphQLType`               | GraphQL return type                                            |
+| `options`           | `FieldOptions`                    | type-graphql field options (nullable, etc.)                    |
+| `mapping.refEntity` | `new () => TRef`                  | ORM entity class to JOIN to (must be in the metadata provider) |
+| `mapping.refFields` | `keyof TRef \| Array<keyof TRef>` | Column(s) on the ref entity to match against                   |
+| `mapping.fields`    | `keyof T \| Array<keyof T>`       | Column(s) on the owner entity to match from                    |
+
+> **Note**: `resolve` and `mapping` are mutually exclusive — TypeScript enforces this via a discriminated union. `resolveDecorators` and `requires` are only valid on the `resolve` branch.
+
+#### Generated SQL
+
+For `kingdom: { mapping: { refEntity: Kingdom, refFields: 'id', fields: 'kingdomId' } }`:
+
+```sql
+select e_a1.id, e_a1.kingdom_id, f_j1.value as "kingdom"
+from (
+  select e_a1.id, e_a1.kingdom_id
+  from hobbit as e_a1
+  where true
+) as e_a1
+left outer join lateral (
+  select row_to_json(f_j1)::jsonb as value
+  from (
+    select f_j1.id, f_j1.name
+    from kingdom as f_j1
+    where e_a1.kingdom_id = f_j1.id
+  ) as f_j1
+) as f_j1 on true
 ```
 
-🎭 **Business Logic** – Apply formatting, ACL, or transformations
-```typescript
-formattedName: {
-  type: () => String,
-  resolve: (root: Fellowship) => formatTitle(root.name),
-}
-```
+Returns `null` when the FK column is null (LEFT JOIN).
+
+---
 
-#### Using Custom Fields in Resolvers
+## Filtering
 
-To make custom fields available in your GraphQL resolvers, extend the generated `FieldsResolver` class:
+Filter at any nesting level:
 
 ```typescript
-import { Resolver, Query, Arg, Info } from 'type-graphql';
-import { FellowshipGQL, FellowshipFieldsResolver } from './entities';
-
-@Resolver(() => FellowshipGQL.GQLEntity)
-export class FellowshipResolver extends FellowshipFieldsResolver {
-  @Query(() => [FellowshipGQL.GQLEntity])
-  async fellowships(
-    @Info() info: GraphQLResolveInfo,
-    @Arg('filter', () => FellowshipGQL.GQLEntityFilterInput, { nullable: true })
-    filter?: GQLEntityFilterInputFieldType<Fellowship>
-  ) {
-    return await queryManager.getQueryResultsForInfo(
-      metadataProvider,
-      Fellowship,
-      info,
-      filter
-    );
-  }
+// Simple equality
+filter: { title: 'The Fellowship of the Ring' }
+
+// Operators
+filter: { publishedYear: { _gte: 1950 } }
+
+// Nested relation filter
+filter: { author: { name: { _like: '%Tolkien%' } } }
+
+// AND / OR
+filter: {
+  _or: [
+    { title: { _like: '%Ring%' } },
+    { publishedYear: { _lt: 1960 } },
+  ],
 }
 ```
 
-The `FieldsResolver` automatically handles custom field resolution alongside the main query execution. When a client requests a custom field, it will be resolved using your custom resolver logic while the rest of the query is handled by GQL of Power's optimized SQL generation.
+### 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)     |
 
-## Configuration
-
-### Environment Variables
+---
 
-```bash
-# Toggle between JSONB and string concatenation for JSON aggregation
-D3GOP_USE_STRING_FOR_JSONB=true
+## Pagination
 
-# Control logging output
-D3GOP_LOG_TYPE="debug"  # Options: debug, disabled
+```typescript
+pagination: {
+  limit: 20,
+  offset: 40,
+  orderBy: [{ publishedYear: 'desc' }],
+}
 ```
 
 ---
 
-## Common Commands
+## Relationship Handling
 
-### Development
+| Relationship           | SQL Strategy                                      |
+| ---------------------- | ------------------------------------------------- |
+| **m:1** (many-to-one)  | `LEFT JOIN LATERAL` + `row_to_json`               |
+| **1:1** (one-to-one)   | `LEFT JOIN LATERAL` + `row_to_json`               |
+| **1:m** (one-to-many)  | `LEFT JOIN LATERAL` + `json_agg`                  |
+| **m:m** (many-to-many) | Pivot table subquery + `json_agg`                 |
+| **custom `mapping`**   | `LEFT JOIN LATERAL` + `row_to_json` (same as m:1) |
 
-```bash
-# Install dependencies
-pnpm install
+---
 
-# Build the library
-pnpm run build
+## Configuration
 
-# Watch mode for development
-pnpm run watch
+### Environment Variables
 
-# Run all tests
-pnpm test
+| 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                          |
 
-# Run unit tests only
-pnpm test:unit
+> **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.
 
-# Run integration tests only
-pnpm test:integration
+### Programmatic config
 
-# Watch mode for tests
-pnpm test:watch
+```typescript
+import { setGlobalConfig } from '@dav3/gql-of-power';
 
-# Generate coverage report
-pnpm test:coverage
+// Call before any @GQLEntityClass decorators run (i.e. before importing entity files)
+setGlobalConfig({ gqlTypesSuffix: 'V2' });
 
-# Build for publishing
-pnpm run prepublishOnly
+// Optionally set a separate suffix for sort/pagination types
+setGlobalConfig({ gqlTypesSuffix: 'V2', gqlSortSuffix: 'V2' });
 ```
 
 ---
 
-## Why GQL of Power?
-
-### The Problem It Solves
-
-Traditional GraphQL + ORM combinations suffer from the **N+1 query problem**:
+## `GQLQueryManager`
 
-- Query 1: Fetch 10 authors
-- Query 2-11: Fetch books for each author (10 queries)
-- Query 12-21: Fetch publication details for each book (10 queries)
-- **Total: 21 queries** ❌
-
-### The Solution
+```typescript
+const queryManager = new GQLQueryManager();
+
+// From a GraphQL resolver — fields are parsed from resolve info automatically
+const results = await queryManager.getQueryResultsForInfo(
+	metadataProvider,
+	BookGQL, // @GQLEntityClass-decorated class or plain ORM class
+	info, // GraphQLResolveInfo
+	filter,
+	pagination
+);
 
-```
-GQL of Power: Fetch all data in **1 query** ✅
+// With explicit field selection (useful for testing or non-resolver contexts)
+const results = await queryManager.getQueryResultsForFields(
+	metadataProvider,
+	BookGQL,
+	{ id: {}, title: {} },
+	filter,
+	pagination
+);
 ```
 
-By analyzing your GraphQL query structure and ORM relationships, GQL of Power generates a single, optimized SQL query with intelligent joins and aggregations that returns your complete data structure.
+`BookGQL.relatedEntityName` (`'Book'`) is used automatically to look up ORM metadata — no need to pass the ORM class separately.
 
 ---
 
-## Architecture Highlights
+## Architecture
 
-### Relationship Handling
+### Core Components
 
-| Relationship | Strategy                                |
-| ------------ | --------------------------------------- |
-| **1:1**      | Simple INNER/LEFT JOIN                  |
-| **m:1**      | INNER/LEFT JOIN to parent table         |
-| **1:m**      | Subquery with JSON aggregation          |
-| **m:m**      | Through junction table with aggregation |
+| Component             | Purpose                                                        |
+| --------------------- | -------------------------------------------------------------- |
+| `GQLtoSQLMapper`      | Transforms GraphQL field selections into SQL with proper joins |
+| `GQLQueryManager`     | Orchestrates query building and execution                      |
+| `FilterProcessor`     | Translates GQL filter inputs to SQL WHERE clauses              |
+| `RelationshipHandler` | Generates JOIN SQL for ORM-declared relations                  |
+| `SQLBuilder`          | Assembles final SQL strings and JSON aggregations              |
+| `AliasManager`        | Manages incremental SQL aliases to prevent naming conflicts    |
 
-### Performance Optimizations
+### Query Flow
 
-- **Alias Management** – Incremental aliases (`a1`, `a2`, ...) prevent naming conflicts
-- **Set-Based Field Selection** – Eliminates duplicate fields automatically
-- **OR to UNION ALL** – Converts OR conditions to UNION queries for optimal execution plans
-- **JSONB Aggregation** – Efficient nested data structure building
+1. **Parse** – `graphql-parse-resolve-info` extracts the requested fields from `GraphQLResolveInfo`
+2. **Map** – `GQLtoSQLMapper.recursiveMap()` walks the field tree, building `select`, `join`, `where` sets
+3. **Aggregate** – JSON aggregation (`row_to_json`, `json_agg`) combines nested results
+4. **Bind** – Named parameters are bound via knex raw
+5. **Execute** – Single SQL sent to the database
 
 ---
 
 ## Known Limitations
 
-These dragons still slumber in the cave—future challenges for brave developers:
-
-- ⚠️ Class-level `NOT` conditions not yet supported
-- ⚠️ Order by reference table columns (e.g., "order authors by their latest book publication")
-- ⚠️ Access Control Lists (ACL) pending async refactoring
-
----
-
-## Examples
-
-See the `/examples` directory for complete, runnable examples:
-
-- **Middle-earth Schema** – Full Author/Book relationship example inspired by Tolkien's lore
-- **Database Integration** – Real PostgreSQL examples with TypeTypeORM metadata
+- ⚠️ Class-level `_not` conditions not yet supported
+- ⚠️ Order by columns on related/joined tables not supported
+- ⚠️ ACL pending async refactoring
 
 ---
 
-## Contributing
+## Development
 
-Contributions are welcome! Whether you're fixing bugs, improving performance, or adding features, please submit a pull request.
+```bash
+bun install        # Install dependencies
+bun run build      # Compile TypeScript → dist/
+bun run test       # Run all tests
+bun run test:watch # Watch mode
+```
 
 ---
 
 ## License
 
-MIT NON-AI License
-
-Forged by [Dav3](https://github.com/dave-palt) with the wisdom of Middle-earth.
-
----
-
-## Support & Community
-
-- 📖 Full documentation coming soon
-- 🐛 Found a bug? [Open an issue](https://github.com/dave-palt/gql-of-power/issues)
-- 💬 Have a question? Reach out to the fellowship
+MIT NON-AI License — Forged by [Dav3](https://github.com/dave-palt) with the wisdom of Middle-earth.
 
 ---