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

Prompt.ts overview

Since v1.0.0


Exports Grouped by Category


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>

Source

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>
}

Source

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>
}

Source

Since v1.0.0

constructors

confirm

Signature

declare const confirm: (options: Prompt.ConfirmOptions) => Prompt<boolean>

Source

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:

  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

declare const custom: <State, Output>(
  initialState: State | Effect<State, never, Prompt.Environment>,
  handlers: Prompt.Handlers<State, Output>
) => Prompt<Output>

Source

Since v1.0.0

date

Signature

declare const date: (options: Prompt.DateOptions) => Prompt<Date>

Source

Since v1.0.0

file

Signature

declare const file: (options?: Prompt.FileOptions) => Prompt<string>

Source

Since v1.0.0

float

Signature

declare const float: (options: Prompt.FloatOptions) => Prompt<number>

Source

Since v1.0.0

hidden

Signature

declare const hidden: (options: Prompt.TextOptions) => Prompt<Redacted>

Source

Since v1.0.0

integer

Signature

declare const integer: (options: Prompt.IntegerOptions) => Prompt<number>

Source

Since v1.0.0

list

Signature

declare const list: (options: Prompt.ListOptions) => Prompt<Array<string>>

Source

Since v1.0.0

multiSelect

Signature

declare const multiSelect: <A>(options: Prompt.SelectOptions<A> & Prompt.MultiSelectOptions) => Prompt<Array<A>>

Source

Since v1.0.0

password

Signature

declare const password: (options: Prompt.TextOptions) => Prompt<Redacted>

Source

Since v1.0.0

select

Signature

declare const select: <A>(options: Prompt.SelectOptions<A>) => Prompt<A>

Source

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>

Source

Since v1.0.0

text

Signature

declare const text: (options: Prompt.TextOptions) => Prompt<string>

Source

Since v1.0.0

toggle

Signature

declare const toggle: (options: Prompt.ToggleOptions) => Prompt<boolean>

Source

Since v1.0.0

execution

run

Executes the specified Prompt.

Signature

declare const run: <Output>(self: Prompt<Output>) => Effect<Output, QuitException, Prompt.Environment>

Source

Since v1.0.0

models

Prompt (interface)

Signature

export interface Prompt<Output> extends Prompt.Variance<Output>, Pipeable, Effect<Output, QuitException, Terminal> {}

Source

Since v1.0.0

symbols

PromptTypeId

Signature

declare const PromptTypeId: unique symbol

Source

Since v1.0.0

PromptTypeId (type alias)

Signature

type PromptTypeId = typeof PromptTypeId

Source

Since v1.0.0

utils

All (namespace)

Source

Since v1.0.0

PromptAny (type alias)

Signature

type PromptAny = Prompt<any>

Source

Since v1.0.0

ReturnIterable (type alias)

Signature

type ReturnIterable<T> = [T] extends [Iterable<Prompt.Variance<infer A>>] ? Prompt<Array<A>> : never

Source

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

Source

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

Source

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

Source

Since v1.0.0

Prompt (namespace)

Source

Since v1.0.0

Variance (interface)

Signature

export interface Variance<Output> {
  readonly [PromptTypeId]: Prompt.VarianceStruct<Output>
}

Source

Since v1.0.0

VarianceStruct (interface)

Signature

export interface VarianceStruct<Output> {
  readonly _Output: (_: never) => Output
}

Source

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"]>
}

Source

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>
}

Source

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
  }
}

Source

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]
  }
}

Source

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>
}

Source

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
}

Source

Since v1.0.0

ListOptions (interface)

Signature

export interface ListOptions extends TextOptions {
  /**
   * The delimiter that separates list entries.
   */
  readonly delimiter?: string
}

Source

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>
}

Source

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
}

Source

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
}

Source

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
}

Source

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>
}

Source

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
}

Source

Since v1.0.0

Environment (type alias)

Represents the services available to a custom Prompt.

Signature

type Environment = FileSystem | Path | Terminal

Source

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 }
  }>

Source

Since v1.0.0