.opencode/node_modules/effect/dist/unstable/cli/Param.d.ts

/**
 * Defines the shared parameter model for CLI arguments and flags.
 *
 * A `Param<Kind, A>` describes how to consume parsed command-line input and
 * return a typed value. The `Kind` decides whether the parameter reads
 * positional arguments or named flags. `Argument` and `Flag` build on this
 * module to share parsing structure, primitive constructors, help metadata,
 * aliases, defaults, prompts, configuration fallbacks, validation, schema
 * decoding, fallback parameters, and traversal helpers.
 *
 * @since 4.0.0
 */
import * as Config from "../../Config.ts";
import * as Effect from "../../Effect.ts";
import type * as FileSystem from "../../FileSystem.ts";
import * as Option from "../../Option.ts";
import type * as Path from "../../Path.ts";
import { type Pipeable } from "../../Pipeable.ts";
import type * as Terminal from "../../Terminal.ts";
import type { Covariant } from "../../Types.ts";
import type { ChildProcessSpawner } from "../process/ChildProcessSpawner.ts";
import * as CliError from "./CliError.ts";
import * as Primitive from "./Primitive.ts";
import * as Prompt from "./Prompt.ts";
declare const TypeId = "~effect/cli/Param";
/**
 * Polymorphic CLI parameter shared by `Argument` and `Flag`.
 *
 * **Details**
 *
 * A parameter knows whether it consumes positional arguments or flags and
 * parses a `ParsedArgs` value into its typed result.
 *
 * @category models
 * @since 4.0.0
 */
export interface Param<Kind extends ParamKind, out A> extends Param.Variance<A> {
    readonly _tag: "Single" | "Map" | "Transform" | "Optional" | "Variadic";
    readonly kind: Kind;
    readonly parse: Parse<A>;
}
/**
 * Discriminator for whether a `Param` parses positional arguments or
 * command-line flags.
 *
 * @category models
 * @since 4.0.0
 */
export type ParamKind = "argument" | "flag";
/**
 * Services that parameter parsing can require, such as filesystem, path,
 * terminal, and child-process support.
 *
 * @category models
 * @since 4.0.0
 */
export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner;
/**
 * Defines the kind discriminator for positional argument parameters.
 *
 * **When to use**
 *
 * Use to build low-level `Param` constructors or type positions for positional
 * argument parameters.
 *
 * @see {@link flagKind} for the named flag parameter discriminator
 * @see {@link ParamKind} for the full parameter kind union
 *
 * @category constants
 * @since 4.0.0
 */
export declare const argumentKind: "argument";
/**
 * Defines the kind discriminator for flag parameters.
 *
 * **When to use**
 *
 * Use to build low-level `Param` constructors or type positions for named flag
 * parameters.
 *
 * @see {@link argumentKind} for the positional argument parameter discriminator
 *
 * @category constants
 * @since 4.0.0
 */
export declare const flagKind: "flag";
/**
 * Represents any parameter.
 *
 * @category models
 * @since 4.0.0
 */
export type Any = Param<ParamKind, unknown>;
/**
 * Represents any positional argument parameter.
 *
 * @category models
 * @since 4.0.0
 */
export type AnyArgument = Param<typeof argumentKind, unknown>;
/**
 * Represents any flag parameter.
 *
 * @category models
 * @since 4.0.0
 */
export type AnyFlag = Param<typeof flagKind, unknown>;
/**
 * Function type used by parameters to parse currently available flags and
 * positional arguments.
 *
 * **Details**
 *
 * It returns the remaining positional arguments together with the parsed value,
 * or fails with a `CliError` while requiring the CLI parsing environment.
 *
 * @category models
 * @since 4.0.0
 */
export type Parse<A> = (args: ParsedArgs) => Effect.Effect<readonly [leftover: ReadonlyArray<string>, value: A], CliError.CliError, Environment>;
/**
 * Namespace containing type-level utilities attached to the `Param` interface.
 *
 * @since 4.0.0
 */
export declare namespace Param {
    /**
     * Variance and pipeability marker carried by every `Param` value.
     *
     * @category models
     * @since 4.0.0
     */
    interface Variance<out A> extends Pipeable {
        readonly [TypeId]: {
            readonly _A: Covariant<A>;
        };
    }
}
/**
 * Map of flag names to their provided string values.
 * Multiple occurrences of a flag produce multiple values.
 *
 * @category models
 * @since 4.0.0
 */
export type Flags = Record<string, ReadonlyArray<string>>;
/**
 * Input context passed to `Param.parse` implementations.
 * - `flags`: already-collected flag values by canonical flag name
 * - `arguments`: remaining positional arguments to be consumed
 *
 * @category models
 * @since 4.0.0
 */
export interface ParsedArgs {
    readonly flags: Flags;
    readonly arguments: ReadonlyArray<string>;
}
/**
 * Represents a fallback prompt that can either be provided directly or
 * computed effectfully when the parameter is missing.
 *
 * @category models
 * @since 4.0.0
 */
export type FallbackPrompt<A> = Prompt.Prompt<A> | Effect.Effect<Prompt.Prompt<A>, CliError.CliError, Environment>;
/**
 * Leaf parameter that reads one named argument or flag with a primitive parser.
 *
 * **Details**
 *
 * Single parameters carry the user-facing name, aliases, description, primitive
 * type, and optional metavar/type name used in help output.
 *
 * @category models
 * @since 4.0.0
 */
export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
    readonly _tag: "Single";
    readonly kind: Kind;
    readonly name: string;
    readonly description: Option.Option<string>;
    readonly aliases: ReadonlyArray<string>;
    readonly primitiveType: Primitive.Primitive<A>;
    readonly typeName?: string | undefined;
    readonly hidden: boolean;
}
/**
 * Parameter node that maps the successfully parsed value of another parameter
 * with a pure function.
 *
 * @category models
 * @since 4.0.0
 */
export interface Map<Kind extends ParamKind, in out A, out B> extends Param<Kind, B> {
    readonly _tag: "Map";
    readonly kind: Kind;
    readonly param: Param<Kind, A>;
    readonly f: (value: A) => B;
}
/**
 * Parameter node that rewrites another parameter's parser, allowing effectful
 * validation, fallback behavior, or error translation while preserving the same
 * parameter kind.
 *
 * @category models
 * @since 4.0.0
 */
export interface Transform<Kind extends ParamKind, in out A, out B> extends Param<Kind, B> {
    readonly _tag: "Transform";
    readonly kind: Kind;
    readonly param: Param<Kind, A>;
    readonly f: (parse: Parse<A>) => Parse<B>;
}
/**
 * Parameter node that turns a missing argument or flag into `Option.none()` and
 * a present parsed value into `Option.some(value)`.
 *
 * @category models
 * @since 4.0.0
 */
export interface Optional<Kind extends ParamKind, A> extends Param<Kind, Option.Option<A>> {
    readonly _tag: "Optional";
    readonly kind: Kind;
    readonly param: Param<Kind, A>;
}
/**
 * Parameter node that parses another parameter zero or more times and returns
 * all parsed values as an array, respecting optional minimum and maximum
 * occurrence bounds.
 *
 * @category models
 * @since 4.0.0
 */
export interface Variadic<Kind extends ParamKind, A> extends Param<Kind, ReadonlyArray<A>> {
    readonly _tag: "Variadic";
    readonly kind: Kind;
    readonly param: Param<Kind, A>;
    readonly min: Option.Option<number>;
    readonly max: Option.Option<number>;
}
/**
 * Constructs a leaf `Single` parameter from its kind, name, primitive parser,
 * and optional help metadata.
 *
 * **Details**
 *
 * The returned parser reads either one positional argument or the named flag,
 * depending on `kind`.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const makeSingle: <const Kind extends ParamKind, A>(params: {
    readonly kind: Kind;
    readonly name: string;
    readonly primitiveType: Primitive.Primitive<A>;
    readonly typeName?: string | undefined;
    readonly description?: Option.Option<string> | undefined;
    readonly aliases?: ReadonlyArray<string> | undefined;
    readonly hidden?: boolean | undefined;
}) => Single<Kind, A>;
/**
 * Makes a flag or positional argument optional.
 *
 * **Details**
 *
 * When the parameter is absent, parsing succeeds with `Option.none()` instead
 * of failing with a missing option or missing argument error. When present, the
 * parsed value is wrapped in `Option.some()`.
 *
 * **Example** (Making parameters optional)
 *
 * ```ts
 * import { Param } from "effect/unstable/cli"
 *
 * // Create an optional port option
 * // - When not provided: returns Option.none()
 * // - When provided: returns Option.some(parsedValue)
 * const port = Param.optional(Param.integer(Param.flagKind, "port"))
 * ```
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const optional: <Kind extends ParamKind, A>(param: Param<Kind, A>) => Param<Kind, Option.Option<A>>;
/**
 * Adds a fallback config that is loaded when a required parameter is missing.
 *
 * **When to use**
 *
 * Use when you need config to provide a fallback source for required flags or
 * arguments that are absent from CLI input.
 *
 * **Details**
 *
 * Provided CLI values win. Config is loaded only after a missing option or
 * missing argument error.
 *
 * **Gotchas**
 *
 * Missing config preserves the original missing-parameter error. Config parse
 * failure becomes `CliError.InvalidValue`.
 *
 * @see {@link withDefault} for a pure default value
 * @see {@link withFallbackPrompt} for prompting interactively when input is missing
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const withFallbackConfig: {
    /**
     * Adds a fallback config that is loaded when a required parameter is missing.
     *
     * **When to use**
     *
     * Use when you need config to provide a fallback source for required flags or
     * arguments that are absent from CLI input.
     *
     * **Details**
     *
     * Provided CLI values win. Config is loaded only after a missing option or
     * missing argument error.
     *
     * **Gotchas**
     *
     * Missing config preserves the original missing-parameter error. Config parse
     * failure becomes `CliError.InvalidValue`.
     *
     * @see {@link withDefault} for a pure default value
     * @see {@link withFallbackPrompt} for prompting interactively when input is missing
     *
     * @category combinators
     * @since 4.0.0
     */
    <B>(config: Config.Config<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>;
    /**
     * Adds a fallback config that is loaded when a required parameter is missing.
     *
     * **When to use**
     *
     * Use when you need config to provide a fallback source for required flags or
     * arguments that are absent from CLI input.
     *
     * **Details**
     *
     * Provided CLI values win. Config is loaded only after a missing option or
     * missing argument error.
     *
     * **Gotchas**
     *
     * Missing config preserves the original missing-parameter error. Config parse
     * failure becomes `CliError.InvalidValue`.
     *
     * @see {@link withDefault} for a pure default value
     * @see {@link withFallbackPrompt} for prompting interactively when input is missing
     *
     * @category combinators
     * @since 4.0.0
     */
    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, config: Config.Config<B>): Param<Kind, A | B>;
};
/**
 * Adds a fallback prompt that is shown when a required parameter is missing.
 *
 * **When to use**
 *
 * Use when a CLI should ask interactively for a missing required flag or
 * argument.
 *
 * **Details**
 *
 * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
 * Effectful prompt creation is lazy and runs only when the fallback is needed.
 *
 * **Gotchas**
 *
 * This only handles missing options and missing arguments. Invalid values do not
 * prompt, and prompt cancellation re-fails with the original missing error.
 *
 * @see {@link FallbackPrompt} for accepted fallback prompt forms
 * @see {@link withFallbackConfig} for loading a fallback from config
 * @see {@link withDefault} for a pure default value
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const withFallbackPrompt: {
    /**
     * Adds a fallback prompt that is shown when a required parameter is missing.
     *
     * **When to use**
     *
     * Use when a CLI should ask interactively for a missing required flag or
     * argument.
     *
     * **Details**
     *
     * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
     * Effectful prompt creation is lazy and runs only when the fallback is needed.
     *
     * **Gotchas**
     *
     * This only handles missing options and missing arguments. Invalid values do not
     * prompt, and prompt cancellation re-fails with the original missing error.
     *
     * @see {@link FallbackPrompt} for accepted fallback prompt forms
     * @see {@link withFallbackConfig} for loading a fallback from config
     * @see {@link withDefault} for a pure default value
     *
     * @category combinators
     * @since 4.0.0
     */
    <B>(prompt: FallbackPrompt<B>): <Kind extends ParamKind, A>(self: Param<Kind, A>) => Param<Kind, A | B>;
    /**
     * Adds a fallback prompt that is shown when a required parameter is missing.
     *
     * **When to use**
     *
     * Use when a CLI should ask interactively for a missing required flag or
     * argument.
     *
     * **Details**
     *
     * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
     * Effectful prompt creation is lazy and runs only when the fallback is needed.
     *
     * **Gotchas**
     *
     * This only handles missing options and missing arguments. Invalid values do not
     * prompt, and prompt cancellation re-fails with the original missing error.
     *
     * @see {@link FallbackPrompt} for accepted fallback prompt forms
     * @see {@link withFallbackConfig} for loading a fallback from config
     * @see {@link withDefault} for a pure default value
     *
     * @category combinators
     * @since 4.0.0
     */
    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, prompt: FallbackPrompt<B>): Param<Kind, A | B>;
};
/**
 * Represent options which can be used to configure variadic parameters.
 *
 * @category options
 * @since 4.0.0
 */
export type VariadicParamOptions = {
    /**
     * The minimum number of times the parameter can be specified.
     */
    readonly min?: number | undefined;
    /**
     * The maximum number of times the parameter can be specified.
     */
    readonly max?: number | undefined;
};
export {};
//# sourceMappingURL=Param.d.ts.map