odata-v4-typeorm-improved

1.0.3 verified Fri May 01 auth: no javascript

OData V4 to TypeORM query compiler that translates OData query strings ($filter, $orderby, $top, $skip, $expand, $select, $search, etc.) into TypeORM query builder calls. Current stable version 1.0.3 (March 2024). Released under MIT license. Differs from other OData-to-ORM libraries by offering a simple middleware integration for Express and NestJS, direct support for TypeORM repositories and query builders, and TypeScript-first design. It wraps TypeORM's repository to produce OData-compliant endpoints with minimal boilerplate. Suitable for building REST APIs that follow the OData protocol on top of any SQL database supported by TypeORM. Requires TypeORM >=0.3.28.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using require() with an ESM-only package (v1.0.0+).

fix

Switch to import syntax or set type: module in package.json.

error Cannot find module 'odata-v4-typeorm' ↓

cause Package renamed; old name is no longer published.

fix

npm install odata-v4-typeorm-improved and update imports.

error TypeError: odataQuery is not a function ↓

cause Importing odataQuery as default import instead of named import.

fix

Use import { odataQuery } from 'odata-v4-typeorm-improved'.

Warnings

breaking v1.0.0 changed from CJS to ESM-only. CommonJS require() will break. ↓

fix Use import syntax or upgrade to Node 14+ with 'type':'module' in package.json.

breaking v1.0.0 renamed package from 'odata-v4-typeorm' to 'odata-v4-typeorm-improved'. Old package may be stale. ↓

fix Install 'odata-v4-typeorm-improved' and update imports.

deprecated The old package 'odata-v4-typeorm' (pre-1.0.0) is deprecated and unmaintained. ↓

fix Migrate to 'odata-v4-typeorm-improved' version 1.0.0 or later.

gotcha TypeORM peer dependency is version 0.3.28 or higher. Older TypeORM versions may cause runtime errors. ↓

fix Ensure typeorm@^0.3.28 is installed.

gotcha The executeQuery function expects req.query object (not the full Express Request). Passing the request object directly will fail. ↓

fix Call executeQuery(repo, req.query) not executeQuery(repo, req).

Install

npm install odata-v4-typeorm-improved

yarn add odata-v4-typeorm-improved

pnpm add odata-v4-typeorm-improved

Imports

odataQuery
wrong
```
const odataQuery = require('odata-v4-typeorm-improved').odataQuery
```
correct
```
import { odataQuery } from 'odata-v4-typeorm-improved'
```
ESM-only since v1.0.0. This function is a middleware factory that takes a TypeORM Repository and returns an Express middleware.
executeQuery
wrong
```
import executeQuery from 'odata-v4-typeorm-improved'
```
correct
```
import { executeQuery } from 'odata-v4-typeorm-improved'
```
Named export, not default. Accepts a repository or query builder and the query parameters object.
executeQuery (by query builder)
wrong
```
import { executeQueryBuilder } from 'odata-v4-typeorm-improved'
```
correct
```
import { executeQuery } from 'odata-v4-typeorm-improved'
```
Same function name but called with a SelectQueryBuilder instead of a Repository. The library exports only two functions.

Quickstart

Creates an Express endpoint that translates OData query parameters to TypeORM queries using the provided repository.

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

const app = express();
const port = 3001;

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

app.listen(port, () => console.log(`Server running on port ${port}`));