client.put API is ambiguous and confusing

[Gozala]

I find client.put API to be confusing and ambiguous. I suspect it inherits an unfortunate API design from ipfs, but I think we can do better.

Problem

wrapWithDirectory controls behavior of the method but in it is often not obvious what the result of it's behavior is, e.g. docs suggest following:

https://github.com/web3-storage/docs/blob/85cae31a077fe4325d5dc5149f918a9a6fda6ec5/docs/reference/client-library.md#L133-L146

However, if you do this instead:

const cid = await client.put(files, { wrapWithDirectory: false })

The contents of the files directory will be at the top level, instead of the files directory itself:

bafybeiebez7epbidb7f6fcurnd5ukpokrpq5wkrsuakynukpxxo4y4ewvi/
├── hello.txt
└── stuff
└── things.md

But even above example produces directory containing files. How can it not unless you provide just a single file ?

Proposal

I would suggest avoiding ambiguity simply by following nft.storage client API design that intentionally avoids ambiguity here and a control flag:

1. storeBlob can stores single file. Note that it's intentionally storeBlob not storeFile because file name and mime type would be meaningless.
2. storeDirectory stores a filesystem tree and as name suggests produces directory.

Note that this makes wrapWithDirectory obsolete, want to wrap just use:

storeDirectory([new File([content], `dir/${name}`))

Want just file without intermediary directory, easy

storeDirectory([new File([content]), 'file')

[Gozala]

Alternative could be a companion library that allows you to build cars representing arbitrary directory structures with web compatible APIs

interface Lib {
  encode(handle:FileSystemHandle):Car
   // @see https://wicg.github.io/file-system-access/#filesystemfilehandle
  createFile():FileSystemFileHandle
  // @see https://wicg.github.io/file-system-access/#filesystemdirectoryhandle
  createDirectory():FileSystemDirectoryHandle
}

interface Car extends Blob {
  readonly type: 'application/car'
}

[vasco-santos]

Note that this makes wrapWithDirectory obsolete, want to wrap just use:

I think this is something we will want! Even from unixfs: ipfs/js-ipfs-unixfs#176

[yusefnapora]

I like this proposal - it feels a lot less surprising to have a separate method for storing "unwrapped" blobs.