Redo docs

[paustint]

Description

I feel the docs are not very consumable / approachable and we should improve the examples and usages. Also remove the V2 stuff about ANTLR (maybe have a v2 section?)

[zac-prodly]

Hello. I recently discovered this library and am glad I did. Concerning the docs—they aren't bad, but there is at least one place that doesn't make sense to me. In the following code block, getComposedField is imported but then never used. And then later, parseWhereClause() is called, but I'm not seeing this method on the composer object returned from the Compose constructor. I'm actually wanting to use almost this exact functionality (build just a where clause), but I can't get this example to work.

import { Compose, getComposedField, parseQuery } from 'soql-parser-js';

const soql = `SELECT Id FROM Account WHERE Name = 'Foo'`;
const parsedQuery = parseQuery(soql);

// Results of Parsed Query:
  // const parsedQuery = {
  //   fields: [
  //     {
  //       type: 'Field',
  //       field: 'Id',
  //     },
  //   ],
  //   sObject: 'Account',
  //   where: {
  //     left: {
  //       field: 'Name',
  //       operator: '=',
  //       value: "'Foo'",
  //       literalType: 'STRING',
  //     },
  //   },
  // };

  // Create a new instance of the compose class and set the autoCompose to false to avoid composing the entire query
  const composer = new Compose(parsedQuery, { autoCompose: false });

  const whereClause = composer.parseWhereClause(parsedQuery.where);

  console.log(whereClause);
  // Name = 'Foo'
}

I decided to leave this comment here because it seemed to pertain to this issue, but let me know if you would prefer that I create a separate issue instead.

[paustint]

@zac-prodly - Hey, sorry about the docs being incorrect - I can confirm that parseWhereClause does not seem to exist in the codebase except for the docs 🤔

I think what you want to use is parseWhereOrHavingClause() - see unit test here with example https://github.com/paustint/soql-parser-js/blob/54253988f20a5acd88156522a3623d5892ac336e/test/test.spec.ts#L175

I will review the docs and get that section updated to be accurate - must have missed it on a refactor :D

[zac-prodly]

Just tested and it works great.

Thanks!

[zac-prodly]

@paustint - Wondering if this method of building just a part of the query such as the where clause still supports formatting with indentation? I can't seem to get it to work. Again, please let me know if this is not the appropriate forum for this question. Thanks

[paustint]

This is fine for support here, but feel free to open a new issue as well in the future.

I just tested and was able to get formatting to work without any issues. The only thing you might run into is that the formatter does assume that it is combined with the WHERE clause, so the indentation may not be perfect.

You need to explicitly set format: true and then you can optionally adjust any of the formatter options as you see fit.

import { Compose, parseQuery } from "soql-parser-js";

const query = parseQuery(
  `SELECT Id FROM Account WHERE (Id IN ('1', '2', '3') OR (NOT Id = '2') OR (Name LIKE '%FOO%' OR (Name LIKE '%ARM%' AND FOO = 'bar')))`
);
const compose = new Compose(query, {
  autoCompose: false,
  format: true,
  formatOptions: {
    newLineAfterKeywords: false,
    whereClauseOperatorsIndented: true,
  },
});

console.log(compose.parseWhereOrHavingClause(query.where));

[paustint]

@zac-prodly - I wanted to let you know that I just released a new version resolving #182 which adds support for both parsing and composing queries that are not fully formed.

Example - you can parse a query that is missing a SELECT or FROM clause as long as you pass allowPartialQuery=true and composeQuery now works with parts of the query object missing (fields and sobject).

const soql = `WHERE (Id IN ('1', '2', '3') OR (NOT Id = '2') OR (Name LIKE '%FOO%' OR (Name LIKE '%ARM%' AND FOO = 'bar'))`;

const parsedQuery = parseQuery(soql, { allowPartialQuery: true });

const composedQuery = composeQuery(parsedQuery, { format: true }); // returns original WHERE clause

isQueryValid(soql, { allowPartialQuery: true }); // true

[zac-prodly]

Awesome, thanks for letting me know!

Cheers, Zac

On Fri, Mar 11, 2022 at 2:32 PM Austin Turner @.***> wrote:

@zac-prodly https://github.com/zac-prodly - I wanted to let you know that I just released a new version resolving #182 https://github.com/paustint/soql-parser-js/issues/182 which adds support for both parsing and composing queries that are not fully formed.

Example - you can parse a query that is missing a SELECT or FROM clause as long as you pass allowPartialQuery=true and composeQuery now works with parts of the query object missing (fields and sobject).

const soql = WHERE (Id IN ('1', '2', '3') OR (NOT Id = '2') OR (Name LIKE '%FOO%' OR (Name LIKE '%ARM%' AND FOO = 'bar')); const parsedQuery = parseQuery(soql, { allowPartialQuery: true }); const composedQuery = composeQuery(parsedQuery, { format: true }); // returns original WHERE clause isQueryValid(soql, { allowPartialQuery: true }); // true

— Reply to this email directly, view it on GitHub https://github.com/paustint/soql-parser-js/issues/172#issuecomment-1065495945, or unsubscribe https://github.com/notifications/unsubscribe-auth/ASEKVM54TZRVIYL4T5WZ3J3U7OUWLANCNFSM5JRZICQA . You are receiving this because you were mentioned.Message ID: @.***>