Hel.js

What is this?

Hel makes easier to query databases in a generic way. In practice, Hel is both the specification of a very simple query language, as long as a JavaScript module that allows you to:

• convert a query string to the corresponding AST (Abstract Syntax Tree) ;
• convert a query string to the corresponding filtering function, to then use it for example with Heimdall ;
• convert an AST to the corresponding query string.

For example, combined with Heimdall.js, Hel.js allows you to build web applications that query Hera databases by abstracting both the data retrieval and the data querying details.
… Which is what Hecate does, by the way.

Why should I use it?

Well really y̴̖̿̓ö̶͕͕͝ǘ̶͖͍ ̵̺̫́s̵̼͝h̷͓͂ò̸̠ü̸͍̈́ḽ̷̋͊ḏ̷̽ṅ̷̘'̷̺́̈́ṭ̶̬́͋,̸͔̥̾ ̴̪̌ô̶̤̇r̴̳̅̀ ̶͚̫͒̕H̶̹̿͜e̵̛̞̒l̵̖͗ ̵̪͓͘m̷̰̦̾a̵̠̱̽y̴͙̝͑ ̷͈̙͌d̵̯͝ř̷̟̓ͅa̷̟͖͗i̸͔̮̎n̶̗̠͂͋ ̶̢̦̿̕y̶̖̼̎o̵̖͉͐̎ú̴̧̕r̶͙̳͆ ̸̟͈͋s̶̰̫̿̀o̵̲͕̐ṳ̸̠̋͠l̷͔̫͘ ̴̦̇̐ ̶̧̤̑̂̃͐ä̵̡̙́̀n̵̞͓̬̅d̷̛͕̞̈̂͘ ̸̧͖̘̘̀t̵͖̓̿̆͂ą̵̳̘͉̿͂̈̎k̴̳̘̖̉͆͠ě̴̠̫ ̴̛̞̏̈́̕i̷̬̜̻͗́͒̽͜t̸̘̻̓ ̴̮̎̇̓a̶̦̪̰͈̍̍͝l̶͕̣̙̆̓ő̴̭͊͌͑ǹ̵̡͖̼̗̚g̷͖̙̤̐̂ ̷̝̞̣͑͜ẗ̸̯́h̶̙̒̊e̶̟͓̖͆̄ͅ ̴̣̰͋t̸̙̭́ẅ̷̨̹́ͅẻ̵̗͍̑l̶̪̏͊͌v̴̼̣̾͑͜͠é̷͇͈̥̣́̇ ̸͈̤̱̗͌̃́r̶̬̼͓̕͝ͅi̷̪̎v̵͍͎̦͂͊̓e̴̗̠͖̍̅͝r̸̡̩̘͝s̷̢̝̞͆ ̸̮̒̎̏̕a̴̳̖̔́̕ḷ̷̨͇͙͌͂̓l̴͖̺̤͓͌̓ ̶̢̩̑̃̅t̷̤͙̙̅̓h̸̢̙̰̋ḙ̶͎̰̀ ̵̢̪̿̍w̶͈͚̺̋̃á̵͈̑̅y̷͇̍ ̷̧̠͍̈́̾͑͝t̴̨̨͕̪̎͋̂ȏ̸̳ͅ ̴̡͓̀̔̓̐t̵͖̖̤̽h̴̞͑́ȇ̵̹̰̫̞ ̸̧̻̻̻̌͗H̷̪̜̐́a̴͎̜͖̞͒̋̉̃l̵͖̀̿́͂ḽ̸͛͌ş̶̜̤͐͌ ̴̧̜̞̊̂o̴̥͚̩̐͜f̶̤̦́̔ ̵̳̰̈́͌ṫ̶̡̩͈h̸̳̳̯̏̈́́͒ḙ̶̣̈͊̎̕ ̴̢͓͇̬̍̽D̷̩̋̈́͝͝e̶̲̥̲̐̀͠a̶̪̐d̷͙̉͑ ̸̣̪̥͠f̷̨͈̰̎̿̓ͅỏ̶͓̬͉̘̀͝r̸̫͍̘̪̍͑̋̕ ̸̱̤̎a̵̺̻̿́ṅ̸̢̡̮̹͘̕ ̴̳̻̮̣̊̍̔e̷͚̠̜̠̽t̵̮͚͈̙̋ę̶̭͔͕͛r̶̼̿̋̕n̷̞̼͈̻̒ḭ̴͚̔͛͊͊ͅṱ̴̣͆͘y̸̤̝̘̲͝ ̴̧͓̩̈́̍͐̀ö̵́́̽͠ͅf̴̼͎̣̂̔̔ ̷̨̝͋̕s̸̫͐͝u̴̦͇̙̤̓f̷̥̙̆f̴̡̲̠̽́̎ě̶̡͍̀r̸̛̹͎̭͔̽i̷̖͕͋̚n̴͓̊́͜ģ̶͉̭̈́̅̌̇.̶̝̓̕ ̵̝̣̞͋̋̽̚
Anyways, what was I saying? Oh well, it's up to you I guess. ¯\(ツ)/¯

How can I use it?

You can install Hel.js ⟨10.5281/zenodo.18413436⟩ by installing the package @cnrs/hel from the NPM repository using your regular package manager.
For example:

pnpm install @cnrs/hel

You can add it as a dependency to your package.json file, as usual.

Once installed, you can start using it with a few simple calls:

import { * as hel } from '@cnrs/hel';

const query = '!(type != "cat") & (subtype == "bobcat" | danger > "high")';
const filter = hel.fromStringToFilter(query);  // filter function
const tree = hel.fromStringToTree(query);   // Abstract Syntax Tree (AST)
const equivalent_query = hel.fromTreeToString(tree);  // equivalent to query

The equivalences between the HEL query language syntax and the corresponding AST (Abstract Syntax Tree) JavaScript nodes :

| Name | Syntax | AST node | Atom? | Notes | | --------- | ------------- | -------------------- | ----- | ------------------------------------------ | | Entity |eid VALUE |{ eid: 'VALUE'} | No | An item of entity ID VALUE:String. | | Attribute |aid VALUE |{ aid: 'VALUE'} | Yes | A metadata of attribute ID VALUE:String. | | Property |pid VALUE |{ pid: 'VALUE'} | Yes | A metadata of property ID VALUE:String. | | Number |VALUE |VALUE | Yes | A litteral numeric equals to VALUE. | | String |"VALUE" |"VALUE" | Yes | A litteral string equals to VALUE. | | Relation |ATOM OP ATOM |{ left: ATOM, operator: OP, right: ATOM}| No | A relation between a left and a right ATOM, using a binary relationnal operator OP. | | And |N¹ & N² & … |{ and: [ N¹, N², …]}| No | True if all nodes N¹,N²,… are true. | | Or |N¹ \| N² \| …|{ or: [ N¹, N², …]} | No | True if any node N¹,N²,… is true. | | Not |!( N ) |{ not: N } | No | The negated value of node N. | | Parentheses |( N ) |N | No | Used for priority between And and Or. |

Is it documented?

Sure!
You can read the user manual here, or jump directly to the technical reference here.
You can use your IDE built-in access to code documentation features, too.

Is it tested?

Of course!
Here's the coverage report.

You can run all tests on your machine, too.
After having cloned this repository, enter it, setup your dev environment, and then do for example:

pnpm run test:coverage

How can I contribute?

Aww that's so very kind of you! (｡◕‿‿◕｡)♥
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

GNU Affero General Public License version 3.0 or later

Acknowledgments

Hel would like to thank all its contributors and users for their support and feedback. ʕᵔᴥᵔʔ

Resources

• Documentation
• Releases
• Getting help
• Citing: ⟨10.5281/zenodo.18413436⟩