odata-v4-typeorm

0.1.2 verified Fri May 01 auth: no javascript

OData V4 query parser and compiler for TypeORM (0.1.2). Converts OData v4 query strings (e.g., $filter, $select, $orderby, $top, $skip, $expand, $apply) into TypeORM QueryBuilder or repository queries. Supports Express and NestJS middleware. Lightweight alternative to full OData frameworks. Limited to SQL databases; no NoSQL support. Regularly released but early-stage (0.x). Ships TypeScript definitions.

Common errors

error TypeError: odataQuery is not a function ↓

cause Incorrect import; using default import instead of named import.

fix

Use import { odataQuery } from 'odata-v4-typeorm';

error Cannot read property 'createQueryBuilder' of undefined ↓

cause executeQuery called with a Repository that is not initialized (null/undefined).

fix

Ensure the repository is properly obtained via getRepository() or dependency injection.

error No metadata for "User" was found ↓

cause Entity not registered in TypeORM connection options.

fix

Add the User entity to entities array in createConnection() or DataSource options.

error getRepository is not a function ↓

cause Using TypeORM 0.3+ where getRepository is no longer exported. Use dataSource.getRepository(User).

fix

Update to TypeORM 0.2.x or use dataSource.getRepository().

Warnings

gotcha The library only translates OData query parameters; it does not build the full OData response envelope (no @odata.context, count, etc.). ↓

fix Manually wrap the response with OData metadata if needed, or use a dedicated OData framework (e.g., odata-v4-server).

breaking Breaking change in v0.0.11: $apply (aggregation) not supported. Use $filter and custom aggregation. ↓

fix Upgrade to v0.1.0+ which includes basic $apply support for count, sum, min, max.

deprecated executeQuery signature changed in v0.0.10: second parameter is now query object, not string. ↓

fix Update calls to executeQuery(repository, req.query) instead of executeQuery(repository, req.queryString).

gotcha TypeORM versions >=0.3.0 use DataSource, not Connection. This library relies on Connection for repository injection; may require adapter. ↓

fix Use TypeORM 0.2.x or wrap DataSource to provide Connection-compatible repository.

gotcha $expand is not supported by default; you must manually define relations in your entity. ↓

fix Use TypeORM's QueryBuilder with leftJoinAndSelect and pass a pre-built queryBuilder to executeQuery.

Install

npm install odata-v4-typeorm

yarn add odata-v4-typeorm

pnpm add odata-v4-typeorm

Imports

odataQuery
wrong
```
const odataQuery = require('odata-v4-typeorm');
```
correct
```
import { odataQuery } from 'odata-v4-typeorm';
```
Both ESM and CJS supported. 'odataQuery' is a middleware function expecting a TypeORM Repository as argument.
executeQuery
wrong
```
import executeQuery from 'odata-v4-typeorm';
```
correct
```
import { executeQuery } from 'odata-v4-typeorm';
```
Named export, not default. Use with repository or query builder and query string object.
ODataQuery
```
import { ODataQuery } from 'odata-v4-typeorm';
```
TypeScript type for the query options object. Optional import for type checking.

Quickstart

Express middleware that automatically parses OData v4 query parameters from the request URL and returns filtered/sorted/paginated data from a TypeORM repository.

import express from 'express';
import { odataQuery } from 'odata-v4-typeorm';
import { getRepository } from 'typeorm';
import { User } from './entities/user';

const app = express();
const usersRepository = getRepository(User);

app.get('/api/users', odataQuery(usersRepository));

app.listen(3001, () => console.log('Example app listening on port 3001!'));