Prompt.ts overview
Since v1.0.0
Exports Grouped by Category
- collecting & elements
- combinators
- constructors
- execution
- models
- symbols
- utils
- All (namespace)
- Prompt (namespace)
- Variance (interface)
- VarianceStruct (interface)
- ActionDefinition (interface)
- Handlers (interface)
- ConfirmOptions (interface)
- DateOptions (interface)
- IntegerOptions (interface)
- FloatOptions (interface)
- ListOptions (interface)
- FileOptions (interface)
- SelectOptions (interface)
- MultiSelectOptions (interface)
- SelectChoice (interface)
- TextOptions (interface)
- ToggleOptions (interface)
- Environment (type alias)
- Action (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.
Example
import * as Prompt from "@effect/cli/Prompt"
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 })
Signature
declare const all: <const Arg extends Iterable<Prompt<any>> | Record<string, Prompt<any>>>(arg: Arg) => All.Return<Arg>
Since v1.0.0
combinators
flatMap
Signature
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>
}
Since v1.0.0
map
Signature
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>
}
Since v1.0.0
constructors
confirm
Signature
declare const confirm: (options: Prompt.ConfirmOptions) => Prompt<boolean>
Since 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
declare const custom: <State, Output>(
initialState: State | Effect<State, never, Prompt.Environment>,
handlers: Prompt.Handlers<State, Output>
) => Prompt<Output>
Since v1.0.0
date
Signature
declare const date: (options: Prompt.DateOptions) => Prompt<Date>
Since v1.0.0
file
Signature
declare const file: (options?: Prompt.FileOptions) => Prompt<string>
Since v1.0.0
float
Signature
declare const float: (options: Prompt.FloatOptions) => Prompt<number>
Since v1.0.0
hidden
Signature
declare const hidden: (options: Prompt.TextOptions) => Prompt<Redacted>
Since v1.0.0
integer
Signature
declare const integer: (options: Prompt.IntegerOptions) => Prompt<number>
Since v1.0.0
list
Signature
declare const list: (options: Prompt.ListOptions) => Prompt<Array<string>>
Since v1.0.0
multiSelect
Signature
declare const multiSelect: <A>(options: Prompt.SelectOptions<A> & Prompt.MultiSelectOptions) => Prompt<Array<A>>
Since v1.0.0
password
Signature
declare const password: (options: Prompt.TextOptions) => Prompt<Redacted>
Since v1.0.0
select
Signature
declare const select: <A>(options: Prompt.SelectOptions<A>) => Prompt<A>
Since 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
declare const succeed: <A>(value: A) => Prompt<A>
Since v1.0.0
text
Signature
declare const text: (options: Prompt.TextOptions) => Prompt<string>
Since v1.0.0
toggle
Signature
declare const toggle: (options: Prompt.ToggleOptions) => Prompt<boolean>
Since v1.0.0
execution
run
Executes the specified Prompt
.
Signature
declare const run: <Output>(self: Prompt<Output>) => Effect<Output, QuitException, Prompt.Environment>
Since v1.0.0
models
Prompt (interface)
Signature
export interface Prompt<Output> extends Prompt.Variance<Output>, Pipeable, Effect<Output, QuitException, Terminal> {}
Since v1.0.0
symbols
PromptTypeId
Signature
declare const PromptTypeId: unique symbol
Since v1.0.0
PromptTypeId (type alias)
Signature
type PromptTypeId = typeof PromptTypeId
Since v1.0.0
utils
All (namespace)
Since v1.0.0
PromptAny (type alias)
Signature
type PromptAny = Prompt<any>
Since v1.0.0
ReturnIterable (type alias)
Signature
type ReturnIterable<T> = [T] extends [Iterable<Prompt.Variance<infer A>>] ? Prompt<Array<A>> : never
Since v1.0.0
ReturnTuple (type alias)
Signature
type Prompt<T[number] extends never ? [] : { -readonly [K in keyof T]: [T[K]] extends [Prompt.Variance<infer _A>] ? _A : never; }> = Prompt<
T[number] extends never ? []
: { -readonly [K in keyof T]: [T[K]] extends [Prompt.Variance<infer _A>] ? _A : never }
> extends infer X ? X : never
Since v1.0.0
ReturnObject (type alias)
Signature
type ReturnObject<T> = [T] extends [{ [K: string]: PromptAny }]
? Prompt<{
-readonly [K in keyof T]: [T[K]] extends [Prompt.Variance<infer _A>] ? _A : never
}>
: never
Since v1.0.0
Return (type alias)
Signature
type Return<Arg> = [Arg] extends [ReadonlyArray<PromptAny>]
? ReturnTuple<Arg>
: [Arg] extends [Iterable<PromptAny>]
? ReturnIterable<Arg>
: [Arg] extends [Record<string, PromptAny>]
? ReturnObject<Arg>
: never
Since v1.0.0
Prompt (namespace)
Since v1.0.0
Variance (interface)
Signature
export interface Variance<Output> {
readonly [PromptTypeId]: Prompt.VarianceStruct<Output>
}
Since v1.0.0
VarianceStruct (interface)
Signature
export interface VarianceStruct<Output> {
readonly _Output: (_: never) => Output
}
Since 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"]>
}
Since 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>
}
Since 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
}
}
Since 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]
}
}
Since 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>
}
Since 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
}
Since v1.0.0
ListOptions (interface)
Signature
export interface ListOptions extends TextOptions {
/**
* The delimiter that separates list entries.
*/
readonly delimiter?: string
}
Since 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>
}
Since 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
}
Since 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
}
Since 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
}
Since 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>
}
Since 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
}
Since v1.0.0
Environment (type alias)
Represents the services available to a custom Prompt
.
Signature
type Environment = FileSystem | Path | Terminal
Since 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
type TaggedEnum<{ readonly Beep: {}; readonly NextFrame: { readonly state: State; }; readonly Submit: { readonly value: Output; }; }> = TaggedEnum<{
readonly Beep: {}
readonly NextFrame: { readonly state: State }
readonly Submit: { readonly value: Output }
}>
Since v1.0.0