@graphql-markdown/core 1.16.2 → 1.17.0

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.
Files changed (90) hide show
  1. package/dist/config.d.ts +17 -55
  2. package/dist/config.d.ts.map +1 -0
  3. package/dist/config.js +82 -94
  4. package/dist/const/patterns.d.ts +114 -0
  5. package/dist/const/patterns.d.ts.map +1 -0
  6. package/dist/const/patterns.js +116 -0
  7. package/dist/diff.d.ts +1 -0
  8. package/dist/diff.d.ts.map +1 -0
  9. package/dist/directives/normalize.d.ts +79 -0
  10. package/dist/directives/normalize.d.ts.map +1 -0
  11. package/dist/directives/normalize.js +91 -0
  12. package/dist/directives/validation.d.ts +146 -0
  13. package/dist/directives/validation.d.ts.map +1 -0
  14. package/dist/directives/validation.js +188 -0
  15. package/dist/event-emitter.d.ts +109 -0
  16. package/dist/event-emitter.d.ts.map +1 -0
  17. package/dist/event-emitter.js +138 -0
  18. package/dist/event-handlers.d.ts +19 -0
  19. package/dist/event-handlers.d.ts.map +1 -0
  20. package/dist/event-handlers.js +54 -0
  21. package/dist/event-map.d.ts +19 -0
  22. package/dist/event-map.d.ts.map +1 -0
  23. package/dist/event-map.js +35 -0
  24. package/dist/event-types.d.ts +313 -0
  25. package/dist/event-types.d.ts.map +1 -0
  26. package/dist/event-types.js +309 -0
  27. package/dist/events/base.d.ts +114 -0
  28. package/dist/events/base.d.ts.map +1 -0
  29. package/dist/events/base.js +148 -0
  30. package/dist/events/diff-check.d.ts +25 -0
  31. package/dist/events/diff-check.d.ts.map +1 -0
  32. package/dist/events/diff-check.js +26 -0
  33. package/dist/events/diff-events.d.ts +15 -0
  34. package/dist/events/diff-events.d.ts.map +1 -0
  35. package/dist/events/diff-events.js +17 -0
  36. package/dist/events/generate-index-metafile-events.d.ts +15 -0
  37. package/dist/events/generate-index-metafile-events.d.ts.map +1 -0
  38. package/dist/events/generate-index-metafile-events.js +17 -0
  39. package/dist/events/generate-index-metafile.d.ts +28 -0
  40. package/dist/events/generate-index-metafile.d.ts.map +1 -0
  41. package/dist/events/generate-index-metafile.js +29 -0
  42. package/dist/events/index.d.ts +19 -0
  43. package/dist/events/index.d.ts.map +1 -0
  44. package/dist/events/index.js +38 -0
  45. package/dist/events/render-homepage-events.d.ts +15 -0
  46. package/dist/events/render-homepage-events.d.ts.map +1 -0
  47. package/dist/events/render-homepage-events.js +17 -0
  48. package/dist/events/render-homepage.d.ts +22 -0
  49. package/dist/events/render-homepage.d.ts.map +1 -0
  50. package/dist/events/render-homepage.js +23 -0
  51. package/dist/events/render-root-types-events.d.ts +15 -0
  52. package/dist/events/render-root-types-events.d.ts.map +1 -0
  53. package/dist/events/render-root-types-events.js +17 -0
  54. package/dist/events/render-root-types.d.ts +22 -0
  55. package/dist/events/render-root-types.d.ts.map +1 -0
  56. package/dist/events/render-root-types.js +23 -0
  57. package/dist/events/render-type-entities-events.d.ts +15 -0
  58. package/dist/events/render-type-entities-events.d.ts.map +1 -0
  59. package/dist/events/render-type-entities-events.js +17 -0
  60. package/dist/events/render-type-entities.d.ts +25 -0
  61. package/dist/events/render-type-entities.d.ts.map +1 -0
  62. package/dist/events/render-type-entities.js +26 -0
  63. package/dist/events/schema-events.d.ts +15 -0
  64. package/dist/events/schema-events.d.ts.map +1 -0
  65. package/dist/events/schema-events.js +17 -0
  66. package/dist/events/schema-load.d.ts +22 -0
  67. package/dist/events/schema-load.d.ts.map +1 -0
  68. package/dist/events/schema-load.js +23 -0
  69. package/dist/generator.d.ts +1 -0
  70. package/dist/generator.d.ts.map +1 -0
  71. package/dist/generator.js +47 -5
  72. package/dist/graphql-config.d.ts +2 -1
  73. package/dist/graphql-config.d.ts.map +1 -0
  74. package/dist/graphql-config.js +16 -10
  75. package/dist/hooks.d.ts +10 -0
  76. package/dist/hooks.d.ts.map +1 -0
  77. package/dist/hooks.js +33 -0
  78. package/dist/index.d.ts +11 -0
  79. package/dist/index.d.ts.map +1 -0
  80. package/dist/index.js +11 -3
  81. package/dist/options/builder.d.ts +157 -0
  82. package/dist/options/builder.d.ts.map +1 -0
  83. package/dist/options/builder.js +215 -0
  84. package/dist/printer.d.ts +3 -2
  85. package/dist/printer.d.ts.map +1 -0
  86. package/dist/printer.js +1 -1
  87. package/dist/renderer.d.ts +76 -23
  88. package/dist/renderer.d.ts.map +1 -0
  89. package/dist/renderer.js +411 -67
  90. package/package.json +15 -15
package/dist/config.d.ts CHANGED
@@ -195,23 +195,23 @@ export declare const getVisibilityDirectives: (cliOpts: Maybe<CliOptions>, confi
195
195
  *
196
196
  * @param customDirectiveOptions - The custom directive configuration object
197
197
  * @param skipDocDirective - Array of directive names that should be skipped
198
- * @returns The filtered custom directives object, or undefined if empty/invalid
198
+ * @returns The filtered custom directives object, or `undefined` if empty/invalid
199
199
  * @throws Error if a custom directive has an invalid format
200
200
  * @example
201
201
  * ```typescript
202
- * // Valid custom directive with tag function
202
+ * // Valid custom directive with descriptor function
203
203
  * const customDirectives = {
204
204
  * example: {
205
205
  * tag: (value) => `Example: ${value}`
206
206
  * },
207
- * todo: {
208
- * descriptor: () => "TODO items"
207
+ * note: {
208
+ * descriptor: () => "Note items"
209
209
  * }
210
210
  * };
211
211
  *
212
- * // Filter out the "example" directive
212
+ * // Filter out the "example" directive, keeping "note"
213
213
  * const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
214
- * console.log(filteredDirectives); // { todo: { descriptor: [Function] } }
214
+ * console.log(filteredDirectives); // { note: { descriptor: [Function] } }
215
215
  *
216
216
  * // Invalid format - will throw an error
217
217
  * getCustomDirectives({ example: { invalid: true } }, []);
@@ -221,25 +221,20 @@ export declare const getVisibilityDirectives: (cliOpts: Maybe<CliOptions>, confi
221
221
  */
222
222
  export declare const getCustomDirectives: (customDirectiveOptions: Maybe<CustomDirective>, skipDocDirective?: Maybe<DirectiveName[]>) => Maybe<CustomDirective>;
223
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.
224
+ * Returns FORCE as the diff method.
225
+ * This function is used when documentation should be forcefully regenerated.
226
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
227
+ * @returns The FORCE diff method
230
228
  * @example
231
229
  * ```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"
230
+ * const method = getForcedDiffMethod();
231
+ * console.log(method); // "FORCE"
239
232
  * ```
240
233
  * @see {@link DiffMethod} for available diff methods
241
234
  */
242
- export declare const getDiffMethod: (diff: TypeDiffMethod, force?: boolean) => TypeDiffMethod;
235
+ export declare const getForcedDiffMethod: () => TypeDiffMethod;
236
+ export declare const getNormalizedDiffMethod: (diff: TypeDiffMethod) => TypeDiffMethod;
237
+ export declare const getDiffMethod: (diff: TypeDiffMethod) => TypeDiffMethod;
243
238
  /**
244
239
  * Placeholder function for handling deprecated document options.
245
240
  * Currently returns an empty object as these options are deprecated.
@@ -294,7 +289,7 @@ export declare const getDocOptions: (cliOpts?: Maybe<CliOptions & Omit<Deprecate
294
289
  * ```
295
290
  * @see {@link TypeHierarchy} for available hierarchy types
296
291
  */
297
- export declare const getTypeHierarchyOption: (cliOption?: Maybe<TypeHierarchyValueType>, configOption?: Maybe<TypeHierarchyType>) => Maybe<TypeHierarchyObjectType>;
292
+ export declare const getTypeHierarchyOption: (cliOption?: Maybe<TypeHierarchyValueType>, configOption?: Maybe<TypeHierarchyType>) => Maybe<Partial<Record<TypeHierarchyValueType, import("@graphql-markdown/types").TypeHierarchyTypeOptions>>>;
298
293
  /**
299
294
  * Placeholder function for handling deprecated print type options.
300
295
  * Currently returns an empty object as these options are deprecated.
@@ -343,7 +338,7 @@ export declare const getPrintTypeOptions: (cliOpts: Maybe<CliOptions & Omit<Depr
343
338
  * - fallback: (Optional) Fallback group name for items without the directive
344
339
  *
345
340
  * @param groupOptions - The group directive option as a string
346
- * @returns A parsed GroupByDirectiveOptions object or undefined if invalid
341
+ * @returns A parsed `GroupByDirectiveOptions` object or `undefined` if invalid
347
342
  * @throws Error if the groupByDirective format is invalid
348
343
  * @example
349
344
  * ```typescript
@@ -364,38 +359,5 @@ export declare const getPrintTypeOptions: (cliOpts: Maybe<CliOptions & Omit<Depr
364
359
  */
365
360
  export declare const parseGroupByOption: (groupOptions: unknown) => Maybe<GroupByDirectiveOptions>;
366
361
  export declare const parseHomepageOption: (cliHomepage: Maybe<string | false>, configHomepage: Maybe<string | false>) => Maybe<string>;
367
- /**
368
- * Builds the complete configuration object by merging options from multiple sources
369
- * in order of precedence:
370
- * 1. CLI options (highest priority)
371
- * 2. Configuration file options
372
- * 3. GraphQL Config options
373
- * 4. Default options (lowest priority)
374
- *
375
- * @param configFileOpts - Options from the configuration file
376
- * @param cliOpts - Options from the command line interface
377
- * @param id - The configuration ID used when referencing multiple schemas
378
- * @returns A promise resolving to the final merged configuration object
379
- * @example
380
- * ```typescript
381
- * // Basic usage with minimal options
382
- * const config = await buildConfig(
383
- * { baseURL: "api" }, // Config file options
384
- * { pretty: true } // CLI options
385
- * );
386
- *
387
- * // With specific config ID
388
- * const config = await buildConfig(
389
- * { schema: "./schemas/users.graphql" },
390
- * { force: true },
391
- * "users"
392
- * );
393
- *
394
- * // The resulting config will contain all required options
395
- * // with values from CLI taking precedence over config file,
396
- * // and defaults filling in any missing values
397
- * ```
398
- * @see {@link Options} for the complete configuration interface
399
- * @see {@link DEFAULT_OPTIONS} for default values
400
- */
401
362
  export declare const buildConfig: (configFileOpts: Maybe<ConfigOptions>, cliOpts?: Maybe<CliOptions>, id?: Maybe<string>) => Promise<Options>;
363
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,0BAA0B,EAC1B,gCAAgC,EAChC,aAAa,EAEb,uBAAuB,EACvB,KAAK,EACL,OAAO,EAIP,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAOjC;;;;;;;;;;;;GAYG;AACH,oBAAY,aAAa;IACvB,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED;;;;;;;;;;;GAWG;AACH,oBAAY,UAAU;IACpB,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,oBAAY,gBAAgB;IAC1B,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;CACd;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,qCAA+C,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,YAAY,gCAA0C,CAAC;AACpE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAKnC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;CAA8B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CACpC,IAAI,CAAC,aAAa,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,SAAS,CAAC,GACrE,QAAQ,CACN,IAAI,CACF,aAAa,EACX,iBAAiB,GACjB,kBAAkB,GAClB,SAAS,GACT,WAAW,GACX,kBAAkB,CACrB,CACF,CACJ,GAAG;IACF,gBAAgB,EAAE,QAAQ,CAAC,IAAI,CAAC,sBAAsB,EAAE,WAAW,CAAC,CAAC,GAAG;QACtE,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,uBAAuB,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;KACvE,CAAC;CAwCM,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,+CAY3B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,iHAchC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,sIAwBhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,uBAAuB;;;CAuBnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB,uHA+B/B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,sBAE/B,CAAC;AAEF,eAAO,MAAM,uBAAuB,0CAInC,CAAC;AAEF,eAAO,MAAM,aAAa,0CAEzB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,mJAKrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,wLAqBzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,sBAAsB,oMA0ClC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,yJAK3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB,wMAkC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,kBAAkB,2DAkB9B,CAAC;AAEF,eAAO,MAAM,mBAAmB,8FAiB/B,CAAC;AAmDF,eAAO,MAAM,WAAW,6GAiFvB,CAAC"}
package/dist/config.js CHANGED
@@ -17,10 +17,14 @@
17
17
  * @packageDocumentation
18
18
  */
19
19
  Object.defineProperty(exports, "__esModule", { value: true });
20
- exports.buildConfig = exports.parseHomepageOption = exports.parseGroupByOption = exports.getPrintTypeOptions = exports.parseDeprecatedPrintTypeOptions = exports.getTypeHierarchyOption = exports.getDocOptions = exports.parseDeprecatedDocOptions = exports.getDiffMethod = exports.getCustomDirectives = exports.getVisibilityDirectives = exports.getSkipDocDirectives = exports.getOnlyDocDirectives = exports.getDocDirective = exports.DEFAULT_OPTIONS = exports.DEFAULT_HIERARCHY = exports.ASSET_HOMEPAGE_LOCATION = exports.PACKAGE_NAME = exports.DOCS_URL = exports.DeprecatedOption = exports.DiffMethod = exports.TypeHierarchy = void 0;
20
+ exports.buildConfig = exports.parseHomepageOption = exports.parseGroupByOption = exports.getPrintTypeOptions = exports.parseDeprecatedPrintTypeOptions = exports.getTypeHierarchyOption = exports.getDocOptions = exports.parseDeprecatedDocOptions = exports.getDiffMethod = exports.getNormalizedDiffMethod = exports.getForcedDiffMethod = exports.getCustomDirectives = exports.getVisibilityDirectives = exports.getSkipDocDirectives = exports.getOnlyDocDirectives = exports.getDocDirective = exports.DEFAULT_OPTIONS = exports.DEFAULT_HIERARCHY = exports.ASSET_HOMEPAGE_LOCATION = exports.PACKAGE_NAME = exports.DOCS_URL = exports.DeprecatedOption = exports.DiffMethod = exports.TypeHierarchy = void 0;
21
21
  const node_path_1 = require("node:path");
22
22
  const node_os_1 = require("node:os");
23
+ const deepmerge_1 = require("@fastify/deepmerge");
23
24
  const graphql_config_1 = require("./graphql-config");
25
+ const patterns_1 = require("./const/patterns");
26
+ const validation_1 = require("./directives/validation");
27
+ const builder_1 = require("./options/builder");
24
28
  /**
25
29
  * Type hierarchy options for organizing schema documentation.
26
30
  *
@@ -109,6 +113,7 @@ exports.DEFAULT_OPTIONS = {
109
113
  customDirective: undefined,
110
114
  diffMethod: DiffMethod.NONE,
111
115
  docOptions: {
116
+ categorySort: undefined,
112
117
  frontMatter: {},
113
118
  index: false,
114
119
  },
@@ -151,11 +156,10 @@ exports.DEFAULT_OPTIONS = {
151
156
  * ```
152
157
  */
153
158
  const getDocDirective = (name) => {
154
- const OPTION_REGEX = /^@(?<directive>\w+)$/;
155
- if (typeof name !== "string" || !OPTION_REGEX.test(name)) {
159
+ if (typeof name !== "string" || !patterns_1.PATTERNS.DIRECTIVE_NAME.test(name)) {
156
160
  throw new Error(`Invalid "${name}"`);
157
161
  }
158
- const { groups: { directive }, } = OPTION_REGEX.exec(name);
162
+ const { groups: { directive }, } = patterns_1.PATTERNS.DIRECTIVE_NAME.exec(name);
159
163
  return directive;
160
164
  };
161
165
  exports.getDocDirective = getDocDirective;
@@ -210,7 +214,7 @@ const getSkipDocDirectives = (cliOpts, configFileOpts) => {
210
214
  });
211
215
  if ((configFileOpts &&
212
216
  configFileOpts.printTypeOptions?.deprecated === DeprecatedOption.SKIP) ||
213
- (cliOpts && cliOpts.deprecated === DeprecatedOption.SKIP)) {
217
+ cliOpts?.deprecated === DeprecatedOption.SKIP) {
214
218
  skipDirectives.push("deprecated");
215
219
  }
216
220
  return skipDirectives;
@@ -261,23 +265,23 @@ exports.getVisibilityDirectives = getVisibilityDirectives;
261
265
  *
262
266
  * @param customDirectiveOptions - The custom directive configuration object
263
267
  * @param skipDocDirective - Array of directive names that should be skipped
264
- * @returns The filtered custom directives object, or undefined if empty/invalid
268
+ * @returns The filtered custom directives object, or `undefined` if empty/invalid
265
269
  * @throws Error if a custom directive has an invalid format
266
270
  * @example
267
271
  * ```typescript
268
- * // Valid custom directive with tag function
272
+ * // Valid custom directive with descriptor function
269
273
  * const customDirectives = {
270
274
  * example: {
271
275
  * tag: (value) => `Example: ${value}`
272
276
  * },
273
- * todo: {
274
- * descriptor: () => "TODO items"
277
+ * note: {
278
+ * descriptor: () => "Note items"
275
279
  * }
276
280
  * };
277
281
  *
278
- * // Filter out the "example" directive
282
+ * // Filter out the "example" directive, keeping "note"
279
283
  * const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
280
- * console.log(filteredDirectives); // { todo: { descriptor: [Function] } }
284
+ * console.log(filteredDirectives); // { note: { descriptor: [Function] } }
281
285
  *
282
286
  * // Invalid format - will throw an error
283
287
  * getCustomDirectives({ example: { invalid: true } }, []);
@@ -295,40 +299,39 @@ const getCustomDirectives = (customDirectiveOptions, skipDocDirective) => {
295
299
  skipDocDirective.includes(name)) {
296
300
  delete customDirectiveOptions[name];
297
301
  }
298
- else if (("descriptor" in option && typeof option.descriptor !== "function") ||
299
- ("tag" in option && typeof option.tag !== "function") ||
302
+ else if ((0, validation_1.isInvalidFunctionProperty)(option, "descriptor") ||
303
+ (0, validation_1.isInvalidFunctionProperty)(option, "tag") ||
300
304
  !("tag" in option || "descriptor" in option)) {
301
305
  throw new Error(`Wrong format for plugin custom directive "${name}".\nPlease refer to ${exports.DOCS_URL}/advanced/custom-directive`);
302
306
  }
303
307
  }
304
- return Object.keys(customDirectiveOptions).length === 0
305
- ? undefined
306
- : customDirectiveOptions;
308
+ return Object.keys(customDirectiveOptions).length > 0
309
+ ? customDirectiveOptions
310
+ : undefined;
307
311
  };
308
312
  exports.getCustomDirectives = getCustomDirectives;
309
313
  /**
310
- * Determines the diff method to use based on the configuration and force flag.
311
- * If force is true, always returns FORCE regardless of the configured diff method.
314
+ * Returns FORCE as the diff method.
315
+ * This function is used when documentation should be forcefully regenerated.
312
316
  *
313
- * @param diff - The configured diff method
314
- * @param force - Whether to force regeneration (overrides diff setting)
315
- * @returns The resolved diff method to use
317
+ * @returns The FORCE diff method
316
318
  * @example
317
319
  * ```typescript
318
- * // Normal usage - respects the configured diff method
319
- * const method1 = getDiffMethod(DiffMethod.NONE, false);
320
- * console.log(method1); // "NONE"
321
- *
322
- * // Force flag overrides the diff method
323
- * const method2 = getDiffMethod(DiffMethod.NONE, true);
324
- * console.log(method2); // "FORCE"
320
+ * const method = getForcedDiffMethod();
321
+ * console.log(method); // "FORCE"
325
322
  * ```
326
323
  * @see {@link DiffMethod} for available diff methods
327
324
  */
328
- const getDiffMethod = (diff, force = false) => {
329
- return force
330
- ? DiffMethod.FORCE
331
- : diff.toLocaleUpperCase();
325
+ const getForcedDiffMethod = () => {
326
+ return DiffMethod.FORCE;
327
+ };
328
+ exports.getForcedDiffMethod = getForcedDiffMethod;
329
+ const getNormalizedDiffMethod = (diff) => {
330
+ return diff.toLocaleUpperCase();
331
+ };
332
+ exports.getNormalizedDiffMethod = getNormalizedDiffMethod;
333
+ const getDiffMethod = (diff) => {
334
+ return (0, exports.getNormalizedDiffMethod)(diff);
332
335
  };
333
336
  exports.getDiffMethod = getDiffMethod;
334
337
  /**
@@ -365,12 +368,11 @@ exports.parseDeprecatedDocOptions = parseDeprecatedDocOptions;
365
368
  */
366
369
  const getDocOptions = (cliOpts, configOptions) => {
367
370
  const deprecated = (0, exports.parseDeprecatedDocOptions)(cliOpts, configOptions);
368
- const index = typeof cliOpts?.index === "boolean"
369
- ? cliOpts.index
370
- : typeof configOptions?.index === "boolean"
371
- ? configOptions.index
372
- : exports.DEFAULT_OPTIONS.docOptions.index;
371
+ const cliIndex = typeof cliOpts?.index === "boolean" ? cliOpts.index : undefined;
372
+ const configIndex = typeof configOptions?.index === "boolean" ? configOptions.index : undefined;
373
+ const index = cliIndex ?? configIndex ?? exports.DEFAULT_OPTIONS.docOptions.index;
373
374
  return {
375
+ categorySort: configOptions?.categorySort,
374
376
  frontMatter: {
375
377
  ...deprecated,
376
378
  ...configOptions?.frontMatter,
@@ -505,7 +507,7 @@ exports.getPrintTypeOptions = getPrintTypeOptions;
505
507
  * - fallback: (Optional) Fallback group name for items without the directive
506
508
  *
507
509
  * @param groupOptions - The group directive option as a string
508
- * @returns A parsed GroupByDirectiveOptions object or undefined if invalid
510
+ * @returns A parsed `GroupByDirectiveOptions` object or `undefined` if invalid
509
511
  * @throws Error if the groupByDirective format is invalid
510
512
  * @example
511
513
  * ```typescript
@@ -525,20 +527,18 @@ exports.getPrintTypeOptions = getPrintTypeOptions;
525
527
  * ```
526
528
  */
527
529
  const parseGroupByOption = (groupOptions) => {
528
- const DEFAULT_GROUP = "Miscellaneous";
529
- const OPTION_REGEX = /^@(?<directive>\w+)\((?<field>\w+)(?:\|=(?<fallback>\w+))?\)/;
530
530
  if (typeof groupOptions !== "string") {
531
531
  return undefined;
532
532
  }
533
- const parsedOptions = OPTION_REGEX.exec(groupOptions);
534
- if (typeof parsedOptions === "undefined" || parsedOptions === null) {
533
+ const parsedOptions = patterns_1.PATTERNS.GROUP_BY_DIRECTIVE.exec(groupOptions);
534
+ if (parsedOptions === null) {
535
535
  throw new Error(`Invalid "${groupOptions}"`);
536
536
  }
537
- if (!("groups" in parsedOptions)) {
538
- return undefined;
539
- }
540
- const { directive, field, fallback = DEFAULT_GROUP, } = parsedOptions.groups;
541
- return { directive, field, fallback };
537
+ return {
538
+ directive: parsedOptions[1],
539
+ field: parsedOptions[2],
540
+ fallback: parsedOptions[3] || patterns_1.CONFIG_CONSTANTS.DEFAULT_GROUP,
541
+ };
542
542
  };
543
543
  exports.parseGroupByOption = parseGroupByOption;
544
544
  const parseHomepageOption = (cliHomepage, configHomepage) => {
@@ -554,72 +554,60 @@ const parseHomepageOption = (cliHomepage, configHomepage) => {
554
554
  return exports.DEFAULT_OPTIONS.homepage;
555
555
  };
556
556
  exports.parseHomepageOption = parseHomepageOption;
557
- /**
558
- * Builds the complete configuration object by merging options from multiple sources
559
- * in order of precedence:
560
- * 1. CLI options (highest priority)
561
- * 2. Configuration file options
562
- * 3. GraphQL Config options
563
- * 4. Default options (lowest priority)
564
- *
565
- * @param configFileOpts - Options from the configuration file
566
- * @param cliOpts - Options from the command line interface
567
- * @param id - The configuration ID used when referencing multiple schemas
568
- * @returns A promise resolving to the final merged configuration object
569
- * @example
570
- * ```typescript
571
- * // Basic usage with minimal options
572
- * const config = await buildConfig(
573
- * { baseURL: "api" }, // Config file options
574
- * { pretty: true } // CLI options
575
- * );
576
- *
577
- * // With specific config ID
578
- * const config = await buildConfig(
579
- * { schema: "./schemas/users.graphql" },
580
- * { force: true },
581
- * "users"
582
- * );
583
- *
584
- * // The resulting config will contain all required options
585
- * // with values from CLI taking precedence over config file,
586
- * // and defaults filling in any missing values
587
- * ```
588
- * @see {@link Options} for the complete configuration interface
589
- * @see {@link DEFAULT_OPTIONS} for default values
590
- */
591
557
  const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
592
558
  cliOpts ??= {};
593
559
  const graphqlConfig = await (0, graphql_config_1.loadConfiguration)(id);
594
- const config = {
595
- ...exports.DEFAULT_OPTIONS,
596
- ...graphqlConfig,
597
- ...configFileOpts,
598
- };
599
- const baseURL = cliOpts.base ?? config.baseURL;
560
+ const config = (0, deepmerge_1.deepmerge)()({ ...exports.DEFAULT_OPTIONS, ...graphqlConfig }, configFileOpts ?? {});
600
561
  const { onlyDocDirective, skipDocDirective } = (0, exports.getVisibilityDirectives)(cliOpts, config);
601
- const force = cliOpts.force ?? config.force ?? exports.DEFAULT_OPTIONS.force;
562
+ // Build options using consistent precedence: CLI > Config > Default
563
+ // The precedence is enforced by the OptionBuilder's setIfProvided method
564
+ // which only updates values if the source has higher precedence than the current source
565
+ const { baseURL, force, linkRoot, prettify, rootPath, schemaLocation, tmpDir, } = new builder_1.OptionBuilder()
566
+ .addDefault(exports.DEFAULT_OPTIONS.baseURL, "baseURL")
567
+ .addFromConfig(config.baseURL, "baseURL")
568
+ .addFromCli(cliOpts.base, "baseURL")
569
+ .addDefault(exports.DEFAULT_OPTIONS.force, "force")
570
+ .addFromConfig(config.force, "force")
571
+ .addFromCli(cliOpts.force, "force")
572
+ .addDefault(exports.DEFAULT_OPTIONS.linkRoot, "linkRoot")
573
+ .addFromConfig(config.linkRoot, "linkRoot")
574
+ .addFromCli(cliOpts.link, "linkRoot")
575
+ .addDefault(exports.DEFAULT_OPTIONS.pretty, "prettify")
576
+ .addFromConfig(config.pretty, "prettify")
577
+ .addFromCli(cliOpts.pretty, "prettify")
578
+ .addDefault(exports.DEFAULT_OPTIONS.rootPath, "rootPath")
579
+ .addFromConfig(config.rootPath, "rootPath")
580
+ .addFromCli(cliOpts.root, "rootPath")
581
+ .addDefault(exports.DEFAULT_OPTIONS.schema, "schemaLocation")
582
+ .addFromConfig(config.schema, "schemaLocation")
583
+ .addFromCli(cliOpts.schema, "schemaLocation")
584
+ .addDefault(exports.DEFAULT_OPTIONS.tmpDir, "tmpDir")
585
+ .addFromConfig(config.tmpDir, "tmpDir")
586
+ .addFromCli(cliOpts.tmp, "tmpDir")
587
+ .build();
602
588
  return {
603
589
  baseURL,
604
590
  customDirective: (0, exports.getCustomDirectives)(config.customDirective, skipDocDirective),
605
- diffMethod: (0, exports.getDiffMethod)(cliOpts.diff ?? config.diffMethod, force),
591
+ diffMethod: force
592
+ ? (0, exports.getForcedDiffMethod)()
593
+ : (0, exports.getDiffMethod)(cliOpts.diff ?? config.diffMethod),
606
594
  docOptions: (0, exports.getDocOptions)(cliOpts, config.docOptions),
607
595
  force,
608
596
  groupByDirective: (0, exports.parseGroupByOption)(cliOpts.groupByDirective) ?? config.groupByDirective,
609
597
  homepageLocation: (0, exports.parseHomepageOption)(cliOpts.homepage, config.homepage),
610
598
  id: id ?? exports.DEFAULT_OPTIONS.id,
611
- linkRoot: cliOpts.link ?? config.linkRoot ?? exports.DEFAULT_OPTIONS.linkRoot,
599
+ linkRoot,
612
600
  loaders: config.loaders,
613
601
  mdxParser: cliOpts.mdxParser ?? config.mdxParser,
614
602
  metatags: config.metatags ?? exports.DEFAULT_OPTIONS.metatags,
615
603
  onlyDocDirective,
616
- outputDir: (0, node_path_1.join)(cliOpts.root ?? config.rootPath, baseURL),
617
- prettify: cliOpts.pretty ?? config.pretty ?? exports.DEFAULT_OPTIONS.pretty,
604
+ outputDir: (0, node_path_1.join)(rootPath, baseURL),
605
+ prettify,
618
606
  printer: (config.printer ?? exports.DEFAULT_OPTIONS.printer),
619
607
  printTypeOptions: (0, exports.getPrintTypeOptions)(cliOpts, config.printTypeOptions),
620
- schemaLocation: cliOpts.schema ?? config.schema ?? exports.DEFAULT_OPTIONS.schema,
608
+ schemaLocation,
621
609
  skipDocDirective,
622
- tmpDir: cliOpts.tmp ?? config.tmpDir ?? exports.DEFAULT_OPTIONS.tmpDir,
610
+ tmpDir,
623
611
  };
624
612
  };
625
613
  exports.buildConfig = buildConfig;
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Regular expressions and string patterns used throughout the core package.
3
+ *
4
+ * This module centralizes all regex patterns and constants to ensure consistency
5
+ * and simplify maintenance when patterns need to be updated.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ /**
10
+ * Central repository of regex patterns used for configuration parsing and string transformation.
11
+ *
12
+ * @example
13
+ * ```typescript
14
+ * import { PATTERNS } from "@graphql-markdown/core/const/patterns";
15
+ *
16
+ * const match = PATTERNS.DIRECTIVE_NAME.exec("@myDirective");
17
+ * ```
18
+ */
19
+ export declare const PATTERNS: {
20
+ /**
21
+ * Matches directive names with named capture groups.
22
+ * Captures the directive name after the @ symbol.
23
+ *
24
+ * @pattern `^@(?<directive>\w+)$`
25
+ * @example
26
+ * - "@tag" matches → directive: "tag"
27
+ * - "@myDirective" matches → directive: "myDirective"
28
+ * - "@" does not match
29
+ * - "tag" does not match
30
+ */
31
+ readonly DIRECTIVE_NAME: RegExp;
32
+ /**
33
+ * Matches group-by directive format with directive name, field, and optional fallback.
34
+ * Groups: (1) directive name, (2) field name, (3) optional fallback
35
+ *
36
+ * @pattern `^@(\w+)\((\w+)(?:\|=(\w+))?\)$`
37
+ * @example
38
+ * - "@tag(name)" matches → ["@tag(name)", "tag", "name", undefined]
39
+ * - "@category(type|=Other)" matches → ["@category(type|=Other)", "category", "type", "Other"]
40
+ * - "@tag()" does not match
41
+ * - "tag(name)" does not match
42
+ */
43
+ readonly GROUP_BY_DIRECTIVE: RegExp;
44
+ /**
45
+ * Matches word boundaries (non-alphanumeric characters) for string splitting.
46
+ * Used globally to split strings on any non-alphanumeric character.
47
+ *
48
+ * @pattern `[^0-9A-Za-z]+`
49
+ * @example
50
+ * - "hello-world" split → ["hello", "world"]
51
+ * - "hello_world" split → ["hello", "world"]
52
+ * - "hello world" split → ["hello", "world"]
53
+ */
54
+ readonly WORD_BOUNDARY: RegExp;
55
+ /**
56
+ * Matches transitions between lowercase/digits and uppercase letters.
57
+ * Used to insert spaces in camelCase strings (e.g., "userId" → "user Id").
58
+ *
59
+ * @pattern `([a-z]+|\d+)([A-Z])`
60
+ * @example
61
+ * - "userId" matches → insert space between "id" and "U" → "user Id"
62
+ * - "HTTPServer" does not match (no lowercase/digit before uppercase)
63
+ * - "get2Users" matches → insert space between "2" and "U" → "get 2 Users"
64
+ */
65
+ readonly CASE_TRANSITION: RegExp;
66
+ /**
67
+ * Matches transitions from letters to digits.
68
+ * Used to insert spaces between letters and numbers (e.g., "user1" → "user 1").
69
+ *
70
+ * @pattern `([a-z]+)(\d)`
71
+ * @example
72
+ * - "user1" matches → "user 1"
73
+ * - "abc123" matches → "abc 123"
74
+ * - "U1" does not match (U is uppercase)
75
+ */
76
+ readonly LETTER_DIGIT_TRANSITION: RegExp;
77
+ /**
78
+ * Matches transitions from digits to letters.
79
+ * Used to insert spaces between numbers and letters (e.g., "2k" → "2 k").
80
+ *
81
+ * @pattern `(\d+)([a-z])`
82
+ * @example
83
+ * - "2k" matches → "2 k"
84
+ * - "123abc" matches → "123 abc"
85
+ * - "2K" does not match (K is uppercase)
86
+ */
87
+ readonly DIGIT_LETTER_TRANSITION: RegExp;
88
+ /**
89
+ * Matches numeric prefix for sorted categories (e.g., "01-query" → "query").
90
+ * Used to extract category names from numbered folder names.
91
+ *
92
+ * Pattern: `^\d{2}-`
93
+ *
94
+ * @example
95
+ * ```typescript
96
+ * - "01-query" matches → remove "01-" → "query"
97
+ * - "02-mutations" matches → remove "02-" → "mutations"
98
+ * - "query" does not match
99
+ * - "1-query" does not match (only 1 digit)
100
+ * ```
101
+ */
102
+ readonly NUMERIC_PREFIX: RegExp;
103
+ };
104
+ /**
105
+ * String constants used for configuration parsing and defaults.
106
+ */
107
+ export declare const CONFIG_CONSTANTS: {
108
+ /**
109
+ * Default fallback group name used when groupByDirective is configured.
110
+ * Items without the grouping directive are assigned to this group.
111
+ */
112
+ readonly DEFAULT_GROUP: "Miscellaneous";
113
+ };
114
+ //# sourceMappingURL=patterns.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/const/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;;;;;;;OAUG;;IAGH;;;;;;;;;;OAUG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;;;;;OAaG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;OAGG;;CAEK,CAAC"}
@@ -0,0 +1,116 @@
1
+ "use strict";
2
+ /**
3
+ * Regular expressions and string patterns used throughout the core package.
4
+ *
5
+ * This module centralizes all regex patterns and constants to ensure consistency
6
+ * and simplify maintenance when patterns need to be updated.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.CONFIG_CONSTANTS = exports.PATTERNS = void 0;
12
+ /**
13
+ * Central repository of regex patterns used for configuration parsing and string transformation.
14
+ *
15
+ * @example
16
+ * ```typescript
17
+ * import { PATTERNS } from "@graphql-markdown/core/const/patterns";
18
+ *
19
+ * const match = PATTERNS.DIRECTIVE_NAME.exec("@myDirective");
20
+ * ```
21
+ */
22
+ exports.PATTERNS = {
23
+ /**
24
+ * Matches directive names with named capture groups.
25
+ * Captures the directive name after the @ symbol.
26
+ *
27
+ * @pattern `^@(?<directive>\w+)$`
28
+ * @example
29
+ * - "@tag" matches → directive: "tag"
30
+ * - "@myDirective" matches → directive: "myDirective"
31
+ * - "@" does not match
32
+ * - "tag" does not match
33
+ */
34
+ DIRECTIVE_NAME: /^@(?<directive>\w+)$/, // NOSONAR: S5843
35
+ /**
36
+ * Matches group-by directive format with directive name, field, and optional fallback.
37
+ * Groups: (1) directive name, (2) field name, (3) optional fallback
38
+ *
39
+ * @pattern `^@(\w+)\((\w+)(?:\|=(\w+))?\)$`
40
+ * @example
41
+ * - "@tag(name)" matches → ["@tag(name)", "tag", "name", undefined]
42
+ * - "@category(type|=Other)" matches → ["@category(type|=Other)", "category", "type", "Other"]
43
+ * - "@tag()" does not match
44
+ * - "tag(name)" does not match
45
+ */
46
+ GROUP_BY_DIRECTIVE: /^@(\w+)\((\w+)(?:\|=(\w+))?\)$/, // NOSONAR: S5843
47
+ /**
48
+ * Matches word boundaries (non-alphanumeric characters) for string splitting.
49
+ * Used globally to split strings on any non-alphanumeric character.
50
+ *
51
+ * @pattern `[^0-9A-Za-z]+`
52
+ * @example
53
+ * - "hello-world" split → ["hello", "world"]
54
+ * - "hello_world" split → ["hello", "world"]
55
+ * - "hello world" split → ["hello", "world"]
56
+ */
57
+ WORD_BOUNDARY: /[^0-9A-Za-z]+/g, // NOSONAR: S5843
58
+ /**
59
+ * Matches transitions between lowercase/digits and uppercase letters.
60
+ * Used to insert spaces in camelCase strings (e.g., "userId" → "user Id").
61
+ *
62
+ * @pattern `([a-z]+|\d+)([A-Z])`
63
+ * @example
64
+ * - "userId" matches → insert space between "id" and "U" → "user Id"
65
+ * - "HTTPServer" does not match (no lowercase/digit before uppercase)
66
+ * - "get2Users" matches → insert space between "2" and "U" → "get 2 Users"
67
+ */
68
+ CASE_TRANSITION: /([a-z]+|\d+)([A-Z])/g, // NOSONAR: S5843
69
+ /**
70
+ * Matches transitions from letters to digits.
71
+ * Used to insert spaces between letters and numbers (e.g., "user1" → "user 1").
72
+ *
73
+ * @pattern `([a-z]+)(\d)`
74
+ * @example
75
+ * - "user1" matches → "user 1"
76
+ * - "abc123" matches → "abc 123"
77
+ * - "U1" does not match (U is uppercase)
78
+ */
79
+ LETTER_DIGIT_TRANSITION: /([a-z]+)(\d)/g, // NOSONAR: S5843
80
+ /**
81
+ * Matches transitions from digits to letters.
82
+ * Used to insert spaces between numbers and letters (e.g., "2k" → "2 k").
83
+ *
84
+ * @pattern `(\d+)([a-z])`
85
+ * @example
86
+ * - "2k" matches → "2 k"
87
+ * - "123abc" matches → "123 abc"
88
+ * - "2K" does not match (K is uppercase)
89
+ */
90
+ DIGIT_LETTER_TRANSITION: /(\d+)([a-z])/g, // NOSONAR: S5843
91
+ /**
92
+ * Matches numeric prefix for sorted categories (e.g., "01-query" → "query").
93
+ * Used to extract category names from numbered folder names.
94
+ *
95
+ * Pattern: `^\d{2}-`
96
+ *
97
+ * @example
98
+ * ```typescript
99
+ * - "01-query" matches → remove "01-" → "query"
100
+ * - "02-mutations" matches → remove "02-" → "mutations"
101
+ * - "query" does not match
102
+ * - "1-query" does not match (only 1 digit)
103
+ * ```
104
+ */
105
+ NUMERIC_PREFIX: /^\d{2}-/, // NOSONAR: S5843
106
+ };
107
+ /**
108
+ * String constants used for configuration parsing and defaults.
109
+ */
110
+ exports.CONFIG_CONSTANTS = {
111
+ /**
112
+ * Default fallback group name used when groupByDirective is configured.
113
+ * Items without the grouping directive are assigned to this group.
114
+ */
115
+ DEFAULT_GROUP: "Miscellaneous",
116
+ };
package/dist/diff.d.ts CHANGED
@@ -51,3 +51,4 @@ import type { DiffMethodName, GraphQLSchema, Maybe } from "@graphql-markdown/typ
51
51
  * @since 1.0.0
52
52
  */
53
53
  export declare const hasChanges: (schema: GraphQLSchema, tmpDir: string, diffMethod: Maybe<DiffMethodName>, diffModule?: Maybe<string>) => Promise<boolean>;
54
+ //# sourceMappingURL=diff.d.ts.map