Skip to main content Link Search Menu Expand Document (external link)

Prompt overview

Added in v1.0.0


Table of contents


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:

  1. The render handler is called with this frame’s prompt state and prompt action and returns an ANSI escape string to be rendered to the Terminal
  2. The Terminal obtains input from the user
  3. 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
  4. 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 the Terminal

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