Initial Commit

packages/api-stack/api/api-graphql-ui-graphiql/src/error-codes/error-codes.md

@@ -0,0 +1,85 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the stable `GRAPHQL_UI_GRAPHIQL.*` error-code registry consumed by the
+GraphiQL UI plugin. Every code in the registry is thrown by a production
+path in this package — the `error-codes.spec-conformance.test.ts` walks
+the registry against the source tree to prove that no code is unused and
+that no production throw site references an unregistered code.
+
+The module also exports `GraphqlUiGraphiqlError`, a concrete
+`SuaveplanError` subclass with a `graphiqlCode` mirror property. Callers
+can discriminate failures from this package via `instanceof` or by
+checking the stable `error.code` field; the mirror property exists so
+TypeScript narrows to the narrow union without the consumer importing
+the `GraphqlUiGraphiqlCode` alias.
+
+## Features
+
+- Two-code registry — `ASSET_MISSING`, `ENDPOINT_COLLISION`.
+- `defineCodes("GRAPHQL_UI_GRAPHIQL", …)` namespace.
+- `GraphqlUiGraphiqlError` extends `SuaveplanError` with a public
+  constructor (required by the repo's `check-error-subclass-constructors`
+  lint).
+- Frozen registry — `Object.isFrozen(GRAPHQL_UI_GRAPHIQL_CODES) === true`.
+
+## Usage: Basic
+
+```ts
+import {
+    GRAPHQL_UI_GRAPHIQL_CODES,
+    GraphqlUiGraphiqlError,
+} from "@suaveplan/api-graphql-ui-graphiql";
+
+throw new GraphqlUiGraphiqlError(
+    GRAPHQL_UI_GRAPHIQL_CODES.ASSET_MISSING,
+    "Bundled asset \"missing.js\" is not registered"
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    GRAPHQL_UI_GRAPHIQL_CODES,
+    GraphqlUiGraphiqlError,
+} from "@suaveplan/api-graphql-ui-graphiql";
+
+try {
+    mountGraphiqlUi();
+} catch (err) {
+    if (err instanceof GraphqlUiGraphiqlError) {
+        if (err.code === GRAPHQL_UI_GRAPHIQL_CODES.ENDPOINT_COLLISION) {
+            // Operator-facing: log the existing plugin from err.context.
+            log.error({
+                msg: "graphiql collision",
+                existing: err.context?.existing,
+            });
+        }
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+- `GRAPHQL_UI_GRAPHIQL_CODES` — frozen `Record<string, string>` of fully
+  qualified codes.
+- `GraphqlUiGraphiqlCode` — union of every value resolved through the
+  registry.
+- `class GraphqlUiGraphiqlError extends SuaveplanError<GraphqlUiGraphiqlCode>`
+  — public constructor `(code, message, options?)` mirrors
+  `SuaveplanError`'s signature.
+
+## Implementation Notes
+
+The class name (`GraphqlUiGraphiqlError`) is intentionally explicit so
+stack traces and logs distinguish errors from this package vs the sibling
+`api-graphql-ui-altair`. The public constructor is required by the
+project-wide `check-error-subclass-constructors` lint added in
+`cd454b3924`.