@graphql-markdown/core 1.16.3 → 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 +80 -89
  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 -16
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,11 +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
23
  const deepmerge_1 = require("@fastify/deepmerge");
24
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");
25
28
  /**
26
29
  * Type hierarchy options for organizing schema documentation.
27
30
  *
@@ -110,6 +113,7 @@ exports.DEFAULT_OPTIONS = {
110
113
  customDirective: undefined,
111
114
  diffMethod: DiffMethod.NONE,
112
115
  docOptions: {
116
+ categorySort: undefined,
113
117
  frontMatter: {},
114
118
  index: false,
115
119
  },
@@ -152,11 +156,10 @@ exports.DEFAULT_OPTIONS = {
152
156
  * ```
153
157
  */
154
158
  const getDocDirective = (name) => {
155
- const OPTION_REGEX = /^@(?<directive>\w+)$/;
156
- if (typeof name !== "string" || !OPTION_REGEX.test(name)) {
159
+ if (typeof name !== "string" || !patterns_1.PATTERNS.DIRECTIVE_NAME.test(name)) {
157
160
  throw new Error(`Invalid "${name}"`);
158
161
  }
159
- const { groups: { directive }, } = OPTION_REGEX.exec(name);
162
+ const { groups: { directive }, } = patterns_1.PATTERNS.DIRECTIVE_NAME.exec(name);
160
163
  return directive;
161
164
  };
162
165
  exports.getDocDirective = getDocDirective;
@@ -211,7 +214,7 @@ const getSkipDocDirectives = (cliOpts, configFileOpts) => {
211
214
  });
212
215
  if ((configFileOpts &&
213
216
  configFileOpts.printTypeOptions?.deprecated === DeprecatedOption.SKIP) ||
214
- (cliOpts && cliOpts.deprecated === DeprecatedOption.SKIP)) {
217
+ cliOpts?.deprecated === DeprecatedOption.SKIP) {
215
218
  skipDirectives.push("deprecated");
216
219
  }
217
220
  return skipDirectives;
@@ -262,23 +265,23 @@ exports.getVisibilityDirectives = getVisibilityDirectives;
262
265
  *
263
266
  * @param customDirectiveOptions - The custom directive configuration object
264
267
  * @param skipDocDirective - Array of directive names that should be skipped
265
- * @returns The filtered custom directives object, or undefined if empty/invalid
268
+ * @returns The filtered custom directives object, or `undefined` if empty/invalid
266
269
  * @throws Error if a custom directive has an invalid format
267
270
  * @example
268
271
  * ```typescript
269
- * // Valid custom directive with tag function
272
+ * // Valid custom directive with descriptor function
270
273
  * const customDirectives = {
271
274
  * example: {
272
275
  * tag: (value) => `Example: ${value}`
273
276
  * },
274
- * todo: {
275
- * descriptor: () => "TODO items"
277
+ * note: {
278
+ * descriptor: () => "Note items"
276
279
  * }
277
280
  * };
278
281
  *
279
- * // Filter out the "example" directive
282
+ * // Filter out the "example" directive, keeping "note"
280
283
  * const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
281
- * console.log(filteredDirectives); // { todo: { descriptor: [Function] } }
284
+ * console.log(filteredDirectives); // { note: { descriptor: [Function] } }
282
285
  *
283
286
  * // Invalid format - will throw an error
284
287
  * getCustomDirectives({ example: { invalid: true } }, []);
@@ -296,40 +299,39 @@ const getCustomDirectives = (customDirectiveOptions, skipDocDirective) => {
296
299
  skipDocDirective.includes(name)) {
297
300
  delete customDirectiveOptions[name];
298
301
  }
299
- else if (("descriptor" in option && typeof option.descriptor !== "function") ||
300
- ("tag" in option && typeof option.tag !== "function") ||
302
+ else if ((0, validation_1.isInvalidFunctionProperty)(option, "descriptor") ||
303
+ (0, validation_1.isInvalidFunctionProperty)(option, "tag") ||
301
304
  !("tag" in option || "descriptor" in option)) {
302
305
  throw new Error(`Wrong format for plugin custom directive "${name}".\nPlease refer to ${exports.DOCS_URL}/advanced/custom-directive`);
303
306
  }
304
307
  }
305
- return Object.keys(customDirectiveOptions).length === 0
306
- ? undefined
307
- : customDirectiveOptions;
308
+ return Object.keys(customDirectiveOptions).length > 0
309
+ ? customDirectiveOptions
310
+ : undefined;
308
311
  };
309
312
  exports.getCustomDirectives = getCustomDirectives;
310
313
  /**
311
- * Determines the diff method to use based on the configuration and force flag.
312
- * 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.
313
316
  *
314
- * @param diff - The configured diff method
315
- * @param force - Whether to force regeneration (overrides diff setting)
316
- * @returns The resolved diff method to use
317
+ * @returns The FORCE diff method
317
318
  * @example
318
319
  * ```typescript
319
- * // Normal usage - respects the configured diff method
320
- * const method1 = getDiffMethod(DiffMethod.NONE, false);
321
- * console.log(method1); // "NONE"
322
- *
323
- * // Force flag overrides the diff method
324
- * const method2 = getDiffMethod(DiffMethod.NONE, true);
325
- * console.log(method2); // "FORCE"
320
+ * const method = getForcedDiffMethod();
321
+ * console.log(method); // "FORCE"
326
322
  * ```
327
323
  * @see {@link DiffMethod} for available diff methods
328
324
  */
329
- const getDiffMethod = (diff, force = false) => {
330
- return force
331
- ? DiffMethod.FORCE
332
- : 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);
333
335
  };
334
336
  exports.getDiffMethod = getDiffMethod;
335
337
  /**
@@ -366,12 +368,11 @@ exports.parseDeprecatedDocOptions = parseDeprecatedDocOptions;
366
368
  */
367
369
  const getDocOptions = (cliOpts, configOptions) => {
368
370
  const deprecated = (0, exports.parseDeprecatedDocOptions)(cliOpts, configOptions);
369
- const index = typeof cliOpts?.index === "boolean"
370
- ? cliOpts.index
371
- : typeof configOptions?.index === "boolean"
372
- ? configOptions.index
373
- : 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;
374
374
  return {
375
+ categorySort: configOptions?.categorySort,
375
376
  frontMatter: {
376
377
  ...deprecated,
377
378
  ...configOptions?.frontMatter,
@@ -506,7 +507,7 @@ exports.getPrintTypeOptions = getPrintTypeOptions;
506
507
  * - fallback: (Optional) Fallback group name for items without the directive
507
508
  *
508
509
  * @param groupOptions - The group directive option as a string
509
- * @returns A parsed GroupByDirectiveOptions object or undefined if invalid
510
+ * @returns A parsed `GroupByDirectiveOptions` object or `undefined` if invalid
510
511
  * @throws Error if the groupByDirective format is invalid
511
512
  * @example
512
513
  * ```typescript
@@ -526,20 +527,18 @@ exports.getPrintTypeOptions = getPrintTypeOptions;
526
527
  * ```
527
528
  */
528
529
  const parseGroupByOption = (groupOptions) => {
529
- const DEFAULT_GROUP = "Miscellaneous";
530
- const OPTION_REGEX = /^@(?<directive>\w+)\((?<field>\w+)(?:\|=(?<fallback>\w+))?\)/;
531
530
  if (typeof groupOptions !== "string") {
532
531
  return undefined;
533
532
  }
534
- const parsedOptions = OPTION_REGEX.exec(groupOptions);
535
- if (typeof parsedOptions === "undefined" || parsedOptions === null) {
533
+ const parsedOptions = patterns_1.PATTERNS.GROUP_BY_DIRECTIVE.exec(groupOptions);
534
+ if (parsedOptions === null) {
536
535
  throw new Error(`Invalid "${groupOptions}"`);
537
536
  }
538
- if (!("groups" in parsedOptions)) {
539
- return undefined;
540
- }
541
- const { directive, field, fallback = DEFAULT_GROUP, } = parsedOptions.groups;
542
- 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
+ };
543
542
  };
544
543
  exports.parseGroupByOption = parseGroupByOption;
545
544
  const parseHomepageOption = (cliHomepage, configHomepage) => {
@@ -555,68 +554,60 @@ const parseHomepageOption = (cliHomepage, configHomepage) => {
555
554
  return exports.DEFAULT_OPTIONS.homepage;
556
555
  };
557
556
  exports.parseHomepageOption = parseHomepageOption;
558
- /**
559
- * Builds the complete configuration object by merging options from multiple sources
560
- * in order of precedence:
561
- * 1. CLI options (highest priority)
562
- * 2. Configuration file options
563
- * 3. GraphQL Config options
564
- * 4. Default options (lowest priority)
565
- *
566
- * @param configFileOpts - Options from the configuration file
567
- * @param cliOpts - Options from the command line interface
568
- * @param id - The configuration ID used when referencing multiple schemas
569
- * @returns A promise resolving to the final merged configuration object
570
- * @example
571
- * ```typescript
572
- * // Basic usage with minimal options
573
- * const config = await buildConfig(
574
- * { baseURL: "api" }, // Config file options
575
- * { pretty: true } // CLI options
576
- * );
577
- *
578
- * // With specific config ID
579
- * const config = await buildConfig(
580
- * { schema: "./schemas/users.graphql" },
581
- * { force: true },
582
- * "users"
583
- * );
584
- *
585
- * // The resulting config will contain all required options
586
- * // with values from CLI taking precedence over config file,
587
- * // and defaults filling in any missing values
588
- * ```
589
- * @see {@link Options} for the complete configuration interface
590
- * @see {@link DEFAULT_OPTIONS} for default values
591
- */
592
557
  const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
593
558
  cliOpts ??= {};
594
559
  const graphqlConfig = await (0, graphql_config_1.loadConfiguration)(id);
595
560
  const config = (0, deepmerge_1.deepmerge)()({ ...exports.DEFAULT_OPTIONS, ...graphqlConfig }, configFileOpts ?? {});
596
- const baseURL = cliOpts.base ?? config.baseURL;
597
561
  const { onlyDocDirective, skipDocDirective } = (0, exports.getVisibilityDirectives)(cliOpts, config);
598
- 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();
599
588
  return {
600
589
  baseURL,
601
590
  customDirective: (0, exports.getCustomDirectives)(config.customDirective, skipDocDirective),
602
- diffMethod: (0, exports.getDiffMethod)(cliOpts.diff ?? config.diffMethod, force),
591
+ diffMethod: force
592
+ ? (0, exports.getForcedDiffMethod)()
593
+ : (0, exports.getDiffMethod)(cliOpts.diff ?? config.diffMethod),
603
594
  docOptions: (0, exports.getDocOptions)(cliOpts, config.docOptions),
604
595
  force,
605
596
  groupByDirective: (0, exports.parseGroupByOption)(cliOpts.groupByDirective) ?? config.groupByDirective,
606
597
  homepageLocation: (0, exports.parseHomepageOption)(cliOpts.homepage, config.homepage),
607
598
  id: id ?? exports.DEFAULT_OPTIONS.id,
608
- linkRoot: cliOpts.link ?? config.linkRoot ?? exports.DEFAULT_OPTIONS.linkRoot,
599
+ linkRoot,
609
600
  loaders: config.loaders,
610
601
  mdxParser: cliOpts.mdxParser ?? config.mdxParser,
611
602
  metatags: config.metatags ?? exports.DEFAULT_OPTIONS.metatags,
612
603
  onlyDocDirective,
613
- outputDir: (0, node_path_1.join)(cliOpts.root ?? config.rootPath, baseURL),
614
- prettify: cliOpts.pretty ?? config.pretty ?? exports.DEFAULT_OPTIONS.pretty,
604
+ outputDir: (0, node_path_1.join)(rootPath, baseURL),
605
+ prettify,
615
606
  printer: (config.printer ?? exports.DEFAULT_OPTIONS.printer),
616
607
  printTypeOptions: (0, exports.getPrintTypeOptions)(cliOpts, config.printTypeOptions),
617
- schemaLocation: cliOpts.schema ?? config.schema ?? exports.DEFAULT_OPTIONS.schema,
608
+ schemaLocation,
618
609
  skipDocDirective,
619
- tmpDir: cliOpts.tmp ?? config.tmpDir ?? exports.DEFAULT_OPTIONS.tmpDir,
610
+ tmpDir,
620
611
  };
621
612
  };
622
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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACb,KAAK,EACN,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,UAAU,4HAwBtB,CAAC"}