![](\"./assets/soql-parser-js-logo.svg\"){kind=logo}
\n\n\n[](https://badge.fury.io/js/@jetstreamapp%2Fsoql-parser-js)\n\n## Description\n\n**This library allows parsing and composing SOQL queries from Salesforce using JavaScript or Typescript.**\n\n### Installation\n\nš **As of version 6.0.0**, this package is now part of the `@jetstreamapp` npm organization.\n\n```bash\nnpm install @jetstreamapp/soql-parser-js\n```\n\n**Available Features:**\n\n1. Parse SOQL queries into a common `Query` data structure.\n2. Deterministically compose a `Query` data structure back into a SOQL query string.\n3. Validate a query to check if the syntax is valid.\n 1. _Even if a query is returned as valid, it might still be invalid based on your Salesforce configuration_\n\nMigrating from version 1 to version 2? [Check out the changelog](CHANGELOG.md#200) for a full list of changes.\n\nMigrating from version 2 to version 3? [Check out the changelog](CHANGELOG.md#300) for a full list of changes.\n\n## Documentation\n\n**[Read the documentation on our docs site](https://paustint.github.io/soql-parser-js/)**.\n\n## Compatibility\n\n**Node**: version 20 or higher \n**Browser**: Tested in all modern browsers, may not work with older browsers.\n\nThis library has no runtime dependencies - the parser, composer, formatter and cli are all self contained.\n\n## Quick Start\n\n```javascript\nimport { parseQuery, composeQuery, isQueryValid } from '@jetstreamapp/soql-parser-js';\n\nconst query = parseQuery(`SELECT Id FROM Account WHERE Id = 'FOO'`);\nconsole.log('query', query);\n\nconst soql = composeQuery(query);\nconsole.log('soql', soql); // SELECT Id FROM Account WHERE Id = 'FOO'\n\nisQueryValid('SELECT Id, Foo FROM Baz'); // true\nisQueryValid('SELECT Id Foo FROM Baz'); // false\n```\n\n### `FORMULA()` in `WHERE`\n\nThe 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).\nThe quoted expression must contain two field references separated by `+` or `-`; `FORMULA()` is not\naccepted in `SELECT`, `HAVING`, `GROUP BY`, or `ORDER BY`. Only comparison operators may follow it,\nand Apex bind variables are rejected because Salesforce does not support them after `FORMULA()`.\nSalesforce ships this function as a Beta feature as of Summer '26.\n\n```typescript\nconst query = parseQuery(\"SELECT Id FROM Opportunity WHERE FORMULA('Amount - ExpectedRevenue') > 100\");\n\nconsole.log(query.where?.left);\n// {\n// fn: {\n// functionName: 'FORMULA',\n// parameters: [\"'Amount - ExpectedRevenue'\"],\n// rawValue: \"FORMULA('Amount - ExpectedRevenue')\",\n// formula: {\n// type: 'BinaryExpression',\n// operator: '-',\n// left: { type: 'FieldReference', parts: ['Amount'] },\n// right: { type: 'FieldReference', parts: ['ExpectedRevenue'] },\n// },\n// },\n// operator: '>',\n// value: '100',\n// literalType: 'INTEGER',\n// }\n```\n\nThe nested formula AST is also accepted by `composeQuery()`. When `formula` is present, `FORMULA()`\nis rebuilt from that AST and `rawValue` is ignored; a `FORMULA` function without `formula` composes\nfrom `rawValue` like any other function. `parameters` holds the normalized expression and `rawValue`\nkeeps the original text. The parser validates the expression's shape, but it cannot validate\nmetadata-dependent Salesforce rules such as field data types or type compatibility.\n\n## Available Features\n\n| Function | Description | Arguments |\n| ------------ | ------------------------------------------------------ | ------------------------------------------ |\n| parseQuery | Parse a SOQL query string into a Query data structure. | soql: QueryParsed Query: {parsedQueryString}
\n\n```\n\nAll public exports of the library (`parseQuery`, `composeQuery`, `formatQuery`, `isQueryValid`, the various utility functions, etc.) are available as named imports from `c/soqlParserJs`.\n\n## CLI\n\nInstall globally or use `npx` to interact with the cli.\n\n### Available Commands\n\n- `soql-parser-js --help` (or using `npx`: `npx soql-parser-js --help`)\n- `soql-parser-js parse --help`\n- `soql-parser-js compose --help`\n- `soql-parser-js format --help`\n\n### Examples\n\n#### Parse\n\n`npx soql-parser-js parse \"SELECT Id FROM Account\"`\n\n```bash\n{\"fields\":[{\"type\":\"Field\",\"field\":\"Id\"}],\"sObject\":\"Account\"}\n```\n\n#### Compose\n\n`npx soql-parser-js compose \"{\\\"fields\\\":[{\\\"type\\\":\\\"Field\\\",\\\"field\\\":\\\"Id\\\"}],\\\"sObject\\\":\\\"Account\\\"}\"`\n\n```bash\nSELECT Id FROM Account\n```\n\n`npx soql-parser-js compose \"{\\\"fields\\\":[{\\\"type\\\":\\\"Field\\\",\\\"field\\\":\\\"Id\\\"}],\\\"sObject\\\":\\\"Account\\\"}\" --json` or -j\n\n```json\n{ \"query\": \"SELECT Id FROM Account\" }\n```\n\n#### Format\n\n`npx soql-parser-js format \"SELECT Name, COUNT(Id) FROM Account GROUP BY Name HAVING COUNT(Id) > 1\"`\n\n```bash\nSELECT Name, COUNT(Id)\nFROM Account\nGROUP BY Name\nHAVING COUNT(Id) > 1\n```\n\n`npx soql-parser-js format \"SELECT Name, COUNT(Id) FROM Account GROUP BY Name HAVING COUNT(Id) > 1 -j`\n\n```json\n{ \"query\": \"SELECT Name, COUNT(Id)\\nFROM Account\\nGROUP BY Name\\nHAVING COUNT(Id) > 1\" }\n```\n\n#### Is Valid\n\n`npx soql-parser-js valid \"SELECT Id FROM Account\"`\n\n```bash\ntrue\n```\n\n`npx soql-parser-js valid \"SELECT Id invalid FROM Account\"`\n\nā¹ļø this returns an exit code of 1\n\n```bash\nfalse\n```\n\n`npx soql-parser-js valid \"SELECT Id FROM Account\" -j`\n\n```json\n{ \"isValid\": true }\n```\n\n`npx soql-parser-js valid \"SELECT Id invalid invalid FROM Account\" -j`\n\nā¹ļø this returns an exit code of 0\n\n```json\n{ \"isValid\": false }\n```\n\n### List of options\n\n`soql-parser-js --help`\n\n```bash\nUsage: soql-parser-js [options] [command]\n\nOptions:\n -h, --help output usage information\n\nCommands:\n parse [options]