@rytass/wms-module-graphql 0.1.3 → 0.1.5

package/docs/integration-guide.md

@@ -68,6 +68,24 @@ The reference consumer ([`wms-standalone`](#13-reference-implementation-wms-stan
 
 The frontend package (`wms-module-react`) is **ESM-only** (`"type": "module"`). Bundlers that target Next.js / Vite / webpack 5 handle this transparently; classic CJS-only Node tools do not.
 
+### 2.1 pnpm build-script approval
+
+If you are on **pnpm 9 or newer**, the first `pnpm install` will refuse to run native build scripts for several transitive dependencies and surface `ERR_PNPM_IGNORED_BUILDS`. This is pnpm's supply-chain protection, not a WMS issue, but it is the very first error a fresh integrator hits.
+
+Resolve it once by approving the packages WMS transitively needs to build:
+
+```bash
+pnpm approve-builds
+# Or, in pnpm-workspace.yaml:
+# allowBuilds:
+#   '@apollo/protobufjs': true
+#   '@nestjs/core': true
+#   '@parcel/watcher': true
+#   sharp: true
+```
+
+After approval, `pnpm install` completes cleanly. The exact list pnpm asks you to approve depends on your other dependencies; the four above are the ones triggered by WMS's NestJS + Apollo + native-image stack.
+
 ---
 
 ## 3. Quick start (60 seconds)
@@ -78,7 +96,7 @@ mkdir my-wms && cd my-wms
 pnpm init
 pnpm add @rytass/wms-module-core @rytass/wms-module-graphql @rytass/wms-module-react
 pnpm add @nestjs/common @nestjs/core @nestjs/graphql @nestjs/typeorm \
-        @nestjs/apollo @nestjs/config @nestjs/platform-express @apollo/server@^4 \
+        @nestjs/apollo@~13.1.0 @nestjs/config @nestjs/platform-express @apollo/server@^4 \
         typeorm pg reflect-metadata graphql rxjs \
         class-transformer class-validator \
         @as-integrations/express5
@@ -191,8 +209,52 @@ What you get from this single `forRootAsync`:
 - DataLoader N+1 prevention across every resolveField
 - Default seed rows (DEFAULT location, DEFAULT loaderType, DEFAULT loader) on first boot
 
+**`forRootAsync` TypeScript signature**:
+
+```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).
+
 See [API Reference - wms-module-graphql](./api-reference.md) for the full `forRootAsync` signature.
 
+### 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`:
+
+```ts
+// apps/api/src/modules/posts/posts.module.ts
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { Post } from './post.entity';
+import { PostResolver } from './post.resolver';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([Post])],
+  providers: [PostResolver],
+})
+export class PostsModule {}
+
+// apps/api/src/app/app.module.ts
+@Module({
+  imports: [
+    /* ... TypeOrm, Config, WmsModuleGraphqlModule ... */
+    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.
+
 ### 4.3 `.env`
 
 Keep DB credentials in `.env` (and add it to `.gitignore`).
@@ -284,7 +346,7 @@ Tested combinations as of 0.1.2:
 |----------------------------------|-------------------------|--------------------------------------------------------------------|
 | NestJS (`@nestjs/*`)             | 11.x                    | 10.x untested; some Express-5-related APIs differ                  |
 | `@nestjs/graphql`                | 13.x                    | Required for `@nestjs/apollo@13`                                   |
-| `@nestjs/apollo`                 | 13.x                    | Pairs with Apollo Server 4 + Express 5                             |
+| `@nestjs/apollo`                 | 13.0.x – 13.1.x         | 13.2+ requires @apollo/server@^5 which breaks lib's v4 plugin usage |
 | `@apollo/server`                 | 4.x                     | v5 is breaking; not supported                                      |
 | `@as-integrations/express5`      | 1.x                     | Required runtime peer                                              |
 | TypeORM                          | 0.3.x                   | 0.2.x not supported (different DataSource API)                     |
@@ -1072,11 +1134,17 @@ logic. Any field set on `req` by a NestJS guard or Passport strategy (e.g. `req.
 therefore accessible from resolvers as `ctx.req.user`.
 
 > **Why returning `context` from `gqlOptions.useFactory` does not work**: the lib's
-> `forRootAsync` calls `gqlOptions.useFactory(…)` to collect your Apollo options, then
-> unconditionally replaces the `context` key with its own factory that injects DataLoaders
-> (`{ loaders, ...contextArg }`). Any `context` you return from `useFactory` is silently
-> dropped. The resulting GraphQL context is always `{ req, res, loaders }` — there is no
-> `user` key.
+> 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.
 
 To access the authenticated user in a **custom** resolver, populate `req.user` in a guard
 or middleware and read it from `ctx.req.user`:
@@ -1267,6 +1335,13 @@ function WmsLayout({ children }: { children: ReactNode }): ReactNode {
 }
 ```
 
+> **Critical constraint**: WMS page components use the `NextPath` enum for all internal
+> navigation (`router.push(NextPath.MATERIALSMANAGEMENT)` etc.). Enum values are hardcoded
+> root-level paths (`/materials-management`, `/inventory-list`, etc.). **WMS pages cannot be
+> mounted under a custom path prefix like `/wms/*`** — internal links will break even though
+> the pages initially render. If your existing project requires path prefixing, you must mount
+> WMS at the root of a separate domain or subdomain.
+
 The lib's page components do not require the WMS navigation shell to be present — they only
 require the three providers (§13.7) and an Apollo client (§13.6). You can completely replace
 the navigation chrome with your own.
@@ -1495,6 +1570,40 @@ creating a new monorepo. Key points:
 `@rytass/wms-module-*` package names, ensure they point to `node_modules` (the installed
 package), not local source, to avoid confusion.
 
+### 13.13.1 pnpm peer-dep multi-instantiation hazard
+
+When a pnpm workspace contains apps that resolve `@nestjs/core` (or other peers
+of `@rytass/wms-module-core`) to different major versions, pnpm creates one
+**instance** of `@rytass/wms-module-core` per unique peer resolution. Both
+instances register their TypeORM entity decorators against the same global
+`getMetadataArgsStorage()`, producing:
+
+```
+TypeError: Cannot read properties of undefined (reading 'ownColumns')
+    at EntityMetadataBuilder.ts:548
+```
+
+**Required workaround**: every workspace app that imports `@rytass/wms-module-core`
+(directly or transitively via `@rytass/wms-module-graphql`) must resolve to the
+same `@nestjs/*` major version. Options:
+
+1. Upgrade the entire workspace to a single NestJS major (preferred)
+2. Force pnpm to deduplicate the WMS module instance:
+
+   ```yaml
+   # pnpm-workspace.yaml
+   overrides:
+     '@rytass/wms-module-core': '0.1.4'
+   ```
+
+3. Apply `public-hoist-pattern[]` for `@rytass/wms-module-*` in `.npmrc`
+
+This is a structural limitation of the pnpm peer-resolution model combined
+with TypeORM's global metadata storage; the WMS lib cannot deduplicate
+itself without rewriting TypeORM's entity registry. Yarn 4 and npm 10 do not
+hit this because their hoisting strategies differ — pnpm with strict mode is
+the only affected case.
+
 ---
 
 ### 13.14 GraphQL Type Name Conflicts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/wms-module-graphql",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Rytass WMS Module — GraphQL schema, resolvers and DTOs for warehouse management",
   "keywords": [
     "rytass",
@@ -46,10 +46,10 @@
   },
   "peerDependencies": {
     "@as-integrations/express5": "^1.0.0",
-    "@nestjs/apollo": "^13.0.0",
+    "@nestjs/apollo": ">=13.0.0 <13.2.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/graphql": "^13.0.0",
-    "@rytass/wms-module-core": "^0.1.3",
+    "@rytass/wms-module-core": "^0.1.5",
     "graphql": "^16.0.0",
     "reflect-metadata": "^0.1.13 || ^0.2.0",
     "rxjs": "^7.8.0"