effect 4.0.0-beta.99 → 4.0.0-rc.109

package/dist/unstable/cli/Param.d.ts

@@ -12,6 +12,7 @@
  */
 import * as Config from "../../Config.ts";
 import * as Effect from "../../Effect.ts";
+import { type LazyArg } from "../../Function.ts";
 import * as Option from "../../Option.ts";
 import { type Pipeable } from "../../Pipeable.ts";
 import * as Predicate from "../../Predicate.ts";
@@ -203,7 +204,8 @@ export interface Transform<Kind extends ParamKind, in out A, out B> extends Para
     readonly _tag: "Transform";
     readonly kind: Kind;
     readonly param: Param<Kind, A>;
-    readonly f: (parse: Parse<A>) => Parse<B>;
+    readonly alternatives: ReadonlyArray<LazyArg<Param<Kind, unknown>>>;
+    readonly f: (parse: Parse<A>, alternatives: ReadonlyArray<LazyArg<Parse<unknown>>>) => Parse<B>;
 }
 /**
  * Parameter node that turns a missing argument or flag into `Option.none()` and
@@ -237,17 +239,15 @@ export interface Variadic<Kind extends ParamKind, A> extends Param<Kind, Readonl
  *
  * **Example** (Checking for params)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const maybeParam = Param.string(Param.flagKind, "name")
  *
- * if (Param.isParam(maybeParam)) {
- *   console.log("This is a Param")
- * }
+ * Param.isParam(maybeParam) // => true
  * ```
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export declare const isParam: (u: unknown) => u is Param<any, ParamKind>;
@@ -256,17 +256,17 @@ export declare const isParam: (u: unknown) => u is Param<any, ParamKind>;
  *
  * **Example** (Checking for single params)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const nameParam = Param.string(Param.flagKind, "name")
  * const optionalParam = Param.optional(nameParam)
  *
- * console.log(Param.isSingle(nameParam)) // true
- * console.log(Param.isSingle(optionalParam)) // false
+ * Param.isSingle(nameParam) // => true
+ * Param.isSingle(optionalParam) // => false
  * ```
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export declare const isSingle: <const Kind extends ParamKind, A>(param: Param<Kind, A>) => param is Single<Kind, A>;
@@ -296,7 +296,7 @@ export declare const makeSingle: <const Kind extends ParamKind, A>(params: {
  *
  * **Example** (Creating string parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a string flag
@@ -306,6 +306,7 @@ export declare const makeSingle: <const Kind extends ParamKind, A>(params: {
  * const fileArg = Param.string(Param.argumentKind, "file")
  *
  * // Usage in CLI: --name "John Doe" or as positional argument
+ * const kinds = [nameFlag.kind, fileArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -317,7 +318,7 @@ export declare const string: <const Kind extends ParamKind>(kind: Kind, name: st
  *
  * **Example** (Creating boolean parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a boolean flag
@@ -328,6 +329,7 @@ export declare const string: <const Kind extends ParamKind>(kind: Kind, name: st
  *
  * // Usage in CLI: --verbose (defaults to true when present, false when absent)
  * // or as positional: true/false
+ * const kinds = [verboseFlag.kind, enableArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -339,7 +341,7 @@ export declare const boolean: <const Kind extends ParamKind>(kind: Kind, name: s
  *
  * **Example** (Creating integer parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create an integer flag
@@ -349,6 +351,7 @@ export declare const boolean: <const Kind extends ParamKind>(kind: Kind, name: s
  * const countArg = Param.integer(Param.argumentKind, "count")
  *
  * // Usage in CLI: --port 8080 or as positional argument: 42
+ * const kinds = [portFlag.kind, countArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -360,7 +363,7 @@ export declare const integer: <const Kind extends ParamKind>(kind: Kind, name: s
  *
  * **Example** (Creating float parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a float flag
@@ -370,6 +373,7 @@ export declare const integer: <const Kind extends ParamKind>(kind: Kind, name: s
  * const thresholdArg = Param.float(Param.argumentKind, "threshold")
  *
  * // Usage in CLI: --rate 0.95 or as positional argument: 3.14159
+ * const kinds = [rateFlag.kind, thresholdArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -381,7 +385,7 @@ export declare const float: <const Kind extends ParamKind>(kind: Kind, name: str
  *
  * **Example** (Creating date parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a date flag
@@ -392,6 +396,7 @@ export declare const float: <const Kind extends ParamKind>(kind: Kind, name: str
  *
  * // Usage in CLI: --start-date "2023-12-25" or as positional: "2023-01-01"
  * // Parses to JavaScript Date object
+ * const kinds = [startFlag.kind, dueDateArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -404,7 +409,7 @@ export declare const date: <const Kind extends ParamKind>(kind: Kind, name: stri
  *
  * **Example** (Creating valued choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * type Animal = Dog | Cat
@@ -421,6 +426,7 @@ export declare const date: <const Kind extends ParamKind>(kind: Kind, name: stri
  *   ["dog", { _tag: "Dog" }],
  *   ["cat", { _tag: "Cat" }]
  * ])
+ * animal.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -433,7 +439,7 @@ export declare const choiceWithValue: <const Kind extends ParamKind, const Choic
  *
  * **Example** (Creating string choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const logLevel = Param.choice(Param.flagKind, "log-level", [
@@ -442,6 +448,7 @@ export declare const choiceWithValue: <const Kind extends ParamKind, const Choic
  *   "warn",
  *   "error"
  * ])
+ * logLevel.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -453,7 +460,7 @@ export declare const choice: <const Kind extends ParamKind, const Choices extend
  *
  * **Example** (Creating path parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic path parameter
@@ -468,6 +475,7 @@ export declare const choice: <const Kind extends ParamKind, const Choices extend
  *   mustExist: true,
  *   typeName: "config-file"
  * })
+ * const kinds = [outputPath.kind, inputPath.kind, configFile.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category constructors
@@ -488,7 +496,7 @@ export declare const path: <Kind extends ParamKind>(kind: Kind, name: string, op
  *
  * **Example** (Creating directory parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic directory parameter
@@ -498,6 +506,7 @@ export declare const path: <Kind extends ParamKind>(kind: Kind, name: string, op
  * const sourceDir = Param.directory(Param.flagKind, "source", { mustExist: true })
  *
  * // Usage: --output-dir /path/to/dir --source /existing/dir
+ * const kinds = [outputDir.kind, sourceDir.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -516,7 +525,7 @@ export declare const directory: <Kind extends ParamKind>(kind: Kind, name: strin
  *
  * **Example** (Creating file parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic file parameter
@@ -526,6 +535,7 @@ export declare const directory: <Kind extends ParamKind>(kind: Kind, name: strin
  * const inputFile = Param.file(Param.flagKind, "input", { mustExist: true })
  *
  * // Usage: --output result.txt --input existing-file.txt
+ * const kinds = [outputFile.kind, inputFile.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -540,7 +550,7 @@ export declare const file: <Kind extends ParamKind>(kind: Kind, name: string, op
  *
  * **Example** (Creating redacted parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a password parameter
@@ -550,6 +560,7 @@ export declare const file: <Kind extends ParamKind>(kind: Kind, name: string, op
  * const apiKey = Param.redacted(Param.argumentKind, "api-key")
  *
  * // Usage: --password (value will be hidden in help/logs)
+ * const kinds = [password.kind, apiKey.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -561,7 +572,7 @@ export declare const redacted: <Kind extends ParamKind>(kind: Kind, name: string
  *
  * **Example** (Reading file text)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Read a config file as string
@@ -571,6 +582,7 @@ export declare const redacted: <Kind extends ParamKind>(kind: Kind, name: string
  * const templateContent = Param.fileText(Param.argumentKind, "template")
  *
  * // Usage: --config config.txt (reads file content into string)
+ * const kinds = [configContent.kind, templateContent.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -587,7 +599,7 @@ export declare const fileText: <Kind extends ParamKind>(kind: Kind, name: string
  *
  * **Example** (Parsing file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Will use the extension of the file passed on the command line to determine
@@ -598,6 +610,7 @@ export declare const fileText: <Kind extends ParamKind>(kind: Kind, name: string
  * const jsonConfig = Param.fileParse(Param.flagKind, "json-config", {
  *   format: "json"
  * })
+ * const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -609,7 +622,7 @@ export declare const fileParse: <Kind extends ParamKind>(kind: Kind, name: strin
  *
  * **Example** (Validating file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Param } from "effect/unstable/cli"
  * // Parse JSON config file
@@ -628,6 +641,7 @@ export declare const fileParse: <Kind extends ParamKind>(kind: Kind, name: strin
  * })
  *
  * // Usage: --config config.json (reads and validates file content)
+ * const kinds = [config.kind, yamlConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -649,7 +663,7 @@ export declare const fileSchema: <Kind extends ParamKind, A>(kind: Kind, name: s
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const env = Param.keyValuePair(Param.flagKind, "env")
@@ -657,6 +671,7 @@ export declare const fileSchema: <Kind extends ParamKind, A>(kind: Kind, name: s
  *
  * const props = Param.keyValuePair(Param.flagKind, "property")
  * // --property name=value --property debug=true
+ * const kinds = [env.kind, props.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -673,7 +688,7 @@ export declare const keyValuePair: <Kind extends ParamKind>(kind: Kind, name: st
  *
  * **Example** (Creating sentinel parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const disabledDebugParam = Param.none(Param.flagKind)
@@ -681,8 +696,8 @@ export declare const keyValuePair: <Kind extends ParamKind>(kind: Kind, name: st
  * const makeDebugParam = (enableDebug: boolean) =>
  *   enableDebug ? Param.string(Param.flagKind, "debug") : disabledDebugParam
  *
- * console.log(makeDebugParam(true) === disabledDebugParam) // false
- * console.log(makeDebugParam(false) === disabledDebugParam) // true
+ * makeDebugParam(true) === disabledDebugParam // => false
+ * makeDebugParam(false) === disabledDebugParam // => true
  * ```
  *
  * @category constructors
@@ -704,7 +719,7 @@ export declare const none: <Kind extends ParamKind>(kind: Kind) => Param<Kind, n
  *
  * **Example** (Adding parameter aliases)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -717,6 +732,7 @@ export declare const none: <Kind extends ParamKind>(kind: Kind) => Param<Kind, n
  *   Param.optional,
  *   Param.withAlias("-c") // finds the underlying Single and adds alias
  * )
+ * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -738,7 +754,7 @@ export declare const withAlias: {
      *
      * **Example** (Adding parameter aliases)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -751,6 +767,7 @@ export declare const withAlias: {
      *   Param.optional,
      *   Param.withAlias("-c") // finds the underlying Single and adds alias
      * )
+     * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -772,7 +789,7 @@ export declare const withAlias: {
      *
      * **Example** (Adding parameter aliases)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -785,6 +802,7 @@ export declare const withAlias: {
      *   Param.optional,
      *   Param.withAlias("-c") // finds the underlying Single and adds alias
      * )
+     * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -802,13 +820,14 @@ export declare const withAlias: {
  *
  * **Example** (Adding help descriptions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
  *   Param.withAlias("-v"),
  *   Param.withDescription("Enable verbose output")
  * )
+ * verbose.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -825,13 +844,14 @@ export declare const withDescription: {
      *
      * **Example** (Adding help descriptions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
      *   Param.withAlias("-v"),
      *   Param.withDescription("Enable verbose output")
      * )
+     * verbose.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -848,13 +868,14 @@ export declare const withDescription: {
      *
      * **Example** (Adding help descriptions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
      *   Param.withAlias("-v"),
      *   Param.withDescription("Enable verbose output")
      * )
+     * verbose.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -873,12 +894,13 @@ export declare const withDescription: {
  *
  * **Example** (Hiding a flag from help)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const experimental = Param.boolean(Param.flagKind, "experimental-foo").pipe(
  *   Param.withHidden
  * )
+ * experimental.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -890,12 +912,13 @@ export declare const withHidden: <Kind extends ParamKind, A>(self: Param<Kind, A
  *
  * **Example** (Mapping parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const port = Param.integer(Param.flagKind, "port").pipe(
  *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
  * )
+ * port.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -907,12 +930,13 @@ export declare const map: {
      *
      * **Example** (Mapping parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
      *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -924,12 +948,13 @@ export declare const map: {
      *
      * **Example** (Mapping parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
      *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -942,9 +967,27 @@ export declare const map: {
  *
  * **Example** (Mapping parsed values effectfully)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { CliError, Param } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
  *   Param.mapEffect((email) =>
@@ -960,6 +1003,14 @@ export declare const map: {
  *       )
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   validatedEmail.parse({
+ *     arguments: [],
+ *     flags: { email: ["alice@example.com"] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => "alice@example.com"
  * ```
  *
  * @category combinators
@@ -971,9 +1022,27 @@ export declare const mapEffect: {
      *
      * **Example** (Mapping parsed values effectfully)
      *
-     * ```ts
-     * import { Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { CliError, Param } from "effect/unstable/cli"
+     * import { ChildProcessSpawner } from "effect/unstable/process"
+     *
+     * const CliTestLayer = Layer.mergeAll(
+     *   FileSystem.layerNoop({}),
+     *   Path.layer,
+     *   Stdio.layerTest({}),
+     *   Layer.succeed(Terminal.Terminal, Terminal.make({
+     *     columns: Effect.succeed(80),
+     *     rows: Effect.succeed(24),
+     *     readInput: Effect.die("unused"),
+     *     readLine: Effect.die("unused"),
+     *     display: () => Effect.void
+     *   })),
+     *   Layer.succeed(
+     *     ChildProcessSpawner.ChildProcessSpawner,
+     *     ChildProcessSpawner.make(() => Effect.die("unused"))
+     *   )
+     * )
      *
      * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
      *   Param.mapEffect((email) =>
@@ -989,6 +1058,14 @@ export declare const mapEffect: {
      *       )
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   validatedEmail.parse({
+     *     arguments: [],
+     *     flags: { email: ["alice@example.com"] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => "alice@example.com"
      * ```
      *
      * @category combinators
@@ -1000,9 +1077,27 @@ export declare const mapEffect: {
      *
      * **Example** (Mapping parsed values effectfully)
      *
-     * ```ts
-     * import { Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { CliError, Param } from "effect/unstable/cli"
+     * import { ChildProcessSpawner } from "effect/unstable/process"
+     *
+     * const CliTestLayer = Layer.mergeAll(
+     *   FileSystem.layerNoop({}),
+     *   Path.layer,
+     *   Stdio.layerTest({}),
+     *   Layer.succeed(Terminal.Terminal, Terminal.make({
+     *     columns: Effect.succeed(80),
+     *     rows: Effect.succeed(24),
+     *     readInput: Effect.die("unused"),
+     *     readLine: Effect.die("unused"),
+     *     display: () => Effect.void
+     *   })),
+     *   Layer.succeed(
+     *     ChildProcessSpawner.ChildProcessSpawner,
+     *     ChildProcessSpawner.make(() => Effect.die("unused"))
+     *   )
+     * )
      *
      * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
      *   Param.mapEffect((email) =>
@@ -1018,6 +1113,14 @@ export declare const mapEffect: {
      *       )
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   validatedEmail.parse({
+     *     arguments: [],
+     *     flags: { email: ["alice@example.com"] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => "alice@example.com"
      * ```
      *
      * @category combinators
@@ -1031,8 +1134,27 @@ export declare const mapEffect: {
  *
  * **Example** (Mapping thrown errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Param } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * const parsedJson = Param.string(Param.flagKind, "config").pipe(
  *   Param.mapTryCatch(
@@ -1041,6 +1163,14 @@ export declare const mapEffect: {
  *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   parsedJson.parse({
+ *     arguments: [],
+ *     flags: { config: ['{"enabled":true}'] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => { enabled: true }
  * ```
  *
  * @category combinators
@@ -1053,8 +1183,27 @@ export declare const mapTryCatch: {
      *
      * **Example** (Mapping thrown errors)
      *
-     * ```ts
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { Param } from "effect/unstable/cli"
+     * import { ChildProcessSpawner } from "effect/unstable/process"
+     *
+     * const CliTestLayer = Layer.mergeAll(
+     *   FileSystem.layerNoop({}),
+     *   Path.layer,
+     *   Stdio.layerTest({}),
+     *   Layer.succeed(Terminal.Terminal, Terminal.make({
+     *     columns: Effect.succeed(80),
+     *     rows: Effect.succeed(24),
+     *     readInput: Effect.die("unused"),
+     *     readLine: Effect.die("unused"),
+     *     display: () => Effect.void
+     *   })),
+     *   Layer.succeed(
+     *     ChildProcessSpawner.ChildProcessSpawner,
+     *     ChildProcessSpawner.make(() => Effect.die("unused"))
+     *   )
+     * )
      *
      * const parsedJson = Param.string(Param.flagKind, "config").pipe(
      *   Param.mapTryCatch(
@@ -1063,6 +1212,14 @@ export declare const mapTryCatch: {
      *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   parsedJson.parse({
+     *     arguments: [],
+     *     flags: { config: ['{"enabled":true}'] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => { enabled: true }
      * ```
      *
      * @category combinators
@@ -1075,8 +1232,27 @@ export declare const mapTryCatch: {
      *
      * **Example** (Mapping thrown errors)
      *
-     * ```ts
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { Param } from "effect/unstable/cli"
+     * import { ChildProcessSpawner } from "effect/unstable/process"
+     *
+     * const CliTestLayer = Layer.mergeAll(
+     *   FileSystem.layerNoop({}),
+     *   Path.layer,
+     *   Stdio.layerTest({}),
+     *   Layer.succeed(Terminal.Terminal, Terminal.make({
+     *     columns: Effect.succeed(80),
+     *     rows: Effect.succeed(24),
+     *     readInput: Effect.die("unused"),
+     *     readLine: Effect.die("unused"),
+     *     display: () => Effect.void
+     *   })),
+     *   Layer.succeed(
+     *     ChildProcessSpawner.ChildProcessSpawner,
+     *     ChildProcessSpawner.make(() => Effect.die("unused"))
+     *   )
+     * )
      *
      * const parsedJson = Param.string(Param.flagKind, "config").pipe(
      *   Param.mapTryCatch(
@@ -1085,6 +1261,14 @@ export declare const mapTryCatch: {
      *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   parsedJson.parse({
+     *     arguments: [],
+     *     flags: { config: ['{"enabled":true}'] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => { enabled: true }
      * ```
      *
      * @category combinators
@@ -1103,13 +1287,14 @@ export declare const mapTryCatch: {
  *
  * **Example** (Making parameters optional)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create an optional port option
  * // - When not provided: returns Option.none()
  * // - When provided: returns Option.some(parsedValue)
  * const port = Param.optional(Param.integer(Param.flagKind, "port"))
+ * port.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1126,7 +1311,7 @@ export declare const optional: <Kind extends ParamKind, A>(param: Param<Kind, A>
  *
  * **Example** (Providing default values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Using the pipe operator to make an option optional
@@ -1140,6 +1325,7 @@ export declare const optional: <Kind extends ParamKind, A>(param: Param<Kind, A>
  *   Param.withDescription("Enable verbose output"),
  *   Param.withDefault(false)
  * )
+ * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1156,7 +1342,7 @@ export declare const withDefault: {
      *
      * **Example** (Providing default values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Using the pipe operator to make an option optional
@@ -1170,6 +1356,7 @@ export declare const withDefault: {
      *   Param.withDescription("Enable verbose output"),
      *   Param.withDefault(false)
      * )
+     * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1186,7 +1373,7 @@ export declare const withDefault: {
      *
      * **Example** (Providing default values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Using the pipe operator to make an option optional
@@ -1200,6 +1387,7 @@ export declare const withDefault: {
      *   Param.withDescription("Enable verbose output"),
      *   Param.withDefault(false)
      * )
+     * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1389,7 +1577,7 @@ export type VariadicParamOptions = {
  *
  * **Example** (Accepting multiple values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic variadic parameter (0 to infinity)
@@ -1406,6 +1594,7 @@ export type VariadicParamOptions = {
  *   min: 2, // at least 2 times
  *   max: 2 // at most 2 times
  * })
+ * const kinds = [tags.kind, inputs.kind, limited.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1422,7 +1611,7 @@ export declare const variadic: <Kind extends ParamKind, A>(self: Param<Kind, A>,
  *
  * **Example** (Bounding repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow 1-3 file inputs
@@ -1441,6 +1630,7 @@ export declare const variadic: <Kind extends ParamKind, A>(self: Param<Kind, A>,
  *
  * // Parse: --tag dev --tag staging --tag v1.0
  * // Result: ["dev", "staging", "v1.0"]
+ * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1457,7 +1647,7 @@ export declare const between: {
      *
      * **Example** (Bounding repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow 1-3 file inputs
@@ -1476,6 +1666,7 @@ export declare const between: {
      *
      * // Parse: --tag dev --tag staging --tag v1.0
      * // Result: ["dev", "staging", "v1.0"]
+     * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1492,7 +1683,7 @@ export declare const between: {
      *
      * **Example** (Bounding repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow 1-3 file inputs
@@ -1511,6 +1702,7 @@ export declare const between: {
      *
      * // Parse: --tag dev --tag staging --tag v1.0
      * // Result: ["dev", "staging", "v1.0"]
+     * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1528,7 +1720,7 @@ export declare const between: {
  *
  * **Example** (Limiting repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow at most 3 warning suppressions
@@ -1538,6 +1730,7 @@ export declare const between: {
  *
  * // Parse: --suppress warning1 --suppress warning2
  * // Result: ["warning1", "warning2"]
+ * suppressions.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1554,7 +1747,7 @@ export declare const atMost: {
      *
      * **Example** (Limiting repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow at most 3 warning suppressions
@@ -1564,6 +1757,7 @@ export declare const atMost: {
      *
      * // Parse: --suppress warning1 --suppress warning2
      * // Result: ["warning1", "warning2"]
+     * suppressions.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1580,7 +1774,7 @@ export declare const atMost: {
      *
      * **Example** (Limiting repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow at most 3 warning suppressions
@@ -1590,6 +1784,7 @@ export declare const atMost: {
      *
      * // Parse: --suppress warning1 --suppress warning2
      * // Result: ["warning1", "warning2"]
+     * suppressions.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1607,7 +1802,7 @@ export declare const atMost: {
  *
  * **Example** (Requiring repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Require at least 2 input files
@@ -1618,6 +1813,7 @@ export declare const atMost: {
  *
  * // Parse: --input file1.txt --input file2.txt --input file3.txt
  * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+ * inputs.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1634,7 +1830,7 @@ export declare const atLeast: {
      *
      * **Example** (Requiring repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Require at least 2 input files
@@ -1645,6 +1841,7 @@ export declare const atLeast: {
      *
      * // Parse: --input file1.txt --input file2.txt --input file3.txt
      * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+     * inputs.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1661,7 +1858,7 @@ export declare const atLeast: {
      *
      * **Example** (Requiring repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Require at least 2 input files
@@ -1672,6 +1869,7 @@ export declare const atLeast: {
      *
      * // Parse: --input file1.txt --input file2.txt --input file3.txt
      * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+     * inputs.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1690,7 +1888,7 @@ export declare const atLeast: {
  *
  * **Example** (Filtering and transforming values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Option } from "effect"
  * import { Param } from "effect/unstable/cli"
  * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1699,6 +1897,7 @@ export declare const atLeast: {
  *     (n) => `Expected positive integer, got ${n}`
  *   )
  * )
+ * positiveInt.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1716,7 +1915,7 @@ export declare const filterMap: {
      *
      * **Example** (Filtering and transforming values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Option } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1725,6 +1924,7 @@ export declare const filterMap: {
      *     (n) => `Expected positive integer, got ${n}`
      *   )
      * )
+     * positiveInt.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1742,7 +1942,7 @@ export declare const filterMap: {
      *
      * **Example** (Filtering and transforming values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Option } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1751,6 +1951,7 @@ export declare const filterMap: {
      *     (n) => `Expected positive integer, got ${n}`
      *   )
      * )
+     * positiveInt.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1763,7 +1964,7 @@ export declare const filterMap: {
  *
  * **Example** (Filtering parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
@@ -1772,6 +1973,7 @@ export declare const filterMap: {
  *     (n) => `Expected even number, got ${n}`
  *   )
  * )
+ * evenNumber.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1783,7 +1985,7 @@ export declare const filter: {
      *
      * **Example** (Filtering parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
@@ -1792,6 +1994,7 @@ export declare const filter: {
      *     (n) => `Expected even number, got ${n}`
      *   )
      * )
+     * evenNumber.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1803,7 +2006,7 @@ export declare const filter: {
      *
      * **Example** (Filtering parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
@@ -1812,6 +2015,7 @@ export declare const filter: {
      *     (n) => `Expected even number, got ${n}`
      *   )
      * )
+     * evenNumber.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1829,7 +2033,7 @@ export declare const filter: {
  *
  * **Example** (Setting metavars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -1839,6 +2043,7 @@ export declare const filter: {
  *     () => "Port must be between 1 and 65535"
  *   )
  * )
+ * port.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -1855,7 +2060,7 @@ export declare const withMetavar: {
      *
      * **Example** (Setting metavars)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -1865,6 +2070,7 @@ export declare const withMetavar: {
      *     () => "Port must be between 1 and 65535"
      *   )
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category metadata
@@ -1881,7 +2087,7 @@ export declare const withMetavar: {
      *
      * **Example** (Setting metavars)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -1891,6 +2097,7 @@ export declare const withMetavar: {
      *     () => "Port must be between 1 and 65535"
      *   )
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category metadata
@@ -1903,7 +2110,7 @@ export declare const withMetavar: {
  *
  * **Example** (Validating with schemas)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Param } from "effect/unstable/cli"
  * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -1915,6 +2122,7 @@ export declare const withMetavar: {
  * const email = Param.string(Param.flagKind, "email").pipe(
  *   Param.withSchema(Email)
  * )
+ * email.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1926,7 +2134,7 @@ export declare const withSchema: {
      *
      * **Example** (Validating with schemas)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Schema } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -1938,6 +2146,7 @@ export declare const withSchema: {
      * const email = Param.string(Param.flagKind, "email").pipe(
      *   Param.withSchema(Email)
      * )
+     * email.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1949,7 +2158,7 @@ export declare const withSchema: {
      *
      * **Example** (Validating with schemas)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Schema } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -1961,6 +2170,7 @@ export declare const withSchema: {
      * const email = Param.string(Param.flagKind, "email").pipe(
      *   Param.withSchema(Email)
      * )
+     * email.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1973,12 +2183,13 @@ export declare const withSchema: {
  *
  * **Example** (Falling back to another parameter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const config = Param.file(Param.flagKind, "config").pipe(
  *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
  * )
+ * config.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1990,35 +2201,37 @@ export declare const orElse: {
      *
      * **Example** (Falling back to another parameter)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const config = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
      * )
+     * config.kind // => "flag"
      * ```
      *
      * @category combinators
      * @since 4.0.0
      */
-    <B, Kind extends ParamKind>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>;
+    <B, Kind extends ParamKind>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>;
     /**
      * Provides a fallback param to use if this param fails to parse.
      *
      * **Example** (Falling back to another parameter)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const config = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
      * )
+     * config.kind // => "flag"
      * ```
      *
      * @category combinators
      * @since 4.0.0
      */
-    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, A | B>;
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, A | B>;
 };
 /**
  * Provides a fallback param and returns a `Result` indicating which param
@@ -2031,13 +2244,14 @@ export declare const orElse: {
  *
  * **Example** (Returning fallback results)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const configSource = Param.file(Param.flagKind, "config").pipe(
  *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
  * )
  * // Returns Result<string, string>
+ * configSource.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2055,19 +2269,20 @@ export declare const orElseResult: {
      *
      * **Example** (Returning fallback results)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const configSource = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
      * )
      * // Returns Result<string, string>
+     * configSource.kind // => "flag"
      * ```
      *
      * @category combinators
      * @since 4.0.0
      */
-    <Kind extends ParamKind, B>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>;
+    <Kind extends ParamKind, B>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>;
     /**
      * Provides a fallback param and returns a `Result` indicating which param
      * succeeded.
@@ -2079,19 +2294,20 @@ export declare const orElseResult: {
      *
      * **Example** (Returning fallback results)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const configSource = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
      * )
      * // Returns Result<string, string>
+     * configSource.kind // => "flag"
      * ```
      *
      * @category combinators
      * @since 4.0.0
      */
-    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, Result.Result<A, B>>;
+    <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, Result.Result<A, B>>;
 };
 export {};
 //# sourceMappingURL=Param.d.ts.map