+5

.changeset/gold-apricots-report.md

··· 1 1 + --- 2 2 + "@0no-co/graphql.web": minor 3 3 + --- 4 4 + 5 5 + Add support for executable definitions as defined in https://github.com/graphql/graphql-spec/pull/1170

+278

src/__tests__/description.test.ts

··· 1 1 + import { describe, it, expect } from 'vitest'; 2 2 + import { parse } from '../parser'; 3 3 + import { print } from '../printer'; 4 4 + import type { 5 5 + OperationDefinitionNode, 6 6 + VariableDefinitionNode, 7 7 + FragmentDefinitionNode, 8 8 + } from '../ast'; 9 9 + 10 10 + describe('GraphQL descriptions', () => { 11 11 + describe('OperationDefinition descriptions', () => { 12 12 + it('parses operation with description', () => { 13 13 + const source = ` 14 14 + """ 15 15 + Request the current status of a time machine and its operator. 16 16 + """ 17 17 + query GetTimeMachineStatus { 18 18 + timeMachine { 19 19 + id 20 20 + status 21 21 + } 22 22 + } 23 23 + `; 24 24 + 25 25 + const doc = parse(source, { noLocation: true }); 26 26 + const operation = doc.definitions[0] as OperationDefinitionNode; 27 27 + 28 28 + expect(operation.description).toBeDefined(); 29 29 + expect(operation.description?.value).toBe( 30 30 + 'Request the current status of a time machine and its operator.' 31 31 + ); 32 32 + expect(operation.description?.block).toBe(true); 33 33 + }); 34 34 + 35 35 + it('parses operation with single-line description', () => { 36 36 + const source = ` 37 37 + "Simple query description" 38 38 + query SimpleQuery { 39 39 + field 40 40 + } 41 41 + `; 42 42 + 43 43 + const doc = parse(source, { noLocation: true }); 44 44 + const operation = doc.definitions[0] as OperationDefinitionNode; 45 45 + 46 46 + expect(operation.description).toBeDefined(); 47 47 + expect(operation.description?.value).toBe('Simple query description'); 48 48 + expect(operation.description?.block).toBe(false); 49 49 + }); 50 50 + 51 51 + it('does not allow description on anonymous operations', () => { 52 52 + const source = ` 53 53 + "This should fail" 54 54 + { 55 55 + field 56 56 + } 57 57 + `; 58 58 + 59 59 + expect(() => parse(source)).toThrow(); 60 60 + }); 61 61 + 62 62 + it('parses mutation with description', () => { 63 63 + const source = ` 64 64 + """ 65 65 + Create a new time machine entry. 66 66 + """ 67 67 + mutation CreateTimeMachine($input: TimeMachineInput!) { 68 68 + createTimeMachine(input: $input) { 69 69 + id 70 70 + } 71 71 + } 72 72 + `; 73 73 + 74 74 + const doc = parse(source, { noLocation: true }); 75 75 + const operation = doc.definitions[0] as OperationDefinitionNode; 76 76 + 77 77 + expect(operation.description).toBeDefined(); 78 78 + expect(operation.description?.value).toBe('Create a new time machine entry.'); 79 79 + }); 80 80 + }); 81 81 + 82 82 + describe('VariableDefinition descriptions', () => { 83 83 + it('parses variable with description', () => { 84 84 + const source = ` 85 85 + query GetTimeMachineStatus( 86 86 + "The unique serial number of the time machine to inspect." 87 87 + $machineId: ID! 88 88 + 89 89 + """ 90 90 + The year to check the status for. 91 91 + **Warning:** certain years may trigger an anomaly in the space-time continuum. 92 92 + """ 93 93 + $year: Int 94 94 + ) { 95 95 + timeMachine(id: $machineId) { 96 96 + status(year: $year) 97 97 + } 98 98 + } 99 99 + `; 100 100 + 101 101 + const doc = parse(source, { noLocation: true }); 102 102 + const operation = doc.definitions[0] as OperationDefinitionNode; 103 103 + const variables = operation.variableDefinitions as VariableDefinitionNode[]; 104 104 + 105 105 + expect(variables[0].description).toBeDefined(); 106 106 + expect(variables[0].description?.value).toBe( 107 107 + 'The unique serial number of the time machine to inspect.' 108 108 + ); 109 109 + expect(variables[0].description?.block).toBe(false); 110 110 + 111 111 + expect(variables[1].description).toBeDefined(); 112 112 + expect(variables[1].description?.value).toBe( 113 113 + 'The year to check the status for.\n**Warning:** certain years may trigger an anomaly in the space-time continuum.' 114 114 + ); 115 115 + expect(variables[1].description?.block).toBe(true); 116 116 + }); 117 117 + 118 118 + it('parses mixed variables with and without descriptions', () => { 119 119 + const source = ` 120 120 + query Mixed( 121 121 + "Described variable" 122 122 + $described: String 123 123 + $undescribed: Int 124 124 + ) { 125 125 + field 126 126 + } 127 127 + `; 128 128 + 129 129 + const doc = parse(source, { noLocation: true }); 130 130 + const operation = doc.definitions[0] as OperationDefinitionNode; 131 131 + const variables = operation.variableDefinitions as VariableDefinitionNode[]; 132 132 + 133 133 + expect(variables[0].description).toBeDefined(); 134 134 + expect(variables[0].description?.value).toBe('Described variable'); 135 135 + expect(variables[1].description).toBeUndefined(); 136 136 + }); 137 137 + }); 138 138 + 139 139 + describe('FragmentDefinition descriptions', () => { 140 140 + it('parses fragment with description', () => { 141 141 + const source = ` 142 142 + "Time machine details." 143 143 + fragment TimeMachineDetails on TimeMachine { 144 144 + id 145 145 + model 146 146 + lastMaintenance 147 147 + } 148 148 + `; 149 149 + 150 150 + const doc = parse(source, { noLocation: true }); 151 151 + const fragment = doc.definitions[0] as FragmentDefinitionNode; 152 152 + 153 153 + expect(fragment.description).toBeDefined(); 154 154 + expect(fragment.description?.value).toBe('Time machine details.'); 155 155 + expect(fragment.description?.block).toBe(false); 156 156 + }); 157 157 + 158 158 + it('parses fragment with block description', () => { 159 159 + const source = ` 160 160 + """ 161 161 + Comprehensive time machine information 162 162 + including maintenance history and operational status. 163 163 + """ 164 164 + fragment FullTimeMachineInfo on TimeMachine { 165 165 + id 166 166 + model 167 167 + lastMaintenance 168 168 + operationalStatus 169 169 + } 170 170 + `; 171 171 + 172 172 + const doc = parse(source, { noLocation: true }); 173 173 + const fragment = doc.definitions[0] as FragmentDefinitionNode; 174 174 + 175 175 + expect(fragment.description).toBeDefined(); 176 176 + expect(fragment.description?.value).toBe( 177 177 + 'Comprehensive time machine information\nincluding maintenance history and operational status.' 178 178 + ); 179 179 + expect(fragment.description?.block).toBe(true); 180 180 + }); 181 181 + }); 182 182 + 183 183 + describe('print with descriptions', () => { 184 184 + it('prints operation description correctly', () => { 185 185 + const source = `""" 186 186 + Request the current status of a time machine and its operator. 187 187 + """ 188 188 + query GetTimeMachineStatus { 189 189 + timeMachine { 190 190 + id 191 191 + } 192 192 + }`; 193 193 + 194 194 + const doc = parse(source, { noLocation: true }); 195 195 + const printed = print(doc); 196 196 + 197 197 + expect(printed).toContain('"""'); 198 198 + expect(printed).toContain('Request the current status of a time machine and its operator.'); 199 199 + }); 200 200 + 201 201 + it('prints variable descriptions correctly', () => { 202 202 + const source = `query GetStatus( 203 203 + "Machine ID" 204 204 + $id: ID! 205 205 + ) { 206 206 + field 207 207 + }`; 208 208 + 209 209 + const doc = parse(source, { noLocation: true }); 210 210 + const printed = print(doc); 211 211 + 212 212 + expect(printed).toContain('"Machine ID"'); 213 213 + }); 214 214 + 215 215 + it('prints fragment description correctly', () => { 216 216 + const source = `"Details fragment" 217 217 + fragment Details on Type { 218 218 + field 219 219 + }`; 220 220 + 221 221 + const doc = parse(source, { noLocation: true }); 222 222 + const printed = print(doc); 223 223 + 224 224 + expect(printed).toContain('"Details fragment"'); 225 225 + }); 226 226 + }); 227 227 + 228 228 + describe('roundtrip parsing and printing', () => { 229 229 + it('maintains descriptions through parse and print cycle', () => { 230 230 + const source = `""" 231 231 + Request the current status of a time machine and its operator. 232 232 + """ 233 233 + query GetTimeMachineStatus( 234 234 + "The unique serial number of the time machine to inspect." 235 235 + $machineId: ID! 236 236 + 237 237 + """ 238 238 + The year to check the status for. 239 239 + **Warning:** certain years may trigger an anomaly in the space-time continuum. 240 240 + """ 241 241 + $year: Int 242 242 + ) { 243 243 + timeMachine(id: $machineId) { 244 244 + ...TimeMachineDetails 245 245 + operator { 246 246 + name 247 247 + licenseLevel 248 248 + } 249 249 + status(year: $year) 250 250 + } 251 251 + } 252 252 + 253 253 + "Time machine details." 254 254 + fragment TimeMachineDetails on TimeMachine { 255 255 + id 256 256 + model 257 257 + lastMaintenance 258 258 + }`; 259 259 + 260 260 + const doc = parse(source, { noLocation: true }); 261 261 + const printed = print(doc); 262 262 + const reparsed = parse(printed, { noLocation: true }); 263 263 + 264 264 + const operation = doc.definitions[0] as OperationDefinitionNode; 265 265 + const reparsedOperation = reparsed.definitions[0] as OperationDefinitionNode; 266 266 + 267 267 + // The printed/reparsed cycle may have slightly different formatting but same content 268 268 + expect(reparsedOperation.description?.value?.trim()).toBe( 269 269 + operation.description?.value?.trim() 270 270 + ); 271 271 + 272 272 + const fragment = doc.definitions[1] as FragmentDefinitionNode; 273 273 + const reparsedFragment = reparsed.definitions[1] as FragmentDefinitionNode; 274 274 + 275 275 + expect(reparsedFragment.description?.value).toBe(fragment.description?.value); 276 276 + }); 277 277 + }); 278 278 + });

+6 -3

src/ast.ts

··· 103 103 >; 104 104 105 105 export type OperationDefinitionNode = Or< 106 106 - GraphQL.OperationDefinitionNode, 106 106 + GraphQL.OperationDefinitionNode & { description?: StringValueNode }, 107 107 { 108 108 readonly kind: Kind.OPERATION_DEFINITION; 109 109 readonly operation: OperationTypeNode; 110 110 readonly name?: NameNode; 111 111 + readonly description?: StringValueNode; 111 112 readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>; 112 113 readonly directives?: ReadonlyArray<DirectiveNode>; 113 114 readonly selectionSet: SelectionSetNode; ··· 116 117 >; 117 118 118 119 export type VariableDefinitionNode = Or< 119 119 - GraphQL.VariableDefinitionNode, 120 120 + GraphQL.VariableDefinitionNode & { description?: StringValueNode }, 120 121 { 121 122 readonly kind: Kind.VARIABLE_DEFINITION; 122 123 readonly variable: VariableNode; 123 124 readonly type: TypeNode; 124 125 readonly defaultValue?: ConstValueNode; 126 126 + readonly description?: StringValueNode; 125 127 readonly directives?: ReadonlyArray<ConstDirectiveNode>; 126 128 readonly loc?: Location; 127 129 } ··· 205 207 >; 206 208 207 209 export type FragmentDefinitionNode = Or< 208 208 - GraphQL.FragmentDefinitionNode, 210 210 + GraphQL.FragmentDefinitionNode & { description?: StringValueNode }, 209 211 { 210 212 readonly kind: Kind.FRAGMENT_DEFINITION; 211 213 readonly name: NameNode; 214 214 + readonly description?: StringValueNode; 212 215 readonly typeCondition: NamedTypeNode; 213 216 readonly directives?: ReadonlyArray<DirectiveNode>; 214 217 readonly selectionSet: SelectionSetNode;

+29 -7

src/parser.ts

··· 421 421 idx++; 422 422 ignored(); 423 423 do { 424 424 + let _description: ast.StringValueNode | undefined; 425 425 + if (input.charCodeAt(idx) === 34 /*'"'*/) { 426 426 + _description = value(true) as ast.StringValueNode; 427 427 + } 424 428 if (input.charCodeAt(idx++) !== 36 /*'$'*/) throw error('Variable'); 425 429 const name = nameNode(); 426 430 if (input.charCodeAt(idx++) !== 58 /*':'*/) throw error('VariableDefinition'); ··· 433 437 _defaultValue = value(true); 434 438 } 435 439 ignored(); 436 436 - vars.push({ 440 440 + const varDef: ast.VariableDefinitionNode = { 437 441 kind: 'VariableDefinition' as Kind.VARIABLE_DEFINITION, 438 442 variable: { 439 443 kind: 'Variable' as Kind.VARIABLE, ··· 442 446 type: _type, 443 447 defaultValue: _defaultValue, 444 448 directives: directives(true), 445 445 - }); 449 449 + }; 450 450 + if (_description) { 451 451 + varDef.description = _description; 452 452 + } 453 453 + vars.push(varDef); 446 454 } while (input.charCodeAt(idx) !== 41 /*')'*/); 447 455 idx++; 448 456 ignored(); ··· 450 458 } 451 459 } 452 460 453 453 - function fragmentDefinition(): ast.FragmentDefinitionNode { 461 461 + function fragmentDefinition(description?: ast.StringValueNode): ast.FragmentDefinitionNode { 454 462 const name = nameNode(); 455 463 if (input.charCodeAt(idx++) !== 111 /*'o'*/ || input.charCodeAt(idx++) !== 110 /*'n'*/) 456 464 throw error('FragmentDefinition'); 457 465 ignored(); 458 458 - return { 466 466 + const fragDef: ast.FragmentDefinitionNode = { 459 467 kind: 'FragmentDefinition' as Kind.FRAGMENT_DEFINITION, 460 468 name, 461 469 typeCondition: { ··· 465 473 directives: directives(false), 466 474 selectionSet: selectionSetStart(), 467 475 }; 476 476 + if (description) { 477 477 + fragDef.description = description; 478 478 + } 479 479 + return fragDef; 468 480 } 469 481 470 482 function definitions(): ast.DefinitionNode[] { 471 483 const _definitions: ast.ExecutableDefinitionNode[] = []; 472 484 do { 485 485 + let _description: ast.StringValueNode | undefined; 486 486 + if (input.charCodeAt(idx) === 34 /*'"'*/) { 487 487 + _description = value(true) as ast.StringValueNode; 488 488 + } 473 489 if (input.charCodeAt(idx) === 123 /*'{'*/) { 490 490 + // Anonymous operations can't have descriptions 491 491 + if (_description) throw error('Document'); 474 492 idx++; 475 493 ignored(); 476 494 _definitions.push({ ··· 485 503 const definition = name(); 486 504 switch (definition) { 487 505 case 'fragment': 488 488 - _definitions.push(fragmentDefinition()); 506 506 + _definitions.push(fragmentDefinition(_description)); 489 507 break; 490 508 case 'query': 491 509 case 'mutation': ··· 499 517 ) { 500 518 name = nameNode(); 501 519 } 502 502 - _definitions.push({ 520 520 + const opDef: ast.OperationDefinitionNode = { 503 521 kind: 'OperationDefinition' as Kind.OPERATION_DEFINITION, 504 522 operation: definition as OperationTypeNode, 505 523 name, 506 524 variableDefinitions: variableDefinitions(), 507 525 directives: directives(false), 508 526 selectionSet: selectionSetStart(), 509 509 - }); 527 527 + }; 528 528 + if (_description) { 529 529 + opDef.description = _description; 530 530 + } 531 531 + _definitions.push(opDef); 510 532 break; 511 533 default: 512 534 throw error('Document');

+17 -6

src/printer.ts

··· 49 49 50 50 const nodes = { 51 51 OperationDefinition(node: OperationDefinitionNode): string { 52 52 - let out: string = node.operation; 52 52 + let out: string = ''; 53 53 + if (node.description) { 54 54 + out += nodes.StringValue(node.description) + '\n'; 55 55 + } 56 56 + out += node.operation; 53 57 if (node.name) out += ' ' + node.name.value; 54 58 if (node.variableDefinitions && node.variableDefinitions.length) { 55 59 if (!node.name) out += ' '; ··· 57 61 } 58 62 if (node.directives && node.directives.length) 59 63 out += ' ' + mapJoin(node.directives, ' ', nodes.Directive); 60 60 - return out !== 'query' 61 61 - ? out + ' ' + nodes.SelectionSet(node.selectionSet) 62 62 - : nodes.SelectionSet(node.selectionSet); 64 64 + const selectionSet = nodes.SelectionSet(node.selectionSet); 65 65 + return out !== 'query' ? out + ' ' + selectionSet : selectionSet; 63 66 }, 64 67 VariableDefinition(node: VariableDefinitionNode): string { 65 65 - let out = nodes.Variable!(node.variable) + ': ' + _print(node.type); 68 68 + let out = ''; 69 69 + if (node.description) { 70 70 + out += nodes.StringValue(node.description) + ' '; 71 71 + } 72 72 + out += nodes.Variable!(node.variable) + ': ' + _print(node.type); 66 73 if (node.defaultValue) out += ' = ' + _print(node.defaultValue); 67 74 if (node.directives && node.directives.length) 68 75 out += ' ' + mapJoin(node.directives, ' ', nodes.Directive); ··· 152 159 return out; 153 160 }, 154 161 FragmentDefinition(node: FragmentDefinitionNode): string { 155 155 - let out = 'fragment ' + node.name.value; 162 162 + let out = ''; 163 163 + if (node.description) { 164 164 + out += nodes.StringValue(node.description) + '\n'; 165 165 + } 166 166 + out += 'fragment ' + node.name.value; 156 167 out += ' on ' + node.typeCondition.name.value; 157 168 if (node.directives && node.directives.length) 158 169 out += ' ' + mapJoin(node.directives, ' ', nodes.Directive);