chore(docs/examples): add dynamic headers (#1065)

examples/transport-http_headers__dynamicHeaders.output-encoder.ts

@@ -0,0 +1,3 @@
+export const encode = (value: string) => {
+  return value.replace(/'x-sent-at-time': '\d+'/g, `'x-sent-at-time': 'DYNAMIC_VALUE'`)
+}

examples/transport-http_headers__dynamicHeaders.output.txt

@@ -0,0 +1,10 @@
+{
+  url: 'https://countries.trevorblades.com/graphql',
+  body: '{"query":"{ languages { code } }"}',
+  method: 'POST',
+  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'
+  }
+}

examples/transport-http_headers__dynamicHeaders.ts

@@ -0,0 +1,23 @@
+import { Graffle } from '../src/entrypoints/main.js'
+import { publicGraphQLSchemaEndpoints, show } from './$helpers.js'
+
+const graffle = Graffle
+  .create({
+    schema: publicGraphQLSchemaEndpoints.SocialStudies,
+  })
+  .use(async ({ pack }) => {
+    return await pack({
+      input: {
+        ...pack.input,
+        headers: {
+          'X-Sent-At-Time': Date.now().toString(),
+        },
+      },
+    })
+  })
+  .use(async ({ exchange }) => {
+    show(exchange.input.request)
+    return exchange()
+  })
+
+await graffle.rawString({ document: `{ languages { code } }` })

scripts/generate-examples-derivatives/generate-tests.ts

@@ -1,4 +1,6 @@
+import { globby } from 'globby'
 import * as FS from 'node:fs/promises'
+import * as Path from 'node:path'
 import { deleteFiles } from '../lib/deleteFiles.js'
 import { readFiles } from '../lib/readFiles.js'
 
@@ -8,32 +10,42 @@ export const generateTests = async () => {
 
   const files = await readFiles({
     pattern: `./examples/*.ts`,
-    options: { ignore: [`./examples/$*`] },
+    options: { ignore: [`./examples/$*`, `./examples/*.output.*`, `./examples/*.output-encoder.*`] },
   })
+  const encoderFilePaths = await globby(`./examples/*.output-encoder.ts`)
+
+  const outputDir = Path.join(process.cwd(), `./tests/examples`)
 
   await Promise.all(files.map(async (file) => {
+    const encoderFilePath = encoderFilePaths.find((encoderFilePath) =>
+      encoderFilePath.match(new RegExp(`${file.name}.output-encoder.ts`)) !== null
+    )
     const code = `// @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// 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 { expect, test } from 'vitest'${
+      encoderFilePath
+        ? `\nimport { encode } from '${Path.relative(outputDir, encoderFilePath.replace(`.ts`, `.js`))}'`
+        : ``
+    }
 
 test(\`${file.name}\`, async () => {
   const result = await execaCommand(\`pnpm tsx ./examples/${file.name}.ts\`)
   expect(result.exitCode).toBe(0)
   // Examples should output their data results.
-  const exampleResult = stripAnsi(result.stdout)
+  const exampleResult = ${encoderFilePath ? `encode(stripAnsi(result.stdout))` : `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(\`../../${file.path.dir}/${file.name}.output.txt\`)
 })
 `
 
-    await FS.writeFile(`./tests/examples/${file.name}.test.ts`, code)
+    await FS.writeFile(Path.join(outputDir, `${file.name}.test.ts`), code)
   }))
 
   console.log(`Generated a test for each example.`)

tests/examples/generated|generated_arguments__arguments.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/raw.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/raw_rawString__rawString.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/raw_rawString_rawTyped__rawString-typed.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/raw_rawTyped__raw-typed.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/transport-http_RequestInput.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/transport-http_abort.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/transport-http_fetch.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

tests/examples/transport-http_headers__dynamicHeaders.test.ts

@@ -0,0 +1,20 @@
+// @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_headers__dynamicHeaders`, async () => {
+  const result = await execaCommand(`pnpm tsx ./examples/transport-http_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_headers__dynamicHeaders.output.txt`)
+})

tests/examples/transport-memory.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment node
 
 // WARNING:
-// This test is generated by scripts/generate-test-examples.ts
+// This test is generated by scripts/generate-example-derivatives/generate.ts
 // Do not modify this file directly.
 
 import { execaCommand } from 'execa'

website/.vitepress/configExamples.ts

@@ -5,6 +5,14 @@ export const sidebarExamples: DefaultTheme.SidebarItem[] = [
     'text': 'Transport Memory',
     'link': '/examples/transport-memory',
   },
+  {
+    'text': 'DynamicHeaders',
+    'link': '/examples/dynamicHeaders',
+  },
+  {
+    'text': 'DynamicHeaders.output Encoder',
+    'link': '/examples/dynamicHeaders.output-encoder',
+  },
   {
     'text': 'Transport Http Fetch',
     'link': '/examples/transport-http_fetch',

website/content/examples/dynamicHeaders.md

@@ -0,0 +1,45 @@
+---
+aside: false
+---
+
+# DynamicHeaders
+
+```ts twoslash
+import { Graffle } from 'graffle'
+
+const graffle = Graffle
+  .create({
+    schema: `https://countries.trevorblades.com/graphql`,
+  })
+  .use(async ({ pack }) => {
+    return await pack({
+      input: {
+        ...pack.input,
+        headers: {
+          'X-Sent-At-Time': Date.now().toString(),
+        },
+      },
+    })
+  })
+  .use(async ({ exchange }) => {
+    console.log(exchange.input.request)
+    return exchange()
+  })
+
+await graffle.rawString({ document: `{ languages { code } }` })
+```
+
+#### Output
+
+```txt
+{
+  url: 'https://countries.trevorblades.com/graphql',
+  body: '{"query":"{ languages { code } }"}',
+  method: 'POST',
+  headers: Headers {
+    accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
+    'content-type': 'application/json',
+    'x-sent-at-time': '1725556925194'
+  }
+}
+```

website/content/examples/dynamicHeaders.output-encoder.md

@@ -0,0 +1,19 @@
+---
+aside: false
+---
+
+# DynamicHeaders.output Encoder
+
+```ts twoslash
+export const encode = (snapshot: string) => {
+  return snapshot.replace(
+    /x-sent-at-time: '\d+'/,
+    `x-sent-at-time: 'DYNAMIC_VALUE'`,
+  )
+}
+```
+
+#### Output
+
+```txt
+```

website/content/examples/transport-http_RequestInput.md

@@ -33,9 +33,9 @@ await graffle.rawString({ document: `{ languages { code } }` })
   body: '{"query":"{ languages { code } }"}',
   method: 'POST',
   headers: Headers {
-    authorization: 'Bearer MY_TOKEN',
-    accept: 'application/graphql-response+json',
-    'content-type': 'application/json'
+    accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
+    'content-type': 'application/json',
+    authorization: 'Bearer MY_TOKEN'
   },
   mode: 'cors'
 }

website/content/guides/_example_links/headers.md

@@ -0,0 +1 @@
+###### Examples -> [DynamicHeaders.output Encoder](../../examples/dynamicHeaders.output-encoder.md) / [DynamicHeaders](../../examples/dynamicHeaders.md)

website/content/guides/_example_links/transport-http.md

@@ -1 +1 @@
-###### Examples -> [Transport Http RequestInput](../../examples/transport-http_RequestInput.md) / [Transport Http Abort](../../examples/transport-http_abort.md) / [Transport Http Fetch](../../examples/transport-http_fetch.md)
+###### Examples -> [Transport Http RequestInput](../../examples/transport-http_RequestInput.md) / [Transport Http Abort](../../examples/transport-http_abort.md) / [Transport Http Fetch](../../examples/transport-http_fetch.md) / [DynamicHeaders.output Encoder](../../examples/dynamicHeaders.output-encoder.md) / [DynamicHeaders](../../examples/dynamicHeaders.md)

website/content/guides/_example_links/transport-http_headers.md

@@ -0,0 +1 @@
+###### Examples -> [DynamicHeaders.output Encoder](../../examples/dynamicHeaders.output-encoder.md) / [DynamicHeaders](../../examples/dynamicHeaders.md)