@hey-api/shared 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -2965,6 +2965,40 @@ declare namespace IR {
   type WebhookObject = IRWebhookObject;
 }
 //#endregion
+//#region src/plugins/schema-processor.d.ts
+interface SchemaProcessor {
+  /** Current inherited context (set by withContext) */
+  readonly context: {
+    readonly anchor: string | undefined;
+    readonly tags: ReadonlyArray<string> | undefined;
+  };
+  /** Check if pointer was already emitted */
+  hasEmitted: (path: ReadonlyArray<string | number>) => boolean;
+  /** Mark pointer as emitted. Returns false if already emitted. */
+  markEmitted: (path: ReadonlyArray<string | number>) => boolean;
+  /** Execute with inherited context for nested extractions */
+  withContext: <T>(ctx: {
+    anchor?: string;
+    tags?: ReadonlyArray<string>;
+  }, fn: () => T) => T;
+}
+interface SchemaProcessorContext {
+  meta: {
+    resource: string;
+    resourceId: string;
+    role?: string;
+  };
+  namingAnchor?: string;
+  path: ReadonlyArray<string | number>;
+  schema: IR.SchemaObject;
+  tags?: ReadonlyArray<string>;
+}
+interface SchemaProcessorResult<Context$1 extends SchemaProcessorContext = SchemaProcessorContext> {
+  process: (ctx: Context$1) => void;
+}
+type SchemaExtractor<Context$1 extends SchemaProcessorContext = SchemaProcessorContext> = (ctx: Context$1) => IR.SchemaObject;
+declare function createSchemaProcessor(): SchemaProcessor;
+//#endregion
 //#region src/openApi/shared/utils/graph.d.ts
 /**
  * Represents the possible access scopes for OpenAPI nodes.
@@ -3224,14 +3258,17 @@ type WalkEvents = BaseEvent & ({
   path: string;
   type: Extract<IrTopLevelKind, 'operation'>;
 } | {
+  /** Name of the parameter (e.g., "id" for a parameter defined as "#/components/parameters/id"). */
   name: string;
   parameter: IR.ParameterObject;
   type: Extract<IrTopLevelKind, 'parameter'>;
 } | {
+  /** Name of the request body (e.g., "CreateUserRequest" for a request body defined as "#/components/requestBodies/CreateUserRequest"). */
   name: string;
   requestBody: IR.RequestBodyObject;
   type: Extract<IrTopLevelKind, 'requestBody'>;
 } | {
+  /** Name of the schema (e.g., "User" for a schema defined as "#/components/schemas/User"). */
   name: string;
   schema: IR.SchemaObject;
   type: Extract<IrTopLevelKind, 'schema'>;
@@ -3360,6 +3397,7 @@ declare class PluginInstance<T extends Plugin.Types = Plugin.Types> {
   symbolOnce(name: SymbolIn['name'], symbol?: Omit<SymbolIn, 'name'>): Symbol;
   private buildEventHooks;
   private forEachError;
+  private getSymbolExportFromFilePath;
   private getSymbolFilePath;
   private isOperationKind;
 }
@@ -3527,6 +3565,28 @@ type Hooks = {
      */
     isQuery?: (operation: IROperationObject) => boolean | undefined;
   };
+  schemas?: {
+    /**
+     * Whether to extract the given schema into a separate symbol.
+     *
+     * This affects how schemas are processed and output.
+     *
+     * **Default behavior:** No schemas are extracted.
+     *
+     * @param ctx - The processing context for the schema.
+     * @returns true to extract the schema, false to keep it inline, or undefined to fallback to default behavior.
+     * @example
+     * ```ts
+     * shouldExtract: (ctx) => {
+     *   if (ctx.meta.resource === 'requestBody') {
+     *     return true;
+     *   }
+     *   return; // fallback to default behavior
+     * }
+     * ```
+     */
+    shouldExtract?: (ctx: SchemaProcessorContext) => boolean;
+  };
   /**
    * Hooks specifically for overriding symbols behavior.
    *
@@ -3536,7 +3596,15 @@ type Hooks = {
     /**
      * Optional output strategy to override default plugin behavior.
      *
-     * Use this to route generated symbols to specific files.
+     * Use this to re-export symbols from specific files.
+     *
+     * @returns The file path(s) that re-export this symbol, or undefined to fallback to default behavior.
+     */
+    getExportFromFilePath?: (symbol: Symbol) => ReadonlyArray<string> | undefined;
+    /**
+     * Optional output strategy to override default plugin behavior.
+     *
+     * Use this to route symbols to specific files.
      *
      * @returns The file path to output the symbol to, or undefined to fallback to default behavior.
      */
@@ -3558,11 +3626,7 @@ type PluginContext = {
   valueToObject: ValueToObject;
 };
 type BaseApi = Record<string, unknown>;
-type BaseConfig$1 = {
-  /**
-   * Whether exports should be re-exported in the index file.
-   */
-  exportFromIndex?: boolean;
+type PluginBaseConfig = UserIndexExportOption & {
   name: AnyPluginName;
   /**
    * Optional hooks to override default plugin behavior.
@@ -3601,10 +3665,14 @@ declare namespace Plugin {
      */
     tags?: ReadonlyArray<PluginTag>;
   };
+  type Comments = CommentsOption;
+  type UserComments = UserCommentsOption;
+  type Exports = IndexExportOption;
+  type UserExports = UserIndexExportOption;
   /**
    * Generic wrapper for plugin hooks.
    */
-  type Hooks = Pick<BaseConfig$1, '~hooks'>;
+  type Hooks = Pick<PluginBaseConfig, '~hooks'>;
   interface Name<Name extends PluginNames> {
     name: Name;
   }
@@ -3624,7 +3692,7 @@ declare namespace Plugin {
      */
     '~resolvers'?: T;
   };
-  type Types<Config extends BaseConfig$1 = BaseConfig$1, ResolvedConfig extends BaseConfig$1 = Config, Api extends BaseApi = never> = ([Api] extends [never] ? {
+  type Types<Config extends PluginBaseConfig = PluginBaseConfig, ResolvedConfig extends PluginBaseConfig = Config, Api extends BaseApi = never> = ([Api] extends [never] ? {
     api?: BaseApi;
   } : {
     api: Api;
@@ -3633,7 +3701,7 @@ declare namespace Plugin {
     resolvedConfig: ResolvedConfig;
   };
 }
-type DefinePlugin<Config extends BaseConfig$1 = BaseConfig$1, ResolvedConfig extends BaseConfig$1 = Config, Api extends BaseApi = never> = {
+type DefinePlugin<Config extends PluginBaseConfig = PluginBaseConfig, ResolvedConfig extends PluginBaseConfig = Config, Api extends BaseApi = never> = {
   Config: Plugin.Config<Plugin.Types<Config, ResolvedConfig, Api>>;
   Handler: (args: {
     plugin: PluginInstance<Plugin.Types<Config, ResolvedConfig, Api>>;
@@ -7200,11 +7268,54 @@ type FeatureToggle = {
    */
   enabled: boolean;
 };
+type UserIndexExportOption = {
+  /**
+   * Whether exports should be re-exported from the entry file.
+   *
+   * - `true` — include all exports
+   * - `false` — exclude all exports
+   * - `(symbol) => boolean` — include exports matching the predicate
+   *
+   * @default false
+   * @deprecated use `includeInEntry` instead
+   */
+  exportFromIndex?: boolean | ((symbol: Symbol) => boolean);
+  /**
+   * Whether exports should be re-exported from the entry file.
+   *
+   * - `true` — include all exports
+   * - `false` — exclude all exports
+   * - `(symbol) => boolean` — include exports matching the predicate
+   *
+   * @default false
+   */
+  includeInEntry?: boolean | ((symbol: Symbol) => boolean);
+};
 type IndexExportOption = {
   /**
-   * Whether exports should be re-exported in the index file.
+   * Whether exports should be re-exported from the entry file.
+   *
+   * @deprecated use `includeInEntry` instead
+   */
+  exportFromIndex: boolean | ((symbol: Symbol) => boolean);
+  /**
+   * Whether exports should be re-exported from the entry file.
+   */
+  includeInEntry: boolean | ((symbol: Symbol) => boolean);
+};
+type UserCommentsOption = {
+  /**
+   * Whether to add comments to the generated code.
+   *
+   * @default true
+   */
+  comments?: boolean;
+};
+type CommentsOption = {
+  /**
+   * Whether to add comments to the generated code.
    */
-  exportFromIndex: boolean;
+  comments: boolean;
 };
 type NamingOptions = {
   /**
@@ -7236,6 +7347,14 @@ interface BaseUserOutput {
    * @default true
    */
   clean?: boolean;
+  /**
+   * Whether to generate an entry file that re-exports symbols for convenient imports.
+   *
+   * Plugins control their inclusion via `includeInEntry`.
+   *
+   * @default true
+   */
+  entryFile?: boolean;
   /**
    * Optional function to transform file names before they are used.
    *
@@ -7274,11 +7393,12 @@ interface BaseUserOutput {
    */
   header?: OutputHeader;
   /**
-   * Should the exports from plugin files be re-exported in the index
-   * barrel file? By default, this is enabled and only default plugins
-   * are re-exported.
+   * Whether to generate an entry file that re-exports symbols for convenient imports.
+   *
+   * Plugins control their inclusion via `includeInEntry`.
    *
    * @default true
+   * @deprecated use `entryFile` instead
    */
   indexFile?: boolean;
   /**
@@ -7323,6 +7443,10 @@ interface BaseOutput {
    * input, or package version changes.
    */
   clean: boolean;
+  /**
+   * Whether to generate an entry file that re-exports symbols for convenient imports.
+   */
+  entryFile: boolean;
   /**
    * Optional function to transform file names before they are used.
    *
@@ -7347,9 +7471,9 @@ interface BaseOutput {
    */
   header: OutputHeader;
   /**
-   * Should the exports from plugin files be re-exported in the index
-   * barrel file? By default, this is enabled and only default plugins
-   * are re-exported.
+   * Whether to generate an entry file that re-exports symbols for convenient imports.
+   *
+   * @deprecated use `entryFile` instead
    */
   indexFile: boolean;
   /**
@@ -7780,6 +7904,23 @@ declare function deduplicateSchema<T extends IR.SchemaObject>({
   schema: T;
 }): T;
 //#endregion
+//#region src/ir/utils.d.ts
+/**
+ * Simply adds `items` to the schema. Also handles setting the logical operator
+ * and avoids setting it for a single item or tuples.
+ */
+declare function addItemsToSchema({
+  items,
+  logicalOperator,
+  mutateSchemaOneItem,
+  schema
+}: {
+  items: Array<IR.SchemaObject>;
+  logicalOperator?: IR.SchemaObject['logicalOperator'];
+  mutateSchemaOneItem?: boolean;
+  schema: IR.SchemaObject;
+}): IR.SchemaObject;
+//#endregion
 //#region src/openApi/index.d.ts
 /**
  * @internal
@@ -8066,6 +8207,32 @@ declare class MinHeap {
   private sinkDown;
 }
 //#endregion
+//#region src/utils/path.d.ts
+interface PathToNameOptions {
+  /**
+   * When provided, replaces the root semantic segments with this anchor.
+   * Structural suffixes are still derived from path.
+   */
+  anchor?: string;
+}
+/**
+ * Derives a composite name from a path.
+ *
+ * Examples:
+ *   .../User                                    → 'User'
+ *   .../User/properties/address                 → 'UserAddress'
+ *   .../User/properties/properties              → 'UserProperties'
+ *   .../User/properties/address/properties/city → 'UserAddressCity'
+ *   .../Pet/additionalProperties                → 'PetValue'
+ *   .../Order/properties/items/items/0          → 'OrderItems'
+ *   paths//event/get/properties/query           → 'EventGetQuery'
+ *
+ * With anchor:
+ *   paths//event/get/properties/query, { anchor: 'event.subscribe' }
+ *                                               → 'event.subscribe-Query'
+ */
+declare function pathToName(path: ReadonlyArray<string | number>, options?: PathToNameOptions): string;
+//#endregion
 //#region src/utils/ref.d.ts
 /**
  * Returns the reusable component name from `$ref`.
@@ -8116,7 +8283,7 @@ declare function normalizeJsonPointer(pointer: string): string;
  */
 declare function pathToJsonPointer(path: ReadonlyArray<string | number>): string;
 /**
- * Checks if a $ref points to a top-level component (not a deep path reference).
+ * Checks if a $ref or path points to a top-level component (not a deep path reference).
  *
  * Top-level component references:
  * - OpenAPI 3.x: #/components/{type}/{name} (3 segments)
@@ -8125,10 +8292,10 @@ declare function pathToJsonPointer(path: ReadonlyArray<string | number>): string
  * Deep path references (4+ segments for 3.x, 3+ for 2.0) should be inlined
  * because they don't have corresponding registered symbols.
  *
- * @param $ref - The $ref string to check
+ * @param refOrPath - The $ref string or path array to check
  * @returns true if the ref points to a top-level component, false otherwise
  */
-declare function isTopLevelComponentRef($ref: string): boolean;
+declare function isTopLevelComponent(refOrPath: string | ReadonlyArray<string | number>): boolean;
 declare function resolveRef<T>({
   $ref,
   spec
@@ -8146,5 +8313,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, 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 SchemaWithType, type SourceConfig, type UserInput, type UserParser, type UserPostProcessor, type UserSourceConfig, type UserWatch, type ValueToObject, type Watch, type WatchValues, applyNaming, buildGraph, checkNodeVersion, compileInputPath, createOperationKey, debugTools, deduplicateSchema, defaultPaginationKeywords, definePluginConfig, dependencyFactory, encodeJsonPointerSegment, ensureDirSync, escapeComment, findPackageJson, findTsConfigPath, getInput, getLogs, getParser, getSpec, hasOperationDataRequired, hasParameterGroupObjectRequired, hasParametersObjectRequired, heyApiRegistryBaseUrl, inputToApiRegistry, isTopLevelComponentRef, jsonPointerToPath, loadPackageJson, loadTsConfig, logCrashReport, logInputPaths, mappers, normalizeJsonPointer, openGitHubIssueWithCrashReport, operationPagination, operationResponsesMap, parameterWithPagination, parseOpenApiSpec, parseUrl, parseV2_0_X, parseV3_0_X, parseV3_1_X, patchOpenApiSpec, pathToJsonPointer, 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 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 };
 //# sourceMappingURL=index.d.mts.map