npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

aql-builder

v0.6.3

Published

Dynamic query-builder for ArangoDB

Downloads

121

Readme

AQL Builder

A simple dynamic query-builder for ArangoDB, written in Typescript.

Installation

npm i --save aql-builder

Usage

AQL Builder consists of a small cluster of types, and a helper class to make using them easier.

  • AqQuery, a JSON structure that describes a complete AQL query
  • AqProperty, a JSON structure that describes a single property or attribute of an Arango document
  • AqFilter, AqAggregate, and AqSort; all subtypes of AqProperty
  • buildQuery, a function that turns an AqQuery JSON object into a GeneratedAqlQuery that can be run via arangojs
  • AqBuilder, a class that lets you build an AqQuery using chainable helper methods.

Chainable methods with AqBuilder

import { AqBuilder } from 'aql-builder';

const aqlQuery = new AqBuilder('responses')
  .filterBy('url.protocol') // Defaults to '!= null'
  .filterBy('url.domain', ['example.com', 'test.com'])
  .groupBy('status')
  .groupBy('mime')
  .count('total')
  .filterBy('status', [200, 404])
  .sortBy('total', 'desc')
  .build();

console.log(aqlQuery);

//  GeneratedAqlQuery
//
//  query: 'FOR item IN responses\n' +
//    'FILTER item.url.protocol != @value0\n' +
//    'FILTER item.url.domain IN @value1\n' +
//    'COLLECT\n' +
//    '  status = item.status,\n' +
//    '  mime = item.mime\n' +
//    'WITH COUNT INTO total\n' +
//    'FILTER status IN @value2\n' +
//    'SORT total DESC\n' +
//    'RETURN { status, mime, total }',
//  bindVars: {
//    value0: null,
//    value1: [ 'example.com', 'test.com' ],
//    value2: [ 200, 404 ]
//  }
//}

Manually constructed AqQuery

Queries can also be described in JSON and passed straight to the builder function; the structure below generates a query identical to the chained method approach above.

import { AqQuery, buildQuery } from 'aql-builder';

const aq: AqQuery = {
  collection: 'responses',
  filters: [
    { name: 'url.protocol', eq: null, negate: true },
    { name: 'url.domain', in: ['example.com', 'test.com'] },
    { name: 'status', in: [200, 404], document: false },
  ],
  aggregates: [
    { name: 'status', function: 'collect' },
    { name: 'mime', function: 'collect' },
  ],
  count: 'total',
  sorts: [
    { name: 'total', direction: 'desc' },
  ],
};
const aqlQuery = buildQuery(aq);

Shorthand syntax with AqQuery

Finally, the AqQuery structure supports shorthand versions of common filter, aggregate, sort, and return definitions. For example, return: [{ name: 'prop.name' }] can be written as return: ['prop.name']. These shorthand versions can be mixed and matched as needed.

import { AqQuery, buildQuery } from 'aql-builder';

const aq: AqQuery = {
  collection: 'responses',
  filters: [
    'url.protocol', // Expanded to 'equals null, negated' filter
    { name: 'url.domain', in: ['example.com', 'test.com'] },
    { name: 'status', in: [200, 404], documemt: false },
  ],
  aggregates: ['status', 'mime'], // Expanded to 'collect' aggregates
  count: 'total',
  sorts: ['total'] // Expanded to 'desc' sorts
};
const aqlQuery = buildQuery(aq);

Using them together

AqBuilder can be instantiated with an existing AqQuery object; that makes it possible to store a reusable query in JSON format, set up an AqBuilder instance with it, and customize the query with the builder object's chainable methods.

import { AqQuery, AqBuilder } from 'aql-builder';

const aq: AqQuery = {
  collection: 'responses',
  filters: [
    'url.protocol',
    { name: 'url.domain', in: ['example.com', 'test.com'] },
    { name: 'status', in: [200, 404], documemt: false },
  ],
  aggregates: ['status', 'mime'],
  count: 'total'
};

const query = new AqBuilder(aq)
  .sort('total', 'asc')
  .build();

Advanced features

Although the fluent methods on the AqBuilder class are handy, some types of query structures are only supported with manually-created AqQuery objects:

  • Filters that compare two properties, rather than one property to a literal value.
  • Subqueries, and filters/aggregations/property assignments that explicitly reference them.
  • Assignment of subqueries to custom variables that can be included in the results or used in filters

Examples can be found in INTERNALS.md.

Limitations

As noted above, the AqBuilder class doesn't support the full range of features that are possible with AqQuery, and AqQuery only supports a subset of the full AQL spec. In particular:

  • Insert or Update queries. AQL Builder is read-only.
  • Use of constructed documents as query sources. Every query requires an existing collection to iterate over.
  • Explicit construction of return documents with nested properties. (Though you can return properties that are themselves arrays or objects.)
  • Complex AQL functions. While it's possible to sneak certain functions in using 'FUNCTION(foo)" as property path, that trick chokes on any functions that require more than one parameter.
  • Explicitly ordering filter/subquery/aggregation functions to optimize queries or control returned results. The closest we get is the distinction between filters and returnFilters that run after aggregation.