@graphql-markdown/core 1.15.0 → 1.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/config.d.ts CHANGED
@@ -1,6 +1,33 @@
1
+ /**
2
+ * Configuration management for GraphQL Markdown.
3
+ *
4
+ * This module handles all aspects of configuration including:
5
+ * - Loading and merging configuration from multiple sources
6
+ * - Validating configuration values
7
+ * - Providing defaults for missing options
8
+ * - Processing special configuration options (directives, deprecated items, etc)
9
+ *
10
+ * The configuration follows this precedence (highest to lowest):
11
+ * 1. CLI arguments
12
+ * 2. Config file options
13
+ * 3. GraphQL Config options
14
+ * 4. Default values
15
+ *
16
+ * @packageDocumentation
17
+ */
1
18
  import type { CliOptions, ConfigDocOptions, ConfigOptions, ConfigPrintTypeOptions, CustomDirective, DeprecatedCliOptions, DeprecatedConfigDocOptions, DeprecatedConfigPrintTypeOptions, DirectiveName, GroupByDirectiveOptions, Maybe, Options, TypeDiffMethod, TypeHierarchyObjectType, TypeHierarchyType, TypeHierarchyValueType } from "@graphql-markdown/types";
2
19
  /**
20
+ * Type hierarchy options for organizing schema documentation.
21
+ *
22
+ * - API: Groups types by their role in the API (Query, Mutation, etc.)
23
+ * - ENTITY: Groups types by their entity relationships
24
+ * - FLAT: No grouping, all types in a flat structure
25
+ *
3
26
  * @public
27
+ * @example
28
+ * ```typescript
29
+ * const hierarchy = TypeHierarchy.API;
30
+ * ```
4
31
  */
5
32
  export declare enum TypeHierarchy {
6
33
  API = "api",
@@ -8,44 +35,366 @@ export declare enum TypeHierarchy {
8
35
  FLAT = "flat"
9
36
  }
10
37
  /**
38
+ * Diff methods used to determine how schema changes are processed.
39
+ *
40
+ * - NONE: No diffing is performed
41
+ * - FORCE: Force regeneration of documentation regardless of schema changes
42
+ *
11
43
  * @public
44
+ * @example
45
+ * ```typescript
46
+ * const diffMethod = DiffMethod.FORCE;
47
+ * ```
12
48
  */
13
49
  export declare enum DiffMethod {
14
50
  NONE = "NONE",
15
51
  FORCE = "FORCE"
16
52
  }
17
53
  /**
54
+ * Options for handling deprecated items in the schema.
55
+ *
56
+ * - DEFAULT: Show deprecated items normally
57
+ * - GROUP: Group deprecated items separately
58
+ * - SKIP: Exclude deprecated items from documentation
59
+ *
18
60
  * @public
61
+ * @example
62
+ * ```typescript
63
+ * const deprecatedHandling = DeprecatedOption.GROUP;
64
+ * ```
19
65
  */
20
66
  export declare enum DeprecatedOption {
21
67
  DEFAULT = "default",
22
68
  GROUP = "group",
23
69
  SKIP = "skip"
24
70
  }
71
+ /**
72
+ * Documentation website URL for reference in error messages and help text.
73
+ * @public
74
+ */
25
75
  export declare const DOCS_URL: "https://graphql-markdown.dev/docs";
76
+ /**
77
+ * Default package name used for temporary directory creation and identification.
78
+ * @public
79
+ */
26
80
  export declare const PACKAGE_NAME: "@graphql-markdown/docusaurus";
81
+ /**
82
+ * Location of the default homepage template.
83
+ * @public
84
+ */
27
85
  export declare const ASSET_HOMEPAGE_LOCATION: string;
86
+ /**
87
+ * Default hierarchy configuration using the API hierarchy type.
88
+ * @public
89
+ */
28
90
  export declare const DEFAULT_HIERARCHY: {
29
91
  api: {};
30
92
  };
93
+ /**
94
+ * Default configuration options used when no user options are provided.
95
+ * These values serve as fallbacks for any missing configuration.
96
+ *
97
+ * @public
98
+ * @see {@link Options} for the complete configuration interface
99
+ */
31
100
  export declare const DEFAULT_OPTIONS: Readonly<Pick<ConfigOptions, "customDirective" | "groupByDirective" | "loaders"> & Required<Omit<ConfigOptions, "customDirective" | "groupByDirective" | "loaders" | "mdxParser" | "printTypeOptions">>> & {
32
101
  printTypeOptions: Required<Omit<ConfigPrintTypeOptions, "hierarchy">> & {
33
102
  hierarchy: Required<Pick<TypeHierarchyObjectType, TypeHierarchy.API>>;
34
103
  };
35
104
  };
105
+ /**
106
+ * Retrieves a directive name from a string by parsing and validating the format.
107
+ * Directive names should be prefixed with '\@' (e.g., '\@example').
108
+ *
109
+ * @param name - The directive name as a string, which should follow the format '\@directiveName'
110
+ * @returns The validated directive name without the '\@' prefix
111
+ * @throws Error if the directive name format is invalid
112
+ * @example
113
+ * ```typescript
114
+ * const directive = getDocDirective("@example");
115
+ * console.log(directive); // "example"
116
+ *
117
+ * // Invalid - will throw an error
118
+ * getDocDirective("example"); // Error: Invalid "example"
119
+ * ```
120
+ */
36
121
  export declare const getDocDirective: (name: Maybe<DirectiveName>) => DirectiveName;
122
+ /**
123
+ * Retrieves the list of "only" directives from CLI and config options.
124
+ * These directives specify which schema elements should be included in the documentation.
125
+ *
126
+ * @param cliOpts - CLI options containing "only" directives
127
+ * @param configFileOpts - Config file options containing "onlyDocDirective"
128
+ * @returns An array of validated "only" directives (without '\@' prefix)
129
+ * @example
130
+ * ```typescript
131
+ * const cliOptions = { only: ["@example", "@internal"] };
132
+ * const configOptions = { onlyDocDirective: ["@auth"] };
133
+ *
134
+ * const onlyDirectives = getOnlyDocDirectives(cliOptions, configOptions);
135
+ * console.log(onlyDirectives); // ["example", "internal", "auth"]
136
+ * ```
137
+ * @see {@link getDocDirective} for directive name validation
138
+ */
37
139
  export declare const getOnlyDocDirectives: (cliOpts: Maybe<CliOptions>, configFileOpts: Maybe<Pick<ConfigOptions, "onlyDocDirective">>) => DirectiveName[];
140
+ /**
141
+ * Retrieves the list of "skip" directives from CLI and config options.
142
+ * These directives specify which schema elements should be excluded from the documentation.
143
+ * Additionally, if deprecated handling is set to SKIP, adds the "deprecated" directive.
144
+ *
145
+ * @param cliOpts - CLI options containing "skip" directives
146
+ * @param configFileOpts - Config file options containing "skipDocDirective" and potentially "printTypeOptions.deprecated"
147
+ * @returns An array of validated "skip" directives (without '\@' prefix)
148
+ * @example
149
+ * ```typescript
150
+ * const cliOptions = { skip: ["@internal"], deprecated: "skip" };
151
+ * const configOptions = { skipDocDirective: ["@auth"] };
152
+ *
153
+ * const skipDirectives = getSkipDocDirectives(cliOptions, configOptions);
154
+ * console.log(skipDirectives); // ["internal", "auth", "deprecated"]
155
+ * ```
156
+ * @see {@link getDocDirective} for directive name validation
157
+ * @see {@link DeprecatedOption} for deprecated handling options
158
+ */
38
159
  export declare const getSkipDocDirectives: (cliOpts: Maybe<CliOptions>, configFileOpts: Maybe<Pick<ConfigOptions, "printTypeOptions" | "skipDocDirective">>) => DirectiveName[];
160
+ /**
161
+ * Combines and validates visibility directives (only and skip) from both CLI and config sources.
162
+ * Ensures that no directive appears in both "only" and "skip" lists simultaneously.
163
+ *
164
+ * @param cliOpts - CLI options containing "only" and "skip" directives
165
+ * @param configFileOpts - Config file options containing directive configurations
166
+ * @returns An object with validated "onlyDocDirective" and "skipDocDirective" arrays
167
+ * @throws Error if the same directive appears in both "only" and "skip" lists
168
+ * @example
169
+ * ```typescript
170
+ * const cliOptions = { only: ["@example"], skip: ["@internal"] };
171
+ * const configOptions = { onlyDocDirective: ["@auth"] };
172
+ *
173
+ * const visibilityDirectives = getVisibilityDirectives(cliOptions, configOptions);
174
+ * console.log(visibilityDirectives);
175
+ * // {
176
+ * // onlyDocDirective: ["example", "auth"],
177
+ * // skipDocDirective: ["internal"]
178
+ * // }
179
+ *
180
+ * // Invalid - will throw an error
181
+ * getVisibilityDirectives(
182
+ * { only: ["@example"], skip: ["@example"] },
183
+ * {}
184
+ * ); // Error: The same directive cannot be declared in 'onlyDocDirective' and 'skipDocDirective'.
185
+ * ```
186
+ * @see {@link getOnlyDocDirectives} and {@link getSkipDocDirectives} for directive retrieval
187
+ */
39
188
  export declare const getVisibilityDirectives: (cliOpts: Maybe<CliOptions>, configFileOpts: Maybe<Pick<ConfigOptions, "onlyDocDirective" | "printTypeOptions" | "skipDocDirective">>) => {
40
189
  onlyDocDirective: DirectiveName[];
41
190
  skipDocDirective: DirectiveName[];
42
191
  };
192
+ /**
193
+ * Processes custom directives, filtering out any that should be skipped.
194
+ * Validates that each custom directive has the correct format with required functions.
195
+ *
196
+ * @param customDirectiveOptions - The custom directive configuration object
197
+ * @param skipDocDirective - Array of directive names that should be skipped
198
+ * @returns The filtered custom directives object, or undefined if empty/invalid
199
+ * @throws Error if a custom directive has an invalid format
200
+ * @example
201
+ * ```typescript
202
+ * // Valid custom directive with tag function
203
+ * const customDirectives = {
204
+ * example: {
205
+ * tag: (value) => `Example: ${value}`
206
+ * },
207
+ * todo: {
208
+ * descriptor: () => "TODO items"
209
+ * }
210
+ * };
211
+ *
212
+ * // Filter out the "example" directive
213
+ * const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
214
+ * console.log(filteredDirectives); // { todo: { descriptor: [Function] } }
215
+ *
216
+ * // Invalid format - will throw an error
217
+ * getCustomDirectives({ example: { invalid: true } }, []);
218
+ * // Error: Wrong format for plugin custom directive "example"...
219
+ * ```
220
+ * @see {@link DOCS_URL}/advanced/custom-directive for custom directive format documentation
221
+ */
43
222
  export declare const getCustomDirectives: (customDirectiveOptions: Maybe<CustomDirective>, skipDocDirective?: Maybe<DirectiveName[]>) => Maybe<CustomDirective>;
223
+ /**
224
+ * Determines the diff method to use based on the configuration and force flag.
225
+ * If force is true, always returns FORCE regardless of the configured diff method.
226
+ *
227
+ * @param diff - The configured diff method
228
+ * @param force - Whether to force regeneration (overrides diff setting)
229
+ * @returns The resolved diff method to use
230
+ * @example
231
+ * ```typescript
232
+ * // Normal usage - respects the configured diff method
233
+ * const method1 = getDiffMethod(DiffMethod.NONE, false);
234
+ * console.log(method1); // "NONE"
235
+ *
236
+ * // Force flag overrides the diff method
237
+ * const method2 = getDiffMethod(DiffMethod.NONE, true);
238
+ * console.log(method2); // "FORCE"
239
+ * ```
240
+ * @see {@link DiffMethod} for available diff methods
241
+ */
44
242
  export declare const getDiffMethod: (diff: TypeDiffMethod, force?: boolean) => TypeDiffMethod;
243
+ /**
244
+ * Placeholder function for handling deprecated document options.
245
+ * Currently returns an empty object as these options are deprecated.
246
+ *
247
+ * @param _cliOpts - Deprecated CLI options (unused)
248
+ * @param _configOptions - Deprecated config options (unused)
249
+ * @returns An empty object
250
+ */
45
251
  export declare const parseDeprecatedDocOptions: (_cliOpts: Maybe<Omit<DeprecatedCliOptions, "never">>, _configOptions: Maybe<Omit<DeprecatedConfigDocOptions, "never">>) => Record<string, never>;
252
+ /**
253
+ * Builds the document options by merging CLI options, config file options, and defaults.
254
+ * Handles index generation flag and front matter configuration.
255
+ *
256
+ * @param cliOpts - CLI options for document generation
257
+ * @param configOptions - Config file options for document generation
258
+ * @returns The resolved document options with all required fields
259
+ * @example
260
+ * ```typescript
261
+ * const cliOptions = { index: true };
262
+ * const configOptions = { frontMatter: { sidebar_label: 'API' } };
263
+ *
264
+ * const docOptions = getDocOptions(cliOptions, configOptions);
265
+ * console.log(docOptions);
266
+ * // {
267
+ * // index: true,
268
+ * // frontMatter: { sidebar_label: 'API' }
269
+ * // }
270
+ * ```
271
+ */
46
272
  export declare const getDocOptions: (cliOpts?: Maybe<CliOptions & Omit<DeprecatedCliOptions, "never">>, configOptions?: Maybe<ConfigDocOptions & Omit<DeprecatedConfigDocOptions, "never">>) => Required<ConfigDocOptions>;
273
+ /**
274
+ * Resolves the type hierarchy configuration by merging CLI and config file options.
275
+ * Validates that CLI and config don't specify conflicting hierarchy types.
276
+ *
277
+ * @param cliOption - The hierarchy option specified via CLI (string value)
278
+ * @param configOption - The hierarchy option from the config file (string or object)
279
+ * @returns The resolved type hierarchy object
280
+ * @throws Error if CLI and config specify conflicting hierarchy types
281
+ * @example
282
+ * ```typescript
283
+ * // Using hierarchy from CLI (string format)
284
+ * const hierarchy1 = getTypeHierarchyOption("api", undefined);
285
+ * console.log(hierarchy1); // { api: {} }
286
+ *
287
+ * // Using hierarchy from config (object format)
288
+ * const hierarchy2 = getTypeHierarchyOption(undefined, { entity: { User: ["posts"] } });
289
+ * console.log(hierarchy2); // { entity: { User: ["posts"] } }
290
+ *
291
+ * // Error case - conflicting hierarchies
292
+ * getTypeHierarchyOption("api", { entity: {} });
293
+ * // Error: Hierarchy option mismatch in CLI flag 'api' and config 'entity'
294
+ * ```
295
+ * @see {@link TypeHierarchy} for available hierarchy types
296
+ */
47
297
  export declare const getTypeHierarchyOption: (cliOption?: Maybe<TypeHierarchyValueType>, configOption?: Maybe<TypeHierarchyType>) => Maybe<TypeHierarchyObjectType>;
298
+ /**
299
+ * Placeholder function for handling deprecated print type options.
300
+ * Currently returns an empty object as these options are deprecated.
301
+ *
302
+ * @param _cliOpts - Deprecated CLI options (unused)
303
+ * @param _configOptions - Deprecated config options (unused)
304
+ * @returns An empty object
305
+ */
48
306
  export declare const parseDeprecatedPrintTypeOptions: (_cliOpts: Maybe<Omit<DeprecatedCliOptions, "never">>, _configOptions: Maybe<Omit<DeprecatedConfigPrintTypeOptions, "never">>) => Record<string, never>;
307
+ /**
308
+ * Builds the print type options by merging CLI options, config file options, and defaults.
309
+ * Handles various formatting options for type documentation.
310
+ *
311
+ * @param cliOpts - CLI options for print type configuration
312
+ * @param configOptions - Config file options for print type configuration
313
+ * @returns The resolved print type options with all required fields
314
+ * @example
315
+ * ```typescript
316
+ * const cliOptions = { noCode: true, deprecated: "group" };
317
+ * const configOptions = {
318
+ * exampleSection: true,
319
+ * hierarchy: "entity"
320
+ * };
321
+ *
322
+ * const printOptions = getPrintTypeOptions(cliOptions, configOptions);
323
+ * console.log(printOptions);
324
+ * // {
325
+ * // codeSection: false, // Disabled via noCode CLI flag
326
+ * // deprecated: "group", // From CLI
327
+ * // exampleSection: true, // From config
328
+ * // parentTypePrefix: true, // Default value
329
+ * // relatedTypeSection: true, // Default value
330
+ * // typeBadges: true, // Default value
331
+ * // hierarchy: { entity: {} } // Parsed from config
332
+ * // }
333
+ * ```
334
+ * @see {@link DeprecatedOption} for deprecated handling options
335
+ * @see {@link getTypeHierarchyOption} for hierarchy resolution
336
+ */
49
337
  export declare const getPrintTypeOptions: (cliOpts: Maybe<CliOptions & Omit<DeprecatedCliOptions, "never">>, configOptions: Maybe<ConfigPrintTypeOptions & Omit<DeprecatedConfigPrintTypeOptions, "never">>) => Required<ConfigPrintTypeOptions>;
338
+ /**
339
+ * Parses and validates the groupByDirective option string format.
340
+ * The format should be \@directive(field|=fallback) where:
341
+ * - directive: Name of the directive to group by
342
+ * - field: Name of the field in the directive to use for grouping
343
+ * - fallback: (Optional) Fallback group name for items without the directive
344
+ *
345
+ * @param groupOptions - The group directive option as a string
346
+ * @returns A parsed GroupByDirectiveOptions object or undefined if invalid
347
+ * @throws Error if the groupByDirective format is invalid
348
+ * @example
349
+ * ```typescript
350
+ * // Basic usage with directive and field
351
+ * const groupBy1 = parseGroupByOption("@tag(name)");
352
+ * console.log(groupBy1);
353
+ * // { directive: "tag", field: "name", fallback: "Miscellaneous" }
354
+ *
355
+ * // With custom fallback group
356
+ * const groupBy2 = parseGroupByOption("@category(name|=Other)");
357
+ * console.log(groupBy2);
358
+ * // { directive: "category", field: "name", fallback: "Other" }
359
+ *
360
+ * // Invalid format - will throw an error
361
+ * parseGroupByOption("invalid-format");
362
+ * // Error: Invalid "invalid-format"
363
+ * ```
364
+ */
50
365
  export declare const parseGroupByOption: (groupOptions: unknown) => Maybe<GroupByDirectiveOptions>;
366
+ /**
367
+ * Builds the complete configuration object by merging options from multiple sources
368
+ * in order of precedence:
369
+ * 1. CLI options (highest priority)
370
+ * 2. Configuration file options
371
+ * 3. GraphQL Config options
372
+ * 4. Default options (lowest priority)
373
+ *
374
+ * @param configFileOpts - Options from the configuration file
375
+ * @param cliOpts - Options from the command line interface
376
+ * @param id - The configuration ID used when referencing multiple schemas
377
+ * @returns A promise resolving to the final merged configuration object
378
+ * @example
379
+ * ```typescript
380
+ * // Basic usage with minimal options
381
+ * const config = await buildConfig(
382
+ * { baseURL: "api" }, // Config file options
383
+ * { pretty: true } // CLI options
384
+ * );
385
+ *
386
+ * // With specific config ID
387
+ * const config = await buildConfig(
388
+ * { schema: "./schemas/users.graphql" },
389
+ * { force: true },
390
+ * "users"
391
+ * );
392
+ *
393
+ * // The resulting config will contain all required options
394
+ * // with values from CLI taking precedence over config file,
395
+ * // and defaults filling in any missing values
396
+ * ```
397
+ * @see {@link Options} for the complete configuration interface
398
+ * @see {@link DEFAULT_OPTIONS} for default values
399
+ */
51
400
  export declare const buildConfig: (configFileOpts: Maybe<ConfigOptions>, cliOpts?: Maybe<CliOptions>, id?: Maybe<string>) => Promise<Options>;