improve: avoid conflict import paths for Twoslash (#1069)

examples/$/generated-clients/SocialStudies/_.ts

@@ -1,3 +1,9 @@
-export { create } from './Client.js'
-export { isError } from './Error.js'
-export { Select } from './Select.js'
+// We import the global module for good measure although it is not clear it is always needed.
+// It at least helps with Twoslash wherein without this import here Twoslash will not include the global module.
+// In real TypeScript projects it seems the global module is included automatically. But there could be certain tsconfig
+// setups where this still indeed does help.
+import './modules/Global.js'
+
+export { create } from './modules/Client.js'
+export { isError } from './modules/Error.js'
+export { Select } from './modules/Select.js'

examples/$/generated-clients/SocialStudies/Client.ts → examples/$/generated-clients/SocialStudies/modules/Client.ts

@@ -1,4 +1,4 @@
-import { createPrefilled } from '../../../../src/entrypoints/client.js'
+import { createPrefilled } from '../../../../../src/entrypoints/client.js'
 
 import { $defaultSchemaUrl, $Index } from './SchemaRuntime.js'
 

examples/$/generated-clients/SocialStudies/Global.ts → examples/$/generated-clients/SocialStudies/modules/Global.ts

@@ -1,4 +1,4 @@
-import type { Index } from './Index.js'
+import type { Index } from './SchemaIndex.js'
 
 declare global {
   export namespace GraffleGlobalTypes {

examples/$/generated-clients/SocialStudies/modules/Scalar.ts

@@ -0,0 +1 @@
+export * from '../../../../../src/entrypoints/scalars.js'

examples/$/generated-clients/SocialStudies/SchemaBuildtime.ts → examples/$/generated-clients/SocialStudies/modules/SchemaBuildtime.ts

@@ -1,4 +1,4 @@
-import type * as $ from '../../../../src/entrypoints/schema.js'
+import type * as $ from '../../../../../src/entrypoints/schema.js'
 import type * as $Scalar from './Scalar.ts'
 
 // ------------------------------------------------------------ //

examples/$/generated-clients/SocialStudies/SchemaRuntime.ts → examples/$/generated-clients/SocialStudies/modules/SchemaRuntime.ts

@@ -1,6 +1,6 @@
 /* eslint-disable */
 
-import * as $ from '../../../../src/entrypoints/schema.js'
+import * as $ from '../../../../../src/entrypoints/schema.js'
 import * as $Scalar from './Scalar.js'
 
 export const $defaultSchemaUrl = new URL('https://countries.trevorblades.com/graphql')

examples/$/generated-clients/SocialStudies/Select.ts → examples/$/generated-clients/SocialStudies/modules/Select.ts

@@ -1,10 +1,10 @@
-import type { ResultSet, SelectionSet } from '../../../../src/entrypoints/schema.js'
-import type { Index } from './Index.js'
+import type { ResultSet, SelectionSet } from '../../../../../src/entrypoints/schema.js'
+import type { Index } from './SchemaIndex.js'
 
 // Runtime
 // -------
 
-import { createSelect } from '../../../../src/entrypoints/client.js'
+import { createSelect } from '../../../../../src/entrypoints/client.js'
 export const Select = createSelect(`default`)
 
 // Buildtime

examples/$/generated-clients/pokemon/_.ts

@@ -1,3 +1,9 @@
-export { create } from './Client.js'
-export { isError } from './Error.js'
-export { Select } from './Select.js'
+// We import the global module for good measure although it is not clear it is always needed.
+// It at least helps with Twoslash wherein without this import here Twoslash will not include the global module.
+// In real TypeScript projects it seems the global module is included automatically. But there could be certain tsconfig
+// setups where this still indeed does help.
+import './modules/Global.js'
+
+export { create } from './modules/Client.js'
+export { isError } from './modules/Error.js'
+export { Select } from './modules/Select.js'

examples/$/generated-clients/pokemon/Client.ts → examples/$/generated-clients/pokemon/modules/Client.ts

@@ -1,4 +1,4 @@
-import { createPrefilled } from '../../../../src/entrypoints/client.js'
+import { createPrefilled } from '../../../../../src/entrypoints/client.js'
 
 import { $defaultSchemaUrl, $Index } from './SchemaRuntime.js'
 

website/pokemon/Global.ts → examples/$/generated-clients/pokemon/modules/Global.ts

@@ -1,4 +1,4 @@
-import type { Index } from './Index.js'
+import type { Index } from './SchemaIndex.js'
 
 declare global {
   export namespace GraffleGlobalTypes {

examples/$/generated-clients/pokemon/modules/Scalar.ts

@@ -0,0 +1 @@
+export * from '../../../../../src/entrypoints/scalars.js'

examples/$/generated-clients/pokemon/SchemaBuildtime.ts → examples/$/generated-clients/pokemon/modules/SchemaBuildtime.ts

@@ -1,4 +1,4 @@
-import type * as $ from '../../../../src/entrypoints/schema.js'
+import type * as $ from '../../../../../src/entrypoints/schema.js'
 import type * as $Scalar from './Scalar.ts'
 
 // ------------------------------------------------------------ //

examples/$/generated-clients/pokemon/SchemaRuntime.ts → examples/$/generated-clients/pokemon/modules/SchemaRuntime.ts

@@ -1,6 +1,6 @@
 /* eslint-disable */
 
-import * as $ from '../../../../src/entrypoints/schema.js'
+import * as $ from '../../../../../src/entrypoints/schema.js'
 import * as $Scalar from './Scalar.js'
 
 export const $defaultSchemaUrl = undefined

examples/$/generated-clients/pokemon/Select.ts → examples/$/generated-clients/pokemon/modules/Select.ts

@@ -1,10 +1,10 @@
-import type { ResultSet, SelectionSet } from '../../../../src/entrypoints/schema.js'
-import type { Index } from './Index.js'
+import type { ResultSet, SelectionSet } from '../../../../../src/entrypoints/schema.js'
+import type { Index } from './SchemaIndex.js'
 
 // Runtime
 // -------
 
-import { createSelect } from '../../../../src/entrypoints/client.js'
+import { createSelect } from '../../../../../src/entrypoints/client.js'
 export const Select = createSelect(`default`)
 
 // Buildtime

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

@@ -0,0 +1,14 @@
+---------------------------------------- SHOW ----------------------------------------
+{
+  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'
+  },
+  signal: undefined,
+  mode: 'cors',
+  method: 'post',
+  url: 'https://countries.trevorblades.com/graphql',
+  body: '{"query":"{ languages { code } }"}'
+}

examples/transport-http|transport-http_abort.output.test.txt

@@ -0,0 +1,2 @@
+---------------------------------------- SHOW ----------------------------------------
+'This operation was aborted'

examples/transport-http|transport-http_fetch.output.test.txt

@@ -0,0 +1,8 @@
+---------------------------------------- SHOW ----------------------------------------
+{
+  "countries": [
+    {
+      "name": "Canada Mocked!"
+    }
+  ]
+}

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

@@ -0,0 +1,13 @@
+---------------------------------------- SHOW ----------------------------------------
+{
+  methodMode: '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'
+  },
+  signal: undefined,
+  method: 'post',
+  url: 'https://countries.trevorblades.com/graphql',
+  body: '{"query":"{ languages { code } }"}'
+}

examples/transport-http|transport-http_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': '1725656299249'
+    'x-sent-at-time': '1725665559439'
   },
   signal: undefined,
   method: 'post',

examples/transport-http|transport-http_method-get.output.test.txt

@@ -0,0 +1,48 @@
+---------------------------------------- SHOW ----------------------------------------
+{
+  methodMode: 'getReads',
+  headers: Headers {
+    accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
+    'content-type': 'application/json'
+  },
+  signal: undefined,
+  method: 'post',
+  url: URL {
+    href: 'http://localhost:3000/graphql',
+    origin: 'http://localhost:3000',
+    protocol: 'http:',
+    username: '',
+    password: '',
+    host: 'localhost:3000',
+    hostname: 'localhost',
+    port: '3000',
+    pathname: '/graphql',
+    search: '',
+    searchParams: URLSearchParams {},
+    hash: ''
+  },
+  body: '{"query":"mutation addPokemon(attack:0, defense:0, hp:1, name:\\"Nano\\") { name }"}'
+}
+---------------------------------------- SHOW ----------------------------------------
+{
+  methodMode: 'getReads',
+  headers: Headers {
+    accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8'
+  },
+  signal: undefined,
+  method: 'get',
+  url: URL {
+    href: 'http://localhost:3000/graphql?query=query+%7B+pokemonByName%28name%3A%22Nano%22%29+%7B+hp+%7D+%7D',
+    origin: 'http://localhost:3000',
+    protocol: 'http:',
+    username: '',
+    password: '',
+    host: 'localhost:3000',
+    hostname: 'localhost',
+    port: '3000',
+    pathname: '/graphql',
+    search: '?query=query+%7B+pokemonByName%28name%3A%22Nano%22%29+%7B+hp+%7D+%7D',
+    searchParams: URLSearchParams { 'query' => 'query { pokemonByName(name:"Nano") { hp } }' },
+    hash: ''
+  }
+}

package.json

@@ -61,7 +61,7 @@
     "graffle": "tsx ./src/cli/generate.ts",
     "gen:test:schema": "tsx tests/_/schemaGenerate.ts",
     "gen:examples": "tsx scripts/generate-examples-derivatives/generate.ts && pnpm format",
-    "gen:docs:examples:clients": "tsx './examples/$/schemas/pokemon/generateSdl.ts' && pnpm graffle --name Pokemon --schema './examples/$/schemas/pokemon/schema.graphql' --output './examples/$/generated-clients/pokemon' --libraryPathClient ../../../../src/entrypoints/client.js --libraryPathSchema ../../../../src/entrypoints/schema.js --libraryPathScalars ../../../../src/entrypoints/scalars.js && pnpm graffle --name SocialStudies --schema https://countries.trevorblades.com/graphql --output './examples/$/generated-clients/SocialStudies' --libraryPathClient ../../../../src/entrypoints/client.js --libraryPathSchema ../../../../src/entrypoints/schema.js --libraryPathScalars ../../../../src/entrypoints/scalars.js",
+    "gen:examples:clients": "tsx './examples/$/schemas/pokemon/generateSdl.ts' && pnpm graffle --name Pokemon --schema './examples/$/schemas/pokemon/schema.graphql' --output './examples/$/generated-clients/pokemon' --libraryPathClient ../../../../../src/entrypoints/client.js --libraryPathSchema ../../../../../src/entrypoints/schema.js --libraryPathScalars ../../../../../src/entrypoints/scalars.js && pnpm graffle --name SocialStudies --schema https://countries.trevorblades.com/graphql --output './examples/$/generated-clients/SocialStudies' --libraryPathClient ../../../../../src/entrypoints/client.js --libraryPathSchema ../../../../../src/entrypoints/schema.js --libraryPathScalars ../../../../../src/entrypoints/scalars.js",
     "dev": "rm -rf dist && tsc --watch",
     "format": "pnpm build:docs && dprint fmt",
     "lint": "eslint . --fix",

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

@@ -125,14 +125,12 @@ const transformRewriteGraffleImports = (example: Example) => {
     )
     .replaceAll(
       `import { SocialStudies } from './$/generated-clients/SocialStudies/__.js'`,
-      `import './graffle/Global.js'
-// ---cut---
+      `// ---cut---
 import { Graffle as SocialStudies } from './graffle/__.js'`,
     )
     .replaceAll(
       /import ({[^}]+}) from '.\/\$\/generated-clients\/([^/]+)\/__\.js'/g,
-      `import './$2/Global.js'
-// ---cut---
+      `// ---cut---
 import $1 from './$2/__.js'`,
     )
     // Any remaining $ imports are entirely removed.

src/layers/2_generator/code/Index.ts → src/layers/2_generator/code/SchemaIndex.ts

@@ -5,12 +5,12 @@ import { createCodeGenerator } from '../createCodeGenerator.js'
 import { moduleNameSchemaBuildtime } from './SchemaBuildtime.js'
 
 export const { generate: generateIndex, moduleName: moduleNameIndex } = createCodeGenerator(
-  `Index`,
+  `SchemaIndex`,
   (config) => {
-    const namespace = `Schema`
+    const SchemaNamespace = `Schema`
     const code = []
     code.push(`/* eslint-disable */\n`)
-    code.push(`import type * as ${namespace} from './${moduleNameSchemaBuildtime}.js'\n`)
+    code.push(`import type * as ${SchemaNamespace} from './${moduleNameSchemaBuildtime}.js'\n`)
 
     code.push(Code.export$(
       Code.interface$(
@@ -19,25 +19,25 @@ export const { generate: generateIndex, moduleName: moduleNameIndex } = createCo
           name: Code.quote(config.name),
           Root: {
             type: Code.objectFrom({
-              Query: hasQuery(config.typeMapByKind) ? `${namespace}.Root.Query` : null,
-              Mutation: hasMutation(config.typeMapByKind) ? `${namespace}.Root.Mutation` : null,
-              Subscription: hasSubscription(config.typeMapByKind) ? `${namespace}.Root.Subscription` : null,
+              Query: hasQuery(config.typeMapByKind) ? `${SchemaNamespace}.Root.Query` : null,
+              Mutation: hasMutation(config.typeMapByKind) ? `${SchemaNamespace}.Root.Mutation` : null,
+              Subscription: hasSubscription(config.typeMapByKind) ? `${SchemaNamespace}.Root.Subscription` : null,
             }),
           },
           objects: Code.objectFromEntries(
-            config.typeMapByKind.GraphQLObjectType.map(_ => [_.name, `${namespace}.Object.${_.name}`]),
+            config.typeMapByKind.GraphQLObjectType.map(_ => [_.name, `${SchemaNamespace}.Object.${_.name}`]),
           ),
           unions: Code.objectFromEntries(
-            config.typeMapByKind.GraphQLUnionType.map(_ => [_.name, `${namespace}.Union.${_.name}`]),
+            config.typeMapByKind.GraphQLUnionType.map(_ => [_.name, `${SchemaNamespace}.Union.${_.name}`]),
           ),
           interfaces: Code.objectFromEntries(
-            config.typeMapByKind.GraphQLInterfaceType.map(_ => [_.name, `${namespace}.Interface.${_.name}`]),
+            config.typeMapByKind.GraphQLInterfaceType.map(_ => [_.name, `${SchemaNamespace}.Interface.${_.name}`]),
           ),
           // todo jsdoc comment saying:
           // Objects that match this pattern name: /.../
           error: Code.objectFrom({
             objects: Code.objectFromEntries(
-              config.error.objects.map(_ => [_.name, `${namespace}.Object.${_.name}`]),
+              config.error.objects.map(_ => [_.name, `${SchemaNamespace}.Object.${_.name}`]),
             ),
             objectsTypename: Code.objectFromEntries(
               config.error.objects.map(_ => [_.name, `{ __typename: "${_.name}" }`]),

src/layers/2_generator/code/Select.ts

@@ -1,6 +1,6 @@
 import { createCodeGenerator } from '../createCodeGenerator.js'
 import { title, typeTitle } from '../helpers.js'
-import { moduleNameIndex } from './Index.js'
+import { moduleNameIndex } from './SchemaIndex.js'
 
 export const { generate: generateSelect, moduleName: moduleNameSelect } = createCodeGenerator(
   `Select`,

src/layers/2_generator/code/_.ts

@@ -8,9 +8,15 @@ export const { generate: generate_, moduleName: moduleName_ } = createCodeGenera
   (_config) => {
     const code: string[] = []
     code.push(
-      `export { Select } from './${moduleNameSelect}.js'`,
-      `export { isError } from './${moduleNameError}.js'`,
-      `export { create } from './${moduleNameClient}.js'`,
+      `// We import the global module for good measure although it is not clear it is always needed.`,
+      `// It at least helps with Twoslash wherein without this import here Twoslash will not include the global module.`,
+      `// In real TypeScript projects it seems the global module is included automatically. But there could be certain tsconfig`,
+      `// setups where this still indeed does help.`,
+      `import './modules/Global.js'`,
+      ``,
+      `export { Select } from './modules/${moduleNameSelect}.js'`,
+      `export { isError } from './modules/${moduleNameError}.js'`,
+      `export { create } from './modules/${moduleNameClient}.js'`,
     )
 
     return code.join(`\n`)

src/layers/2_generator/code/global.ts

@@ -1,5 +1,5 @@
 import { createCodeGenerator } from '../createCodeGenerator.js'
-import { moduleNameIndex } from './Index.js'
+import { moduleNameIndex } from './SchemaIndex.js'
 
 export const { moduleName: moduleNameGlobal, generate: generateGlobal } = createCodeGenerator(
   `Global`,

src/layers/2_generator/files.ts

@@ -91,10 +91,15 @@ export const generateFiles = async (input: Input) => {
     },
   })
 
+  // todo clear directory before generating so that removed or renamed files are cleaned up.
   await fs.mkdir(outputDirPath, { recursive: true })
+  await fs.mkdir(`${outputDirPath}/modules`, { recursive: true })
   await Promise.all(
     codes.map((code) => {
-      return fs.writeFile(`${outputDirPath}/${code.moduleName}.ts`, code.code, { encoding: `utf8` })
+      const isIndexModule = code.moduleName.match(/^_+$/) !== null
+      return fs.writeFile(`${outputDirPath}/${isIndexModule ? `` : `modules/`}${code.moduleName}.ts`, code.code, {
+        encoding: `utf8`,
+      })
     }),
   )
 }

src/layers/2_generator/generateCode.ts

@@ -9,9 +9,9 @@ import { generate__ } from './code/__.js'
 import { generateClient } from './code/Client.js'
 import { generateError } from './code/Error.js'
 import { generateGlobal } from './code/global.js'
-import { generateIndex } from './code/Index.js'
 import { generateScalar } from './code/Scalar.js'
 import { generateSchemaBuildtime } from './code/SchemaBuildtime.js'
+import { generateIndex } from './code/SchemaIndex.js'
 import { generateRuntimeSchema } from './code/SchemaRuntime.js'
 import { generateSelect } from './code/Select.js'
 

website/content/examples/generated-arguments.md

@@ -6,7 +6,6 @@ aside: false
 
 <!-- dprint-ignore-start -->
 ```ts twoslash
-import './graffle/Global.js'
 // ---cut---
 import { Graffle as SocialStudies } from './graffle/__.js'
 

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

@@ -41,7 +41,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': '1725656299249'
+    'x-sent-at-time': '1725665559439'
   },
   signal: undefined,
   method: 'post',

website/content/examples/transport-http-method-get.md

@@ -9,7 +9,6 @@ to be sent over HTTP GET method. Note write-kind operations (mutation) are still
 
 <!-- dprint-ignore-start -->
 ```ts twoslash
-import './pokemon/Global.js'
 // ---cut---
 import { Pokemon } from './pokemon/__.js'