import type { ApiType, ApiTypeReference } from "../apiJson.js";

/**
 * Traverse through ApiType text string, turning type references into links.
 *
 * Also hydrates well-known JS "global" keywords (e.g. `string`, `number`), even
 * if they don't appear in ApiType.references.
 *
 * @param apiType - The ApiType to hydrate
 * @param hydratePart - A callback that converts a type reference into desired output
 * @see [Type References](https://devtopia.esri.com/WebGIS/arcgis-web-components/blob/main/packages/support-packages/api-extractor/src/const/typeReferences/README.md)
 * @example
 * ```ts
 * const markdownTypeString = hydrateApiType(
 *   apiProperty.type,
 *   (text, reference) => `[${text}](${reference.viewUrl})`
 * ).join("");
 * ```
 */
export function hydrateApiType<T>(apiType: Pick<ApiType, "references" | "text">, hydratePart: HydrateApiTypeCallback<T>): (T | string)[];

/**
 * @param referenceText - The text of the type reference
 * @param reference - The metadata about the type reference
 */
export type HydrateApiTypeCallback<T> = (referenceText: string, reference: ApiTypeReference & { viewUrl: NonNullable<ApiTypeReference["viewUrl"]>; }) => T;