@hey-api/shared 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -3,8 +3,8 @@ import ts from "typescript";
 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, RenderContext, StructureLocation, Symbol, SymbolIdentifier, SymbolIn, SymbolMeta } from "@hey-api/codegen-core";
 
 //#region src/cli.d.ts
 declare function printCliIntro(initialDir: string, showLogo?: boolean): void;
@@ -2965,7 +2965,7 @@ declare namespace IR {
   type WebhookObject = IRWebhookObject;
 }
 //#endregion
-//#region src/plugins/schema-processor.d.ts
+//#region src/ir/schema-processor.d.ts
 interface SchemaProcessor {
   /** Current inherited context (set by withContext) */
   readonly context: {
@@ -3706,6 +3706,7 @@ type DefinePlugin<Config extends PluginBaseConfig = PluginBaseConfig, ResolvedCo
   Handler: (args: {
     plugin: PluginInstance<Plugin.Types<Config, ResolvedConfig, Api>>;
   }) => void;
+  /** The plugin instance. */
   Instance: PluginInstance<Plugin.Types<Config, ResolvedConfig, Api>>;
   Types: Plugin.Types<Config, ResolvedConfig, Api>;
 };
@@ -3748,7 +3749,7 @@ interface NamingConfig {
 type NamingRule = NameTransformer | NamingConfig;
 //#endregion
 //#region src/config/output/types.d.ts
-type OutputHeader = MaybeFunc<(ctx: RenderContext) => MaybeArray<string> | null | undefined>;
+type OutputHeader = MaybeFunc<(ctx: Omit<RenderContext, 'file'> & Pick<Partial<RenderContext>, 'file'>) => MaybeArray<string> | null | undefined>;
 //#endregion
 //#region src/config/parser/filters.d.ts
 type Filters = {
@@ -6890,7 +6891,42 @@ declare namespace OpenApiSchemaObject {
 }
 //#endregion
 //#region src/config/parser/patch.d.ts
-type Patch = {
+type PatchInputFn = (spec: OpenApi.V2_0_X | OpenApi.V3_0_X | OpenApi.V3_1_X) => void | Promise<void>;
+type Patch = PatchInputFn | {
+  /**
+   * Patch the raw OpenAPI spec object in place. Called before all other
+   * patch callbacks. Useful for bulk/structural transformations such as
+   * adding new component definitions or modifying many operations at once.
+   *
+   * @param spec The OpenAPI spec object for the current version.
+   *
+   * @example
+   * ```ts
+   * input: (spec) => {
+   *   // Create new component parameters
+   *   if (!spec.components) spec.components = {};
+   *   if (!spec.components.parameters) spec.components.parameters = {};
+   *   spec.components.parameters.MyParam = {
+   *     in: 'query',
+   *     name: 'myParam',
+   *     schema: { type: 'string' }
+   *   };
+   *
+   *   // Inject parameters into operations
+   *   for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+   *     if (pathItem?.get) {
+   *       if (!Array.isArray(pathItem.get.parameters)) {
+   *         pathItem.get.parameters = [];
+   *       }
+   *       pathItem.get.parameters.push({
+   *         $ref: '#/components/parameters/MyParam'
+   *       });
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  input?: PatchInputFn;
   /**
    * Patch the OpenAPI meta object in place. Useful for modifying general metadata such as title, description, version, or custom fields before further processing.
    *
@@ -6898,16 +6934,51 @@ type Patch = {
    */
   meta?: (meta: OpenApiMetaObject.V2_0_X | OpenApiMetaObject.V3_0_X | OpenApiMetaObject.V3_1_X) => void;
   /**
-   * Patch OpenAPI operations in place. The key is the operation method and operation path, and the function receives the operation object to modify directly.
+   * Patch OpenAPI operations in place. Each function receives the operation
+   * object to be modified in place. Common use cases include injecting
+   * `operationId` for specs that don't have them, adding `x-*` extensions,
+   * setting `deprecated` based on path patterns, or injecting `security`
+   * requirements globally.
+   *
+   * Can be:
+   * - `Record<string, fn>`: Patch specific operations by `"METHOD /path"` key
+   * - `function`: Bulk callback receives `(method, path, operation)` for every operation
+   *
+   * Both patterns support async functions for operations like fetching data
+   * from external sources or performing I/O.
    *
    * @example
+   * ```js
+   * // Named operations
    * operations: {
    *   'GET /foo': (operation) => {
-   *     operation.responses['200'].description = 'foo';
+   *     operation.responses['200'].description = 'Success';
+   *   },
+   *   'POST /bar': (operation) => {
+   *     operation.deprecated = true;
+   *   }
+   * }
+   *
+   * // Bulk callback for all operations
+   * operations: (method, path, operation) => {
+   *   if (!operation.operationId) {
+   *     operation.operationId = method + buildOperationName(path);
    *   }
    * }
+   *
+   * // Async example - inject operationId based on path patterns
+   * operations: async (method, path, operation) => {
+   *   if (operation.operationId) return;
+   *
+   *   const segments = path.split('/').filter(Boolean);
+   *   const parts = segments
+   *     .map((seg) => seg.startsWith('{') ? 'ById' : seg)
+   *     .join('');
+   *   operation.operationId = method + parts;
+   * }
+   * ```
    */
-  operations?: Record<string, (operation: OpenApiOperationObject.V2_0_X | OpenApiOperationObject.V3_0_X | OpenApiOperationObject.V3_1_X) => void>;
+  operations?: Record<string, (operation: OpenApiOperationObject.V2_0_X | OpenApiOperationObject.V3_0_X | OpenApiOperationObject.V3_1_X) => void | Promise<void>> | ((method: string, path: string, operation: OpenApiOperationObject.V2_0_X | OpenApiOperationObject.V3_0_X | OpenApiOperationObject.V3_1_X) => void | Promise<void>);
   /**
    * Patch OpenAPI parameters in place. The key is the parameter name, and the function receives the parameter object to modify directly.
    *
@@ -6946,8 +7017,16 @@ type Patch = {
    * use cases include fixing incorrect data types, removing unwanted
    * properties, adding missing fields, or standardizing date/time formats.
    *
+   * Can be:
+   * - `Record<string, fn>`: Patch specific named schemas
+   * - `function`: Bulk callback receives `(name, schema)` for every schema
+   *
+   * Both patterns support async functions for operations like fetching data
+   * from external sources or performing I/O.
+   *
    * @example
    * ```js
+   * // Named schemas
    * schemas: {
    *   Foo: (schema) => {
    *     // convert date-time format to timestamp
@@ -6967,9 +7046,26 @@ type Patch = {
    *     delete schema.properties.internalField;
    *   }
    * }
+   *
+   * // Bulk callback for all schemas
+   * schemas: (name, schema) => {
+   *   const match = name.match(/_v(\d+)_(\d+)_(\d+)_/);
+   *   if (match) {
+   *     schema.description = (schema.description || '') +
+   *       `\n@version ${match[1]}.${match[2]}.${match[3]}`;
+   *   }
+   * }
+   *
+   * // Async example - fetch metadata from external source
+   * schemas: async (name, schema) => {
+   *   const metadata = await fetchSchemaMetadata(name);
+   *   if (metadata) {
+   *     schema.description = `${schema.description}\n\n${metadata.notes}`;
+   *   }
+   * }
    * ```
    */
-  schemas?: Record<string, (schema: OpenApiSchemaObject.V2_0_X | OpenApiSchemaObject.V3_0_X | OpenApiSchemaObject.V3_1_X) => void>;
+  schemas?: Record<string, (schema: OpenApiSchemaObject.V2_0_X | OpenApiSchemaObject.V3_0_X | OpenApiSchemaObject.V3_1_X) => void | Promise<void>> | ((name: string, schema: OpenApiSchemaObject.V2_0_X | OpenApiSchemaObject.V3_0_X | OpenApiSchemaObject.V3_1_X) => void | Promise<void>);
   /**
    * Patch the OpenAPI version string. The function receives the current version and should return the new version string.
    * Useful for normalizing or overriding the version value before further processing.
@@ -7145,6 +7241,21 @@ type UserParser = {
         name?: NameTransformer;
       };
     };
+    /**
+     * Sometimes your schema names are auto-generated or follow a naming convention
+     * that produces verbose or awkward type names. You can rename schema component
+     * keys throughout the specification, automatically updating all `$ref` pointers.
+     *
+     * @example
+     * ```ts
+     * {
+     *   schemaName: (name) => name.replace(/_v\d+_\d+_\d+_/, '_')
+     * }
+     * ```
+     *
+     * @default undefined
+     */
+    schemaName?: NameTransformer;
   };
   /**
    * **This is an experimental feature.**
@@ -7248,6 +7359,13 @@ type Parser = {
        */
       responses: NamingOptions;
     };
+    /**
+     * Rename schema component keys and automatically update all `$ref` pointers
+     * throughout the specification.
+     *
+     * @default undefined
+     */
+    schemaName?: NameTransformer;
   };
   /**
    * **This is an experimental feature.**
@@ -7904,6 +8022,88 @@ declare function deduplicateSchema<T extends IR.SchemaObject>({
   schema: T;
 }): T;
 //#endregion
+//#region src/plugins/shared/types/schema.d.ts
+type SchemaWithType<T extends Required<IR.SchemaObject>['type'] = Required<IR.SchemaObject>['type']> = Omit<IR.SchemaObject, 'type'> & {
+  type: Extract<Required<IR.SchemaObject>['type'], T>;
+};
+//#endregion
+//#region src/ir/schema-walker.d.ts
+/**
+ * Context passed to all visitor methods.
+ */
+interface SchemaVisitorContext<TPlugin = unknown> {
+  /** Current path in the schema tree. */
+  path: Ref<ReadonlyArray<string | number>>;
+  /** The plugin instance. */
+  plugin: TPlugin;
+}
+/**
+ * The walk function signature. Fully generic over TResult.
+ */
+type Walker<TResult, TPlugin = unknown> = (schema: IR.SchemaObject, ctx: SchemaVisitorContext<TPlugin>) => TResult;
+/**
+ * The visitor interface. Plugins define their own TResult type.
+ *
+ * The walker handles orchestration (dispatch, deduplication, path tracking).
+ * Result shape and semantics are entirely plugin-defined.
+ */
+interface SchemaVisitor<TResult, TPlugin = unknown> {
+  /**
+   * Apply modifiers to a result.
+   */
+  applyModifiers(result: TResult, ctx: SchemaVisitorContext<TPlugin>, context?: {
+    /** Is this property optional? */
+    optional?: boolean;
+  }): unknown;
+  array(schema: SchemaWithType<'array'>, ctx: SchemaVisitorContext<TPlugin>, walk: Walker<TResult, TPlugin>): TResult;
+  boolean(schema: SchemaWithType<'boolean'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  enum(schema: SchemaWithType<'enum'>, ctx: SchemaVisitorContext<TPlugin>, walk: Walker<TResult, TPlugin>): TResult;
+  integer(schema: SchemaWithType<'integer'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  /**
+   * Called before any dispatch logic. Return a result to short-circuit,
+   * or undefined to continue normal dispatch.
+   */
+  intercept?(schema: IR.SchemaObject, ctx: SchemaVisitorContext<TPlugin>, walk: Walker<TResult, TPlugin>): TResult | undefined;
+  /**
+   * Handle intersection types. Receives already-walked child results.
+   */
+  intersection(items: Array<TResult>, schemas: ReadonlyArray<IR.SchemaObject>, parentSchema: IR.SchemaObject, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  never(schema: SchemaWithType<'never'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  null(schema: SchemaWithType<'null'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  number(schema: SchemaWithType<'number'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  object(schema: SchemaWithType<'object'>, ctx: SchemaVisitorContext<TPlugin>, walk: Walker<TResult, TPlugin>): TResult;
+  /**
+   * Called after each typed schema visitor returns.
+   */
+  postProcess?(result: TResult, schema: IR.SchemaObject, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  /**
+   * Handle $ref to another schema.
+   */
+  reference($ref: string, schema: IR.SchemaObject, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  string(schema: SchemaWithType<'string'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  tuple(schema: SchemaWithType<'tuple'>, ctx: SchemaVisitorContext<TPlugin>, walk: Walker<TResult, TPlugin>): TResult;
+  undefined(schema: SchemaWithType<'undefined'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  /**
+   * Handle union types. Receives already-walked child results.
+   */
+  union(items: Array<TResult>, schemas: ReadonlyArray<IR.SchemaObject>, parentSchema: IR.SchemaObject, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  unknown(schema: SchemaWithType<'unknown'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+  void(schema: SchemaWithType<'void'>, ctx: SchemaVisitorContext<TPlugin>): TResult;
+}
+/**
+ * Create a schema walker from a visitor.
+ *
+ * The walker handles:
+ * - Dispatch order ($ref → type → items → fallback)
+ * - Deduplication of union/intersection schemas
+ * - Path tracking for child schemas
+ */
+declare function createSchemaWalker<TResult, TPlugin = unknown>(visitor: SchemaVisitor<TResult, TPlugin>): Walker<TResult, TPlugin>;
+/**
+ * Helper to create a child context with an extended path.
+ */
+declare function childContext<TPlugin>(ctx: SchemaVisitorContext<TPlugin>, ...segments: ReadonlyArray<string | number>): SchemaVisitorContext<TPlugin>;
+//#endregion
 //#region src/ir/utils.d.ts
 /**
  * Simply adds `items` to the schema. Also handles setting the logical operator
@@ -8085,12 +8285,7 @@ declare function patchOpenApiSpec({
 }: {
   patchOptions: Patch | undefined;
   spec: unknown;
-}): void;
-//#endregion
-//#region src/plugins/shared/types/schema.d.ts
-type SchemaWithType<T extends Required<IR.SchemaObject>['type'] = Required<IR.SchemaObject>['type']> = Omit<IR.SchemaObject, 'type'> & {
-  type: Extract<Required<IR.SchemaObject>['type'], T>;
-};
+}): Promise<void>;
 //#endregion
 //#region src/plugins/shared/utils/config.d.ts
 declare const definePluginConfig: <T extends Plugin.Types>(defaultConfig: Plugin.Config<T>) => (userConfig?: Omit<T["config"], "name">) => Omit<Plugin.Config<T>, "name"> & {
@@ -8187,6 +8382,12 @@ declare const utils: {
   toCase: typeof toCase;
 };
 //#endregion
+//#region src/utils/header.d.ts
+/**
+ * Converts an {@link OutputHeader} value to a string prefix for file content.
+ */
+declare function outputHeaderToPrefix(header: OutputHeader, project: IProject): string;
+//#endregion
 //#region src/utils/input/index.d.ts
 declare function inputToApiRegistry(input: Input & {
   path: string;
@@ -8313,5 +8514,5 @@ interface Url {
 }
 declare function parseUrl(value: string): Url;
 //#endregion
-export { type AnyConfig, type AnyPluginName, type BaseConfig, type BaseOutput, type BaseUserConfig, type BaseUserOutput, type Casing, type CodeSampleObject, type CommentsOption, ConfigError, ConfigValidationError, Context, type DefinePlugin, type Dependency, type EnumExtensions, type FeatureToggle, type Filters, HeyApiError, type Hooks, type IR, type IndexExportOption, type Input, IntentContext, JobError, type LinguistLanguages, 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, type OpenApiV2_0_X, type OpenApiV2_0_XTypes, type OpenApiV3_0_X, type OpenApiV3_0_XTypes, type OpenApiV3_1_X, type OpenApiV3_1_XTypes, 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 PostProcessor, type SchemaExtractor, type SchemaProcessor, type SchemaProcessorContext, type SchemaProcessorResult, type SchemaWithType, type SourceConfig, type UserCommentsOption, type UserIndexExportOption, type UserInput, type UserParser, type UserPostProcessor, type UserSourceConfig, type UserWatch, type ValueToObject, type Watch, type WatchValues, addItemsToSchema, applyNaming, buildGraph, checkNodeVersion, compileInputPath, createOperationKey, createSchemaProcessor, debugTools, deduplicateSchema, defaultPaginationKeywords, definePluginConfig, dependencyFactory, encodeJsonPointerSegment, ensureDirSync, escapeComment, findPackageJson, findTsConfigPath, getInput, getLogs, getParser, getSpec, hasOperationDataRequired, hasParameterGroupObjectRequired, hasParametersObjectRequired, heyApiRegistryBaseUrl, inputToApiRegistry, isTopLevelComponent, jsonPointerToPath, loadPackageJson, loadTsConfig, logCrashReport, logInputPaths, mappers, normalizeJsonPointer, openGitHubIssueWithCrashReport, operationPagination, operationResponsesMap, parameterWithPagination, parseOpenApiSpec, parseUrl, parseV2_0_X, parseV3_0_X, parseV3_1_X, patchOpenApiSpec, pathToJsonPointer, pathToName, postprocessOutput, printCliIntro, printCrashReport, refToName, resolveNaming, resolveRef, resolveSource, satisfies, shouldReportCrash, statusCodeToGroup, toCase, utils, valueToObject };
+export { type AnyConfig, type AnyPluginName, type BaseConfig, type BaseOutput, type BaseUserConfig, type BaseUserOutput, type Casing, type CodeSampleObject, type CommentsOption, ConfigError, ConfigValidationError, Context, type DefinePlugin, type Dependency, type EnumExtensions, type FeatureToggle, type Filters, HeyApiError, type Hooks, type IR, type IndexExportOption, type Input, IntentContext, JobError, type LinguistLanguages, 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, type OpenApiV2_0_X, type OpenApiV2_0_XTypes, type OpenApiV3_0_X, type OpenApiV3_0_XTypes, type OpenApiV3_1_X, type OpenApiV3_1_XTypes, 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 PostProcessor, type SchemaExtractor, type SchemaProcessor, type SchemaProcessorContext, type SchemaProcessorResult, type SchemaVisitor, type SchemaVisitorContext, type SchemaWithType, type SourceConfig, type UserCommentsOption, type UserIndexExportOption, type UserInput, type UserParser, type UserPostProcessor, type UserSourceConfig, type UserWatch, type ValueToObject, type Walker, type Watch, type WatchValues, addItemsToSchema, applyNaming, buildGraph, checkNodeVersion, childContext, compileInputPath, createOperationKey, createSchemaProcessor, createSchemaWalker, debugTools, deduplicateSchema, defaultPaginationKeywords, definePluginConfig, dependencyFactory, encodeJsonPointerSegment, ensureDirSync, escapeComment, findPackageJson, findTsConfigPath, getInput, getLogs, getParser, getSpec, hasOperationDataRequired, hasParameterGroupObjectRequired, hasParametersObjectRequired, heyApiRegistryBaseUrl, inputToApiRegistry, isTopLevelComponent, jsonPointerToPath, loadPackageJson, loadTsConfig, logCrashReport, logInputPaths, mappers, normalizeJsonPointer, openGitHubIssueWithCrashReport, operationPagination, operationResponsesMap, outputHeaderToPrefix, parameterWithPagination, parseOpenApiSpec, parseUrl, parseV2_0_X, parseV3_0_X, parseV3_1_X, patchOpenApiSpec, pathToJsonPointer, pathToName, postprocessOutput, printCliIntro, printCrashReport, refToName, resolveNaming, resolveRef, resolveSource, satisfies, shouldReportCrash, statusCodeToGroup, toCase, utils, valueToObject };
 //# sourceMappingURL=index.d.mts.map