Using "whose" on arrays in Javascript for Automation - applescript

Question

Playing with the new JS for automation using Script Editor. I'm getting an error on the final line of the following:
var iTunes = Application("iTunes");
var sources = iTunes.sources();
var library = sources.whose({name : "Library"});
Confirmed that the sources array is as expected (two elements, one with name "Library" and one "Internet Radio"). But that final line chokes with Error on line 3: TypeError: undefined is not a function (evaluating 'sources.whose({name : "Library"})').
As far as I can tell, I'm using the right syntax for the whose function. (I also tried with an explicit _equals clause to the same result.) What am I doing wrong?

Answer 1

What am I doing wrong?
Short answer: it's not your fault. The JXA documentation is a sack of lies.
Longer explanation: an object's elements have nothing to do with Arrays. They represent a one-to-many relationship in an object graph, in this case, between a source object and zero or more library objects.
While many relationships may reflect the underlying implementation's containment hierarchy, there is no obligation to do so; e.g. Finder allows you to identify objects on the desktop in multiple ways:
items of folder "Desktop" of folder "jsmith" of folder "Users" of disk "Macintosh HD" of app "Finder"
items of folder "Desktop" of folder "jsmith" of folder "Users" of startup disk of app "Finder"
items of folder "Desktop" of home of app "Finder"
items of folder "Macintosh HD:Users:jsmith:Desktop" of app "Finder"
items of desktop of app "Finder"
items of app "Finder"
[etc.]
Apple event-based application scripting is based on remote procedure calls plus simple first-class queries. It's not OOP, regardless of superficial appearance: that's just syntactic sugar to make its queries easy to read and write.
...
In this case, your second line is telling iTunes to get a list (Array) of query objects (ObjectSpecifiers) that identify each of the source objects in your iTunes application:
var iTunes = Application("iTunes");
var sources = iTunes.sources();
Once you've got an Array, you can't use it to construct further queries, because JavaScript doesn't know how to build queries itself. What you actually want is this:
var iTunes = Application("iTunes");
var sourcesSpecifier = iTunes.sources;
var librarySpecifier = sourcesSpecifier.whose({name : "Library"});
That will give you an object specifier that identifies all of the source objects whose name is "Library". (If you only want to specify the first source object named "Library", use the byName method instead of whose; it's simpler.)
--
Personally, I consider all this somewhat academic as JXA's Apple event bridge implementation, like its documentation, is mostly made of Lame and Fail anyway. It mostly works up to a point, then poops on you beyond that. If your needs are modest and it's "good enough" to do then more power to you, but for anything non-trivial stick with AppleScript: it's the only supported solution that works right.
(The AppleScript/JXA team has no excuse for such crap work either: I sent them an almost-finished JavaScriptOSA reference implementation months ago to study or steal from as they wished, which they totally ignored. So you'll excuse my pissiness, as this was a solved problem long ago.)

Answer 2

This now works as theory would predict.
(function () {
'use strict';
var iTunes = Application('iTunes'),
filtered = iTunes.sources.whose({
name: 'Library'
});
return filtered().length;
})();

Answer 3

Based on the JavaScript for Automation Release Notes Mail.inbox.messages.whose(...) example, the following should work:
var iTunes = Application('iTunes');
var filtered = iTunes.sources.whose({name : 'Library'});
The apparent goal for the "special whose method" with "an object containing the query" is to be efficient by only bringing select items (or item references) from the OS X object hierarchy into the resulting JavaScript array.
However, ... the whose feature of JXA appeared to have some bugs in the earlier OS X v10.10 release.
So, since the array in question is small (i.e. 2 items), filtering can be done fast & reliably on the JavaScript side after getting the elements as a JS array.
Workaround Example 1
var iTunes = Application('iTunes');
var sources = iTunes.sources();
var librarySource = null;
for (key in sources) {
var name = sources[key].name();
if (name.localeCompare("Library") == 0) {
librarySource = sources[key];
}
}
Workaround Example 2
var iTunes = Application('iTunes');
var sources = iTunes.sources();
function hasLibraryName(obj) {
var name = obj.name();
if (name.localeCompare("Library") == 0) {
return true;
}
return false;
}
var filtered = sources.filter(hasLibraryName);

Answer 4

In OS X 10.11.5 this seems to be working just fine.
library = Application("iTunes").sources.whose({name:'Library'})()[0]
library.properties()
// {"class":"source", "id":64, "index":1, "name":"Library", "persistentID":"2D8F973150E0A3AD", "kind":"library", "capacity":0, "freeSpace":0}
Note the addition of () after the whose clause to resolve the object specifier into an array of references and then the [0] to get the first (and only, in my case) library object reference, which can then be used to get the properties of that library.
In case the source is not named "Library" in other languages or regions, I would probably use this instead:
library = Application("iTunes").sources.whose({kind:"kLib"})()[0]