@appxdigital/appx-core 0.1.128-beta.4 → 0.1.128-beta.5

package/CHANGELOG.md

@@ -29,7 +29,7 @@ Read-only GraphQL, reworked into a **namespaced, opt-in-per-module** API.
 - **Nested selection is to-one only.** Generated GraphQL model types expose scalars, **to-one** relations, and `_count`; **to-many relations are not nested-selectable** (nested lists have no pagination, so they could return unbounded rows). Fetch a list at the top level with pagination — `track { find(where: { albumId … }, take, skip) }`. Filtering by a to-many relation in `where` (`some`/`every`/`none`) and `_count { … }` still work.
 - **Self-documenting operations.** `find` / `get` / `count` and their `where` arg carry GraphQL descriptions (visible in the Apollo Sandbox); model-field descriptions come from Prisma `///` doc comments as before. See [docs/graphql.md](./docs/graphql.md) for the full `where`/`orderBy`/pagination reference.
 - **Malformed filter values return `400`, not `500`.** A `where`/`orderBy` value Prisma can't parse (e.g. `createdAt: { gt: 2024 }` — a number where a date is expected) now surfaces a clean `400`, instead of an internal error that leaked the raw Prisma invocation.
-- **Output shaping via native field resolvers.** Transform a field on the way out (sign a stored key into a URL, mask, format) or add a computed field with a `@Resolver(() => Model)` + `@ResolveField`, registered in the module. A field resolver reads its source columns from `@Parent()`; ABAC field omission still runs at query time, so a transform never sees a `@Role`-restricted column. New **`@FieldRequires('col')`** (one column, several, or an array) declares which columns a computed field reads so the generated `find`/`get` fetches exactly those; undeclared computed fields fall back to fetching all scalar columns, and relations always stay selection-driven. See [docs/graphql.md](./docs/graphql.md) → *Shaping read output*.
+- **Output shaping via native field resolvers.** Transform a field on the way out (sign a stored key into a URL, mask, format) or add a computed field with a `@Resolver(() => Model)` + `@ResolveField`, registered in the module. A field resolver reads its source columns from `@Parent()`; ABAC field omission still runs at query time, so a transform never sees a `@Role`-restricted column. New **`@FieldRequires('col')`** (one column, several, or an array) declares which columns a field reads so the generated `find`/`get` fetches exactly those — for a computed field, an in-place override, **and a field on a nested relation** (the source columns are resolved from a bootstrap registry, so declarations apply at every level). Undeclared field resolvers fall back to fetching the model's scalar columns; relations always stay selection-driven. See [docs/graphql.md](./docs/graphql.md) → *Shaping read output*.
 - **GraphQL introspection on in development.** The Apollo Sandbox (`GET /graphql`) needs introspection, which Apollo Server v4 disables under `NODE_ENV=production` (`INTROSPECTION_DISABLED`). It is now enabled in development and disabled in production by default (defense-in-depth — introspection exposes schema shape, not data, which ABAC still governs). Opt in for a production deployment with `APPX_GRAPHQL_INTROSPECTION=true`.
 
 ### Fixed

package/dist/common/decorators/field-requires.decorator.d.ts

@@ -1,22 +1,22 @@
 /**
- * The GraphQL schema-field `extensions` key under which {@link FieldRequires}
- * records the source columns. The generated read resolver reads it back from the
- * schema when deciding which columns to fetch
- * (see `generic.resolver.ts` → `selectReadColumns`).
+ * Reflect metadata key under which {@link FieldRequires} records a field
+ * resolver's source columns. Read at bootstrap by the GraphQL field-requires
+ * scanner (see `field-requires.registry.ts`) to build the model→field→columns
+ * registry the read resolver consults.
  */
-export declare const FIELD_REQUIRES_EXTENSION = "requires";
+export declare const FIELD_REQUIRES_METADATA = "appx:field_requires";
 /**
  * Declare the model columns a custom GraphQL `@ResolveField` reads from its
  * `@Parent()`, so the generated `find` / `get` fetches those columns even when
- * the client didn't select them.
+ * the client didn't select them — at the top level and on nested relations.
  *
- * Use it on a computed field whose value derives from a column — e.g. a signed
- * `coverUrl` built from a stored `coverKey`. Without it, only the columns the
- * client selected are fetched and `@Parent().coverKey` would be `undefined`.
+ * Use it on a computed field or an in-place transform whose value derives from a
+ * column, e.g. a signed `coverUrl` built from a stored `coverKey`. Without it,
+ * only the columns the client selected are fetched and `@Parent().coverKey` would
+ * be `undefined`.
  *
  * - Declared → only the listed columns are fetched for the field.
  * - Not declared → all of the model's scalar columns are fetched.
- * - Not needed for an in-place transform that reuses an existing field's name.
  *
  * ABAC applies: a column the caller's role may not read is omitted at query time,
  * so the resolver sees it as absent — a transform can never surface a
@@ -46,5 +46,5 @@ export declare const FIELD_REQUIRES_EXTENSION = "requires";
  * }
  * ```
  */
-export declare const FieldRequires: (...columns: (string | string[])[]) => MethodDecorator & ClassDecorator & PropertyDecorator;
+export declare const FieldRequires: (...columns: (string | string[])[]) => import("@nestjs/common").CustomDecorator<string>;
 //# sourceMappingURL=field-requires.decorator.d.ts.map

package/dist/common/decorators/field-requires.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-requires.decorator.d.ts","sourceRoot":"","sources":["../../../src/common/decorators/field-requires.decorator.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,aAAa,eAAgB,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,yDACH,CAAC"}
+{"version":3,"file":"field-requires.decorator.d.ts","sourceRoot":"","sources":["../../../src/common/decorators/field-requires.decorator.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,aAAa,eAAgB,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,qDACP,CAAC"}

package/dist/common/decorators/field-requires.decorator.js

@@ -1,26 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FieldRequires = exports.FIELD_REQUIRES_EXTENSION = void 0;
-const graphql_1 = require("@nestjs/graphql");
+exports.FieldRequires = exports.FIELD_REQUIRES_METADATA = void 0;
+const common_1 = require("@nestjs/common");
 /**
- * The GraphQL schema-field `extensions` key under which {@link FieldRequires}
- * records the source columns. The generated read resolver reads it back from the
- * schema when deciding which columns to fetch
- * (see `generic.resolver.ts` → `selectReadColumns`).
+ * Reflect metadata key under which {@link FieldRequires} records a field
+ * resolver's source columns. Read at bootstrap by the GraphQL field-requires
+ * scanner (see `field-requires.registry.ts`) to build the model→field→columns
+ * registry the read resolver consults.
  */
-exports.FIELD_REQUIRES_EXTENSION = 'requires';
+exports.FIELD_REQUIRES_METADATA = 'appx:field_requires';
 /**
  * Declare the model columns a custom GraphQL `@ResolveField` reads from its
  * `@Parent()`, so the generated `find` / `get` fetches those columns even when
- * the client didn't select them.
+ * the client didn't select them — at the top level and on nested relations.
  *
- * Use it on a computed field whose value derives from a column — e.g. a signed
- * `coverUrl` built from a stored `coverKey`. Without it, only the columns the
- * client selected are fetched and `@Parent().coverKey` would be `undefined`.
+ * Use it on a computed field or an in-place transform whose value derives from a
+ * column, e.g. a signed `coverUrl` built from a stored `coverKey`. Without it,
+ * only the columns the client selected are fetched and `@Parent().coverKey` would
+ * be `undefined`.
  *
  * - Declared → only the listed columns are fetched for the field.
  * - Not declared → all of the model's scalar columns are fetched.
- * - Not needed for an in-place transform that reuses an existing field's name.
  *
  * ABAC applies: a column the caller's role may not read is omitted at query time,
  * so the resolver sees it as absent — a transform can never surface a
@@ -50,5 +50,5 @@ exports.FIELD_REQUIRES_EXTENSION = 'requires';
  * }
  * ```
  */
-const FieldRequires = (...columns) => (0, graphql_1.Extensions)({ [exports.FIELD_REQUIRES_EXTENSION]: columns.flat() });
+const FieldRequires = (...columns) => (0, common_1.SetMetadata)(exports.FIELD_REQUIRES_METADATA, columns.flat());
 exports.FieldRequires = FieldRequires;

package/dist/graphql/field-requires.registry.d.ts

@@ -0,0 +1,27 @@
+import { OnModuleInit } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+/**
+ * Look up a field resolver on a model. Returns `undefined` if the field is not a
+ * custom `@ResolveField` (i.e. a plain column), otherwise `{ requires }` where
+ * `requires` is the declared columns or `null` if none were declared.
+ */
+export declare function getFieldRequires(model: string, field: string): {
+    requires: string[] | null;
+} | undefined;
+/**
+ * Scans every resolver provider once at startup and records each `@ResolveField`
+ * as `Model.field` → its `@FieldRequires` columns. Runs after all providers are
+ * instantiated, so field resolvers registered in any feature module are included.
+ *
+ * This scan (not a per-request read) is required because the code that builds the
+ * Prisma query — the generated `find`/`get` — must know the source columns of
+ * field resolvers on OTHER classes and nested relation models, not just the
+ * executing handler.
+ */
+export declare class FieldRequiresScanner implements OnModuleInit {
+    private readonly discovery;
+    private readonly scanner;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner);
+    onModuleInit(): void;
+}
+//# sourceMappingURL=field-requires.registry.d.ts.map

package/dist/graphql/field-requires.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-requires.registry.d.ts","sourceRoot":"","sources":["../../src/graphql/field-requires.registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,YAAY,EAAC,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAC,gBAAgB,EAAE,eAAe,EAAC,MAAM,cAAc,CAAC;AAqB/D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAC,GAAG,SAAS,CAMtG;AAED;;;;;;;;;GASG;AACH,qBACa,oBAAqB,YAAW,YAAY;IAEjD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,eAAe;IAG7C,YAAY,IAAI,IAAI;CA+BvB"}

package/dist/graphql/field-requires.registry.js

@@ -0,0 +1,96 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldRequiresScanner = exports.getFieldRequires = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const field_requires_decorator_1 = require("../common/decorators/field-requires.decorator");
+// NestJS GraphQL reflect keys (set by @Resolver / @ResolveField). Reading them is
+// how we recover, for each field resolver, the model it belongs to and the field
+// it resolves — including in-place overrides, whose declared columns never reach
+// the built schema field.
+const RESOLVER_NAME_METADATA = 'graphql:resolver_name';
+const RESOLVER_PROPERTY_METADATA = 'graphql:resolve_property';
+/**
+ * `Model.field` → the columns the field resolver reads, or `null` when the field
+ * is a custom resolver that declared nothing (an undeclared resolver means "fetch
+ * this model's scalars, we can't know what it reads"). Absence of a key means the
+ * field is not a custom resolver at all (a plain column).
+ *
+ * Populated once at bootstrap by {@link FieldRequiresScanner}; read by the
+ * generated read resolver when building the Prisma `select`.
+ */
+const registry = new Map();
+/**
+ * Look up a field resolver on a model. Returns `undefined` if the field is not a
+ * custom `@ResolveField` (i.e. a plain column), otherwise `{ requires }` where
+ * `requires` is the declared columns or `null` if none were declared.
+ */
+function getFieldRequires(model, field) {
+    const key = `${model}.${field}`;
+    if (!registry.has(key)) {
+        return undefined;
+    }
+    return { requires: registry.get(key) ?? null };
+}
+exports.getFieldRequires = getFieldRequires;
+/**
+ * Scans every resolver provider once at startup and records each `@ResolveField`
+ * as `Model.field` → its `@FieldRequires` columns. Runs after all providers are
+ * instantiated, so field resolvers registered in any feature module are included.
+ *
+ * This scan (not a per-request read) is required because the code that builds the
+ * Prisma query — the generated `find`/`get` — must know the source columns of
+ * field resolvers on OTHER classes and nested relation models, not just the
+ * executing handler.
+ */
+let FieldRequiresScanner = exports.FieldRequiresScanner = class FieldRequiresScanner {
+    constructor(discovery, scanner) {
+        this.discovery = discovery;
+        this.scanner = scanner;
+    }
+    onModuleInit() {
+        registry.clear();
+        for (const wrapper of this.discovery.getProviders()) {
+            const instance = wrapper.instance;
+            if (!instance || typeof instance !== 'object') {
+                continue;
+            }
+            // The model a resolver is bound to: @Resolver(() => Model) records the
+            // model name on the class under RESOLVER_NAME_METADATA.
+            const model = Reflect.getMetadata(RESOLVER_NAME_METADATA, instance.constructor);
+            if (!model || typeof model !== 'string') {
+                continue; // not a model-bound resolver (root resolvers, other providers)
+            }
+            const prototype = Object.getPrototypeOf(instance);
+            if (!prototype) {
+                continue;
+            }
+            for (const methodName of this.scanner.getAllMethodNames(prototype)) {
+                const handler = prototype[methodName];
+                if (typeof handler !== 'function') {
+                    continue;
+                }
+                if (Reflect.getMetadata(RESOLVER_PROPERTY_METADATA, handler) !== true) {
+                    continue; // not a @ResolveField
+                }
+                const field = Reflect.getMetadata(RESOLVER_NAME_METADATA, handler) || methodName;
+                const requires = Reflect.getMetadata(field_requires_decorator_1.FIELD_REQUIRES_METADATA, handler);
+                registry.set(`${model}.${field}`, Array.isArray(requires) ? requires : null);
+            }
+        }
+    }
+};
+exports.FieldRequiresScanner = FieldRequiresScanner = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_1.MetadataScanner])
+], FieldRequiresScanner);

package/dist/graphql/generic.resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generic.resolver.d.ts","sourceRoot":"","sources":["../../src/graphql/generic.resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAC;AA4GrC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,SAAS,GAAG,GAAG;IAC/C,iFAAiF;IACjF,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACvB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,oDAAoD;IACpD,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,8DAA8D;IAC9D,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAuE/F"}
+{"version":3,"file":"generic.resolver.d.ts","sourceRoot":"","sources":["../../src/graphql/generic.resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAC;AAoIrC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,SAAS,GAAG,GAAG;IAC/C,iFAAiF;IACjF,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACvB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,oDAAoD;IACpD,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,8DAA8D;IAC9D,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAuE/F"}

package/dist/graphql/generic.resolver.js

@@ -18,7 +18,7 @@ const common_1 = require("@nestjs/common");
 const plugins_1 = require("@paljs/plugins");
 const graphql_2 = require("graphql");
 const prisma_service_1 = require("../prisma/prisma.service");
-const field_requires_decorator_1 = require("../common/decorators/field-requires.decorator");
+const field_requires_registry_1 = require("./field-requires.registry");
 /**
  * Run a read and translate a Prisma **validation** error into a `400`. A
  * malformed `where`/`orderBy` value (e.g. `createdAt: { gt: 2024 }` — a number
@@ -39,83 +39,99 @@ async function readOrBadRequest(op) {
     }
 }
 /**
- * Turn a `PrismaSelect`-derived selection into the columns actually fetched,
- * resolving the source columns that custom `@ResolveField`s need.
+ * Build the Prisma `select` for a read so that every custom `@ResolveField` — at
+ * the top level and on nested relations — receives its source columns in
+ * `@Parent()`.
  *
- * `PrismaSelect` narrows the Prisma query to exactly the fields the GraphQL
- * request asked for. That breaks the standard NestJS code-first contract where a
- * `@ResolveField` on the model type receives the full entity as `@Parent()`: a
- * custom field (`coverUrl` derived from a `coverKey` column, or a signed-URL
- * transform of an existing field) can't read a source column the client didn't
- * also select. We restore that contract with a **hybrid** strategy that avoids
- * over-fetching:
+ * `PrismaSelect` narrows each query to the columns the GraphQL request selected,
+ * which breaks the standard NestJS contract that a `@ResolveField` receives the
+ * full entity: a transform or computed field can't read a column the client
+ * didn't also select, and on a nested relation not even its own key is
+ * guaranteed. Using the `@FieldRequires` registry (populated at bootstrap), each
+ * selected field that is a custom resolver contributes its declared source
+ * columns; a resolver that declared nothing falls back to the model's scalar
+ * columns. Plain columns are fetched as-is, so a query with no custom fields is
+ * exactly what was asked for. Relations stay selection-driven — only selected
+ * relations are fetched, and each is recursed into so its own resolvers get their
+ * columns too. ABAC field omission runs afterward in the proxy and strips
+ * `@Role`-restricted columns at select-time, so a caller — and a transform — only
+ * ever sees readable columns.
  *
- *   - A custom field can declare its source columns natively, via the standard
- *     NestJS field `extensions`:
- *         `@ResolveField(() => String, { extensions: { requires: ['coverKey'] } })`
- *     When declared, ONLY those columns are added — no over-fetch.
- *   - A custom field that declares nothing falls back to fetching all of the
- *     model's scalar columns (safe default: the resolver can read anything from
- *     `@Parent()`), at the cost of reading columns the query didn't select.
- *   - A query that selects no custom fields fetches exactly what was asked for.
- *
- * Relations stay selection-driven throughout (no unbounded relation fetching).
- * ABAC field omission runs afterward in the proxy and strips `@Role`-restricted
- * columns at select-time, so a caller still only ever receives — and a transform
- * only ever sees — the columns their role may read.
- *
- * Custom field names (no backing column) are dropped from the Prisma `select`:
- * `PrismaSelect` puts every requested GraphQL field there, and passing a name
- * Prisma doesn't recognise throws a validation error. They resolve from the
- * parent afterward, so they must not reach the query.
+ * Custom field names with no backing column are dropped: `PrismaSelect` puts every
+ * requested GraphQL field into the `select`, and passing a name Prisma doesn't
+ * recognise throws a validation error. They resolve from the parent afterward.
  */
 function selectReadColumns(select, info, prisma, modelName) {
-    const scalars = new Set(prisma.getScalarFields(modelName));
-    const requested = select?.select && typeof select.select === 'object' ? select.select : {};
-    // The GraphQL type of the returned rows, to read each field's
-    // `extensions.requires` (find → [Model], get → Model; getNamedType unwraps).
     const named = (0, graphql_2.getNamedType)(info.returnType);
-    const gqlFields = named instanceof graphql_2.GraphQLObjectType ? named.getFields() : {};
+    const type = named instanceof graphql_2.GraphQLObjectType ? named : null;
+    const requested = select?.select && typeof select.select === 'object' ? select.select : {};
+    const resolved = resolveLevelColumns(requested, type, prisma, modelName);
+    return { ...(select && typeof select === 'object' ? select : {}), select: resolved };
+}
+/**
+ * Per-level worker for {@link selectReadColumns}: resolve the columns fetched for
+ * one model, recursing into each selected relation against its own model type.
+ */
+function resolveLevelColumns(requested, type, prisma, modelName) {
+    const scalars = prisma.getScalarFields(modelName);
+    const scalarSet = new Set(scalars);
+    const fields = type ? type.getFields() : undefined;
     const out = {};
-    const requiredColumns = new Set();
-    let needAllScalars = false;
+    const needed = new Set();
+    let fetchAllScalars = false;
     for (const [key, value] of Object.entries(requested)) {
         if (value && typeof value === 'object') {
-            out[key] = value; // a relation (or `_count`) selection — keep as-is
+            // A relation or `_count`. Recurse into a known relation model so its
+            // own field resolvers get their source columns (a relation's GraphQL
+            // type name is its Prisma model name); keep `_count`/opaque verbatim.
+            const relField = fields?.[key];
+            if (relField && value.select && typeof value.select === 'object') {
+                const relType = (0, graphql_2.getNamedType)(relField.type);
+                if (relType instanceof graphql_2.GraphQLObjectType && prisma.getScalarFields(relType.name).length) {
+                    out[key] = {
+                        ...value,
+                        select: resolveLevelColumns(value.select, relType, prisma, relType.name),
+                    };
+                    continue;
+                }
+            }
+            out[key] = value;
+            continue;
         }
-        else if (scalars.has(key)) {
-            out[key] = value; // a real scalar column
+        if (scalarSet.has(key)) {
+            out[key] = value; // a real scalar column — keep even if also overridden by a resolver
         }
-        else {
-            // A custom field resolver (no backing column). Prefer its declared
-            // dependencies (@FieldRequires); otherwise fall back to all scalars.
-            const requires = gqlFields[key]?.extensions?.[field_requires_decorator_1.FIELD_REQUIRES_EXTENSION];
-            if (Array.isArray(requires)) {
-                for (const col of requires) {
-                    if (scalars.has(col))
-                        requiredColumns.add(col);
+        // Is this field a custom @ResolveField on this model (new field OR in-place
+        // override)? The registry knows, and knows its declared source columns.
+        const entry = (0, field_requires_registry_1.getFieldRequires)(modelName, key);
+        if (entry) {
+            if (entry.requires) {
+                for (const col of entry.requires) {
+                    if (scalarSet.has(col))
+                        needed.add(col);
                 }
             }
             else {
-                needAllScalars = true;
+                fetchAllScalars = true; // a resolver that declared nothing — fetch all scalars
             }
         }
+        // else: a plain column (already added above) or an unknown non-column
+        // field name — dropped; it resolves from @Parent() afterward.
     }
-    if (needAllScalars) {
+    if (fetchAllScalars) {
         for (const field of scalars)
             out[field] = true;
     }
     else {
-        for (const col of requiredColumns)
+        for (const col of needed)
             out[col] = true;
     }
-    // Guard against an empty select (e.g. only a custom field with `requires: []`)
-    // — an empty Prisma `select` is invalid; fall back to all scalars.
+    // An empty select is invalid Prisma; fall back to the model's scalar columns.
     if (Object.keys(out).length === 0) {
         for (const field of scalars)
             out[field] = true;
     }
-    return { ...(select && typeof select === 'object' ? select : {}), select: out };
+    return out;
 }
 /**
  * Build a **namespaced, read-only** GraphQL resolver for one model.

package/dist/graphql/graphql.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphql.module.d.ts","sourceRoot":"","sources":["../../src/graphql/graphql.module.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,qBACa,oBAAoB;IAK7B,QAAQ,IAAI,MAAM;CAGrB;AAED,qBAwBa,aAAa;CAAG"}
+{"version":3,"file":"graphql.module.d.ts","sourceRoot":"","sources":["../../src/graphql/graphql.module.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,qBACa,oBAAoB;IAK7B,QAAQ,IAAI,MAAM;CAGrB;AAED,qBA0Ba,aAAa;CAAG"}

package/dist/graphql/graphql.module.js

@@ -11,8 +11,10 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GraphqlModule = exports.AppxCoreRootResolver = void 0;
 const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
 const graphql_1 = require("@nestjs/graphql");
 const apollo_1 = require("@nestjs/apollo");
+const field_requires_registry_1 = require("./field-requires.registry");
 /**
  * Always-present root query. GraphQL requires a non-empty `Query` type, but a
  * project may register `GraphqlModule` before any model has opted in (models
@@ -41,6 +43,8 @@ let GraphqlModule = exports.GraphqlModule = class GraphqlModule {
 exports.GraphqlModule = GraphqlModule = __decorate([
     (0, common_1.Module)({
         imports: [
+            // DiscoveryService/MetadataScanner power the @FieldRequires bootstrap scan.
+            core_1.DiscoveryModule,
             graphql_1.GraphQLModule.forRoot({
                 driver: apollo_1.ApolloDriver,
                 context: ({ req, res }) => ({ req, res }),
@@ -60,6 +64,6 @@ exports.GraphqlModule = GraphqlModule = __decorate([
                     process.env.APPX_GRAPHQL_INTROSPECTION === 'true',
             }),
         ],
-        providers: [AppxCoreRootResolver],
+        providers: [AppxCoreRootResolver, field_requires_registry_1.FieldRequiresScanner],
     })
 ], GraphqlModule);

package/docs/graphql.md

@@ -214,9 +214,9 @@ coverUrl(@Parent() p: Project) { … }
 fullName(@Parent() p: Project) { … }
 ```
 
-- **Declared** → only those columns are fetched for the field.
+- **Declared** → only those columns are fetched for the field. Works the same for a computed field, an in-place override, and a field on a nested relation.
 - **Not declared** → all of the model's scalar columns are fetched, so the field can read any of them from its parent.
-- **In-place transform** (a resolver reusing an existing field's name) → needs no declaration; that column is fetched whenever the client selects the field.
+- **In-place transform reading only its own column** → needs no declaration; that column is fetched whenever the client selects the field. Declare `@FieldRequires` for any *other* columns it reads.
 
 Read from `@Parent()`, not the raw Prisma client — re-querying bypasses ABAC. For key-to-URL transforms, reuse the existing field's name so the raw stored value never leaves the server.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@appxdigital/appx-core",
-    "version": "0.1.128-beta.4",
+    "version": "0.1.128-beta.5",
     "description": "Appx Core is a library that provides a set of tools to help you build your application faster.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",