hadars 0.2.2-rc.0 → 0.2.2-rc.2

package/README.md

@@ -19,30 +19,30 @@ Bring your own router (or none), keep your components as plain React, and get SS
 ## Benchmarks
 
 <!-- BENCHMARK_START -->
-> Last run: 2026-03-21 · 60s · 100 connections · Bun runtime
+> Last run: 2026-03-23 · 120s · 100 connections · Bun runtime
 > hadars is **8.7x faster** in requests/sec
 
-**Throughput** (autocannon, 60s)
+**Throughput** (autocannon, 120s)
 
 | Metric | hadars | Next.js |
 |---|---:|---:|
 | Requests/sec | **148** | 17 |
-| Latency median | **647 ms** | 2712 ms |
-| Latency p99 | **969 ms** | 6544 ms |
-| Throughput | **42.23** MB/s | 9.29 MB/s |
-| Peak RSS | 1062.8 MB | **472.3 MB** |
-| Avg RSS | 799.7 MB | **404.7 MB** |
+| Latency median | **639 ms** | 2754 ms |
+| Latency p99 | **976 ms** | 4040 ms |
+| Throughput | **42.23** MB/s | 9.49 MB/s |
+| Peak RSS | 987.9 MB | **476.9 MB** |
+| Avg RSS | 775.3 MB | **424.5 MB** |
 | Build time | 0.7 s | 6.0 s |
 
 **Page load** (Playwright · Chromium headless · median)
 
 | Metric | hadars | Next.js |
 |---|---:|---:|
-| TTFB | **20 ms** | 43 ms |
-| FCP | **100 ms** | 136 ms |
-| DOMContentLoaded | **41 ms** | 127 ms |
-| Load | **127 ms** | 174 ms |
-| Peak RSS | 444.7 MB | **284.9 MB** |
+| TTFB | **19 ms** | 46 ms |
+| FCP | **96 ms** | 140 ms |
+| DOMContentLoaded | **40 ms** | 128 ms |
+| Load | **124 ms** | 174 ms |
+| Peak RSS | 468.0 MB | **297.0 MB** |
 <!-- BENCHMARK_END -->
 
 ## Quick start
@@ -117,6 +117,9 @@ hadars run
 # Pre-render every page to static HTML files (output goes to out/ by default)
 hadars export static [outDir]
 
+# Write the inferred GraphQL schema to a SDL file (for graphql-codegen / gql.tada)
+hadars export schema [schema.graphql]
+
 # Bundle the app into a single self-contained Lambda .mjs file
 hadars export lambda [output.mjs]
 
@@ -355,6 +358,119 @@ For each node type (e.g. `BlogPost`) you get two root queries:
 
 All scalar fields are automatically added as optional lookup arguments, so you can do `blogPost(slug: "hello")` without knowing the hashed node id.
 
+### useGraphQL hook
+
+Query your GraphQL layer directly inside any component — no need to pass data down through `getInitProps`. The hook integrates with `useServerData` so queries are executed on the server during static export and hydrated on the client.
+
+```tsx
+import { useGraphQL } from 'hadars';
+import { GetAllPostsDocument } from './gql/graphql';
+
+const PostList = () => {
+    const result = useGraphQL(GetAllPostsDocument);
+    const posts = result?.data?.allBlogPost ?? [];
+    return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
+};
+```
+
+Pass variables as a second argument:
+
+```tsx
+const PostPage = ({ slug }: { slug: string }) => {
+    const result = useGraphQL(GetPostDocument, { slug });
+    const post = result?.data?.blogPost;
+    if (!post) return null;
+    return <h1>{post.title}</h1>;
+};
+```
+
+- `result` is `undefined` on the first SSR pass (data not yet resolved) — render `null` or a skeleton
+- When a typed `DocumentNode` from graphql-codegen is passed, the return type is fully inferred — `result.data` has the exact shape of your query
+- GraphQL errors throw during static export so the page is marked as failed rather than silently serving incomplete data
+- Requires `graphql` and a `sources` or `graphql` executor configured in `hadars.config.ts`
+
+### Schema export & type generation
+
+Run `hadars export schema` to write the inferred schema to a SDL file, then feed it to **graphql-codegen** to generate TypeScript types for your queries:
+
+```bash
+# 1. Generate schema.graphql from your sources
+hadars export schema
+
+# 2. Install codegen (one-time)
+npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations
+
+# 3. Generate types
+npx graphql-codegen --schema schema.graphql --documents "src/**/*.tsx" --out src/gql/
+```
+
+Or use a `codegen.ts` config file:
+
+```ts
+// codegen.ts
+import type { CodegenConfig } from '@graphql-codegen/cli';
+
+const config: CodegenConfig = {
+    schema: 'schema.graphql',
+    documents: ['src/**/*.tsx'],
+    generates: {
+        'src/gql/': {
+            preset: 'client',
+        },
+    },
+};
+
+export default config;
+```
+
+`hadars export schema` also works with a custom `graphql` executor — it runs an introspection query against it and converts the result to SDL.
+
+### GraphQL fragments
+
+graphql-codegen's `client` preset generates fragment masking helpers (`FragmentType`, `useFragment`, `makeFragmentData`) that let components co-locate their exact data requirements. No hadars changes are needed — just define your fragment with `graphql()` and accept a masked prop:
+
+```tsx
+// src/PostCard.tsx
+import { graphql, useFragment, type FragmentType } from './gql';
+
+export const PostCardFragment = graphql(`
+    fragment PostCard on BlogPost {
+        slug
+        title
+        date
+    }
+`);
+
+interface Props {
+    post: FragmentType<typeof PostCardFragment>;
+}
+
+const PostCard = ({ post: postRef }: Props) => {
+    const post = useFragment(PostCardFragment, postRef);
+    return (
+        <article>
+            <h2>{post.title}</h2>
+            <time>{post.date}</time>
+        </article>
+    );
+};
+```
+
+The parent component spreads the raw node into the masked prop — TypeScript ensures it satisfies the fragment shape:
+
+```tsx
+const PostList = () => {
+    const result = useGraphQL(GetAllPostsDocument);
+    return (
+        <>
+            {result?.data?.allBlogPost.map(post => (
+                <PostCard key={post.slug} post={post} />
+            ))}
+        </>
+    );
+};
+```
+
 ### Custom GraphQL executor
 
 Skip `sources` and provide a `graphql` executor directly for full control over resolvers:

package/cli-lib.ts

@@ -6,7 +6,7 @@ import * as Hadars from './src/build'
 import type { HadarsOptions, HadarsEntryModule } from './src/types/hadars'
 import { renderStaticSite } from './src/static'
 import { runSources } from './src/source/runner'
-import { buildSchemaExecutor } from './src/source/inference'
+import { buildSchemaExecutor, buildSchemaSDL, introspectExecutorSDL } from './src/source/inference'
 
 const SUPPORTED = ['hadars.config.js', 'hadars.config.mjs', 'hadars.config.cjs', 'hadars.config.ts']
 
@@ -46,6 +46,53 @@ async function loadConfig(configPath: string): Promise<HadarsOptions> {
   return (mod && (mod.default ?? mod)) as HadarsOptions
 }
 
+// ── hadars export schema ─────────────────────────────────────────────────────
+
+async function exportSchema(
+    config: HadarsOptions,
+    outputFile: string,
+): Promise<void> {
+    let sdl: string | null = null
+
+    if (config.sources && config.sources.length > 0) {
+        console.log(`Running ${config.sources.length} source plugin(s)...`)
+        const store = await runSources(config.sources)
+        console.log(`Schema inferred for types: ${store.getTypes().join(', ') || '(none)'}`)
+        sdl = await buildSchemaSDL(store)
+        if (!sdl) {
+            console.error(
+                'Error: `graphql` package not found.\n' +
+                'Source plugins require graphql-js to be installed:\n\n' +
+                '  npm install graphql\n',
+            )
+            process.exit(1)
+        }
+    } else if (config.graphql) {
+        console.log('Introspecting custom GraphQL executor...')
+        sdl = await introspectExecutorSDL(config.graphql)
+        if (!sdl) {
+            console.error(
+                'Error: `graphql` package not found.\n' +
+                'Schema export requires graphql-js to be installed:\n\n' +
+                '  npm install graphql\n',
+            )
+            process.exit(1)
+        }
+    } else {
+        console.error(
+            'Error: no GraphQL source configured.\n' +
+            'Add `sources` or a `graphql` executor to your hadars.config.ts first.\n',
+        )
+        process.exit(1)
+    }
+
+    await writeFile(outputFile, sdl, 'utf-8')
+    console.log(`Schema written to ${outputFile}`)
+    console.log(`\nNext steps — generate TypeScript types with graphql-codegen:`)
+    console.log(`  npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations`)
+    console.log(`  npx graphql-codegen --schema ${outputFile} --documents "src/**/*.tsx" --out src/gql/`)
+}
+
 // ── hadars export static ─────────────────────────────────────────────────────
 
 async function exportStatic(
@@ -548,7 +595,7 @@ Done! Next steps:
 // ── CLI entry ─────────────────────────────────────────────────────────────────
 
 function usage(): void {
-  console.log('Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs] | export cloudflare [output.mjs] | export static [outDir]>')
+  console.log('Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs] | export cloudflare [output.mjs] | export static [outDir] | export schema [schema.graphql]>')
 }
 
 export async function runCli(argv: string[], cwd = process.cwd()): Promise<void> {
@@ -608,8 +655,12 @@ export async function runCli(argv: string[], cwd = process.cwd()): Promise<void>
                 const outDirArg = argv[4] ?? 'out'
                 await exportStatic(cfg, outDirArg, cwd)
                 process.exit(0)
+            } else if (subCmd === 'schema') {
+                const outputFile = resolve(cwd, argv[4] ?? 'schema.graphql')
+                await exportSchema(cfg, outputFile)
+                process.exit(0)
             } else {
-                console.error(`Unknown export target: ${subCmd ?? '(none)'}. Supported: lambda, cloudflare, static`)
+                console.error(`Unknown export target: ${subCmd ?? '(none)'}. Supported: lambda, cloudflare, static, schema`)
                 process.exit(1)
             }
         }

package/dist/cli.js

@@ -1905,6 +1905,8 @@ var NodeStore = class {
   byId = /* @__PURE__ */ new Map();
   byType = /* @__PURE__ */ new Map();
   createNode(node) {
+    if (!node.id) throw new Error("[hadars] createNode: node.id must be a non-empty string");
+    if (!node.internal?.type) throw new Error("[hadars] createNode: node.internal.type must be a non-empty string");
     this.byId.set(node.id, node);
     const list = this.byType.get(node.internal.type) ?? [];
     const idx = list.findIndex((n) => n.id === node.id);
@@ -1966,6 +1968,7 @@ function makeGatsbyContext(store, pluginName, pluginOptions = {}, emitter = new
   const actions = {
     createNode: (node) => store.createNode(node),
     deleteNode: ({ id }) => {
+      console.warn(`[${pluginName}] deleteNode("${id}") called but is not supported by hadars \u2014 node will remain in the store.`);
     },
     touchNode: () => {
     }
@@ -1995,6 +1998,7 @@ function makeGatsbyContext(store, pluginName, pluginOptions = {}, emitter = new
 // src/source/runner.ts
 var SETTLE_IDLE_MS = 300;
 var SETTLE_TIMEOUT_MS = 1e4;
+var SOURCE_NODES_TIMEOUT_MS = 3e4;
 function waitForSettle(getLastNodeTime) {
   return new Promise((resolve2) => {
     const deadline = Date.now() + SETTLE_TIMEOUT_MS;
@@ -2003,10 +2007,19 @@ function waitForSettle(getLastNodeTime) {
       if (idle >= SETTLE_IDLE_MS || Date.now() >= deadline) {
         resolve2();
       } else {
-        setTimeout(check, 50);
+        const t2 = setTimeout(check, 50);
+        t2.unref?.();
       }
     };
-    setTimeout(check, SETTLE_IDLE_MS);
+    const t = setTimeout(check, SETTLE_IDLE_MS);
+    t.unref?.();
+  });
+}
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve2, reject) => {
+    const t = setTimeout(() => reject(new Error(`[hadars] "${label}" timed out after ${ms}ms`)), ms);
+    t.unref?.();
+    promise.then(resolve2, reject).finally(() => clearTimeout(t));
   });
 }
 async function runSources(sources) {
@@ -2047,11 +2060,18 @@ async function runSources(sources) {
     const emitter = new EventEmitter2();
     const ctx = makeGatsbyContext(trackingStore, pluginName, options, emitter);
     try {
-      await mod.sourceNodes(ctx, options);
+      await withTimeout(
+        Promise.resolve(mod.sourceNodes(ctx, options)),
+        SOURCE_NODES_TIMEOUT_MS,
+        `${pluginName} sourceNodes`
+      );
     } catch (err) {
-      throw new Error(
-        `[hadars] source plugin "${pluginName}" threw during sourceNodes: ${err.message}`
+      const cause = err instanceof Error ? err : new Error(String(err));
+      const wrapped = new Error(
+        `[hadars] source plugin "${pluginName}" threw during sourceNodes: ${cause.message}`
       );
+      wrapped.cause = cause;
+      throw wrapped;
     }
     await waitForSettle(() => lastNodeTime);
     emitter.emit("BOOTSTRAP_FINISHED");
@@ -2080,12 +2100,13 @@ function inferFieldShape(value, seenTypes) {
   return { type: inferScalar(value), nullable: true };
 }
 var INTERNAL_FIELDS = /* @__PURE__ */ new Set(["id", "internal", "__typename", "parent", "children"]);
+var isReservedFieldName = (name) => name.startsWith("__");
 var FILTERABLE_SCALARS = /* @__PURE__ */ new Set(["String", "Int", "Float", "Boolean", "ID"]);
 function buildTypeFields(nodes) {
   const fieldMap = /* @__PURE__ */ new Map();
   for (const node of nodes) {
     for (const [key, val] of Object.entries(node)) {
-      if (INTERNAL_FIELDS.has(key)) continue;
+      if (INTERNAL_FIELDS.has(key) || isReservedFieldName(key)) continue;
       if (fieldMap.has(key)) continue;
       const { type } = inferFieldShape(val, /* @__PURE__ */ new Set());
       fieldMap.set(key, {
@@ -2117,7 +2138,7 @@ function buildSingleArgs(fields) {
   ];
   return args.join(", ");
 }
-async function buildSchemaExecutor(store) {
+async function loadAndBuildSchema(store) {
   let gql;
   try {
     const { createRequire: createRequire2 } = await import("node:module");
@@ -2127,11 +2148,11 @@ async function buildSchemaExecutor(store) {
   } catch {
     return null;
   }
-  const { buildSchema, graphql } = gql;
+  const { buildSchema, printSchema, print } = gql;
   const types = store.getTypes();
   if (types.length === 0) {
-    const schema2 = buildSchema("type Query { _empty: String }");
-    return (query, variables) => graphql({ schema: schema2, source: query, variableValues: variables });
+    const rawSdl2 = "type Query { _empty: String }";
+    return { schema: buildSchema(rawSdl2), sdl: rawSdl2, gql };
   }
   const typeFields = new Map(
     types.map((typeName) => {
@@ -2150,7 +2171,7 @@ async function buildSchemaExecutor(store) {
       `  ${all}: [${typeName}!]!`
     ].join("\n");
   });
-  const sdl = [
+  const rawSdl = [
     ...typeSDLs,
     `type Query {
 ${queryFields.join("\n")}
@@ -2158,10 +2179,24 @@ ${queryFields.join("\n")}
   ].join("\n\n");
   let schema;
   try {
-    schema = buildSchema(sdl);
+    schema = buildSchema(rawSdl);
   } catch (err) {
     throw new Error(`[hadars] Failed to build GraphQL schema from node store: ${err.message}`);
   }
+  return { schema, sdl: printSchema(schema), gql };
+}
+function toQueryString(query, print) {
+  return typeof query === "string" ? query : print(query);
+}
+async function buildSchemaExecutor(store) {
+  const built = await loadAndBuildSchema(store);
+  if (!built) return null;
+  const { schema, gql } = built;
+  const { graphql, print } = gql;
+  const types = store.getTypes();
+  if (types.length === 0) {
+    return (query, variables) => graphql({ schema, source: toQueryString(query, print), variableValues: variables });
+  }
   const rootValue = {};
   for (const typeName of types) {
     const { single, all } = queryNames(typeName);
@@ -2173,7 +2208,31 @@ ${queryFields.join("\n")}
       ) ?? null;
     };
   }
-  return (query, variables) => graphql({ schema, rootValue, source: query, variableValues: variables });
+  return (query, variables) => graphql({ schema, rootValue, source: toQueryString(query, print), variableValues: variables });
+}
+async function buildSchemaSDL(store) {
+  const built = await loadAndBuildSchema(store);
+  return built?.sdl ?? null;
+}
+async function introspectExecutorSDL(executor) {
+  let gql;
+  try {
+    const { createRequire: createRequire2 } = await import("node:module");
+    const projectRequire = createRequire2(process.cwd() + "/package.json");
+    const graphqlPath = projectRequire.resolve("graphql");
+    gql = await import(graphqlPath);
+  } catch {
+    return null;
+  }
+  const { getIntrospectionQuery, buildClientSchema, printSchema } = gql;
+  const result = await executor(getIntrospectionQuery());
+  if (result.errors?.length) {
+    throw new Error(`[hadars] Introspection failed: ${result.errors[0].message}`);
+  }
+  if (!result.data) {
+    throw new Error("[hadars] Introspection returned no data");
+  }
+  return printSchema(buildClientSchema(result.data));
 }
 
 // src/source/graphiql.ts
@@ -2208,7 +2267,12 @@ var GRAPHIQL_HTML = `<!doctype html>
 </html>`;
 function createGraphiqlHandler(executor) {
   return async (req) => {
-    const url = new URL(req.url);
+    let url;
+    try {
+      url = new URL(req.url);
+    } catch {
+      return void 0;
+    }
     if (url.pathname !== GRAPHQL_PATH) return void 0;
     if (req.method === "GET") {
       return new Response(GRAPHIQL_HTML, {
@@ -2225,8 +2289,8 @@ function createGraphiqlHandler(executor) {
           headers: { "Content-Type": "application/json" }
         });
       }
-      if (!body.query) {
-        return new Response(JSON.stringify({ errors: [{ message: 'Missing "query" field' }] }), {
+      if (typeof body.query !== "string" || !body.query.trim()) {
+        return new Response(JSON.stringify({ errors: [{ message: 'Missing or invalid "query" field \u2014 must be a non-empty string' }] }), {
           status: 400,
           headers: { "Content-Type": "application/json" }
         });
@@ -2659,6 +2723,7 @@ var dev = async (options) => {
         getInitProps,
         getFinalProps
       } = await import(importPath);
+      globalThis.__hadarsGraphQL = devStaticCtx?.graphql;
       const { head, status, getAppBody, finalize } = await getReactResponse(request, {
         document: {
           body: Component,
@@ -2864,6 +2929,7 @@ async function renderStaticSite(opts) {
   for (const urlPath of paths) {
     try {
       const req = parseRequest(new Request("http://localhost" + urlPath));
+      globalThis.__hadarsGraphQL = staticCtx.graphql;
       const { head, getAppBody, finalize } = await getReactResponse(req, {
         document: {
           body: ssrModule.default,
@@ -2937,6 +3003,41 @@ async function loadConfig(configPath) {
   const mod = await import(url);
   return mod && (mod.default ?? mod);
 }
+async function exportSchema(config, outputFile) {
+  let sdl = null;
+  if (config.sources && config.sources.length > 0) {
+    console.log(`Running ${config.sources.length} source plugin(s)...`);
+    const store = await runSources(config.sources);
+    console.log(`Schema inferred for types: ${store.getTypes().join(", ") || "(none)"}`);
+    sdl = await buildSchemaSDL(store);
+    if (!sdl) {
+      console.error(
+        "Error: `graphql` package not found.\nSource plugins require graphql-js to be installed:\n\n  npm install graphql\n"
+      );
+      process.exit(1);
+    }
+  } else if (config.graphql) {
+    console.log("Introspecting custom GraphQL executor...");
+    sdl = await introspectExecutorSDL(config.graphql);
+    if (!sdl) {
+      console.error(
+        "Error: `graphql` package not found.\nSchema export requires graphql-js to be installed:\n\n  npm install graphql\n"
+      );
+      process.exit(1);
+    }
+  } else {
+    console.error(
+      "Error: no GraphQL source configured.\nAdd `sources` or a `graphql` executor to your hadars.config.ts first.\n"
+    );
+    process.exit(1);
+  }
+  await writeFile2(outputFile, sdl, "utf-8");
+  console.log(`Schema written to ${outputFile}`);
+  console.log(`
+Next steps \u2014 generate TypeScript types with graphql-codegen:`);
+  console.log(`  npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations`);
+  console.log(`  npx graphql-codegen --schema ${outputFile} --documents "src/**/*.tsx" --out src/gql/`);
+}
 async function exportStatic(config, outputDir, cwd) {
   if (!config.paths) {
     console.error(
@@ -3369,7 +3470,7 @@ Done! Next steps:
 `);
 }
 function usage() {
-  console.log("Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs] | export cloudflare [output.mjs] | export static [outDir]>");
+  console.log("Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs] | export cloudflare [output.mjs] | export static [outDir] | export schema [schema.graphql]>");
 }
 async function runCli(argv, cwd = process.cwd()) {
   const cmd = argv[2];
@@ -3424,8 +3525,12 @@ async function runCli(argv, cwd = process.cwd()) {
           const outDirArg = argv[4] ?? "out";
           await exportStatic(cfg, outDirArg, cwd);
           process.exit(0);
+        } else if (subCmd === "schema") {
+          const outputFile = resolve(cwd, argv[4] ?? "schema.graphql");
+          await exportSchema(cfg, outputFile);
+          process.exit(0);
         } else {
-          console.error(`Unknown export target: ${subCmd ?? "(none)"}. Supported: lambda, cloudflare, static`);
+          console.error(`Unknown export target: ${subCmd ?? "(none)"}. Supported: lambda, cloudflare, static, schema`);
           process.exit(1);
         }
       }

package/dist/cloudflare.d.cts

@@ -1,4 +1,4 @@
-import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-mKu5txjW.cjs';
+import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-CSWWhlQC.cjs';
 
 /**
  * Cloudflare Workers adapter for hadars.

package/dist/cloudflare.d.ts

@@ -1,4 +1,4 @@
-import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-mKu5txjW.js';
+import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-CSWWhlQC.js';
 
 /**
  * Cloudflare Workers adapter for hadars.

package/dist/{hadars-mKu5txjW.d.cts → hadars-CSWWhlQC.d.cts}

@@ -1,3 +1,22 @@
+/**
+ * Minimal structural representation of a typed GraphQL document node.
+ *
+ * Compatible with `TypedDocumentNode` from `@graphql-typed-document-node/core`
+ * and the documents emitted by graphql-codegen's `client` preset — so passing
+ * a generated document object gives you fully-inferred result and variable types
+ * without writing explicit generics.
+ *
+ * hadars intentionally avoids importing from `graphql` or
+ * `@graphql-typed-document-node/core` so that neither is a required dependency.
+ */
+interface HadarsDocumentNode<TResult = Record<string, unknown>, TVariables = Record<string, unknown>> {
+    /** @internal Used by TypeScript to carry the result type. */
+    readonly __apiType?: (variables: TVariables) => TResult;
+    /** At least one definition — ensures a plain string is not assignable. */
+    readonly definitions: ReadonlyArray<{
+        readonly kind: string;
+    }>;
+}
 /**
  * In-process GraphQL executor passed to `getInitProps` and `paths` during
  * `hadars export static`. Hadars is executor-agnostic — configure it in
@@ -13,9 +32,24 @@
  *     gql({ schema, rootValue, source: query, variableValues: variables }),
  * } satisfies HadarsOptions;
  * ```
+ *
+ * The executor is generic — call it with explicit type parameters or pass a
+ * `TypedDocumentNode` / codegen-generated document to get inferred types:
+ *
+ * ```ts
+ * // Explicit generics:
+ * const { data } = await ctx.graphql<GetPostQuery, GetPostQueryVariables>(
+ *   `query GetPost($slug: String) { blogPost(slug: $slug) { title } }`,
+ *   { slug },
+ * );
+ *
+ * // Inferred via TypedDocumentNode (graphql-codegen client preset):
+ * import { GetPostDocument } from './gql';
+ * const { data } = await ctx.graphql(GetPostDocument, { slug });
+ * ```
  */
-type GraphQLExecutor = (query: string, variables?: Record<string, unknown>) => Promise<{
-    data?: any;
+type GraphQLExecutor = <TData = any, TVariables extends Record<string, unknown> = Record<string, unknown>>(query: string | HadarsDocumentNode<TData, TVariables>, variables?: TVariables) => Promise<{
+    data?: TData;
     errors?: ReadonlyArray<{
         message: string;
     }>;
@@ -252,4 +286,4 @@ interface HadarsRequest extends Request {
     cookies: Record<string, string>;
 }
 
-export type { GraphQLExecutor as G, HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetClientProps as c, HadarsGetFinalProps as d, HadarsGetInitialProps as e, HadarsProps as f, HadarsRequest as g, HadarsSourceEntry as h, HadarsStaticContext as i };
+export type { GraphQLExecutor as G, HadarsEntryModule as H, HadarsOptions as a, HadarsDocumentNode as b, HadarsApp as c, HadarsGetClientProps as d, HadarsGetFinalProps as e, HadarsGetInitialProps as f, HadarsProps as g, HadarsRequest as h, HadarsSourceEntry as i, HadarsStaticContext as j };

package/dist/{hadars-mKu5txjW.d.ts → hadars-CSWWhlQC.d.ts}

@@ -1,3 +1,22 @@
+/**
+ * Minimal structural representation of a typed GraphQL document node.
+ *
+ * Compatible with `TypedDocumentNode` from `@graphql-typed-document-node/core`
+ * and the documents emitted by graphql-codegen's `client` preset — so passing
+ * a generated document object gives you fully-inferred result and variable types
+ * without writing explicit generics.
+ *
+ * hadars intentionally avoids importing from `graphql` or
+ * `@graphql-typed-document-node/core` so that neither is a required dependency.
+ */
+interface HadarsDocumentNode<TResult = Record<string, unknown>, TVariables = Record<string, unknown>> {
+    /** @internal Used by TypeScript to carry the result type. */
+    readonly __apiType?: (variables: TVariables) => TResult;
+    /** At least one definition — ensures a plain string is not assignable. */
+    readonly definitions: ReadonlyArray<{
+        readonly kind: string;
+    }>;
+}
 /**
  * In-process GraphQL executor passed to `getInitProps` and `paths` during
  * `hadars export static`. Hadars is executor-agnostic — configure it in
@@ -13,9 +32,24 @@
  *     gql({ schema, rootValue, source: query, variableValues: variables }),
  * } satisfies HadarsOptions;
  * ```
+ *
+ * The executor is generic — call it with explicit type parameters or pass a
+ * `TypedDocumentNode` / codegen-generated document to get inferred types:
+ *
+ * ```ts
+ * // Explicit generics:
+ * const { data } = await ctx.graphql<GetPostQuery, GetPostQueryVariables>(
+ *   `query GetPost($slug: String) { blogPost(slug: $slug) { title } }`,
+ *   { slug },
+ * );
+ *
+ * // Inferred via TypedDocumentNode (graphql-codegen client preset):
+ * import { GetPostDocument } from './gql';
+ * const { data } = await ctx.graphql(GetPostDocument, { slug });
+ * ```
  */
-type GraphQLExecutor = (query: string, variables?: Record<string, unknown>) => Promise<{
-    data?: any;
+type GraphQLExecutor = <TData = any, TVariables extends Record<string, unknown> = Record<string, unknown>>(query: string | HadarsDocumentNode<TData, TVariables>, variables?: TVariables) => Promise<{
+    data?: TData;
     errors?: ReadonlyArray<{
         message: string;
     }>;
@@ -252,4 +286,4 @@ interface HadarsRequest extends Request {
     cookies: Record<string, string>;
 }
 
-export type { GraphQLExecutor as G, HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetClientProps as c, HadarsGetFinalProps as d, HadarsGetInitialProps as e, HadarsProps as f, HadarsRequest as g, HadarsSourceEntry as h, HadarsStaticContext as i };
+export type { GraphQLExecutor as G, HadarsEntryModule as H, HadarsOptions as a, HadarsDocumentNode as b, HadarsApp as c, HadarsGetClientProps as d, HadarsGetFinalProps as e, HadarsGetInitialProps as f, HadarsProps as g, HadarsRequest as h, HadarsSourceEntry as i, HadarsStaticContext as j };