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

@wedgekit/mql

v2.0.0

Published

Handles encoding and decoding of internal query language, MQL.

Downloads

15

Readme

MQL (Metadata Query Language)

Encoding

The encode method accepts a pseudo abstract syntax tree that is represented as follows using disjunctive normal form:

    [ // conditions combined with ||
        conditionA,
        conditionB,
        [ // conditions combined with &&
    	    conditionC,
    	    [ // conditions combined with ||
    		    conditionD,
    		    [ // conditions combined with &&
    			    ... and so on, alternating || and && by layer
    		    ]
    	    ]
        ],
        conditionE
    ]

...where a given condition is represented as and object with a field, operator, and list of values:

    {
        field: some field,
        operator: an operator from the metadata spec,
        value: [list of reqired values needed for chosen operator]
    }

The field and values cannot contain parentheses or gate symbols, so the following symbols are reserved: (, ), ||, and &&.

Refer to the metadata spec for required values.

NOTE - SET_VALUE expressions are not currently supported by the encoder.

For example, the following condition:

    [
        {
            field: 'exampleA',
            operator: 'EQUALS',
            value: ['A']
        },
        [
            {
                field: 'exampleB',
                operator: 'TRUTHY',
                value: []
            },
    	    [
                {
                    field: 'exampleC',
                    operator: 'STARTS_WITH',
                    value: ['example']
                },
                {
                    field: 'exampleC',
                    operator: 'ENDS_WITH',
                    value: ['C']
                }
    	    ]
        ],
        {
            field: 'exampleD',
            operator: 'BETWEEN',
            value: [1, 5]
        }
    ]

is encoded as "exampleA EQUALS A || (exampleB TRUTHY && (exampleC STARTS_WITH example || exampleC ENDS_WITH C)) || exampleD BETWEEN 1 5".

Parsing

The parse method accepts MQL query string written and returns a pseudo abstract syntax tree. It does the inverse of the example above.

A compound condition MUST be comprised of conditions or compound conditions seperated by a logic operator i.e. && and ||. More information on valid conditions can be found in the metadata spec

Combining two conditions into a compound condition:
"fieldA TRUTHY && fieldB FALSY"
Combining a compound condition and a condition into a compound condition:
"(fieldA TRUTHY && fieldB TRUTHY) || fieldC TRUTHY"
Combining two compound conditions into a compound condition:
"(fieldA TRUTHY && fieldB TRUTHY) || (fieldC TRUTHY && fieldD TRUTHY)"

The MQL parser makes no assumptions in regards to order of operations, so a compound condition MUST NOT have different operators in the same logic level. Consider the following example:

"coditionA || conditionB && conditionC"

This MQL query is INVALID. The query can result in two different results based on which operation is validated first. MQL requires that one of these operations be grouped into a logic level that will be evaluated first.

"conditionA || (conditionB && conditionC)"

The MQL query does NOT need to be simplified. Redundant parentheses are allowed and will be cleaned up before parsing.