Function optional

packages/effect/src/unstable/cli/Param.ts:1271–1303

(
  param: Param<Kind, A>
)

 * @since 4.0.0
 */
export const optional = <Kind extends ParamKind, A>(
  param: Param<Kind, A>
): Param<Kind, Option.Option<A>> => {
  const parse: Parse<Option.Option<A>> = Effect.fnUntraced(function*(args) {
    const single = getUnderlyingSingleOrThrow(param)

    // Handle boolean params that are explicitly marked as optional (i.e. the
    // end user wants to return `Option.none()` instead of `false` when the
    // flag (or its negated variant) are not present on the command line
    if (
      isFlagParam(single) &&
      Primitive.isBoolean(single.primitiveType) &&
      ![single.name, ...single.aliases].some((name) => (args.flags[name] ?? []).length > 0)
    ) {
      return [args.arguments, Option.none()] as const
    }

    return yield* param.parse(args).pipe(
      Effect.map(([leftover, value]) => [leftover, Option.some(value)] as const),
      // Catch both MissingOption (for flags) and MissingArgument (for positional arguments)
      Effect.catchTags({
        MissingOption: () => Effect.succeed([args.arguments, Option.none()] as const),
        MissingArgument: () => Effect.succeed([args.arguments, Option.none()] as const)
      })
    )
  })
  return Object.assign(Object.create(Proto), {
    _tag: "Optional",
    kind: param.kind,
    param,
    parse
  })
}

/**
 * Makes a flag or positional argument optional by supplying a fallback value.