docs: Add semantics to fileReader
nh2 opened this issue · 1 comments
The docs at https://github.com/tus/tus-js-client/blob/beea5983cc79d6d61b65d150cef8809114873661/docs/api.md#filereader show the type signatures, but they don't explain what the values mean.
interface FileReader {
openFile(input: any, chunkSize: number): Promise<FileSource>
}
interface FileSource {
size: number
slice(start: number, end: number): Promise<SliceResult>
close()
}
interface SliceResult {
// Platform-specific data type which must be usable by the HTTP stack as a body.
value: any
done: boolean
}
For example:
- What's the meaning of
done: boolean
, to what value should one set it? The code atLines 784 to 791 in beea598
suggests it's to indicate the end of the stream whenuploadLengthDeferred
is used. So I guess there are 2 possible cases:
a.uploadLengthDeferred = true
,FileSource.size = Infinity
-- in that case, probably myslice()
function must also be prepared to receiveend = Infinity
, and I should setdone = true
exactly when I know that the streaming is now finished.
b.uploadLengthDeferred = false
, in that caseFileSource.size
must be finite, myslice
will only be called with finiteend
, and it is irrelevant what I setdone
to because the value is not read. - Is there any other contract over what the paremeters in
slice(start, end)
will be? For example:
a. Isend
the exclusive boundary, like inBlob.slice()
?
b. Will it be thatend - start <= chunkSize
(thechunkSize
that was passed toopenFile()
)?
One can guess answers from the current code, but since this is an interface, it would be nice to know what invariants will hold in the future.
Good point, thanks for bringing this up. The documentation could definitely be improved here.
2. a. Is
end
the exclusive boundary, like inBlob.slice()
?
Yes, see
tus-js-client/lib/node/sources/FileSource.js
Lines 41 to 46 in beea598
2. b. Will it be that
end - start <= chunkSize
(thechunkSize
that was passed toopenFile()
)?
If end
is finite, yes. But be aware that end
might also be Infinity
.
- What's the meaning of
done: boolean
, to what value should one set it?
done
indicates if subsequent calls to slice
will not return any data because the stream has ended. So done
can be set in the final slice
call where the final data chunk was returned:
{
done: true,
value: [some_data]
}
Or done
can be set as the only property if you notice that no more data is available:
{
done: true,
value: null
}
Note that in this case, tus-js-client might have to send an empty PATCH request to indicate the end of the upload if you used uploadLengthDeferred
.
I am not entirely sure if done
is only used if uploadLengthDeferred
is enabled, but I encourage every implementation to handle it properly because we cannot guarantee that this might not change in the future.
I will make sure to add all these points to the documentation soon.