effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/unstable/cli/Param.js

@@ -1,13 +1,30 @@
 /**
+ * The `Param` module defines the shared parser tree used by the unstable CLI
+ * `Argument` and `Flag` modules. A `Param<Kind, A>` describes how to consume
+ * either positional arguments or named flags from parsed command-line input and
+ * return a typed value.
+ *
+ * **Common tasks**
+ *
+ * - Build primitive CLI inputs such as strings, booleans, numbers, choices,
+ *   paths, files, and redacted values
+ * - Attach help metadata with aliases and descriptions
+ * - Transform parsed values with pure or effectful validation
+ * - Model missing inputs with `Option`, defaults, config fallbacks, or prompts
+ * - Accept repeated inputs with variadic, bounded, and non-empty parameters
+ *
+ * **Gotchas**
+ *
+ * - The `Kind` type parameter (`"argument"` or `"flag"`) keeps positional
+ *   arguments and flags separate while allowing the implementation and
+ *   combinators to be shared.
+ * - Combinators preserve the parameter kind, so an argument parameter cannot be
+ *   accidentally composed into a flag parameter or the reverse.
+ * - Parsers return both the remaining positional arguments and the parsed
+ *   value; this is important for argument ordering and variadic parameters.
+ * - Some parsers require CLI services such as filesystem, path, terminal, or
+ *   child-process support through the parsing environment.
  * @internal
- *
- * Param is the polymorphic implementation shared by Argument.ts and Flag.ts.
- * The `Kind` type parameter ("argument" | "flag") enables type-safe separation
- * while sharing parsing logic and combinators.
- *
- * Users should import from `Argument` and `Flag` modules, not this module directly.
- * This module is not exported from the public API.
- *
  * @since 4.0.0
  */
 import * as Config from "../../Config.js";
@@ -25,15 +42,15 @@ const TypeId = "~effect/cli/Param";
 /**
  * Kind discriminator for positional argument parameters.
  *
- * @since 4.0.0
  * @category constants
+ * @since 4.0.0
  */
 export const argumentKind = "argument";
 /**
  * Kind discriminator for flag parameters.
  *
- * @since 4.0.0
  * @category constants
+ * @since 4.0.0
  */
 export const flagKind = "flag";
 const Proto = {
@@ -47,7 +64,8 @@ const Proto = {
 /**
  * Type guard to check if a value is a Param.
  *
- * @example
+ * **Example** (Checking for params)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -60,14 +78,15 @@ const Proto = {
  * }
  * ```
  *
- * @since 4.0.0
  * @category refinements
+ * @since 4.0.0
  */
 export const isParam = u => Predicate.hasProperty(u, TypeId);
 /**
  * Type guard to check if a param is a Single param (not composed).
  *
- * @example
+ * **Example** (Checking for single params)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -80,8 +99,8 @@ export const isParam = u => Predicate.hasProperty(u, TypeId);
  * console.log(Param.isSingle(optionalParam)) // false
  * ```
  *
- * @since 4.0.0
  * @category refinements
+ * @since 4.0.0
  */
 export const isSingle = param => Predicate.isTagged(param, "Single");
 /**
@@ -91,8 +110,14 @@ export const isSingle = param => Predicate.isTagged(param, "Single");
  */
 export const isFlagParam = single => single.kind === "flag";
 /**
- * @since 4.0.0
+ * Constructs a leaf `Single` parameter from its kind, name, primitive parser,
+ * and optional help metadata.
+ *
+ * The returned parser reads either one positional argument or the named flag,
+ * depending on `kind`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeSingle = params => {
   const parse = args => params.kind === argumentKind ? parsePositional(params.name, params.primitiveType, args) : parseFlag(params.name, params.primitiveType, args);
@@ -107,7 +132,8 @@ export const makeSingle = params => {
 /**
  * Creates a string parameter.
  *
- * @example
+ * **Example** (Creating string parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -122,8 +148,8 @@ export const makeSingle = params => {
  * // Usage in CLI: --name "John Doe" or as positional argument
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const string = (kind, name) => makeSingle({
   name,
@@ -133,7 +159,8 @@ export const string = (kind, name) => makeSingle({
 /**
  * Creates a boolean parameter.
  *
- * @example
+ * **Example** (Creating boolean parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -149,8 +176,8 @@ export const string = (kind, name) => makeSingle({
  * // or as positional: true/false
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const boolean = (kind, name) => makeSingle({
   name,
@@ -160,7 +187,8 @@ export const boolean = (kind, name) => makeSingle({
 /**
  * Creates an integer parameter.
  *
- * @example
+ * **Example** (Creating integer parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -175,8 +203,8 @@ export const boolean = (kind, name) => makeSingle({
  * // Usage in CLI: --port 8080 or as positional argument: 42
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const integer = (kind, name) => makeSingle({
   name,
@@ -186,7 +214,8 @@ export const integer = (kind, name) => makeSingle({
 /**
  * Creates a floating-point number parameter.
  *
- * @example
+ * **Example** (Creating float parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -201,8 +230,8 @@ export const integer = (kind, name) => makeSingle({
  * // Usage in CLI: --rate 0.95 or as positional argument: 3.14159
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const float = (kind, name) => makeSingle({
   name,
@@ -212,7 +241,8 @@ export const float = (kind, name) => makeSingle({
 /**
  * Creates a date parameter that parses ISO date strings.
  *
- * @example
+ * **Example** (Creating date parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -228,8 +258,8 @@ export const float = (kind, name) => makeSingle({
  * // Parses to JavaScript Date object
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const date = (kind, name) => makeSingle({
   name,
@@ -240,7 +270,8 @@ export const date = (kind, name) => makeSingle({
  * Constructs command-line params that represent a choice between several
  * inputs. The input will be mapped to it's associated value during parsing.
  *
- * @example
+ * **Example** (Creating valued choices)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -262,8 +293,8 @@ export const date = (kind, name) => makeSingle({
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choiceWithValue = (kind, name, choices) => makeSingle({
   name,
@@ -274,7 +305,8 @@ export const choiceWithValue = (kind, name, choices) => makeSingle({
  * Constructs command-line params that represent a choice between several
  * string inputs.
  *
- * @example
+ * **Example** (Creating string choices)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -288,8 +320,8 @@ export const choiceWithValue = (kind, name, choices) => makeSingle({
  * ])
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const choice = (kind, name, choices) => {
   const mappedChoices = choices.map(value => [value, value]);
@@ -298,7 +330,8 @@ export const choice = (kind, name, choices) => {
 /**
  * Creates a path parameter that accepts file or directory paths.
  *
- * @example
+ * **Example** (Creating path parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -318,8 +351,8 @@ export const choice = (kind, name, choices) => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const path = (kind, name, options) => makeSingle({
   name,
@@ -333,7 +366,8 @@ export const path = (kind, name, options) => makeSingle({
  * This is a convenience function that creates a path parameter with the
  * `pathType` set to `"directory"` and a default type name of `"directory"`.
  *
- * @example
+ * **Example** (Creating directory parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -348,8 +382,8 @@ export const path = (kind, name, options) => makeSingle({
  * // Usage: --output-dir /path/to/dir --source /existing/dir
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const directory = (kind, name, options) => path(kind, name, {
   pathType: "directory",
@@ -362,7 +396,8 @@ export const directory = (kind, name, options) => path(kind, name, {
  * This is a convenience function that creates a path parameter with a
  * `pathType` set to `"file"` and a default type name of `"file"`.
  *
- * @example
+ * **Example** (Creating file parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -377,8 +412,8 @@ export const directory = (kind, name, options) => path(kind, name, {
  * // Usage: --output result.txt --input existing-file.txt
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const file = (kind, name, options) => path(kind, name, {
   pathType: "file",
@@ -389,7 +424,8 @@ export const file = (kind, name, options) => path(kind, name, {
  * Creates a redacted parameter for sensitive data like passwords.
  * The value is masked in help output and logging.
  *
- * @example
+ * **Example** (Creating redacted parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -404,8 +440,8 @@ export const file = (kind, name, options) => path(kind, name, {
  * // Usage: --password (value will be hidden in help/logs)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const redacted = (kind, name) => makeSingle({
   name,
@@ -415,7 +451,8 @@ export const redacted = (kind, name) => makeSingle({
 /**
  * Creates a parameter that reads and returns file content as a string.
  *
- * @example
+ * **Example** (Reading file text)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -430,8 +467,8 @@ export const redacted = (kind, name) => makeSingle({
  * // Usage: --config config.txt (reads file content into string)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileText = (kind, name) => makeSingle({
   name,
@@ -444,7 +481,8 @@ export const fileText = (kind, name) => makeSingle({
  * The parser that is utilized will depend on the specified `format`, or the
  * extension of the file passed on the command-line if no `format` is specified.
  *
- * @example
+ * **Example** (Parsing file contents)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -460,8 +498,8 @@ export const fileText = (kind, name) => makeSingle({
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileParse = (kind, name, options) => makeSingle({
   name,
@@ -471,7 +509,8 @@ export const fileParse = (kind, name, options) => makeSingle({
 /**
  * Creates a parameter that reads and validates file content using a schema.
  *
- * @example
+ * **Example** (Validating file contents)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import * as Param from "effect/unstable/cli/Param"
@@ -495,8 +534,8 @@ export const fileParse = (kind, name, options) => makeSingle({
  * // Usage: --config config.json (reads and validates file content)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fileSchema = (kind, name, schema, options) => makeSingle({
   name,
@@ -510,7 +549,8 @@ export const fileSchema = (kind, name, schema, options) => makeSingle({
  * Note: Requires at least one key=value pair. The parsed pairs are merged
  * into a single record object.
  *
- * @example
+ * **Example** (Parsing key-value pairs)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -523,8 +563,8 @@ export const fileSchema = (kind, name, schema, options) => makeSingle({
  * // --property name=value --property debug=true
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const keyValuePair = (kind, name) => map(variadic(makeSingle({
   name,
@@ -538,23 +578,24 @@ export const keyValuePair = (kind, name) => map(variadic(makeSingle({
  *
  * This is useful for creating placeholder parameters or for combinators.
  *
- * @example
+ * **Example** (Creating sentinel parameters)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
  * // @internal - this module is not exported publicly
  *
- * // Create a none parameter for composition
- * const noneParam = Param.none(Param.flagKind)
+ * const disabledDebugParam = Param.none(Param.flagKind)
  *
- * // Often used in conditional parameter creation
- * const conditionalParam = process.env.NODE_ENV === "production"
- *   ? Param.string(Param.flagKind, "my-dev-flag")
- *   : Param.none(Param.flagKind)
+ * const makeDebugParam = (enableDebug: boolean) =>
+ *   enableDebug ? Param.string(Param.flagKind, "debug") : disabledDebugParam
+ *
+ * console.log(makeDebugParam(true) === disabledDebugParam) // false
+ * console.log(makeDebugParam(false) === disabledDebugParam) // true
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const none = kind => makeSingle({
   name: "__none__",
@@ -571,7 +612,8 @@ const FLAG_DASH_REGEXP = /^-+/;
  * This works on any param structure by recursively finding the underlying
  * `Single` node and applying the alias there.
  *
- * @example
+ * **Example** (Adding parameter aliases)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -589,8 +631,8 @@ const FLAG_DASH_REGEXP = /^-+/;
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withAlias = /*#__PURE__*/dual(2, (self, alias) => {
   return transformSingle(self, single => makeSingle({
@@ -604,7 +646,8 @@ export const withAlias = /*#__PURE__*/dual(2, (self, alias) => {
  * Descriptions provide users with information about what the option does
  * when they view help documentation.
  *
- * @example
+ * **Example** (Adding help descriptions)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -616,8 +659,8 @@ export const withAlias = /*#__PURE__*/dual(2, (self, alias) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDescription = /*#__PURE__*/dual(2, (self, description) => {
   return transformSingle(self, single => makeSingle({
@@ -628,7 +671,8 @@ export const withDescription = /*#__PURE__*/dual(2, (self, description) => {
 /**
  * Transforms the parsed value of an option using a mapping function.
  *
- * @example
+ * **Example** (Mapping parsed values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -639,8 +683,8 @@ export const withDescription = /*#__PURE__*/dual(2, (self, description) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => {
   const parse = args => Effect.map(self.parse(args), ([operands, value]) => [operands, f(value)]);
@@ -662,7 +706,8 @@ const transform = (self, f) => Object.assign(Object.create(Proto), {
 /**
  * Transforms the parsed value of an option using an effectful mapping function.
  *
- * @example
+ * **Example** (Mapping parsed values effectfully)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -686,15 +731,16 @@ const transform = (self, f) => Object.assign(Object.create(Proto), {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapEffect = /*#__PURE__*/dual(2, (self, f) => transform(self, parse => args => Effect.flatMap(parse(args), ([leftover, a]) => f(a).pipe(Effect.map(b => [leftover, b])))));
 /**
  * Transforms the parsed value of an option using a function that may throw,
  * converting any thrown errors into failure messages.
  *
- * @example
+ * **Example** (Mapping thrown errors)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -709,8 +755,8 @@ export const mapEffect = /*#__PURE__*/dual(2, (self, f) => transform(self, parse
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => {
   const single = getUnderlyingSingleOrThrow(self);
@@ -725,12 +771,14 @@ export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => {
   })), Effect.map(b => [leftover, b]))));
 });
 /**
- * Creates an optional option that returns None when not provided.
+ * Makes a flag or positional argument optional.
  *
- * Optional options never fail with MissingOption errors. If the option is not
- * provided on the command line, Option.none() is returned instead.
+ * When the parameter is absent, parsing succeeds with `Option.none()` instead
+ * of failing with a missing option or missing argument error. When present, the
+ * parsed value is wrapped in `Option.some()`.
+ *
+ * **Example** (Making parameters optional)
  *
- * @example
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -740,8 +788,8 @@ export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => {
  * const port = Param.optional(Param.integer(Param.flagKind, "port"))
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const optional = param => {
   const parse = Effect.fnUntraced(function* (args) {
@@ -767,13 +815,13 @@ export const optional = param => {
   });
 };
 /**
- * Makes an option optional by providing a default value.
+ * Makes a flag or positional argument optional by supplying a fallback value.
+ *
+ * The fallback may be a pure value or an effect. It is used only when the
+ * parameter is absent; provided values are parsed normally.
  *
- * This combinator is useful when you want to make an existing option optional
- * by providing a fallback value that will be used when the option is not
- * provided on the command line.
+ * **Example** (Providing default values)
  *
- * @example
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -792,8 +840,8 @@ export const optional = param => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withDefault = /*#__PURE__*/dual(2, (self, defaultValue) => {
   if (!Effect.isEffect(defaultValue)) {
@@ -807,8 +855,8 @@ export const withDefault = /*#__PURE__*/dual(2, (self, defaultValue) => {
 /**
  * Adds a fallback config that is loaded when a required parameter is missing.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withFallbackConfig = /*#__PURE__*/dual(2, (self, config) => {
   const toInvalidValue = (error, configError) => new CliError.InvalidValue({
@@ -817,7 +865,7 @@ export const withFallbackConfig = /*#__PURE__*/dual(2, (self, config) => {
     expected: configError.message,
     kind: error._tag === "MissingOption" ? "flag" : "argument"
   });
-  const runConfig = (error, args) => Config.option(config).asEffect().pipe(Effect.mapError(configError => toInvalidValue(error, configError)), Effect.flatMap(Option.match({
+  const runConfig = (error, args) => Config.option(config).pipe(Effect.mapError(configError => toInvalidValue(error, configError)), Effect.flatMap(Option.match({
     onNone: () => Effect.fail(error),
     onSome: value => Effect.succeed([args.arguments, value])
   })));
@@ -826,8 +874,8 @@ export const withFallbackConfig = /*#__PURE__*/dual(2, (self, config) => {
 /**
  * Adds a fallback prompt that is shown when a required parameter is missing.
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withFallbackPrompt = /*#__PURE__*/dual(2, (self, prompt) => {
   const runPrompt = (error, args) => Effect.flatMap(Prompt.isPrompt(prompt) ? Effect.succeed(prompt) : prompt, Prompt.run).pipe(Effect.map(value => [args.arguments, value]), Effect.catchTag("QuitError", () => Effect.fail(error)));
@@ -840,7 +888,8 @@ export const withFallbackPrompt = /*#__PURE__*/dual(2, (self, prompt) => {
  * The min and max parameters are optional - if not provided, the parameter can be
  * specified any number of times (0 to infinity).
  *
- * @example
+ * **Example** (Accepting multiple values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -858,12 +907,12 @@ export const withFallbackPrompt = /*#__PURE__*/dual(2, (self, prompt) => {
  * // Variadic with both min and max
  * const limited = Param.variadic(Param.string(Param.flagKind, "item"), {
  *   min: 2, // at least 2 times
- *   max: 2 // at most 5 times
+ *   max: 2 // at most 2 times
  * })
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const variadic = (self, options) => {
   const single = getUnderlyingSingleOrThrow(self);
@@ -889,7 +938,8 @@ export const variadic = (self, options) => {
  * This combinator transforms an option to accept between `min` and `max`
  * occurrences on the command line, returning an array of all provided values.
  *
- * @example
+ * **Example** (Bounding repeated values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -913,8 +963,8 @@ export const variadic = (self, options) => {
  * // Result: ["dev", "staging", "v1.0"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const between = /*#__PURE__*/dual(3, (self, min, max) => {
   if (min < 0) {
@@ -934,7 +984,8 @@ export const between = /*#__PURE__*/dual(3, (self, min, max) => {
  * This combinator transforms an option to accept between 0 and `max`
  * occurrences on the command line, returning an array of all provided values.
  *
- * @example
+ * **Example** (Limiting repeated values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -949,8 +1000,8 @@ export const between = /*#__PURE__*/dual(3, (self, min, max) => {
  * // Result: ["warning1", "warning2"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atMost = /*#__PURE__*/dual(2, (self, max) => {
   if (max < 0) {
@@ -966,7 +1017,8 @@ export const atMost = /*#__PURE__*/dual(2, (self, max) => {
  * This combinator transforms an option to accept at least `min`
  * occurrences on the command line, returning an array of all provided values.
  *
- * @example
+ * **Example** (Requiring repeated values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -982,8 +1034,8 @@ export const atMost = /*#__PURE__*/dual(2, (self, max) => {
  * // Result: ["file1.txt", "file2.txt", "file3.txt"]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const atLeast = /*#__PURE__*/dual(2, (self, min) => {
   if (min < 0) {
@@ -999,7 +1051,8 @@ export const atLeast = /*#__PURE__*/dual(2, (self, min) => {
  *
  * This combinator is useful for validation and transformation in a single step.
  *
- * @example
+ * **Example** (Filtering and transforming values)
+ *
  * ```ts
  * import { Option } from "effect"
  * import * as Param from "effect/unstable/cli/Param"
@@ -1013,8 +1066,8 @@ export const atLeast = /*#__PURE__*/dual(2, (self, min) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filterMap = /*#__PURE__*/dual(3, (self, filter, onNone) => mapEffect(self, Effect.fnUntraced(function* (a) {
   const result = filter(a);
@@ -1032,7 +1085,8 @@ export const filterMap = /*#__PURE__*/dual(3, (self, filter, onNone) => mapEffec
 /**
  * Filters parsed values, failing with a custom error message if the predicate returns false.
  *
- * @example
+ * **Example** (Filtering parsed values)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1046,8 +1100,8 @@ export const filterMap = /*#__PURE__*/dual(3, (self, filter, onNone) => mapEffec
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => filterMap(self, Option.liftPredicate(predicate), onFalse));
 /**
@@ -1056,7 +1110,8 @@ export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => filterM
  * The metavar is displayed in usage text to indicate what value the user should provide.
  * For example, `--output FILE` shows `FILE` as the metavar.
  *
- * @example
+ * **Example** (Setting metavars)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1071,8 +1126,8 @@ export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => filterM
  * )
  * ```
  *
- * @since 4.0.0
  * @category metadata
+ * @since 4.0.0
  */
 export const withMetavar = /*#__PURE__*/dual(2, (self, metavar) => transformSingle(self, single => makeSingle({
   ...single,
@@ -1081,7 +1136,8 @@ export const withMetavar = /*#__PURE__*/dual(2, (self, metavar) => transformSing
 /**
  * Validates parsed values against a Schema, providing detailed error messages.
  *
- * @example
+ * **Example** (Validating with schemas)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import * as Param from "effect/unstable/cli/Param"
@@ -1098,8 +1154,8 @@ export const withMetavar = /*#__PURE__*/dual(2, (self, metavar) => transformSing
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const withSchema = /*#__PURE__*/dual(2, (self, schema) => {
   const decodeParam = Schema.decodeUnknownEffect(schema);
@@ -1116,7 +1172,8 @@ export const withSchema = /*#__PURE__*/dual(2, (self, schema) => {
 /**
  * Provides a fallback param to use if this param fails to parse.
  *
- * @example
+ * **Example** (Falling back to another parameter)
+ *
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1127,14 +1184,19 @@ export const withSchema = /*#__PURE__*/dual(2, (self, schema) => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElse = /*#__PURE__*/dual(2, (self, orElse) => transform(self, parse => args => Effect.catch(parse(args), err => orElse(err).parse(args))));
 /**
- * Provides a fallback param, wrapping results in Either to distinguish which param succeeded.
+ * Provides a fallback param and returns a `Result` indicating which param
+ * succeeded.
+ *
+ * The original param's value is returned as `Result.succeed`, while the
+ * fallback param's value is returned as `Result.fail`.
+ *
+ * **Example** (Returning fallback results)
  *
- * @example
  * ```ts
  * import * as Param from "effect/unstable/cli/Param"
  *
@@ -1146,8 +1208,8 @@ export const orElse = /*#__PURE__*/dual(2, (self, orElse) => transform(self, par
  * // Returns Result<string, string>
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const orElseResult = /*#__PURE__*/dual(2, (self, orElse) => {
   return transform(self, parse => args => Effect.catch(Effect.map(parse(args), ([leftover, value]) => [leftover, Result.succeed(value)]), err => Effect.map(orElse(err).parse(args), ([leftover, value]) => [leftover, Result.fail(value)])));