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

Options overview

Added in v1.0.0

Table of contents

combinators

atLeast

Signature

export declare const atLeast: {
  (times: 0): <A>(self: Options<A>) => Options<A[]>
  (times: number): <A>(self: Options<A>) => Options<NonEmptyArray<A>>
  <A>(self: Options<A>, times: 0): Options<A[]>
  <A>(self: Options<A>, times: number): Options<NonEmptyArray<A>>
}

Added in v1.0.0

atMost

Signature

export declare const atMost: {
  (times: number): <A>(self: Options<A>) => Options<A[]>
  <A>(self: Options<A>, times: number): Options<A[]>
}

Added in v1.0.0

between

Signature

export declare const between: {
  (min: 0, max: number): <A>(self: Options<A>) => Options<A[]>
  (min: number, max: number): <A>(self: Options<A>) => Options<NonEmptyArray<A>>
  <A>(self: Options<A>, min: 0, max: number): Options<A[]>
  <A>(self: Options<A>, min: number, max: number): Options<NonEmptyArray<A>>
}

Added in v1.0.0

filterMap

Signature

export declare const filterMap: {
  <A, B>(f: (a: A) => Option<B>, message: string): (self: Options<A>) => Options<B>
  <A, B>(self: Options<A>, f: (a: A) => Option<B>, message: string): Options<B>
}

Added in v1.0.0

getHelp

Signature

export declare const getHelp: <A>(self: Options<A>) => HelpDoc

Added in v1.0.0

getIdentifier

Signature

export declare const getIdentifier: <A>(self: Options<A>) => Option<string>

Added in v1.0.0

getUsage

Signature

export declare const getUsage: <A>(self: Options<A>) => Usage

Added in v1.0.0

isBool

Returns true if the specified Options is a boolean flag, false otherwise.

Signature

export declare const isBool: <A>(self: Options<A>) => boolean

Added in v1.0.0

map

Signature

export declare const map: {
  <A, B>(f: (a: A) => B): (self: Options<A>) => Options<B>
  <A, B>(self: Options<A>, f: (a: A) => B): Options<B>
}

Added in v1.0.0

mapEffect

Signature

export declare const mapEffect: {
  <A, B>(f: (a: A) => Effect<B, ValidationError, any>): (self: Options<A>) => Options<B>
  <A, B>(self: Options<A>, f: (a: A) => Effect<B, ValidationError, any>): Options<B>
}

Added in v1.0.0

mapTryCatch

Signature

export declare const mapTryCatch: {
  <A, B>(f: (a: A) => B, onError: (e: unknown) => HelpDoc): (self: Options<A>) => Options<B>
  <A, B>(self: Options<A>, f: (a: A) => B, onError: (e: unknown) => HelpDoc): Options<B>
}

Added in v1.0.0

optional

Signature

export declare const optional: <A>(self: Options<A>) => Options<Option<A>>

Added in v1.0.0

orElse

Signature

export declare const orElse: {
  <A>(that: Options<A>): <B>(self: Options<B>) => Options<A | B>
  <A, B>(self: Options<A>, that: Options<B>): Options<A | B>
}

Added in v1.0.0

orElseEither

Signature

export declare const orElseEither: {
  <A>(that: Options<A>): <B>(self: Options<B>) => Options<Either<A, B>>
  <A, B>(self: Options<A>, that: Options<B>): Options<Either<A, B>>
}

Added in v1.0.0

parse

Signature

export declare const parse: {
  (
    args: HashMap<string, readonly string[]>,
    config: CliConfig
  ): <A>(self: Options<A>) => Effect<A, ValidationError, FileSystem>
  <A>(
    self: Options<A>,
    args: HashMap<string, readonly string[]>,
    config: CliConfig
  ): Effect<A, ValidationError, FileSystem>
}

Added in v1.0.0

processCommandLine

Processes the provided command-line arguments, searching for the specified Options.

Returns an Option<ValidationError>, any leftover arguments, and the constructed value of type A. The possible error inside Option<ValidationError> would only be triggered if there is an error when parsing the command-line arguments. This is because ValidationErrors are also used internally to control the end of the command-line arguments (i.e. the command-line symbol --) corresponding to options.

Signature

export declare const processCommandLine: {
  (
    args: ReadonlyArray<string>,
    config: CliConfig
  ): <A>(self: Options<A>) => Effect<[Option<ValidationError>, string[], A], ValidationError, any>
  <A>(
    self: Options<A>,
    args: ReadonlyArray<string>,
    config: CliConfig
  ): Effect<[Option<ValidationError>, string[], A], ValidationError, any>
}

Added in v1.0.0

repeated

Indicates that the specified command-line option can be repeated 0 or more times.

NOTE: if the command-line option is not provided, and empty array will be returned as the value for said option.

Signature

export declare const repeated: <A>(self: Options<A>) => Options<A[]>

Added in v1.0.0

withAlias

Signature

export declare const withAlias: {
  (alias: string): <A>(self: Options<A>) => Options<A>
  <A>(self: Options<A>, alias: string): Options<A>
}

Added in v1.0.0

withDefault

Signature

export declare const withDefault: {
  <const B>(fallback: B): <A>(self: Options<A>) => Options<B | A>
  <A, const B>(self: Options<A>, fallback: B): Options<A | B>
}

Added in v1.0.0

withDescription

Signature

export declare const withDescription: {
  (description: string): <A>(self: Options<A>) => Options<A>
  <A>(self: Options<A>, description: string): Options<A>
}

Added in v1.0.0

withFallbackConfig

Signature

export declare const withFallbackConfig: {
  <B>(config: Config<B>): <A>(self: Options<A>) => Options<B | A>
  <A, B>(self: Options<A>, config: Config<B>): Options<A | B>
}

Added in v1.0.0

withPseudoName

Signature

export declare const withPseudoName: {
  (pseudoName: string): <A>(self: Options<A>) => Options<A>
  <A>(self: Options<A>, pseudoName: string): Options<A>
}

Added in v1.0.0

withSchema

Signature

export declare const withSchema: {
  <A, I extends A, B>(schema: Schema<B, I, any>): (self: Options<A>) => Options<B>
  <A, I extends A, B>(self: Options<A>, schema: Schema<B, I, any>): Options<B>
}

Added in v1.0.0

wizard

Signature

export declare const wizard: {
  (config: CliConfig): <A>(self: Options<A>) => Effect<string[], any, any>
  <A>(self: Options<A>, config: CliConfig): Effect<string[], any, any>
}

Added in v1.0.0

constructors

all

Signature

export declare const all: <const Arg extends Iterable<Options<any>> | Record<string, Options<any>>>(
  arg: Arg
) => All.Return<Arg>

Added in v1.0.0

boolean

Signature

export declare const boolean: (name: string, options?: Options.BooleanOptionsConfig) => Options<boolean>

Added in v1.0.0

choice

Constructs command-line Options that represent a choice between several inputs. The input will be mapped to it’s associated value during parsing.

Signature

export declare const choice: <A extends string, C extends readonly A[]>(name: string, choices: C) => Options<C[number]>

Example

import * as Options from "@effect/cli/Options"

export const animal: Options.Options<"dog" | "cat"> = Options.choice("animal", ["dog", "cat"])

Added in v1.0.0

choiceWithValue

Constructs command-line Options that represent a choice between several inputs. The input will be mapped to it’s associated value during parsing.

Signature

export declare const choiceWithValue: <C extends readonly [string, any][]>(
  name: string,
  choices: C
) => Options<C[number][1]>

Example

import * as Options from "@effect/cli/Options"
import * as Data from "effect/Data"

export type Animal = Dog | Cat

export interface Dog {
  readonly _tag: "Dog"
}

export const Dog = Data.tagged<Dog>("Dog")

export interface Cat {
  readonly _tag: "Cat"
}

export const Cat = Data.tagged<Cat>("Cat")

export const animal: Options.Options<Animal> = Options.choiceWithValue("animal", [
  ["dog", Dog()],
  ["cat", Cat()]
])

Added in v1.0.0

date

Signature

export declare const date: (name: string) => Options<globalThis.Date>

Added in v1.0.0

directory

Creates a parameter expecting path to a directory.

Signature

export declare const directory: (name: string, config?: Options.PathOptionsConfig) => Options<string>

Added in v1.0.0

file

Creates a parameter expecting path to a file.

Signature

export declare const file: (name: string, config?: Options.PathOptionsConfig) => Options<string>

Added in v1.0.0

fileContent

Creates a parameter expecting path to a file and reads its contents.

Signature

export declare const fileContent: (name: string) => Options<readonly [path: string, content: Uint8Array]>

Added in v1.0.0

fileParse

Creates a parameter expecting path to a file and parse its contents.

Signature

export declare const fileParse: (
  name: string,
  format?: "json" | "yaml" | "ini" | "toml" | undefined
) => Options<unknown>

Added in v1.0.0

fileSchema

Creates a parameter expecting path to a file, parse its contents and validate it with a Schema.

Signature

export declare const fileSchema: <I, A>(
  name: string,
  schema: Schema<A, I, any>,
  format?: "json" | "yaml" | "ini" | "toml" | undefined
) => Options<A>

Added in v1.0.0

fileText

Creates a parameter expecting path to a file and reads its contents.

Signature

export declare const fileText: (name: string) => Options<readonly [path: string, content: string]>

Added in v1.0.0

float

Signature

export declare const float: (name: string) => Options<number>

Added in v1.0.0

integer

Signature

export declare const integer: (name: string) => Options<number>

Added in v1.0.0

keyValueMap

Signature

export declare const keyValueMap: (option: string | Options<string>) => Options<HashMap<string, string>>

Added in v1.0.0

none

Signature

export declare const none: Options<void>

Added in v1.0.0

secret

Signature

export declare const secret: (name: string) => Options<Secret>

Added in v1.0.0

text

Signature

export declare const text: (name: string) => Options<string>

Added in v1.0.0

models

Options (interface)

Signature

export interface Options<A> extends Options.Variance<A>, Pipeable {}

Added in v1.0.0

refinements

isOptions

Signature

export declare const isOptions: (u: unknown) => u is Options<unknown>

Added in v1.0.0

symbols

OptionsTypeId

Signature

export declare const OptionsTypeId: typeof OptionsTypeId

Added in v1.0.0

OptionsTypeId (type alias)

Signature

export type OptionsTypeId = typeof OptionsTypeId

Added in v1.0.0

utils

All (namespace)

Added in v1.0.0

OptionsAny (type alias)

Signature

export type OptionsAny = Options<any>

Added in v1.0.0

Return (type alias)

Signature

export type Return<Arg extends Iterable<OptionsAny> | Record<string, OptionsAny>> = [Arg] extends [
  ReadonlyArray<OptionsAny>
]
  ? ReturnTuple<Arg>
  : [Arg] extends [Iterable<OptionsAny>]
    ? ReturnIterable<Arg>
    : [Arg] extends [Record<string, OptionsAny>]
      ? ReturnObject<Arg>
      : never

Added in v1.0.0

ReturnIterable (type alias)

Signature

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

Added in v1.0.0

ReturnObject (type alias)

Signature

export type ReturnObject<T> = [T] extends [{ [K: string]: OptionsAny }]
  ? Options<{
      -readonly [K in keyof T]: [T[K]] extends [Options.Variance<infer _A>] ? _A : never
    }>
  : never

Added in v1.0.0

ReturnTuple (type alias)

Signature

export type ReturnTuple<T extends ReadonlyArray<unknown>> =
  Options<
    T[number] extends never
      ? []
      : {
          -readonly [K in keyof T]: [T[K]] extends [Options.Variance<infer _A>] ? _A : never
        }
  > extends infer X
    ? X
    : never

Added in v1.0.0

Options (namespace)

Added in v1.0.0

BooleanOptionsConfig (interface)

Signature

export interface BooleanOptionsConfig {
  readonly ifPresent?: boolean
  readonly negationNames?: ReadonlyArray<string>
  readonly aliases?: ReadonlyArray<string>
}

Added in v1.0.0

PathOptionsConfig (interface)

Signature

export interface PathOptionsConfig {
  readonly exists?: Primitive.PathExists
}

Added in v1.0.0

Variance (interface)

Signature

export interface Variance<A> {
  readonly [OptionsTypeId]: {
    _A: (_: never) => A
  }
}

Added in v1.0.0