improve(jsdoc): gql send method

examples/20_output/output_return-error_return-error-execution__return-error-execution.ts

@@ -34,7 +34,7 @@ try {
       throw new Error(`Something went wrong.`)
     })
     .query
-    .pokemon({ name: true })
+    .pokemons({ name: true })
 } catch (error) {
   show(error)
 }

examples/30_gql/gql_gql-string.ts

@@ -11,7 +11,7 @@ const graffle = Graffle.create({
 
 const data = await graffle.gql`
   {
-    pokemon {
+    pokemons {
       name
     }
   }

examples/50_anyware/anyware_slot_slot-body__slot-body.ts

@@ -20,12 +20,12 @@ const graffle = Graffle
   })
 
 const result = await graffle.gql`
-    query pokemon {
-      trainers { name }
+    query pokemons {
+      pokemons { name }
     }
     query trainers {
-      pokemon { name }
+      trainers { name }
     }
-  `.send(`pokemon`)
+  `.send(`pokemons`)
 
 show(result)

examples/50_anyware/anyware_slot_slot-body__slot-search-params.ts

@@ -12,7 +12,7 @@ const graffle = Graffle
         searchParams: (graphqlRequest) => {
           return {
             query: graphqlRequest.query,
-            operationName: `getPokemon`,
+            operationName: `getPokemons`,
           }
         },
       },
@@ -23,8 +23,8 @@ const result = await graffle.gql`
     query getTrainers {
       trainers { name }
     }
-    query getPokemon {
-      pokemon { name }
+    query getPokemons {
+      pokemons { name }
     }
   `
   .send(`getTrainers`)

examples/__outputs__/10_transport-http/transport-http_extension_headers__dynamicHeaders.output.txt

@@ -4,9 +4,8 @@
   headers: Headers {
     accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
     'content-type': 'application/json',
-    'x-sent-at-time': '1730125688291'
+    'x-sent-at-time': '1731942324944'
   },
-  signal: undefined,
   method: 'post',
   url: 'http://localhost:3000/graphql',
   body: '{"query":"{ pokemons { name } }"}'

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

@@ -16,7 +16,7 @@
     headers: Headers {
       'content-type': 'application/graphql-response+json; charset=utf-8',
       'content-length': '142',
-      date: 'Mon, 28 Oct 2024 14:28:09 GMT',
+      date: 'Mon, 18 Nov 2024 15:05:25 GMT',
       connection: 'keep-alive',
       'keep-alive': 'timeout=5'
     },

examples/__outputs__/30_gql/gql_gql-string.output.txt

@@ -1,6 +1,6 @@
 ---------------------------------------- SHOW ----------------------------------------
 {
-  pokemon: [
+  pokemons: [
     { name: 'Pikachu' },
     { name: 'Charizard' },
     { name: 'Squirtle' },

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

@@ -1,11 +1,9 @@
 ---------------------------------------- SHOW ----------------------------------------
 {
-  pokemon: [
-    { name: 'Pikachu' },
-    { name: 'Charizard' },
-    { name: 'Squirtle' },
-    { name: 'Bulbasaur' },
-    { name: 'Caterpie' },
-    { name: 'Weedle' }
+  trainers: [
+    { name: 'Ash' },
+    { name: 'Misty' },
+    { name: 'Brock' },
+    { name: 'Gary' }
   ]
 }

examples/__outputs__/50_anyware/anyware_slot_slot-body__slot-search-params.output.txt

@@ -1,6 +1,6 @@
 ---------------------------------------- SHOW ----------------------------------------
 {
-  pokemon: [
+  pokemons: [
     { name: 'Pikachu' },
     { name: 'Charizard' },
     { name: 'Squirtle' },

examples/__outputs__/60_extension/extension_introspection__introspection.output.txt

@@ -639,6 +639,14 @@
             defaultValue: null,
             isDeprecated: false,
             deprecationReason: null
+          },
+          {
+            name: 'type',
+            description: null,
+            type: { kind: 'ENUM', name: 'PokemonType', ofType: null },
+            defaultValue: null,
+            isDeprecated: false,
+            deprecationReason: null
           }
         ],
         interfaces: null,
@@ -735,22 +743,6 @@
             isDeprecated: false,
             deprecationReason: null
           },
-          {
-            name: 'pokemon',
-            description: null,
-            args: [],
-            type: {
-              kind: 'LIST',
-              name: null,
-              ofType: {
-                kind: 'NON_NULL',
-                name: null,
-                ofType: { kind: 'OBJECT', name: 'Pokemon', ofType: null }
-              }
-            },
-            isDeprecated: false,
-            deprecationReason: null
-          },
           {
             name: 'pokemonByName',
             description: null,

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

@@ -2,21 +2,21 @@
 {
   resource: {
     attributes: {
-      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.7.0/bin/node',
+      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.11.0/bin/node',
       'telemetry.sdk.language': 'nodejs',
       'telemetry.sdk.name': 'opentelemetry',
       'telemetry.sdk.version': '1.27.0'
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: 'a15d7e95d85b3bf2bc123f8acaf94d5d',
-  parentId: '6bd4cb15802af388',
+  traceId: 'd1df7288d6e61f6468a98edf7a68ef88',
+  parentId: '209715d4b5564e5f',
   traceState: undefined,
   name: 'encode',
-  id: 'da01b95998af1310',
+  id: '1c887e1c1ec9a2f0',
   kind: 0,
-  timestamp: 1730125689574000,
-  duration: 1388.042,
+  timestamp: 1731942325967000,
+  duration: 1660.917,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -26,21 +26,21 @@
 {
   resource: {
     attributes: {
-      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.7.0/bin/node',
+      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.11.0/bin/node',
       'telemetry.sdk.language': 'nodejs',
       'telemetry.sdk.name': 'opentelemetry',
       'telemetry.sdk.version': '1.27.0'
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: 'a15d7e95d85b3bf2bc123f8acaf94d5d',
-  parentId: '6bd4cb15802af388',
+  traceId: 'd1df7288d6e61f6468a98edf7a68ef88',
+  parentId: '209715d4b5564e5f',
   traceState: undefined,
   name: 'pack',
-  id: '269378c8ef1b74a2',
+  id: 'a809cd5489d8667e',
   kind: 0,
-  timestamp: 1730125689577000,
-  duration: 11309.583,
+  timestamp: 1731942325969000,
+  duration: 25164.041,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -50,21 +50,21 @@
 {
   resource: {
     attributes: {
-      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.7.0/bin/node',
+      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.11.0/bin/node',
       'telemetry.sdk.language': 'nodejs',
       'telemetry.sdk.name': 'opentelemetry',
       'telemetry.sdk.version': '1.27.0'
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: 'a15d7e95d85b3bf2bc123f8acaf94d5d',
-  parentId: '6bd4cb15802af388',
+  traceId: 'd1df7288d6e61f6468a98edf7a68ef88',
+  parentId: '209715d4b5564e5f',
   traceState: undefined,
   name: 'exchange',
-  id: 'bf1490ed8d17bfba',
+  id: 'b0a98d222477503a',
   kind: 0,
-  timestamp: 1730125689589000,
-  duration: 20820.458,
+  timestamp: 1731942325995000,
+  duration: 20493.166,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -74,21 +74,21 @@
 {
   resource: {
     attributes: {
-      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.7.0/bin/node',
+      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.11.0/bin/node',
       'telemetry.sdk.language': 'nodejs',
       'telemetry.sdk.name': 'opentelemetry',
       'telemetry.sdk.version': '1.27.0'
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: 'a15d7e95d85b3bf2bc123f8acaf94d5d',
-  parentId: '6bd4cb15802af388',
+  traceId: 'd1df7288d6e61f6468a98edf7a68ef88',
+  parentId: '209715d4b5564e5f',
   traceState: undefined,
   name: 'unpack',
-  id: '9b7ed752b79d9543',
+  id: '653173e30aed7697',
   kind: 0,
-  timestamp: 1730125689610000,
-  duration: 1649.458,
+  timestamp: 1731942326016000,
+  duration: 951.5,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -98,21 +98,21 @@
 {
   resource: {
     attributes: {
-      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.7.0/bin/node',
+      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.11.0/bin/node',
       'telemetry.sdk.language': 'nodejs',
       'telemetry.sdk.name': 'opentelemetry',
       'telemetry.sdk.version': '1.27.0'
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: 'a15d7e95d85b3bf2bc123f8acaf94d5d',
-  parentId: '6bd4cb15802af388',
+  traceId: 'd1df7288d6e61f6468a98edf7a68ef88',
+  parentId: '209715d4b5564e5f',
   traceState: undefined,
   name: 'decode',
-  id: '3aafa22c23adfb5d',
+  id: 'fb042b294d2cd179',
   kind: 0,
-  timestamp: 1730125689612000,
-  duration: 209.833,
+  timestamp: 1731942326017000,
+  duration: 441.958,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -122,21 +122,21 @@
 {
   resource: {
     attributes: {
-      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.7.0/bin/node',
+      'service.name': 'unknown_service:/Users/jasonkuhrt/Library/pnpm/nodejs/22.11.0/bin/node',
       'telemetry.sdk.language': 'nodejs',
       'telemetry.sdk.name': 'opentelemetry',
       'telemetry.sdk.version': '1.27.0'
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: 'a15d7e95d85b3bf2bc123f8acaf94d5d',
+  traceId: 'd1df7288d6e61f6468a98edf7a68ef88',
   parentId: undefined,
   traceState: undefined,
   name: 'request',
-  id: '6bd4cb15802af388',
+  id: '209715d4b5564e5f',
   kind: 0,
-  timestamp: 1730125689573000,
-  duration: 38858.25,
+  timestamp: 1731942325966000,
+  duration: 51312.625,
   attributes: {},
   status: { code: 0 },
   events: [],

src/client/gql/gql.test-d.ts

@@ -39,6 +39,8 @@ AssertTypeOf<D | null>(await g.gql(d3).send({}))
 
 // dprint-ignore
 {
+  // Return Type
+
   AssertTypeOf<D | null>(await g.gql<Grafaid.Document.Typed.Query<D, { x: 1 }>               >``.send({ x: 1 }))
   AssertTypeOf<D | null>(await g.gql<Grafaid.Document.Typed.Query<D, { x?: 1 }>              >``.send())
   AssertTypeOf<D | null>(await g.gql<Grafaid.Document.Typed.Query<D, { x?: 1 }>              >``.send({ x: 1 }))

src/client/gql/send.ts

@@ -22,6 +22,44 @@ type SendArguments__<$Variables extends Grafaid.Document.Typed.Variables, $Varia
 
 // dprint-ignore
 export interface DocumentController<$Context extends Context, $TypedDocument extends Grafaid.Document.Typed.TypedDocumentLike> {
+  /**
+   * Send the document. You can pass an operation name and variables.
+   *
+   * If the document has multiple operations you must specify the operation name to be executed.
+   *
+   * If the operation being selected for execution has required variables you must pass them.
+   *
+   * @example
+   *
+   * ```ts
+   * const data = await graffle.gql`{ pokemons { name } }`.send()
+   * ```
+   *
+   * @example
+   * ```ts
+   * const data = await graffle.gql`
+   *   query($type: PokemonType!) {
+   *     pokemons(filter: { type: $type }) { name }
+   *   }
+   * `.send({ type: `electric` })
+   * ```
+   *
+   * @example
+   * ```ts
+   * const document = graffle.gql`
+   *   mutation createPokemon($name: String!, $type: PokemonType!) {
+   *     addPokemon(name: $name, type: $type) {
+   *      name
+   *     }
+   *   }
+   *   query pokemonsType($type: PokemonType!) {
+   *     pokemons(filter: { type: $type }) { name }
+   *   }
+   * `
+   * const data1 = await document.send(`createPokemon`, { name: `Pikabar`, type: `electric` })
+   * const data2 = await document.send(`pokemonsType`, { type: `electric` })
+   * ```
+   */
   send(...args: SendArguments<$TypedDocument>):
     Promise<SimplifyNullable<HandleOutput<$Context, Grafaid.Document.Typed.ResultOf<$TypedDocument>>>>
 }

src/documentBuilder/InferResult/__.test-d.ts

@@ -1,3 +1,4 @@
+import type { Simplify } from 'type-fest'
 import type { DateScalar } from '../../../tests/_/fixtures/scalars.js'
 import type { db } from '../../../tests/_/schemas/db.js'
 import type { Schema } from '../../../tests/_/schemas/kitchen-sink/graffle/modules/schema.js'
@@ -7,7 +8,7 @@ import type { Registry } from '../../types/Schema/nodes/Scalar/helpers.js'
 import type { InferResult } from './__.js'
 import type { PickSelectsPositiveIndicatorAndNotSelectAlias } from './OutputObject.js'
 
-type $<$SelectionSet extends SelectionSets.Query> = InferResult.OperationQuery<$SelectionSet, Schema>
+type $<$SelectionSet extends SelectionSets.Query> = Simplify<InferResult.OperationQuery<$SelectionSet, Schema>>
 
 type $Registry = Registry.AddScalar<Registry.Empty, typeof DateScalar>
 
@@ -100,8 +101,13 @@ assertEqual<$<{ idNonNull: ['x', true] }>, { x: string }>()
 assertEqual<$<{ object: ['x', { id: true }] }>, { x: { id: null|string } | null }>()
 // argument
 assertEqual<$<{objectWithArgs: ['x', { $: {id:''}; id:true }]}>, { x: { id: null|string } | null }>()
-// multi
+// one field multiple times
 assertEqual<$<{ id: [['id1', true],['id2', true]] }>, { id1: null | string; id2: null | string }>()
+// multiple fields
+// assertEqual<
+//   $<{ id: [['id1', true],['id2', true]], abcEnum: ['abcEnum1', true] }>,
+//   { id1: null | string; id2: null | string; abcEnum1: null | db.ABCEnum }
+// >()
 // AssertEqual<RS<{ id_as: true }>, { id_as: InferResult.Errors.UnknownFieldName<'id_as', Schema.Root.Query> }>()
 // AssertEqual<RS<{ id_as_$: true }>, { id_as_$: InferResult.Errors.UnknownFieldName<'id_as_$', Schema.Root.Query> }>()
 // union fragment