Prompt overview
Added in v1.0.0
Table of contents
- collecting & elements
- combinators
- constructors
- execution
- models
- symbols
- utils
- All (namespace)
- Prompt (namespace)
- ActionDefinition (interface)
- ConfirmOptions (interface)
- DateOptions (interface)
- FileOptions (interface)
- FloatOptions (interface)
- Handlers (interface)
- IntegerOptions (interface)
- ListOptions (interface)
- MultiSelectOptions (interface)
- SelectChoice (interface)
- SelectOptions (interface)
- TextOptions (interface)
- ToggleOptions (interface)
- Variance (interface)
- VarianceStruct (interface)
- Action (type alias)
- Environment (type alias)
collecting & elements
all
Runs all the provided prompts in sequence respecting the structure provided in input.
Supports either a tuple / iterable of prompts or a record / struct of prompts as an argument.
Signature
export declare const all: <const Arg extends Iterable<Prompt<any>> | Record<string, Prompt<any>>>(
arg: Arg
) => All.Return<Arg>
Example
import * as Prompt from "@effect/cli/Prompt"
import * as NodeContext from "@effect/platform-node/NodeContext"
import * as Runtime from "@effect/platform-node/NodeRuntime"
import * as Effect from "effect/Effect"
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 })
Added in v1.0.0
combinators
flatMap
Signature
export declare const flatMap: {
<Output, Output2>(f: (output: Output) => Prompt<Output2>): (self: Prompt<Output>) => Prompt<Output2>
<Output, Output2>(self: Prompt<Output>, f: (output: Output) => Prompt<Output2>): Prompt<Output2>
}
Added in v1.0.0
map
Signature
export declare const map: {
<Output, Output2>(f: (output: Output) => Output2): (self: Prompt<Output>) => Prompt<Output2>
<Output, Output2>(self: Prompt<Output>, f: (output: Output) => Output2): Prompt<Output2>
}
Added in v1.0.0
constructors
confirm
Signature
export declare const confirm: (options: Prompt.ConfirmOptions) => Prompt<boolean>
Added in v1.0.0
custom
Creates a custom Prompt
from the specified initial state and handlers.
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 some effectful computation, such as reading data from the file system.
A Prompt
is essentially a render loop where user input triggers a new frame to be rendered to the Terminal
. The handlers
of a custom prompt are used to control what is rendered to the Terminal
each frame. During each frame, the following occurs:
- The
render
handler is called with this frame’s prompt state and prompt action and returns an ANSI escape string to be rendered to theTerminal
- The
Terminal
obtains input from the user - The
process
handler is called with the input obtained from the user and this frame’s prompt state and returns the next prompt action that should be performed - The
clear
handler is called with this frame’s prompt state and prompt action and returns an ANSI escape string used to clear the screen of theTerminal
Signature
export declare const custom: <State, Output>(
initialState: State | Effect<State, never, Prompt.Environment>,
handlers: Prompt.Handlers<State, Output>
) => Prompt<Output>
Added in v1.0.0
date
Signature
export declare const date: (options: Prompt.DateOptions) => Prompt<Date>
Added in v1.0.0
file
Signature
export declare const file: (options?: Prompt.FileOptions) => Prompt<string>
Added in v1.0.0
float
Signature
export declare const float: (options: Prompt.FloatOptions) => Prompt<number>
Added in v1.0.0
hidden
Signature
export declare const hidden: (options: Prompt.TextOptions) => Prompt<Redacted>
Added in v1.0.0
integer
Signature
export declare const integer: (options: Prompt.IntegerOptions) => Prompt<number>
Added in v1.0.0
list
Signature
export declare const list: (options: Prompt.ListOptions) => Prompt<Array<string>>
Added in v1.0.0
multiSelect
Signature
export declare const multiSelect: <A>(options: Prompt.SelectOptions<A> & Prompt.MultiSelectOptions) => Prompt<Array<A>>
Added in v1.0.0
password
Signature
export declare const password: (options: Prompt.TextOptions) => Prompt<Redacted>
Added in v1.0.0
select
Signature
export declare const select: <A>(options: Prompt.SelectOptions<A>) => Prompt<A>
Added in v1.0.0
succeed
Creates a Prompt
which immediately succeeds with the specified value.
NOTE: This method will not attempt to obtain user input or render anything to the screen.
Signature
export declare const succeed: <A>(value: A) => Prompt<A>
Added in v1.0.0
text
Signature
export declare const text: (options: Prompt.TextOptions) => Prompt<string>
Added in v1.0.0
toggle
Signature
export declare const toggle: (options: Prompt.ToggleOptions) => Prompt<boolean>
Added in v1.0.0
execution
run
Executes the specified Prompt
.
Signature
export declare const run: <Output>(self: Prompt<Output>) => Effect<Output, QuitException, Prompt.Environment>
Added in v1.0.0
models
Prompt (interface)
Signature
export interface Prompt<Output> extends Prompt.Variance<Output>, Pipeable, Effect<Output, QuitException, Terminal> {}
Added in v1.0.0
symbols
PromptTypeId
Signature
export declare const PromptTypeId: typeof PromptTypeId
Added in v1.0.0
PromptTypeId (type alias)
Signature
export type PromptTypeId = typeof PromptTypeId
Added in v1.0.0
utils
All (namespace)
Added in v1.0.0
PromptAny (type alias)
Signature
export type PromptAny = Prompt<any>
Added in v1.0.0
Return (type alias)
Signature
export type Return<Arg extends Iterable<PromptAny> | Record<string, PromptAny>> = [Arg] extends [
ReadonlyArray<PromptAny>
]
? ReturnTuple<Arg>
: [Arg] extends [Iterable<PromptAny>]
? ReturnIterable<Arg>
: [Arg] extends [Record<string, PromptAny>]
? ReturnObject<Arg>
: never
Added in v1.0.0
ReturnIterable (type alias)
Signature
export type ReturnIterable<T extends Iterable<PromptAny>> = [T] extends [Iterable<Prompt.Variance<infer A>>]
? Prompt<Array<A>>
: never
Added in v1.0.0
ReturnObject (type alias)
Signature
export type ReturnObject<T> = [T] extends [{ [K: string]: PromptAny }]
? Prompt<{
-readonly [K in keyof T]: [T[K]] extends [Prompt.Variance<infer _A>] ? _A : never
}>
: never
Added in v1.0.0
ReturnTuple (type alias)
Signature
export type ReturnTuple<T extends ReadonlyArray<unknown>> =
Prompt<
T[number] extends never ? [] : { -readonly [K in keyof T]: [T[K]] extends [Prompt.Variance<infer _A>] ? _A : never }
> extends infer X
? X
: never
Added in v1.0.0
Prompt (namespace)
Added in v1.0.0
ActionDefinition (interface)
Represents the definition of an Action
.
Required to create a Data.TaggedEnum
with generic type arguments.
Signature
export interface ActionDefinition extends TaggedEnum.WithGenerics<2> {
readonly taggedEnum: Action<this["A"], this["B"]>
}
Added in v1.0.0
ConfirmOptions (interface)
Signature
export interface ConfirmOptions {
/**
* The message to display in the prompt.
*/
readonly message: string
/**
* The intitial 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
}
}
Added in v1.0.0
DateOptions (interface)
Signature
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<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]
}
}
Added in v1.0.0
FileOptions (interface)
Signature
export interface FileOptions {
/**
* The path type that will be selected.
*
* Defaults to `"file"`.
*/
readonly type?: Primitive.PathType
/**
* The message to display in the prompt.
*
* Defaults to `"Choose a file"`.
*/
readonly message?: string
/**
* Where the user will initially be prompted to select files from.
*
* Defaults to the current working directory.
*/
readonly startingPath?: string
/**
* The number of choices to display at one time
*
* Defaults to `10`.
*/
readonly maxPerPage?: number
/**
* A function which removes any file from the prompt display where the
* specified predicate returns `true`.
*
* Defaults to returning all files.
*/
readonly filter?: (file: string) => boolean | Effect<boolean, never, Environment>
}
Added in v1.0.0
FloatOptions (interface)
Signature
export interface FloatOptions extends IntegerOptions {
/**
* The precision to use for the floating point value (defaults to `2`).
*/
readonly precision?: number
}
Added in v1.0.0
Handlers (interface)
Represents the set of handlers used by a Prompt
to:
- Render the current frame of the prompt
- Process user input and determine the next
Prompt.Action
to take - Clear the terminal screen before the next frame
Signature
export interface Handlers<State, Output> {
/**
* A function that is called to render the current frame of the `Prompt`.
*
* @param state The current state of the prompt.
* @param action The `Prompt.Action` for the current frame.
* @returns An ANSI escape code sequence to display in the terminal screen.
*/
readonly render: (state: State, action: Action<State, Output>) => Effect<string, never, Environment>
/**
* A function that is called to process user input and determine the next
* `Prompt.Action` that should be taken.
*
* @param input The input the user provided for the current frame.
* @param state The current state of the prompt.
* @returns The next `Prompt.Action` that should be taken.
*/
readonly process: (input: UserInput, state: State) => Effect<Action<State, Output>, never, Environment>
/**
* A function that is called to clear the terminal screen before rendering
* the next frame of the `Prompt`.
*
* @param action The `Prompt.Action` for the current frame.
* @param columns The current number of columns available in the `Terminal`.
* @returns An ANSI escape code sequence used to clear the terminal screen.
*/
readonly clear: (state: State, action: Action<State, Output>) => Effect<string, never, Environment>
}
Added in v1.0.0
IntegerOptions (interface)
Signature
export interface IntegerOptions {
/**
* The message to display in the prompt.
*/
readonly message: string
/**
* 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<number, string>
}
Added in v1.0.0
ListOptions (interface)
Signature
export interface ListOptions extends TextOptions {
/**
* The delimiter that separates list entries.
*/
readonly delimiter?: string
}
Added in v1.0.0
MultiSelectOptions (interface)
Signature
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
}
Added in v1.0.0
SelectChoice (interface)
Signature
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
}
Added in v1.0.0
SelectOptions (interface)
Signature
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
}
Added in v1.0.0
TextOptions (interface)
Signature
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<string, string>
}
Added in v1.0.0
ToggleOptions (interface)
Signature
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
}
Added in v1.0.0
Variance (interface)
Signature
export interface Variance<Output> {
readonly [PromptTypeId]: Prompt.VarianceStruct<Output>
}
Added in v1.0.0
VarianceStruct (interface)
Signature
export interface VarianceStruct<Output> {
readonly _Output: (_: never) => Output
}
Added in v1.0.0
Action (type alias)
Represents the action that should be taken by a Prompt
based upon the user input received during the current frame.
Signature
export type Action<State, Output> = TaggedEnum<{
readonly Beep: {}
readonly NextFrame: { readonly state: State }
readonly Submit: { readonly value: Output }
}>
Added in v1.0.0
Environment (type alias)
Represents the services available to a custom Prompt
.
Signature
export type Environment = FileSystem | Path | Terminal
Added in v1.0.0