first commit

docs/api-stack/api/api-graphql/src/error-codes/error-codes.md

@@ -0,0 +1,80 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Stable error-code registry for `@suaveplan/api-graphql`. Every public failure
+path raises a `GraphqlError` carrying one of these namespaced `GRAPHQL.*`
+codes; the host's `ErrorEnvelope` writer maps them directly to the JSON wire
+shape declared by `@suaveplan/api-types/errors`.
+
+Centralising the registry here lets engine adapters (`api-graphql-yoga`,
+`api-graphql-apollo`) inherit the seven base codes and add engine-specific
+codes under a longer namespace (`GRAPHQL.YOGA.*`) without colliding with the
+contract layer.
+
+## Features
+
+- Seven frozen codes covering schema federation, resolver wiring, loader
+  registration, directive lookup, subscription transport availability, and
+  strict-mode namespace enforcement.
+- Typed `GraphqlError` subclass — `instanceof` narrows the `code` field to
+  `GraphqlErrorCode`.
+- Constructor widened to `public` so callers may instantiate directly.
+- Side-effect import from the package barrel surfaces the registry at
+  load time (matches `api-plugin`'s pattern).
+
+## Usage: Basic
+
+```ts
+import { GRAPHQL_CODES, GraphqlError } from "@suaveplan/api-graphql/error-codes";
+
+throw new GraphqlError(
+    GRAPHQL_CODES.SCHEMA_COLLISION,
+    "two plugins declare Query.users"
+);
+```
+
+## Usage: Advanced
+
+Attach structured detail for the wire envelope:
+
+```ts
+throw new GraphqlError(
+    "GRAPHQL.SCHEMA_COLLISION",
+    "schema collision on Query.users between plugins Billing and Identity",
+    {
+        details: {
+            path: "Query.users",
+            plugins: ["Billing", "Identity"],
+        },
+    }
+);
+```
+
+The host's error-envelope writer pipes `details` straight into the JSON
+response without modification.
+
+## API Reference
+
+- `GRAPHQL_CODES` — frozen record `{ SCHEMA_COLLISION, RESOLVER_MISSING,
+  LOADER_DUPLICATE_NAME, LOADER_NOT_REGISTERED, DIRECTIVE_UNKNOWN,
+  SUBSCRIPTION_TRANSPORT_UNAVAILABLE, NAMESPACE_REQUIRED }`. Values are the
+  fully-qualified `GRAPHQL.<NAME>` strings.
+- `GraphqlErrorCode` — string union derived from `GRAPHQL_CODES`.
+- `GraphqlError extends SuaveplanError<GraphqlErrorCode>` — adds a
+  read-only `graphqlCode` mirror for ergonomic branching.
+
+## Implementation Notes
+
+`defineCodes` returns a `Object.freeze`d record so the union literal is
+preserved at the type level (TypeScript widens otherwise). Callers may
+branch on the string literal (`"GRAPHQL.SCHEMA_COLLISION"`) or the typed
+constant (`GRAPHQL_CODES.SCHEMA_COLLISION`) — both produce the same value.
+
+Concrete engines that raise additional codes do so via their own
+`defineCodes("GRAPHQL.YOGA", [...])` registry; this package owns only the
+contract-layer codes that map to engine-agnostic failure modes.