✨ API: add File() or NewFile() to API to create a new file

[jpadams]

What are you trying to do?

Today, there is no way to ask the API for a new file directly. You have to go through Directory.

We got close to seeing this in the past, but it hasn't happened yet.

• Core API: Directory and File types #3028
• API: Creating a new file is annoying #3884

Why is this important to you?

Many users have requested this including @sagikazarmark @vito @helderco @jpadams

How are you currently working around this?

myFile := dag.Directory().WithNewFile("file.json", content).File("file.json")

query test($content: String = "{}") {
  directory {
    withNewFile(path:"file.json", contents: $content) {
      file(path: "file.json") {
        id
      }
    }
  }
}

[helderco]

We already have a dag.File but it's deprecated because it was used to load a File from a FileID:

• Remove deprecated schema fields #6934

However, we have:

• dag.Container that creates an empty container
• dag.Directory that creates an empty directory
• dag.HTTP that returns a File from a URL

So having dag.File would be more consistent than dag.NewFile:

type Query {
  file(name: String!, contents: String!): File!
}

The problem is Query.file is deprecated but haven't been removed. We can't change the deprecation for just the ID argument like we did with Query.directory because it's a required argument in Query.file.

We could wait to add this until a release after v0.12 (i.e., release without current Query.file, then new release with new Query.file). But I feel inclined to just replace, instead of remove + add in different releases.

[sagikazarmark]

So having dag.File would be more consistent than dag.NewFile

On the other hand, dag.NewFile would be more consistent with Container.WithNewFile and Directory.WithNewFile.

One could argue though, that with the addition of dag.File those calls could be replaced with WithFile instead, leading to WithNewFile functions getting deprecated.

[helderco]

So having dag.File would be more consistent than dag.NewFile

On the other hand, dag.NewFile would be more consistent with Container.WithNewFile and Directory.WithNewFile.

It's more inconsistent with dag.Container and dag.Directory than with those though (WithNew, rather than NewXXX).

One could argue though, that with the addition of dag.File those calls could be replaced with WithFile instead, leading to WithNewFile functions getting deprecated.

I thought about that but I'm not sure. If you don't want to repeat the file name:

source.WithFile("", dag.File("file.json", "{}"))

But internally that'll be equivalent to:

source.WithFile("", dag.Directory().WithNewFile("file.json", "{}").File("file.json"))

Which produces a llb.Merge between the current directory and an empty directory with the new file. Whereas Directory.withNewFile performs a llb.State.File op on the directory State directly.

Curious if the merge has more benefits and if deprecating WithNewFile in favor of it would be better though.