chore(docs): bette organize http transport examples

examples/transport-http|transport-http_abort.ts

@@ -1,18 +1,20 @@
 /**
- * It is possible to cancel a request using an `AbortController` signal.
+ * This example shows how to cancel requests using an `AbortController` signal.
  */
 
 import { Graffle } from '../src/entrypoints/main.js'
 import { publicGraphQLSchemaEndpoints, show } from './$/helpers.js'
 
 const abortController = new AbortController()
+//    ^^^^^^^^^^^^^^^
 
 const graffle = Graffle.create({
   schema: publicGraphQLSchemaEndpoints.SocialStudies,
 })
 
 const resultPromise = graffle
   .with({ transport: { signal: abortController.signal } })
+  //                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   .rawString({
     document: `
       {
@@ -24,6 +26,7 @@ const resultPromise = graffle
   })
 
 abortController.abort()
+//              ^^^^^^^
 
 const result = await resultPromise.catch((error: unknown) => (error as Error).message)
 

examples/transport-http|transport-http_fetch.ts → examples/transport-http|transport-http_extension_fetch__custom-fetch.ts

@@ -1,3 +1,7 @@
+/**
+ * This examples shows how to leverage the extension system to override the "exchange" hook's default fetch implementation.
+ */
+
 /* eslint-disable */
 import { Graffle } from '../src/entrypoints/main.js'
 import { showJson } from './$/helpers.js'

examples/transport-http|transport-http_headers__dynamicHeaders.output.test.txt → examples/transport-http|transport-http_extension_headers__dynamicHeaders.output.txt

@@ -4,7 +4,7 @@
   headers: Headers {
     accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
     'content-type': 'application/json',
-    'x-sent-at-time': 'DYNAMIC_VALUE'
+    'x-sent-at-time': '1725741416691'
   },
   signal: undefined,
   method: 'post',

examples/transport-http|transport-http_headers__dynamicHeaders.ts → examples/transport-http|transport-http_extension_headers__dynamicHeaders.ts

@@ -1,3 +1,7 @@
+/**
+ * This example shows how to leverage the extension system to dynamically manipulate headers per request.
+ */
+
 import { Graffle } from '../src/entrypoints/main.js'
 import { publicGraphQLSchemaEndpoints, show } from './$/helpers.js'
 

examples/transport-http|transport-http_headers_raw__headers.output.txt

@@ -0,0 +1,6 @@
+---------------------------------------- SHOW ----------------------------------------
+Headers {
+  accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
+  'content-type': 'application/json',
+  'x-from-raw': 'true'
+}

examples/transport-http|transport-http_headers_raw__headers.ts

@@ -0,0 +1,32 @@
+/**
+ * This example shows how to use the `transport` configuration to control request headers. Notice how empty string headers unset previously set headers.
+ */
+import { Graffle } from '../src/entrypoints/main.js'
+import { show } from './$/helpers.js'
+import { publicGraphQLSchemaEndpoints } from './$/helpers.js'
+
+const graffle = Graffle
+  .create({
+    schema: publicGraphQLSchemaEndpoints.SocialStudies,
+    transport: {
+      headers: {
+        // todo: authorization header not showing up in final output!
+        authorization: `Bearer MY_TOKEN`,
+        'x-something-to-unset': `true`,
+      },
+      raw: {
+        headers: {
+          'x-from-raw': `true`,
+        },
+      },
+    },
+  })
+  .with({
+    transport: { headers: { 'x-something-to-unset': `` } },
+  })
+  .use(async ({ exchange }) => {
+    show(exchange.input.request.headers)
+    return exchange()
+  })
+
+await graffle.rawString({ document: `{ languages { code } }` })

examples/transport-http|transport-http_RequestInput.output.test.txt → examples/transport-http|transport-http_raw.output.txt

@@ -3,8 +3,7 @@
   methodMode: 'post',
   headers: Headers {
     accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
-    'content-type': 'application/json',
-    authorization: 'Bearer MY_TOKEN'
+    'content-type': 'application/json'
   },
   signal: undefined,
   mode: 'cors',

examples/transport-http|transport-http_RequestInput.ts → examples/transport-http|transport-http_raw.ts

@@ -1,3 +1,6 @@
+/**
+ * This example shows how to use the `raw` configuration of transport configuration to easily access low-level `RequestInit` configuration.
+ */
 import { Graffle } from '../src/entrypoints/main.js'
 import { show } from './$/helpers.js'
 import { publicGraphQLSchemaEndpoints } from './$/helpers.js'
@@ -6,9 +9,6 @@ const graffle = Graffle
   .create({
     schema: publicGraphQLSchemaEndpoints.SocialStudies,
     transport: {
-      headers: {
-        authorization: `Bearer MY_TOKEN`,
-      },
       raw: {
         mode: `cors`,
       },

tests/examples/transport-http|transport-http_headers__dynamicHeaders.test.ts → tests/examples/transport-http|transport-http_extension_fetch__custom-fetch.test.ts

@@ -9,14 +9,16 @@ import stripAnsi from 'strip-ansi'
 import { expect, test } from 'vitest'
 import { encode } from '../../examples/transport-http_headers__dynamicHeaders.output-encoder.js'
 
-test(`transport-http|transport-http_headers__dynamicHeaders`, async () => {
-  const result = await execaCommand(`pnpm tsx ./examples/transport-http|transport-http_headers__dynamicHeaders.ts`)
+test(`transport-http|transport-http_extension_fetch__custom-fetch`, async () => {
+  const result = await execaCommand(
+    `pnpm tsx ./examples/transport-http|transport-http_extension_fetch__custom-fetch.ts`,
+  )
   expect(result.exitCode).toBe(0)
   // Examples should output their data results.
   const exampleResult = encode(stripAnsi(result.stdout))
   // If ever outputs vary by Node version, you can use this to snapshot by Node version.
   // const nodeMajor = process.version.match(/v(\d+)/)?.[1] ?? `unknown`
   await expect(exampleResult).toMatchFileSnapshot(
-    `../.././examples/transport-http|transport-http_headers__dynamicHeaders.output.test.txt`,
+    `../.././examples/transport-http|transport-http_extension_fetch__custom-fetch.output.test.txt`,
   )
 })

tests/examples/transport-http|transport-http_extension_headers__dynamicHeaders.test.ts

@@ -0,0 +1,24 @@
+// @vitest-environment node
+
+// WARNING:
+// This test is generated by scripts/generate-example-derivatives/generate.ts
+// Do not modify this file directly.
+
+import { execaCommand } from 'execa'
+import stripAnsi from 'strip-ansi'
+import { expect, test } from 'vitest'
+import { encode } from '../../examples/transport-http_headers__dynamicHeaders.output-encoder.js'
+
+test(`transport-http|transport-http_extension_headers__dynamicHeaders`, async () => {
+  const result = await execaCommand(
+    `pnpm tsx ./examples/transport-http|transport-http_extension_headers__dynamicHeaders.ts`,
+  )
+  expect(result.exitCode).toBe(0)
+  // Examples should output their data results.
+  const exampleResult = encode(stripAnsi(result.stdout))
+  // If ever outputs vary by Node version, you can use this to snapshot by Node version.
+  // const nodeMajor = process.version.match(/v(\d+)/)?.[1] ?? `unknown`
+  await expect(exampleResult).toMatchFileSnapshot(
+    `../.././examples/transport-http|transport-http_extension_headers__dynamicHeaders.output.test.txt`,
+  )
+})

tests/examples/transport-http|transport-http_fetch.test.ts → tests/examples/transport-http|transport-http_headers_raw__headers.test.ts

@@ -9,14 +9,14 @@ import stripAnsi from 'strip-ansi'
 import { expect, test } from 'vitest'
 import { encode } from '../../examples/transport-http_headers__dynamicHeaders.output-encoder.js'
 
-test(`transport-http|transport-http_fetch`, async () => {
-  const result = await execaCommand(`pnpm tsx ./examples/transport-http|transport-http_fetch.ts`)
+test(`transport-http|transport-http_headers_raw__headers`, async () => {
+  const result = await execaCommand(`pnpm tsx ./examples/transport-http|transport-http_headers_raw__headers.ts`)
   expect(result.exitCode).toBe(0)
   // Examples should output their data results.
   const exampleResult = encode(stripAnsi(result.stdout))
   // If ever outputs vary by Node version, you can use this to snapshot by Node version.
   // const nodeMajor = process.version.match(/v(\d+)/)?.[1] ?? `unknown`
   await expect(exampleResult).toMatchFileSnapshot(
-    `../.././examples/transport-http|transport-http_fetch.output.test.txt`,
+    `../.././examples/transport-http|transport-http_headers_raw__headers.output.test.txt`,
   )
 })

tests/examples/transport-http|transport-http_RequestInput.test.ts → tests/examples/transport-http|transport-http_raw.test.ts

@@ -9,14 +9,12 @@ import stripAnsi from 'strip-ansi'
 import { expect, test } from 'vitest'
 import { encode } from '../../examples/transport-http_headers__dynamicHeaders.output-encoder.js'
 
-test(`transport-http|transport-http_RequestInput`, async () => {
-  const result = await execaCommand(`pnpm tsx ./examples/transport-http|transport-http_RequestInput.ts`)
+test(`transport-http|transport-http_raw`, async () => {
+  const result = await execaCommand(`pnpm tsx ./examples/transport-http|transport-http_raw.ts`)
   expect(result.exitCode).toBe(0)
   // Examples should output their data results.
   const exampleResult = encode(stripAnsi(result.stdout))
   // If ever outputs vary by Node version, you can use this to snapshot by Node version.
   // const nodeMajor = process.version.match(/v(\d+)/)?.[1] ?? `unknown`
-  await expect(exampleResult).toMatchFileSnapshot(
-    `../.././examples/transport-http|transport-http_RequestInput.output.test.txt`,
-  )
+  await expect(exampleResult).toMatchFileSnapshot(`../.././examples/transport-http|transport-http_raw.output.test.txt`)
 })

website/.vitepress/configExamples.ts

@@ -33,26 +33,30 @@ export const sidebarExamples: DefaultTheme.SidebarItem[] = [
   {
     'text': 'Transport Http',
     'items': [
-      {
-        'text': 'Request Input',
-        'link': '/examples/transport-http-request-input',
-      },
       {
         'text': 'Abort',
         'link': '/examples/transport-http-abort',
       },
       {
-        'text': 'Fetch',
-        'link': '/examples/transport-http-fetch',
+        'text': 'Custom Fetch',
+        'link': '/examples/transport-http-custom-fetch',
       },
       {
         'text': 'Dynamic Headers',
         'link': '/examples/transport-http-dynamic-headers',
       },
+      {
+        'text': 'Headers',
+        'link': '/examples/transport-http-headers',
+      },
       {
         'text': 'Method Get',
         'link': '/examples/transport-http-method-get',
       },
+      {
+        'text': 'Raw',
+        'link': '/examples/transport-http-raw',
+      },
     ],
   },
 ]

website/content/examples/transport-http-abort.md

@@ -4,20 +4,22 @@ aside: false
 
 # Abort
 
-It is possible to cancel a request using an `AbortController` signal.
+This example shows how to cancel requests using an `AbortController` signal.
 
 <!-- dprint-ignore-start -->
 ```ts twoslash
 import { Graffle } from 'graffle'
 
 const abortController = new AbortController()
+//    ^^^^^^^^^^^^^^^
 
 const graffle = Graffle.create({
   schema: `https://countries.trevorblades.com/graphql`,
 })
 
 const resultPromise = graffle
   .with({ transport: { signal: abortController.signal } })
+  //                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   .rawString({
     document: `
       {
@@ -29,6 +31,7 @@ const resultPromise = graffle
   })
 
 abortController.abort()
+//              ^^^^^^^
 
 const result = await resultPromise.catch((error: unknown) => (error as Error).message)
 

website/content/examples/transport-http-fetch.md → website/content/examples/transport-http-custom-fetch.md

@@ -2,7 +2,9 @@
 aside: false
 ---
 
-# Fetch
+# Custom Fetch
+
+This examples shows how to leverage the extension system to override the "exchange" hook's default fetch implementation.
 
 <!-- dprint-ignore-start -->
 ```ts twoslash

website/content/examples/transport-http-dynamic-headers.md

@@ -4,6 +4,8 @@ aside: false
 
 # Dynamic Headers
 
+This example shows how to leverage the extension system to dynamically manipulate headers per request.
+
 <!-- dprint-ignore-start -->
 ```ts twoslash
 import { Graffle } from 'graffle'
@@ -41,7 +43,7 @@ await graffle.rawString({ document: `{ languages { code } }` })
   headers: Headers {
     accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
     'content-type': 'application/json',
-    'x-sent-at-time': '1725665559439'
+    'x-sent-at-time': '1725741416691'
   },
   signal: undefined,
   method: 'post',