raql v0.0.4

🦸🏻‍♀️ RAQL

RAQL is a Really Awesome Query Language.

This package contains the javascript parser (NodeJS or Browser) to transform RAQL queries into Abstract Syntax Trees (ASTs), providing a structured representation of the query which can be processed or analyzed further.

Install

npm install raql

Features

• Highly Compatible: Understands a wide range of filtering syntaxes.
• Robust: Thoroughly tested, ensuring accurate parsing.
• Useful Debugging Information: In case of syntax errors, it provides meaningful error messages.
• (TODO) Extensible: Can be extended to support additional syntaxes in the future.

Usage

To use the RAQLParser, you need to instantiate it and then feed in the RAQL string that you wish to parse:

    import { Parser } = 'raql';
    
    let parser = new RAQLParser();
    
    parser.feed(
      'dogs.$.names[1][2][3].$.name = "maggie" || startsWith(user.name, username)'
    );

    expect(parser.results[0]).toEqual({
      "type": "LOGIC",
      "operator": "||",
      "parameters": [
        {
          "operator": "=",
          "parameters": [
            {
              "type": "PATH",
              "value": [
                {
                  "type": "IDENTIFIER",
                  "value": "dogs",
                },
                {
                  "type": "ARRAY_DOT_NOTATION",
                  "value": ".$.",
                },
                {
                  "type": "IDENTIFIER",
                  "value": "names",
                },
                {
                  "type": "BRACKET_NOTATION",
                  "value": "[1]",
                },
                {
                  "type": "BRACKET_NOTATION",
                  "value": "[2]",
                },
                {
                  "type": "BRACKET_NOTATION",
                  "value": "[3]",
                },
                {
                  "type": "ARRAY_DOT_NOTATION",
                  "value": ".$.",
                },
                {
                  "type": "IDENTIFIER",
                  "value": "name",
                },
              ],
            },
            {
              "type": "STRING",
              "value": "maggie",
            },
          ],
          "type": "COMPARISON",
        },
        {
          "field": {
            "type": "PATH",
            "value": [
              {
                "type": "IDENTIFIER",
                "value": "user",
              },
              {
                "type": "DOT_NOTATION",
                "value": ".",
              },
              {
                "type": "IDENTIFIER",
                "value": "name",
              },
            ],
          },
          "parameters": [
            {
              "type": "PATH",
              "value": [
                {
                  "type": "IDENTIFIER",
                  "value": "username",
                },
              ],
            },
          ],
          "type": "FN_STARTS_WITH",
        },
      ],
    });

// === Query to AST examples ===

examples['1 > 2 || (( size(PATH) ))'] = `
{
  "operator": "||",
  "parameters": [
    {
      "operator": ">",
      "parameters": [
        {
          "type": "NUMBER",
          "value": "1",
        },
        {
          "type": "NUMBER",
          "value": "2",
        },
      ],
      "type": "COMPARISON",
    },
    {
      "parameters": [
        {
          "parameters": [
            {
              "field": {
                "type": "PATH",
                "value": [
                  {
                    "type": "IDENTIFIER",
                    "value": "PATH",
                  },
                ],
              },
              "type": "FN_SIZE",
            },
          ],
          "type": "GROUPED_OPERATION",
        },
      ],
      "type": "GROUPED_OPERATION",
    },
  ],
  "type": "LOGIC",
}
`;

examples['between(path, "value1", "value2")'] = `
{
  "field": {
    "type": "PATH",
    "value": [
      {
        "type": "IDENTIFIER",
        "value": "path",
      },
    ],
  },
  "parameters": [
    {
      "type": "STRING",
      "value": "value1",
    },
    {
      "type": "STRING",
      "value": "value2",
    },
  ],
  "type": "FN_BETWEEN",
}
`;

examples['dogs.$.names[1][2][3].$.name = "maggie" || startsWith(user.name, username)'] = `
{
  "operator": "||",
  "parameters": [
    {
      "operator": "=",
      "parameters": [
        {
          "type": "PATH",
          "value": [
            {
              "type": "IDENTIFIER",
              "value": "dogs",
            },
            {
              "type": "ARRAY_DOT_NOTATION",
              "value": ".$.",
            },
            {
              "type": "IDENTIFIER",
              "value": "names",
            },
            {
              "type": "BRACKET_NOTATION",
              "value": "[1]",
            },
            {
              "type": "BRACKET_NOTATION",
              "value": "[2]",
            },
            {
              "type": "BRACKET_NOTATION",
              "value": "[3]",
            },
            {
              "type": "ARRAY_DOT_NOTATION",
              "value": ".$.",
            },
            {
              "type": "IDENTIFIER",
              "value": "name",
            },
          ],
        },
        {
          "type": "STRING",
          "value": "maggie",
        },
      ],
      "type": "COMPARISON",
    },
    {
      "field": {
        "type": "PATH",
        "value": [
          {
            "type": "IDENTIFIER",
            "value": "user",
          },
          {
            "type": "DOT_NOTATION",
            "value": ".",
          },
          {
            "type": "IDENTIFIER",
            "value": "name",
          },
        ],
      },
      "parameters": [
        {
          "type": "PATH",
          "value": [
            {
              "type": "IDENTIFIER",
              "value": "username",
            },
          ],
        },
      ],
      "type": "FN_STARTS_WITH",
    },
  ],
  "type": "LOGIC",
}
`;

examples['exists(maggie) || 1 >= 18'] = `
{
  "operator": "||",
  "parameters": [
    {
      "field": {
        "type": "PATH",
        "value": [
          {
            "type": "IDENTIFIER",
            "value": "maggie",
          },
        ],
      },
      "type": "FN_EXISTS",
    },
    {
      "operator": ">=",
      "parameters": [
        {
          "type": "NUMBER",
          "value": "1",
        },
        {
          "type": "NUMBER",
          "value": "18",
        },
      ],
      "type": "COMPARISON",
    },
  ],
  "type": "LOGIC",
}
`;

examples['regex(path, /^Antonio/mig)'] = `
{
  "field": {
    "type": "PATH",
    "value": [
      {
        "type": "IDENTIFIER",
        "value": "path",
      },
    ],
  },
  "parameters": [
    {
      "type": "REGEX",
      "value": "/^Antonio/mig",
    },
  ],
  "type": "FN_REGEX",
}
`;

examples['size(PATH)'] = `
{
  "field": {
    "type": "PATH",
    "value": [
      {
        "type": "IDENTIFIER",
        "value": "PATH",
      },
    ],
  },
  "type": "FN_SIZE",
}
`;

examples['startsWith(path, "value1")'] = `
{
  "field": {
    "type": "PATH",
    "value": [
      {
        "type": "IDENTIFIER",
        "value": "path",
      },
    ],
  },
  "parameters": [
    {
      "type": "STRING",
      "value": "value1",
    },
  ],
  "type": "FN_STARTS_WITH",
}
`;

examples['type(path, "value1")'] = `
{
  "field": {
    "type": "PATH",
    "value": [
      {
        "type": "IDENTIFIER",
        "value": "path",
      },
    ],
  },
  "parameters": [
    {
      "type": "STRING",
      "value": "value1",
    },
  ],
  "type": "FN_TYPE",
}

Contributions

Contributions to RAQL Parser are very welcome! Feel free to submit a pull request or create an issue if you find a bug or would like to suggest a feature.

License

RAQL Parser is licensed under the MIT license.