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

arangodb-query-parser

v0.1.20

Published

Convert url query string to ArangoDB friendly query object.

Downloads

6

Readme

arangodb-query-parser

Convert url query string to ArangoDB database AQL query.

Features

Supports most of the ArangoDB operators and features including filters, sorting, limit, skip, populating and aggregations.

Note: as this library allows to create heavy and/or unintentional database queries use it with caution in public environments!

Installation

npm install arangodb-query-parser

Usage

API

import { ArangoDbQueryParser } from 'arangodb-query-parser';

const parser = new ArangoDbQueryParser(options?: ParserOptions)
const queryOptions = parser.parse(query: string, predefined: any) : QueryOptions

parser.createQuery(queryOptions);

Constructor

Initialize parser with given options.

Arguments

  • ParserOptions: Object for advanced options:
    • dateFormat: Date format, default is ISO-8601 (YYYY-MM-DD)
    • whitelist: String array of fields allowed to be in the filter
    • blacklist: String array of fields disallowed to be in the filter
    • casters: Custom casters
    • castParams: Caster parameters
    • collection: Name of the collection for query
    • populateMapping: Field to collection mappings
    • populateAlways: Related collections/fields that are always populated
    • fieldsKey: Name of the query parameter used for selected fields
    • populateKey: Name of the query parameter used for reference population
    • sortKey: Name of the query parameter used for sorting
    • limitKey: Name of the query parameter for result count limit and skip
    • filterKey: Name of the query parameter for filters
    • aggregateKey: Name of the query parameter for aggregations

parser.parse(query, predefined)

Parses the query parameters into a QueryOptions object.

Arguments

  • query: query string part of the requested API URL (ie, firstName=John&limit=10). [required]
  • predefined: object for predefined queries/string templates [optional]

Returns

  • QueryOptions: object contains the following properties:
    • filter.filters contains the query string
    • filter.bindVars contains the query binding values
    • fields contains the query projection
    • populate paths to populate
    • sort,
    • limit contains the cursor modifiers for paging purposes.
    • aggregate contains the parsed aggregations

Filters

All other query parameters are considered to be filters. Example:

?firstName=Frederick&lastName=Durst

Specifies filters for firstName and lastName fields. Several values can be separated with comma for alternatives (OR):

?firstName=Frederick,Bernie,Jack

Value can be a regular expression:

?firstName=/frederick/i

Other signs for number and date fields:

?price<1000      // price is less than 1000
?price!=1000     // price is not 1000
?price>=1000     // price is larger or equal to 1000
?categories?=party // categories array includes party (any)
?categories*=party // categories array includes party (all)
?categories#=party // categories array does not include party (none)

Filters are excluding by default (AND): you can create OR by adding pipe character in front of the field name:

?price<1000&|price>1500      // price is less than 1000 or larger than 1500

Fields

Result fields can be specified in the format:

?fields=firstName,lastName

Limit

Result limits can be specified in the format:

?limit=10

will return 10 items. Optionally you can add starting offset:

?limit=10,30

will return 10 items starting from 30.

Sorting

Sorting can be specified in the format:

?sort=creationDate,-price

will sort first by creationDate ascending and then by price descending.

Populating

Two choices for relationship population exists:

  1. "Hardcoded" population with option populateAlways and populateMapping.
  2. Permissive population with option populateMapping and parsed parameter populate.

The option populateMapping is used for mapping allowed relationships (field to collection).

Option populateAlways can be used for specifying which relationships are always populated.

Example 1 - map field owner to collection users and field parent to collection customers:

const parser = new ArangoDbQueryParser({
	collection: 'customers',
	populateMapping: { owner: 'users', parent: 'customers' },
});

Then the query URL can specify which relationships to populate, for example:

?populate=owner,parent.name,parent.name2

will populate all fields from owner and fields name & name2 from parent.

Example 2 - map field owner to collection users and field parent to collection customers, specify that all fields from owner and name field from parent are always populated:

const parser = new ArangoDbQueryParser({
	collection: 'customers',
	populateMapping: { owner: 'users', parent: 'customers' },
	populateAlways: 'owner,parent.name'
});

You can disable default populates with dash:

?populate=-owner,-parent.name

To disable all populates use a dash only:

?populate=-

Aggregations

Aggregations can be specified in the format:

field,field2:as func field3

Where

  • field and field2 are the grouping fields
  • as is the name of the aggregation
  • func is the aggregation function (avg, sum, min, max, length, stddev, variance, count, count_distinct, unique, sorted_unique)
  • field3 is the name of the aggregated field

Example:

?aggregate=owner,status:totalPrice sum sum,averagePrice avg sum,priceCount count sum

You can leave out the grouping fields:

?aggregate=totalCount count owner

will create query for aggregation without grouping.

parser.createQuery(queryOptions)

Arguments

  • queryOptions: query options created by parse method. [required]

Returns

  • query: AQL query (as string) created from the query options. This can be used together with queryoptions filter.bindVars to run the query in ArangoDB.

License

MIT

Thanks

This library is heavily based on mongoose-query-parser by Leodinas Hao