Not the “mechanics”, but the data structures, methods etc. are documented in the scripting dictionary.
I feel your pain. The idea behind the scripting dictionary is great. But the implementation … The terminology is at best outdated, at worst misleading. Let’s have a look at DT’s database “object” (in fact, it’s a class, but as I said: the terminology is misleading).
** Database** Object [inh. Item] : A database (supports the standard ‘close’ command).
ELEMENTS
contains contents, parents, records, smartGroups, tagGroups;
contained by application
That tells you that a database object contains other objects – well, no, those are Arrays (lists in AppleScript parlance) of objects. As can be seen by the plural form. So, a database contains arrays of content, parent, record, smartGroup and tagGroup objects. And a database itself is contained by an application object.
The latter is kind of what you get when call the top-level JXA method Application("DEVONthink 3")
With
app = Application("DEVONThink 3")
you store an Object Specifier (don’t ask me what that really is – I’d loosely translate it as “pointer to an object”) in the variable app. Knowing that this app “contains” databases, you can write:
allDatabases = app.databases;
What you’re doing there is similar to the approach of object-oriented languages: The dot descends into the object to address one of its properties (“Elements” in Apple parlance – they treat single value properties differently from list-valued ones. Terrible.) Now, allDatabases is again an Object Specifier.
We know that this Object Specifier “points” to an Array. In order to work with this underlying structure in JavaScript, we have to “dereference” using parenthesis:
allDatabases().forEach(db => console.log(db.name()) works because allDatabases() gives you a standard JavaScript Array, on which you call the method forEach. The same goes for db.name(): it “dereferences” the name property (!) of a database object, so that it becomes a JavaScript String.
As long as you’re staying in the JXA world, ie inside Apple’s scripting architecture, you do not dereference Object Specifiers. As soon as you need objects in the JavaScript world, you must dereference.
There’s more in-depth information on JXA and sample code on my website.