@nxgt/graphql-validation 0.6.0 → 0.8.0

package/dist/limits/max-list-cost.d.ts

@@ -1,24 +1,6 @@
 import { type ValidationRule } from 'graphql';
-/** Options of {@link maxListCost}. */
-export interface MaxListCostOptions {
-    /** The most an operation may cost (at least 0). */
-    budget: number;
-    /** The size of a list field whose size cannot be read (an integer of at least 0). */
-    defaultFirst: number;
-    /**
-     * The argument names that size a list. Each one given, or defaulted in the
-     * SDL, says a size (an Int, a canonical-integer string or an integral Float)
-     * and the largest wins. Default `['first', 'last', 'limit']`.
-     */
-    sizeArguments?: readonly string[];
-    /**
-     * Do not cost `__schema` and `__type` (default `false`). Only where
-     * introspection is disabled or the client is trusted, e.g. GraphiQL in
-     * development: the standard introspection query is costly (on the order of
-     * 200,000 on a one-field schema).
-     */
-    ignoreIntrospection?: boolean;
-}
+import { type MaxListCostOptions } from './max-list-cost-options.js';
+export type { MaxListCostOptions };
 /**
  * A graphql-js validation rule refusing an operation whose cost is more than
  * `budget`, to stop a client from exploiting list cycles (`Folder.items`,
@@ -36,15 +18,30 @@ export interface MaxListCostOptions {
  * `first`, `last`, `limit`) say. A literal Int, a String holding a canonical
  * integer (`"1000"`) or an integral Float (`1e3`) of at least 0 says that
  * number. Anything else (a negative literal, a variable, since validation has
- * no variable values) says the argument's SDL default when it has a usable one,
- * `defaultFirst` otherwise; an argument not given says its SDL default, or
- * nothing. When nothing is said the size is `defaultFirst`. On an interface the
- * largest default over its possible types is used. Hence no subtree ever costs
- * less than nothing: a negative `first` on one field cannot cancel the cost of
- * its sibling. A field whose type (once unwrapped from non-null) is a list is
- * one list, nested `[[X]]` included.
+ * no variable values) says the largest of the argument's SDL default when it
+ * has a usable one (`defaultFirst` otherwise), its declared bound
+ * (`@constraint(max)` or `exclusiveMax`) and, when some definition declares no
+ * bound, `variableSize`; an argument not given says its SDL default, or
+ * nothing. When nothing is said the size is `defaultFirst`. On an interface
+ * the largest default and bound over its possible types is used. Hence no
+ * subtree ever costs less than nothing: a negative `first` on one field cannot
+ * cancel the cost of its sibling. A field whose type (once unwrapped from
+ * non-null) is a list is one list, nested `[[X]]` included.
  *
- * Named fragments are followed, each costed once. Inline fragments and
+ * A Relay connection puts the size on a field returning an object, with the
+ * list below it (`items(first: 100) { edges { node { id } } }`). A field that
+ * is not a list and states a size (by the same reading) hands it to the lists
+ * selected directly on its return type, through inline fragments and fragment
+ * spreads on that same selection set, and only to those declaring none of the
+ * size arguments (`edges`, `nodes`): such a list takes it instead of
+ * `defaultFirst`. A list declaring a size argument (`recent(first: Int)`)
+ * reads its own, never the pending size. Crossing any other field (an object
+ * field, `pageInfo`, a wrapper) ends it. A connection stating nothing hands
+ * down nothing: its lists are sized `defaultFirst`.
+ *
+ * Named fragments are followed, each costed once per pending size (past eight
+ * distinct sizes under one fragment a size is rounded up to a power of two, so
+ * the work stays linear in the document and a cost only over-counts). Inline fragments and
  * fragments on an abstract type are summed branch by branch, so the cost of a
  * query on an interface or a union is overestimated, never underestimated.
  *

package/dist/limits/max-list-cost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"max-list-cost.d.ts","sourceRoot":"","sources":["../../src/limits/max-list-cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAcN,KAAK,cAAc,EACnB,MAAM,SAAS,CAAC;AASjB,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IAClC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAuGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CA+CvE"}
+{"version":3,"file":"max-list-cost.d.ts","sourceRoot":"","sources":["../../src/limits/max-list-cost.ts"],"names":[],"mappings":"AAAA,OAAO,EAUN,KAAK,cAAc,EACnB,MAAM,SAAS,CAAC;AAajB,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAoFnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAmDvE"}

package/dist/limits/pending-size.d.ts

@@ -0,0 +1,13 @@
+import type { ArgumentNode, GraphQLField, GraphQLNamedType } from 'graphql';
+import { type SizeContext } from './list-size.js';
+/**
+ * The size of the list `definition` on `parent`. `pending` is the size of the
+ * field whose return type this list is selected on (a connection's `first`):
+ * a list that declares none of the size arguments takes it, since the size
+ * cannot be stated on the list itself. A list that declares one reads its own
+ * arguments, else `defaultFirst`, and never the pending size. On an abstract
+ * parent some possible types may declare one and others not: the largest of
+ * both readings, since the query cannot say which comes back.
+ */
+export declare function listSizeUnder(cost: SizeContext, parent: GraphQLNamedType | undefined, definition: GraphQLField<unknown, unknown>, args: readonly ArgumentNode[] | undefined, pending: number | undefined): number;
+//# sourceMappingURL=pending-size.d.ts.map

package/dist/limits/pending-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-size.d.ts","sourceRoot":"","sources":["../../src/limits/pending-size.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAe,KAAK,WAAW,EAAc,MAAM,aAAa,CAAC;AAExE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,UAAU,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EAC1C,IAAI,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,CASR"}

package/dist/limits/size-reading.d.ts

@@ -0,0 +1,22 @@
+import type { GraphQLArgument, ValueNode } from 'graphql';
+/**
+ * The one reading of a size, wherever it comes from (a literal, a default): a
+ * non-negative integral number or bigint, or a canonical-integer string,
+ * clamped to the ceiling. Anything else says nothing.
+ */
+export declare function sizeOf(value: unknown): number | undefined;
+/** The size a literal gives: an Int, a canonical-integer String or an integral Float (`1e3`). */
+export declare function literalSize(value: ValueNode): number | undefined;
+/**
+ * An argument's SDL default as a size. graphql 16 holds it as `defaultValue`;
+ * graphql 17 as `default`, `{ value }` or `{ literal }`.
+ */
+export declare function defaultSizeOf(argument: object | undefined): number | undefined;
+/**
+ * The bound of an argument's `@constraint` directive, as a size: what the
+ * client may send at most. The largest of `max` and `exclusiveMax` (the value
+ * itself, a slight over-count), a fractional one rounded up. Read from the SDL
+ * node, so a code-first argument (no `astNode`) declares none.
+ */
+export declare function constraintMaxOf(argument: GraphQLArgument | undefined): number | undefined;
+//# sourceMappingURL=size-reading.d.ts.map

package/dist/limits/size-reading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"size-reading.d.ts","sourceRoot":"","sources":["../../src/limits/size-reading.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAK1D;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAczD;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAKhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,SAAS,CAiBpB;AAeD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,eAAe,GAAG,SAAS,GACnC,MAAM,GAAG,SAAS,CAepB"}

package/docs/README.md

@@ -6,7 +6,7 @@
 | --- | --- |
 | [Constraints](guide/constraints.md) | you write `@constraint` in your schema: setup with `withValidation`, every argument and its Zod equivalent, the formats and your own, lists and nested inputs |
 | [Answering invalid input as one error](guide/invalid-input.md) | your API answers invalid input as one 400 error with a list of fields (`invalidInputError`, `fieldIssueOf` for a Zod parse), or a refusal such as a 409 names the fields at fault (`fieldsError`) |
-| [Limiting the depth and cost of a query](guide/query-limits.md) | a schema has list cycles and you want to refuse a query nested too deep or too costly (`maxDepth`, `maxListCost`), with graphql-js `validate` or graphql-yoga |
+| [Limiting the depth and cost of a query](guide/query-limits.md) | a schema has list cycles and you want to refuse a query nested too deep, too costly or too wide (`maxDepth`, `maxListCost`, `maxFields`), with graphql-js `validate` or graphql-yoga |
 | [Errors](guide/errors.md) | you handle the `BAD_USER_INPUT` error in a client, build it yourself with `badUserInput`, or add rules a directive cannot say with `validated` |
 
 ## Reference

package/docs/guide/query-limits.md

@@ -1,6 +1,6 @@
 # Limiting the depth and cost of a query
 
-`maxDepth` and `maxListCost` are graphql-js validation rules. They refuse an
+`maxDepth`, `maxListCost` and `maxFields` are graphql-js validation rules. They refuse an
 operation before any resolver runs, so a hostile query costs a walk of its
 document and nothing more. For `@constraint`, see
 [Constraints](constraints.md).
@@ -26,25 +26,31 @@ query {
 Four `items` levels of 100 each can ask for 100 million nodes in a query nine
 levels deep (`folder`, four `items`, three `folder`, `id`). `maxDepth` bounds the nesting; `maxListCost` bounds the work.
 
+Neither bounds breadth: a query of 2000 aliases of `item(id: "1") { id }` is two
+levels deep and costs 4000, yet selects 4000 fields for the executor to run; so does a
+query of thousands of aliases of `__typename`, which neither rule counts.
+`maxFields` bounds that.
+
 ## Use
 
 With graphql-js, add the rules to the ones `validate` already runs:
 
 ```ts
-import { maxDepth, maxListCost } from '@nxgt/graphql-validation';
+import { maxDepth, maxFields, maxListCost } from '@nxgt/graphql-validation';
 import { parse, specifiedRules, validate } from 'graphql';
 
 const errors = validate(schema, parse(query), [
   ...specifiedRules,
   maxDepth({ depth: 8 }),
   maxListCost({ budget: 10_000, defaultFirst: 50 }),
+  maxFields({ limit: 500 }),
 ]);
 ```
 
 With graphql-yoga, in a plugin:
 
 ```ts
-import { maxDepth, maxListCost } from '@nxgt/graphql-validation';
+import { maxDepth, maxFields, maxListCost } from '@nxgt/graphql-validation';
 import { createYoga } from 'graphql-yoga';
 
 createYoga({
@@ -54,6 +60,7 @@ createYoga({
       onValidate: ({ addValidationRule }) => {
         addValidationRule(maxDepth({ depth: 8 }));
         addValidationRule(maxListCost({ budget: 10_000, defaultFirst: 50 }));
+        addValidationRule(maxFields({ limit: 500 }));
       },
     },
   ],
@@ -61,7 +68,7 @@ createYoga({
 ```
 
 Each rule reports **one** `GraphQLError` per operation, whose `nodes` is the
-operation. An invalid option (`depth: 0`, a fractional `budget`) throws a
+operation. An invalid option (`depth: 0`, a fractional `budget`, `limit: 0`) throws a
 `RangeError` when the rule is created.
 
 ## `maxDepth({ depth, ignoreIntrospection? })`
@@ -95,7 +102,7 @@ The refusal:
 `depth` is the operation's real depth. An anonymous operation reads
 `Operation is 9 levels deep, ...`.
 
-## `maxListCost({ budget, defaultFirst, sizeArguments?, ignoreIntrospection? })`
+## `maxListCost({ budget, defaultFirst, sizeArguments?, ignoreIntrospection?, variableSize? })`
 
 ### How cost is counted
 
@@ -142,35 +149,113 @@ argument says:
 | a bigint (an SDL default held by a code-first schema, or after graphql-tools' `mapSchema`) | that number |
 | an integral Float literal (`first: 1000.0`, `first: 1e3`) | that number; `1.5` and `-1000.0` are unusable |
 | a negative literal (`first: -1000`), another string | as if unusable, see below |
-| a variable (`first: $n`) | as if unusable: validation has no variable values |
+| a variable (`first: $n`) | as if unusable, see below: validation has no variable values |
 | not given | its SDL default, when it has one; else nothing |
 
 An SDL default is read the same way: `limit: String = "1000"` and `first:
 Float = 1000.0` are sizes of 1000. Every size is held at most
 `Number.MAX_SAFE_INTEGER`.
 
-An argument given but unusable counts for its SDL default when it has one in
-any accepted form (`items(first: Int = 100)`), and `defaultFirst` otherwise. On
-an abstract parent that is the largest default, or `defaultFirst` when it is
-larger and some possible type has no default. A
-field where no size argument says anything is sized `defaultFirst`.
+An argument given but unusable (a negative number, a variable) counts for the
+largest of its SDL default when it has one in any accepted form (`items(first:
+Int = 100)`, else `defaultFirst`), its declared bound (`@constraint(max)` or
+`exclusiveMax`) and, where some definition declares no bound, `variableSize`:
+see [Variables](#variables). A field where no size argument says anything is
+sized `defaultFirst`.
 
 On an interface or a union, the default is the **largest** over the interface's
 field and the field of every possible type (`Node.kids(first: Int = 1)` next to
 `Folder.kids(first: Int = 100000)` is sized 100,000), since the query cannot
-say which object comes back.
+say which object comes back; `defaultFirst` counts too when it is larger and
+some possible type has no default.
 
 A negative number is therefore never taken as a size: no subtree costs less than
 nothing, and `items(first: -1000)` next to an expensive sibling cannot cancel
 the sibling's cost.
 
-Pick `defaultFirst` knowing a variable counts for it: a client using
-`first: $n` is charged the default whatever it sends. If your server caps a size
-argument, set `defaultFirst` (or the SDL default) at that cap.
+### Variables
+
+The client can send any value the argument accepts, so a size given as a
+variable (or as an unusable literal) counts as the **largest** of:
+
+- its SDL default, else `defaultFirst`: never less than that;
+- the bound of the argument's `@constraint` (the directive `withValidation`
+  enforces), read from the schema's SDL: `first: Int = 20 @constraint(max: 100)`
+  counts 100 for `first: $n`. `exclusiveMax` is read the same way (the value
+  itself, a slight over-count), a fractional bound is rounded up (`max: 100.5`
+  counts 101), and the largest of `max` and `exclusiveMax` counts. On an
+  interface it is the largest over the interface's field and each possible
+  type's field;
+- `variableSize`, where some definition declares no bound:
+  `maxListCost({ budget, defaultFirst, variableSize: 100 })` for a server that
+  caps every page at 100 in its resolvers. It applies to every size argument
+  (`first`, `last`, `limit`, your own `sizeArguments`) and to unusable
+  literals. A declared bound wins over it only when every definition (the
+  interface's field and each possible type's) declares one; if any lacks one,
+  `variableSize` applies too and the largest wins.
+
+```graphql
+query ($n: Int) { wards(first: $n) { edges { node { rooms(first: $n) { id } } } } }
+```
+
+With `first: Int = 20 @constraint(max: 100)` on both fields, that query is
+costed as the same one written with `first: 100`, not with the defaults. The
+operation's own variable default (`query ($n: Int = 5)`) is ignored: the client
+can override it. An argument not given at all keeps its SDL default.
+
+### Relay connections
+
+On a Relay connection the size is on a field that returns an **object**, and the
+list is below it:
+
+```graphql
+type Query { items(first: Int): ItemConnection! }
+type ItemConnection { edges: [ItemEdge!]! nodes: [Item!]! pageInfo: PageInfo! }
+```
+
+```graphql
+{ items(first: 100) { edges { node { id } } nodes { id } } }
+```
+
+A field that is not a list and states a size, read as for a list above (a size
+argument given, or declared with a default; on an abstract parent the largest
+over its possible types), hands it down as a **pending size** to the lists
+selected **directly on its return type**:
+
+- Only a list that **declares none of the size arguments** takes it, instead of
+  `defaultFirst`: `edges` and `nodes` above are both 100. A list that declares
+  one (`recent(first: Int)`) reads its own arguments, else `defaultFirst`,
+  never the pending size.
+- On an interface, when some possible types declare a size argument on that
+  list and others do not, the larger of the pending size and the list's own
+  reading is used, since the query cannot say which comes back.
+- It stops at the first field crossed: an object field (`owner`), `pageInfo` or
+  a wrapper object passes nothing on, so the lists below them are sized as
+  without a connection. In `items(first: 0) { owner { friends { … } } }` the
+  `0` does not reach `friends`. A nested field that states a size hands its own
+  to the lists directly on it.
+- A connection field that states nothing (no size argument given, none declared
+  with a default) hands down nothing: its lists are sized `defaultFirst`, as
+  before. A variable, a negative number or an unusable value on it counts as for
+  a list, see [Variables](#variables).
+- The rule is structural: any non-list field stating a size sizes the lists
+  declaring no size argument directly on its return type, whether or not it is
+  a connection. `user(limit: 0) { friends { … } }` sizes `friends` 0. So an
+  argument named in `sizeArguments` must size the lists directly under its
+  field: when one of yours means something else, leave its name out of
+  `sizeArguments` (or rename the argument).
+- Inline fragments, and fragment spreads, on that same selection set pass the
+  pending size through. A named fragment is costed once for each distinct
+  pending size it is spread under (`...C` under
+  `first: 2` and `first: 5` costs differently). Under more than eight distinct
+  sizes in one document a fragment's further sizes are rounded up to the next
+  power of two, so the work stays linear in the document and the cost only
+  over-counts.
 
 ### Fragments and abstract types
 
-Named fragments are followed, each costed once (a fragment's type condition fixes
+Named fragments are followed, each costed once per pending size (see above;
+a fragment's type condition fixes
 its parent type). A fragment spread twice counts twice. Inline fragments and
 fragments on an interface or a union are **summed branch by branch**: a
 selection `... on A { ... } ... on B { ... }` costs A's plus B's, although an
@@ -186,7 +271,7 @@ never underestimated.
 }
 ```
 
-`budget` and `defaultFirst` must be integers below `Number.MAX_SAFE_INTEGER`
+`budget`, `defaultFirst` and `variableSize` must be integers below `Number.MAX_SAFE_INTEGER`
 (a cost never exceeds it, so a budget at or over it would refuse nothing); the
 rule throws a `RangeError` otherwise.
 
@@ -194,8 +279,61 @@ Costs are plain numbers, computed from memoized fragments (no exponential work
 on a hostile query) and held at `Number.MAX_SAFE_INTEGER`: `cost` is exact below
 it and never `Infinity`.
 
+## `maxFields({ limit, ignoreIntrospection? })`
+
+The size of an operation is the number of field selections in its document,
+fragment spreads expanded. It is not what the executor runs: how often a field
+runs inside a list is `maxListCost`'s business, so `maxFields` alone does not
+bound execution.
+
+- Every field node counts 1: aliases count (`a1: id a2: id` is 2), and so does
+  `__typename`.
+- A named fragment counts **at each spread**: a fragment of 3 fields spread
+  twice adds 6. Each fragment is walked once, so the work stays linear in the
+  size of the document even when spreads multiply. A fragment cycle counts 0
+  (`NoFragmentCyclesRule` reports it).
+- Inline fragments count their contents. No type condition prunes anything:
+  every branch of a union or an interface counts, so the figure can only be
+  over the document's field count.
+- `@skip` and `@include` are not evaluated (the rules read the document, not its
+  variables): a field they would remove is counted anyway.
+- `__schema` and `__type` and everything under them count like any field.
+  The standard introspection query (`getIntrospectionQuery()`) selects **220
+  fields** on graphql 16 and 17 (the fragments `FullType`, `InputValue` and
+  `TypeRef` are counted at each spread), so a limit under 220 refuses it. Where
+  introspection is disabled, or the client is trusted (GraphiQL in development),
+  pass `ignoreIntrospection: true`.
+
+The refusal:
+
+```json
+{
+  "message": "Operation \"Wide\" selects 4000 fields, more than the 500 allowed",
+  "extensions": { "code": "QUERY_TOO_WIDE", "fields": 4000, "limit": 500 }
+}
+```
+
+`fields` is the operation's real count, held at `Number.MAX_SAFE_INTEGER`
+whatever a hostile query multiplies. An anonymous operation reads
+`Operation selects 4000 fields, ...`. `limit` must be an integer from 1 to
+`Number.MAX_SAFE_INTEGER - 1`, else a `RangeError`.
+
+### Choosing a limit
+
+Count the fields of your largest legitimate query, spreads included (a page
+that spreads a 10-field fragment on 20 list entries reads 200 plus the rest),
+and add headroom: a few hundred covers most screens. Keep the introspection
+query in mind (220) if you leave it counted. `maxFields` complements the other
+two: `maxDepth` bounds nesting, `maxListCost` bounds list multiplication, and
+`maxFields` bounds how many fields one request may name.
+
 ## Not covered
 
+- A code-first argument has no SDL node, hence no declared bound: only
+  `variableSize` applies to a variable on it.
+- A size bounded only by a custom scalar (`first: PageSize`) or by `maxItems`
+  or `maxLength` counts as having no bound: declare `@constraint(max)` on the
+  argument.
 - A size carried inside an input object (`items(page: { first: 1000 })`) is not
   read: the field has no size argument, so it is sized `defaultFirst`. Name the
   size as an argument, or raise `defaultFirst`.

package/docs/roadmap.md

@@ -18,10 +18,21 @@ Nothing planned yet.
 
 ## Shipped
 
-- **Query depth and cost limits** — `maxDepth` and `maxListCost` are graphql-js
-  validation rules (also for graphql-yoga's `addValidationRule`) that refuse a
-  query nested too deep or too costly for a schema with list cycles, with the
-  stable codes `QUERY_TOO_DEEP` and `QUERY_TOO_COSTLY`.
+- **Relay connection sizing** — `maxListCost` sizes the `edges` and `nodes` of
+  a connection from the connection field's size argument (`items(first: 100)
+  { edges { … } }`), not `defaultFirst`.
+- **Variable sizes counted at their bound** — `maxListCost` counts a size sent
+  as a variable (or an unusable literal) at the argument's declared bound
+  (`@constraint(max)` or `exclusiveMax`) and the new `variableSize` option. The
+  bound wins only when every definition declares one, and never counts below the
+  SDL default or `defaultFirst`, so a query cannot hide a large page behind a
+  variable.
+- **Query depth, cost and breadth limits** — `maxDepth`, `maxListCost` and
+  `maxFields` are graphql-js validation rules (also for graphql-yoga's
+  `addValidationRule`) that refuse a query nested too deep, too costly for a
+  schema with list cycles, or selecting too many fields (aliases of a cheap
+  field), with the stable codes `QUERY_TOO_DEEP`, `QUERY_TOO_COSTLY` and
+  `QUERY_TOO_WIDE`.
 - **Schemas that read the context** — 0.5.0. `validated((context, info) =>
   schema, resolver)` builds the schema on each call from the request's context
   and the field's `info`, for checks that need the request (a uniqueness query

package/docs/troubleshooting.md

@@ -425,11 +425,35 @@ reads `Operation is 9 levels deep, ...`.
 **When:** an operation is validated with `maxListCost({ budget: 1000, ... })`.
 **Why:** `extensions` is `{ code: 'QUERY_TOO_COSTLY', cost: 5002, limit: 1000 }`.
 Each field costs 1, times the sizes of the lists enclosing it. A list without a
-usable `first` (a variable, a negative number, nothing) counts for its SDL
-default, else `defaultFirst`, so a query that is cheap with the variable's real
-value can still be refused.
-**Fix:** ask for fewer items with a literal `first`, or raise `budget`. A query
-on an interface or a union is overestimated (every branch is summed).
+usable `first` counts for its SDL default, else `defaultFirst`; a variable or
+a negative number counts for the largest of that, the declared bound and
+`variableSize`, so a query that is cheap with the variable's real value can
+still be refused, see [Variables](guide/query-limits.md#variables). A size
+argument on a field returning an object (a connection's `first`) sizes its
+`edges` and `nodes`, and any non-list field stating a size sizes the lists
+declaring none directly under it, see
+[Relay connections](guide/query-limits.md#relay-connections).
+
+**Fix:** ask for fewer items with a literal `first`, lower the `@constraint(max)`
+of a size argument, or raise `budget`. A query on an interface or a union is
+overestimated (every branch is summed).
+
+### `Operation "Name" selects 4000 fields, more than the 500 allowed`
+
+**When:** an operation is validated with `maxFields({ limit: 500 })`.
+**Why:** `extensions` is `{ code: 'QUERY_TOO_WIDE', fields: 4000, limit: 500 }`.
+Every field selection counts 1, aliases and `__typename` included, and a named
+fragment counts at each spread; every branch of an inline fragment counts and
+`@skip`/`@include` are not evaluated, so the figure can be over what runs. An
+anonymous operation reads `Operation selects 4000 fields, ...`.
+**Fix:** ask for fewer fields (a fragment spread many times is many fields), or
+raise `limit`. See [Limiting the depth and cost of a query](guide/query-limits.md).
+
+### `maxFields: limit must be an integer from 1 to 9007199254740990.`
+
+**When:** `maxFields` is called with `0`, a negative, a fractional or a too
+large `limit`.
+**Fix:** pass an integer in range.
 
 ### `maxDepth: depth must be an integer from 1 to 9007199254740990.`
 
@@ -448,15 +472,28 @@ budget at or over it would refuse nothing.
 **When:** `defaultFirst` is negative, fractional or too large.
 **Fix:** pass the size to assume for a list with no usable size argument.
 
+### `maxListCost: variableSize must be an integer from 0 to 9007199254740990.`
+
+**When:** `variableSize` is negative, fractional or too large.
+**Why:** it is the size assumed for a variable or unusable size argument, and
+a size is an integer from 0 up to a bound a cost cannot overflow.
+**Fix:** pass an integer in range, such as the page cap of your resolvers:
+
+```ts
+maxListCost({ budget: 10_000, defaultFirst: 50, variableSize: 100 });
+```
+
 ### A query refused although its `first` is small, or an introspection query refused
 
-**When:** `QUERY_TOO_COSTLY` or `QUERY_TOO_DEEP` for GraphiQL's schema fetch or
+**When:** `QUERY_TOO_COSTLY`, `QUERY_TOO_DEEP` or `QUERY_TOO_WIDE` for GraphiQL's schema fetch or
 a codegen's introspection query.
 **Why:** `__schema` is counted: the standard introspection query is 15 levels
-deep and costs on the order of 200,000 on a one-field schema.
+deep, selects 220 fields and costs on the order of 200,000 on a one-field schema.
 **Fix:** `ignoreIntrospection: true` on the rule where introspection is
-disabled or the client is trusted. A `first: $n` variable counts for the SDL
-default, not for the value sent.
+disabled or the client is trusted. A `first: $n` variable counts for its
+declared bound (`@constraint(max)` or `exclusiveMax`, when every definition
+declares one) and `variableSize` otherwise, never below the SDL default or
+`defaultFirst`, not for the value sent.
 
 ## The bin
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/graphql-validation",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"description": "Validate GraphQL arguments and input fields with @constraint directives, checked by Zod schemas, for graphql 16 and 17",
 	"license": "MIT",
 	"type": "module",