Support nested directories with namingFunction & clarify docs

[Murderlon]

Resolves #457 (comment)

• Support nested directories in @tus/file-store (@tus/s3-store: add object prefixing #457 (comment))
• Remove req.baseUrl, which was ts-ignore'd, from generateUrl. This is always undefined and only exists in Express.js. From a type perspective it's a breaking change, but since we always passed undefined and removing the type means it's still undefined so it's practically speaking the same.
• Clarify docs on generateUrl, getFileIdFromRequest, and namingFunction.

I thought generateUrl supersedes namingFunction, as instead of only generating an ID we now do the entire URL. Except generateUrl only changes the returned Location header, while we used to have the principle of upload ID mapping to the file name in storage. So if you return an entirely different ID in generateUrl, the default of namingFunction is the name written to storage. If you define namingFunction, then that becomes the id argument in generateUrl.

[Acconut]

Great improvement! After these changes, the two options don't seem odd to me anymore. namingFunction customizes the upload ID and file name, while generateURL and getFileIdFromRequest (which should maybe have been called getUploadIdFromRequest?) embed or extract the upload ID from the URL.

[Murderlon]

To simplify the code for custom implementations, we could also pass a default id to namingFunction and the default extracted id to getFileIdFromRequest. Then it becomes a lot cleaner:

const path = '/files'
const server = new Server({
  path,
  datastore: new FileStore({directory: './test/output'}),
-  namingFunction(req) {
+ namingFunction(req, defaultId) {
-    const id = crypto.randomBytes(16).toString('hex')
    const folder = getFolderForUser(req) // your custom logic
-    return `users/${folder}/${id}`
+    return `users/${folder}/${defaultId}`
  },
  generateUrl(req, {proto, host, path, id}) {
    id = Buffer.from(id, 'utf-8').toString('base64url')
    return `${proto}://${host}${path}/${id}`
  },
-  getFileIdFromRequest(req) {
+ getFileIdFromRequest(req, lastPath) {
-    const reExtractFileID = /([^/]+)\/?$/
-    const match = reExtractFileID.exec(req.url as string)
-
-   if (!match || path.includes(match[1])) {
-      return
-   }
-
-    return Buffer.from(match[1], 'base64url').toString('utf-8')
+    return Buffer.from(lastPath, 'base64url').toString('utf-8')
  },
})

[fenos]

@Murderlon not sure i like the idea of passing a default id in the namingFunction - it feels like wasted computation for users who really don't need the defaultId

However, I do like the lastPath param on the getFileIdFromRequest it makes things easier.
I'm wondering if passing the full uri instead of lastpath could also unlock more flexibilities?

that way an implementor might also decide to not base64 the id and simply do:

getFileIdFromRequest(req, uri) {
   return uri.split('/').slice(3).join('/')
}

[Murderlon]

Fair enough, I was mostly thinking out loud. We can keep things as is for now. uri probably isn't different from req.url either.

[fenos]

Looks great!