search

octet-stream / form-data

Spec-compliant FormData implementation for Node.js
https://www.npmjs.com/package/formdata-node
MIT License
142 stars 17 forks source link

mention some few differences #43

Closed jimmywarting closed 3 years ago

jimmywarting commented 3 years ago

i where wondering if we should mention any key differences between our two packages.

your's are cjs mine are esm

yours use older fetch-blob version still in cjs and won't update to the esm version? yours blob/file don't use whatwg:streams for instances

is one or the other better for node-fetch? if you use mine then you will also use the same fetch-blob version in my polyfill and node-fetch and avoid dedupl

yours are also smaller in since due to web-stream-polyfills large size

is your better for other libs like axios and superagent that are stuck with cjs?

jimmywarting commented 3 years ago

i don't know if you will ever update to esm and start using the latest version of fetch-blob (https://github.com/octet-stream/form-data/issues/42#issuecomment-899819682)

maybe it's good to have one of each? it's also likely that nodejs will implement FormData one day also

octet-stream commented 3 years ago

i don't know if you will ever update to esm and start using the latest version of fetch-blob

I was kind of thinking to just vendor it and port for my project's purposes (after that polyfill of Web Streams will reduce its size). Then after I switch over ESM I will just use fetch-blob, as a dependency again.

octet-stream commented 3 years ago

it's also likely that nodejs will implement FormData one day also

Yeah, I heard of it. Then my package will be there as a ponyfill for older Node.js versions or other JS environments that does not have FormData.

i where wondering if we should mention any key differences between our two packages.

Perhaps. But there's no much of a difference since you've added Node.js support. So I'm not sure what else to mention other than ESM/CJS support...

  1. Both packages implement FormData per spec
  2. Both has support of the files backed by FS
  3. Both has TS typing, I guess. Mine has some problems with fetch because TS thinks it is URLSearchParam class for some reason. Maybe it has some incompatibilities with FormData in its type declarations. Perhaps in File or Blob. Maybe somewhere else. Couldn't find it yet.
  4. Mine has both CJS and ESM support, so it can be used in both module systems.
  5. Mine exposes File, Blob, and also fileFromPath, fileFromPathSync and isFile as separate entry
octet-stream commented 3 years ago

I ended up porting fetch-blob into formdata-node to get rid of v2. When I drop CJS I will switch back to fetch-blob again.

octet-stream commented 3 years ago

I think we can add a table comparing our packages and also form-data. I think there's no much of a difference between ours (I mean, that likely only a few of them, such as having CJS support or not, others just a minor things), but it should make more sense to compare with form-data package, so people will be able to get this information straight from the readme rather than going to issues to find very first issue in pinned issues.

octet-stream commented 3 years ago

Ah! Mine targets to Node.js only, even though it has browser field in package.json, I only re-export native FormData from globalThis (or window, or self)

octet-stream commented 3 years ago

I guess the comparison table may look like this:

formdata-node formdata-polyfill undici FormData form-data
.append() ✔️ ✔️ ✔️ ✔️1
.set() ✔️ ✔️ ✔️ ❌
.get() ✔️ ✔️ ✔️ ❌
.getAll() ✔️ ✔️ ✔️ ❌
.forEach() ✔️ ✔️ ✔️ ❌
.keys() ✔️ ✔️ ✔️ ❌
.values() ✔️ ✔️ ✔️ ❌
.entries() ✔️ ✔️ ✔️ ❌
.forEach() ✔️ ✔️ ✔️ ❌
Symbol.iterator ✔️ ✔️ ✔️ ❌
CommonJS ✔️ ❌ ✔️ ✔️
ESM ✔️ ✔️ ✔️2 ✔️2
Blob ✔️3 ✔️4 ✔️3 ❌
Browser polyfill ❌ ✔️ ✔️ ❌
Builtin encoder ❌ ✔️ ✔️5 ✔️

1 Does not support Blob and File in entry value, but allows streams and Buffer (which is not spec-compiant, however); 2 Can be imported in ESM, because Node.js support for CJS modules in ESM context, but it does not have ESM entry point. 3 Have builtin implementations of Blob and/or File, allows native Blob and File as entry value. 4 Support Blob and File via fetch-blob package, allows native Blob and File as entry value. 5 Have multipart/form-data encoder as part of their fetch implementation.

✔️ - For FormData methods, indicates that the method is present and spec-compliant. For features, shows its presence. ❌ - Indicates that method or feature is not implemented.

What other things we might compare in our packages and form-data?

octet-stream commented 3 years ago

Maybe it also worth to mention FormData undici and few additional features like files backed up by fs (for my package it is also builtin feature as of now)?

jimmywarting commented 3 years ago

fetch-blob is the only one with "files backed up by fs" support...

octet-stream commented 3 years ago

No. My library includes this feature too. It will be removed, however, once I move to latest fetch-blob version.

octet-stream commented 3 years ago

For context: I made it because v2.1.2 was broken and my fix was released only in one of the v3 betas, so I had to either stick with 2.1.1 (which has its own problems, like being unable to test for null instanceof Blob) or just re-implement it myself. So, I decided to go with the second solution.

jimmywarting commented 3 years ago

As mention in the commit as a comment, my pkg has a built in encoder that turns formData into a blob

octet-stream commented 3 years ago

Sure thing 👍

octet-stream commented 3 years ago

Is everything correct now?

jimmywarting commented 3 years ago

lgtm