feat(extension/or-throw): add new extension (#1087)

eslint.config.js

@@ -20,5 +20,9 @@ export default tsEslint.config({
   },
   rules: {
     ['@typescript-eslint/only-throw-error']: 'off',
+    ['@typescript-eslint/no-unsafe-assignment']: 'off',
+    ['@typescript-eslint/no-unsafe-call']: 'off',
+    ['@typescript-eslint/no-unsafe-member-access']: 'off',
+    ['@typescript-eslint/ban-types']: 'off',
   },
 })

examples/$/generated-clients/atlas/modules/SchemaIndex.ts

@@ -4,6 +4,7 @@ import type * as Schema from './SchemaBuildtime.js'
 
 export interface Index {
   name: 'Atlas'
+  RootTypesPresent: ['Query']
   Root: {
     Query: Schema.Root.Query
     Mutation: null

examples/$/generated-clients/atlas/modules/SchemaRuntime.ts

@@ -100,6 +100,7 @@ export const Query = $.Object$(`Query`, {
 
 export const $Index = {
   name: 'Atlas' as const,
+  RootTypesPresent: ['Query'] as const,
   Root: {
     Query,
     Mutation: null,

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

@@ -4,6 +4,7 @@ import type * as Schema from './SchemaBuildtime.js'
 
 export interface Index {
   name: 'Pokemon'
+  RootTypesPresent: ['Query', 'Mutation']
   Root: {
     Query: Schema.Root.Query
     Mutation: Schema.Root.Mutation

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

@@ -47,6 +47,7 @@ export const Query = $.Object$(`Query`, {
 
 export const $Index = {
   name: 'Pokemon' as const,
+  RootTypesPresent: ['Query', 'Mutation'] as const,
   Root: {
     Query,
     Mutation,

examples/$/show.ts

@@ -6,28 +6,27 @@ type Logger = typeof console.log | typeof globalThis.process.stdout.write
 
 export const show = <$Logger extends Logger = typeof console.log>(
   value: unknown,
-  logger?: $Logger,
+  subTitle?: string,
 ): ReturnType<$Logger> => {
-  const write = logger ?? console.log
+  const write = console.log
   const inspected = inspect(value, { depth: null, colors: true })
-  const message = renderShow(inspected)
+  const message = renderShow(inspected, subTitle)
   return write(message) as ReturnType<$Logger>
 }
 
 export const showJson = <$Logger extends Logger = typeof console.log>(
   value: unknown,
-  logger?: $Logger,
 ): ReturnType<$Logger> => {
-  const write = logger ?? console.log
+  const write = console.log
   const encoded = JSON.stringify(value, null, 2)
   const message = renderShow(encoded)
   return write(message) as ReturnType<$Logger>
 }
 
 export const showPartition = `---------------------------------------- SHOW ----------------------------------------`
 
-const renderShow = (value: string) => {
-  return showPartition + '\n' + value
+const renderShow = (value: string, subTitle?: string) => {
+  return showPartition + (subTitle ? `\n${subTitle}` : '') + '\n' + value
 }
 
 export const interceptAndShowOutput = (): void => {
@@ -37,3 +36,10 @@ export const interceptAndShowOutput = (): void => {
     return originalWrite(renderShow(value))
   }
 }
+
+export const interceptAndShowUncaughtErrors = () => {
+  process.on('uncaughtException', (error) => {
+    show(error, 'UNCAUGHT EXCEPTION:\n')
+    process.exit(1)
+  })
+}

examples/__outputs__/extension|extension_opentelemetry.output.txt

@@ -9,14 +9,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '93ece70aa164958fd1b3d3c6c89e9f70',
-  parentId: 'e3b3fd57f531674b',
+  traceId: '62449852d475be9dce6a74f0b0555f54',
+  parentId: 'b3ba100af8bce057',
   traceState: undefined,
   name: 'encode',
-  id: '0f8e4e2d2fa7a1d1',
+  id: 'bcca0b855b22b8af',
   kind: 0,
-  timestamp: 1726068743834000,
-  duration: 442.792,
+  timestamp: 1726346409548000,
+  duration: 448.042,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -33,14 +33,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '93ece70aa164958fd1b3d3c6c89e9f70',
-  parentId: 'e3b3fd57f531674b',
+  traceId: '62449852d475be9dce6a74f0b0555f54',
+  parentId: 'b3ba100af8bce057',
   traceState: undefined,
   name: 'pack',
-  id: '37766e2e0fa6ea2e',
+  id: '884350df7488294f',
   kind: 0,
-  timestamp: 1726068743836000,
-  duration: 808.5,
+  timestamp: 1726346409551000,
+  duration: 1024.667,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -57,14 +57,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '93ece70aa164958fd1b3d3c6c89e9f70',
-  parentId: 'e3b3fd57f531674b',
+  traceId: '62449852d475be9dce6a74f0b0555f54',
+  parentId: 'b3ba100af8bce057',
   traceState: undefined,
   name: 'exchange',
-  id: 'ed9ae7aad6fd1e69',
+  id: 'c5b5c072b7c8c20d',
   kind: 0,
-  timestamp: 1726068743837000,
-  duration: 329989.458,
+  timestamp: 1726346409553000,
+  duration: 194155.958,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -81,14 +81,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '93ece70aa164958fd1b3d3c6c89e9f70',
-  parentId: 'e3b3fd57f531674b',
+  traceId: '62449852d475be9dce6a74f0b0555f54',
+  parentId: 'b3ba100af8bce057',
   traceState: undefined,
   name: 'unpack',
-  id: 'd0d9cbd74e358490',
+  id: '6956cc361339e79b',
   kind: 0,
-  timestamp: 1726068744168000,
-  duration: 1907.291,
+  timestamp: 1726346409747000,
+  duration: 4696.875,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -105,14 +105,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '93ece70aa164958fd1b3d3c6c89e9f70',
-  parentId: 'e3b3fd57f531674b',
+  traceId: '62449852d475be9dce6a74f0b0555f54',
+  parentId: 'b3ba100af8bce057',
   traceState: undefined,
   name: 'decode',
-  id: '51a5859eae82dd62',
+  id: '5093bc556bcde250',
   kind: 0,
-  timestamp: 1726068744170000,
-  duration: 97.958,
+  timestamp: 1726346409753000,
+  duration: 286.459,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -129,14 +129,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '93ece70aa164958fd1b3d3c6c89e9f70',
+  traceId: '62449852d475be9dce6a74f0b0555f54',
   parentId: undefined,
   traceState: undefined,
   name: 'request',
-  id: 'e3b3fd57f531674b',
+  id: 'b3ba100af8bce057',
   kind: 0,
-  timestamp: 1726068743834000,
-  duration: 336135.125,
+  timestamp: 1726346409547000,
+  duration: 205724.167,
   attributes: {},
   status: { code: 0 },
   events: [],

examples/__outputs__/extension|extension_or-throw.output.txt

@@ -0,0 +1,36 @@
+---------------------------------------- SHOW ----------------------------------------
+ContextualError: There was an error in the extension "anonymous" (use named functions to improve this error message) while running hook "encode".
+    at runPipeline (/some/path/to/runPipeline.ts:XX:XX)
+    at async Object.run (/some/path/to/main.ts:XX:XX)
+    at async run (/some/path/to/client.ts:XX:XX)
+    at async executeRootType (/some/path/to/client.ts:XX:XX)
+    at async executeRootTypeField (/some/path/to/client.ts:XX:XX)
+    at async <anonymous> (/some/path/to/extension|extension_or-throw.ts:XX:XX) {
+  context: {
+    hookName: 'encode',
+    source: 'extension',
+    extensionName: 'anonymous'
+  },
+  cause: Error: Something went wrong.
+      at <anonymous> (/some/path/to/extension|extension_or-throw.ts:XX:XX)
+      at applyBody (/some/path/to/main.ts:XX:XX)
+}
+---------------------------------------- SHOW ----------------------------------------
+UNCAUGHT EXCEPTION:
+
+ContextualError: There was an error in the extension "anonymous" (use named functions to improve this error message) while running hook "encode".
+    at runPipeline (/some/path/to/runPipeline.ts:XX:XX)
+    at async Object.run (/some/path/to/main.ts:XX:XX)
+    at async run (/some/path/to/client.ts:XX:XX)
+    at async executeRootType (/some/path/to/client.ts:XX:XX)
+    at async executeRootTypeField (/some/path/to/client.ts:XX:XX)
+    at async <anonymous> (/some/path/to/extension|extension_or-throw.ts:XX:XX) {
+  context: {
+    hookName: 'encode',
+    source: 'extension',
+    extensionName: 'anonymous'
+  },
+  cause: Error: Something went wrong.
+      at <anonymous> (/some/path/to/extension|extension_or-throw.ts:XX:XX)
+      at applyBody (/some/path/to/main.ts:XX:XX)
+}

examples/__outputs__/other|transport-memory.output.txt

@@ -1,6 +1,4 @@
 ---------------------------------------- SHOW ----------------------------------------
 {
-  "data": {
-    "foo": "bar"
-  }
+  "foo": "bar"
 }

examples/__outputs__/output|output_envelope.output.txt

@@ -19,7 +19,7 @@
     headers: Headers {
       connection: 'keep-alive',
       'content-length': '119',
-      'x-served-by': 'cache-yul1970045-YUL',
+      'x-served-by': 'cache-yul1970038-YUL',
       'accept-ranges': 'bytes',
       date: 'Sun, 08 Sep 2024 18:13:26 GMT',
       'content-type': 'application/graphql-response+json; charset=utf-8',
@@ -32,13 +32,13 @@
       'alt-svc': 'h3=":443"; ma=86400',
       'access-control-allow-origin': '*',
       'x-powered-by': 'Stellate',
-      age: '249539',
+      age: '527204',
       'cache-control': 'public, s-maxage=2628000, stale-while-revalidate=2628000',
       'x-cache': 'HIT',
-      'x-cache-hits': '5',
+      'x-cache-hits': '33',
       'gcdn-cache': 'HIT',
-      'stellate-rate-limit-budget-remaining': '41',
-      'stellate-rate-limit-rules': '"IP limit";type="RequestCount";budget=50;limited=?0;remaining=41;refill=60',
+      'stellate-rate-limit-budget-remaining': '46',
+      'stellate-rate-limit-rules': '"IP limit";type="RequestCount";budget=50;limited=?0;remaining=46;refill=60',
       'stellate-rate-limit-decision': 'pass',
       'stellate-rate-limit-budget-required': '5',
       'content-encoding': 'br'

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

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

@@ -21,7 +21,7 @@
     searchParams: URLSearchParams {},
     hash: ''
   },
-  body: '{"query":"mutation addPokemon(attack:0, defense:0, hp:1, name:\\"Nano\\") { name }"}'
+  body: '{"query":"mutation { addPokemon(attack:0, defense:0, hp:1, name:\\"Nano\\") { name } }"}'
 }
 ---------------------------------------- SHOW ----------------------------------------
 {

examples/extension|extension_opentelemetry.ts

@@ -16,5 +16,5 @@ provider.addSpanProcessor(processor)
 provider.register()
 
 const graffle = Atlas.create().use(Opentelemetry())
-const result = await graffle.rawString({ document: `query { continents { name } }` })
-show(result.data)
+const data = await graffle.rawString({ document: `query { continents { name } }` })
+show(data)

examples/extension|extension_or-throw.ts

@@ -0,0 +1,22 @@
+/**
+ * This example shows how to use the Or Throw extension to throw errors for one-off cases.
+ */
+
+import { OrThrow } from '../src/entrypoints/extensions.js'
+import { Atlas } from './$/generated-clients/atlas/__.js'
+import { interceptAndShowUncaughtErrors, show } from './$/show.js'
+
+interceptAndShowUncaughtErrors()
+
+const atlas = Atlas
+  .create({ output: { defaults: { errorChannel: `return` } } })
+  .use(OrThrow())
+  .anyware(({ encode: _ }) => {
+    throw new Error(`Something went wrong.`)
+  })
+
+const result1 = await atlas.query.continents({ name: true })
+show(result1)
+
+const result2 = await atlas.query.continentsOrThrow({ name: true })
+result2 // This line will never be reached because of thrown error.

examples/other|transport-memory.ts

@@ -20,6 +20,6 @@ const schema = new GraphQLSchema({
 
 const graffle = Graffle.create({ schema })
 
-const result = await graffle.rawString({ document: `{ foo }` })
+const data = await graffle.rawString({ document: `{ foo }` })
 
-showJson(result)
+showJson(data)

examples/output|output_default.ts

@@ -7,6 +7,6 @@ import { show } from './$/helpers.js'
 
 const atlas = Atlas.create()
 
-const result = await atlas.query.continents({ name: true })
+const continents = await atlas.query.continents({ name: true })
 
-show(result)
+show(continents)

examples/output|output_envelope_envelope-error__envelope-error.ts

@@ -18,7 +18,7 @@ const atlas = Atlas
       },
     },
   })
-  .use(({ encode: _ }) => {
+  .anyware(({ encode: _ }) => {
     throw new Error(`Something went wrong.`)
   //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   })

examples/output|output_envelope_envelope_error-throw__envelope-error-throw.ts

@@ -5,18 +5,20 @@
 import { Atlas } from './$/generated-clients/atlas/__.js'
 
 // dprint-ignore
-const atlas = Atlas.create({
-  output: {
-    envelope: {
-      errors: {
-        execution: false,
-        other: false, // default
-      }
+const atlas = Atlas
+  .create({
+    output: {
+      envelope: {
+        errors: {
+          execution: false,
+          other: false, // default
+        }
+      },
     },
-  },
-}).use(({ encode: _ }) => {
-  throw new Error(`Something went wrong.`)
-//^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-})
+  })
+  .anyware(({ encode: _ }) => {
+    throw new Error(`Something went wrong.`)
+  //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  })
 
 await atlas.query.continents({ name: true })