@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
@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.loadConfiguration = exports.setLoaderOptions = exports.graphQLConfigExtension = exports.EXTENSION_NAME = void 0;
37
37
  const logger_1 = require("@graphql-markdown/logger");
38
+ const validation_1 = require("./directives/validation");
38
39
  /**
39
40
  * The name of the GraphQL Markdown extension.
40
41
  * Used to identify the extension in graphql-config.
@@ -57,6 +58,14 @@ const graphQLConfigExtension = () => {
57
58
  return { name: exports.EXTENSION_NAME };
58
59
  };
59
60
  exports.graphQLConfigExtension = graphQLConfigExtension;
61
+ /**
62
+ * Default throw options for loading configuration.
63
+ * @internal
64
+ */
65
+ const DEFAULT_THROW_OPTIONS = {
66
+ throwOnMissing: false,
67
+ throwOnEmpty: false,
68
+ };
60
69
  /**
61
70
  * Sets loader options for GraphQL Markdown loaders.
62
71
  *
@@ -82,7 +91,7 @@ exports.graphQLConfigExtension = graphQLConfigExtension;
82
91
  */
83
92
  const setLoaderOptions = (loaders, options) => {
84
93
  for (const loader in loaders) {
85
- if (typeof loaders[loader] === "string") {
94
+ if ((0, validation_1.isLoaderString)(loaders[loader])) {
86
95
  loaders[loader] = {
87
96
  module: loaders[loader],
88
97
  options,
@@ -108,7 +117,7 @@ exports.setLoaderOptions = setLoaderOptions;
108
117
  * @param id - The project ID to load configuration for.
109
118
  * @param options - Optional package options to apply.
110
119
  * @param throwOptions - Options for controlling throw behavior.
111
- * @returns The extension project configuration if found, otherwise undefined.
120
+ * @returns The extension project configuration if found, otherwise `undefined`.
112
121
  *
113
122
  * @throws Will throw an error if throwOnMissing or throwOnEmpty is true and
114
123
  * the corresponding condition is met.
@@ -126,10 +135,7 @@ exports.setLoaderOptions = setLoaderOptions;
126
135
  * );
127
136
  * ```
128
137
  */
129
- const loadConfiguration = async (id, options, { throwOnMissing, throwOnEmpty } = {
130
- throwOnMissing: false,
131
- throwOnEmpty: false,
132
- }) => {
138
+ const loadConfiguration = async (id, options, { throwOnMissing, throwOnEmpty } = DEFAULT_THROW_OPTIONS) => {
133
139
  let graphQLConfig;
134
140
  if (typeof id !== "string") {
135
141
  return undefined;
@@ -156,13 +162,13 @@ const loadConfiguration = async (id, options, { throwOnMissing, throwOnEmpty } =
156
162
  .extension(exports.EXTENSION_NAME);
157
163
  if (Array.isArray(projectConfig.schema)) {
158
164
  const schema = projectConfig.schema[0];
159
- if (typeof schema === "string") {
165
+ if ((0, validation_1.isSchemaString)(schema)) {
160
166
  projectConfig.schema = schema;
161
167
  }
162
- if (typeof projectConfig.schema === "object") {
168
+ else if ((0, validation_1.isSchemaObject)(schema)) {
163
169
  projectConfig.schema = Object.keys(schema)[0];
164
- if (typeof projectConfig.loaders !== "undefined") {
165
- projectConfig.loaders = (0, exports.setLoaderOptions)(projectConfig.loaders ?? {}, Object.values(schema)[0]);
170
+ if (projectConfig.loaders) {
171
+ projectConfig.loaders = (0, exports.setLoaderOptions)(projectConfig.loaders, Object.values(schema)[0]);
166
172
  }
167
173
  }
168
174
  }
@@ -0,0 +1,10 @@
1
+ export type Callback = (...args: unknown[]) => unknown;
2
+ export interface Subscription {
3
+ unsubscribe: () => void;
4
+ }
5
+ export declare abstract class Hookable {
6
+ map: Map<string, Callback[]>;
7
+ subscribe(hookName: string, callback: Callback): Subscription;
8
+ protected emit(hookName: string, args?: unknown[]): unknown[];
9
+ }
10
+ //# sourceMappingURL=hooks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AACvD,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,8BAAsB,QAAQ;IAC5B,GAAG,0BAAiC;IAEpC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAiB5D;IAED,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,EAAO,GAAG,OAAO,EAAE,CAQhE;CACF"}
package/dist/hooks.js ADDED
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.Hookable = void 0;
4
+ class Hookable {
5
+ map = new Map();
6
+ subscribe(hookName, callback) {
7
+ if (!this.map.has(hookName))
8
+ this.map.set(hookName, []);
9
+ const arr = this.map.get(hookName) ?? [];
10
+ arr.push(callback);
11
+ return {
12
+ unsubscribe: () => {
13
+ const index = arr.indexOf(callback);
14
+ if (index === -1) {
15
+ return;
16
+ }
17
+ arr.splice(index, 1);
18
+ if (arr.length === 0) {
19
+ this.map.delete(hookName);
20
+ }
21
+ },
22
+ };
23
+ }
24
+ emit(hookName, args = []) {
25
+ const handlers = this.map.get(hookName);
26
+ if (handlers)
27
+ return handlers.map((handler) => {
28
+ return handler(...args);
29
+ });
30
+ return [];
31
+ }
32
+ }
33
+ exports.Hookable = Hookable;
package/dist/index.d.ts CHANGED
@@ -3,3 +3,14 @@
3
3
  */
4
4
  export { generateDocFromSchema } from "./generator";
5
5
  export { buildConfig } from "./config";
6
+ export { getEvents, resetEvents, type EmitResult } from "./event-emitter";
7
+ export { registerMDXEventHandlers } from "./event-handlers";
8
+ export { EVENT_CALLBACK_MAP } from "./event-map";
9
+ export type { CancellableEvent } from "./events/base";
10
+ export type { SchemaLoadEvent } from "./events/schema-load";
11
+ export type { DiffCheckEvent } from "./events/diff-check";
12
+ export type { RenderRootTypesEvent } from "./events/render-root-types";
13
+ export type { RenderHomepageEvent } from "./events/render-homepage";
14
+ export type { RenderTypeEntitiesEvent } from "./events/render-type-entities";
15
+ export type { GenerateIndexMetafileEvent } from "./events/generate-index-metafile";
16
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC7E,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC"}
package/dist/index.js CHANGED
@@ -4,8 +4,16 @@
4
4
  */
5
5
  /* istanbul ignore file */
6
6
  Object.defineProperty(exports, "__esModule", { value: true });
7
- exports.buildConfig = exports.generateDocFromSchema = void 0;
8
- var generator_1 = require("./generator");
7
+ exports.EVENT_CALLBACK_MAP = exports.registerMDXEventHandlers = exports.resetEvents = exports.getEvents = exports.buildConfig = exports.generateDocFromSchema = void 0;
8
+ const generator_1 = require("./generator");
9
9
  Object.defineProperty(exports, "generateDocFromSchema", { enumerable: true, get: function () { return generator_1.generateDocFromSchema; } });
10
- var config_1 = require("./config");
10
+ const config_1 = require("./config");
11
11
  Object.defineProperty(exports, "buildConfig", { enumerable: true, get: function () { return config_1.buildConfig; } });
12
+ // Event system exports
13
+ const event_emitter_1 = require("./event-emitter");
14
+ Object.defineProperty(exports, "getEvents", { enumerable: true, get: function () { return event_emitter_1.getEvents; } });
15
+ Object.defineProperty(exports, "resetEvents", { enumerable: true, get: function () { return event_emitter_1.resetEvents; } });
16
+ const event_handlers_1 = require("./event-handlers");
17
+ Object.defineProperty(exports, "registerMDXEventHandlers", { enumerable: true, get: function () { return event_handlers_1.registerMDXEventHandlers; } });
18
+ const event_map_1 = require("./event-map");
19
+ Object.defineProperty(exports, "EVENT_CALLBACK_MAP", { enumerable: true, get: function () { return event_map_1.EVENT_CALLBACK_MAP; } });
@@ -0,0 +1,157 @@
1
+ /**
2
+ * Option builder for handling CLI/config/default option precedence.
3
+ *
4
+ * This utility provides a fluent interface for merging options from multiple
5
+ * sources (CLI, config file, defaults) with consistent precedence rules:
6
+ * 1. CLI options (highest priority)
7
+ * 2. Config file options
8
+ * 3. Default values (lowest priority)
9
+ *
10
+ * Precedence is enforced semantically via the setIfProvided() method,
11
+ * regardless of the order in which methods are called. Each value tracks its
12
+ * source, and only higher-precedence sources can override existing values.
13
+ *
14
+ * Eliminates repetitive if/coalesce patterns throughout the codebase.
15
+ *
16
+ * @packageDocumentation
17
+ */
18
+ import type { Maybe } from "@graphql-markdown/types";
19
+ /**
20
+ * Builder for constructing options from multiple sources with priority precedence.
21
+ *
22
+ * Precedence is enforced semantically via source tracking, not by call order.
23
+ * CLI values always override config values, which always override defaults,
24
+ * regardless of the order in which methods are called.
25
+ *
26
+ * @template T - The type of the options object being built
27
+ *
28
+ * @example
29
+ * ```typescript
30
+ * const options = new OptionBuilder<MyOptions>()
31
+ * // Add in order: default -> config -> cli
32
+ * .addDefault(false, "pretty")
33
+ * .addFromConfig(undefined, "pretty")
34
+ * .addFromCli(true, "pretty") // CLI overrides default
35
+ * .addDefault("/", "baseURL")
36
+ * .addFromConfig("/api", "baseURL") // Config overrides default
37
+ * .addFromCli(undefined, "baseURL")
38
+ * .build();
39
+ * // Result: { pretty: true, baseURL: "/api" }
40
+ * ```
41
+ */
42
+ export declare class OptionBuilder<T extends Record<string, unknown>> {
43
+ private static readonly PRECEDENCE_ORDER;
44
+ private merged;
45
+ private readonly sources;
46
+ /**
47
+ * Adds a default value (lowest priority).
48
+ * Sets a value that can be overwritten by config or CLI options.
49
+ * This method can be called at any time; precedence is enforced semantically.
50
+ *
51
+ * @param value - The default value
52
+ * @param key - The key to store the value under
53
+ * @returns This builder for method chaining
54
+ *
55
+ * @example
56
+ * ```typescript
57
+ * builder.addDefault(3000, "port")
58
+ * ```
59
+ */
60
+ addDefault<K extends keyof T>(value: Maybe<T[K]>, key: K): this;
61
+ /**
62
+ * Adds a value from config file if provided (medium priority).
63
+ * Can override default values if the config value exists.
64
+ * This method can be called at any time; precedence is enforced semantically.
65
+ *
66
+ * @param value - The config file option value
67
+ * @param key - The key to store the value under
68
+ * @returns This builder for method chaining
69
+ *
70
+ * @example
71
+ * ```typescript
72
+ * builder.addFromConfig(config.port, "port")
73
+ * ```
74
+ */
75
+ addFromConfig<K extends keyof T>(value: Maybe<T[K]>, key: K): this;
76
+ /**
77
+ * Adds a value from CLI options if provided (highest priority).
78
+ * Can override both default and config values for this key.
79
+ * This method can be called at any time; precedence is enforced semantically.
80
+ *
81
+ * @param value - The CLI option value
82
+ * @param key - The key to store the value under
83
+ * @returns This builder for method chaining
84
+ *
85
+ * @example
86
+ * ```typescript
87
+ * builder.addFromCli(cliOpts.port, "port")
88
+ * ```
89
+ */
90
+ addFromCli<K extends keyof T>(value: Maybe<T[K]>, key: K): this;
91
+ /**
92
+ * Sets a value if it's not null or undefined, respecting precedence.
93
+ * Internal helper method used by addDefault, addFromConfig, and addFromCli.
94
+ *
95
+ * Only updates the merged value if the source has equal or higher precedence
96
+ * than the currently stored source. Precedence order: default < config < cli.
97
+ *
98
+ * @param value - The value to set
99
+ * @param key - The key to set
100
+ * @param source - The source of this value ('default', 'config', or 'cli')
101
+ * @returns This builder for method chaining
102
+ */
103
+ private setIfProvided;
104
+ /**
105
+ * Transforms a value using a function if the key exists.
106
+ * Useful for processing values after they've been set.
107
+ *
108
+ * @param key - The key to transform
109
+ * @param fn - Function that transforms the current value
110
+ * @returns This builder for method chaining
111
+ *
112
+ * @example
113
+ * ```typescript
114
+ * builder.transform("path", (p) => resolve(p))
115
+ * ```
116
+ */
117
+ transform<K extends keyof T>(key: K, fn: (v: T[K]) => T[K]): this;
118
+ /**
119
+ * Conditionally applies a transformation if a predicate is true.
120
+ * Useful for applying different transformations based on other values.
121
+ *
122
+ * @param key - The key to potentially transform
123
+ * @param predicate - Function that determines if transformation should apply
124
+ * @param fn - Function that transforms the value if predicate is true
125
+ * @returns This builder for method chaining
126
+ *
127
+ * @example
128
+ * ```typescript
129
+ * builder.transformIf("path", () => force, (p) => resolve(p))
130
+ * ```
131
+ */
132
+ transformIf<K extends keyof T>(key: K, predicate: (merged: Partial<T>) => boolean, fn: (v: T[K]) => T[K]): this;
133
+ /**
134
+ * Gets the current value for a key without building.
135
+ * Useful for conditional logic during building.
136
+ * Returns a shallow copy for arrays and objects to prevent external mutations.
137
+ * Note: Nested objects and arrays are not deep copied.
138
+ *
139
+ * @param key - The key to get
140
+ * @returns The current value for the key, or `undefined` if not set
141
+ */
142
+ get<K extends keyof T>(key: K): T[K] | undefined;
143
+ /**
144
+ * Returns the built options object with all accumulated values.
145
+ * The object contains all keys that were set during the building process.
146
+ *
147
+ * Note: The returned object may be a partial object containing only the keys
148
+ * that were set. Callers should handle potentially missing properties.
149
+ * Returns a defensive copy of the object to prevent external mutations of
150
+ * internal state. Arrays and objects are shallow-copied to protect against
151
+ * external modifications.
152
+ *
153
+ * @returns The constructed options object with type `Partial<T>` (may not have all properties of `T`)
154
+ */
155
+ build(): Partial<T>;
156
+ }
157
+ //# sourceMappingURL=builder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/options/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAOrD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAItC;IAEF,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAE9D;IAED;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAEjE;IAED;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAE9D;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAoBrB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAKhE;IAED;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,EAC3B,GAAG,EAAE,CAAC,EACN,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,EAC1C,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GACpB,IAAI,CAKN;IAED;;;;;;;;OAQG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAS/C;IAED;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAalB;CACF"}
@@ -0,0 +1,215 @@
1
+ "use strict";
2
+ /**
3
+ * Option builder for handling CLI/config/default option precedence.
4
+ *
5
+ * This utility provides a fluent interface for merging options from multiple
6
+ * sources (CLI, config file, defaults) with consistent precedence rules:
7
+ * 1. CLI options (highest priority)
8
+ * 2. Config file options
9
+ * 3. Default values (lowest priority)
10
+ *
11
+ * Precedence is enforced semantically via the setIfProvided() method,
12
+ * regardless of the order in which methods are called. Each value tracks its
13
+ * source, and only higher-precedence sources can override existing values.
14
+ *
15
+ * Eliminates repetitive if/coalesce patterns throughout the codebase.
16
+ *
17
+ * @packageDocumentation
18
+ */
19
+ Object.defineProperty(exports, "__esModule", { value: true });
20
+ exports.OptionBuilder = void 0;
21
+ /**
22
+ * Builder for constructing options from multiple sources with priority precedence.
23
+ *
24
+ * Precedence is enforced semantically via source tracking, not by call order.
25
+ * CLI values always override config values, which always override defaults,
26
+ * regardless of the order in which methods are called.
27
+ *
28
+ * @template T - The type of the options object being built
29
+ *
30
+ * @example
31
+ * ```typescript
32
+ * const options = new OptionBuilder<MyOptions>()
33
+ * // Add in order: default -> config -> cli
34
+ * .addDefault(false, "pretty")
35
+ * .addFromConfig(undefined, "pretty")
36
+ * .addFromCli(true, "pretty") // CLI overrides default
37
+ * .addDefault("/", "baseURL")
38
+ * .addFromConfig("/api", "baseURL") // Config overrides default
39
+ * .addFromCli(undefined, "baseURL")
40
+ * .build();
41
+ * // Result: { pretty: true, baseURL: "/api" }
42
+ * ```
43
+ */
44
+ class OptionBuilder {
45
+ static PRECEDENCE_ORDER = {
46
+ default: 0,
47
+ config: 1,
48
+ cli: 2,
49
+ };
50
+ merged = {};
51
+ sources = new Map();
52
+ /**
53
+ * Adds a default value (lowest priority).
54
+ * Sets a value that can be overwritten by config or CLI options.
55
+ * This method can be called at any time; precedence is enforced semantically.
56
+ *
57
+ * @param value - The default value
58
+ * @param key - The key to store the value under
59
+ * @returns This builder for method chaining
60
+ *
61
+ * @example
62
+ * ```typescript
63
+ * builder.addDefault(3000, "port")
64
+ * ```
65
+ */
66
+ addDefault(value, key) {
67
+ return this.setIfProvided(value, key, "default");
68
+ }
69
+ /**
70
+ * Adds a value from config file if provided (medium priority).
71
+ * Can override default values if the config value exists.
72
+ * This method can be called at any time; precedence is enforced semantically.
73
+ *
74
+ * @param value - The config file option value
75
+ * @param key - The key to store the value under
76
+ * @returns This builder for method chaining
77
+ *
78
+ * @example
79
+ * ```typescript
80
+ * builder.addFromConfig(config.port, "port")
81
+ * ```
82
+ */
83
+ addFromConfig(value, key) {
84
+ return this.setIfProvided(value, key, "config");
85
+ }
86
+ /**
87
+ * Adds a value from CLI options if provided (highest priority).
88
+ * Can override both default and config values for this key.
89
+ * This method can be called at any time; precedence is enforced semantically.
90
+ *
91
+ * @param value - The CLI option value
92
+ * @param key - The key to store the value under
93
+ * @returns This builder for method chaining
94
+ *
95
+ * @example
96
+ * ```typescript
97
+ * builder.addFromCli(cliOpts.port, "port")
98
+ * ```
99
+ */
100
+ addFromCli(value, key) {
101
+ return this.setIfProvided(value, key, "cli");
102
+ }
103
+ /**
104
+ * Sets a value if it's not null or undefined, respecting precedence.
105
+ * Internal helper method used by addDefault, addFromConfig, and addFromCli.
106
+ *
107
+ * Only updates the merged value if the source has equal or higher precedence
108
+ * than the currently stored source. Precedence order: default < config < cli.
109
+ *
110
+ * @param value - The value to set
111
+ * @param key - The key to set
112
+ * @param source - The source of this value ('default', 'config', or 'cli')
113
+ * @returns This builder for method chaining
114
+ */
115
+ setIfProvided(value, key, source) {
116
+ if (value !== null && value !== undefined) {
117
+ const currentSource = this.sources.get(key);
118
+ const shouldUpdate = !currentSource ||
119
+ OptionBuilder.PRECEDENCE_ORDER[source] >=
120
+ OptionBuilder.PRECEDENCE_ORDER[currentSource];
121
+ if (shouldUpdate) {
122
+ this.merged[key] = value;
123
+ this.sources.set(key, source);
124
+ }
125
+ }
126
+ return this;
127
+ }
128
+ /**
129
+ * Transforms a value using a function if the key exists.
130
+ * Useful for processing values after they've been set.
131
+ *
132
+ * @param key - The key to transform
133
+ * @param fn - Function that transforms the current value
134
+ * @returns This builder for method chaining
135
+ *
136
+ * @example
137
+ * ```typescript
138
+ * builder.transform("path", (p) => resolve(p))
139
+ * ```
140
+ */
141
+ transform(key, fn) {
142
+ if (key in this.merged) {
143
+ this.merged[key] = fn(this.merged[key]);
144
+ }
145
+ return this;
146
+ }
147
+ /**
148
+ * Conditionally applies a transformation if a predicate is true.
149
+ * Useful for applying different transformations based on other values.
150
+ *
151
+ * @param key - The key to potentially transform
152
+ * @param predicate - Function that determines if transformation should apply
153
+ * @param fn - Function that transforms the value if predicate is true
154
+ * @returns This builder for method chaining
155
+ *
156
+ * @example
157
+ * ```typescript
158
+ * builder.transformIf("path", () => force, (p) => resolve(p))
159
+ * ```
160
+ */
161
+ transformIf(key, predicate, fn) {
162
+ if (key in this.merged && predicate({ ...this.merged })) {
163
+ this.merged[key] = fn(this.merged[key]);
164
+ }
165
+ return this;
166
+ }
167
+ /**
168
+ * Gets the current value for a key without building.
169
+ * Useful for conditional logic during building.
170
+ * Returns a shallow copy for arrays and objects to prevent external mutations.
171
+ * Note: Nested objects and arrays are not deep copied.
172
+ *
173
+ * @param key - The key to get
174
+ * @returns The current value for the key, or `undefined` if not set
175
+ */
176
+ get(key) {
177
+ const value = this.merged[key];
178
+ if (Array.isArray(value)) {
179
+ return [...value];
180
+ }
181
+ if (value && typeof value === "object") {
182
+ return { ...value };
183
+ }
184
+ return value;
185
+ }
186
+ /**
187
+ * Returns the built options object with all accumulated values.
188
+ * The object contains all keys that were set during the building process.
189
+ *
190
+ * Note: The returned object may be a partial object containing only the keys
191
+ * that were set. Callers should handle potentially missing properties.
192
+ * Returns a defensive copy of the object to prevent external mutations of
193
+ * internal state. Arrays and objects are shallow-copied to protect against
194
+ * external modifications.
195
+ *
196
+ * @returns The constructed options object with type `Partial<T>` (may not have all properties of `T`)
197
+ */
198
+ build() {
199
+ const result = {};
200
+ for (const key in this.merged) {
201
+ const value = this.merged[key];
202
+ if (Array.isArray(value)) {
203
+ result[key] = [...value];
204
+ }
205
+ else if (value && typeof value === "object") {
206
+ result[key] = { ...value };
207
+ }
208
+ else {
209
+ result[key] = value;
210
+ }
211
+ }
212
+ return result;
213
+ }
214
+ }
215
+ exports.OptionBuilder = OptionBuilder;
package/dist/printer.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * This module provides the functionality to load and initialize a printer for GraphQL schema documentation.
5
5
  * It dynamically imports a printer module and configures it with the provided schema and options.
6
6
  */
7
- import type { Maybe, PackageName, Printer, PrinterConfig, PrinterOptions } from "@graphql-markdown/types";
7
+ import type { IPrinter, Maybe, PackageName, PrinterConfig, PrinterOptions } from "@graphql-markdown/types";
8
8
  /**
9
9
  * Loads and initializes a printer module for GraphQL schema documentation.
10
10
  *
@@ -49,4 +49,5 @@ import type { Maybe, PackageName, Printer, PrinterConfig, PrinterOptions } from
49
49
  * const output = printer.printSchema();
50
50
  * ```
51
51
  */
52
- export declare const getPrinter: (printerModule?: Maybe<PackageName>, config?: Maybe<PrinterConfig>, options?: Maybe<PrinterOptions>, mdxModule?: unknown) => Promise<Printer>;
52
+ export declare const getPrinter: (printerModule?: Maybe<PackageName>, config?: Maybe<PrinterConfig>, options?: Maybe<PrinterOptions>, mdxModule?: unknown) => Promise<typeof IPrinter>;
53
+ //# sourceMappingURL=printer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"printer.d.ts","sourceRoot":"","sources":["../src/printer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,KAAK,EACL,WAAW,EAEX,aAAa,EACb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,UAAU,uJA0BtB,CAAC"}
package/dist/printer.js CHANGED
@@ -80,7 +80,7 @@ exports.getPrinter = void 0;
80
80
  */
81
81
  const getPrinter = async (printerModule, config, options, mdxModule) => {
82
82
  if (typeof printerModule !== "string") {
83
- throw new Error("Invalid printer module name.");
83
+ throw new TypeError("Invalid printer module name.");
84
84
  }
85
85
  if (!config) {
86
86
  throw new Error("Invalid printer config.");