@medyll/idae-api 0.119.0 → 0.121.0

package/README.md

@@ -1,240 +1,314 @@
-# @medyll/idae-api
-
-A flexible and extensible API framework for Node.js, designed to work with multiple database types and configurations.
-
-## Features
-
-- Modular architecture with clear separation of concerns
-- Dynamic database connection management
-- Flexible routing system
-- Support for multiple database types (currently MongoDB, with easy extensibility for others)
-- TypeScript support for improved robustness and maintainability
-
-## Installation
-
-```
-npm install @medyll/idae-api
-```
-
-## Quick Start
-
-```javascript
-import { idaeApi } from '@medyll/idae-api';
-
-// Configure the server
-idaeApi.setOptions({
-  port: 3000,
-  enableAuth: false,
-  onInUse: 'reboot'
-});
-
-// Start the server
-idaeApi.start();
-```
-
-## Configuration
-
-You can configure the API server using the `setOptions` method:
-
-```javascript
-idaeApi.setOptions({
-  port: 3000,
-  routes: customRoutes,
-  enableAuth: true,
-  jwtSecret: 'your-secret-key',
-  tokenExpiration: '1h',
-  onInUse: 'reboot'
-});
-```
-
-## Custom Routes
-
-You can add custom routes to the API:
-
-```javascript
-const customRoutes = [
-  {
-    method: 'get',
-    path: '/custom/hello',
-    handler: async () => ({ message: 'Hello from custom route!' }),
-    requiresAuth: false
-  }
-];
-
-idaeApi.router.addRoutes(customRoutes);
-```
-
-## Database Adapters
-
-The API currently supports MongoDB out of the box. You can easily extend it to support other databases by implementing the `DatabaseAdapter` interface.
-
-## Error Handling
-
-The API includes built-in error handling middleware. You can customize error handling by modifying the `configureErrorHandling` method in the `IdaeApi` class.
-
-## API Client Usage
-
-The `@medyll/idae-api` package includes a flexible and powerful API client that allows you to interact with your API endpoints easily. Below is a detailed guide on how to use the `IdaeApiClient` and `IdaeApiClientCollection` classes.
-
-### Configuration
-
-First, configure the API client using the `IdaeApiClientConfig` singleton. This configuration will set up the host, port, method, default database, and other options for the client.
-
-```typescript
-import { IdaeApiClientConfig } from '@medyll/idae-api';
-
-IdaeApiClientConfig.setOptions({
-  host: 'localhost',
-  port: 3000,
-  method: 'http',
-  defaultDb: 'idae_base',
-  separator: '//'
-});
-```
-
-### Creating a Client Instance
-
-Create an instance of the `IdaeApiClient` class to start interacting with your API.
-
-```typescript
-import { IdaeApiClient } from '@medyll/idae-api';
-
-const client = new IdaeApiClient();
-```
-
-### Interacting with Databases and Collections
-
-You can interact with different databases and collections using the `db` and `collection` methods.
-
-#### Getting the List of Databases
-
-```typescript
-async function listDatabases() {
-  try {
-    const dbList = await client.getDbList();
-    console.log('Databases:', dbList);
-  } catch (error) {
-    console.error('Error fetching database list:', error);
-  }
-}
-
-listDatabases();
-```
-
-#### Getting the List of Collections in a Database
-
-```typescript
-async function listCollections(dbName: string) {
-  try {
-    const collections = await client.getCollections(dbName);
-    console.log(`Collections in ${dbName}:`, collections);
-  } catch (error) {
-    console.error(`Error fetching collections for ${dbName}:`, error);
-  }
-}
-
-listCollections('idae_base');
-```
-
-#### Performing CRUD Operations on a Collection
-
-You can perform CRUD operations on a collection using the `IdaeApiClientCollection` class.
-
-```typescript
-async function performCrudOperations() {
-  const appConfCollection = client.collection('app_conf');
-
-  try {
-    // Create a new document
-    const newDoc = await appConfCollection.create({ name: 'Test Config', value: 'Test Value' });
-    console.log('Created document:', newDoc);
-
-    // Find all documents
-    const allDocs = await appConfCollection.findAll();
-    console.log('All documents:', allDocs);
-
-    // Find a specific document by ID
-    const foundDoc = await appConfCollection.findById(newDoc._id);
-    console.log('Found document:', foundDoc);
-
-    // Update the document
-    const updatedDoc = await appConfCollection.update(newDoc._id, { value: 'Updated Value' });
-    console.log('Updated document:', updatedDoc);
-
-    // Delete the document
-    const deleteResult = await appConfCollection.deleteById(newDoc._id);
-    console.log('Deleted document:', deleteResult);
-  } catch (error) {
-    console.error('Error performing CRUD operations:', error);
-  }
-}
-
-performCrudOperations();
-```
-
-#### Using a Specific Database
-
-You can also specify a database explicitly when working with collections.
-
-```typescript
-async function useSpecificDatabase() {
-  const appSchemeCollection = client.db('idae_base').collection('appscheme');
-
-  try {
-    const appSchemeDocs = await appSchemeCollection.findAll();
-    console.log('Documents in appscheme:', appSchemeDocs);
-  } catch (error) {
-    console.error('Error fetching documents from appscheme:', error);
-  }
-}
-
-useSpecificDatabase();
-```
-
-### Classes and Methods
-
-#### `IdaeApiClient`
-
-- `constructor(clientConfig?: IdaeApiClientConfigCoreOptions & { baseUrl?: string })`
-- `getDbList(): Promise<Response>`
-- `getCollections(dbName: string): Promise<Response>`
-- `db(dbName: string): { collection: (collectionName: string) => IdaeApiClientCollection; getCollections: () => Promise<Response> }`
-- `collection(collectionName: string, dbName?: string): IdaeApiClientCollection`
-
-#### `IdaeApiClientCollection`
-
-- `constructor(apiClient: IdaeApiClient, dbName: string, collectionName: string)`
-- `findAll<T>(params?: RequestParams): Promise<Response>`
-- `findById<T>(id: string): Promise<Response>`
-- `create<T>(body: T): Promise<Response>`
-- `update<T>(id: string, body: T): Promise<Response>`
-- `deleteById<T>(id: string): Promise<Response>`
-- `deleteManyByQuery<T>(params: RequestParams): Promise<Response>`
-
-#### `IdaeApiClientConfig`
-
-- `setOptions(options: Partial<IdaeApiClientConfigCoreOptions> | undefined = {}): void`
-- `get baseUrl(): string`
-
-#### `IdaeApiClientRequest`
-
-- `constructor(clientConfig: IdaeApiClientConfigCore)`
-- `doRequest<T, R = any>(options: RequestOptions<T>): Promise<R>`
-- `private buildUrl(params: UrlParams): string`
-
-### 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! Please feel free to submit a Pull Request.
-
-## License
-
-This project is licensed under the MIT License.
- 
+# @medyll/idae-api
+
+A flexible and extensible Node.js API, based on the [@medyll/idae-db](https://www.npmjs.com/package/@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](#overview)
+- [Installation](#installation)
+- [Main Features](#main-features)
+- [Server Usage](#server-usage)
+  - [Configuration](#configuration)
+  - [Adding Custom Routes](#adding-custom-routes)
+  - [Database Management](#database-management)
+  - [Error Handling](#error-handling)
+- [Client Usage](#client-usage)
+  - [Client Configuration](#client-configuration)
+  - [Available Methods](#available-methods)
+  - [Usage Examples](#usage-examples)
+- [Full List of Methods (inherited from idae-db)](#full-list-of-methods-inherited-from-idae-db)
+- [Contributing](#contributing)
+- [License](#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](https://www.npmjs.com/package/@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
+
+```bash
+npm install @medyll/idae-api
+
+npm install @medyll/idae-api --latest # to install the latest version
+npm install @medyll/idae-api --next # for the next version (if available)
+
+```
+
+---
+
+## 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](https://www.npmjs.com/package/@medyll/idae-db)
+
+---
+
+## Server Usage
+
+### Configuration
+
+```typescript
+import { idaeApi } from '@medyll/idae-api';
+
+idaeApi.setOptions({
+  port: 3000,
+  enableAuth: true, // or false
+  jwtSecret: 'your-secret-key',
+  tokenExpiration: '1h',
+  onInUse: 'reboot', // behavior if the port is already in use
+  routes: customRoutes // optional
+});
+
+idaeApi.start();
+```
+
+#### Example of custom routes
+
+```typescript
+const customRoutes = [
+  {
+    method: 'get',
+    path: '/custom/hello',
+    handler: async () => ({ message: 'Hello from custom route!' }),
+    requiresAuth: false
+  }
+];
+
+idaeApi.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
+
+```typescript
+import { IdaeApiClientConfig } from '@medyll/idae-api';
+
+IdaeApiClientConfig.setOptions({
+  host: 'localhost',
+  port: 3000,
+  method: 'http',
+  defaultDb: 'idae_base',
+  separator: '//'
+});
+```
+
+### Creating a client instance
+
+```typescript
+import { IdaeApiClient } from '@medyll/idae-api';
+
+const 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)
+
+#### CRUD Operations on a Collection
+
+All the following methods are available via the `IdaeApiClientCollection` object:
+
+- `findAll(params?)` : List all documents (with filters, sorting, pagination)
+- `findById(id)` : Get a document by its ID
+- `findOne(params)` : Get a document by a filter (inherited from idae-db)
+- `create(body)` : Create a document
+- `update(id, body)` : Update a document
+- `deleteById(id)` : Delete a document by its ID
+- `deleteManyByQuery(params)` : Delete multiple documents by filter
+
+#### Event/Hook Management (inherited from idae-db)
+
+You can register hooks on all operations:
+
+```typescript
+const usersCollection = client.collection('user');
+
+usersCollection.registerEvents({
+  findById: {
+    pre: (id) => console.log(`Before searching for ID: ${id}`),
+    post: (result, id) => console.log(`Result for ${id}:`, result),
+    error: (error) => console.error('Error on findById:', error)
+  },
+  // ... same for update, create, etc.
+});
+```
+
+### 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
+
+```typescript
+const dbList = await client.getDbList();
+console.log('Databases:', dbList);
+```
+
+#### List collections in a database
+
+```typescript
+const collections = await client.getCollections('idae_base');
+console.log('Collections:', collections);
+```
+
+#### Find documents with advanced query (MongoDB-like)
+
+```typescript
+const userCollection = client.db('app').collection('user');
+const users = await userCollection.find({
+  email: { $in: ["Karin@example.com", "Test@Value"] },
+  age: 31,
+});
+console.log(users);
+```
+
+#### Create a new document
+
+```typescript
+const newUser = await userCollection.create({
+  name: "new user",
+  email: "Test@Value",
+});
+console.log(newUser);
+```
+
+#### Find all documents in a collection
+
+```typescript
+const allDocs = await userCollection.findAll();
+console.log(allDocs);
+```
+
+#### Find a specific document by ID
+
+```typescript
+const foundDoc = await userCollection.findById(newUser._id);
+console.log(foundDoc);
+```
+
+#### Update a document (MongoDB-like update syntax)
+
+```typescript
+const updatedDoc = await userCollection.update(newUser._id, {
+  $set: { value: "Updated Value" },
+});
+console.log(updatedDoc);
+```
+
+#### Delete a document
+
+```typescript
+const deleteResult = await userCollection.deleteById(newUser._id);
+console.log(deleteResult);
+```
+
+#### Use a specific database and collection
+
+```typescript
+const appSchemeCollection = client.db('idae_base').collection('appscheme');
+const docs = await appSchemeCollection.findAll();
+console.log(docs);
+```
+
+#### Delete many documents by query (be careful with this!)
+
+```typescript
+const deleteResult2 = await client
+  .collection('appscheme_base')
+  .deleteManyByQuery({ testField: 'testValue' });
+console.log(deleteResult2);
+```
+
+#### Register hooks/events on collection methods
+
+```typescript
+const usersCollection = client.collection('user');
+
+usersCollection.registerEvents({
+  findById: {
+    pre: (id) => console.log(`Before searching for ID: ${id}`),
+    post: (result, id) => console.log(`Result for ${id}:`, result),
+    error: (error) => console.error('Error on findById:', error)
+  },
+  // ... same for update, create, etc.
+});
+```
+
+---
+
+## 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.

package/dist/idae-api.d.ts

@@ -1,18 +1,18 @@
-// packages\idae-api\src\lib\idae-api.d.ts
-
-import mongoose from "mongoose";
-import { IdaeDb, IdaeDbAdapter } from "@medyll/idae-db";
-
-declare global {
-  namespace Express {
-    interface Request {
-      dbConnection?: mongoose.Connection;
-      collectionName?: string;
-      dbName?: string;
-      idaeDb?: IdaeDb;
-      connectedCollection: IdaeDbAdapter;
-    }
-  }
-}
-
-export {};
+// packages\idae-api\src\lib\idae-api.d.ts
+
+import mongoose from "mongoose";
+import { IdaeDb, IdaeDbAdapter } from "@medyll/idae-db";
+
+declare global {
+  namespace Express {
+    interface Request {
+      dbConnection?: mongoose.Connection;
+      collectionName?: string;
+      dbName?: string;
+      idaeDb?: IdaeDb;
+      connectedCollection: IdaeDbAdapter;
+    }
+  }
+}
+
+export {};

package/dist/server/IdaeApi.js

@@ -10,7 +10,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _a, _IdaeApi_instance, _IdaeApi_app, _IdaeApi_idaeApiOptions, _IdaeApi_routeManager, _IdaeApi_serverInstance, _IdaeApi_state, _IdaeApi_authMiddleware;
-// packages\idae-api\src\lib\IdaeApi.ts
+// packages\idae-api\src\lib\server\IdaeApi.ts
 import {} from "@medyll/idae-db";
 import express, {} from "express";
 import { idaeDbMiddleware } from "./middleware/databaseMiddleware.js";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@medyll/idae-api",
 	"scope": "@medyll",
-	"version": "0.119.0",
+	"version": "0.121.0",
 	"main": "./dist/index.js",
 	"module": "./dist/index.js",
 	"description": "A flexible and extensible API framework for Node.js, designed to work with multiple database types and configurations. It features a modular architecture, dynamic database connection management, and a flexible routing system. The framework supports TypeScript for improved robustness and maintainability.",
@@ -40,44 +40,44 @@
 		"@typegoose/auto-increment": "^4.13.0",
 		"express": "^5.1.0",
 		"jsonwebtoken": "^9.0.2",
-		"mongoose": "^8.13.2",
+		"mongoose": "^8.15.1",
 		"mongoose-sequence": "^6.0.1",
 		"qs": "^6.14.0",
 		"sequelize": "^6.37.7"
 	},
 	"devDependencies": {
-		"@medyll/idae-prettier-config": "^1.1.0",
-		"@sveltejs/adapter-auto": "^6.0.0",
-		"@sveltejs/kit": "^2.20.7",
+		"@medyll/idae-db": "^0.89.0",
+		"@medyll/idae-prettier-config": "next",
+		"@sveltejs/adapter-auto": "^6.0.1",
+		"@sveltejs/kit": "^2.21.2",
 		"@sveltejs/package": "^2.3.11",
-		"@sveltejs/vite-plugin-svelte": "^5.0.3",
+		"@sveltejs/vite-plugin-svelte": "^5.1.0",
 		"@types/eslint": "^9.6.1",
-		"@types/express": "^5.0.1",
 		"@types/jest": "^29.5.14",
 		"@types/jsonwebtoken": "^9.0.9",
 		"@types/mongoose": "^5.11.97",
 		"@types/mongoose-sequence": "^3.0.11",
 		"@types/supertest": "^6.0.3",
-		"eslint": "^9.25.0",
-		"eslint-config-prettier": "^10.1.2",
-		"eslint-plugin-svelte": "^3.5.1",
-		"globals": "^16.0.0",
+		"eslint": "^9.28.0",
+		"eslint-config-prettier": "^10.1.5",
+		"eslint-plugin-svelte": "^3.9.1",
+		"globals": "^16.2.0",
 		"jest": "^29.7.0",
 		"mongodb-memory-server": "^10.1.4",
-		"mysql2": "^3.14.0",
+		"mysql2": "^3.14.1",
 		"prettier": "^3.5.3",
-		"prettier-plugin-svelte": "^3.3.3",
-		"supertest": "^7.1.0",
-		"svelte": "^5.28.1",
-		"svelte-check": "^4.1.6",
+		"prettier-plugin-svelte": "^3.4.0",
+		"supertest": "^7.1.1",
+		"svelte": "^5.33.14",
+		"svelte-check": "^4.2.1",
 		"tslib": "^2.8.1",
-		"tsx": "^4.19.3",
+		"tsx": "^4.19.4",
 		"typescript": "^5.8.3",
-		"typescript-eslint": "^8.30.1",
-		"vite": "^6.3.2",
-		"vitest": "^3.1.1"
+		"typescript-eslint": "^8.33.1",
+		"vite": "^6.3.5",
+		"vitest": "^3.2.1"
 	},
 	"svelte": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"type": "module"
-}
+}