Version 2.0 release

Author: paustint

.release-it.json

@@ -5,6 +5,6 @@
   "hooks": {
     "before:init": ["npm test"],
     "after:bump": "npm run build",
-    "after:release": "cd docs && npm install soql-parser-js@${version} && git add package*.json && git commit -m \"Updated docs version\" && git push && npm run deploy"
+    "after:release": "npm run copy-tc-to-docs && cd docs && npm install soql-parser-js@${version} && git add package*.json && git commit -m \"Updated docs version\" && git push && npm run deploy"
   }
 }

CHANGELOG.md

@@ -10,10 +10,12 @@ With this change, the data model was reviewed and analyzed, and there are some s
 
 #### Bundle Size
 
-To compare the bundle size, the following small program was written and then compiled using the default configuration of webpack, and the output bundle was compared.
+To compare the bundle size, the following small program was written and then compiled using the default configuration of webpack, and the resulting webpack bundle was compared to determine the full size of the library.
+
+Minified, uncompressed:
 
 - Version 1.x: **545kb**
-- Version 2.0: **197kb**
+- Version 2.0: **207kb**
 
 ```javascript
 var soqlParser = require('soql-parser-js');
@@ -26,11 +28,24 @@ console.log('soql', soql);
 
 #### Benchmarks
 
-Here is an example benchmark of parsing all the unit tests 1,000 times
+Performance testing was done by iterating the unit tests 60K times, here are the results:
+
+**Version 1.x parser**
 
 ```
-OLD PARSER: ~6.2 seconds for ~60K parses
-NEW PARSER: ~2.25 seconds for 60K parses
+Library import (startup time): 0.8671 milliseconds
+Parsing: 58 X 1000 = 58000 iterations.
+Duration: 5.7648 seconds
+Average of 0.0994 milliseconds per query
+```
+
+**Version 2.0 parser**
+
+```
+Library import (startup time): 1.3793 milliseconds
+Parsing: 87 X 1000 = 87000 iterations.
+Duration: 3.6582 seconds
+Average of 0.0420 milliseconds per query
 ```
 
 ### Breaking Changes 🔥
@@ -44,9 +59,9 @@ NEW PARSER: ~2.25 seconds for 60K parses
   - `TRUE`, `FALSE`, and all functions except those listed below will always be returned in uppercase, regardless of case of input.
   - **Exceptions**:
     - `toLabel`, `convertTimezone`, `convertCurrency` will always be in camelCase.
-  - Added new available types for `DateLiteral` and `DateNLiteral`.
+  - Added types for `DateLiteral` and `DateNLiteral` values. If you are using TypeScript, you can utilize these types.
 - A new `LiteralType` value was added for `APEX_BIND_VARIABLE`.
-- When composing functions in a where clause or group by clause, the `rawValue` will be preferred (if exists) (no change here), but if rawValue is not provided, then the function will be composed using the `functionName` and `parameters`.
+- When composing functions in a where clause or group by clause, the `rawValue` will be preferred (if it exists) (no change here), but if rawValue is not provided, then the function will be composed using the `functionName` and `parameters`.
 - A new `LiteralType` value was added for `INTEGER_WITH_CURRENCY_PREFIX` and `DECIMAL_WITH_CURRENCY_PREFIX`. e.x. `USD500.01`
 
 #### Compose Query
@@ -93,6 +108,69 @@ export interface FormatOptions {
   - Added support for `usingScope` - https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_using_scope.htm?search_text=format()
 
 ```diff
+export type LiteralType =
+  | 'STRING'
+  | 'INTEGER'
+  | 'DECIMAL'
++ | 'INTEGER_WITH_CURRENCY_PREFIX'
++ | 'DECIMAL_WITH_CURRENCY_PREFIX'
+  | 'BOOLEAN'
+  | 'NULL'
+  | 'DATETIME'
+  | 'DATE'
+  | 'DATE_LITERAL'
+  | 'DATE_N_LITERAL'
++ | 'APEX_BIND_VARIABLE';
+
++ export type DateLiteral =
++   | 'YESTERDAY'
++   | 'TODAY'
++   | 'TOMORROW'
++   | 'LAST_WEEK'
++   | 'THIS_WEEK'
++   | 'NEXT_WEEK'
++   | 'LAST_MONTH'
++   | 'THIS_MONTH'
++   | 'NEXT_MONTH'
++   | 'LAST_90_DAYS'
++   | 'NEXT_90_DAYS'
++   | 'THIS_QUARTER'
++   | 'LAST_QUARTER'
++   | 'NEXT_QUARTER'
++   | 'THIS_YEAR'
++   | 'LAST_YEAR'
++   | 'NEXT_YEAR'
++   | 'THIS_FISCAL_QUARTER'
++   | 'LAST_FISCAL_QUARTER'
++   | 'NEXT_FISCAL_QUARTER'
++   | 'THIS_FISCAL_YEAR'
++   | 'LAST_FISCAL_YEAR'
++   | 'NEXT_FISCAL_YEAR';
+
++ export type DateNLiteral =
++   | 'YESTERDAY'
++   | 'NEXT_N_DAYS'
++   | 'LAST_N_DAYS'
++   | 'N_DAYS_AGO'
++   | 'NEXT_N_WEEKS'
++   | 'LAST_N_WEEKS'
++   | 'N_WEEKS_AGO'
++   | 'NEXT_N_MONTHS'
++   | 'LAST_N_MONTHS'
++   | 'N_MONTHS_AGO'
++   | 'NEXT_N_QUARTERS'
++   | 'LAST_N_QUARTERS'
++   | 'N_QUARTERS_AGO'
++   | 'NEXT_N_YEARS'
++   | 'LAST_N_YEARS'
++   | 'N_YEARS_AGO'
++   | 'NEXT_N_FISCAL_QUARTERS'
++   | 'LAST_N_FISCAL_QUARTERS'
++   | 'N_FISCAL_QUARTERS_AGO'
++   | 'NEXT_N_FISCAL_YEARS'
++   | 'LAST_N_FISCAL_YEARS'
++   | 'N_FISCAL_YEARS_AGO';
+
 export interface Field {
   type: 'Field';
   field: string;
@@ -106,7 +184,7 @@ export interface FieldFunctionExpression {
 - fn: string;
 + functionName: string;
 - parameters?: string[] | FieldFunctionExpression[];
-+ parameters?: (string | FieldFunctionExpression)[];
++ parameters: (string | FieldFunctionExpression)[];
   alias?: string;
   isAggregateFn?: boolean;
   rawValue?: string;

README.md

@@ -12,9 +12,11 @@
 
 1. Parse SOQL queries into a common `Query` data structure.
 2. Compose a `Query` data structure back into a SOQL query.
-3. Validate a query to check if the syntax is valid. (Note: even if a query is valid, it might still be invalid based on your org configuration)
+3. Validate a query to check if the syntax is valid. (Note: even if a query is returned as valid, it might still be invalid based on your Salesforce configuration)
 
-This library uses [Chevrotain](https://github.com/SAP/chevrotain) to parse queries. Prior to version 2.0.0, [antlr4](https://github.com/antlr/antlr4) was used. The move to Chevrotain provided a 35% performance improvement and resulted in a 36% decrease in bundle size. :tada:
+This library uses [Chevrotain](https://github.com/SAP/chevrotain) to parse queries. Prior to version 2.0.0, [antlr4](https://github.com/antlr/antlr4) was used. The move to Chevrotain provided a significant performance increase and decrease in bundle size. :tada:
+
+Migrating from version 1 to version 2? [Check out the changelog](CHANGELOG.md#200) for a full list of changes.
 
 Want to try it out? [Check out the demo](https://paustint.github.io/soql-parser-js/).
 
@@ -39,24 +41,32 @@ isQueryValid('SELECT Id Foo FROM Baz'); // false
 | ------------ | ------------------------------------------------------ | ------------------------------------------ |
 | parseQuery   | Parse a SOQL query string into a Query data structure. | soql: Query<br> config?: ParseQueryConfig  |
 | isQueryValid | Returns true if the query was able to be parsed.       | soql: Query<br> config?: ParseQueryConfig  |
-| composeQuery | Turn a Query object back into a SOQL statement         | soql: Query<br> config?: SoqlComposeConfig |
+| composeQuery | Turn a Query object back into a SOQL statement.        | soql: Query<br> config?: SoqlComposeConfig |
 | formatQuery  | Format a SOQL query string.                            | soql: Query<br> config?: FormatOptions     |
 
+## Utility Functions
+
+| Function           | Description                                                                                                                                                               | Arguments                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| getField           | Convenience method to construct fields in the correct format when using `composeQuery()`. Look in the data models section below for the structure of `ComposeFieldInput`. | input: `string | ComposeFieldInput`        |
+| isSubquery         | Returns `true` if the data passed in is a subquery.                                                                                                                       | query: `Query | Subquery`                  |
+| getFlattenedFields | Flatten a Salesforce record based on the parsed SOQL Query.                                                                                                               | soql: Query<br> config?: SoqlComposeConfig |
+
 **ParseQueryConfig**
 
-| Property               | Type    | Description                                                                                   | required | default |
-| ---------------------- | ------- | --------------------------------------------------------------------------------------------- | -------- | ------- |
-| allowApexBindVariables | boolean | Determines if apex variables are allowed in parsed query. Example: `WHERE Id IN :accountIds`. | FALSE    | FALSE   |
+| Property               | Type    | Description                                                                                          | required | default |
+| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------- | -------- | ------- |
+| allowApexBindVariables | boolean | Determines if apex variables are allowed in parsed query. Example: `WHERE Id IN :accountIds`.        | FALSE    | FALSE   |
+| logErrors              | boolean | If true, then additional detail will be logged to the console if there is a lexing or parsing error. | FALSE    | FALSE   |
 
 **SoqlComposeConfig**
 
-| Property         | Type          | Description                                                                                                                                                                                                              | required | default |
-| ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
-| format           | boolean       | Apply formatting the the composed query. This will result in a multi-line soql statement.                                                                                                                                | FALSE    | TRUE    |
-| formatOptions    | FormatOptions | Options to apply to the formatter.                                                                                                                                                                                       | FALSE    |         |
-| autoCompose      | boolean       | If you need to compose just part of a query, you can create your own instance of the Compose class and set this to false, then call any methods that you need to just for what you would like to turn into a SOQL query. | FALSE    | TRUE    |
-| useRawValueForFn | boolean       | When composing WHERE/GROUP BY functions, prefer the `rawValue` property instead of using `functionName` and `parameters` to compose the query.                                                                           | FALSE    | TRUE    |
-| logging          | boolean       | Print out logging statements to the console about the format operation.                                                                                                                                                  | FALSE    | FALSE   |
+| Property      | Type          | Description                                                                                                                                                                                                              | required | default |
+| ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
+| format        | boolean       | Apply formatting the the composed query. This will result in a multi-line soql statement.                                                                                                                                | FALSE    | TRUE    |
+| formatOptions | FormatOptions | Options to apply to the formatter.                                                                                                                                                                                       | FALSE    |         |
+| autoCompose   | boolean       | If you need to compose just part of a query, you can create your own instance of the Compose class and set this to false, then call any methods that you need to just for what you would like to turn into a SOQL query. | FALSE    | TRUE    |
+| logging       | boolean       | Print out logging statements to the console about the format operation.                                                                                                                                                  | FALSE    | FALSE   |
 
 **FormatOptions**
 
@@ -65,7 +75,7 @@ isQueryValid('SELECT Id Foo FROM Baz'); // false
 | numIndent                    | number  | The number of tab characters to indent.                                                                                              | FALSE    | 1       |
 | fieldMaxLineLength           | number  | The number of characters that the fields should take up before making a new line. Set this to 1 to have every field on its own line. | FALSE    | 60      |
 | fieldSubqueryParensOnOwnLine | boolean | If true, the opening and closing parentheses will be on their own line for subqueries.                                               | FALSE    | TRUE    |
-| whereClauseOperatorsIndented | boolean | If true, indents the where clause operators                                                                                          | FALSE    | FALSE   |
+| whereClauseOperatorsIndented | boolean | If true, indents the where clause operators.                                                                                         | FALSE    | FALSE   |
 | logging                      | boolean | Print out logging statements to the console about the format operation.                                                              | FALSE    | FALSE   |
 
 ## Examples
@@ -139,7 +149,6 @@ console.log(JSON.stringify(soqlQuery, null, 2));
 
 ```typescript
 import { isQueryValid } from 'soql-parser-js';
-// var soqlParserJs = require('soql-parser-js'); // node's require format - usage: soqlParserJs.parseQuery()
 
 const invalidSoql = `SELECT UserId, COUNT(Id) Account`;
 const validSoql = `SELECT UserId, COUNT(Id) Account`;
@@ -158,7 +167,7 @@ These examples show building your own Query object with the minimum required fie
 
 Some utility methods have been provided to make it easier to build the field data structures.
 
-**Note:** Some operators may be converted to upper case (e.x. NOT, AND)
+**Note:** Some operators may be converted to uppercase (e.x. NOT, AND)
 
 **Note:** There are a number of fields populated on the Query object when `parseQuery()` is called that are not required to compose a query. Look at the examples below and the comments in the data model for more information.
 
@@ -369,12 +378,14 @@ WHERE Name LIKE 'a%'
 The following utility functions are available:
 
 1. `getField(input: string | ComposeFieldInput)`
-   1. Convenience method to construct fields in the correct data format. See example usage in the Compose example.
+   1. Convenience method to construct fields in the correct format. See data model below for the various input types as well as example usage in the Compose examples above.
+   2. returns one of the following data structures: `SoqlModels.FieldFunctionExpression | SoqlModels.Field | SoqlModels.FieldRelationship | SoqlModels.FieldSubquery | SoqlModels.FieldTypeOf`.
 2. `isSubquery(query: Query | Subquery)`
-   1. Returns true if the data passed in is a subquery
+   1. Returns `true` if the data passed in is a subquery
 3. `getFlattenedFields(query: Query)`
    1. Flatten a Salesforce record based on the parsed SOQL Query. this is useful if you have relationships in your query and want to show the results in a table, using `.` dot notation for the relationship field headings.
-   2. Refer to `tests/publicUtils.spec.ts` for usage examples.
+   2. Returns an array of strings.
+   3. Refer to `tests/publicUtils.spec.ts` for usage examples.
 
 ## Data Models
 
@@ -563,10 +574,10 @@ export interface HavingClause {
 }
 
 export interface FunctionExp {
-  rawValue?: string; // only used for compose fields if useRawValueForFn=true. Should be formatted like this: Count(Id)
-  functionName?: string; // only used for compose fields if useRawValueForFn=false, not used for compose, will be populated if SOQL is parsed
+  rawValue?: string; // This is the entire text of the function, such as Count(Id). When composing a query, if this is populated this will be used to build output SOQL query.
+  functionName?: string; // When composing a query, if rawValue is undefined/null this will be used to build the SOQL query.
   alias?: string;
-  parameters?: (string | FunctionExp)[]; // only used for compose fields if useRawValueForFn=false, not used for compose, will be populated if SOQL is parsed
+  parameters?: (string | FunctionExp)[]; // When composing a query, if rawValue is undefined/null this will be used to build the SOQL query.
   isAggregateFn?: boolean; // not used for compose, will be populated if SOQL is parsed
 }
 
@@ -581,6 +592,40 @@ export interface WithDataCategoryCondition {
 }
 ```
 
+## Compose / Utility
+
+```typescript
+export type ComposeFieldInput = ComposeField | ComposeFieldFunction | ComposeFieldRelationship | ComposeFieldSubquery | ComposeFieldTypeof;
+
+export interface ComposeField {
+  field: string;
+  objectPrefix?: string;
+}
+
+export interface ComposeFieldFunction {
+  // @Deprecated - will still be used if populated, but `functionName` is checked first and preferred
+  fn?: string;
+  functionName: string;
+  parameters?: string | SoqlModels.FieldFunctionExpression | (string | SoqlModels.FieldFunctionExpression)[];
+  alias?: string;
+}
+
+export interface ComposeFieldRelationship {
+  field: string;
+  relationships: string[];
+  objectPrefix?: string;
+}
+
+export interface ComposeFieldSubquery {
+  subquery?: SoqlModels.Subquery;
+}
+
+export interface ComposeFieldTypeof {
+  field: string;
+  conditions: SoqlModels.FieldTypeOfCondition[];
+}
+```
+
 ## Contributing
 
 All contributions are welcome on the project. Please read the [contribution guidelines](https://github.com/paustint/soql-parser-js/blob/master/CONTRIBUTING.md).