[{"data":1,"prerenderedAt":909},["ShallowReactive",2],{"page:\u002Fdocs\u002F5.x\u002Fhow-to\u002Fmacros":3},{"id":4,"title":5,"body":6,"description":893,"extension":894,"frontmatter":895,"heading":5,"meta":901,"navigation":902,"order":898,"path":903,"seo":904,"sitemap":905,"source":906,"stem":907,"__hash__":908},"docs\u002Fdocs\u002F5.x\u002Fhow-to\u002Fmacros.md","Transform schemas with macros",{"type":7,"value":8,"toc":885},"minimark",[9,13,31,36,39,197,208,375,379,398,638,645,648,659,664,681,685,697,882],[10,11,12],"p",{},"Use a macro to transform schema or operation nodes before generation. Macros can rename symbols, change field types, or remove metadata across output targets.",[10,14,15,16,20,21,24,25,30],{},"Import the macro engine through ",[17,18,19],"code",{},"ast"," from ",[17,22,23],{},"kubb\u002Fkit",". For callback signatures and context properties, see the ",[26,27,29],"a",{"href":28},"\u002Fdocs\u002F5.x\u002Freference\u002Fkit\u002Fast#macros","AST reference",".",[32,33,35],"h2",{"id":34},"writing-a-macro","Writing a macro",[10,37,38],{},"Define the node transformation:",[40,41,46],"pre",{"language":42,"filename":43,"code":44,"class":45},"typescript","macro.ts","import { ast } from 'kubb\u002Fkit'\n\nconst macroIntegerToString = ast.defineMacro({\n  name: 'integer-to-string',\n  schema(node) {\n    return node.type === 'integer' ? { ...node, type: 'string' } : undefined\n  },\n})","highlights",[17,47,49,76,77,76,79,76,101,76,118,76,134,76,183,76,192],{"class":48},"language-typescript",[50,51,54,58,62,66,69,72],"span",{"class":52,"style":53},"line","display: inline",[50,55,57],{"style":56},"color:#d73a49;--hls-dark:#f97583","import ",[50,59,61],{"style":60},"color:#005cc5;--hls-dark:#79b8ff","{ ",[50,63,65],{"style":64},"color:#24292e;--hls-dark:#e1e4e8","ast ",[50,67,68],{"style":60},"} ",[50,70,71],{"style":56},"from ",[50,73,75],{"style":74},"color:#032f62;--hls-dark:#9ecbff","'kubb\u002Fkit'","\n",[50,78],{"class":52,"style":53},[50,80,81,84,87,90,92,94,98],{"class":52,"style":53},[50,82,83],{"style":56},"const ",[50,85,86],{"style":64},"macroIntegerToString ",[50,88,89],{"style":56},"= ",[50,91,19],{"style":64},[50,93,30],{"style":56},[50,95,97],{"style":96},"color:#6f42c1;--hls-dark:#b392f0","defineMacro",[50,99,100],{"style":60},"({",[50,102,103,106,109,112,115],{"class":52,"style":53},[50,104,105],{"style":60},"  ",[50,107,108],{"style":60},"name",[50,110,111],{"style":56},": ",[50,113,114],{"style":74},"'integer-to-string'",[50,116,117],{"style":56},",",[50,119,120,122,125,128,131],{"class":52,"style":53},[50,121,105],{"style":56},[50,123,124],{"style":96},"schema",[50,126,127],{"style":60},"(",[50,129,130],{"style":64},"node",[50,132,133],{"style":60},") {",[50,135,136,139,142,144,146,149,152,155,158,160,163,165,168,171,173,176,178,180],{"class":52,"style":53},[50,137,138],{"style":60},"    ",[50,140,141],{"style":56},"return ",[50,143,130],{"style":64},[50,145,30],{"style":56},[50,147,148],{"style":60},"type ",[50,150,151],{"style":56},"=== ",[50,153,154],{"style":74},"'integer' ",[50,156,157],{"style":56},"? ",[50,159,61],{"style":60},[50,161,162],{"style":56},"...",[50,164,130],{"style":64},[50,166,167],{"style":56},", ",[50,169,170],{"style":60},"type",[50,172,111],{"style":56},[50,174,175],{"style":74},"'string' ",[50,177,68],{"style":60},[50,179,111],{"style":56},[50,181,182],{"style":60},"undefined",[50,184,185,187,190],{"class":52,"style":53},[50,186,105],{"style":60},[50,188,189],{"style":60},"}",[50,191,117],{"style":56},[50,193,194],{"class":52,"style":53},[50,195,196],{"style":60},"})",[10,198,199,200,203,204,207],{},"The ",[17,201,202],{},"match"," predicate skips a macro for nodes it does not care about, and ",[17,205,206],{},"enforce"," places a macro before or after the unmarked ones.",[40,209,212],{"language":42,"filename":210,"code":211,"class":45},"enforce.ts","import { ast } from 'kubb\u002Fkit'\n\nconst macroUntagged = ast.defineMacro({\n  name: 'untagged',\n  enforce: 'post',\n  match: (node) => node.kind === 'Operation',\n  operation(node) {\n    return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }\n  },\n})",[17,213,214,76,228,76,230,76,247,76,260,76,273,76,305,76,318,76,364,76,371],{"class":48},[50,215,216,218,220,222,224,226],{"class":52,"style":53},[50,217,57],{"style":56},[50,219,61],{"style":60},[50,221,65],{"style":64},[50,223,68],{"style":60},[50,225,71],{"style":56},[50,227,75],{"style":74},[50,229],{"class":52,"style":53},[50,231,232,234,237,239,241,243,245],{"class":52,"style":53},[50,233,83],{"style":56},[50,235,236],{"style":64},"macroUntagged ",[50,238,89],{"style":56},[50,240,19],{"style":64},[50,242,30],{"style":56},[50,244,97],{"style":96},[50,246,100],{"style":60},[50,248,249,251,253,255,258],{"class":52,"style":53},[50,250,105],{"style":60},[50,252,108],{"style":60},[50,254,111],{"style":56},[50,256,257],{"style":74},"'untagged'",[50,259,117],{"style":56},[50,261,262,264,266,268,271],{"class":52,"style":53},[50,263,105],{"style":56},[50,265,206],{"style":60},[50,267,111],{"style":56},[50,269,270],{"style":74},"'post'",[50,272,117],{"style":56},[50,274,275,277,279,281,283,285,288,291,293,295,298,300,303],{"class":52,"style":53},[50,276,105],{"style":56},[50,278,202],{"style":60},[50,280,111],{"style":56},[50,282,127],{"style":60},[50,284,130],{"style":64},[50,286,287],{"style":60},") ",[50,289,290],{"style":56},"=> ",[50,292,130],{"style":64},[50,294,30],{"style":56},[50,296,297],{"style":60},"kind ",[50,299,151],{"style":56},[50,301,302],{"style":74},"'Operation'",[50,304,117],{"style":56},[50,306,307,309,312,314,316],{"class":52,"style":53},[50,308,105],{"style":56},[50,310,311],{"style":96},"operation",[50,313,127],{"style":60},[50,315,130],{"style":64},[50,317,133],{"style":60},[50,319,320,322,324,326,328,331,334,337,339,342,344,346,348,350,352,354,356,359,361],{"class":52,"style":53},[50,321,138],{"style":60},[50,323,141],{"style":56},[50,325,130],{"style":64},[50,327,30],{"style":56},[50,329,330],{"style":60},"tags",[50,332,333],{"style":56},"?.",[50,335,336],{"style":60},"length ",[50,338,157],{"style":56},[50,340,341],{"style":60},"undefined ",[50,343,111],{"style":56},[50,345,61],{"style":60},[50,347,162],{"style":56},[50,349,130],{"style":64},[50,351,167],{"style":56},[50,353,330],{"style":60},[50,355,111],{"style":56},[50,357,358],{"style":60},"[",[50,360,257],{"style":74},[50,362,363],{"style":60},"] }",[50,365,366,369],{"class":52,"style":53},[50,367,368],{"style":60},"  }",[50,370,117],{"style":56},[50,372,373],{"class":52,"style":53},[50,374,196],{"style":60},[32,376,378],{"id":377},"using-macros-in-a-plugin","Using macros in a plugin",[10,380,381,382,385,386,389,390,393,394,397],{},"Pass macros through a plugin's ",[17,383,384],{},"macros"," option, or register them from ",[17,387,388],{},"setup"," with ",[17,391,392],{},"addMacro"," and ",[17,395,396],{},"setMacros",". Macros run per plugin, so one plugin's macros never change the nodes another plugin sees.",[40,399,402],{"language":42,"filename":400,"code":401,"class":45},"plugin.ts","import { ast, defineExtension } from 'kubb\u002Fkit'\n\nconst macroDropDescriptions = ast.defineMacro({\n  name: 'drop-descriptions',\n  schema(node) {\n    return 'description' in node && node.description ? { ...node, description: undefined } : undefined\n  },\n})\n\nexport const pluginRename = defineExtension({\n  kind: 'plugin',\n  meta: { name: 'plugin-rename' },\n  setup(options, kubb) {\n    kubb.addMacro(macroDropDescriptions)\n    return options\n  },\n})",[17,403,404,76,423,76,425,76,442,76,455,76,467,76,515,76,523,76,527,76,529,76,546,76,560,76,582,76,600,76,618,76,626,76,634],{"class":48},[50,405,406,408,410,412,414,417,419,421],{"class":52,"style":53},[50,407,57],{"style":56},[50,409,61],{"style":60},[50,411,19],{"style":64},[50,413,167],{"style":56},[50,415,416],{"style":64},"defineExtension ",[50,418,68],{"style":60},[50,420,71],{"style":56},[50,422,75],{"style":74},[50,424],{"class":52,"style":53},[50,426,427,429,432,434,436,438,440],{"class":52,"style":53},[50,428,83],{"style":56},[50,430,431],{"style":64},"macroDropDescriptions ",[50,433,89],{"style":56},[50,435,19],{"style":64},[50,437,30],{"style":56},[50,439,97],{"style":96},[50,441,100],{"style":60},[50,443,444,446,448,450,453],{"class":52,"style":53},[50,445,105],{"style":60},[50,447,108],{"style":60},[50,449,111],{"style":56},[50,451,452],{"style":74},"'drop-descriptions'",[50,454,117],{"style":56},[50,456,457,459,461,463,465],{"class":52,"style":53},[50,458,105],{"style":56},[50,460,124],{"style":96},[50,462,127],{"style":60},[50,464,130],{"style":64},[50,466,133],{"style":60},[50,468,469,471,473,476,479,482,485,487,489,492,494,496,498,500,502,505,507,509,511,513],{"class":52,"style":53},[50,470,138],{"style":60},[50,472,141],{"style":56},[50,474,475],{"style":74},"'description' ",[50,477,478],{"style":56},"in ",[50,480,481],{"style":64},"node ",[50,483,484],{"style":56},"&& ",[50,486,130],{"style":64},[50,488,30],{"style":56},[50,490,491],{"style":60},"description ",[50,493,157],{"style":56},[50,495,61],{"style":60},[50,497,162],{"style":56},[50,499,130],{"style":64},[50,501,167],{"style":56},[50,503,504],{"style":60},"description",[50,506,111],{"style":56},[50,508,341],{"style":60},[50,510,68],{"style":60},[50,512,111],{"style":56},[50,514,182],{"style":60},[50,516,517,519,521],{"class":52,"style":53},[50,518,105],{"style":60},[50,520,189],{"style":60},[50,522,117],{"style":56},[50,524,525],{"class":52,"style":53},[50,526,196],{"style":60},[50,528],{"class":52,"style":53},[50,530,531,534,536,539,541,544],{"class":52,"style":53},[50,532,533],{"style":56},"export ",[50,535,83],{"style":56},[50,537,538],{"style":64},"pluginRename ",[50,540,89],{"style":56},[50,542,543],{"style":96},"defineExtension",[50,545,100],{"style":60},[50,547,548,550,553,555,558],{"class":52,"style":53},[50,549,105],{"style":60},[50,551,552],{"style":60},"kind",[50,554,111],{"style":56},[50,556,557],{"style":74},"'plugin'",[50,559,117],{"style":56},[50,561,562,564,567,569,571,573,575,578,580],{"class":52,"style":53},[50,563,105],{"style":56},[50,565,566],{"style":60},"meta",[50,568,111],{"style":56},[50,570,61],{"style":60},[50,572,108],{"style":60},[50,574,111],{"style":56},[50,576,577],{"style":74},"'plugin-rename' ",[50,579,189],{"style":60},[50,581,117],{"style":56},[50,583,584,586,588,590,593,595,598],{"class":52,"style":53},[50,585,105],{"style":56},[50,587,388],{"style":96},[50,589,127],{"style":60},[50,591,592],{"style":64},"options",[50,594,167],{"style":56},[50,596,597],{"style":64},"kubb",[50,599,133],{"style":60},[50,601,602,604,606,608,610,612,615],{"class":52,"style":53},[50,603,138],{"style":60},[50,605,597],{"style":64},[50,607,30],{"style":56},[50,609,392],{"style":96},[50,611,127],{"style":60},[50,613,614],{"style":64},"macroDropDescriptions",[50,616,617],{"style":60},")",[50,619,620,622,624],{"class":52,"style":53},[50,621,138],{"style":60},[50,623,141],{"style":56},[50,625,592],{"style":64},[50,627,628,630,632],{"class":52,"style":53},[50,629,105],{"style":64},[50,631,189],{"style":60},[50,633,117],{"style":56},[50,635,636],{"class":52,"style":53},[50,637,196],{"style":60},[10,639,640,641,644],{},"Together, the two macros on this page turn a ",[17,642,643],{},"Pet"," schema node into the node on the right. Hover a line to see what changed it.",[646,647],"flow-diagram",{"preset":384},[10,649,650,651,654,655,658],{},"Macros run before the resolver names anything, so a renamed ",[17,652,653],{},"operationId"," or ",[17,656,657],{},"SchemaNode.name"," carries through to generated names, paths, and files.",[660,661,663],"blockquote",{"as":662},"tip","Keep macros pure. Build a new node and return it rather than mutating the input, since the AST is shared by reference.",[660,665,667,668,670,671,674,675,680],{"as":666},"warning","Do not rename a schema by changing only the declaration's ",[17,669,108],{},". Every ",[17,672,673],{},"$ref"," to it still resolves to the old name, so imports and printed references point at a file the plugin no longer emits. Use ",[26,676,677],{"href":28},[17,678,679],{},"macroRenameSchema",", which renames the declaration and retargets the refs in one pass.",[32,682,684],{"id":683},"use-the-built-in-macros","Use the built-in macros",[10,686,687,689,690,692,693,696],{},[17,688,23],{}," exports presets for common normalizations. Compose them with your own through a plugin's ",[17,691,384],{}," option. See the ",[26,694,695],{"href":28},"built-in macros table"," for what each one does.",[40,698,701],{"language":42,"filename":699,"code":700,"class":45},"presets.ts","import { ast, macroSimplifyUnion, macroDiscriminatorEnum, macroRenameSchema } from 'kubb\u002Fkit'\n\nconst root = ast.factory.createInput({ schemas: [], operations: [] })\nconst next = ast.applyMacros(root, [\n  macroSimplifyUnion,\n  macroDiscriminatorEnum({ propertyName: 'kind', values: ['cat', 'dog'] }),\n  macroRenameSchema({ from: 'Order', to: 'StoreOrder' }),\n])",[17,702,703,76,732,76,734,76,776,76,801,76,809,76,847,76,877],{"class":48},[50,704,705,707,709,711,713,716,718,721,723,726,728,730],{"class":52,"style":53},[50,706,57],{"style":56},[50,708,61],{"style":60},[50,710,19],{"style":64},[50,712,167],{"style":56},[50,714,715],{"style":64},"macroSimplifyUnion",[50,717,167],{"style":56},[50,719,720],{"style":64},"macroDiscriminatorEnum",[50,722,167],{"style":56},[50,724,725],{"style":64},"macroRenameSchema ",[50,727,68],{"style":60},[50,729,71],{"style":56},[50,731,75],{"style":74},[50,733],{"class":52,"style":53},[50,735,736,738,741,743,745,747,750,752,755,758,761,763,766,768,771,773],{"class":52,"style":53},[50,737,83],{"style":56},[50,739,740],{"style":64},"root ",[50,742,89],{"style":56},[50,744,19],{"style":64},[50,746,30],{"style":56},[50,748,749],{"style":60},"factory",[50,751,30],{"style":56},[50,753,754],{"style":96},"createInput",[50,756,757],{"style":60},"({ ",[50,759,760],{"style":60},"schemas",[50,762,111],{"style":56},[50,764,765],{"style":60},"[]",[50,767,167],{"style":56},[50,769,770],{"style":60},"operations",[50,772,111],{"style":56},[50,774,775],{"style":60},"[] })",[50,777,778,780,783,785,787,789,792,794,797,799],{"class":52,"style":53},[50,779,83],{"style":56},[50,781,782],{"style":64},"next ",[50,784,89],{"style":56},[50,786,19],{"style":64},[50,788,30],{"style":56},[50,790,791],{"style":96},"applyMacros",[50,793,127],{"style":60},[50,795,796],{"style":64},"root",[50,798,167],{"style":56},[50,800,358],{"style":60},[50,802,803,805,807],{"class":52,"style":53},[50,804,105],{"style":60},[50,806,715],{"style":64},[50,808,117],{"style":56},[50,810,811,813,815,817,820,822,825,827,830,832,834,837,839,842,845],{"class":52,"style":53},[50,812,105],{"style":56},[50,814,720],{"style":96},[50,816,757],{"style":60},[50,818,819],{"style":60},"propertyName",[50,821,111],{"style":56},[50,823,824],{"style":74},"'kind'",[50,826,167],{"style":56},[50,828,829],{"style":60},"values",[50,831,111],{"style":56},[50,833,358],{"style":60},[50,835,836],{"style":74},"'cat'",[50,838,167],{"style":56},[50,840,841],{"style":74},"'dog'",[50,843,844],{"style":60},"] })",[50,846,117],{"style":56},[50,848,849,851,853,855,858,860,863,865,868,870,873,875],{"class":52,"style":53},[50,850,105],{"style":56},[50,852,679],{"style":96},[50,854,757],{"style":60},[50,856,857],{"style":60},"from",[50,859,111],{"style":56},[50,861,862],{"style":74},"'Order'",[50,864,167],{"style":56},[50,866,867],{"style":60},"to",[50,869,111],{"style":56},[50,871,872],{"style":74},"'StoreOrder' ",[50,874,196],{"style":60},[50,876,117],{"style":56},[50,878,879],{"class":52,"style":53},[50,880,881],{"style":60},"])",[10,883,884],{},"Export macros from a shared module to reuse them across plugins and projects.",{"title":886,"searchDepth":887,"depth":887,"links":888},"",5,[889,891,892],{"id":34,"depth":890,"text":35},2,{"id":377,"depth":890,"text":378},{"id":683,"depth":890,"text":684},"A macro is a named, composable transform over Kubb's AST. Macros rewrite schema and operation nodes before generators print code, and the same macro works across every adapter and every output target.","md",{"layout":896,"title":5,"description":893,"outline":897,"order":898,"navigation":899},"doc","deep",4,{"title":5,"icon":900},"i-iconoir-magic-wand",{"layout":896,"outline":897},{"title":5,"icon":900},"\u002Fdocs\u002F5.x\u002Fhow-to\u002Fmacros",{"title":5,"description":893},{"loc":903},"kubb-labs\u002Fkubb\u002Fdocs\u002F5.x\u002Fhow-to\u002Fmacros.md","docs\u002F5.x\u002Fhow-to\u002Fmacros","IfGlsxA1JFz7OFHIEVDQjzRxKgIEmGPkOKrLkdfN_4w",1792931640500]