fork of hey-api/openapi-ts because I need some additional things
1import type { Node, Symbol, SymbolIn, SymbolMeta } from '@hey-api/codegen-core';
2import type { MaybeFunc } from '@hey-api/types';
3
4import type { SchemaProcessorContext } from '../ir/schema-processor';
5import type { IROperationObject, IRSchemaObject } from '../ir/types';
6import type { PluginInstance } from '../plugins/shared/utils/instance';
7import type { NamingConfig } from '../utils/naming/types';
8
9export type Hooks = {
10 /**
11 * Event hooks.
12 */
13 events?: {
14 /**
15 * Triggered after adding or updating a node.
16 *
17 * You can use this to perform actions after a node is added or updated.
18 *
19 * @param args Arguments object.
20 * @returns void
21 */
22 'node:set:after'?: (args: {
23 /** The node added or updated. */
24 node: Node | null;
25 /** Plugin that added or updated the node. */
26 plugin: PluginInstance;
27 }) => void;
28 /**
29 * Triggered before adding or updating a node.
30 *
31 * You can use this to modify the node before it's added or updated.
32 *
33 * @param args Arguments object.
34 * @returns void
35 */
36 'node:set:before'?: (args: {
37 /** The node to be added or updated. */
38 node: Node | null;
39 /** Plugin adding or updating the node. */
40 plugin: PluginInstance;
41 }) => void;
42 /**
43 * Triggered after executing a plugin handler.
44 *
45 * @param args Arguments object.
46 * @returns void
47 */
48 'plugin:handler:after'?: (args: {
49 /** Plugin that just executed. */
50 plugin: PluginInstance;
51 }) => void;
52 /**
53 * Triggered before executing a plugin handler.
54 *
55 * @param args Arguments object.
56 * @returns void
57 */
58 'plugin:handler:before'?: (args: {
59 /** Plugin about to execute. */
60 plugin: PluginInstance;
61 }) => void;
62 /**
63 * Triggered after registering a symbol.
64 *
65 * You can use this to perform actions after a symbol is registered.
66 *
67 * @param args Arguments object.
68 * @returns void
69 */
70 'symbol:register:after'?: (args: {
71 /** Plugin that registered the symbol. */
72 plugin: PluginInstance;
73 /** The registered symbol. */
74 symbol: Symbol;
75 }) => void;
76 /**
77 * Triggered before registering a symbol.
78 *
79 * You can use this to modify the symbol before it's registered.
80 *
81 * @param args Arguments object.
82 * @returns void
83 */
84 'symbol:register:before'?: (args: {
85 /** Plugin registering the symbol. */
86 plugin: PluginInstance;
87 /** Symbol to register. */
88 symbol: SymbolIn;
89 }) => void;
90 };
91 /**
92 * Hooks specifically for overriding operations behavior.
93 *
94 * Use these to classify operations, decide which outputs to generate,
95 * or apply custom behavior to individual operations.
96 */
97 operations?: {
98 /**
99 * Classify the given operation into one or more kinds.
100 *
101 * Each kind determines how we treat the operation (e.g., generating queries or mutations).
102 *
103 * **Default behavior:**
104 * - GET → 'query'
105 * - DELETE, PATCH, POST, PUT → 'mutation'
106 *
107 * **Resolution order:**
108 * 1. If `isQuery` or `isMutation` returns `true` or `false`, that overrides `getKind`.
109 * 2. If `isQuery` or `isMutation` returns `undefined`, the result of `getKind` is used.
110 *
111 * @param operation - The operation object to classify.
112 * @returns An array containing one or more of 'query' or 'mutation', or undefined to fallback to default behavior.
113 * @example
114 * ```ts
115 * getKind: (operation) => {
116 * if (operation.method === 'get' && operation.path === '/search') {
117 * return ['query', 'mutation'];
118 * }
119 * return; // fallback to default behavior
120 * }
121 * ```
122 */
123 getKind?: (operation: IROperationObject) => ReadonlyArray<'mutation' | 'query'> | undefined;
124 /**
125 * Check if the given operation should be treated as a mutation.
126 *
127 * This affects which outputs are generated for the operation.
128 *
129 * **Default behavior:** DELETE, PATCH, POST, and PUT operations are treated as mutations.
130 *
131 * **Resolution order:** If this returns `true` or `false`, it overrides `getKind`.
132 * If it returns `undefined`, `getKind` is used instead.
133 *
134 * @param operation - The operation object to check.
135 * @returns true if the operation is a mutation, false otherwise, or undefined to fallback to `getKind`.
136 * @example
137 * ```ts
138 * isMutation: (operation) => {
139 * if (operation.method === 'post' && operation.path === '/search') {
140 * return true;
141 * }
142 * return; // fallback to default behavior
143 * }
144 * ```
145 */
146 isMutation?: (operation: IROperationObject) => boolean | undefined;
147 /**
148 * Check if the given operation should be treated as a query.
149 *
150 * This affects which outputs are generated for the operation.
151 *
152 * **Default behavior:** GET operations are treated as queries.
153 *
154 * **Resolution order:** If this returns `true` or `false`, it overrides `getKind`.
155 * If it returns `undefined`, `getKind` is used instead.
156 *
157 * @param operation - The operation object to check.
158 * @returns true if the operation is a query, false otherwise, or undefined to fallback to `getKind`.
159 * @example
160 * ```ts
161 * isQuery: (operation) => {
162 * if (operation.method === 'post' && operation.path === '/search') {
163 * return true;
164 * }
165 * return; // fallback to default behavior
166 * }
167 * ```
168 */
169 isQuery?: (operation: IROperationObject) => boolean | undefined;
170 };
171 schemas?: {
172 /**
173 * Whether to extract the given schema into a separate symbol.
174 *
175 * This affects how schemas are processed and output.
176 *
177 * @param ctx - The processing context for the schema.
178 * @returns true to extract the schema, false to keep it inline, or undefined to fallback to default behavior.
179 * @example
180 * ```ts
181 * shouldExtract: (ctx) => {
182 * if (ctx.meta.resource === 'requestBody') {
183 * return true;
184 * }
185 * return; // fallback to default behavior
186 * }
187 * ```
188 */
189 shouldExtract?: MaybeFunc<(ctx: SchemaProcessorContext) => boolean>;
190 };
191 /**
192 * Hooks specifically for overriding symbols behavior.
193 *
194 * Use these to customize file placement.
195 */
196 symbols?: {
197 /**
198 * Optional output strategy to override default plugin behavior.
199 *
200 * Use this to re-export symbols from specific files.
201 *
202 * @returns The file path(s) that re-export this symbol, or undefined to fallback to default behavior.
203 */
204 getExportFromFilePath?: (symbol: Symbol) => ReadonlyArray<string> | undefined;
205 /**
206 * Optional output strategy to override default plugin behavior.
207 *
208 * Use this to route symbols to specific files.
209 *
210 * @returns The file path to output the symbol to, or undefined to fallback to default behavior.
211 */
212 getFilePath?: (symbol: Symbol) => string | undefined;
213 /**
214 * Optional output strategy to override default plugin behavior.
215 *
216 * Use this to customize symbol names.
217 *
218 * @returns The name to register the symbol with, or undefined to fallback to default behavior.
219 */
220 getName?: (ctx: GetNameContext) => MaybeFunc<(ctx: GetNameContext) => string | undefined>;
221 };
222};
223
224export interface GetNameContext {
225 /** Arbitrary metadata about the symbol. */
226 meta: SymbolMeta;
227 /** The proposed name for the symbol. */
228 name: string;
229 /** The naming configuration for the symbol. */
230 naming?: NamingConfig;
231 /** The operation object associated with the symbol. */
232 operation?: IROperationObject;
233 /** The schema object associated with the symbol. */
234 schema?: IRSchemaObject;
235}