odata-fluent-query

A modern, type-safe OData query builder for TypeScript/JavaScript

✨ Version 3.0 - Fully modernized and production-ready

Client side queries with extensive filtering and typesafe joins

This lib only generates the query string, so you need to use it with your own implementation of http request. There is no need to scaffold any pre build model.

Features

• 🎯 Full TypeScript support with built-in type definitions
• 🔒 Type-safe queries with IntelliSense support
• 🚀 Modern ES2022 target for optimal performance
• ✅ 100% test coverage with 319 comprehensive tests
• 📦 Minimal dependencies with only validator as a runtime dependency
• 🔧 Fluent API for readable query building
• 🔄 Parse existing query strings with fromString() method

Installation

npm install odata-fluent-query

Requirements:

• Node.js 18+
• TypeScript 5.0+ (optional, but recommended)

TypeScript Support

This package includes built-in TypeScript definitions and provides full type safety:

interface User {
  id: number
  email: string
  isActive: boolean
  posts: Post[]
}

// Full intellisense and type checking
const query = odataQuery<User>()
  .filter(u => u.email.contains('test'))  // ✅ Type-safe
  .select('id', 'email')                  // ✅ Only valid properties
  .orderBy(u => u.isActive)               // ✅ Correct types
  .toString()

// Result: "$filter=contains(email,'test')&$select=id,email&$orderby=isActive"

Quick Start

import { odataQuery } from 'odata-fluent-query'

// Simple filter
const query = odataQuery<User>()
  .filter(u => u.id.equals(1))
  .toString()
// Result: $filter=id eq 1

// Complex query with multiple operations
const complexQuery = odataQuery<User>()
  .select('id', 'email', 'username')
  .filter(u => u.isActive.equals(true).and(u.email.contains('@company.com')))
  .orderBy(u => u.username)
  .paginate(10, 0)
  .toString()

Documentation

Core Features

• Filtering - Advanced filtering with type-safe expressions
• Selecting - Choose specific properties to return
• Ordering - Sort results with complex ordering rules
• Expanding - Include related data with nested queries
• Computing - Create computed properties with type safety
• Searching - Full-text search with automatic quoting
• Grouping - Group data with aggregations
• Pagination - Handle large datasets with pagination
• Parsing - Parse existing query strings back to objects

Development

Requirements:

• Node.js 18+
• npm 8+

Setup:

npm install

Build:

npm run build        # Build the project
npm run build:watch  # Build in watch mode

Testing:

npm test                # Run tests
npm run test:coverage   # Run with coverage report
npm run test:watch      # Run tests in watch mode
npm run test:debug      # Debug tests

Code Quality:

npm run lint           # Check code style
npm run lint:fix       # Auto-fix linting issues
npm run ci             # Full CI check (build + test + coverage)

Publishing:

npm run ci             # Verify everything works
npm publish            # Publish to npm (runs CI automatically)

The output files will be placed in the dist directory. This project contains comprehensive unit tests using jest and ts-jest.

After running tests with coverage, you can open coverage/lcov-report/index.html in your browser to see detailed coverage reports.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (npm run ci)
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

MIT - see LICENSE file for details.