EdgeAIG's picture
download
raw
27 kB
import * as Data from "../../Data.ts";
import * as Effect from "../../Effect.ts";
import * as FileSystem from "../../FileSystem.ts";
import * as Path from "../../Path.ts";
import * as Queue from "../../Queue.ts";
import * as Redacted from "../../Redacted.ts";
import * as Terminal from "../../Terminal.ts";
import type { Covariant } from "../../Types.ts";
import type * as Primitive from "./Primitive.ts";
declare const TypeId = "~effect/cli/Prompt";
/**
* Represents an interactive terminal prompt that produces an `Output` value.
*
* **Details**
*
* A `Prompt` is an `Effect` that may fail with `Terminal.QuitError` and
* requires the prompt environment needed to render frames, read input, and
* access files or paths when a prompt uses them.
*
* @category models
* @since 4.0.0
*/
export interface Prompt<Output> extends Effect.Effect<Output, Terminal.QuitError, Environment> {
readonly [TypeId]: {
readonly _Output: Covariant<Output>;
};
}
/**
* Returns `true` if the provided value is a `Prompt`.
*
* @category guards
* @since 4.0.0
*/
export declare const isPrompt: (u: unknown) => u is Prompt<unknown>;
/**
* Represents the services available to a custom `Prompt`.
*
* @category models
* @since 4.0.0
*/
export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal;
/**
* Represents the action that should be taken by a `Prompt` based upon user
* input or an external event received during the current frame.
*
* @category models
* @since 4.0.0
*/
export type Action<State, Output> = Data.TaggedEnum<{
readonly Beep: {};
readonly NextFrame: {
readonly state: State;
};
readonly Submit: {
readonly value: Output;
};
}>;
/**
* Type-level definition for the tagged `Prompt.Action` variants.
*
* **Details**
*
* It connects the action state and output type parameters to the `Beep`,
* `NextFrame`, and `Submit` action cases.
*
* @category models
* @since 4.0.0
*/
export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
readonly taggedEnum: Action<this["A"], this["B"]>;
}
/**
* Represents the input that should be processed by a `Prompt` based upon user
* input or an external event received during the current frame.
*
* @category models
* @since 4.0.0
*/
export type ProcessInput<A> = Data.TaggedEnum<{
readonly Input: {
readonly input: Terminal.UserInput;
};
readonly Event: {
readonly value: A;
};
}>;
/**
* Represents the set of handlers used by a `Prompt`.
*
* **Details**
*
* The handlers render the current frame, process user input into the next
* `Prompt.Action`, and clear the terminal screen before the next frame.
*
* @category models
* @since 4.0.0
*/
export interface Handlers<State, Output, Input = Terminal.UserInput> {
/**
* A function that is called to render the current frame of the `Prompt`.
*/
readonly render: (state: State, action: Action<State, Output>) => Effect.Effect<string, never, Environment>;
/**
* A function that is called to process user input and determine the next
* `Prompt.Action` that should be taken.
*/
readonly process: (input: Input, state: State) => Effect.Effect<Action<State, Output>, never, Environment>;
/**
* A function that is called to clear the terminal screen before rendering
* the next frame of the `Prompt`.
*/
readonly clear: (state: State, action: Action<State, Output>) => Effect.Effect<string, never, Environment>;
}
/**
* Options for a confirmation prompt that asks the user to choose a boolean
* yes/no value.
*
* @category options
* @since 4.0.0
*/
export interface ConfirmOptions {
/**
* The message to display in the prompt.
*/
readonly message: string;
/**
* The initial value of the confirm prompt (defaults to `false`).
*/
readonly initial?: boolean;
/**
* The label to display after a user has responded to the prompt.
*/
readonly label?: {
/**
* The label used if the prompt is confirmed (defaults to `"yes"`).
*/
readonly confirm: string;
/**
* The label used if the prompt is not confirmed (defaults to `"no"`).
*/
readonly deny: string;
};
/**
* The placeholder to display when a user is responding to the prompt.
*/
readonly placeholder?: {
/**
* The placeholder to use if the `initial` value of the prompt is `true`
* (defaults to `"(Y/n)"`).
*/
readonly defaultConfirm?: string;
/**
* The placeholder to use if the `initial` value of the prompt is `false`
* (defaults to `"(y/N)"`).
*/
readonly defaultDeny?: string;
};
}
/**
* Options for a date prompt, including the displayed message, initial value,
* format mask, validation, and locale labels.
*
* @category options
* @since 4.0.0
*/
export interface DateOptions {
/**
* The message to display in the prompt.
*/
readonly message: string;
/**
* The initial date value to display in the prompt (defaults to the current
* date).
*/
readonly initial?: globalThis.Date;
/**
* The format mask of the date (defaults to `YYYY-MM-DD HH:mm:ss`).
*/
readonly dateMask?: string;
/**
* An effectful function that can be used to validate the value entered into
* the prompt before final submission.
*/
readonly validate?: (value: globalThis.Date) => Effect.Effect<globalThis.Date, string>;
/**
* Custom locales that can be used in place of the defaults.
*/
readonly locales?: {
/**
* The full names of each month of the year.
*/
readonly months: [
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string
];
/**
* The short names of each month of the year.
*/
readonly monthsShort: [
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string,
string
];
/**
* The full names of each day of the week.
*/
readonly weekdays: [string, string, string, string, string, string, string];
/**
* The short names of each day of the week.
*/
readonly weekdaysShort: [string, string, string, string, string, string, string];
};
}
/**
* Options for an integer prompt, including bounds, keyboard step sizes, and
* additional validation.
*
* @category options
* @since 4.0.0
*/
export interface IntegerOptions {
/**
* The message to display in the prompt.
*/
readonly message: string;
/**
* The default value of the integer prompt.
*/
readonly default?: number;
/**
* The minimum value that can be entered by the user (defaults to `-Infinity`).
*/
readonly min?: number;
/**
* The maximum value that can be entered by the user (defaults to `Infinity`).
*/
readonly max?: number;
/**
* The value that will be used to increment the prompt value when using the
* up arrow key (defaults to `1`).
*/
readonly incrementBy?: number;
/**
* The value that will be used to decrement the prompt value when using the
* down arrow key (defaults to `1`).
*/
readonly decrementBy?: number;
/**
* An effectful function that can be used to validate the value entered into
* the prompt before final submission.
*/
readonly validate?: (value: number) => Effect.Effect<number, string>;
}
/**
* Options for a floating-point number prompt.
*
* **Details**
*
* In addition to the numeric bounds and step settings from `IntegerOptions`,
* the prompt can be configured with a display precision.
*
* @category options
* @since 4.0.0
*/
export interface FloatOptions extends IntegerOptions {
/**
* The precision to use for the floating point value (defaults to `2`).
*/
readonly precision?: number;
}
/**
* Options for a text prompt that returns a list of strings by splitting the
* input on a delimiter.
*
* @category options
* @since 4.0.0
*/
export interface ListOptions extends TextOptions {
/**
* The delimiter that separates list entries.
*/
readonly delimiter?: string;
}
/**
* Options for a file-system selection prompt.
*
* **Details**
*
* They control which path type can be selected, the starting directory, paging,
* and filtering of displayed entries.
*
* @category options
* @since 4.0.0
*/
export interface FileOptions {
/**
* The path type that will be selected, defaulting to `"file"`.
*/
readonly type?: Primitive.PathType;
/**
* The message to display in the prompt, defaulting to `"Choose a file"`.
*/
readonly message?: string;
/**
* Where the user will initially be prompted to select files from, defaulting
* to the current working directory.
*/
readonly startingPath?: string;
/**
* The default path to select when the prompt is first displayed.
*/
readonly default?: string;
/**
* The number of choices to display at one time, defaulting to `10`.
*/
readonly maxPerPage?: number;
/**
* A predicate or effect that keeps a file in the prompt when it returns
* `true`, defaulting to returning all files.
*/
readonly filter?: (file: string) => boolean | Effect.Effect<boolean, never, Environment>;
}
/**
* Options for a prompt that asks the user to select one value from a list of
* choices.
*
* @category options
* @since 4.0.0
*/
export interface SelectOptions<A> {
/**
* The message to display in the prompt.
*/
readonly message: string;
/**
* The choices to display to the user.
*/
readonly choices: ReadonlyArray<SelectChoice<A>>;
/**
* The number of choices to display at one time (defaults to `10`).
*/
readonly maxPerPage?: number;
}
/**
* Options for an autocomplete prompt that lets the user filter selectable
* choices by typing.
*
* @category options
* @since 4.0.0
*/
export interface AutoCompleteOptions<A> extends SelectOptions<A> {
/**
* The label used for the filter display (defaults to "filter").
*/
readonly filterLabel?: string;
/**
* The placeholder shown when the filter is empty (defaults to "type to filter").
*/
readonly filterPlaceholder?: string;
/**
* The message displayed when no choices match (defaults to "No matches").
*/
readonly emptyMessage?: string;
}
/**
* Options for a multi-select prompt, including bulk-selection labels and
* minimum or maximum selection counts.
*
* @category options
* @since 4.0.0
*/
export interface MultiSelectOptions {
/**
* Text for the "Select All" option (defaults to "Select All").
*/
readonly selectAll?: string;
/**
* Text for the "Select None" option (defaults to "Select None").
*/
readonly selectNone?: string;
/**
* Text for the "Inverse Selection" option (defaults to "Inverse Selection").
*/
readonly inverseSelection?: string;
/**
* The minimum number of choices that must be selected.
*/
readonly min?: number;
/**
* The maximum number of choices that can be selected.
*/
readonly max?: number;
}
/**
* Represents one choice displayed by select, autocomplete, and multi-select
* prompts.
*
* @category models
* @since 4.0.0
*/
export interface SelectChoice<A> {
/**
* The name of the select option that is displayed to the user.
*/
readonly title: string;
/**
* The underlying value of the select option.
*/
readonly value: A;
/**
* An optional description for the select option which will be displayed
* to the user.
*/
readonly description?: string;
/**
* Whether or not this select option is disabled.
*/
readonly disabled?: boolean;
/**
* Whether this option should be selected by default (only used by MultiSelect).
*/
readonly selected?: boolean;
}
/**
* Options for text-entry prompts, including the displayed message, default
* text, and effectful validation before submission.
*
* @category options
* @since 4.0.0
*/
export interface TextOptions {
/**
* The message to display in the prompt.
*/
readonly message: string;
/**
* The default value of the text option.
*/
readonly default?: string;
/**
* An effectful function that can be used to validate the value entered into
* the prompt before final submission.
*/
readonly validate?: (value: string) => Effect.Effect<string, string>;
}
/**
* Options for a toggle prompt that lets the user switch between active and
* inactive boolean states.
*
* @category options
* @since 4.0.0
*/
export interface ToggleOptions {
/**
* The message to display in the prompt.
*/
readonly message: string;
/**
* The intitial value of the toggle prompt (defaults to `false`).
*/
readonly initial?: boolean;
/**
* The text to display when the toggle is in the active state (defaults to
* `on`).
*/
readonly active?: string;
/**
* The text to display when the toggle is in the inactive state (defaults to
* `off`).
*/
readonly inactive?: string;
}
/**
* Type alias for any `Prompt`, regardless of its output type.
*
* @category utility types
* @since 4.0.0
*/
export type Any = Prompt<unknown>;
/**
* Namespace containing return-type helpers for `Prompt.all`.
*
* @since 4.0.0
*/
export declare namespace All {
/**
* Computes the prompt returned by `Prompt.all` for an iterable of prompts.
*
* **Details**
*
* The resulting prompt produces an array of each prompt's output value.
*
* @category utility types
* @since 4.0.0
*/
type ReturnIterable<T extends Iterable<Any>> = [T] extends [Iterable<Prompt<infer A>>] ? Prompt<Array<A>> : never;
/**
* Computes the prompt returned by `Prompt.all` for a readonly tuple or array
* of prompts, preserving tuple positions in the output type.
*
* @category utility types
* @since 4.0.0
*/
type ReturnTuple<T extends ReadonlyArray<unknown>> = Prompt<T[number] extends never ? [] : {
-readonly [K in keyof T]: [T[K]] extends [Prompt<infer _A>] ? _A : never;
}> extends infer X ? X : never;
/**
* Computes the prompt returned by `Prompt.all` for a record of prompts,
* preserving the record keys and replacing each prompt with its output type.
*
* @category utility types
* @since 4.0.0
*/
type ReturnObject<T> = [T] extends [{
[K: string]: Any;
}] ? Prompt<{
-readonly [K in keyof T]: [T[K]] extends [Prompt<infer _A>] ? _A : never;
}> : never;
/**
* Computes the return prompt type for `Prompt.all` based on the input
* structure.
*
* @category constructors
* @since 4.0.0
*/
type Return<Arg extends Iterable<Any> | Record<string, Any>> = [Arg] extends [ReadonlyArray<Any>] ? ReturnTuple<Arg> : [Arg] extends [Iterable<Any>] ? ReturnIterable<Arg> : [Arg] extends [Record<string, Any>] ? ReturnObject<Arg> : never;
}
/**
* Runs all the provided prompts in sequence respecting the structure provided
* in input.
*
* **Details**
*
* Supports either a tuple / iterable of prompts or a record / struct of prompts
* as an argument.
*
* **Example** (Collecting prompt results)
*
* ```ts
* import { Effect } from "effect"
* import { Prompt } from "effect/unstable/cli"
*
* const username = Prompt.text({
* message: "Enter your username: "
* })
*
* const password = Prompt.password({
* message: "Enter your password: ",
* validate: (value) =>
* value.length === 0
* ? Effect.fail("Password cannot be empty")
* : Effect.succeed(value)
* })
*
* const allWithTuple = Prompt.all([username, password])
*
* const allWithRecord = Prompt.all({ username, password })
* ```
*
* @category collecting & elements
* @since 4.0.0
*/
export declare const all: <const Arg extends Iterable<Prompt<any>> | Record<string, Prompt<any>>>(arg: Arg) => All.Return<Arg>;
/**
* Creates a confirmation prompt that asks the user to choose a boolean yes/no
* value.
*
* **When to use**
*
* Use to ask for a yes/no answer that can be submitted directly.
*
* **Details**
*
* `initial` defaults to `false`. Enter submits the current default, yes-style
* input submits `true`, no-style input submits `false`, and other input beeps.
*
* @see {@link toggle} for an interactive switch-before-submit boolean prompt
*
* @category constructors
* @since 4.0.0
*/
export declare const confirm: (options: ConfirmOptions) => Prompt<boolean>;
/**
* Creates a custom `Prompt` from the specified initial state and handlers.
*
* **Details**
*
* The initial state can either be a pure value or an `Effect`. This is
* particularly useful when the initial state of the `Prompt` must be computed
* by performing an effectful computation, such as reading data from the file
* system. A `Prompt` runs as a render loop: `render` returns ANSI output for
* the current frame, the `Terminal` obtains user input, `process` returns the
* next prompt action, and `clear` returns ANSI output used to clear the previous
* frame.
*
* Optionally, an external `events` dequeue can be provided as the third
* argument. When present, the render loop will race user input against events
* from the dequeue, allowing background events to trigger re-renders without
* waiting for a keypress. When an event is received from the dequeue, the
* `receive` handler is called instead of `process`.
*
* @category constructors
* @since 4.0.0
*/
export declare const custom: {
/**
* Creates a custom `Prompt` from the specified initial state and handlers.
*
* **Details**
*
* The initial state can either be a pure value or an `Effect`. This is
* particularly useful when the initial state of the `Prompt` must be computed
* by performing an effectful computation, such as reading data from the file
* system. A `Prompt` runs as a render loop: `render` returns ANSI output for
* the current frame, the `Terminal` obtains user input, `process` returns the
* next prompt action, and `clear` returns ANSI output used to clear the previous
* frame.
*
* Optionally, an external `events` dequeue can be provided as the third
* argument. When present, the render loop will race user input against events
* from the dequeue, allowing background events to trigger re-renders without
* waiting for a keypress. When an event is received from the dequeue, the
* `receive` handler is called instead of `process`.
*
* @category constructors
* @since 4.0.0
*/
<State, Output>(initialState: State | Effect.Effect<State, never, Environment>, handlers: Handlers<State, Output>): Prompt<Output>;
/**
* Creates a custom `Prompt` from the specified initial state and handlers.
*
* **Details**
*
* The initial state can either be a pure value or an `Effect`. This is
* particularly useful when the initial state of the `Prompt` must be computed
* by performing an effectful computation, such as reading data from the file
* system. A `Prompt` runs as a render loop: `render` returns ANSI output for
* the current frame, the `Terminal` obtains user input, `process` returns the
* next prompt action, and `clear` returns ANSI output used to clear the previous
* frame.
*
* Optionally, an external `events` dequeue can be provided as the third
* argument. When present, the render loop will race user input against events
* from the dequeue, allowing background events to trigger re-renders without
* waiting for a keypress. When an event is received from the dequeue, the
* `receive` handler is called instead of `process`.
*
* @category constructors
* @since 4.0.0
*/
<State, Output, A>(initialState: State | Effect.Effect<State, never, Environment>, events: Queue.Dequeue<A, never>, handlers: Handlers<State, Output, ProcessInput<A>>): Prompt<Output>;
};
/**
* Creates a date prompt that lets the user edit a formatted date value and
* validates the final `Date` before submission.
*
* **Details**
*
* `initial` defaults to the current `Date`, `dateMask` defaults to
* `YYYY-MM-DD HH:mm:ss`, mask parsing creates editable date parts plus literal
* tokens, `locales` customizes month and weekday labels, and `validate` runs on
* submission.
*
* **Gotchas**
*
* A supplied `initial` `Date` is edited in place during prompt interaction.
* Date edits use JavaScript `Date` setters, so out-of-range typed values can
* normalize before validation. If the prompt is meant to be editable,
* `dateMask` should contain at least one editable date token.
*
* @category constructors
* @since 4.0.0
*/
export declare const date: (options: DateOptions) => Prompt<Date>;
/**
* Creates a file-system selection prompt and returns the selected path.
*
* **Details**
*
* The prompt can be configured to select files, directories, or either path
* type.
*
* @category constructors
* @since 4.0.0
*/
export declare const file: (options?: FileOptions) => Prompt<string>;
/**
* Composes prompts by using the output of this prompt to create the next prompt.
*
* @category combinators
* @since 4.0.0
*/
export declare const flatMap: {
/**
* Composes prompts by using the output of this prompt to create the next prompt.
*
* @category combinators
* @since 4.0.0
*/
<Output, Output2>(f: (output: Output) => Prompt<Output2>): (self: Prompt<Output>) => Prompt<Output2>;
/**
* Composes prompts by using the output of this prompt to create the next prompt.
*
* @category combinators
* @since 4.0.0
*/
<Output, Output2>(self: Prompt<Output>, f: (output: Output) => Prompt<Output2>): Prompt<Output2>;
};
/**
* Creates a floating-point number prompt.
*
* **Details**
*
* The prompt supports minimum and maximum bounds, keyboard step sizes, display
* precision, and additional validation before submission.
*
* @category constructors
* @since 4.0.0
*/
export declare const float: (options: FloatOptions) => Prompt<number>;
/**
* Creates a text prompt that does not echo typed input and returns the
* submitted value wrapped in `Redacted`.
*
* @category constructors
* @since 4.0.0
*/
export declare const hidden: (options: TextOptions) => Prompt<Redacted.Redacted>;
/**
* Creates an integer prompt.
*
* **Details**
*
* The prompt supports minimum and maximum bounds, keyboard step sizes, and
* additional validation before submission.
*
* @category constructors
* @since 4.0.0
*/
export declare const integer: (options: IntegerOptions) => Prompt<number>;
/**
* Creates a text prompt that returns an array of strings by splitting the
* submitted input on the configured delimiter.
*
* @category constructors
* @since 4.0.0
*/
export declare const list: (options: ListOptions) => Prompt<Array<string>>;
/**
* Transforms the output value produced by a prompt.
*
* @category combinators
* @since 4.0.0
*/
export declare const map: {
/**
* Transforms the output value produced by a prompt.
*
* @category combinators
* @since 4.0.0
*/
<Output, Output2>(f: (output: Output) => Output2): (self: Prompt<Output>) => Prompt<Output2>;
/**
* Transforms the output value produced by a prompt.
*
* @category combinators
* @since 4.0.0
*/
<Output, Output2>(self: Prompt<Output>, f: (output: Output) => Output2): Prompt<Output2>;
};
/**
* Creates a password prompt that masks typed input and returns the submitted
* value wrapped in `Redacted`.
*
* @category constructors
* @since 4.0.0
*/
export declare const password: (options: TextOptions) => Prompt<Redacted.Redacted>;
/**
* Runs a prompt by reading terminal input and rendering prompt frames until the
* prompt submits a value.
*
* **Gotchas**
*
* The returned effect may fail with `Terminal.QuitError` if terminal input ends
* or the prompt is quit.
*
* @category execution
* @since 4.0.0
*/
export declare const run: <Output>(self: Prompt<Output>) => Effect.Effect<Output, Terminal.QuitError, Environment>;
/**
* Creates a prompt that lets the user select a single value from a list of
* choices.
*
* **Gotchas**
*
* At most one choice may be marked as selected by default.
*
* @category constructors
* @since 4.0.0
*/
export declare const select: <const A>(options: SelectOptions<A>) => Prompt<A>;
/**
* Creates a prompt that lets users filter select choices by typing.
*
* **Example** (Filtering choices with autocomplete)
*
* ```ts
* import { Prompt } from "effect/unstable/cli"
*
* const language = Prompt.autoComplete({
* message: "Choose a language",
* choices: [
* { title: "TypeScript", value: "ts" },
* { title: "Rust", value: "rs" },
* { title: "Kotlin", value: "kt" }
* ]
* })
* ```
*
* @category constructors
* @since 4.0.0
*/
export declare const autoComplete: <const A>(options: AutoCompleteOptions<A>) => Prompt<A>;
/**
* Creates a prompt that lets the user select multiple choices and returns their
* values as an array.
*
* **Details**
*
* The prompt supports default selected choices, bulk-selection commands, and
* minimum or maximum selection counts.
*
* @category constructors
* @since 4.0.0
*/
export declare const multiSelect: <const A>(options: SelectOptions<A> & MultiSelectOptions) => Prompt<Array<A>>;
/**
* Creates a `Prompt` which immediately succeeds with the specified value.
*
* **Details**
*
* This prompt does not attempt to obtain user input or render anything to the
* screen.
*
* @category constructors
* @since 4.0.0
*/
export declare const succeed: <A>(value: A) => Prompt<A>;
/**
* Creates a text-entry prompt that echoes input and returns the submitted
* string after validation.
*
* @category constructors
* @since 4.0.0
*/
export declare const text: (options: TextOptions) => Prompt<string>;
/**
* Creates a toggle prompt that lets the user switch between active and inactive
* states and returns the selected boolean value.
*
* @category constructors
* @since 4.0.0
*/
export declare const toggle: (options: ToggleOptions) => Prompt<boolean>;
export {};
//# sourceMappingURL=Prompt.d.ts.map

Xet Storage Details

Size:
27 kB
·
Xet hash:
8693922b4e038f8cb90097213171b8c7e4562ef0666d1379c7d99a77a4fe6a5a

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.