@venn-lang/graphql 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @venn-lang/graphql
+
+> The `gql` namespace: GraphQL queries, mutations and subscriptions as Venn verbs.
+
+Three verbs that all answer with the same `{ data, errors }` envelope, plus a `noGraphqlErrors`
+matcher to assert on it. Every call travels through the `GqlClient` port, so the same `.vn` file runs
+against a live server or against canned responses depending only on what the host bound at startup.
+
+## Install
+
+The package ships with the stdlib, so the CLI already loads it. Inside a `.vn` file, bring the
+namespace in with `use`:
+
+```ruby
+use "venn/graphql"
+```
+
+## Usage
+
+```ruby
+module demo.profile
+
+use "venn/graphql"
+
+flow "Profile" {
+  step "read the profile" {
+    let res = gql.query "{ me { id plan } }" { auth: "Bearer tok123" }
+    expect res noGraphqlErrors
+    expect res.data.me.plan == "pro"
+  }
+}
+```
+
+The document is the single positional argument. Everything else rides the options map:
+
+```ruby
+let res = gql.mutate "mutation Rename($id: ID!, $name: String!) { rename(id: $id, name: $name) { id } }" {
+  variables: { id: "u1", name: "Alice" }
+  auth: "Bearer tok123"
+}
+```
+
+`variables` and `auth` are the only accepted option names. Anything else is `VN3001`, reported by
+`venn check` before the flow runs and refused again when the line executes.
+
+## Verbs
+
+| Verb | Positional argument | Options | Result |
+| --- | --- | --- | --- |
+| `gql.query` | `document: string` | `variables`, `auth` | `gql.GraphqlResponse` |
+| `gql.mutate` | `document: string` | `variables`, `auth` | `gql.GraphqlResponse` |
+| `gql.subscribe` | `document: string` | `variables`, `auth` | `gql.GraphqlResponse` |
+
+`query` and `mutate` both call `GqlClient.execute`; `subscribe` calls `GqlClient.subscribe`. A
+subscription answers with one envelope, the same shape as the other two, not a live stream.
+
+## Matcher
+
+`expect <subject> noGraphqlErrors` passes when `errors` is absent, `null`, or an empty array, and
+fails when it carries at least one entry. It declares `appliesTo: "GraphqlResponse"`, which the
+editor shows on hover. The matcher lives in the plugin definition (`gqlPlugin.matchers`) and is not
+exported from the barrel.
+
+## Types
+
+The plugin publishes two named types the checker and the editor read:
+
+| Name | Shape |
+| --- | --- |
+| `gql.GraphqlResponse` | `{ data?: dynamic, errors?: list<gql.GraphqlError> }`, open |
+| `gql.GraphqlError` | `{ message: string, path?: list<string \| number>, extensions?: map<dynamic> }`, open |
+
+Both are open, because a server may answer with more than the client reads (`extensions`, above all).
+
+## The GqlClient port
+
+| | |
+| --- | --- |
+| id | `venn.port.gql-client` |
+| version | `1` |
+| requires | `net` |
+| methods | `execute`, `subscribe` |
+
+Two implementations ship with the package, as the port rule demands. `createFakeClient` replays
+canned envelopes; `createRealClient` is a placeholder that throws `VN8090` on every call, since no
+real transport is wired in this build. The conformance suite lives in
+`src/clients/gql-client.suite.ts` and the fake runs it today; the real client joins it the day it
+answers instead of throwing.
+
+`@venn-lang/stdlib` binds `createFakeClient()` with no configuration, so out of the box every call answers
+`{ data: {}, errors: undefined }`: `noGraphqlErrors` passes and field assertions have nothing to read.
+To assert on real data, bind a fake of your own:
+
+```ts
+import { createFakeClient, GqlClientPort, okGraphqlResponse } from "@venn-lang/graphql";
+
+const binding = {
+  port: GqlClientPort,
+  impl: createFakeClient({
+    responses: {
+      "{ me { id plan } }": okGraphqlResponse({ data: { me: { id: "u1", plan: "pro" } } }),
+    },
+  }),
+};
+```
+
+`responses` is keyed by the exact document text; `response` sets a single fallback for every query.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `gqlPlugin` (also the default export) | The `PluginDefinition`: namespace `gql`, `requires: ["net"]`, three actions, one matcher. |
+| `GqlClientPort` | The port descriptor actions resolve through `ctx.port(...)`. |
+| `createFakeClient({ response?, responses? })` | The test double. Returns the canned envelope for a query, or the fallback. |
+| `okGraphqlResponse(overrides?)` | `{ data: {}, errors: undefined }` merged with `overrides`. |
+| `createRealClient()` | The real client's slot. Every method throws `VN8090`. |
+| `graphqlResponseType` | The Zod schema of the envelope, registered as the plugin's `GraphqlResponse` type. |
+| `GqlClient`, `GqlRequest`, `GqlResponse`, `GqlError` | Types only. |
+
+## See also
+
+- [`@venn-lang/grpc`](../std-grpc), the same port pattern over gRPC.
+- [`@venn-lang/http`](../std-http), the HTTP verbs and the `Response` type.
+- [`@venn-lang/sdk`](../sdk), `defineAction` / `defineMatcher` / `definePlugin`.

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import { Port } from "@venn-lang/contracts";
+import { PluginDefinition, ZodType } from "@venn-lang/sdk";
+//#region src/port/gql-client.types.d.ts
+/** One operation to run: the document text, its variables and any bearer token. */
+interface GqlRequest {
+  query: string;
+  variables?: Record<string, unknown>;
+  auth?: string;
+}
+/** One entry of `errors`. `path` walks down `data` to the field that failed. */
+interface GqlError {
+  message: string;
+  path?: readonly (string | number)[];
+  extensions?: Record<string, unknown>;
+}
+/**
+ * The `{ data, errors }` envelope, and what `res` holds after a gql verb.
+ *
+ * GraphQL answers 200 with errors inside, so a failed operation arrives here and
+ * not as a thrown error. `expect res noGraphqlErrors` is how a flow checks.
+ */
+interface GqlResponse {
+  data?: unknown;
+  errors?: readonly GqlError[];
+}
+/**
+ * Running one GraphQL operation against an endpoint.
+ *
+ * `execute` and `subscribe` are separate methods because the transports differ,
+ * even though both answer with the same envelope.
+ *
+ * Two implementations: `createRealClient` and `createFakeClient`.
+ */
+interface GqlClient {
+  execute(req: GqlRequest): Promise<GqlResponse>;
+  subscribe(req: GqlRequest): Promise<GqlResponse>;
+}
+//#endregion
+//#region src/port/gql-client.port.d.ts
+/**
+ * The port descriptor every `gql` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot reach an endpoint refuses
+ * the binding at load time with a readable diagnostic.
+ */
+declare const GqlClientPort: Port<GqlClient>;
+//#endregion
+//#region src/clients/fake-client.d.ts
+/**
+ * A successful envelope: an empty `data` object and no `errors`.
+ *
+ * @param overrides Fields to replace on the default envelope.
+ * @returns A complete {@link GqlResponse}.
+ */
+declare function okGraphqlResponse(overrides?: Partial<GqlResponse>): GqlResponse;
+/**
+ * The double: canned envelopes, and no endpoint.
+ *
+ * A document with no entry in `responses` falls back to `response`, so a test
+ * only names the documents it cares about. `execute` and `subscribe` resolve
+ * from the same table.
+ *
+ * @param args.responses Envelopes keyed by the exact document text.
+ * @param args.response What every other document gets. Defaults to
+ *   {@link okGraphqlResponse}.
+ */
+declare function createFakeClient(args?: {
+  response?: GqlResponse;
+  responses?: Record<string, GqlResponse>;
+}): GqlClient;
+//#endregion
+//#region src/clients/real-client.d.ts
+/**
+ * The real GraphQL client. Not implemented in this build.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+declare function createRealClient(): GqlClient;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `gql` namespace: `query`, `mutate`, `subscribe`, the `noGraphqlErrors`
+ * matcher and the `gql.GraphqlResponse` type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow.
+ */
+declare const gqlPlugin: PluginDefinition;
+//#endregion
+//#region src/schema/graphql-response.d.ts
+/**
+ * Runtime validation for `gql.GraphqlResponse`, registered on the plugin.
+ *
+ * Pairs with `gqlTypeDefs.GraphqlResponse`, which tells the checker the same
+ * shape: this one guards a value, that one types an expression.
+ */
+declare const graphqlResponseType: ZodType;
+//#endregion
+export { type GqlClient, GqlClientPort, type GqlError, type GqlRequest, type GqlResponse, createFakeClient, createRealClient, gqlPlugin as default, gqlPlugin, graphqlResponseType, okGraphqlResponse };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/port/gql-client.types.ts","../src/port/gql-client.port.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/plugin.ts","../src/schema/graphql-response.ts"],"mappings":";;;;UACiB;EACf;EACA,YAAY;EACZ;;;UAIe;EACf;EACA;EACA,aAAa;;;;;;;;UASE;EACf;EACA,kBAAkB;;;;;;;;;;UAWH;EACf,QAAQ,KAAK,aAAa,QAAQ;EAClC,UAAU,KAAK,aAAa,QAAQ;;;;;;;;;;cC1BzB,eAAe,KAAK;;;;;;;;;iBCDjB,kBAAkB,YAAW,QAAQ,eAAoB;;;;;;;;;;;;iBAezD,iBACd;EAAQ,WAAW;EAAa,YAAY,eAAe;IAC1D;;;;;;;;;;;iBCda,oBAAoB;;;;;;;;;;cCEvB,WAAW;;;;;;;;;cCLX,qBAAqB"}

package/dist/index.js

@@ -0,0 +1,226 @@
+import { VennError } from "@venn-lang/contracts";
+import { arg, defineAction, defineMatcher, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/clients/fake-client.ts
+/**
+* A successful envelope: an empty `data` object and no `errors`.
+*
+* @param overrides Fields to replace on the default envelope.
+* @returns A complete {@link GqlResponse}.
+*/
+function okGraphqlResponse(overrides = {}) {
+	return {
+		data: {},
+		errors: void 0,
+		...overrides
+	};
+}
+/**
+* The double: canned envelopes, and no endpoint.
+*
+* A document with no entry in `responses` falls back to `response`, so a test
+* only names the documents it cares about. `execute` and `subscribe` resolve
+* from the same table.
+*
+* @param args.responses Envelopes keyed by the exact document text.
+* @param args.response What every other document gets. Defaults to
+*   {@link okGraphqlResponse}.
+*/
+function createFakeClient(args = {}) {
+	const responses = args.responses ?? {};
+	const fallback = args.response ?? okGraphqlResponse();
+	const resolve = (req) => responses[req.query] ?? fallback;
+	return {
+		execute: async (req) => resolve(req),
+		subscribe: async (req) => resolve(req)
+	};
+}
+//#endregion
+//#region src/clients/real-client.ts
+/**
+* The real GraphQL client. Not implemented in this build.
+*
+* It exists so the port has its second implementation and the failure is a named
+* Venn error rather than a missing method.
+*
+* @throws VN8090 from every method.
+*/
+function createRealClient() {
+	return {
+		async execute() {
+			return unimplemented();
+		},
+		async subscribe() {
+			return unimplemented();
+		}
+	};
+}
+function unimplemented() {
+	throw new VennError({
+		code: "VN8090",
+		message: "GraphQL real client not implemented in this build"
+	});
+}
+//#endregion
+//#region src/port/gql-client.port.ts
+/**
+* The port descriptor every `gql` verb resolves through `ctx.port(...)`.
+*
+* Declares the `net` capability, so a host that cannot reach an endpoint refuses
+* the binding at load time with a readable diagnostic.
+*/
+const GqlClientPort = {
+	id: "venn.port.gql-client",
+	version: 1,
+	requires: ["net"],
+	methods: ["execute", "subscribe"]
+};
+//#endregion
+//#region src/actions/gql-action.ts
+const paramsSchema = z.object({
+	variables: z.record(z.string(), z.unknown()).optional(),
+	auth: z.string().optional()
+});
+/**
+* Build one gql verb.
+*
+* The document is the single positional argument and everything else rides the
+* options map. All three verbs return the same envelope, `subscribe` included,
+* so a flow reads one shape whatever it asked for.
+*
+* @param config.name The verb as a flow writes it, such as `query`.
+* @param config.transport Which {@link GqlClient} method carries it.
+*/
+function gqlAction(config) {
+	return defineAction({
+		name: config.name,
+		doc: `GraphQL ${config.name} operation.`,
+		params: paramsSchema.optional(),
+		args: [arg("document", t.string, "The query, mutation or subscription text.")],
+		result: t.ref("gql.GraphqlResponse"),
+		run: (ctx, input) => dispatch({
+			client: ctx.port(GqlClientPort),
+			transport: config.transport,
+			input
+		})
+	});
+}
+function dispatch(args) {
+	const request = buildRequest(args.input);
+	return args.transport === "subscribe" ? args.client.subscribe(request) : args.client.execute(request);
+}
+function buildRequest(input) {
+	const params = input.params ?? {};
+	return {
+		query: String(input.args[0] ?? ""),
+		variables: params.variables,
+		auth: params.auth
+	};
+}
+//#endregion
+//#region src/actions/index.ts
+/** The gql namespace's verbs. Adding one is a single line here. */
+const gqlActions = [
+	gqlAction({
+		name: "query",
+		transport: "execute"
+	}),
+	gqlAction({
+		name: "mutate",
+		transport: "execute"
+	}),
+	gqlAction({
+		name: "subscribe",
+		transport: "subscribe"
+	})
+];
+//#endregion
+//#region src/matchers/no-graphql-errors.ts
+/**
+* `expect res noGraphqlErrors`: passes when `errors` is absent or empty.
+*
+* GraphQL reports failures inside a 200 response, so this is the check that
+* `expect res status 200` cannot make.
+*/
+const noGraphqlErrors = defineMatcher({
+	name: "noGraphqlErrors",
+	appliesTo: "GraphqlResponse",
+	test: ({ subject }) => isEmpty(subject.errors),
+	message: () => "expected the GraphQL response to carry no errors"
+});
+function isEmpty(errors) {
+	if (errors === void 0 || errors === null) return true;
+	return Array.isArray(errors) && errors.length === 0;
+}
+//#endregion
+//#region src/matchers/index.ts
+const gqlMatchers = [noGraphqlErrors];
+//#endregion
+//#region src/schema/graphql-response.ts
+/**
+* Runtime validation for `gql.GraphqlResponse`, registered on the plugin.
+*
+* Pairs with `gqlTypeDefs.GraphqlResponse`, which tells the checker the same
+* shape: this one guards a value, that one types an expression.
+*/
+const graphqlResponseType = z.object({
+	data: z.unknown().optional(),
+	errors: z.array(z.unknown()).optional()
+});
+//#endregion
+//#region src/types.ts
+/**
+* The types the plugin publishes to flows: `gql.GraphqlResponse` and
+* `gql.GraphqlError`.
+*
+* They mirror `port/gql-client.types.ts` by hand, under the names the rest of
+* the plugin already answers to: `noGraphqlErrors` applies to `GraphqlResponse`,
+* so the type a flow reaches for is the same word.
+*/
+const gqlTypeDefs = {
+	/**
+	* The `{ data, errors }` envelope every gql verb gives back.
+	*
+	* Open, because a server may answer with more than the two entries the client
+	* reads, `extensions` above all.
+	*/
+	GraphqlResponse: t.record({
+		data: t.dynamic,
+		errors: t.list(t.ref("gql.GraphqlError"))
+	}, {
+		optional: ["data", "errors"],
+		open: true
+	}),
+	/** One entry of `errors`. `path` walks down `data` to the field that failed. */
+	GraphqlError: t.record({
+		message: t.string,
+		path: t.list(t.union(t.string, t.number)),
+		extensions: t.map(t.dynamic)
+	}, {
+		optional: ["path", "extensions"],
+		open: true
+	})
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* The `gql` namespace: `query`, `mutate`, `subscribe`, the `noGraphqlErrors`
+* matcher and the `gql.GraphqlResponse` type.
+*
+* Requires the `net` capability, so a host without it refuses the plugin at load
+* time rather than failing mid-flow.
+*/
+const gqlPlugin = definePlugin({
+	name: "venn/graphql",
+	version: "0.0.0",
+	namespace: "gql",
+	requires: ["net"],
+	actions: gqlActions,
+	matchers: gqlMatchers,
+	types: { GraphqlResponse: graphqlResponseType },
+	typeDefs: gqlTypeDefs
+});
+//#endregion
+export { GqlClientPort, createFakeClient, createRealClient, gqlPlugin as default, gqlPlugin, graphqlResponseType, okGraphqlResponse };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/port/gql-client.port.ts","../src/actions/gql-action.ts","../src/actions/index.ts","../src/matchers/no-graphql-errors.ts","../src/matchers/index.ts","../src/schema/graphql-response.ts","../src/types.ts","../src/plugin.ts"],"sourcesContent":["import type { GqlClient, GqlRequest, GqlResponse } from \"../port/index.js\";\n\n/**\n * A successful envelope: an empty `data` object and no `errors`.\n *\n * @param overrides Fields to replace on the default envelope.\n * @returns A complete {@link GqlResponse}.\n */\nexport function okGraphqlResponse(overrides: Partial<GqlResponse> = {}): GqlResponse {\n  return { data: {}, errors: undefined, ...overrides };\n}\n\n/**\n * The double: canned envelopes, and no endpoint.\n *\n * A document with no entry in `responses` falls back to `response`, so a test\n * only names the documents it cares about. `execute` and `subscribe` resolve\n * from the same table.\n *\n * @param args.responses Envelopes keyed by the exact document text.\n * @param args.response What every other document gets. Defaults to\n *   {@link okGraphqlResponse}.\n */\nexport function createFakeClient(\n  args: { response?: GqlResponse; responses?: Record<string, GqlResponse> } = {},\n): GqlClient {\n  const responses = args.responses ?? {};\n  const fallback = args.response ?? okGraphqlResponse();\n  const resolve = (req: GqlRequest): GqlResponse => responses[req.query] ?? fallback;\n  return {\n    execute: async (req) => resolve(req),\n    subscribe: async (req) => resolve(req),\n  };\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { GqlClient } from \"../port/index.js\";\n\n/**\n * The real GraphQL client. Not implemented in this build.\n *\n * It exists so the port has its second implementation and the failure is a named\n * Venn error rather than a missing method.\n *\n * @throws VN8090 from every method.\n */\nexport function createRealClient(): GqlClient {\n  return {\n    async execute() {\n      return unimplemented();\n    },\n    async subscribe() {\n      return unimplemented();\n    },\n  };\n}\n\nfunction unimplemented(): never {\n  throw new VennError({\n    code: \"VN8090\",\n    message: \"GraphQL real client not implemented in this build\",\n  });\n}\n","import type { Port } from \"@venn-lang/contracts\";\nimport type { GqlClient } from \"./gql-client.types.js\";\n\n/**\n * The port descriptor every `gql` verb resolves through `ctx.port(...)`.\n *\n * Declares the `net` capability, so a host that cannot reach an endpoint refuses\n * the binding at load time with a readable diagnostic.\n */\nexport const GqlClientPort: Port<GqlClient> = {\n  id: \"venn.port.gql-client\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"execute\", \"subscribe\"],\n};\n","import { type ActionDefinition, type ActionInput, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { type GqlClient, GqlClientPort, type GqlRequest } from \"../port/index.js\";\n\nconst paramsSchema = z.object({\n  variables: z.record(z.string(), z.unknown()).optional(),\n  auth: z.string().optional(),\n});\n\n/** Which port method a verb rides. `query` and `mutate` execute; `subscribe` streams. */\ntype GqlTransport = \"execute\" | \"subscribe\";\n\n/**\n * Build one gql verb.\n *\n * The document is the single positional argument and everything else rides the\n * options map. All three verbs return the same envelope, `subscribe` included,\n * so a flow reads one shape whatever it asked for.\n *\n * @param config.name The verb as a flow writes it, such as `query`.\n * @param config.transport Which {@link GqlClient} method carries it.\n */\nexport function gqlAction(config: { name: string; transport: GqlTransport }): ActionDefinition {\n  return defineAction({\n    name: config.name,\n    doc: `GraphQL ${config.name} operation.`,\n    params: paramsSchema.optional(),\n    args: [arg(\"document\", t.string, \"The query, mutation or subscription text.\")],\n    result: t.ref(\"gql.GraphqlResponse\"),\n    run: (ctx, input) =>\n      dispatch({ client: ctx.port(GqlClientPort), transport: config.transport, input }),\n  });\n}\n\nfunction dispatch(args: {\n  client: GqlClient;\n  transport: GqlTransport;\n  input: ActionInput<unknown>;\n}): Promise<unknown> {\n  const request = buildRequest(args.input);\n  return args.transport === \"subscribe\"\n    ? args.client.subscribe(request)\n    : args.client.execute(request);\n}\n\nfunction buildRequest(input: ActionInput<unknown>): GqlRequest {\n  const params = (input.params ?? {}) as { variables?: Record<string, unknown>; auth?: string };\n  return { query: String(input.args[0] ?? \"\"), variables: params.variables, auth: params.auth };\n}\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { gqlAction } from \"./gql-action.js\";\n\n/** The gql namespace's verbs. Adding one is a single line here. */\nexport const gqlActions: ActionDefinition[] = [\n  gqlAction({ name: \"query\", transport: \"execute\" }),\n  gqlAction({ name: \"mutate\", transport: \"execute\" }),\n  gqlAction({ name: \"subscribe\", transport: \"subscribe\" }),\n];\n","import { defineMatcher, type MatcherDefinition } from \"@venn-lang/sdk\";\n\n/**\n * `expect res noGraphqlErrors`: passes when `errors` is absent or empty.\n *\n * GraphQL reports failures inside a 200 response, so this is the check that\n * `expect res status 200` cannot make.\n */\nexport const noGraphqlErrors: MatcherDefinition = defineMatcher({\n  name: \"noGraphqlErrors\",\n  appliesTo: \"GraphqlResponse\",\n  test: ({ subject }) => isEmpty((subject as { errors?: unknown }).errors),\n  message: () => \"expected the GraphQL response to carry no errors\",\n});\n\nfunction isEmpty(errors: unknown): boolean {\n  if (errors === undefined || errors === null) return true;\n  return Array.isArray(errors) && errors.length === 0;\n}\n","import type { MatcherDefinition } from \"@venn-lang/sdk\";\nimport { noGraphqlErrors } from \"./no-graphql-errors.js\";\n\nexport const gqlMatchers: MatcherDefinition[] = [noGraphqlErrors];\n","import { type ZodType, z } from \"@venn-lang/sdk\";\n\n/**\n * Runtime validation for `gql.GraphqlResponse`, registered on the plugin.\n *\n * Pairs with `gqlTypeDefs.GraphqlResponse`, which tells the checker the same\n * shape: this one guards a value, that one types an expression.\n */\nexport const graphqlResponseType: ZodType = z.object({\n  data: z.unknown().optional(),\n  errors: z.array(z.unknown()).optional(),\n});\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types the plugin publishes to flows: `gql.GraphqlResponse` and\n * `gql.GraphqlError`.\n *\n * They mirror `port/gql-client.types.ts` by hand, under the names the rest of\n * the plugin already answers to: `noGraphqlErrors` applies to `GraphqlResponse`,\n * so the type a flow reaches for is the same word.\n */\nexport const gqlTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /**\n   * The `{ data, errors }` envelope every gql verb gives back.\n   *\n   * Open, because a server may answer with more than the two entries the client\n   * reads, `extensions` above all.\n   */\n  GraphqlResponse: t.record(\n    { data: t.dynamic, errors: t.list(t.ref(\"gql.GraphqlError\")) },\n    { optional: [\"data\", \"errors\"], open: true },\n  ),\n  /** One entry of `errors`. `path` walks down `data` to the field that failed. */\n  GraphqlError: t.record(\n    {\n      message: t.string,\n      path: t.list(t.union(t.string, t.number)),\n      extensions: t.map(t.dynamic),\n    },\n    { optional: [\"path\", \"extensions\"], open: true },\n  ),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { gqlActions } from \"./actions/index.js\";\nimport { gqlMatchers } from \"./matchers/index.js\";\nimport { graphqlResponseType } from \"./schema/index.js\";\nimport { gqlTypeDefs } from \"./types.js\";\n\n/**\n * The `gql` namespace: `query`, `mutate`, `subscribe`, the `noGraphqlErrors`\n * matcher and the `gql.GraphqlResponse` type.\n *\n * Requires the `net` capability, so a host without it refuses the plugin at load\n * time rather than failing mid-flow.\n */\nexport const gqlPlugin: PluginDefinition = definePlugin({\n  name: \"venn/graphql\",\n  version: \"0.0.0\",\n  namespace: \"gql\",\n  requires: [\"net\"],\n  actions: gqlActions,\n  matchers: gqlMatchers,\n  types: { GraphqlResponse: graphqlResponseType },\n  typeDefs: gqlTypeDefs,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/graphql",
+  "version": "0.1.0",
+  "description": "The gql namespace: GraphQL queries, mutations and subscriptions as Venn verbs.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "graphql"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-graphql#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-graphql"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/types": "0.1.0",
+    "@venn-lang/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/gql-action.ts

@@ -0,0 +1,49 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { type GqlClient, GqlClientPort, type GqlRequest } from "../port/index.js";
+
+const paramsSchema = z.object({
+  variables: z.record(z.string(), z.unknown()).optional(),
+  auth: z.string().optional(),
+});
+
+/** Which port method a verb rides. `query` and `mutate` execute; `subscribe` streams. */
+type GqlTransport = "execute" | "subscribe";
+
+/**
+ * Build one gql verb.
+ *
+ * The document is the single positional argument and everything else rides the
+ * options map. All three verbs return the same envelope, `subscribe` included,
+ * so a flow reads one shape whatever it asked for.
+ *
+ * @param config.name The verb as a flow writes it, such as `query`.
+ * @param config.transport Which {@link GqlClient} method carries it.
+ */
+export function gqlAction(config: { name: string; transport: GqlTransport }): ActionDefinition {
+  return defineAction({
+    name: config.name,
+    doc: `GraphQL ${config.name} operation.`,
+    params: paramsSchema.optional(),
+    args: [arg("document", t.string, "The query, mutation or subscription text.")],
+    result: t.ref("gql.GraphqlResponse"),
+    run: (ctx, input) =>
+      dispatch({ client: ctx.port(GqlClientPort), transport: config.transport, input }),
+  });
+}
+
+function dispatch(args: {
+  client: GqlClient;
+  transport: GqlTransport;
+  input: ActionInput<unknown>;
+}): Promise<unknown> {
+  const request = buildRequest(args.input);
+  return args.transport === "subscribe"
+    ? args.client.subscribe(request)
+    : args.client.execute(request);
+}
+
+function buildRequest(input: ActionInput<unknown>): GqlRequest {
+  const params = (input.params ?? {}) as { variables?: Record<string, unknown>; auth?: string };
+  return { query: String(input.args[0] ?? ""), variables: params.variables, auth: params.auth };
+}

package/src/actions/index.ts

@@ -0,0 +1,9 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { gqlAction } from "./gql-action.js";
+
+/** The gql namespace's verbs. Adding one is a single line here. */
+export const gqlActions: ActionDefinition[] = [
+  gqlAction({ name: "query", transport: "execute" }),
+  gqlAction({ name: "mutate", transport: "execute" }),
+  gqlAction({ name: "subscribe", transport: "subscribe" }),
+];

package/src/clients/fake-client.ts

@@ -0,0 +1,34 @@
+import type { GqlClient, GqlRequest, GqlResponse } from "../port/index.js";
+
+/**
+ * A successful envelope: an empty `data` object and no `errors`.
+ *
+ * @param overrides Fields to replace on the default envelope.
+ * @returns A complete {@link GqlResponse}.
+ */
+export function okGraphqlResponse(overrides: Partial<GqlResponse> = {}): GqlResponse {
+  return { data: {}, errors: undefined, ...overrides };
+}
+
+/**
+ * The double: canned envelopes, and no endpoint.
+ *
+ * A document with no entry in `responses` falls back to `response`, so a test
+ * only names the documents it cares about. `execute` and `subscribe` resolve
+ * from the same table.
+ *
+ * @param args.responses Envelopes keyed by the exact document text.
+ * @param args.response What every other document gets. Defaults to
+ *   {@link okGraphqlResponse}.
+ */
+export function createFakeClient(
+  args: { response?: GqlResponse; responses?: Record<string, GqlResponse> } = {},
+): GqlClient {
+  const responses = args.responses ?? {};
+  const fallback = args.response ?? okGraphqlResponse();
+  const resolve = (req: GqlRequest): GqlResponse => responses[req.query] ?? fallback;
+  return {
+    execute: async (req) => resolve(req),
+    subscribe: async (req) => resolve(req),
+  };
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeClient, okGraphqlResponse } from "./fake-client.js";
+export { createRealClient } from "./real-client.js";

package/src/clients/real-client.ts

@@ -0,0 +1,28 @@
+import { VennError } from "@venn-lang/contracts";
+import type { GqlClient } from "../port/index.js";
+
+/**
+ * The real GraphQL client. Not implemented in this build.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+export function createRealClient(): GqlClient {
+  return {
+    async execute() {
+      return unimplemented();
+    },
+    async subscribe() {
+      return unimplemented();
+    },
+  };
+}
+
+function unimplemented(): never {
+  throw new VennError({
+    code: "VN8090",
+    message: "GraphQL real client not implemented in this build",
+  });
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `gql` plugin: `query`, `mutate` and `subscribe`, plus the
+ * `noGraphqlErrors` matcher.
+ *
+ * All three verbs cross the `GqlClient` port and answer with the same
+ * `{ data, errors }` envelope, so a flow reads one shape whatever it asked for.
+ */
+
+export * from "./clients/index.js";
+export { gqlPlugin, gqlPlugin as default } from "./plugin.js";
+export * from "./port/index.js";
+export * from "./schema/index.js";

package/src/matchers/index.ts

@@ -0,0 +1,4 @@
+import type { MatcherDefinition } from "@venn-lang/sdk";
+import { noGraphqlErrors } from "./no-graphql-errors.js";
+
+export const gqlMatchers: MatcherDefinition[] = [noGraphqlErrors];

package/src/matchers/no-graphql-errors.ts

@@ -0,0 +1,19 @@
+import { defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+
+/**
+ * `expect res noGraphqlErrors`: passes when `errors` is absent or empty.
+ *
+ * GraphQL reports failures inside a 200 response, so this is the check that
+ * `expect res status 200` cannot make.
+ */
+export const noGraphqlErrors: MatcherDefinition = defineMatcher({
+  name: "noGraphqlErrors",
+  appliesTo: "GraphqlResponse",
+  test: ({ subject }) => isEmpty((subject as { errors?: unknown }).errors),
+  message: () => "expected the GraphQL response to carry no errors",
+});
+
+function isEmpty(errors: unknown): boolean {
+  if (errors === undefined || errors === null) return true;
+  return Array.isArray(errors) && errors.length === 0;
+}

package/src/plugin.ts

@@ -0,0 +1,23 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { gqlActions } from "./actions/index.js";
+import { gqlMatchers } from "./matchers/index.js";
+import { graphqlResponseType } from "./schema/index.js";
+import { gqlTypeDefs } from "./types.js";
+
+/**
+ * The `gql` namespace: `query`, `mutate`, `subscribe`, the `noGraphqlErrors`
+ * matcher and the `gql.GraphqlResponse` type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow.
+ */
+export const gqlPlugin: PluginDefinition = definePlugin({
+  name: "venn/graphql",
+  version: "0.0.0",
+  namespace: "gql",
+  requires: ["net"],
+  actions: gqlActions,
+  matchers: gqlMatchers,
+  types: { GraphqlResponse: graphqlResponseType },
+  typeDefs: gqlTypeDefs,
+});

package/src/port/gql-client.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "@venn-lang/contracts";
+import type { GqlClient } from "./gql-client.types.js";
+
+/**
+ * The port descriptor every `gql` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot reach an endpoint refuses
+ * the binding at load time with a readable diagnostic.
+ */
+export const GqlClientPort: Port<GqlClient> = {
+  id: "venn.port.gql-client",
+  version: 1,
+  requires: ["net"],
+  methods: ["execute", "subscribe"],
+};

package/src/port/gql-client.types.ts

@@ -0,0 +1,37 @@
+/** One operation to run: the document text, its variables and any bearer token. */
+export interface GqlRequest {
+  query: string;
+  variables?: Record<string, unknown>;
+  auth?: string;
+}
+
+/** One entry of `errors`. `path` walks down `data` to the field that failed. */
+export interface GqlError {
+  message: string;
+  path?: readonly (string | number)[];
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * The `{ data, errors }` envelope, and what `res` holds after a gql verb.
+ *
+ * GraphQL answers 200 with errors inside, so a failed operation arrives here and
+ * not as a thrown error. `expect res noGraphqlErrors` is how a flow checks.
+ */
+export interface GqlResponse {
+  data?: unknown;
+  errors?: readonly GqlError[];
+}
+
+/**
+ * Running one GraphQL operation against an endpoint.
+ *
+ * `execute` and `subscribe` are separate methods because the transports differ,
+ * even though both answer with the same envelope.
+ *
+ * Two implementations: `createRealClient` and `createFakeClient`.
+ */
+export interface GqlClient {
+  execute(req: GqlRequest): Promise<GqlResponse>;
+  subscribe(req: GqlRequest): Promise<GqlResponse>;
+}

package/src/port/index.ts

@@ -0,0 +1,2 @@
+export { GqlClientPort } from "./gql-client.port.js";
+export type { GqlClient, GqlError, GqlRequest, GqlResponse } from "./gql-client.types.js";

package/src/schema/graphql-response.ts

@@ -0,0 +1,12 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+
+/**
+ * Runtime validation for `gql.GraphqlResponse`, registered on the plugin.
+ *
+ * Pairs with `gqlTypeDefs.GraphqlResponse`, which tells the checker the same
+ * shape: this one guards a value, that one types an expression.
+ */
+export const graphqlResponseType: ZodType = z.object({
+  data: z.unknown().optional(),
+  errors: z.array(z.unknown()).optional(),
+});

package/src/schema/index.ts

@@ -0,0 +1 @@
+export { graphqlResponseType } from "./graphql-response.js";

package/src/types.ts

@@ -0,0 +1,31 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types the plugin publishes to flows: `gql.GraphqlResponse` and
+ * `gql.GraphqlError`.
+ *
+ * They mirror `port/gql-client.types.ts` by hand, under the names the rest of
+ * the plugin already answers to: `noGraphqlErrors` applies to `GraphqlResponse`,
+ * so the type a flow reaches for is the same word.
+ */
+export const gqlTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /**
+   * The `{ data, errors }` envelope every gql verb gives back.
+   *
+   * Open, because a server may answer with more than the two entries the client
+   * reads, `extensions` above all.
+   */
+  GraphqlResponse: t.record(
+    { data: t.dynamic, errors: t.list(t.ref("gql.GraphqlError")) },
+    { optional: ["data", "errors"], open: true },
+  ),
+  /** One entry of `errors`. `path` walks down `data` to the field that failed. */
+  GraphqlError: t.record(
+    {
+      message: t.string,
+      path: t.list(t.union(t.string, t.number)),
+      extensions: t.map(t.dynamic),
+    },
+    { optional: ["path", "extensions"], open: true },
+  ),
+};