uppy
uppy copied to clipboard
Make arguments passed to events consistent
Initial checklist
- [X] I understand this is a feature request and questions should be posted in the Community Forum
- [X] I searched issues and couldn’t find anything (or linked relevant results below)
Problem
Event names are sometimes confusing and seem inconsistent.
Solution
@uppy/core
Always send file(s) instead of ID(s)
Renaming we decided not to do.
- Rename
files-added
tofile-batch-added
. Or at least a better name to differentiate withfile-added
better - Rename
upload
toupload-start
- Rename
progress
toupload-progress
(total progress) - Rename
upload-progress
tofile-progress
(individual progress) - Rename
complete
toupload-complete
(success or error) - Rename
upload-error
tofile-error
(one file upload error) - Rename
error
toupload-error
(entire upload error) - Rename
cancel-all
toupload-cancel
@uppy/transloadit
- It's slighly weird that we something prefix with assembly (
transloadit:assembly-created
) and sometimes not (transloadit:upload
). We should always or never prefix with assembly because we are always talking about the same thing. - Make sure assembly is always the first argument, now it's mixed
- Always send file(s) instead of ID(s)
- Unclear what the difference is between
transloadit:result
andtransloadit:complete
. Potentially refactor to only have*:complete
-
uppy.on('error')
is extended with anassembly
property when the upload fails. This is a bit confusing, I suggest making suretransloadit:complete
also fires with it fails, with the assembly context, and keeperror
generic / consistent no matter the upload plugin.
Related
These should also be taken into account:
- https://github.com/transloadit/uppy/issues/4045
- https://github.com/transloadit/uppy/issues/3248
- https://github.com/transloadit/uppy/issues/3815
- https://github.com/transloadit/uppy/issues/4333
Alternatives
- No breaking change but rather confusing names for newcomers.
- Support both to not make it a breaking change. Deprecate the old in the docs.
- EDIT: having both is not possible as there are certain events (like
upload-error
) which would be both deprecated and new at once.
- EDIT: having both is not possible as there are certain events (like
We have internal, non-documented:
-
plugin-added
-
plugin-removed
Reusing the upload-progress
and upload-error
names for a different event is unfortunate as code that is not properly migrated will still register a listener for an existing event but for a different one.
our file-related events are a bit messy. some include a UppyFile
object, other include fileId
, some don't include anything.
in a future major we should probably refactor all file related events to either
- always include
fileId
- or always include an up to date
UppyFile
object (fromuppy.getFile()
)
@mifi this could be improved in a minor version by adding the missing property (either fileId
or file
depending on the choice done for the future) in existing events in addition to the current properties (and documenting that the other one is deprecated)
yes, but it will still be messy because fileId
, file
etc are not properties, they are instead positional arguments, so some events would be (fileId, file)
, others (file)
, others (file, fileId)
One way or another I think we would need a breaking change. But I'm starting to change my mind on the renaming of all events. It's incredibly challenging to get right for little user value. Yes the current names are confusing, but with good docs we get away with it and we would prevent breaking changes.
That being said we should definitely make the arguments consistent and up-to-date (no stale file
's)
@mifi for positional arguments, there is indeed no backward compatible solution.