@hey-api/shared 0.4.7 → 0.5.0

package/dist/index.d.mts

@@ -2,8 +2,8 @@ import { PathLike } from "node:fs";
 import * as semver from "semver";
 import { RangeOptions, SemVer } from "semver";
 import { getResolvedInput } from "@hey-api/json-schema-ref-parser";
-import { IProject, Logger, NameConflictResolver, Node, Project, Ref, RenderContext, StructureLocation, Symbol, SymbolIdentifier, SymbolIn, SymbolMeta } from "@hey-api/codegen-core";
-import { AnyString, MaybeArray, MaybeFunc, MaybePromise } from "@hey-api/types";
+import { IProject, Logger, NameConflictResolver, Node, Project, Ref, RenderContext, StructureLocation, Symbol, SymbolIdentifier, SymbolIn, SymbolMeta, log } from "@hey-api/codegen-core";
+import { AnyObject, AnyString, MaybeArray, MaybeFunc, MaybePromise } from "@hey-api/types";
 import { CodeSampleObject, JSONSchemaDraft2020_12, OpenAPIV2, OpenAPIV3, OpenAPIV3_1, SpecExtensions } from "@hey-api/spec-types";
 
 //#region src/cli.d.ts
@@ -585,6 +585,7 @@ interface IRSchemaObject extends Pick<JSONSchemaDraft2020_12.Document, '$ref' |
    * discriminator for polymorphism.
    */
   discriminator?: {
+    mapping?: Record<string, string>;
     propertyName: string;
   };
   /**
@@ -845,25 +846,15 @@ declare class Context<Spec extends Record<string, any> = any, Config extends Any
    * is a mix of user-provided and default values.
    */
   config: Config;
-  /**
-   * The code generation project instance used to manage files, symbols,
-   */
+  /** The code generation project instance used to manage files, symbols, */
   gen: Project;
-  /**
-   * The dependency graph built from the intermediate representation.
-   */
+  /** The dependency graph built from the intermediate representation. */
   graph: Graph | undefined;
-  /**
-   * Intents declared by plugins.
-   */
+  /** Intents declared by plugins. */
   intents: Array<ExampleIntent>;
-  /**
-   * Intermediate representation model obtained from `spec`.
-   */
+  /** Intermediate representation model obtained from `spec`. */
   ir: IR.Model;
-  /**
-   * Logger instance.
-   */
+  /** Logger instance. */
   logger: Logger;
   /**
    * The package metadata and utilities for the current context, constructed
@@ -878,9 +869,7 @@ declare class Context<Spec extends Record<string, any> = any, Config extends Any
    * their configured name from the config.
    */
   plugins: Partial<Record<PluginNames, PluginInstance<PluginConfigMap[keyof PluginConfigMap]>>>;
-  /**
-   * Resolved specification from `input`.
-   */
+  /** Resolved specification from `input`. */
   spec: Spec;
   constructor({
     config,
@@ -927,6 +916,30 @@ declare class Context<Spec extends Record<string, any> = any, Config extends Any
 declare const irTopLevelKinds: readonly ["operation", "parameter", "requestBody", "schema", "server", "webhook"];
 type IrTopLevelKind = (typeof irTopLevelKinds)[number];
 //#endregion
+//#region src/utils/symbols.d.ts
+interface PluginInstanceTypes {}
+/**
+ * Resolves the Node type, falling back to base Node if not augmented.
+ */
+type ResolvedNode = 'Node' extends keyof PluginInstanceTypes ? PluginInstanceTypes['Node'] : Node;
+type EventHooks = { [K in keyof Required<NonNullable<Hooks['events']>>]: Array<NonNullable<NonNullable<Hooks['events']>[K]>> };
+declare class SymbolFactory {
+  private readonly eventHooks;
+  private readonly project;
+  private readonly plugin?;
+  constructor(props: {
+    eventHooks: EventHooks;
+    plugin?: PluginInstance;
+    project: IProject;
+  });
+  static buildEventHooks(scopes: ReadonlyArray<NonNullable<Hooks['events']> | undefined>): EventHooks;
+  isRegistered(identifier: SymbolIdentifier): boolean;
+  query<TNode extends Node = ResolvedNode>(filter: SymbolMeta, tags?: ReadonlyArray<NonNullable<TNode['~dsl']>>, predicate?: (symbol: Symbol<TNode>) => boolean): Symbol<TNode> | undefined;
+  queryAll<TNode extends Node = ResolvedNode>(filter: SymbolMeta, tags?: ReadonlyArray<NonNullable<TNode['~dsl']>>, predicate?: (symbol: Symbol<TNode>) => boolean): Array<Symbol<TNode>>;
+  reference(meta: SymbolMeta): Symbol<ResolvedNode>;
+  register(name: SymbolIn['name'], symbol?: Omit<SymbolIn, 'name'>): Symbol<ResolvedNode>;
+}
+//#endregion
 //#region src/plugins/shared/types/instance.d.ts
 type BaseEvent = {
   /**
@@ -973,11 +986,6 @@ type WalkEvent<T extends IrTopLevelKind = IrTopLevelKind> = Extract<WalkEvents,
 }>;
 //#endregion
 //#region src/plugins/shared/utils/instance.d.ts
-interface PluginInstanceTypes {}
-/**
- * Resolves the Node type, falling back to base Node if not augmented.
- */
-type ResolvedNode = 'Node' extends keyof PluginInstanceTypes ? PluginInstanceTypes['Node'] : Node;
 declare class PluginInstance<T extends Plugin.Types = Plugin.Types> {
   api: T['api'];
   config: Omit<T['resolvedConfig'], 'name'>;
@@ -986,6 +994,8 @@ declare class PluginInstance<T extends Plugin.Types = Plugin.Types> {
   private eventHooks;
   gen: IProject;
   private handler;
+  /** External symbols imported from other modules. */
+  imports: T['imports'];
   name: T['resolvedConfig']['name'];
   /**
    * The package metadata and utilities for the current context, constructed
@@ -994,15 +1004,19 @@ declare class PluginInstance<T extends Plugin.Types = Plugin.Types> {
    * code generation.
    */
   package: Dependency;
-  /** Symbols declared in the plugin config. */
-  symbols: T['symbols'];
-  constructor(props: Pick<Plugin.Config<T>, 'api' | 'handler' | 'name' | 'symbols'> & {
+  /** Factory for creating and managing symbols. */
+  symbolFactory: SymbolFactory;
+  /** Metadata merged into every symbol this plugin creates. */
+  symbolMeta: Plugin.Config<T>['symbolMeta'];
+  readonly isSymbolRegistered: SymbolFactory['isRegistered'];
+  readonly querySymbol: SymbolFactory['query'];
+  readonly referenceSymbol: SymbolFactory['reference'];
+  constructor(props: Pick<Plugin.Config<T>, 'api' | 'handler' | 'imports' | 'name' | 'symbolMeta'> & {
     config: Omit<T['resolvedConfig'], 'name'>;
     context: Context;
     dependencies: Set<AnyPluginName>;
     gen: IProject;
   });
-  external(resource: Required<SymbolMeta>['resource'], meta?: Omit<SymbolMeta, 'category' | 'resource'>): Symbol;
   /**
    * Iterates over various input elements as specified by the event types, in
    * a specific order: servers, schemas, parameters, request bodies, then
@@ -1059,7 +1073,6 @@ declare class PluginInstance<T extends Plugin.Types = Plugin.Types> {
    * @returns void
    */
   intent(intent: ExampleIntent): void;
-  isSymbolRegistered(identifier: SymbolIdentifier): boolean;
   /**
    * Sets or adds a node to the project graph.
    *
@@ -1068,26 +1081,18 @@ declare class PluginInstance<T extends Plugin.Types = Plugin.Types> {
    * @returns The index of the added node or void if updated.
    */
   node<T extends number | undefined = undefined>(node: Node | null, index?: T): T extends number ? void : number;
-  querySymbol<TNode extends Node = ResolvedNode>(filter: SymbolMeta, tags?: ReadonlyArray<NonNullable<TNode['~dsl']>>, predicate?: (symbol: Symbol<TNode>) => boolean): Symbol<TNode> | undefined;
-  querySymbols<TNode extends Node = ResolvedNode>(filter: SymbolMeta, tags?: ReadonlyArray<NonNullable<TNode['~dsl']>>, predicate?: (symbol: Symbol<TNode>) => boolean): Array<Symbol<TNode>>;
-  referenceSymbol(meta: SymbolMeta): Symbol<ResolvedNode>;
-  /**
-   * Alias for `symbol()` method with single argument.
-   */
-  registerSymbol(symbol: SymbolIn): Symbol<ResolvedNode>;
   /**
    * Executes plugin's handler function.
    */
   run(): Promise<void>;
   symbol(name: SymbolIn['name'], symbol?: Omit<SymbolIn, 'name'>): Symbol<ResolvedNode>;
+  symbol(symbol: SymbolIn): Symbol<ResolvedNode>;
   /**
    * Registers a symbol only if it does not already exist based on the provided
    * name and metadata. This prevents duplicate symbols from being created in
    * the project.
    */
   symbolOnce(name: SymbolIn['name'], symbol?: Omit<SymbolIn, 'name'>): Symbol;
-  private buildEventHooks;
-  private buildSymbols;
   private forEachError;
   private getSymbolExportFromFilePath;
   private getSymbolFilePath;
@@ -1188,7 +1193,7 @@ type Hooks = {
      * @returns void
      */
     'symbol:register:after'?: (args: {
-      /** Plugin that registered the symbol. */plugin: PluginInstance; /** The registered symbol. */
+      /** Plugin that registered the symbol, if available. */plugin?: PluginInstance; /** The registered symbol. */
       symbol: Symbol;
     }) => void;
     /**
@@ -1200,7 +1205,7 @@ type Hooks = {
      * @returns void
      */
     'symbol:register:before'?: (args: {
-      /** Plugin registering the symbol. */plugin: PluginInstance; /** Symbol to register. */
+      /** Plugin registering the symbol, if available. */plugin?: PluginInstance; /** Symbol to register. */
       symbol: SymbolIn;
     }) => void;
   };
@@ -1345,6 +1350,8 @@ interface GetNameContext {
   naming?: NamingConfig;
   /** The operation object associated with the symbol. */
   operation?: IROperationObject;
+  /** Path to the resource this symbol represents. */
+  path?: ReadonlyArray<string | number>;
   /** The schema object associated with the symbol. */
   schema?: IRSchemaObject;
 }
@@ -1353,7 +1360,7 @@ interface GetNameContext {
 interface PluginConfigMap {}
 type PluginNames = keyof PluginConfigMap extends never ? string : keyof PluginConfigMap;
 type AnyPluginName = PluginNames | AnyString;
-type PluginTag = 'client' | 'mocker' | 'sdk' | 'transformer' | 'validator';
+type PluginTag = 'client' | 'handler' | 'sdk' | 'source' | 'transformer' | 'validator';
 type ResolveTagOptions<T extends AnyPluginName = AnyPluginName> = {
   /**
    * Plugin to use if no plugin with the given tag is found in the user's
@@ -1391,17 +1398,18 @@ type PluginContext = {
    */
   resolveTag: <T extends AnyPluginName = AnyPluginName>(tag: PluginTag, options?: ResolveTagOptions<T>) => T | false;
 };
-type PluginSymbols = {
-  [key: string]: Symbol | PluginSymbols;
+/** Map of symbols imported from external modules. */
+type PluginImports = {
+  [key: string]: Symbol | PluginImports;
 };
 type BaseApi = Record<string, unknown>;
 type PluginBaseConfig = UserIndexExportOption & {
+  /** Hooks to override default plugin behavior. */$hooks?: Hooks;
   name: AnyPluginName;
   /**
-   * Optional hooks to override default plugin behavior.
+   * Hooks to override default plugin behavior.
    *
-   * Use these to classify resources, control which outputs are generated,
-   * or provide custom behavior for specific resources.
+   * @deprecated Use `$hooks` instead.
    */
   '~hooks'?: Hooks;
 };
@@ -1416,12 +1424,10 @@ declare namespace Plugin {
     dependencies?: ReadonlyArray<AnyPluginName>;
     handler: (args: {
       plugin: PluginInstance<T>;
-    }) => void;
-    name: T['config']['name'];
-    /**
-     * Symbols this plugin registers at construction time.
-     */
-    symbols?: (plugin: PluginInstance<T>) => T['symbols'];
+    }) => void; /** Declares symbols this plugin imports from external modules. */
+    imports?: (plugin: PluginInstance<T>) => T['imports'];
+    name: T['config']['name']; /** Metadata merged into every symbol this plugin creates. */
+    symbolMeta?: (symbol: Omit<SymbolIn, 'name'>) => SymbolMeta;
     /**
      * Tags can be used to help with deciding plugin order and resolving
      * plugin configuration options.
@@ -1433,23 +1439,32 @@ declare namespace Plugin {
   type Exports = IndexExportOption;
   type UserExports = UserIndexExportOption;
   /** Generic wrapper for plugin hooks. */
-  type Hooks = Pick<PluginBaseConfig, '~hooks'>;
+  type Hooks = Pick<PluginBaseConfig, '$hooks' | '~hooks'>;
   interface Name<Name extends PluginNames> {
     name: Name;
   }
   /**
    * Generic wrapper for plugin resolvers.
    *
-   * Provides a namespaced configuration entry (`~resolvers`)
+   * Provides a namespaced configuration entry (`$resolvers`)
    * where plugins can define how specific schema constructs
    * should be resolved or overridden.
    */
   type Resolvers<T extends Record<string, unknown> = Record<string, unknown>> = {
     /**
-     * Custom behavior resolvers for a plugin.
+     * Custom behavior resolvers.
+     *
+     * Used to define how specific schema constructs are
+     * resolved into AST or runtime logic.
+     */
+    $resolvers?: T;
+    /**
+     * Custom behavior resolvers.
      *
      * Used to define how specific schema constructs are
      * resolved into AST or runtime logic.
+     *
+     * @deprecated Use `$resolvers` instead.
      */
     '~resolvers'?: T;
   };
@@ -1462,27 +1477,42 @@ declare namespace Plugin {
     config: T['resolvedConfig'];
     dependencies: Set<AnyPluginName>;
   };
-  type Types<Config extends PluginBaseConfig = PluginBaseConfig, ResolvedConfig extends PluginBaseConfig = Config, Api extends BaseApi = never, Symbols extends PluginSymbols = Record<never, never>> = ([Api] extends [never] ? {
+  /**
+   * @typeParam Config - User-facing config shape.
+   * @typeParam ResolvedConfig - Fully resolved config shape after normalization.
+   * @typeParam Api - Public API surface exposed by this plugin to other plugins.
+   * @typeParam Imports - Shape of the external symbol imports map.
+   */
+  type Types<Config extends PluginBaseConfig = PluginBaseConfig, ResolvedConfig extends PluginBaseConfig = Config, Api extends BaseApi = never, Imports extends PluginImports = Record<never, never>> = ([Api] extends [never] ? {
     api?: BaseApi;
   } : {
     api: Api;
   }) & {
     config: Config;
+    imports: Imports;
     resolvedConfig: ResolvedConfig;
-    symbols: Symbols;
   };
 }
-type DefinePlugin<Config extends PluginBaseConfig = PluginBaseConfig, ResolvedConfig extends PluginBaseConfig = Config, Api extends BaseApi = never, Symbols extends PluginSymbols = Record<never, never>> = {
-  Config: Plugin.Config<Plugin.Types<Config, ResolvedConfig, Api, Symbols>>;
+/**
+ * Convenience type that derives all plugin-related types from a single
+ * set of type parameters.
+ *
+ * @typeParam Config - User-facing config shape.
+ * @typeParam ResolvedConfig - Fully resolved config shape after normalization.
+ * @typeParam Api - Public API surface exposed by this plugin to other plugins.
+ * @typeParam Imports - Shape of the external symbol imports map.
+ */
+type DefinePlugin<Config extends PluginBaseConfig = PluginBaseConfig, ResolvedConfig extends PluginBaseConfig = Config, Api extends BaseApi = never, Imports extends PluginImports = Record<never, never>> = {
+  Config: Plugin.Config<Plugin.Types<Config, ResolvedConfig, Api, Imports>>;
   Handler: (args: {
-    plugin: PluginInstance<Plugin.Types<Config, ResolvedConfig, Api, Symbols>>;
+    plugin: PluginInstance<Plugin.Types<Config, ResolvedConfig, Api, Imports>>;
   }) => void; /** The plugin instance. */
-  Instance: PluginInstance<Plugin.Types<Config, ResolvedConfig, Api, Symbols>>;
-  Types: Plugin.Types<Config, ResolvedConfig, Api, Symbols>;
+  Instance: PluginInstance<Plugin.Types<Config, ResolvedConfig, Api, Imports>>;
+  Types: Plugin.Types<Config, ResolvedConfig, Api, Imports>;
 };
 //#endregion
 //#region src/config/output/types.d.ts
-type OutputHeader = MaybeFunc<(ctx: Pick<RenderContext, 'meta' | 'project'> & Pick<Partial<RenderContext>, 'file'> & {
+type OutputHeader = MaybeFunc<(ctx: Pick<RenderContext, 'project'> & Pick<Partial<RenderContext>, 'file'> & {
   /** The default header value. */defaultValue: ReadonlyArray<string>;
 }) => MaybeArray<string> | null | undefined>;
 //#endregion
@@ -2141,6 +2171,16 @@ type Parser = {
   validate_EXPERIMENTAL: false | 'strict' | 'warn';
 };
 //#endregion
+//#region src/config/presets.d.ts
+interface PresetPlugin {
+  [key: string]: unknown;
+  name: string;
+}
+interface Preset {
+  /** Plugin configurations contributed by this preset. */
+  plugins?: ReadonlyArray<string | PresetPlugin>;
+}
+//#endregion
 //#region src/config/shared.d.ts
 type FeatureToggle = {
   /**
@@ -2393,6 +2433,8 @@ type BaseUserConfig<TOutput extends BaseUserOutput> = {
   /**
    * Path to the config file. Set this value if you don't use the default
    * config file name, or it's not located in the project root.
+   *
+   * @default undefined
    */
   configFile?: string;
   /**
@@ -2440,8 +2482,16 @@ type BaseUserConfig<TOutput extends BaseUserOutput> = {
   /**
    * Customize how the input is parsed and transformed before it's passed to
    * plugins.
+   *
+   * @default undefined
    */
   parser?: UserParser;
+  /**
+   * Configuration presets.
+   *
+   * @default []
+   */
+  presets?: ReadonlyArray<Preset>;
   /**
    * @deprecated use `input.watch` instead
    */
@@ -2744,27 +2794,27 @@ interface Pagination {
 }
 //#endregion
 //#region src/ir/operation.d.ts
-declare const hasOperationDataRequired: (operation: IR.OperationObject) => boolean;
-declare const createOperationKey: ({
+declare function hasOperationDataRequired(operation: IR.OperationObject): boolean;
+declare function createOperationKey({
   method,
   path
 }: {
   method: string;
   path: string;
-}) => string;
-declare const operationPagination: ({
+}): string;
+declare function operationPagination({
   context,
   operation
 }: {
   context: Context;
   operation: IR.OperationObject;
-}) => Pagination | undefined;
+}): Pagination | undefined;
 type StatusGroup = '1XX' | '2XX' | '3XX' | '4XX' | '5XX' | 'default';
-declare const statusCodeToGroup: ({
+declare function statusCodeToGroup({
   statusCode
 }: {
   statusCode: string;
-}) => StatusGroup;
+}): StatusGroup;
 interface OperationResponsesMap {
   /**
    * A deduplicated union of all error types. Unknown types are omitted.
@@ -2783,18 +2833,18 @@ interface OperationResponsesMap {
    */
   responses?: IR.SchemaObject;
 }
-declare const operationResponsesMap: (operation: IR.OperationObject) => OperationResponsesMap;
+declare function operationResponsesMap(operation: IR.OperationObject): OperationResponsesMap;
 //#endregion
 //#region src/ir/parameter.d.ts
-declare const hasParameterGroupObjectRequired: (parameterGroup?: Record<string, IR.ParameterObject>) => boolean;
-declare const hasParametersObjectRequired: (parameters: IR.ParametersObject | undefined) => boolean;
-declare const parameterWithPagination: ({
+declare function hasParameterGroupObjectRequired(parameterGroup?: Record<string, IR.ParameterObject>): boolean;
+declare function hasParametersObjectRequired(parameters: IR.ParametersObject | undefined): boolean;
+declare function parameterWithPagination({
   context,
   parameters
 }: {
   context: Context;
   parameters: IR.ParametersObject | undefined;
-}) => Pagination | undefined;
+}): Pagination | undefined;
 //#endregion
 //#region src/ir/schema.d.ts
 /**
@@ -3072,6 +3122,49 @@ declare const OperationPath: {
   id: () => OperationPathStrategy;
 };
 //#endregion
+//#region src/openApi/shared/utils/discriminator.d.ts
+/**
+ * Supported types for discriminator properties.
+ */
+type DiscriminatorPropertyType = 'boolean' | 'integer' | 'number' | 'string';
+/**
+ * Converts a string discriminator mapping value to the appropriate type based on
+ * the actual property type in the schema.
+ *
+ * OpenAPI discriminator mappings always use string keys, but the actual discriminator
+ * property may be a boolean, number, or integer. This function converts the string
+ * key to the correct runtime value and IR type.
+ */
+declare function convertDiscriminatorValue(value: string, propertyType: DiscriminatorPropertyType): {
+  const: IR.SchemaObject['const'];
+  type: IR.SchemaObject['type'];
+};
+declare function discriminatorValues($ref: string, mapping?: Record<string, string>, shouldUseRefAsValue?: () => boolean): ReadonlyArray<string>;
+interface DiscriminatedUnionMember {
+  /** The discriminator value for this member. */
+  discriminatedValue: unknown;
+  /**
+   * True when the referenced schema does not already define the discriminator
+   * property as a const/literal. The plugin must inject it explicitly.
+   */
+  needsExtend: boolean;
+  /** The resolved $ref string for this member. */
+  ref: string;
+}
+interface DiscriminatedUnionData {
+  discriminatorKey: string;
+  members: Array<DiscriminatedUnionMember>;
+}
+declare function buildDiscriminatedUnion({
+  parentSchema,
+  resolveIrRef,
+  schemas
+}: {
+  parentSchema: IR.SchemaObject;
+  resolveIrRef: (ref: string) => IR.SchemaObject | undefined;
+  schemas: ReadonlyArray<IR.SchemaObject>;
+}): DiscriminatedUnionData | null;
+//#endregion
 //#region src/openApi/shared/utils/patch.d.ts
 declare function patchOpenApiSpec({
   patchOptions,
@@ -3081,14 +3174,7 @@ declare function patchOpenApiSpec({
   spec: unknown;
 }): Promise<void>;
 //#endregion
-//#region src/plugins/duplicate.d.ts
-type PluginConfig = {
-  name: PluginNames;
-};
-type PluginDefinition<TConfig extends PluginConfig = PluginConfig> = PluginNames | TConfig;
-declare function warnOnConflictingDuplicatePlugins<TConfig extends PluginConfig>(plugins: ReadonlyArray<PluginDefinition<TConfig>>): void;
-//#endregion
-//#region src/plugins/shared/utils/config.d.ts
+//#region src/plugins/config.d.ts
 declare function definePluginConfig<T extends Plugin.Types>(pluginConfig: Plugin.Config<T>): (userConfig?: Omit<T["config"], "name">) => {
   config: Plugin.Config<T>["config"];
   /**
@@ -3103,25 +3189,52 @@ declare function definePluginConfig<T extends Plugin.Types>(pluginConfig: Plugin
   handler: (args: {
     plugin: PluginInstance<T>;
   }) => void;
-  symbols?: ((plugin: PluginInstance<T>) => T["symbols"]) | undefined;
+  imports?: ((plugin: PluginInstance<T>) => T["imports"]) | undefined;
+  symbolMeta?: (symbol: Omit<log, "name">) => log;
   tags?: ReadonlyArray<PluginTag>;
 };
+interface PluginResolutionInput {
+  /** Registry of built-in plugin definitions keyed by name. */
+  defaultPluginConfigs: Partial<Record<string, any>>;
+  /** Plugins to include when the user doesn't specify any. */
+  defaultPlugins: ReadonlyArray<string>;
+  /** Resolved project dependencies. */
+  dependencies: Record<string, string>;
+  /** Raw user configuration (only the `plugins` field is read). */
+  userConfig: {
+    plugins?: ReadonlyArray<string | {
+      name: string;
+    }>;
+    presets?: ReadonlyArray<Preset>;
+  };
+}
+interface PluginResolutionResult<TPluginNames extends string = string> {
+  pluginOrder: ReadonlyArray<TPluginNames>;
+  plugins: Record<string, any>;
+}
+declare function resolvePlugins<TPluginNames extends string = string>({
+  defaultPluginConfigs,
+  defaultPlugins,
+  dependencies,
+  userConfig
+}: PluginResolutionInput): PluginResolutionResult<TPluginNames>;
+//#endregion
+//#region src/plugins/helper.d.ts
+type PluginConfig<K extends keyof PluginConfigMap> = PluginConfigMap[K]['config'] & {
+  name: K;
+};
+type PluginHelper<K extends keyof PluginConfigMap> = (config?: Omit<PluginConfigMap[K]['config'], 'name'>) => PluginConfig<K>;
+declare function pluginHelper<K extends keyof PluginConfigMap>(name: K): PluginHelper<K>;
 //#endregion
 //#region src/plugins/symbol.d.ts
 /**
- * Helper function to build the input for symbol registration, applying naming hooks if provided.
+ * Function to build the input for symbol registration, applying naming hooks if provided.
  */
 declare function buildSymbolIn({
   plugin,
   ...ctx
 }: GetNameContext & {
   plugin: {
-    config: Pick<PluginInstance['config'], '~hooks'>;
-    context: {
-      config: {
-        parser: Pick<PluginInstance['context']['config']['parser'], 'hooks'>;
-      };
-    };
     getHooks: PluginInstance['getHooks'];
   };
 }): SymbolIn;
@@ -3202,6 +3315,11 @@ interface RequestSchemaContext<Plugin extends PluginInstance = PluginInstance> {
   layers?: RequestValidatorLayers;
   /** The operation object. */
   operation: IR.OperationObject;
+  /**
+   * When `true` and every non-omitted layer is optional, wrap the entire
+   * composite schema in an outer optional wrapper.
+   */
+  outerOptional?: boolean;
   /** The plugin instance. */
   plugin: Plugin;
 }
@@ -3316,7 +3434,8 @@ declare class MinHeap {
 }
 //#endregion
 //#region src/utils/object.d.ts
-declare function isPlainObject(value: unknown): value is Record<string, any>;
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function deepMerge<T extends AnyObject | Array<unknown>>(target: T, source: T): T;
 //#endregion
 //#region src/utils/path.d.ts
 interface PathToNameOptions {
@@ -3422,7 +3541,11 @@ interface Url {
   port: string;
   protocol: string;
 }
+/**
+ * Resolve the base URL string if it's a valid URL or path.
+ */
+declare function getBaseUrl(config: string | number | boolean, ir: IR.Model): string | undefined;
 declare function parseUrl(value: string): Url;
 //#endregion
-export { type AnyConfig, type AnyPluginName, type BaseConfig, type BaseOutput, type BaseUserConfig, type BaseUserOutput, COERCER, type Casing, type Coercer, type CoercerMap, type CommentsOption, ConfigError, type ConfigNormalizer, type ConfigTable, ConfigValidationError, Context, type DefaultRequestValidatorLayers, type DefaultValidatorLayers, type DefinePlugin, type Dependency, type FeatureToggle, type Filters, type GetNameContext, HeyApiError, type Hooks, type IR, type IRModel, type IROperationObject, type IRParameterObject, type IRParametersObject, type IRSchemaObject, type IRServerObject, type IndexExportOption, type Input, InputError, IntentContext, JobError, type LogLevel, type Logs, MinHeap, type NameTransformer, type NamingConfig, type NamingOptions, type NamingRule, type OpenApi, type OpenApiMetaObject, type OpenApiOperationObject, type OpenApiParameterObject, type OpenApiRequestBodyObject, type OpenApiResponseObject, type OpenApiSchemaObject, OperationPath, type OperationPathStrategy, OperationStrategy, type OperationStructureStrategy, type OperationsStrategy, type OutputHeader, type Parser, type Patch, type Plugin, type PluginConfigMap, type PluginContext, PluginInstance, type PluginInstanceTypes, type PluginNames, type PluginSymbols, type PluginTag, type PostProcessor, type RequestSchemaContext, type RequestValidatorLayer, type RequestValidatorLayers, type ResolveModuleFn, type ResolvedRequestValidatorLayer, type SchemaExtractor, type SchemaProcessor, type SchemaProcessorContext, type SchemaProcessorResult, type SchemaVisitor, type SchemaVisitorContext, type SchemaWithType, type SourceConfig, type TableDirectives, type UserCommentsOption, type UserIndexExportOption, type UserInput, type UserParser, type UserPostProcessor, type UserSourceConfig, type UserWatch, type ValidatorLayers, type Walker, type Watch, type WatchValues, type WithCoercers, addItemsToSchema, applyNaming, buildGraph, buildSymbolIn, checkNodeVersion, childContext, coerce, collectDeps, compileInputPath, createOperationKey, createSchemaProcessor, createSchemaWalker, debugTools, deduplicateSchema, defaultPaginationKeywords, defineConfig, definePluginConfig, dependencyFactory, encodeJsonPointerSegment, ensureDirSync, escapeComment, findPackageJson, findTsConfigPath, getInput, getInputError, getLogs, getParser, getSpec, hasOperationDataRequired, hasParameterGroupObjectRequired, hasParametersObjectRequired, heyApiRegistryBaseUrl, inputToApiRegistry, isCoercer, isEnvironment, isPlainObject, isTopLevelComponent, jsonPointerToPath, loadPackageJson, logCrashReport, logInputPaths, normalizeJsonPointer, openGitHubIssueWithCrashReport, operationPagination, operationResponsesMap, outputHeaderToPrefix, parameterWithPagination, parseOpenApiSpec, parseUrl, parseV2_0_X, parseV3_0_X, parseV3_1_X, patchOpenApiSpec, pathToJsonPointer, pathToName, postprocessOutput, printCliIntro, printCrashReport, refToName, requestValidatorLayers, resolveNaming, resolveRef, resolveValidatorLayer, satisfies, shouldReportCrash, sourceConfig, statusCodeToGroup, toCase, utils, warnOnConflictingDuplicatePlugins };
+export { type AnyConfig, type AnyPluginName, type BaseConfig, type BaseOutput, type BaseUserConfig, type BaseUserOutput, COERCER, type Casing, type Coercer, type CoercerMap, type CommentsOption, ConfigError, type ConfigNormalizer, type ConfigTable, ConfigValidationError, Context, type DefaultRequestValidatorLayers, type DefaultValidatorLayers, type DefinePlugin, type Dependency, type DiscriminatedUnionData, type DiscriminatedUnionMember, type DiscriminatorPropertyType, type EventHooks, type FeatureToggle, type Filters, type GetNameContext, HeyApiError, type Hooks, type IR, type IRModel, type IROperationObject, type IRParameterObject, type IRParametersObject, type IRSchemaObject, type IRServerObject, type IndexExportOption, type Input, InputError, IntentContext, JobError, type LogLevel, type Logs, MinHeap, type NameTransformer, type NamingConfig, type NamingOptions, type NamingRule, type OpenApi, type OpenApiMetaObject, type OpenApiOperationObject, type OpenApiParameterObject, type OpenApiRequestBodyObject, type OpenApiResponseObject, type OpenApiSchemaObject, OperationPath, type OperationPathStrategy, OperationStrategy, type OperationStructureStrategy, type OperationsStrategy, type OutputHeader, type Parser, type Patch, type Plugin, type PluginConfigMap, type PluginContext, type PluginImports, PluginInstance, type PluginInstanceTypes, type PluginNames, type PluginResolutionInput, type PluginResolutionResult, type PluginTag, type PostProcessor, type Preset, type PresetPlugin, type RequestSchemaContext, type RequestValidatorLayer, type RequestValidatorLayers, type ResolveModuleFn, type ResolvedNode, type ResolvedRequestValidatorLayer, type SchemaExtractor, type SchemaProcessor, type SchemaProcessorContext, type SchemaProcessorResult, type SchemaVisitor, type SchemaVisitorContext, type SchemaWithType, type SourceConfig, SymbolFactory, type TableDirectives, type UserCommentsOption, type UserIndexExportOption, type UserInput, type UserParser, type UserPostProcessor, type UserSourceConfig, type UserWatch, type ValidatorLayers, type Walker, type Watch, type WatchValues, type WithCoercers, addItemsToSchema, applyNaming, buildDiscriminatedUnion, buildGraph, buildSymbolIn, checkNodeVersion, childContext, coerce, collectDeps, compileInputPath, convertDiscriminatorValue, createOperationKey, createSchemaProcessor, createSchemaWalker, debugTools, deduplicateSchema, deepMerge, defaultPaginationKeywords, defineConfig, definePluginConfig, dependencyFactory, discriminatorValues, encodeJsonPointerSegment, ensureDirSync, escapeComment, findPackageJson, findTsConfigPath, getBaseUrl, getInput, getInputError, getLogs, getParser, getSpec, hasOperationDataRequired, hasParameterGroupObjectRequired, hasParametersObjectRequired, heyApiRegistryBaseUrl, inputToApiRegistry, isCoercer, isEnvironment, isPlainObject, isTopLevelComponent, jsonPointerToPath, loadPackageJson, logCrashReport, logInputPaths, normalizeJsonPointer, openGitHubIssueWithCrashReport, operationPagination, operationResponsesMap, outputHeaderToPrefix, parameterWithPagination, parseOpenApiSpec, parseUrl, parseV2_0_X, parseV3_0_X, parseV3_1_X, patchOpenApiSpec, pathToJsonPointer, pathToName, pluginHelper, postprocessOutput, printCliIntro, printCrashReport, refToName, requestValidatorLayers, resolveNaming, resolvePlugins, resolveRef, resolveValidatorLayer, satisfies, shouldReportCrash, sourceConfig, statusCodeToGroup, toCase, utils };
 //# sourceMappingURL=index.d.mts.map