Specify folder parameter for folder-based filter

[ryanseys]

Add folder-based filtering to Bucket#getFiles with a folder query parameter.

Also implemented weird idea for returning prefixes for #342. I'm not sure how bad an idea it is, but basically return the prefixes as a property of the files Array. Yes, a property on an Array... How bad of an idea is that? 👶

[ryanseys]

Agh, tags. What ones do I use?? I just added a boat-load of them.

[stephenplusplus]

Agh, tags. What ones do I use?? I just added a boat-load of them.

Lol

What does the API response (resp.prefixes) look like? I don't feel like giving the dev a prefixes property on the files array is too important or useful. If they're using the folder property on a query passed to getFiles, they may not even realize we're using "prefixes" and "delimiters" under the hood, and wouldn't know what to do with that.

[stephenplusplus]

in progress and ready for review are relics from the days of waffle.io. opinions wanted and enhancement (and really, anything except for the service a PR is affecting) make more sense to me to be used on issues. But, I won't remove them again if you would like them back :)

[ryanseys]

What does the API response (resp.prefixes) look like?

Looks something like [ 'test/goodbye/', 'test/hello/' ] when folder is set to test so basically, it's the folders in a given folder. What if we used a new query flag that the developer can specify and then we will return them in the prefixes property. Like includePrefixes: true or something?

[stephenplusplus]

What if on the File object itself, it had a "folder" property that was it's prefix? I don't think an array of prefixes is too useful.

[ryanseys]

Yeah, thought of that too! A complaint I have with that with doing that is that suddenly everyone's code will need to handle the case where the file isn't actually a file and has no metadata or id or anything, and just contains a folder property instead.

[stephenplusplus]

How would that happen? I'm envisioning:

bucket.getFiles(function(err, files) {
  files[0].name = 'iamin/a/folder.jpg'
  files[0].folder = 'iamin/a'

  files[1].name = 'iamnotinafolder.jpg'
  files[0].folder = undefined
});

Though, chasing this thought down, I'm still not sure that's a helpful bit of knowledge to have. If I really wanted to, I could use the native path module to parse out the folder/extension from a file path. The most important thing should be bucket.getFiles({ folder: 'a/folder' }) to get only the files from a folder, and bucket.getFolders() (which I don't think we know how to do yet / haven't implemented).

[ryanseys]

The problem with your example is that the files might not exist but the folders would. Also, bucket.getFiles({ folder: 'test' }) returns the files in the test folder (and the folder itself), and prefixes returns the folders in that folder.

[ryanseys]

Because, the test folder is returned the results, we could add the prefixes as a subfolders property on that object in the files list? This won't work for the root folder (/) because it's not a folder, it's just the root. In that case, getting the subfolders in the root would be impossible which isn't ideal.

[stephenplusplus]

My head is spinning a bit, because I still don't see the value to a user. There's clear value to bucket.getFiles({ folder: 'a/folder' }), and bucket.getFolders() would be nice as well, though not as vital. Even for a power-user, getting a File object that retains knowledge of the folder it's in or sub-folder, or prefix, etc, isn't something I can see being useful. And if I'm wrong and the user does need that information, they can solve the problem simply by putting files that were retrieved from a folder into a data structure that's labeled as such:

var folders = { dir1: [], dir2: [] };

Object.keys(folders).forEach(function(folder) {
  bucket.getFiles({ folder: folder }, function (err, files) {
    folders[folder] = files;
  });
});

Hope I'm not overlooking something obvious. As is evident from my history on this project, it sometimes just takes a while for me to understand the Google APIs :)

// also, would it be useful / possible to accept getFiles({ folders: ['folder1', 'folder2'] })?

[ryanseys]

Yeah my head is spinning too. In this case I think it's best if we just find the simplest way to return the parameter rather than potentially messing up some folder-related methods that we don't fully understand.

[ryanseys]

Ok, no folder value, how about just returning prefixes so that this value can be used to allow developers to create their own similar functionality if required (e.g. like in #342)

[stephenplusplus]

I'll let you make the call on this.

[ryanseys]

Yeah, I've decided this idea sucks. Will reconsider #342 or something similar.