@jetstreamapp/soql-parser-js 7.4.1 → 8.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,10 +32,10 @@ Migrating from version 2 to version 3? [Check out the changelog](CHANGELOG.md#30
32
32
 
33
33
  ## Compatibility
34
34
 
35
- **Node**: version 11 or higher, or a polyfill for [Array.flat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat)
35
+ **Node**: version 20 or higher
36
36
  **Browser**: Tested in all modern browsers, may not work with older browsers.
37
37
 
38
- The **commander** dependency is only required for the cli, the other two dependencies **chevrotain** and **lodash.get** are bundled with the non-cli code.
38
+ This library has no runtime dependencies - the parser, composer, formatter and cli are all self contained.
39
39
 
40
40
  ## Quick Start
41
41
 
@@ -52,6 +52,42 @@ isQueryValid('SELECT Id, Foo FROM Baz'); // true
52
52
  isQueryValid('SELECT Id Foo FROM Baz'); // false
53
53
  ```
54
54
 
55
+ ### `FORMULA()` in `WHERE`
56
+
57
+ The parser supports Salesforce's arithmetic [`FORMULA()` WHERE function](https://developer.salesforce.com/docs/atlas.en-us.264.0.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_formula.htm).
58
+ The quoted expression must contain two field references separated by `+` or `-`; `FORMULA()` is not
59
+ accepted in `SELECT`, `HAVING`, `GROUP BY`, or `ORDER BY`. Only comparison operators may follow it,
60
+ and Apex bind variables are rejected because Salesforce does not support them after `FORMULA()`.
61
+ Salesforce ships this function as a Beta feature as of Summer '26.
62
+
63
+ ```typescript
64
+ const query = parseQuery("SELECT Id FROM Opportunity WHERE FORMULA('Amount - ExpectedRevenue') > 100");
65
+
66
+ console.log(query.where?.left);
67
+ // {
68
+ // fn: {
69
+ // functionName: 'FORMULA',
70
+ // parameters: ["'Amount - ExpectedRevenue'"],
71
+ // rawValue: "FORMULA('Amount - ExpectedRevenue')",
72
+ // formula: {
73
+ // type: 'BinaryExpression',
74
+ // operator: '-',
75
+ // left: { type: 'FieldReference', parts: ['Amount'] },
76
+ // right: { type: 'FieldReference', parts: ['ExpectedRevenue'] },
77
+ // },
78
+ // },
79
+ // operator: '>',
80
+ // value: '100',
81
+ // literalType: 'INTEGER',
82
+ // }
83
+ ```
84
+
85
+ The nested formula AST is also accepted by `composeQuery()`. When `formula` is present, `FORMULA()`
86
+ is rebuilt from that AST and `rawValue` is ignored; a `FORMULA` function without `formula` composes
87
+ from `rawValue` like any other function. `parameters` holds the normalized expression and `rawValue`
88
+ keeps the original text. The parser validates the expression's shape, but it cannot validate
89
+ metadata-dependent Salesforce rules such as field data types or type compatibility.
90
+
55
91
  ## Available Features
56
92
 
57
93
  | Function | Description | Arguments |
@@ -79,6 +115,7 @@ Many of hte utility functions are provided to easily determine the shape of spec
79
115
  | stripComments | Removes comments from a query string without otherwise modifying it. Returns the original string as-is if there are no comments. See [Comments in queries](#comments-in-queries). | soql: `string` |
80
116
  | isSubquery | Returns `true` if the data passed in is a subquery. | query: `Query \| Subquery` |
81
117
  | isFieldSubquery | Returns `true` if the data passed in is a FieldSubquery. | value: `any` |
118
+ | isFormulaFunction | Returns `true` if the value is a `FORMULA()` function that carries a nested `formula` AST. | value: `FunctionExp \| FormulaFunctionExp` |
82
119
  | isWhereClauseWithRightCondition | Returns `true` if the value passed in is a `WhereClause` with an `operator` and `right` property | value: `WhereClause` |
83
120
  | isHavingClauseWithRightCondition | Returns `true` if the value passed in is a `HavingClause` with an `operator` and `right` property | value: `HavingClause` |
84
121
  | isWhereOrHavingClauseWithRightCondition | Returns `true` if the value passed in is a `WhereClause` or `HavingClause` with an `operator` and `right` property | value: `WhereClause \| HavingClause` |
@@ -106,21 +143,22 @@ Many of hte utility functions are provided to easily determine the shape of spec
106
143
 
107
144
  | Property | Type | Description | required | default |
108
145
  | ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
109
- | format | boolean | Apply formatting the the composed query. This will result in a multi-line soql statement. | FALSE | TRUE |
146
+ | format | boolean | Apply formatting to the composed query. This will result in a multi-line soql statement. | FALSE | FALSE |
110
147
  | formatOptions | FormatOptions | Options to apply to the formatter. | FALSE | |
111
148
  | 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 |
112
149
  | logging | boolean | Print out logging statements to the console about the format operation. | FALSE | FALSE |
113
150
 
114
151
  **FormatOptions**
115
152
 
116
- | Property | Type | Description | required | default |
117
- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
118
- | numIndent | number | The number of tab characters to indent. | FALSE | 1 |
119
- | 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 |
120
- | fieldSubqueryParensOnOwnLine | boolean | If true, the opening and closing parentheses will be on their own line for subqueries. | FALSE | TRUE |
121
- | newLineAfterKeywords | boolean | Adds a new line and indent after all keywords (such as SELECT, FROM, WHERE, ORDER BY, etc..) Setting this to true will add new lines in other places as well, such as complex WHERE clauses | FALSE | FALSE |
122
- | ~~whereClauseOperatorsIndented~~ | boolean | **Deprecated** If true, indents the where clause operators. | FALSE | FALSE |
123
- | logging | boolean | Print out logging statements to the console about the format operation. | FALSE | FALSE |
153
+ | Property | Type | Description | required | default |
154
+ | -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
155
+ | numIndent | number | The number of times `indentString` is repeated for each level of indentation. | FALSE | 1 |
156
+ | indentString | string | The string used for one unit of indentation. e.g. `{ indentString: ' ', numIndent: 2 }` indents with two spaces per level. Must be whitespace only (spaces and/or tabs); other values are ignored. | FALSE | `\t` |
157
+ | 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. Also applies to GROUP BY and ORDER BY items. | FALSE | 60 |
158
+ | fieldSubqueryParensOnOwnLine | boolean | If true, the opening and closing parentheses will be on their own line for subqueries. | FALSE | TRUE |
159
+ | newLineAfterKeywords | boolean | Adds a new line and indent after all keywords (such as SELECT, FROM, WHERE, ORDER BY, etc..) Setting this to true will add new lines in other places as well, such as complex WHERE clauses | FALSE | FALSE |
160
+ | ~~whereClauseOperatorsIndented~~ | boolean | **Deprecated** If true, indents the where clause operators. | FALSE | FALSE |
161
+ | ~~logging~~ | boolean | **Deprecated** - this is ignored and will be removed in a future version. | FALSE | FALSE |
124
162
 
125
163
  ## Examples
126
164
 
@@ -467,7 +505,7 @@ These are used internally, but are public and available for use.
467
505
  parseQuery(query: Query | Subquery): string;
468
506
  parseFields(fields: FieldType[]): { text: string; typeOfClause?: string[] }[];
469
507
  parseTypeOfField(typeOfField: FieldTypeOf): string[];
470
- parseWhereOrHavingClause(whereOrHaving: WhereClause | HavingClause, tabOffset = 0, priorConditionIsNegation = false): string;
508
+ parseWhereOrHavingClause(whereOrHaving: WhereClause | HavingClause, indent = 0): string; // indent only applies when format is enabled
471
509
  parseGroupByClause(groupBy: GroupByClause | GroupByClause[]): string;
472
510
  parseOrderBy(orderBy: OrderByClause | OrderByClause[]): string;
473
511
  parseWithDataCategory(withDataCategory: WithDataCategoryClause): string;
@@ -478,7 +516,7 @@ parseWithDataCategory(withDataCategory: WithDataCategoryClause): string;
478
516
  ## Format Query
479
517
 
480
518
  This function is provided as a convenience and just calls parse and compose.
481
- [Check out the demo](https://jetstreamapp.github.io/soql-parser-js/) to see the outcome of the various format options.
519
+ [Check out the playground](https://soql-parser-js.getjetstream.app/playground) to see the outcome of the various format options.
482
520
 
483
521
  ```typescript
484
522
  import { formatQuery } from '@jetstreamapp/soql-parser-js';
@@ -486,20 +524,17 @@ import { formatQuery } from '@jetstreamapp/soql-parser-js';
486
524
  const query = `SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue, BillingAddress, BillingCity, BillingCountry, BillingGeocodeAccuracy, ShippingStreet, Sic, SicDesc, Site, SystemModstamp, TickerSymbol, Type, Website, (SELECT Id, Name, AccountId, Amount, CampaignId, CloseDate, CreatedById, Type FROM Opportunities), (SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue, BillingAddress, Website FROM ChildAccounts) FROM Account WHERE Name LIKE 'a%' OR Name LIKE 'b%' OR Name LIKE 'c%'`;
487
525
 
488
526
  const formattedQuery1 = formatQuery(query);
489
- const formattedQuery2 = formatQuery(query, {
490
- fieldMaxLineLength: 20,
491
- fieldSubqueryParensOnOwnLine: false,
492
- whereClauseOperatorsIndented: true,
493
- });
494
- const formattedQuery3 = formatQuery(query, { fieldSubqueryParensOnOwnLine: true, whereClauseOperatorsIndented: true });
527
+ const formattedQuery2 = formatQuery(query, { fieldMaxLineLength: 20, fieldSubqueryParensOnOwnLine: false });
528
+ const formattedQuery3 = formatQuery(query, { newLineAfterKeywords: true });
529
+ const formattedQuery4 = formatQuery(query, { indentString: ' ', numIndent: 2, fieldMaxLineLength: 40 });
495
530
  ```
496
531
 
497
532
  ```sql
498
533
  -- formattedQuery1
499
534
  SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
500
- BillingAddress, BillingCity, BillingCountry, BillingGeocodeAccuracy,
501
- ShippingStreet, Sic, SicDesc, Site, SystemModstamp, TickerSymbol, Type,
502
- Website,
535
+ BillingAddress, BillingCity, BillingCountry,
536
+ BillingGeocodeAccuracy, ShippingStreet, Sic, SicDesc, Site,
537
+ SystemModstamp, TickerSymbol, Type, Website,
503
538
  (
504
539
  SELECT Id, Name, AccountId, Amount, CampaignId, CloseDate,
505
540
  CreatedById, Type
@@ -512,25 +547,34 @@ SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
512
547
  )
513
548
  FROM Account
514
549
  WHERE Name LIKE 'a%'
515
- OR Name LIKE 'b%'
516
- OR Name LIKE 'c%'
550
+ OR Name LIKE 'b%'
551
+ OR Name LIKE 'c%'
517
552
 
518
553
  -- formattedQuery2
519
554
  SELECT Id, Name,
520
- AccountNumber, AccountSource,
521
- AnnualRevenue, BillingAddress,
522
- BillingCity, BillingCountry,
523
- BillingGeocodeAccuracy, ShippingStreet,
555
+ AccountNumber,
556
+ AccountSource,
557
+ AnnualRevenue,
558
+ BillingAddress,
559
+ BillingCity,
560
+ BillingCountry,
561
+ BillingGeocodeAccuracy,
562
+ ShippingStreet,
524
563
  Sic, SicDesc, Site,
525
- SystemModstamp, TickerSymbol, Type,
564
+ SystemModstamp,
565
+ TickerSymbol, Type,
526
566
  Website,
527
567
  (SELECT Id, Name,
528
- AccountId, Amount, CampaignId,
529
- CloseDate, CreatedById, Type
568
+ AccountId, Amount,
569
+ CampaignId,
570
+ CloseDate,
571
+ CreatedById, Type
530
572
  FROM Opportunities),
531
573
  (SELECT Id, Name,
532
- AccountNumber, AccountSource,
533
- AnnualRevenue, BillingAddress,
574
+ AccountNumber,
575
+ AccountSource,
576
+ AnnualRevenue,
577
+ BillingAddress,
534
578
  Website
535
579
  FROM ChildAccounts)
536
580
  FROM Account
@@ -538,26 +582,54 @@ WHERE Name LIKE 'a%'
538
582
  OR Name LIKE 'b%'
539
583
  OR Name LIKE 'c%'
540
584
 
541
-
542
585
  -- formattedQuery3
543
- SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
544
- BillingAddress, BillingCity, BillingCountry, BillingGeocodeAccuracy,
545
- ShippingStreet, Sic, SicDesc, Site, SystemModstamp, TickerSymbol, Type,
546
- Website,
586
+ SELECT
587
+ Id, Name, AccountNumber, AccountSource, AnnualRevenue,
588
+ BillingAddress, BillingCity, BillingCountry,
589
+ BillingGeocodeAccuracy, ShippingStreet, Sic, SicDesc, Site,
590
+ SystemModstamp, TickerSymbol, Type, Website,
547
591
  (
548
- SELECT Id, Name, AccountId, Amount, CampaignId, CloseDate,
592
+ SELECT
593
+ Id, Name, AccountId, Amount, CampaignId, CloseDate,
549
594
  CreatedById, Type
550
- FROM Opportunities
595
+ FROM
596
+ Opportunities
551
597
  ),
552
598
  (
553
- SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
599
+ SELECT
600
+ Id, Name, AccountNumber, AccountSource, AnnualRevenue,
554
601
  BillingAddress, Website
555
- FROM ChildAccounts
602
+ FROM
603
+ ChildAccounts
556
604
  )
557
- FROM Account
558
- WHERE Name LIKE 'a%'
605
+ FROM
606
+ Account
607
+ WHERE
608
+ Name LIKE 'a%'
559
609
  OR Name LIKE 'b%'
560
610
  OR Name LIKE 'c%'
611
+
612
+ -- formattedQuery4
613
+ SELECT Id, Name, AccountNumber, AccountSource,
614
+ AnnualRevenue, BillingAddress,
615
+ BillingCity, BillingCountry,
616
+ BillingGeocodeAccuracy, ShippingStreet,
617
+ Sic, SicDesc, Site, SystemModstamp,
618
+ TickerSymbol, Type, Website,
619
+ (
620
+ SELECT Id, Name, AccountId, Amount,
621
+ CampaignId, CloseDate, CreatedById, Type
622
+ FROM Opportunities
623
+ ),
624
+ (
625
+ SELECT Id, Name, AccountNumber, AccountSource,
626
+ AnnualRevenue, BillingAddress, Website
627
+ FROM ChildAccounts
628
+ )
629
+ FROM Account
630
+ WHERE Name LIKE 'a%'
631
+ OR Name LIKE 'b%'
632
+ OR Name LIKE 'c%'
561
633
  ```
562
634
 
563
635
  ## Using in LWC
@@ -642,7 +714,7 @@ export default class MyComponent extends LightningElement {
642
714
  }
643
715
  ```
644
716
 
645
- <!-- LWC event bindings must be unquoted (onclick={handleClick}); prettier would add quotes -->
717
+ <!-- LWC event bindings must be unquoted (onclick={handleClick}); the formatter would add quotes. oxfmt honors prettier-ignore in markdown -->
646
718
  <!-- prettier-ignore -->
647
719
  ```html
648
720
  <template>
@@ -772,8 +844,9 @@ Usage: compose [options] <query>
772
844
 
773
845
  Options:
774
846
  -f, --format format output
775
- -i --indent <chars> number of tab characters to indent (default: 1)
776
- -m --line-length <chars> max number of characters per lins (default: 60)
847
+ -i --indent <count> number of times the indent string is repeated per level (default: 1)
848
+ -t --indent-string <string> string used for one unit of indentation (default: tab), e.g. --indent-string " "
849
+ -m --line-length <chars> max number of characters per line (default: 60)
777
850
  -s --subquery-parens-new-line subquery parens on own line
778
851
  -k --keywords-new-line new line after keywords
779
852
  -j, --json output as JSON
@@ -788,8 +861,9 @@ Usage: format [options] <sql>
788
861
  Options:
789
862
  -a, --allow-apex allow apex bind variables
790
863
  -p, --allow-partial allow partial queries
791
- -i --indent <chars> number of tab characters to indent (default: 1)
792
- -m --line-length <chars> max number of characters per lins (default: 60)
864
+ -i --indent <count> number of times the indent string is repeated per level (default: 1)
865
+ -t --indent-string <string> string used for one unit of indentation (default: tab), e.g. --indent-string " "
866
+ -m --line-length <chars> max number of characters per line (default: 60)
793
867
  -s --subquery-parens-new-line subquery parens on own line
794
868
  -k --keywords-new-line new line after keywords
795
869
  -j, --json output as JSON
@@ -833,13 +907,7 @@ export type LiteralType =
833
907
  | 'DATE_N_LITERAL'
834
908
  | 'APEX_BIND_VARIABLE';
835
909
  export type FieldType =
836
- | Field
837
- | FieldWithAlias
838
- | FieldFunctionExpression
839
- | FieldRelationship
840
- | FieldRelationshipWithAlias
841
- | FieldSubquery
842
- | FieldTypeOf;
910
+ Field | FieldWithAlias | FieldFunctionExpression | FieldRelationship | FieldRelationshipWithAlias | FieldSubquery | FieldTypeOf;
843
911
  export type OrderByCriterion = 'ASC' | 'DESC';
844
912
  export type NullsOrder = 'FIRST' | 'LAST';
845
913
  export type GroupByType = 'CUBE' | 'ROLLUP';
@@ -978,11 +1046,7 @@ export interface WhereClauseWithRightCondition extends WhereClauseWithoutOperato
978
1046
  }
979
1047
 
980
1048
  export type Condition =
981
- | ValueCondition
982
- | ValueWithDateLiteralCondition
983
- | ValueWithDateNLiteralCondition
984
- | ValueFunctionCondition
985
- | NegationCondition;
1049
+ ValueCondition | ValueWithDateLiteralCondition | ValueWithDateNLiteralCondition | ValueFunctionCondition | NegationCondition;
986
1050
 
987
1051
  export type ConditionWithValueQuery = Condition | ValueQueryCondition;
988
1052
 
@@ -1020,7 +1084,7 @@ export interface ValueQueryCondition extends OptionalParentheses {
1020
1084
  }
1021
1085
 
1022
1086
  export interface ValueFunctionCondition extends OptionalParentheses {
1023
- fn: FunctionExp;
1087
+ fn: FunctionExp | FormulaFunctionExp; // narrow with isFormulaFunction(); checking functionName alone does not narrow the type
1024
1088
  operator: Operator;
1025
1089
  value: string | string[];
1026
1090
  literalType?: LiteralType | LiteralType[];
@@ -1078,6 +1142,25 @@ export interface FunctionExp {
1078
1142
  isAggregateFn?: boolean; // not used for compose, will be populated if SOQL is parsed
1079
1143
  }
1080
1144
 
1145
+ export type FormulaArithmeticOperator = '+' | '-';
1146
+
1147
+ export interface FormulaFieldReference {
1148
+ type: 'FieldReference';
1149
+ parts: string[];
1150
+ }
1151
+
1152
+ export interface FormulaBinaryExpression {
1153
+ type: 'BinaryExpression';
1154
+ operator: FormulaArithmeticOperator;
1155
+ left: FormulaFieldReference;
1156
+ right: FormulaFieldReference;
1157
+ }
1158
+
1159
+ export interface FormulaFunctionExp extends FunctionExp {
1160
+ functionName: 'FORMULA';
1161
+ formula: FormulaBinaryExpression;
1162
+ }
1163
+
1081
1164
  export interface WithDataCategoryClause {
1082
1165
  conditions: WithDataCategoryCondition[];
1083
1166
  }
@@ -1091,4 +1174,4 @@ export interface WithDataCategoryCondition {
1091
1174
 
1092
1175
  ## Contributing
1093
1176
 
1094
- All contributions are welcome on the project. Please read the [contribution guidelines](https://github.com/jetstreamapp/soql-parser-js/blob/master/CONTRIBUTING.md).
1177
+ All contributions are welcome on the project. Please read the [contribution guidelines](https://github.com/jetstreamapp/soql-parser-js/blob/main/CONTRIBUTING.md).