import { ValueParser, ValueParserResult } from "./valueparser.js";
import { Mode, Suggestion } from "./internal/parser.js";

//#region src/dependency-metadata.d.ts

/**
 * Metadata for a parser that is a dependency source.
 *
 * @internal
 * @since 1.0.0
 */
interface DependencySourceCapability {
  /** Discriminant tag. */
  readonly kind: "source";
  /** The unique dependency source identifier. */
  readonly sourceId: symbol;
  /**
   * Extracts the dependency source parse result from the parser's state.
   *
   * The `state` argument is the current parser state for the source-owning
   * parser.  Each wrapper composes this method to handle its own state shape:
   * - plain source: reads from `DependencySourceState`
   * - `optional()`/`withDefault()`: unwraps `[innerState]` first
   * - `map()`: reads the pre-transform value from inner state
   *
   * Returns the `ValueParserResult` (which may be successful with any
   * value including `undefined`, or failed), a promise that resolves to the
   * same shape when extraction needs async work, or `undefined` if the state
   * does not contain a source result at all (unpopulated/wrong shape).
   * Callers and wrapper authors must handle both direct and promise-wrapped
   * results when composing `extractSourceValue`.
   */
  readonly extractSourceValue: (state: unknown) => ValueParserResult<unknown> | Promise<ValueParserResult<unknown> | undefined> | undefined;
  /**
   * When present, provides a missing-source value (e.g., from a
   * `withDefault()` wrapper).  Called during the `fillMissingSourceDefaults`
   * phase of the dependency runtime.
   */
  readonly getMissingSourceValue?: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
  /**
   * Whether the parser's output value is the actual dependency source value.
   * `false` when a transform like `map()` has been applied.
   */
  readonly preservesSourceValue: boolean;
}
/**
 * Metadata for a parser that depends on one or more dependency sources.
 *
 * @internal
 * @since 1.0.0
 */
interface DerivedDependencyCapability {
  /** Discriminant tag. */
  readonly kind: "derived";
  /** The dependency source IDs this parser depends on. */
  readonly dependencyIds: readonly symbol[];
  /**
   * Returns default values for each dependency, used when the
   * corresponding sources are not provided.
   */
  readonly getDefaultDependencyValues?: () => readonly unknown[];
  /**
   * Replays a parse with the given raw input and resolved dependency values.
   */
  readonly replayParse: (rawInput: string, dependencyValues: readonly unknown[]) => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
  /**
   * Replays suggestions with the given prefix and resolved dependency values.
   */
  readonly replaySuggest?: (prefix: string, dependencyValues: readonly unknown[]) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
}
/**
 * Metadata indicating that a wrapper transforms the dependency source value.
 *
 * @internal
 * @since 1.0.0
 */
interface DependencyTransformCapability {
  /** Whether the wrapper transforms the source value. */
  readonly transformsSourceValue: boolean;
}
/**
 * Composed dependency metadata for a parser node.
 *
 * A parser may have any combination of source, derived, and transform
 * capabilities.  In practice, a parser is typically either a source or
 * derived, never both.
 *
 * @internal
 * @since 1.0.0
 */
interface ParserDependencyMetadata {
  /** Present if the parser is (or wraps) a dependency source. */
  readonly source?: DependencySourceCapability;
  /** Present if the parser depends on one or more sources. */
  readonly derived?: DerivedDependencyCapability;
  /** Present if a transform has been applied. */
  readonly transform?: DependencyTransformCapability;
}
/**
 * Extracts {@link ParserDependencyMetadata} from a value parser by reading
 * old-protocol markers (`dependencySourceMarker`, `derivedValueParserMarker`,
 * etc.).
 *
 * Returns `undefined` if the parser has no dependency-related markers.
 *
 * @param valueParser The value parser to inspect.
 * @returns Metadata, or `undefined` for plain parsers.
 * @internal
 * @since 1.0.0
 */
declare function extractDependencyMetadata<M extends Mode, T>(valueParser: ValueParser<M, T>): ParserDependencyMetadata | undefined;
/**
 * Options for `composeDependencyMetadata` when the wrapper kind is
 * `"withDefault"`.
 *
 * @internal
 * @since 1.0.0
 */
interface WithDefaultCompositionOptions {
  /** Thunk returning the default value as a `ValueParserResult`. */
  readonly defaultValue: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
}
/**
 * Composes dependency metadata through a modifier wrapper.
 *
 * - `"optional"`: composes `extractSourceValue` with array unwrapping.
 * - `"withDefault"`: adds `getMissingSourceValue` if the inner parser
 *   preserves a dependency source.
 * - `"map"`: sets `transformsSourceValue` and clears
 *   `preservesSourceValue`.
 *
 * Returns `undefined` if `inner` is `undefined`.
 *
 * @param inner The inner parser's metadata.
 * @param wrapperKind The type of modifier being applied.
 * @param options Additional options for certain wrapper kinds.
 * @returns Composed metadata, or `undefined`.
 * @internal
 * @since 1.0.0
 */
declare function composeDependencyMetadata(inner: ParserDependencyMetadata | undefined, wrapperKind: "optional" | "withDefault" | "map", options?: WithDefaultCompositionOptions): ParserDependencyMetadata | undefined;
//#endregion
export { DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };