@ttoss/graphql-api 0.9.8 → 0.9.10

package/README.md

@@ -90,6 +90,214 @@ import './modules/User/composer';
 export { schemaComposer };
 ```
 
+## Recommended Module Structure
+
+As your GraphQL API grows, you'll encounter three recurring problems: circular imports between modules, relational fields hidden in resolver files (making TC files incomplete), and monolith resolver files with hundreds of lines. The structure below solves all three.
+
+### Directory Structure
+
+Each module has **TC files** at the root and a `resolvers/` folder with one file per GraphQL field:
+
+```
+src/modules/
+├── Meta/
+│   ├── index.ts                              # side-effect imports of all resolver files
+│   ├── MetaAdAccountTC.ts                    # pure shape — scalars + string type refs
+│   ├── MetaCampaignTC.ts
+│   └── resolvers/
+│       ├── Query.metaAdAccount.ts            # root query
+│       ├── Mutation.addMetaAdAccounts.ts     # root mutation
+│       ├── MetaAdAccount.optimizations.ts    # cross-module relational field
+│       └── MetaCampaign.optimization.ts
+├── Optimizations/
+│   ├── index.ts
+│   ├── OptimizationTC.ts
+│   └── resolvers/
+│       ├── Query.optimization.ts
+│       ├── Mutation.createOptimization.ts
+│       ├── Optimization.metaCampaign.ts      # cross-module relational field
+│       └── Optimization.algorithm.ts
+└── User/
+    ├── index.ts
+    ├── UserTC.ts
+    └── resolvers/
+        └── Query.me.ts
+```
+
+### Rule 1: TC Files — All Fields Declared with String Type References
+
+TC files declare **all** fields (scalars and relational) but use **string type names** for cross-module types instead of importing other TCs. `schemaComposer` resolves string type names lazily when building the schema, eliminating circular imports and keeping the full type shape visible in one file.
+
+```typescript
+// MetaAdAccountTC.ts — no imports from other modules
+import { schemaComposer } from '@ttoss/graphql-api';
+
+export const MetaAdAccountTC = schemaComposer.createObjectTC({
+  name: 'MetaAdAccount',
+  fields: {
+    id: 'ID!',
+    name: 'String!',
+    // String type ref — resolved lazily by schemaComposer at build time
+    optimizations: '[Optimization!]!',
+    tracking: 'MetaAdAccountTracking',
+  },
+});
+```
+
+### Rule 2: Resolver Files — One Field Per File with `extendField`
+
+Each resolver file attaches the `resolve` function to a single field using `extendField`. Root queries and mutations use `schemaComposer.Query.addFields()` / `schemaComposer.Mutation.addFields()`.
+
+```typescript
+// resolvers/MetaAdAccount.optimizations.ts
+import { schemaComposer } from '@ttoss/graphql-api';
+import { MetaAdAccountTC } from '../MetaAdAccountTC';
+
+MetaAdAccountTC.extendField('optimizations', {
+  args: { isActive: 'Boolean' },
+  resolve: async (source, args) => {
+    return findManyOptimizations({
+      metaAdAccountId: source.id,
+      isActive: args.isActive,
+    });
+  },
+});
+```
+
+```typescript
+// resolvers/Query.metaAdAccount.ts
+import { schemaComposer } from '@ttoss/graphql-api';
+
+schemaComposer.Query.addFields({
+  metaAdAccount: {
+    type: 'MetaAdAccount',
+    args: { id: 'ID!' },
+    resolve: async (_source, args) => {
+      return findMetaAdAccount({ id: args.id });
+    },
+  },
+});
+```
+
+### Rule 3: Dot Notation File Naming
+
+Resolver files use `Parent.field.ts` naming that maps 1:1 to the GraphQL schema path:
+
+| File name                        | GraphQL path                             |
+| -------------------------------- | ---------------------------------------- |
+| `Query.metaAdAccount.ts`         | `metaAdAccount` field on `Query`         |
+| `Mutation.createOptimization.ts` | `createOptimization` field on `Mutation` |
+| `MetaAdAccount.optimizations.ts` | `optimizations` field on `MetaAdAccount` |
+
+### Rule 4: Index Files — Side-Effect Imports
+
+Each module's `index.ts` imports all TC and resolver files as side effects, guaranteeing registration order:
+
+```typescript
+// Meta/index.ts
+import './MetaAdAccountTC';
+import './MetaCampaignTC';
+import './resolvers/Query.metaAdAccount';
+import './resolvers/Mutation.addMetaAdAccounts';
+import './resolvers/MetaAdAccount.optimizations';
+import './resolvers/MetaCampaign.optimization';
+```
+
+The top-level `schemaComposer.ts` then imports each module index:
+
+```typescript
+// src/schemaComposer.ts
+import { schemaComposer } from '@ttoss/graphql-api';
+import './modules/Meta';
+import './modules/Optimizations';
+import './modules/User';
+
+export { schemaComposer };
+```
+
+### Why This Works
+
+| Concern                         | Solution                                                                                                                         |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **No circular imports**         | TC files never import other module TCs. Only resolver files (leaf nodes) do cross-module imports, and nothing imports from them. |
+| **Full shape visibility**       | The TC file shows every field on the type — scalars and relational — in one place.                                               |
+| **Import order independence**   | String type refs are resolved lazily at `buildSchema()` time.                                                                    |
+| **Easy to locate**              | `Parent.field.ts` maps 1:1 to the GraphQL schema path.                                                                           |
+| **One responsibility per file** | Each resolver file handles exactly one field, keeping files small and focused.                                                   |
+
+## Recommended Test Structure
+
+Test files mirror the source layout using the same dot notation — one test file per resolver.
+
+### Test Directory Structure
+
+```
+tests/unit/
+├── Meta/
+│   ├── Query.metaAdAccount.test.ts
+│   ├── Query.metaAdAccounts.test.ts
+│   ├── Mutation.addMetaAdAccounts.test.ts
+│   ├── MetaAdAccount.optimizations.test.ts
+│   └── MetaCampaign.optimization.test.ts
+├── Optimizations/
+│   ├── Query.optimization.test.ts
+│   ├── Mutation.createOptimization.test.ts
+│   └── Optimization.metaCampaign.test.ts
+└── User/
+    └── Query.me.test.ts
+```
+
+### Test Structure Rules
+
+1. **Same dot notation** as resolver files — `Parent.field.test.ts`
+2. **Module subfolder** — `tests/unit/{Module}/` mirrors `src/modules/{Module}/resolvers/`
+3. **No `resolvers/` subfolder in tests** — unnecessary nesting since test files are already leaf nodes
+4. **One test file per resolver** — keeps tests focused and easy to find
+
+### Testing Style
+
+Prefer schema-level testing using `graphql()` against `schemaComposer.buildSchema()` — this validates the full wiring (TC shape → resolver → response):
+
+```typescript
+import { graphql } from 'graphql';
+import { schemaComposer } from 'src/schemaComposer';
+
+test('should return optimizations for a MetaAdAccount', async () => {
+  const response = await graphql({
+    schema: schemaComposer.buildSchema(),
+    source: /* GraphQL */ `
+      query ($id: ID!) {
+        node(id: $id) {
+          ... on MetaAdAccount {
+            optimizations {
+              id
+              isActive
+            }
+          }
+        }
+      }
+    `,
+    contextValue: mockContext,
+    variableValues: { id: globalId },
+  });
+
+  expect(response.errors).toBeUndefined();
+  expect(response.data).toEqual({
+    /* expected */
+  });
+});
+```
+
+### Source-to-Test Mapping
+
+| Source file                                                          | Test file                                                      |
+| -------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `src/modules/Meta/resolvers/Query.metaAdAccount.ts`                  | `tests/unit/Meta/Query.metaAdAccount.test.ts`                  |
+| `src/modules/Meta/resolvers/MetaAdAccount.optimizations.ts`          | `tests/unit/Meta/MetaAdAccount.optimizations.test.ts`          |
+| `src/modules/Optimizations/resolvers/Mutation.createOptimization.ts` | `tests/unit/Optimizations/Mutation.createOptimization.test.ts` |
+
+This 1:1 mapping makes it trivial to find the test for any resolver and vice versa.
+
 ## Relay Server Specification
 
 As ttoss uses Relay as the main GraphQL client, this library implements the [Relay Server Specification](https://relay.dev/docs/guides/graphql-server-specification/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/graphql-api",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "A library for building GraphQL APIs using ttoss ecosystem.",
   "license": "MIT",
   "author": "ttoss",
@@ -35,7 +35,7 @@
     "graphql-middleware": "^6.1.35",
     "graphql-shield": "^7.6.5",
     "npmlog": "^7.0.1",
-    "@ttoss/ids": "^0.4.8"
+    "@ttoss/ids": "^0.4.9"
   },
   "peerDependencies": {
     "graphql": "^16.6.0"
@@ -44,7 +44,7 @@
     "graphql": "^16.11.0",
     "jest": "^30.3.0",
     "tsup": "^8.5.1",
-    "@ttoss/config": "^1.37.8"
+    "@ttoss/config": "^1.37.9"
   },
   "keywords": [
     "api",