@medyll/idae-api

A flexible and extensible Node.js API, based on the @medyll/idae-db library, allowing you to manage multiple types of databases (MongoDB, MySQL, etc.) and providing a complete TypeScript client to interact with your endpoints.

---

Table of Contents

• Overview
• Installation
• Main Features
• Server Usage
  • Configuration
  • Adding Custom Routes
  • Database Management
  • Error Handling
• Client Usage
  • Client Configuration
  • Available Methods
  • Usage Examples
• Full List of Methods (inherited from idae-db)
• Contributing
• License

---

Overview

@medyll/idae-api is a modular Node.js API framework designed to work with multiple database types thanks to the @medyll/idae-db library. It offers:

• Modular architecture (routes, middlewares, dynamic connection management)
• TypeScript/JavaScript client for easy API consumption
• Extension system to support other databases
• Native support for MongoDB and MySQL (via idae-db)
• Hooks/events on CRUD operations
• MongoDB-like API syntax: All query and update operations use a syntax very close to MongoDB (operators like $in, $gt, $set, etc.), making it intuitive for developers familiar with MongoDB.

Installation

1npm install @medyll/idae-api
2
3npm install @medyll/idae-api --latest # to install the latest version
4npm install @medyll/idae-api --next # for the next version (if available)
5

---

Main Features

• Multi-database management (MongoDB, MySQL, etc.)
• Flexible routing and custom route addition
• Optional authentication middleware
• Centralized error handling
• Hooks/events on all CRUD operations
• Complete TypeScript client for API consumption
• Inherits all advanced methods from @medyll/idae-db

---

Server Usage

Configuration

1import { idaeApi } from '@medyll/idae-api';
2
3idaeApi.setOptions({
4  port: 3000,
5  enableAuth: true, // or false
6  jwtSecret: 'your-secret-key',
7  tokenExpiration: '1h',
8  routes: customRoutes // optional
9});
10
11idaeApi.start();

Example of custom routes

1const customRoutes = [
2  {
3    method: 'get',
4    path: '/custom/hello',
5    handler: async () => ({ message: 'Hello from custom route!' }),
6    requiresAuth: false
7  }
8];
9
10idaeApi.router.addRoutes(customRoutes);

Database Management

idae-api relies on @medyll/idae-db for connection and database operation management. You can:

• Add new database adapters (see the DatabaseAdapter interface in idae-db)
• Use all hooks/events from idae-db (see below)

Error Handling

An error handling middleware is included. You can customize it via the configureErrorHandling method in the IdaeApi class.

---

Client Usage

Client Configuration

1import { IdaeApiClientConfig } from '@medyll/idae-api';
2
3IdaeApiClientConfig.setOptions({
4  host: 'localhost',
5  port: 3000,
6  method: 'http',
7  defaultDb: 'idae_base',
8  separator: '//'
9});

Creating a client instance

1import { IdaeApiClient } from '@medyll/idae-api';
2
3const client = new IdaeApiClient();

Available Methods

Database and Collection Management

• getDbList() : List available databases
• getCollections(dbName) : List collections in a database
• db(dbName) : Select a database (returns an object with collection and getCollections)
• collection(collectionName, dbName?) : Select a collection (optionally in a given database)

Event/Hook Management (inherited from idae-db)

You can register hooks on all operations:

1const usersCollection = client.collection('user');
2
3usersCollection.registerEvents({
4  findById: {
5    pre: (id) => console.log(`Before searching for ID: ${id}`),
6    post: (result, id) => console.log(`Result for ${id}:`, result),
7    error: (error) => console.error('Error on findById:', error)
8  },
9  // ... same for update, create, etc.
10});
11
12#### CRUD Operations on a Collection
13
14All the following methods are available via the `IdaeApiClientCollection` object:
15
16- `findAll(params?)` : List all documents (with filters, sorting, pagination)
17- `findById(id)` : Get a document by its ID
18- `findOne(params)` : Get a document by a filter (inherited from idae-db)
19- `create(body)` : Create a document
20- `update(id, body)` : Update a document
21- `deleteById(id)` : Delete a document by its ID
22- `deleteManyByQuery(params)` : Delete multiple documents by filter
23
24#

Usage Examples

MongoDB-like Query Syntax

All query and update operations use a syntax very close to MongoDB. For example, you can use operators like $in, $gt, $set, etc. in your queries and updates.

---

List databases

1const dbList = await client.getDbList();
2console.log('Databases:', dbList);

List collections in a database

1const collections = await client.getCollections('idae_base');
2console.log('Collections:', collections);

Find documents with advanced query (MongoDB-like)

1const userCollection = client.db('app').collection('user');
2const users = await userCollection.find({
3  email: { $in: ["Karin@example.com", "Test@Value"] },
4  age: 31,
5});
6console.log(users);

Create a new document

1const newUser = await userCollection.create({
2  name: "new user",
3  email: "Test@Value",
4});
5console.log(newUser);

Find all documents in a collection

1const allDocs = await userCollection.findAll();
2console.log(allDocs);

Find a specific document by ID

1const foundDoc = await userCollection.findById(newUser._id);
2console.log(foundDoc);

Update a document (MongoDB-like update syntax)

1const updatedDoc = await userCollection.update(newUser._id, {
2  $set: { value: "Updated Value" },
3});
4console.log(updatedDoc);

Delete a document

1const deleteResult = await userCollection.deleteById(newUser._id);
2console.log(deleteResult);

Use a specific database and collection

1const appSchemeCollection = client.db('idae_base').collection('appscheme');
2const docs = await appSchemeCollection.findAll();
3console.log(docs);

Delete many documents by query (be careful with this!)

1const deleteResult2 = await client
2  .collection('appscheme_base')
3  .deleteManyByQuery({ testField: 'testValue' });
4console.log(deleteResult2);

Register hooks/events on collection methods

1const usersCollection = client.collection('user');
2
3usersCollection.registerEvents({
4  findById: {
5    pre: (id) => console.log(`Before searching for ID: ${id}`),
6    post: (result, id) => console.log(`Result for ${id}:`, result),
7    error: (error) => console.error('Error on findById:', error)
8  },
9  // ... same for update, create, etc.
10});

---

Full List of Methods (inherited from idae-db)

Collection Methods

• find(params) : Advanced search (filters, sorting, pagination)
• findOne(params) : Find a single document by filter
• findById(id) : Find by ID
• create(data) : Create
• update(id, data) : Update
• deleteById(id) : Delete by ID
• deleteManyByQuery(params) : Bulk delete
• registerEvents(events) : Register hooks (pre/post/error) on each method

Connection Management

• closeAllConnections() : Close all active connections

Useful Types

• RequestParams : Record<string, unknown>
• HttpMethod : 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
• RouteNamespace : methods/${'dbs' | 'collections'}
• UrlParams : { dbName?: string; collectionName?: string; slug?: string; params?: Record<string, string>; routeNamespace?: RouteNamespace }
• RequestOptions<T> : UrlParams & { baseUrl?: string; method?: HttpMethod; body?: T; headers?: RequestInit['headers'] }

---

Contributing

Contributions are welcome! Feel free to submit a Pull Request.

---

License

This project is licensed under the MIT License.