@glubean/graphql 0.1.7 → 0.2.1

package/dist/contract/factory.js

@@ -0,0 +1,90 @@
+/**
+ * contract.graphql factory — scoped-defaults pattern.
+ *
+ * Root `contract.graphql` exposes only `.with(name, defaults)`. Calling
+ * `contract.graphql("id", spec)` directly is forbidden — client injection
+ * via scoped instances is the canonical authoring pattern (same as HTTP
+ * and gRPC).
+ *
+ * The factory wraps the generic dispatcher attached to `contract.graphql`
+ * by `contract.register("graphql", graphqlAdapter)`. Calls flow through:
+ *   user code
+ *     → scoped factory(id, spec)
+ *     → merge instance defaults into spec
+ *     → dispatcher(id, mergedSpec)   [generic register() output]
+ *     → adapter.project + per-case registerTest + Test[] with
+ *       _projection/_spec
+ */
+function mergeExtensions(base, override) {
+    if (!base && !override)
+        return undefined;
+    const merged = {
+        ...(base ?? {}),
+        ...(override ?? {}),
+    };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function mergeGraphqlDefaults(defaults, spec) {
+    if (!defaults)
+        return spec;
+    const mergedTags = [...(defaults.tags ?? []), ...(spec.tags ?? [])];
+    const mergedExtensions = mergeExtensions(defaults.extensions, spec.extensions);
+    const mergedHeaders = {
+        ...(defaults.headers ?? {}),
+        ...(spec.defaultHeaders ?? {}),
+    };
+    return {
+        ...spec,
+        client: spec.client ?? defaults.client,
+        endpoint: spec.endpoint ?? defaults.endpoint,
+        feature: spec.feature ?? defaults.feature,
+        tags: mergedTags.length > 0 ? mergedTags : undefined,
+        extensions: mergedExtensions,
+        defaultHeaders: Object.keys(mergedHeaders).length > 0 ? mergedHeaders : undefined,
+    };
+}
+function applyInstanceMetadata(contract, instanceName) {
+    const proj = contract._projection;
+    proj.instanceName = instanceName;
+}
+/**
+ * Build a scoped GraphQL factory. `dispatch` is `contract.graphql` attached
+ * by the core's register() call — we wrap it to inject instance defaults.
+ */
+export function createGraphqlFactory(dispatch, defaults) {
+    const factory = (id, spec) => {
+        if (!defaults?._name) {
+            throw new Error(`contract.graphql("${id}", spec) is not supported. ` +
+                `Use contract.graphql.with("name", { client }) first to create a scoped instance, ` +
+                `then call instance("${id}", spec).`);
+        }
+        const merged = mergeGraphqlDefaults(defaults, spec);
+        const result = dispatch(id, merged);
+        applyInstanceMetadata(result, defaults._name);
+        return result;
+    };
+    factory.with = (name, more = {}) => {
+        const mergedTags = [...(defaults?.tags ?? []), ...(more.tags ?? [])];
+        const mergedExtensions = mergeExtensions(defaults?.extensions, more.extensions);
+        const mergedHeaders = {
+            ...(defaults?.headers ?? {}),
+            ...(more.headers ?? {}),
+        };
+        return createGraphqlFactory(dispatch, {
+            ...defaults,
+            ...more,
+            tags: mergedTags.length > 0 ? mergedTags : undefined,
+            extensions: mergedExtensions,
+            headers: Object.keys(mergedHeaders).length > 0 ? mergedHeaders : undefined,
+            _name: name,
+        });
+    };
+    return factory;
+}
+/**
+ * Root factory — `.with()` only, direct call throws.
+ */
+export function createGraphqlRoot(dispatch) {
+    return createGraphqlFactory(dispatch);
+}
+//# sourceMappingURL=factory.js.map

package/dist/contract/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/contract/factory.ts"],"names":[],"mappings":"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"}

package/dist/contract/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GraphQL contract surface for @glubean/graphql 0.2.0.
+ *
+ * This module makes `@glubean/graphql` a single-package owner of both:
+ *   - Transport / client layer (existing `../index.ts`, unchanged)
+ *   - Contract adapter layer (this directory)
+ *
+ * Mirrors the same single-package design as `@glubean/grpc` 0.2.0.
+ * See `internal/00-product/positioning-v3.md` §12.0 resolved and
+ * `internal/40-discovery/proposals/contract-grpc-graphql-expansion.md` §6.1.
+ *
+ * Side-effect on import:
+ *   1. `contract.register("graphql", graphqlAdapter)` — registers dispatcher
+ *   2. Wrap dispatcher with `createGraphqlRoot` so
+ *      `contract.graphql.with(name, defaults)` UX works
+ *
+ * After this module loads, users can:
+ *
+ *   import "@glubean/graphql"; // side-effect: registers graphql contract adapter
+ *   import { contract } from "@glubean/sdk";
+ *
+ *   const api = contract.graphql.with("api", { client });
+ *   export const getUser = api("get-user", {
+ *     cases: {
+ *       ok: {
+ *         description: "success",
+ *         query: `query GetUser($id: ID!) { user(id: $id) { name } }`,
+ *         variables: { id: "1" },
+ *         expect: { data: { user: { name: "Alice" } } },
+ *       },
+ *     },
+ *   });
+ */
+export { graphqlAdapter } from "./adapter.js";
+export { createGraphqlFactory, createGraphqlRoot } from "./factory.js";
+export type { GraphqlContractCase, GraphqlContractDefaults, GraphqlContractExample, GraphqlContractExpect, GraphqlContractFactory, GraphqlContractMeta, GraphqlContractRoot, GraphqlContractSafeMeta, GraphqlContractSpec, GraphqlCaseResult, GraphqlErrorsExpect, GraphqlFlowCaseOutput, GraphqlPayloadSchemas, GraphqlSafeSchemas, GraphqlTypeDef, GraphqlTypeDefs, InferGraphqlVariables, InferGraphqlResponse, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA0BH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACvE,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/contract/index.js

@@ -0,0 +1,55 @@
+/**
+ * GraphQL contract surface for @glubean/graphql 0.2.0.
+ *
+ * This module makes `@glubean/graphql` a single-package owner of both:
+ *   - Transport / client layer (existing `../index.ts`, unchanged)
+ *   - Contract adapter layer (this directory)
+ *
+ * Mirrors the same single-package design as `@glubean/grpc` 0.2.0.
+ * See `internal/00-product/positioning-v3.md` §12.0 resolved and
+ * `internal/40-discovery/proposals/contract-grpc-graphql-expansion.md` §6.1.
+ *
+ * Side-effect on import:
+ *   1. `contract.register("graphql", graphqlAdapter)` — registers dispatcher
+ *   2. Wrap dispatcher with `createGraphqlRoot` so
+ *      `contract.graphql.with(name, defaults)` UX works
+ *
+ * After this module loads, users can:
+ *
+ *   import "@glubean/graphql"; // side-effect: registers graphql contract adapter
+ *   import { contract } from "@glubean/sdk";
+ *
+ *   const api = contract.graphql.with("api", { client });
+ *   export const getUser = api("get-user", {
+ *     cases: {
+ *       ok: {
+ *         description: "success",
+ *         query: `query GetUser($id: ID!) { user(id: $id) { name } }`,
+ *         variables: { id: "1" },
+ *         expect: { data: { user: { name: "Alice" } } },
+ *       },
+ *     },
+ *   });
+ */
+import { contract } from "@glubean/sdk";
+import { graphqlAdapter } from "./adapter.js";
+import { createGraphqlRoot } from "./factory.js";
+import { registerGraphqlMatchers } from "./matchers.js";
+// Step 1: register the adapter. After this, `contract.graphql` exists as the
+// generic dispatcher attached by `contract.register()`.
+contract.register("graphql", graphqlAdapter);
+// Step 2: wrap dispatcher with the scoped-defaults factory so
+// `contract.graphql.with(name, defaults)` UX works.
+{
+    const dispatcher = contract.graphql;
+    contract.graphql = createGraphqlRoot(dispatcher);
+}
+// Step 3: register GraphQL custom matchers so
+// `ctx.expect(res).toHaveGraphqlData({...})` / `.toHaveGraphqlNoErrors()` /
+// `.toHaveHttpStatus(200)` / `.toHaveGraphqlErrorCode("UNAUTHENTICATED")`
+// work out of the box for any `@glubean/graphql` user.
+registerGraphqlMatchers();
+// Re-exports for type consumers who import from the package directly.
+export { graphqlAdapter } from "./adapter.js";
+export { createGraphqlFactory, createGraphqlRoot } from "./factory.js";
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAGxD,6EAA6E;AAC7E,wDAAwD;AACxD,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAE7C,8DAA8D;AAC9D,oDAAoD;AACpD,CAAC;IACC,MAAM,UAAU,GAAI,QAAgB,CAAC,OAAkD,CAAC;IACvF,QAAwD,CAAC,OAAO,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;AACpG,CAAC;AAED,8CAA8C;AAC9C,4EAA4E;AAC5E,0EAA0E;AAC1E,uDAAuD;AACvD,uBAAuB,EAAE,CAAC;AAE1B,sEAAsE;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/contract/matchers.d.ts

@@ -0,0 +1,95 @@
+/**
+ * GraphQL custom matchers for `ctx.expect()`.
+ *
+ * Registered as a side effect of `import "@glubean/graphql"` (see
+ * `./index.ts`). No extra import or configure step required — the
+ * matchers become available on every `ctx.expect(res)` call and are
+ * fully typed via the `CustomMatchers<T>` declaration merging block
+ * below.
+ *
+ * Matchers work on any object that carries GraphQL response shape, including:
+ *   - `GraphQLResult<T>` from `@glubean/graphql` transport
+ *     (`gql.query(...)` / `gql.mutate(...)`)
+ *   - `GraphqlCaseResult<T>` from the contract adapter
+ *     (verify callback / flow `out` lens input)
+ *
+ * Both expose:
+ *   {
+ *     data: T | null,
+ *     errors?: GraphQLError[],
+ *     extensions?: Record<string, unknown>,
+ *     httpStatus: number,
+ *     headers: Record<string, string | string[]>,
+ *     rawBody: string | null,
+ *     ...
+ *   }
+ *
+ * The HTTP `toHaveStatus` built-in matcher reads `actual.status`, which the
+ * GraphQL envelope does NOT expose (it's `httpStatus` — a deliberate rename
+ * in CG-10 to avoid shadowing the native `Response.status` semantics). The
+ * `toHaveHttpStatus` matcher added here reads the envelope's `httpStatus`
+ * field so GraphQL users have a symmetric transport-level assertion.
+ */
+declare module "@glubean/sdk/expect" {
+    interface CustomMatchers<T> {
+        /**
+         * Assert the transport-level HTTP status on a `GraphQLResult` /
+         * `GraphqlCaseResult`. Reads `actual.httpStatus`.
+         *
+         * Use this (not `toHaveStatus`) for GraphQL responses — the envelope
+         * field is `httpStatus`, not `status`.
+         *
+         * @example ctx.expect(res).toHaveHttpStatus(200);
+         * @example ctx.expect(res).toHaveHttpStatus(401, "missing token");
+         */
+        toHaveHttpStatus(code: number, message?: string): Expectation<T>;
+        /**
+         * Partial-match the GraphQL `data` field (like `toMatchObject`).
+         *
+         * Fails if `data` is null or the subset is not contained in `data`.
+         *
+         * @example ctx.expect(res).toHaveGraphqlData({ user: { name: "Alice" } });
+         */
+        toHaveGraphqlData(subset: Record<string, unknown>, message?: string): Expectation<T>;
+        /**
+         * Assert the `errors` array is absent or empty (strict success).
+         *
+         * @example ctx.expect(res).toHaveGraphqlNoErrors();
+         */
+        toHaveGraphqlNoErrors(message?: string): Expectation<T>;
+        /**
+         * Assert at least one entry in `errors` has matching
+         * `extensions.code` (case-insensitive).
+         *
+         * @example ctx.expect(res).toHaveGraphqlErrorCode("UNAUTHENTICATED");
+         */
+        toHaveGraphqlErrorCode(code: string, message?: string): Expectation<T>;
+        /**
+         * Assert a key exists in `extensions` (server-side tracing / cost),
+         * optionally matching an exact value.
+         *
+         * @example ctx.expect(res).toHaveGraphqlExtension("tracing");
+         * @example ctx.expect(res).toHaveGraphqlExtension("version", "v2");
+         */
+        toHaveGraphqlExtension(key: string, value?: unknown, message?: string): Expectation<T>;
+    }
+}
+/**
+ * Register GraphQL matchers onto the shared `Expectation` prototype. Called
+ * from `./index.ts` during the same side-effect block that registers the
+ * contract adapter; users get matchers + adapter from a single
+ * `import "@glubean/graphql"`.
+ *
+ * Idempotent: swallows the "matcher already exists" error thrown by
+ * `Expectation.extend` on re-evaluation (duplicate imports, Vitest
+ * isolation boundaries, etc.).
+ *
+ * Note: `toHaveHttpStatus` is registered here even though it's
+ * conceptually transport-level (not GraphQL-specific) — users of
+ * `@glubean/graphql` are the ones who need it because the GraphQL
+ * envelope uses `httpStatus` instead of `status`. If a future package
+ * also exposes an `httpStatus` field, registration idempotency will
+ * catch the conflict at boot.
+ */
+export declare function registerGraphqlMatchers(): void;
+//# sourceMappingURL=matchers.d.ts.map

package/dist/contract/matchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.d.ts","sourceRoot":"","sources":["../../src/contract/matchers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AASH,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,cAAc,CAAC,CAAC;QACxB;;;;;;;;;WASG;QACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAEjE;;;;;;WAMG;QACH,iBAAiB,CACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAAC,CAAC,CAAC,CAAC;QAElB;;;;WAIG;QACH,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAExD;;;;;WAKG;QACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAEvE;;;;;;WAMG;QACH,sBAAsB,CACpB,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAAC,CAAC,CAAC,CAAC;KACnB;CACF;AAgPD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAe9C"}

package/dist/contract/matchers.js

@@ -0,0 +1,246 @@
+/**
+ * GraphQL custom matchers for `ctx.expect()`.
+ *
+ * Registered as a side effect of `import "@glubean/graphql"` (see
+ * `./index.ts`). No extra import or configure step required — the
+ * matchers become available on every `ctx.expect(res)` call and are
+ * fully typed via the `CustomMatchers<T>` declaration merging block
+ * below.
+ *
+ * Matchers work on any object that carries GraphQL response shape, including:
+ *   - `GraphQLResult<T>` from `@glubean/graphql` transport
+ *     (`gql.query(...)` / `gql.mutate(...)`)
+ *   - `GraphqlCaseResult<T>` from the contract adapter
+ *     (verify callback / flow `out` lens input)
+ *
+ * Both expose:
+ *   {
+ *     data: T | null,
+ *     errors?: GraphQLError[],
+ *     extensions?: Record<string, unknown>,
+ *     httpStatus: number,
+ *     headers: Record<string, string | string[]>,
+ *     rawBody: string | null,
+ *     ...
+ *   }
+ *
+ * The HTTP `toHaveStatus` built-in matcher reads `actual.status`, which the
+ * GraphQL envelope does NOT expose (it's `httpStatus` — a deliberate rename
+ * in CG-10 to avoid shadowing the native `Response.status` semantics). The
+ * `toHaveHttpStatus` matcher added here reads the envelope's `httpStatus`
+ * field so GraphQL users have a symmetric transport-level assertion.
+ */
+import { Expectation, inspect } from "@glubean/sdk/expect";
+function readHttpStatus(actual) {
+    const s = actual?.httpStatus;
+    return typeof s === "number" ? s : undefined;
+}
+function readEnvelope(actual) {
+    if (!actual || typeof actual !== "object")
+        return undefined;
+    return actual;
+}
+/** Minimal partial-match helper — checks that every key/value in subset
+ *  is deep-equal to the corresponding path in target. Keeps this file
+ *  dependency-free from the sdk internal `matchesObject`. */
+function matchesSubset(target, subset) {
+    for (const [k, expected] of Object.entries(subset)) {
+        const actual = target[k];
+        if (expected !== null &&
+            typeof expected === "object" &&
+            !Array.isArray(expected)) {
+            if (!actual || typeof actual !== "object" || Array.isArray(actual)) {
+                return false;
+            }
+            if (!matchesSubset(actual, expected)) {
+                return false;
+            }
+        }
+        else if (Array.isArray(expected)) {
+            if (!Array.isArray(actual) || actual.length !== expected.length) {
+                return false;
+            }
+            for (let i = 0; i < expected.length; i++) {
+                if (JSON.stringify(actual[i]) !== JSON.stringify(expected[i])) {
+                    return false;
+                }
+            }
+        }
+        else if (actual !== expected) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
+// Matcher implementations
+// =============================================================================
+const toHaveHttpStatus = (actual, ...args) => {
+    const code = args[0];
+    const actualCode = readHttpStatus(actual);
+    if (actualCode === undefined) {
+        return {
+            passed: false,
+            message: `to have HTTP status ${code} — actual has no \`.httpStatus\` (got ${inspect(actual)})`,
+            actual,
+            expected: code,
+        };
+    }
+    return {
+        passed: actualCode === code,
+        message: `to have HTTP status ${code}`,
+        actual: actualCode,
+        expected: code,
+    };
+};
+const toHaveGraphqlData = (actual, ...args) => {
+    const subset = args[0];
+    const env = readEnvelope(actual);
+    if (!env) {
+        return {
+            passed: false,
+            message: `to have GraphQL data matching ${inspect(subset)} — actual is not an envelope`,
+            actual,
+            expected: subset,
+        };
+    }
+    const data = env.data;
+    if (data == null) {
+        return {
+            passed: false,
+            message: `to have GraphQL data matching ${inspect(subset)} — \`.data\` is null`,
+            actual: data,
+            expected: subset,
+        };
+    }
+    if (typeof data !== "object" || Array.isArray(data)) {
+        return {
+            passed: false,
+            message: `to have GraphQL data matching ${inspect(subset)} — \`.data\` is not an object`,
+            actual: data,
+            expected: subset,
+        };
+    }
+    const passed = matchesSubset(data, subset);
+    return {
+        passed,
+        message: `to have GraphQL data matching ${inspect(subset)}`,
+        actual: data,
+        expected: subset,
+    };
+};
+const toHaveGraphqlNoErrors = (actual) => {
+    const env = readEnvelope(actual);
+    const errs = env?.errors;
+    const count = Array.isArray(errs) ? errs.length : 0;
+    const summary = count > 0
+        ? errs.map((e) => e.message).slice(0, 3).join("; ") +
+            (count > 3 ? ` (+${count - 3} more)` : "")
+        : "";
+    return {
+        passed: count === 0,
+        message: count > 0
+            ? `to have no GraphQL errors (got ${count}: ${summary})`
+            : `to have no GraphQL errors`,
+        actual: errs ?? [],
+        expected: [],
+    };
+};
+const toHaveGraphqlErrorCode = (actual, ...args) => {
+    const code = args[0];
+    const env = readEnvelope(actual);
+    const errs = env?.errors;
+    if (!Array.isArray(errs) || errs.length === 0) {
+        return {
+            passed: false,
+            message: `to have GraphQL error code ${inspect(code)} — no errors on envelope`,
+            actual: errs ?? [],
+            expected: { "extensions.code": code },
+        };
+    }
+    const lower = code.toUpperCase();
+    const match = errs.find((e) => {
+        const c = e.extensions?.code;
+        return typeof c === "string" && c.toUpperCase() === lower;
+    });
+    return {
+        passed: !!match,
+        message: `to have GraphQL error code ${inspect(code)}`,
+        actual: errs.map((e) => e.extensions?.code ?? null),
+        expected: code,
+    };
+};
+const toHaveGraphqlExtension = (actual, ...args) => {
+    const key = args[0];
+    const expectedValue = args[1];
+    const env = readEnvelope(actual);
+    const ext = env?.extensions;
+    if (!ext || typeof ext !== "object") {
+        return {
+            passed: false,
+            message: `to have GraphQL extension \`${key}\` — actual has no \`.extensions\``,
+            actual: ext,
+            expected: expectedValue !== undefined ? { [key]: expectedValue } : key,
+        };
+    }
+    if (!(key in ext)) {
+        return {
+            passed: false,
+            message: `to have GraphQL extension \`${key}\``,
+            actual: Object.keys(ext),
+            expected: expectedValue !== undefined ? { [key]: expectedValue } : key,
+        };
+    }
+    if (expectedValue === undefined) {
+        return {
+            passed: true,
+            message: `to have GraphQL extension \`${key}\``,
+            actual: ext[key],
+            expected: key,
+        };
+    }
+    return {
+        passed: JSON.stringify(ext[key]) === JSON.stringify(expectedValue),
+        message: `to have GraphQL extension \`${key}\` = ${inspect(expectedValue)}`,
+        actual: ext[key],
+        expected: expectedValue,
+    };
+};
+// =============================================================================
+// Registration — side effect
+// =============================================================================
+/**
+ * Register GraphQL matchers onto the shared `Expectation` prototype. Called
+ * from `./index.ts` during the same side-effect block that registers the
+ * contract adapter; users get matchers + adapter from a single
+ * `import "@glubean/graphql"`.
+ *
+ * Idempotent: swallows the "matcher already exists" error thrown by
+ * `Expectation.extend` on re-evaluation (duplicate imports, Vitest
+ * isolation boundaries, etc.).
+ *
+ * Note: `toHaveHttpStatus` is registered here even though it's
+ * conceptually transport-level (not GraphQL-specific) — users of
+ * `@glubean/graphql` are the ones who need it because the GraphQL
+ * envelope uses `httpStatus` instead of `status`. If a future package
+ * also exposes an `httpStatus` field, registration idempotency will
+ * catch the conflict at boot.
+ */
+export function registerGraphqlMatchers() {
+    try {
+        Expectation.extend({
+            toHaveHttpStatus,
+            toHaveGraphqlData,
+            toHaveGraphqlNoErrors,
+            toHaveGraphqlErrorCode,
+            toHaveGraphqlExtension,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && /already exists/.test(err.message)) {
+            return;
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=matchers.js.map

package/dist/contract/matchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.js","sourceRoot":"","sources":["../../src/contract/matchers.ts"],"names":[],"mappings":"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"}