Proposal: less generic / confusing interface

[Gozala]

I find myself staring going back to docs / examples to try and figure out what various options would do to make sure I get things right. In my experience this is an opportunity to improve API such that it is difficult to misuse / misinterpret.

Given a bit of experience here are few suggestions:

1. Expose separate APIs per use case:

   • pack a file - Most cases I've encountered so far it's a single file in which case following options are confusing and serve little purpose
     1. multiple inputs
     2. path of the input
     3. wrapWithDirectory
   • pack a directory of files - This could also be simplified by
     1. Getting rid of wrapWithDirectory option (if you want to warp file with dir use packDiretory and pass a single file.

2. Let user normalize input instead

   I think this is idiosyncrasy of IPFS that is really not worth replicating. Input type is extremely complex which is flexible enough to take almost anything yet it is not always obvious how each one is treated.

   I think API can be a lot nicer if it let user deal with input normalization and was itself was super simple

   • packFile({ content: Blob, ... })
   • packDirectory({ files: File[], ... })

   Files and Blobs can easily be created from all those input types and bad inputs.

3. Allow deciding what output should be afterwards

   Right now you have to pick between blob, fs and stream packer. I would suggest instead having single result value Pack that is:

   interface WebPack extends Blob {
       type: 'File' | 'Directory'
       readonly maxChunkSize: number
       readonly blockstore: BlockStore
   }

   And following in node:

   interface NodePack extends WebPack {
      // mimics https://nodejs.org/dist/latest-v17.x/docs/api/fs.html#fswritefilefile-data-options-callback
      writeFile(path:string, options:import('fs').WriteFileOptions):Promise<void>
      // mimics https://nodejs.org/dist/latest-v17.x/docs/api/fs.html#fscreatereadstreampath-options
      createReadStream():import('stream').Readable
   }

   Also given that web streams and blobs are coming to node, I'm not sure if it's even worth doing node specific things.