@phrasecode/odata

v0.3.1

Published

12 days ago

Modern OData v4 server library for Node.js with TypeScript support. Build standards-compliant REST APIs for Express, serverless AWS Lambda, Azure Functions, and Next.js API routes. Automatic query handling, metadata generation, and support for PostgreSQL,

Node OData Framework (TypeScript)

A powerful Node.js framework for building REST APIs with full OData v4 query capabilities. This framework provides a decorator-based approach to define models and automatically generates OData-compliant endpoints with advanced querying features.

📖 Documentation: For complete guides, tutorials, and API reference, visit https://odata.phrasecode.com

Why This Package?

Building REST APIs with complex querying capabilities can be time-consuming and error-prone. Traditional approaches require you to manually implement filtering, sorting, pagination, and relationship expansion for each endpoint. This package solves these problems by:

Eliminating Boilerplate: Define your data models once using decorators, and get fully functional OData endpoints automatically
Type Safety: Built with TypeScript from the ground up, providing excellent IntelliSense and compile-time type checking
Framework Flexibility: Works with Express.js, Next.js, serverless functions, and any other Node.js framework
OData v4 Compliance: Supports standard OData query options ($filter, $select, $expand, $orderby, $top, $skip, $count) out of the box
Database Agnostic: Currently supports PostgreSQL, MySQL, SQLite, and other Sequelize-compatible databases
Developer Experience: Intuitive decorator-based API that feels natural to TypeScript developers

Key Features

✅ Decorator-Based Model Definition: Use TypeScript decorators to define your data models
✅ Full OData v4 Query Support: $select, $filter, $expand, $orderby, $top, $skip, $count
✅ Advanced Filter Capabilities: Comparison, logical, arithmetic operators, string/date/math functions
✅ Powerful Expansion Features: Nested expansions (5+ levels), filters on relations, and more
✅ Relationship Support: One-to-many, one-to-one, and many-to-one relationships
✅ Multiple Integration Options: Express.js Router and OpenRouter for Next.js/serverless
✅ OData Metadata Endpoint: Automatic $metadata endpoint for API discovery
✅ Type-Safe Query Results: Full TypeScript support with proper type inference
✅ Database Agnostic: PostgreSQL, MySQL, SQLite, MariaDB, MSSQL, Oracle
✅ Webpack Compatible: Special handling for circular dependencies in bundled environments

Installation

npm install @phrasecode/odata

You'll also need to install a database driver. See the Installation Guide for details.

Quick Start

import {
  Model,
  Table,
  Column,
  DataTypes,
  DataSource,
  ExpressRouter,
  ODataControler,
} from '@phrasecode/odata';
import express from 'express';

// Define a model
@Table({ tableName: 'users' })
class User extends Model<User> {
  @Column({
    dataType: DataTypes.INTEGER,
    isPrimaryKey: true,
    isAutoIncrement: true,
  })
  id: number;

  @Column({ dataType: DataTypes.STRING })
  name: string;

  @Column({ dataType: DataTypes.STRING })
  email: string;
}

// Create data source
const dataSource = new DataSource({
  dialect: 'postgres',
  database: 'mydb',
  username: 'user',
  password: 'password',
  host: 'localhost',
  port: 5432,
  models: [User],
});

// Set up Express router
const app = express();
const userController = new ODataControler({
  model: User,
  allowedMethod: ['get'],
});
new ExpressRouter(app, { controllers: [userController], dataSource });

app.listen(3000);
// Now you can query: GET http://localhost:3000/User?$select=name,email&$filter=name eq 'John'
// Metadata endpoint: GET http://localhost:3000/$metadata

For more detailed examples, see the Quick Start Guide.

Documentation

Full documentation is available at https://odata.phrasecode.com

🚀 Getting Started

📚 Core Concepts

Quick Reference

OData Query Examples

# Select specific fields
GET /User?$select=name,email

# Filter results
GET /User?$filter=age gt 18 and status eq 'active'

# Expand relations
GET /User?$expand=department,orders

# Combine multiple options
GET /User?$filter=age gt 18&$expand=department&$select=name,email&$orderby=name asc&$top=20

# String functions
GET /User?$filter=contains(name, 'john') or startswith(email, 'admin')

# Arithmetic expressions
GET /Order?$filter=((price mul quantity) sub discount) gt 1000

Performance Tips

Connection Pooling

Critical for production! Connection pooling improves query performance by 10-15x:

const dataSource = new DataSource({
  // ... other config
  pool: {
    max: 10,
    min: 2,
    idle: 10000,
  },
});

Performance Impact:

Without pooling: 1000-1500ms per query
With pooling: 85-110ms per query

See the Best Practices Guide for more optimization tips.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme