chore(docs): add example for union (#1148)

examples/55_generated/generated_union.ts

@@ -0,0 +1,101 @@
+/**
+ * This example shows how to work with GraphQL union types in the TypeScript interface.
+ */
+
+import { Pokemon } from '../../tests/_/schemas/pokemon/graffle/__.js'
+import { show } from '../$/helpers.js'
+
+const pokemon = Pokemon.create()
+
+// dprint-ignore
+const battles = await pokemon.query.battles({
+  __typename: true,
+  ___on_BattleRoyale: {
+    date: true,
+    combatants: {
+      trainer: {
+        name: true,
+      },
+      pokemons: {
+        name: true,
+      }
+    },
+    winner: {
+      name: true,
+    },
+  },
+  ___on_BattleTrainer: {
+    date: true,
+    combatant1: {
+      trainer: {
+        name: true,
+      },
+      pokemon: {
+        name: true,
+      },
+    },
+    combatant2: {
+      trainer: {
+        name: true,
+      },
+      pokemon: {
+        name: true,
+      },
+    },
+    winner: {
+      name: true,
+    },
+  },
+  ___on_BattleWild: {
+    date: true,
+    trainer: {
+      name: true,
+    },
+    pokemon: {
+      name: true,
+    },
+    wildPokemons: {
+      name: true,
+    },
+    result: true,
+  },
+})
+
+// The following contrived switch shows how the returned type is a discriminated union.
+// After checking the __typename, the type is known to be one of the possible battle types
+// and TypeScript narrows accordingly.
+
+const dateFormatter = new Intl.DateTimeFormat(`en-US`, { timeZone: `UTC` })
+
+for (const battle of battles) {
+  switch (battle.__typename) {
+    case `BattleRoyale`: {
+      // eslint-disable-next-line
+      // @ts-ignore-error fixme
+      const trainers = battle.combatants?.map(_ => _.trainer?.name)
+      let info = ``
+      info += `${battle.__typename} on ${dateFormatter.format(new Date(battle.date ?? 0))}\n`
+      info += `combatants: ${trainers?.join(`, `) ?? `null`}\n`
+      info += `winner: ${battle.winner?.name ?? `null`}`
+      show(info)
+      break
+    }
+    case `BattleTrainer`: {
+      let info = ``
+      info += `${battle.__typename} on ${dateFormatter.format(new Date(battle.date ?? 0))}\n`
+      info += `${battle.combatant1?.trainer?.name ?? `null`} vs ${battle.combatant2?.trainer?.name ?? `null`}\n`
+      info += `winner: ${battle.winner?.name ?? `null`}`
+      show(info)
+      break
+    }
+    case `BattleWild`: {
+      let info = ``
+      info += `${battle.__typename} on ${dateFormatter.format(new Date(battle.date ?? 0))}\n`
+      info += `trainer: ${battle.trainer?.name ?? `null`} with ${battle.pokemon?.name ?? `null`}\n`
+      info += `vs wild pokemons: ${battle.wildPokemons?.map(_ => _.name).join(`, `) ?? `null`}\n`
+      info += `result: ${battle.result ?? `null`}`
+      show(info)
+      break
+    }
+  }
+}

examples/__outputs__/10_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': '1727448397817'
+    'x-sent-at-time': '1727568837251'
   },
   signal: undefined,
   method: 'post',

examples/__outputs__/20_output/output_default.output.txt

@@ -3,5 +3,7 @@
   { name: 'Pikachu' },
   { name: 'Charizard' },
   { name: 'Squirtle' },
-  { name: 'Bulbasaur' }
+  { name: 'Bulbasaur' },
+  { name: 'Caterpie' },
+  { name: 'Weedle' }
 ]

examples/__outputs__/20_output/output_envelope.output.test.txt

@@ -5,7 +5,9 @@
       { name: 'Pikachu' },
       { name: 'Charizard' },
       { name: 'Squirtle' },
-      { name: 'Bulbasaur' }
+      { name: 'Bulbasaur' },
+      { name: 'Caterpie' },
+      { name: 'Weedle' }
     ]
   },
   errors: undefined,

examples/__outputs__/20_output/output_envelope.output.txt

@@ -5,7 +5,9 @@
       { name: 'Pikachu' },
       { name: 'Charizard' },
       { name: 'Squirtle' },
-      { name: 'Bulbasaur' }
+      { name: 'Bulbasaur' },
+      { name: 'Caterpie' },
+      { name: 'Weedle' }
     ]
   },
   errors: undefined,
@@ -15,8 +17,8 @@
     statusText: 'OK',
     headers: Headers {
       'content-type': 'application/graphql-response+json; charset=utf-8',
-      'content-length': '104',
-      date: 'Fri, 27 Sep 2024 14:46:38 GMT',
+      'content-length': '142',
+      date: 'Sun, 29 Sep 2024 00:13:57 GMT',
       connection: 'keep-alive',
       'keep-alive': 'timeout=5'
     },

examples/__outputs__/30_raw/raw_rawString__rawString.output.txt

@@ -4,6 +4,8 @@
     { name: 'Pikachu' },
     { name: 'Charizard' },
     { name: 'Squirtle' },
-    { name: 'Bulbasaur' }
+    { name: 'Bulbasaur' },
+    { name: 'Caterpie' },
+    { name: 'Weedle' }
   ]
 }

examples/__outputs__/50_anyware/anyware_slot_slot-body__slot-body.output.txt

@@ -4,6 +4,8 @@
     { name: 'Pikachu' },
     { name: 'Charizard' },
     { name: 'Squirtle' },
-    { name: 'Bulbasaur' }
+    { name: 'Bulbasaur' },
+    { name: 'Caterpie' },
+    { name: 'Weedle' }
   ]
 }

examples/__outputs__/55_generated/generated_batch.output.txt

@@ -3,11 +3,11 @@
   "pokemonByName": [
     {
       "name": "Pikachu",
-      "id": 1
+      "id": "1"
     }
   ],
   "trainerByName": {
     "name": "Ash",
-    "id": 1
+    "id": "1"
   }
 }

examples/__outputs__/55_generated/generated_directive.output.txt

@@ -19,6 +19,14 @@
           "name": "Squirtle"
         }
       ]
+    },
+    {
+      "name": "Brock",
+      "pokemon": []
+    },
+    {
+      "name": "Gary",
+      "pokemon": []
     }
   ]
 }

examples/__outputs__/55_generated/generated_document.output.txt

@@ -6,6 +6,12 @@
     },
     {
       "name": "Misty"
+    },
+    {
+      "name": "Brock"
+    },
+    {
+      "name": "Gary"
     }
   ],
   "pokemons": [

examples/__outputs__/55_generated/generated_interface.output.txt

@@ -15,6 +15,14 @@ Misty
 ---------------------------------------- SHOW ----------------------------------------
 teamRocketGrunt
 ---------------------------------------- SHOW ----------------------------------------
+Brock
+---------------------------------------- SHOW ----------------------------------------
+youth
+---------------------------------------- SHOW ----------------------------------------
+Gary
+---------------------------------------- SHOW ----------------------------------------
+youth
+---------------------------------------- SHOW ----------------------------------------
 Pikachu
 ---------------------------------------- SHOW ----------------------------------------
 electric
@@ -29,4 +37,12 @@ water
 ---------------------------------------- SHOW ----------------------------------------
 Bulbasaur
 ---------------------------------------- SHOW ----------------------------------------
-grass
+grass
+---------------------------------------- SHOW ----------------------------------------
+Caterpie
+---------------------------------------- SHOW ----------------------------------------
+bug
+---------------------------------------- SHOW ----------------------------------------
+Weedle
+---------------------------------------- SHOW ----------------------------------------
+bug

examples/__outputs__/55_generated/generated_root-field.output.txt

@@ -11,5 +11,11 @@
   },
   {
     "name": "Bulbasaur"
+  },
+  {
+    "name": "Caterpie"
+  },
+  {
+    "name": "Weedle"
   }
 ]

examples/__outputs__/55_generated/generated_union.output.txt

@@ -0,0 +1,13 @@
+---------------------------------------- SHOW ----------------------------------------
+BattleWild on 1/1/2020
+trainer: Ash with Pikachu
+vs wild pokemons: Squirtle, Bulbasaur
+result: pokemonsCaptured
+---------------------------------------- SHOW ----------------------------------------
+BattleTrainer on 1/1/2003
+Ash vs Misty
+winner: Misty
+---------------------------------------- SHOW ----------------------------------------
+BattleRoyale on 1/13/1987
+combatants: Ash, Misty
+winner: Ash

examples/__outputs__/60_extension/extension_opentelemetry__opentelemetry.output.test.txt

@@ -148,6 +148,8 @@
     { name: 'Pikachu' },
     { name: 'Charizard' },
     { name: 'Squirtle' },
-    { name: 'Bulbasaur' }
+    { name: 'Bulbasaur' },
+    { name: 'Caterpie' },
+    { name: 'Weedle' }
   ]
 }