https://github.com/jacobshirley/soql-parser-lite
Zero-dependency Salesforce Object Query Language (SOQL) parser written in TypeScript
https://github.com/jacobshirley/soql-parser-lite
objects oop parser parsing query salesforce soql
Last synced: 4 months ago
JSON representation
Zero-dependency Salesforce Object Query Language (SOQL) parser written in TypeScript
- Host: GitHub
- URL: https://github.com/jacobshirley/soql-parser-lite
- Owner: jacobshirley
- License: mit
- Created: 2025-12-14T19:56:27.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-01-29T18:50:31.000Z (4 months ago)
- Last Synced: 2026-01-30T07:19:10.338Z (4 months ago)
- Topics: objects, oop, parser, parsing, query, salesforce, soql
- Language: TypeScript
- Homepage: https://jacobshirley.github.io/soql-parser-lite/
- Size: 79.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
**[Examples](./EXAMPLES.md)** | **[Documentation](https://jacobshirley.github.io/soql-parser-lite/v1)**
# soql-parser-lite
A zero-dependency, TypeScript/JavaScript parser for SOQL (Salesforce Object Query Language) that converts query strings into structured objects.
[](https://www.npmjs.com/package/soql-parser-lite)
[](https://opensource.org/licenses/MIT)
## Features
- 🔍 **Complete SOQL Support**: Parses all major SOQL clauses (SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET)
- 📦 **TypeScript First**: Fully typed API with comprehensive type definitions
- 🚀 **Zero Dependencies**: Lightweight with no external runtime dependencies
- 🔄 **Streaming Support**: Can parse queries incrementally from streams
- 🎯 **Accurate**: Handles complex queries including subqueries, aggregate functions, and nested field paths
- 🛡️ **Error Handling**: Provides detailed error messages for malformed queries
## Installation
```bash
npm install soql-parser-lite
```
Or with pnpm:
```bash
pnpm add soql-parser-lite
```
Or with yarn:
```bash
yarn add soql-parser-lite
```
## Quick Start
```typescript
import { parseSoqlQuery } from 'soql-parser-lite'
// Parse a simple query
const query = parseSoqlQuery(
'SELECT Id, Name FROM Account WHERE Status = "Active" LIMIT 10',
)
console.log(JSON.stringify(query, null, 2))
// Output:
/*
{
"select": {
"items": [
{
"item": {
"name": "Id"
}
},
{
"item": {
"name": "Name"
}
}
]
},
"from": {
"objects": [
{
"name": "Account"
}
]
},
"where": {
"expr": {
"left": {
"name": "Status"
},
"right": {
"value": "Active"
}
}
},
"limit": 10
}
*/
```
## Usage Examples
### Basic Query
```typescript
import { parseSoqlQuery } from 'soql-parser-lite'
const query = parseSoqlQuery('SELECT Id, Name, Email FROM Contact')
```
### Query with WHERE Clause
```typescript
const query = parseSoqlQuery(
'SELECT Id, Name FROM Account WHERE Status = "Active" AND Revenue > 1000000',
)
```
### Query with Aggregate Functions
```typescript
const query = parseSoqlQuery(
'SELECT COUNT(Id) cnt, MAX(Amount) maxAmount FROM Opportunity GROUP BY StageName',
)
```
### Query with Subquery
```typescript
const query = parseSoqlQuery(
'SELECT Name, (SELECT LastName FROM Contacts) FROM Account',
)
```
### Query with Date Literals
```typescript
const query = parseSoqlQuery('SELECT Id FROM Case WHERE CreatedDate = TODAY')
```
### Query with ORDER BY and LIMIT
```typescript
const query = parseSoqlQuery(
'SELECT Id, Name, CreatedDate FROM Account ORDER BY CreatedDate DESC LIMIT 100 OFFSET 50',
)
```
### Query with Relationship Fields
```typescript
const query = parseSoqlQuery(
'SELECT Id, Account.Name, Account.Owner.Email FROM Contact',
)
```
## Supported SOQL Features
- ✅ SELECT clause with fields, aggregate functions, and subqueries
- ✅ FROM clause with multiple objects and aliases
- ✅ WHERE clause with comparison and logical operators
- ✅ GROUP BY clause
- ✅ HAVING clause
- ✅ ORDER BY clause with ASC/DESC
- ✅ LIMIT clause
- ✅ OFFSET clause
- ✅ Date literals (TODAY, YESTERDAY, LAST_N_DAYS, etc.)
- ✅ Bind variables (:variable)
- ✅ IN operator with arrays and subqueries
- ✅ Relationship field paths (Account.Owner.Name)
- ✅ Aggregate functions (COUNT, MAX, MIN, SUM, AVG)
- ✅ Field aliases
## Development
```bash
# Install dependencies
pnpm install
# Build the project
pnpm run compile
# Run tests
pnpm test
# Format code
pnpm run format
# Generate documentation
pnpm run docs:gen
```
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
## License
MIT © [Jacob Shirley](https://github.com/jacobshirley)
## Related Projects
- [Salesforce SOQL Documentation](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm)
## Support
- 📚 [Documentation](https://jacobshirley.github.io/soql-parser-lite/v1)
- 💬 [GitHub Issues](https://github.com/jacobshirley/soql-parser-lite/issues)
- 📖 [Examples](./EXAMPLES.md)