vsm/vsm-dictionary

VSM-dictionary interface specification, and parent class with shared code for subclasses

vsm-dictionary's Issues

Split off `numToExp.js` code

Should we put it into a separate package called big-number-to-exponential ?

Make it a pure Node.js based project

and use Webpack only for the interactive demo.

Longer entry/match-object property names

Rename them like this:

- i --> id
- d --> dictID  (or dictId, or dictid, or dict?)
- x --> descr   (or expl, or def?)
- t --> terms
  - s --> str
  - y --> style
  - x --> descr  (or see above)
- z --> z
- w --> type   // } (used by match-objects only)
- s --> str    // }  "
- y --> style  // }  "
- tdel -> termsDel  // } (used by 'entryLike'-objects only)
- zdel -> zDel      // }  "

Split the project into the three Dictionary classes

Now it's a library with three properties: Dictionary, DictionaryLocal and DictionaryRemote.

This package should only contain the parent class Dictionary (and then renamed to VsmDictionary).
The two other classes should be in separate packages: vsm-dictionary-local and vsm-dictionary-remote-demo.

Allow less freedom for arguments

The spec currently defines that certain variables (get-options properties, and all add/update/delete functions' first arguments) can be either an Array of items, or a single item, e.g.:
{String | Array(String)}, {Object | Array(Object)}, etc.

This is a good approach when creating functions for a code library, that will be used in diverse projects.

But in our case, I expect that vsm-dictionary will only be used in the vsm-autocomplete and vsm-term-manager (or so) packages. And there we can simply agree to always access a vsm-dictionary-*'s functionality through the Array format only.

With that in mind, we could simplify vsm-dicionary's spec by replacing all
{String | Array(String)} ---> {Array(String)}, etc.,
which makes it simpler for people to create a new vsm-dictionary subclass.

If we do this, then we'd have to update vsm-dictionary-local in some way as well:
• We could leave the code as it is, and simply add a few sentences to its spec about the freedom it adds.
• Or (better) we could simplify some code and remove some tests. This would be helpful, because then the tests would again serve as as a direct inspiration for making other vsm-dictionary subclasses.

Update spec: return errors as Objects – (and a 'Not Implemented' code?)

Not all real-world APIs support some of the operations requested by getDictInfos or getEntries for example.
Usually this issue had to do with asking more general information from the APIs - e.g. asking for all dictionary information, all entries (in all possible sub-dictionaries/ontologies).

Thus, the specification should include information on what object should these functions return in these cases.

E.g., it could be something like:

{
  status: 400,
  error: 'Not implemented'
}

Extend definition of `name` property of a `dictInfo` object (to discuss)

The PubDictionaries API returns information on the dictionaries such as:
http://pubdictionaries.org/dictionaries/PTO-all.json
http://pubdictionaries.org/dictionaries/UBERON-AE.json

Should we map the given description to the name attribute of the dictInfo object (thus extending the definition a little bit)? Consider vsm-box's handling of dictInfo.name and size? Or maybe we could consider an extra z object property for dictInfo as well or too much/keep it simple?

Use Mocha for testing

Update spec for getDictInfos when subdictionary does not exist to not return an error

Generally I have implemented in all vsm-dictionaries strict-error handling: lannching multiple queries in the respective server API, one of them goes wrong, send proper error message back (see also issue #11 )

When at least one non-proper/non-existent options.filter.id is given in getDictInfos, the server API returns an error.
For example, PubDictionaries and BioPortal servers return a JSON object with a message like Unknown ontology/dictionary.
We agreed at some point that these kind of errors should be ignored, e.g. see implemention in BioPortal vsm-dictionary and vsm-pubdictionaries, but this is not mentioned in the spec currently (or maybe I ddin't look hard enough?)

Please updatre spec accordingly, because even me, after creating all these dictionaries, I almost forgot to do it for a new one (had the BioPortal code to guide me through it of course :))

Use 'nock' for testing DictionaryRemoteDemo

Replace our mock-replacing of the XMLHttpRequest-object, by using nock.
The 'nock' package mocks HTTP-requests, and acts as a fake server.
Using nock, we can now also mock the last, 'live test' based on a real term-providing server.