effect 4.0.0-beta.102 → 4.0.0-beta.104

package/src/unstable/cli/Param.ts

@@ -12,7 +12,7 @@
  */
 import * as Config from "../../Config.ts"
 import * as Effect from "../../Effect.ts"
-import { dual, identity } from "../../Function.ts"
+import { dual, identity, type LazyArg } from "../../Function.ts"
 import * as Option from "../../Option.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
@@ -226,7 +226,11 @@ 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>
 }
 
 /**
@@ -272,17 +276,15 @@ const Proto = {
  *
  * **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 const isParam = (u: unknown): u is Param<any, ParamKind> => Predicate.hasProperty(u, TypeId)
@@ -292,17 +294,17 @@ export const isParam = (u: unknown): u is Param<any, ParamKind> => Predicate.has
  *
  * **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 const isSingle = <const Kind extends ParamKind, A>(
@@ -358,7 +360,7 @@ export 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
@@ -368,6 +370,7 @@ export 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
@@ -388,7 +391,7 @@ export const string = <const Kind extends ParamKind>(
  *
  * **Example** (Creating boolean parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a boolean flag
@@ -399,6 +402,7 @@ export const string = <const Kind extends ParamKind>(
  *
  * // 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
@@ -419,7 +423,7 @@ export const boolean = <const Kind extends ParamKind>(
  *
  * **Example** (Creating integer parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create an integer flag
@@ -429,6 +433,7 @@ export const boolean = <const Kind extends ParamKind>(
  * 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
@@ -449,7 +454,7 @@ export const integer = <const Kind extends ParamKind>(
  *
  * **Example** (Creating float parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a float flag
@@ -459,6 +464,7 @@ export const integer = <const Kind extends ParamKind>(
  * 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
@@ -479,7 +485,7 @@ export const float = <const Kind extends ParamKind>(
  *
  * **Example** (Creating date parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a date flag
@@ -490,6 +496,7 @@ export const float = <const Kind extends ParamKind>(
  *
  * // 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
@@ -511,7 +518,7 @@ export const date = <const Kind extends ParamKind>(
  *
  * **Example** (Creating valued choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * type Animal = Dog | Cat
@@ -528,6 +535,7 @@ export const date = <const Kind extends ParamKind>(
  *   ["dog", { _tag: "Dog" }],
  *   ["cat", { _tag: "Cat" }]
  * ])
+ * animal.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -549,7 +557,7 @@ export const choiceWithValue = <
  *
  * **Example** (Creating string choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const logLevel = Param.choice(Param.flagKind, "log-level", [
@@ -558,6 +566,7 @@ export const choiceWithValue = <
  *   "warn",
  *   "error"
  * ])
+ * logLevel.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -576,7 +585,7 @@ export const choice = <
  *
  * **Example** (Creating path parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic path parameter
@@ -591,6 +600,7 @@ export const choice = <
  *   mustExist: true,
  *   typeName: "config-file"
  * })
+ * const kinds = [outputPath.kind, inputPath.kind, configFile.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category constructors
@@ -622,7 +632,7 @@ export const path = <Kind extends ParamKind>(
  *
  * **Example** (Creating directory parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic directory parameter
@@ -632,6 +642,7 @@ export const path = <Kind extends ParamKind>(
  * 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
@@ -660,7 +671,7 @@ export const directory = <Kind extends ParamKind>(
  *
  * **Example** (Creating file parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic file parameter
@@ -670,6 +681,7 @@ export const directory = <Kind extends ParamKind>(
  * 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
@@ -694,7 +706,7 @@ export const file = <Kind extends ParamKind>(
  *
  * **Example** (Creating redacted parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a password parameter
@@ -704,6 +716,7 @@ export const file = <Kind extends ParamKind>(
  * 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
@@ -724,7 +737,7 @@ export const redacted = <Kind extends ParamKind>(
  *
  * **Example** (Reading file text)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Read a config file as string
@@ -734,6 +747,7 @@ export const redacted = <Kind extends ParamKind>(
  * 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
@@ -756,7 +770,7 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
  *
  * **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
@@ -767,6 +781,7 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
  * const jsonConfig = Param.fileParse(Param.flagKind, "json-config", {
  *   format: "json"
  * })
+ * const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -788,7 +803,7 @@ export const fileParse = <Kind extends ParamKind>(
  *
  * **Example** (Validating file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Param } from "effect/unstable/cli"
  * // Parse JSON config file
@@ -807,6 +822,7 @@ export const fileParse = <Kind extends ParamKind>(
  * })
  *
  * // Usage: --config config.json (reads and validates file content)
+ * const kinds = [config.kind, yamlConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -839,7 +855,7 @@ export const fileSchema = <Kind extends ParamKind, A>(
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const env = Param.keyValuePair(Param.flagKind, "env")
@@ -847,6 +863,7 @@ export const fileSchema = <Kind extends ParamKind, A>(
  *
  * const props = Param.keyValuePair(Param.flagKind, "property")
  * // --property name=value --property debug=true
+ * const kinds = [env.kind, props.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -878,7 +895,7 @@ export const keyValuePair = <Kind extends ParamKind>(
  *
  * **Example** (Creating sentinel parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const disabledDebugParam = Param.none(Param.flagKind)
@@ -886,8 +903,8 @@ export const keyValuePair = <Kind extends ParamKind>(
  * 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
@@ -917,7 +934,7 @@ const FLAG_DASH_REGEXP = /^-+/
  *
  * **Example** (Adding parameter aliases)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -930,6 +947,7 @@ const FLAG_DASH_REGEXP = /^-+/
  *   Param.optional,
  *   Param.withAlias("-c") // finds the underlying Single and adds alias
  * )
+ * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -951,7 +969,7 @@ export 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(
@@ -964,6 +982,7 @@ export const withAlias: {
    *   Param.optional,
    *   Param.withAlias("-c") // finds the underlying Single and adds alias
    * )
+   * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -985,7 +1004,7 @@ export 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(
@@ -998,6 +1017,7 @@ export const withAlias: {
    *   Param.optional,
    *   Param.withAlias("-c") // finds the underlying Single and adds alias
    * )
+   * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -1022,13 +1042,14 @@ export 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
@@ -1045,13 +1066,14 @@ export 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
@@ -1068,13 +1090,14 @@ export 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
@@ -1100,12 +1123,13 @@ export 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
@@ -1123,12 +1147,13 @@ export const withHidden = <Kind extends ParamKind, A>(self: Param<Kind, A>): Par
  *
  * **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
@@ -1140,12 +1165,13 @@ export 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
@@ -1157,12 +1183,13 @@ export 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
@@ -1186,24 +1213,49 @@ export const map: {
 
 const transform = <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  f: (parse: Parse<A>) => Parse<B>
-) =>
-  Object.assign(Object.create(Proto), {
+  f: (
+    parse: Parse<A>,
+    alternatives: ReadonlyArray<LazyArg<Parse<unknown>>>
+  ) => Parse<B>,
+  alternatives: ReadonlyArray<LazyArg<Param<Kind, unknown>>> = []
+): Transform<Kind, A, B> => {
+  const alternativeParsers = alternatives.map((alternative) => () => alternative().parse)
+  return Object.assign(Object.create(Proto), {
     _tag: "Transform",
     kind: self.kind,
     param: self,
+    alternatives,
     f,
-    parse: f(self.parse)
+    parse: f(self.parse, alternativeParsers)
   })
+}
 
 /**
  * Transforms the parsed value of an option using an effectful mapping function.
  *
  * **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) =>
@@ -1219,6 +1271,14 @@ const transform = <Kind extends ParamKind, A, B>(
  *       )
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   validatedEmail.parse({
+ *     arguments: [],
+ *     flags: { email: ["alice@example.com"] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => "alice@example.com"
  * ```
  *
  * @category combinators
@@ -1230,9 +1290,27 @@ export 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) =>
@@ -1248,6 +1326,14 @@ export 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
@@ -1259,9 +1345,27 @@ export 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) =>
@@ -1277,6 +1381,14 @@ export 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
@@ -1305,8 +1417,27 @@ export 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(
@@ -1315,6 +1446,14 @@ export 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
@@ -1327,8 +1466,27 @@ export 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(
@@ -1337,6 +1495,14 @@ export 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
@@ -1349,8 +1515,27 @@ export 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(
@@ -1359,6 +1544,14 @@ export 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
@@ -1405,13 +1598,14 @@ export 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
@@ -1461,7 +1655,7 @@ export const optional = <Kind extends ParamKind, 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
@@ -1475,6 +1669,7 @@ export const optional = <Kind extends ParamKind, A>(
  *   Param.withDescription("Enable verbose output"),
  *   Param.withDefault(false)
  * )
+ * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1491,7 +1686,7 @@ export 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
@@ -1505,6 +1700,7 @@ export const withDefault: {
    *   Param.withDescription("Enable verbose output"),
    *   Param.withDefault(false)
    * )
+   * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -1521,7 +1717,7 @@ export 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
@@ -1535,6 +1731,7 @@ export const withDefault: {
    *   Param.withDescription("Enable verbose output"),
    *   Param.withDefault(false)
    * )
+   * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -1790,7 +1987,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)
@@ -1807,6 +2004,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
@@ -1844,7 +2042,7 @@ export const variadic = <Kind extends ParamKind, A>(
  *
  * **Example** (Bounding repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow 1-3 file inputs
@@ -1863,6 +2061,7 @@ export const variadic = <Kind extends ParamKind, A>(
  *
  * // Parse: --tag dev --tag staging --tag v1.0
  * // Result: ["dev", "staging", "v1.0"]
+ * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1879,7 +2078,7 @@ export const between: {
    *
    * **Example** (Bounding repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow 1-3 file inputs
@@ -1898,6 +2097,7 @@ export 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
@@ -1914,7 +2114,7 @@ export const between: {
    *
    * **Example** (Bounding repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow 1-3 file inputs
@@ -1933,6 +2133,7 @@ export 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
@@ -1960,7 +2161,7 @@ export const between: {
  *
  * **Example** (Limiting repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow at most 3 warning suppressions
@@ -1970,6 +2171,7 @@ export const between: {
  *
  * // Parse: --suppress warning1 --suppress warning2
  * // Result: ["warning1", "warning2"]
+ * suppressions.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1986,7 +2188,7 @@ export const atMost: {
    *
    * **Example** (Limiting repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow at most 3 warning suppressions
@@ -1996,6 +2198,7 @@ export const atMost: {
    *
    * // Parse: --suppress warning1 --suppress warning2
    * // Result: ["warning1", "warning2"]
+   * suppressions.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2012,7 +2215,7 @@ export const atMost: {
    *
    * **Example** (Limiting repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow at most 3 warning suppressions
@@ -2022,6 +2225,7 @@ export const atMost: {
    *
    * // Parse: --suppress warning1 --suppress warning2
    * // Result: ["warning1", "warning2"]
+   * suppressions.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2045,7 +2249,7 @@ export const atMost: {
  *
  * **Example** (Requiring repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Require at least 2 input files
@@ -2056,6 +2260,7 @@ export const atMost: {
  *
  * // Parse: --input file1.txt --input file2.txt --input file3.txt
  * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+ * inputs.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2072,7 +2277,7 @@ export const atLeast: {
    *
    * **Example** (Requiring repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Require at least 2 input files
@@ -2083,6 +2288,7 @@ export const atLeast: {
    *
    * // Parse: --input file1.txt --input file2.txt --input file3.txt
    * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+   * inputs.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2099,7 +2305,7 @@ export const atLeast: {
    *
    * **Example** (Requiring repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Require at least 2 input files
@@ -2110,6 +2316,7 @@ export const atLeast: {
    *
    * // Parse: --input file1.txt --input file2.txt --input file3.txt
    * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+   * inputs.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2134,7 +2341,7 @@ export 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(
@@ -2143,6 +2350,7 @@ export const atLeast: {
  *     (n) => `Expected positive integer, got ${n}`
  *   )
  * )
+ * positiveInt.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2160,7 +2368,7 @@ export 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(
@@ -2169,6 +2377,7 @@ export const filterMap: {
    *     (n) => `Expected positive integer, got ${n}`
    *   )
    * )
+   * positiveInt.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2186,7 +2395,7 @@ export 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(
@@ -2195,6 +2404,7 @@ export const filterMap: {
    *     (n) => `Expected positive integer, got ${n}`
    *   )
    * )
+   * positiveInt.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2232,7 +2442,7 @@ export 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(
@@ -2241,6 +2451,7 @@ export const filterMap: {
  *     (n) => `Expected even number, got ${n}`
  *   )
  * )
+ * evenNumber.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2252,7 +2463,7 @@ export 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(
@@ -2261,6 +2472,7 @@ export const filter: {
    *     (n) => `Expected even number, got ${n}`
    *   )
    * )
+   * evenNumber.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2272,7 +2484,7 @@ export 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(
@@ -2281,6 +2493,7 @@ export const filter: {
    *     (n) => `Expected even number, got ${n}`
    *   )
    * )
+   * evenNumber.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2307,7 +2520,7 @@ export const filter: {
  *
  * **Example** (Setting metavars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -2317,6 +2530,7 @@ export const filter: {
  *     () => "Port must be between 1 and 65535"
  *   )
  * )
+ * port.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -2333,7 +2547,7 @@ export const withMetavar: {
    *
    * **Example** (Setting metavars)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -2343,6 +2557,7 @@ export const withMetavar: {
    *     () => "Port must be between 1 and 65535"
    *   )
    * )
+   * port.kind // => "flag"
    * ```
    *
    * @category metadata
@@ -2359,7 +2574,7 @@ export const withMetavar: {
    *
    * **Example** (Setting metavars)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -2369,6 +2584,7 @@ export const withMetavar: {
    *     () => "Port must be between 1 and 65535"
    *   )
    * )
+   * port.kind // => "flag"
    * ```
    *
    * @category metadata
@@ -2390,7 +2606,7 @@ export 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@]+$/)
@@ -2402,6 +2618,7 @@ export const withMetavar: {
  * const email = Param.string(Param.flagKind, "email").pipe(
  *   Param.withSchema(Email)
  * )
+ * email.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2413,7 +2630,7 @@ export 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@]+$/)
@@ -2425,6 +2642,7 @@ export const withSchema: {
    * const email = Param.string(Param.flagKind, "email").pipe(
    *   Param.withSchema(Email)
    * )
+   * email.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2438,7 +2656,7 @@ export 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@]+$/)
@@ -2450,6 +2668,7 @@ export const withSchema: {
    * const email = Param.string(Param.flagKind, "email").pipe(
    *   Param.withSchema(Email)
    * )
+   * email.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2481,12 +2700,13 @@ export 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
@@ -2498,42 +2718,46 @@ export 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>
 } = dual(2, <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  orElse: (error: CliError.CliError) => Param<Kind, B>
+  orElse: LazyArg<Param<Kind, B>>
 ) =>
   transform(
     self,
-    (parse: Parse<A>): Parse<A | B> => (args: ParsedArgs) => Effect.catch(parse(args), (err) => orElse(err).parse(args))
+    (parse: Parse<A>, alternatives): Parse<A | B> => (args: ParsedArgs) =>
+      Effect.catch(parse(args), () => (alternatives[0]!() as Parse<B>)(args)),
+    [orElse]
   ))
 
 /**
@@ -2547,13 +2771,14 @@ export 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
@@ -2571,19 +2796,20 @@ export 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.
@@ -2595,34 +2821,36 @@ export 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>>
 } = dual(2, <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  orElse: (error: CliError.CliError) => Param<Kind, B>
+  orElse: LazyArg<Param<Kind, B>>
 ) => {
   return transform(
     self,
-    (parse: Parse<A>): Parse<Result.Result<A, B>> => (args: ParsedArgs) =>
+    (parse: Parse<A>, alternatives): Parse<Result.Result<A, B>> => (args: ParsedArgs) =>
       Effect.catch(
         Effect.map(parse(args), ([leftover, value]) => [leftover, Result.succeed(value)] as const),
-        (err) =>
+        () =>
           Effect.map(
-            orElse(err).parse(args),
+            (alternatives[0]!() as Parse<B>)(args),
             ([leftover, value]) => [leftover, Result.fail(value)] as const
           )
-      )
+      ),
+    [orElse]
   )
 })
 
@@ -2839,7 +3067,12 @@ const transformSingle = <Kind extends ParamKind, A>(
   return matchParam(param, {
     Single: (single) => f(single),
     Map: (mapped) => map(transformSingle(mapped.param, f), mapped.f),
-    Transform: (mapped) => transform(transformSingle(mapped.param, f), mapped.f),
+    Transform: (mapped) =>
+      transform(
+        transformSingle(mapped.param, f),
+        mapped.f,
+        mapped.alternatives.map((alternative) => () => transformSingle(alternative(), f))
+      ),
     Optional: (p) => optional(transformSingle(p.param, f)) as Param<Kind, A>,
     Variadic: (p) =>
       variadic(transformSingle(p.param, f), {
@@ -2861,7 +3094,10 @@ export const extractSingleParams = <Kind extends ParamKind, A>(
   return matchParam(param, {
     Single: (single) => [single as Single<Kind, unknown>],
     Map: (mapped) => extractSingleParams(mapped.param),
-    Transform: (mapped) => extractSingleParams(mapped.param),
+    Transform: (mapped) => [
+      ...extractSingleParams(mapped.param),
+      ...mapped.alternatives.flatMap((alternative) => extractSingleParams(alternative()))
+    ],
     Optional: (optional) => extractSingleParams(optional.param),
     Variadic: (variadic) => extractSingleParams(variadic.param)
   })