@rytass/wms-module-graphql 0.2.0 → 0.3.0

package/README.md

@@ -17,56 +17,74 @@ yarn add @nestjs/common @nestjs/graphql @nestjs/apollo @apollo/server graphql da
 ```ts
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
+import { GraphQLModule } from '@nestjs/graphql';
 import { ApolloDriver } from '@nestjs/apollo';
 import { resolve } from 'node:path';
-import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import {
+  WmsModuleGraphqlModule,
+  LoaderService,
+  createWmsLoaders,
+} from '@rytass/wms-module-graphql';
 
 @Module({
   imports: [
     TypeOrmModule.forRoot({ /* ...db config... */ }),
-    WmsModuleGraphqlModule.forRootAsync(
-      {
-        useFactory: async () => ({}),
-        defaultLoaderSerialId: 'DEFAULT',
-        defaultLoaderTypeKey: 'DEFAULT',
-        defaultLocationKey: 'DEFAULT',
-      },
-      {
-        driver: ApolloDriver,
-        useFactory: async () => ({
-          autoSchemaFile: resolve(process.cwd(), 'schema.gql'),
-          playground: false,
-          introspection: true,
-          cors: true,
-          autoTransformHttpErrors: true,
+    WmsModuleGraphqlModule.forRootAsync({
+      useFactory: async () => ({}),
+      defaultLoaderSerialId: 'DEFAULT',
+      defaultLoaderTypeKey: 'DEFAULT',
+      defaultLocationKey: 'DEFAULT',
+    }),
+    GraphQLModule.forRootAsync({
+      driver: ApolloDriver,
+      inject: [LoaderService],
+      useFactory: (loaderService: LoaderService) => ({
+        autoSchemaFile: resolve(process.cwd(), 'schema.gql'),
+        playground: false,
+        introspection: true,
+        cors: true,
+        autoTransformHttpErrors: true,
+        context: ({ req }) => ({
+          ...createWmsLoaders(loaderService),
+          // your own context fields stay yours — no silent overwrite
+          user: req.user,
         }),
-      },
-    ),
+      }),
+    }),
   ],
 })
 export class AppModule {}
 ```
 
-The first argument is `WmsModuleCoreModuleAsyncOptions` (merged from `@rytass/wms-module-core` — same shape as `WMSBaseModuleAsyncOptions` plus the three `default*` keys). The second is a standard `@nestjs/graphql` `GqlModuleAsyncOptions` — extend the `useFactory` to override the Apollo config (cors, plugins, custom scalars, etc.).
+`WmsModuleGraphqlModule.forRootAsync` takes a single argument (`WmsModuleCoreModuleAsyncOptions`, re-exported from `@rytass/wms-module-core` — same shape as `WMSBaseModuleAsyncOptions` plus the three `default*` keys). It registers the resolvers/queries/mutations as composable NestJS providers and exposes `LoaderService` as a `@Global()` DI token; it does **not** start Apollo Server.
+
+You register a **single** `GraphQLModule.forRootAsync(...)` of your own, mix your resolvers with the WMS resolvers in the same schema, and own the Apollo / context configuration end-to-end.
 
 `WmsModuleGraphqlModule` internally wires `WmsModuleCoreModule.forRootAsync` so you do not need to import the core module separately when using this package.
 
 ## DataLoader context
 
-The module ships a `HelperModule` that provides DataLoader instances for batched entity lookups, automatically injected into the GraphQL context so resolvers can avoid N+1 queries:
+The module ships a `HelperModule` (auto-registered) that provides a singleton `LoaderService`. To avoid N+1 queries, the WMS resolvers expect a per-request DataLoader trio at `context.loaders`:
 
 ```ts
-context: async (contextArg) => ({
-  loaders: {
-    batchSingle: ...,
-    batchMany: ...,
-    batchManyWithPagination: ...,
-  },
-  ...contextArg,
-})
+type WmsLoaders = {
+  batchSingle: DataLoader<...>;
+  batchMany: DataLoader<...>;
+  batchManyWithPagination: DataLoader<...>;
+};
+```
+
+Inject `LoaderService` into your `GraphQLModule.forRootAsync` factory and call `createWmsLoaders(loaderService)` **per request** inside `context`. The helper returns a `{ loaders: WmsLoaders }` fragment that is safe to spread:
+
+```ts
+context: ({ req }) => ({
+  ...createWmsLoaders(loaderService),   // adds `loaders: { batchSingle, ... }`
+  user: req.user,                       // your fields preserved
+  csrfToken: req.headers['x-csrf'],
+}),
 ```
 
-Custom context factories from `gqlOptions.useFactory` are merged with the loaders — your existing context fields survive the wrap.
+Per-request is non-negotiable — DataLoader caches results inside the instance, so reusing one across requests leaks data between callers. `createWmsLoaders` is a thin factory you call from inside `context`, never at module scope.
 
 ## Schema artefacts
 

package/docs/README.md

@@ -7,7 +7,7 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | Document                                       | Description                                                                                       |
 |------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | [Integration Guide](./integration-guide.md)    | Step-by-step instructions for wiring the three packages into a new consumer project (NestJS + Next.js + PostgreSQL). Includes ready-to-paste `_app.tsx`, `app.module.ts`, `next.config.ts`, the 19 Pages Router shell pattern, AuthGuard stub, seed script template, deployment notes, and known issues. |
-| [API Reference](./api-reference.md)            | Complete export catalog for all three packages — every NestJS module, TypeORM entity, GraphQL resolver, DTO, React component, hook, and utility, organized by role with source paths and usage examples. Mirrors the actual `src/index.ts` barrel exports of v0.1.2. |
+| [API Reference](./api-reference.md)            | Complete export catalog for all three packages — every NestJS module, TypeORM entity, GraphQL resolver, DTO, React component, hook, and utility, organized by role with source paths and usage examples. Mirrors the actual `src/index.ts` barrel exports of `@rytass/wms-module-graphql@0.3.0` and `@rytass/wms-module-{core,react}@0.1.6`. |
 
 ## Quick links
 
@@ -28,6 +28,6 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 
 ## Versioning
 
-These documents track the **latest published `0.1.x` release**. Anything in `main` that has not yet been released is marked clearly inline; otherwise assume the documented signature matches the current npm-published library.
+These documents track the **latest published versions** — `@rytass/wms-module-graphql@0.3.0` and `@rytass/wms-module-{core,react}@0.1.6` as of this writing. Anything in `main` that has not yet been released is marked clearly inline; otherwise assume the documented signature matches the current npm-published library.
 
-When you upgrade the lib, check each package's `CHANGELOG.md` for breaking changes that may affect the snippets here.
+`@rytass/wms-module-graphql@0.3.0` introduced **breaking changes** to `WmsModuleGraphqlModule.forRootAsync` (single argument; consumer now registers their own `GraphQLModule.forRootAsync`). The integration guide and API reference reflect the post-0.3.0 surface — see each package's `CHANGELOG.md` for the full breaking change list when upgrading.

package/docs/api-reference.md

@@ -6,10 +6,12 @@ Complete export catalog for the three publishable libraries:
 - `@rytass/wms-module-graphql` — GraphQL resolvers, DTOs, DataLoader helpers
 - `@rytass/wms-module-react` — React components, hooks, Apollo client, GraphQL operations
 
-Current versions: **0.1.2** (all three packages).
+Current versions: **0.3.0** (`@rytass/wms-module-graphql`), **0.1.6** (`@rytass/wms-module-core`, `@rytass/wms-module-react`).
 
 This document mirrors the actual `src/index.ts` barrel exports and is generated by static analysis of the lib sources. For runtime behavior changes between versions, see each package's `CHANGELOG.md`.
 
+> **0.3.0 surface change**: `WmsModuleGraphqlModule.forRootAsync(...)` now takes a single argument and exposes resolvers as composable providers — see [`WmsModuleGraphqlModule`](#wmsmodulegraphqlmodule) and the new public exports [`LoaderService`](#loaderservice-injectable), [`createWmsLoaders`](#createwmsloaders) below.
+
 > Companion document — **[Integration Guide](./integration-guide.md)** — step-by-step instructions for wiring the three packages into a new consumer project.
 
 ---
@@ -293,10 +295,10 @@ enum ShipInventoryOrderStatus { PENDING, PARTIAL_SHIPPED, SHIPPED, REMOVED }
 ## NestJS Modules
 
 ### `WmsModuleGraphqlModule`
-- 用途: WMS GraphQL NestJS 動態模組，整合 Apollo GraphQL、DataLoader 與所有 Resolver/Query/Mutation。是消費端 `apps/api` 唯一需要 `imports: [...]` 的 WMS 模組。
+- 用途: WMS GraphQL NestJS 動態模組，**僅註冊 providers**（Resolver / Query / Mutation 與 `LoaderService`），不啟動 Apollo Server。消費端在自己的 `AppModule` 內額外 `imports: [GraphQLModule.forRootAsync(...)]` 統一起 server。
 - 來源: `lib/graphql.module.ts`
 
-**`forRootAsync(options, gqlOptions): DynamicModule`**
+**`forRootAsync(options): DynamicModule`** (since 0.3.0)
 ```ts
 static forRootAsync(
   options: WmsModuleCoreModuleAsyncOptions,
@@ -305,16 +307,87 @@ static forRootAsync(
   //     defaultLoaderSerialId: string  — 庫存作業預設載具序號
   //     defaultLoaderTypeKey: string   — 預設載具類型 key
   //     defaultLocationKey: string     — 預設儲存位置 key
-  gqlOptions: GqlModuleAsyncOptions,
-  // 標準 @nestjs/graphql GqlModuleAsyncOptions，
-  // 例如 autoSchemaFile、context factory 等
-  // 注意：此方法會自動在 context 中注入 loaders（DataLoader instances）:
-  //   loaders.batchSingle — DataLoader<LoaderOptions<T>, T>
-  //   loaders.batchMany   — DataLoader<LoaderOptions<T>, T[]>
-  //   loaders.batchManyWithPagination — DataLoader<LoaderOptionsWithPagination<T>, { items: T[]; total: number }>
 ): DynamicModule
 ```
 
+> **Breaking from 0.2.x**: 0.2.0 took a second `gqlOptions` argument and started Apollo Server internally; 0.3.0 dropped it. Consumers now own `GraphQLModule.forRootAsync(...)` and the GraphQL context factory. Use `createWmsLoaders(loaderService)` inside `context` to provide the WMS DataLoader trio (see below).
+
+### `LoaderService` (`@Injectable()`, since 0.3.0 publicly exported)
+- 用途: 提供 DataLoader 工廠方法（`batchEntity()`、`batchEntities()`、`batchEntitiesWithPagination()`）。每次呼叫產生新的 DataLoader instance — 須在 GraphQL context factory **per request** 呼叫，**勿** 在 module scope 重用。
+- 來源: `lib/helpers/loader.service.ts`
+- 透過 `WmsModuleGraphqlModule.forRootAsync(...)` 自動經 `HelperModule` (`@Global()`) 全域提供，可在任何模組的 factory 內 `inject: [LoaderService]`。
+
+### `createWmsLoaders`
+- 用途: 便利 helper — 呼叫 `LoaderService` 三個 factory 並回傳 spreadable context fragment `{ loaders: { batchSingle, batchMany, batchManyWithPagination } }`。
+- 來源: `lib/helpers/create-wms-loaders.ts`
+
+```ts
+import {
+  createWmsLoaders,
+  LoaderService,
+  type WmsLoaders,
+} from '@rytass/wms-module-graphql';
+
+GraphQLModule.forRootAsync({
+  driver: ApolloDriver,
+  inject: [LoaderService],
+  useFactory: (loaderService: LoaderService) => ({
+    autoSchemaFile: 'schema.gql',
+    context: ({ req }) => ({
+      ...createWmsLoaders(loaderService),  // ← adds `loaders` key
+      user: req.user,                      // your own fields preserved
+    }),
+  }),
+});
+```
+
+```ts
+// Type signature
+export type WmsLoaders = {
+  batchSingle: DataLoader<LoaderOptions<unknown>, unknown>;
+  batchMany: DataLoader<LoaderOptions<unknown>, unknown[]>;
+  batchManyWithPagination: DataLoader<
+    LoaderOptionsWithPagination<unknown>,
+    { items: unknown[]; total: number }
+  >;
+};
+
+export function createWmsLoaders(
+  loaderService: LoaderService,
+): { loaders: WmsLoaders };
+```
+
+Resolvers consume the loaders via the `LoaderType<T>` shape (see [`LoaderType`](#loadertype)) injected through `@Context()`. The helper's return shape (`{ loaders: ... }`) is intentional so it can be spread into a custom context without colliding with consumer fields.
+
+### `LoaderType`
+- 用途: Resolver 端解構 GraphQL context 的型別契約，描述 `context.loaders` 的形狀。
+- 來源: `lib/helpers/dataloader.type.ts`
+
+```ts
+export interface LoaderType<T> {
+  loaders: {
+    batchSingle: DataLoader<LoaderOptions<T>, T>;
+    batchMany: DataLoader<LoaderOptions<T>, T[]>;
+    batchManyWithPagination: DataLoader<
+      LoaderOptionsWithPagination<T>,
+      { items: T[]; total: number }
+    >;
+  };
+}
+
+// 使用範例（resolver 內）
+@ResolveField(() => MaterialEntityClass)
+material(
+  @Parent() stock: StockDto,
+  @Context() { loaders }: LoaderType<MaterialEntityClass>,
+) {
+  return loaders.batchSingle.load({
+    __entity: MaterialEntity,
+    __from: { id: stock.materialId },
+  });
+}
+```
+
 ---
 
 ## Resolvers（`@Resolver()` decorator class）

package/docs/integration-guide.md

@@ -40,8 +40,8 @@ WMS is packaged as three layered npm libraries:
                v
 +-------------------------------+
 | wms-module-graphql            |   Resolvers, DTOs, DataLoader helpers
-| (one forRootAsync wires up    |   ---------------------------------------
-|  the entire GraphQL surface)  |   Wires the schema, depends on core for
+| (composable providers + your  |   ---------------------------------------
+|  own GraphQLModule.forRoot)   |   Exposes resolvers; depends on core for
 +--------------+----------------+   entities + services.
                v
 +-------------------------------+
@@ -138,13 +138,18 @@ bootstrap();
 
 ### 4.2 `apps/api/src/app/app.module.ts`
 
-The entire backend domain is wired in a single `forRootAsync` call on `WmsModuleGraphqlModule`. The module cascades into `WmsModuleCoreModule` automatically — the consumer **does not** import `wms-module-core` directly.
+Two registrations: `WmsModuleGraphqlModule.forRootAsync(...)` wires the WMS resolvers, entities, services and `LoaderService`; your own `GraphQLModule.forRootAsync(...)` starts Apollo Server and owns the context factory. The two participate in **one** schema — NestJS's schema builder discovers every `@Resolver()` provider across all imported modules.
 
 ```ts
 import { Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { TypeOrmModule, TypeOrmModuleOptions } from '@nestjs/typeorm';
-import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { GraphQLModule } from '@nestjs/graphql';
+import {
+  WmsModuleGraphqlModule,
+  LoaderService,
+  createWmsLoaders,
+} from '@rytass/wms-module-graphql';
 import { ApolloDriver } from '@nestjs/apollo';
 import {
   ApolloServerPluginLandingPageLocalDefault,
@@ -173,40 +178,46 @@ import { resolve } from 'path';
       }),
     }),
 
-    // WMS GraphQL - one call wires the entire domain
-    WmsModuleGraphqlModule.forRootAsync(
-      {
-        useFactory: async () => ({}),
-        // Module-init seed values; the keys you pass here are created
-        // on first boot for `location`, `loaderType`, and `loader`.
-        defaultLoaderSerialId: 'DEFAULT',
-        defaultLoaderTypeKey: 'DEFAULT',
-        defaultLocationKey: 'DEFAULT',
-      },
-      {
-        driver: ApolloDriver,
-        useFactory: async () => ({
-          playground: false,
-          introspection: true,
-          cors: true,
-          csrfPrevention: false,
-          plugins: [ApolloServerPluginLandingPageLocalDefault()],
-          autoTransformHttpErrors: true,
-          autoSchemaFile: resolve(process.cwd(), 'schema.gql'),
+    // WMS resolvers + LoaderService — no Apollo Server is started here
+    WmsModuleGraphqlModule.forRootAsync({
+      useFactory: async () => ({}),
+      // Module-init seed values; the keys you pass here are created
+      // on first boot for `location`, `loaderType`, and `loader`.
+      defaultLoaderSerialId: 'DEFAULT',
+      defaultLoaderTypeKey: 'DEFAULT',
+      defaultLocationKey: 'DEFAULT',
+    }),
+
+    // YOUR Apollo / Schema / Context registration
+    GraphQLModule.forRootAsync({
+      driver: ApolloDriver,
+      inject: [LoaderService],
+      useFactory: (loaderService: LoaderService) => ({
+        playground: false,
+        introspection: true,
+        cors: true,
+        csrfPrevention: false,
+        plugins: [ApolloServerPluginLandingPageLocalDefault()],
+        autoTransformHttpErrors: true,
+        autoSchemaFile: resolve(process.cwd(), 'schema.gql'),
+        context: ({ req }) => ({
+          ...createWmsLoaders(loaderService),  // per-request DataLoaders
+          // your own context fields — fully preserved
+          user: req.user,
         }),
-      },
-    ),
+      }),
+    }),
   ],
 })
 export class AppModule {}
 ```
 
-What you get from this single `forRootAsync`:
+What this registration wires:
 
 - 50 TypeORM entities (material, batch, loader, location, every order kind, change logs, signatures, etc.)
 - ~100 GraphQL types
 - ~65 queries and mutations
-- DataLoader N+1 prevention across every resolveField
+- DataLoader N+1 prevention across every `resolveField` (via the `loaders` key in context)
 - Default seed rows (DEFAULT location, DEFAULT loaderType, DEFAULT loader) on first boot
 
 **`forRootAsync` TypeScript signature**:
@@ -214,21 +225,16 @@ What you get from this single `forRootAsync`:
 ```ts
 WmsModuleGraphqlModule.forRootAsync(
   options: WmsModuleCoreModuleAsyncOptions,
-  gqlOptions: GqlModuleAsyncOptions<ApolloDriverConfig>,
 ): DynamicModule
 ```
 
-> Note the **two positional arguments**. A common mistake is to pass a single options object
-> (matching NestJS's typical convention) which produces a misleading
-> `TypeError: Cannot read properties of undefined (reading 'imports')` from inside the lib.
-> The first arg configures the WMS core module (seed defaults, async factory, etc.); the
-> second arg configures the underlying NestJS GraphQL module (driver, autoSchemaFile, plugins).
+A single argument — the WMS core module options (seed defaults, async factory). All GraphQL-server concerns (driver, schema file, context factory, plugins) live in your own `GraphQLModule.forRootAsync(...)` next to it.
 
-See [API Reference - wms-module-graphql](./api-reference.md) for the full `forRootAsync` signature.
+See [API Reference - wms-module-graphql](./api-reference.md) for the full export catalog including `LoaderService`, `createWmsLoaders`, `LoaderType<T>` and `WmsLoaders`.
 
 ### Adding your own resolvers alongside WMS
 
-`WmsModuleGraphqlModule` calls `GraphQLModule.forRootAsync(...)` internally — that registration is workspace-global, so you cannot register a second `GraphQLModule` (see §13.1). What you **can** do is put your own resolvers in **sibling NestJS modules** imported in `AppModule`:
+Your `GraphQLModule.forRootAsync(...)` registration **is** the single workspace-wide GraphQL module — no constraint from `WmsModuleGraphqlModule` (the lib intentionally does **not** call `GraphQLModule.forRoot` internally). Put your resolvers in normal NestJS modules and import them next to `WmsModuleGraphqlModule`:
 
 ```ts
 // apps/api/src/modules/posts/posts.module.ts
@@ -246,14 +252,14 @@ export class PostsModule {}
 // apps/api/src/app/app.module.ts
 @Module({
   imports: [
-    /* ... TypeOrm, Config, WmsModuleGraphqlModule ... */
+    /* ... TypeOrm, Config, WmsModuleGraphqlModule, GraphQLModule ... */
     PostsModule,   // your sibling module
   ],
 })
 export class AppModule {}
 ```
 
-NestJS's GraphQL module discovers every `@Resolver()` class from every imported module via DI and merges them into the **same** schema. So your `Post`/`User` resolvers coexist in one schema with the WMS resolvers automatically — no extra wiring needed. The §13.1 "one GraphQLModule" constraint only forbids a second `GraphQLModule.forRoot(...)` registration, not additional resolvers.
+NestJS's GraphQL module discovers every `@Resolver()` class from every imported module via DI and merges them into the **same** schema. So your `Post`/`User` resolvers coexist in one schema with the WMS resolvers automatically — no extra wiring needed.
 
 ### 4.3 `.env`
 
@@ -960,37 +966,59 @@ This section covers the real-world scenarios where the WMS modules are added to
 that already has its own NestJS backend, GraphQL setup, or Next.js frontend. The greenfield
 setup in sections 4-7 is the baseline; read this section for the delta.
 
-> **Scope**: 0.1.x. Many limitations listed here are known gaps — roadmap notes are included
-> where improvements are planned.
+> **Scope**: 0.3.0+. Earlier 0.1.x / 0.2.0 limitations around `GraphQLModule` co-existence have
+> been removed by the user-driven composition refactor — see §13.1.
 
 ### 13.1 Coexisting with an existing `GraphQLModule`
 
-**Status**: Not supported in 0.1.x without forking the library.
-
-`WmsModuleGraphqlModule.forRootAsync(...)` internally calls `GraphQLModule.forRootAsync(...)`.
-NestJS does not allow two `GraphQLModule` registrations in the same application — the second
-registration throws `Error: Cannot register 2 GraphQL modules`. If your host app already
-imports `GraphQLModule`, you cannot simply add `WmsModuleGraphqlModule` to the same
-`imports: [...]` array.
+**Status**: Fully supported since 0.3.0.
 
-**Recommended workarounds** (in order of practicality):
+`WmsModuleGraphqlModule.forRootAsync(...)` only registers providers (resolvers, `LoaderService`,
+core module) — it does **not** call `GraphQLModule.forRoot` internally. The host application
+registers a **single** `GraphQLModule.forRootAsync(...)` of its own. NestJS's schema builder
+walks the DI container at boot, collects every `@Resolver()` class from every imported module,
+and merges them into one schema.
 
-1. **Separate NestJS process** — run the WMS API as its own NestJS server on a different port
-   (e.g. 7103) and have the host API proxy or federate as needed. This is the architecture
-   used by `wms-standalone` and is the safest path.
+This means a host app with an existing GraphQL server just adds `WmsModuleGraphqlModule` next to
+its existing `GraphQLModule.forRootAsync(...)`. To preserve N+1 prevention for the WMS resolvers,
+the host must inject `LoaderService` into its own context factory and call `createWmsLoaders(...)`
+per request:
 
-2. **NestJS sub-app (monorepo)** — if you use the Nx or NestJS CLI monorepo pattern, you can
-   host the WMS app as a separate application inside the same repo that shares code with your
-   existing app but runs as a distinct process.
+```ts
+import {
+  WmsModuleGraphqlModule,
+  LoaderService,
+  createWmsLoaders,
+} from '@rytass/wms-module-graphql';
 
-3. **Fork and merge** — advanced consumers can fork `libs/graphql` and extract the resolver
-   registrations, removing the internal `GraphQLModule.forRootAsync(...)` call. The host app
-   then registers a single `GraphQLModule` that includes the WMS resolver classes. This requires
-   maintaining a fork and is not recommended unless you intend to take full ownership of the lib.
+@Module({
+  imports: [
+    // ... your existing modules ...
+    WmsModuleGraphqlModule.forRootAsync({
+      useFactory: async () => ({}),
+      defaultLoaderSerialId: 'DEFAULT',
+      defaultLoaderTypeKey: 'DEFAULT',
+      defaultLocationKey: 'DEFAULT',
+    }),
+    GraphQLModule.forRootAsync({
+      driver: ApolloDriver,
+      inject: [LoaderService, /* your existing deps */],
+      useFactory: (loaderService: LoaderService /* , ... */) => ({
+        autoSchemaFile: 'schema.gql',
+        context: ({ req }) => ({
+          ...createWmsLoaders(loaderService),   // WMS DataLoader trio
+          user: req.user,                       // your existing context fields
+          // ... any other context shape you already had ...
+        }),
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
 
-**Tied to §13.1**: the `/graphql` endpoint name conflict (see §13.14 for GraphQL type name conflicts) is also
-fundamentally blocked by this same single-GraphQLModule constraint when running both APIs in
-the same process.
+**Type name conflicts**: still a separate concern — see §13.14. The shared-schema model means
+your `type Material`, `type Location`, etc. must not collide with the WMS counterparts.
 
 ---
 
@@ -1128,26 +1156,34 @@ export class AppModule {}
 
 This applies your guard to every resolver, including WMS resolvers.
 
-**Option B**: Read auth identity via `context.req.user` in custom resolvers. The Express `req`
-object is spread directly into the GraphQL context by the lib's internal DataLoader injection
-logic. Any field set on `req` by a NestJS guard or Passport strategy (e.g. `req.user`) is
-therefore accessible from resolvers as `ctx.req.user`.
+**Option B**: Surface the authenticated user through your **own** GraphQL context factory. Since 0.3.0 you own the entire `GraphQLModule.forRootAsync(...)` registration, including `context`. Both `context.user` (returned directly from your factory) and `context.req.user` (set by a guard / Passport on Express) work — pick whichever your resolvers prefer:
 
-> **Why returning `context` from `gqlOptions.useFactory` does not work**: the lib's
-> internal context factory replaces any `context` key you return from `gqlOptions.useFactory`,
-> but it spreads the raw `contextArg` (the `{ req, res }` provided by Apollo Server). So:
->
-> | Approach                                           | Works? |
-> |----------------------------------------------------|--------|
-> | Return `context: () => ({ user })` from useFactory | ❌ overridden |
-> | Populate `req.user` via NestJS guard / Passport    | ✅ access via `context.req.user` |
->
-> Always populate identity onto `req` (via a guard) and read it as `context.req.user` in
-> your resolvers. The resulting GraphQL context is `{ req, res, loaders }` — `req.user` IS
-> accessible as long as a guard or middleware has set it on the request object.
+```ts
+GraphQLModule.forRootAsync({
+  driver: ApolloDriver,
+  inject: [LoaderService],
+  useFactory: (loaderService: LoaderService) => ({
+    autoSchemaFile: 'schema.gql',
+    context: ({ req }) => ({
+      ...createWmsLoaders(loaderService),  // WMS DataLoader trio
+      user: req.user,                      // directly accessible as ctx.user
+      // ...any other fields you want on context
+    }),
+  }),
+})
+```
+
+| Approach                                                | Works? |
+|---------------------------------------------------------|--------|
+| Return `context: () => ({ user, ...createWmsLoaders(svc) })` | ✅ user fully controls context |
+| Populate `req.user` via NestJS guard / Passport             | ✅ access via `context.req.user`  |
+
+> **0.1.x behavior gone**: earlier releases of this lib silently replaced any `context` factory
+> you supplied because `WmsModuleGraphqlModule` registered Apollo Server itself. Since 0.3.0,
+> the lib only exposes providers and your `GraphQLModule.forRootAsync(...)` is the single
+> registration — there is no internal override anymore.
 
-To access the authenticated user in a **custom** resolver, populate `req.user` in a guard
-or middleware and read it from `ctx.req.user`:
+To access the authenticated user in a **custom** resolver, either read it directly from `ctx.user` (if you put it there in your factory) or from `ctx.req.user` (if a guard set it on the request):
 
 ```ts
 // auth.guard.ts — populate req.user before the resolver runs
@@ -1631,8 +1667,7 @@ The viable options are the same as those described in §13.1:
 3. **Wait for a future major release** — a type prefix configuration option is a candidate
    for a future major version that introduces namespace support.
 
-This is the same fundamental single-`GraphQLModule` constraint discussed in §13.1. Running
-both APIs in the same process is not supported in 0.1.x.
+Unlike the §13.1 `GraphQLModule` co-existence story (fixed in 0.3.0), the type-name collision is a **shared-schema** problem: every `@Resolver()` provider in the DI container, WMS or host-app, contributes to the same `GraphQLSchema` instance. Renaming the host app's types away from WMS-occupied names is the only fix without splitting processes.
 
 
 ## 14. Reference implementation (`wms-standalone`)
@@ -1647,7 +1682,7 @@ wms-standalone/
     api/
       src/
         main.ts                       17 LOC   NestJS bootstrap
-        app/app.module.ts             52 LOC   WmsModuleGraphqlModule.forRootAsync
+        app/app.module.ts             60 LOC   WmsModuleGraphqlModule + GraphQLModule.forRootAsync
       .env                             6 LOC   PG credentials
       package.json
     client/

package/index.cjs.js

@@ -204,9 +204,11 @@ common.createParamDecorator((data, context) => {
 
 function createWmsLoaders(loaderService) {
     return {
-        batchSingle: loaderService.batchEntity(),
-        batchMany: loaderService.batchEntities(),
-        batchManyWithPagination: loaderService.batchEntitiesWithPagination(),
+        loaders: {
+            batchSingle: loaderService.batchEntity(),
+            batchMany: loaderService.batchEntities(),
+            batchManyWithPagination: loaderService.batchEntitiesWithPagination(),
+        },
     };
 }
 

package/lib/helpers/create-wms-loaders.d.ts

@@ -1,4 +1,6 @@
 import type { LoaderType } from './dataloader.type';
 import type { LoaderService } from './loader.service';
 export type WmsLoaders = LoaderType<unknown>['loaders'];
-export declare function createWmsLoaders(loaderService: LoaderService): WmsLoaders;
+export declare function createWmsLoaders(loaderService: LoaderService): {
+    loaders: WmsLoaders;
+};

package/lib/helpers/create-wms-loaders.js

@@ -1,8 +1,10 @@
 function createWmsLoaders(loaderService) {
     return {
-        batchSingle: loaderService.batchEntity(),
-        batchMany: loaderService.batchEntities(),
-        batchManyWithPagination: loaderService.batchEntitiesWithPagination(),
+        loaders: {
+            batchSingle: loaderService.batchEntity(),
+            batchMany: loaderService.batchEntities(),
+            batchManyWithPagination: loaderService.batchEntitiesWithPagination(),
+        },
     };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/wms-module-graphql",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Rytass WMS Module — GraphQL schema, resolvers and DTOs for warehouse management",
   "keywords": [
     "rytass",