@medyll/idae-api 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,240 @@
+# @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.
+ 

package/dist/client/IdaeApiClient.d.ts

@@ -0,0 +1,21 @@
+import { type IdaeApiClientConfigCoreOptions } from './IdaeApiClientConfig';
+import { IdaeApiClientCollection } from './IdaeApiClientCollection';
+import { IdaeApiClientRequest } from './IdaeApiClientRequest';
+type IdaeApiClientRequestParams<T = any> = Record<string, T>;
+declare class IdaeApiClient {
+    private clientConfig;
+    private _request;
+    constructor(clientConfig?: IdaeApiClientConfigCoreOptions & {
+        baseUrl?: string;
+    });
+    get request(): IdaeApiClientRequest;
+    getDbList(): Promise<Response>;
+    getCollections(dbName: string): Promise<Response>;
+    db(dbName: string): {
+        collection: (collectionName: string) => IdaeApiClientCollection;
+        getCollections: () => Promise<Response>;
+    };
+    collection(collectionName: string, dbName?: string): IdaeApiClientCollection;
+}
+export { IdaeApiClient };
+export type { IdaeApiClientRequestParams };

package/dist/client/IdaeApiClient.js

@@ -0,0 +1,31 @@
+// packages\idae-api\src\lib\client\IdaeApiClient.ts
+import { IdaeApiClientConfig, IdaeApiClientConfigCore } from './IdaeApiClientConfig';
+import { IdaeApiClientCollection } from './IdaeApiClientCollection';
+import { IdaeApiClientRequest } from './IdaeApiClientRequest';
+class IdaeApiClient {
+    constructor(clientConfig) {
+        this.clientConfig = IdaeApiClientConfig;
+        this.clientConfig.setOptions(clientConfig);
+        this._request = new IdaeApiClientRequest(this.clientConfig);
+    }
+    get request() {
+        return this._request;
+    }
+    async getDbList() {
+        return this._request.doRequest({ routeNamespace: 'methods/dbs' });
+    }
+    async getCollections(dbName) {
+        return this._request.doRequest({ dbName, routeNamespace: 'methods/collections' });
+    }
+    db(dbName) {
+        return {
+            collection: (collectionName) => new IdaeApiClientCollection(this, dbName, collectionName),
+            getCollections: () => this.getCollections(dbName)
+        };
+    }
+    collection(collectionName, dbName) {
+        dbName = dbName || this.clientConfig.defaultDb;
+        return new IdaeApiClientCollection(this, dbName, collectionName);
+    }
+}
+export { IdaeApiClient };

package/dist/client/IdaeApiClientCollection.d.ts

@@ -0,0 +1,14 @@
+import { IdaeApiClient } from './IdaeApiClient';
+import type { IdaeApiClientRequestParams } from './IdaeApiClient';
+declare class IdaeApiClientCollection {
+    private apiClient;
+    private meta;
+    constructor(apiClient: IdaeApiClient, dbName: string, collectionName: string);
+    findAll<T>(params?: IdaeApiClientRequestParams): 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: IdaeApiClientRequestParams): Promise<Response>;
+}
+export { IdaeApiClientCollection };

package/dist/client/IdaeApiClientCollection.js

@@ -0,0 +1,53 @@
+// packages\idae-api\src\lib\client\IdaeApiClientCollection.ts
+import { IdaeApiClient } from './IdaeApiClient';
+class IdaeApiClientCollection {
+    constructor(apiClient, dbName, collectionName) {
+        this.apiClient = apiClient;
+        this.meta = {
+            dbName,
+            collectionName
+        };
+    }
+    async findAll(params) {
+        return this.apiClient.request.doRequest({
+            ...this.meta,
+            params
+        });
+    }
+    async findById(id) {
+        return this.apiClient.request.doRequest({
+            ...this.meta,
+            slug: id
+        });
+    }
+    async create(body) {
+        return this.apiClient.request.doRequest({
+            method: 'POST',
+            ...this.meta,
+            body
+        });
+    }
+    async update(id, body) {
+        return this.apiClient.request.doRequest({
+            method: 'PUT',
+            ...this.meta,
+            body,
+            slug: id
+        });
+    }
+    async deleteById(id) {
+        return this.apiClient.request.doRequest({
+            method: 'DELETE',
+            ...this.meta,
+            slug: id
+        });
+    }
+    async deleteManyByQuery(params) {
+        return this.apiClient.request.doRequest({
+            method: 'DELETE',
+            ...this.meta,
+            params
+        });
+    }
+}
+export { IdaeApiClientCollection };

package/dist/client/IdaeApiClientConfig.d.ts

@@ -0,0 +1,23 @@
+export interface IdaeApiClientConfigCoreOptions {
+    host: string;
+    port: number;
+    method: 'http' | 'https';
+    defaultDb: string;
+    separator: string;
+}
+export declare class IdaeApiClientConfigCore {
+    private static instance;
+    private options;
+    private _baseUrl;
+    private constructor();
+    static getInstance(): IdaeApiClientConfigCore;
+    setOptions(options?: Partial<IdaeApiClientConfigCoreOptions> | undefined): void;
+    get baseUrl(): string;
+    private forgeBaseUrl;
+    get host(): string;
+    get port(): number;
+    get method(): 'http' | 'https';
+    get separator(): string;
+    get defaultDb(): string;
+}
+export declare const IdaeApiClientConfig: IdaeApiClientConfigCore;

package/dist/client/IdaeApiClientConfig.js

@@ -0,0 +1,43 @@
+export class IdaeApiClientConfigCore {
+    constructor() {
+        this.options = {
+            host: 'localhost',
+            port: 3000,
+            method: 'https',
+            defaultDb: 'idaenext_sitebase_app',
+            separator: '//'
+        };
+    }
+    static getInstance() {
+        if (!IdaeApiClientConfigCore.instance) {
+            IdaeApiClientConfigCore.instance = new IdaeApiClientConfigCore();
+        }
+        return IdaeApiClientConfigCore.instance;
+    }
+    setOptions(options = {}) {
+        this.options = { ...this.options, ...options };
+        this._baseUrl = this.forgeBaseUrl();
+    }
+    get baseUrl() {
+        return this._baseUrl;
+    }
+    forgeBaseUrl() {
+        return `${this.method}:${this.separator}${this.host}:${this.port}`;
+    }
+    get host() {
+        return this.options.host;
+    }
+    get port() {
+        return this.options.port;
+    }
+    get method() {
+        return this.options.method;
+    }
+    get separator() {
+        return this.options.separator;
+    }
+    get defaultDb() {
+        return this.options.defaultDb;
+    }
+}
+export const IdaeApiClientConfig = IdaeApiClientConfigCore.getInstance();

package/dist/client/IdaeApiClientRequest.d.ts

@@ -0,0 +1,24 @@
+import { IdaeApiClientConfigCore } from './IdaeApiClientConfig';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+type RouteNamespace = `methods/${'dbs' | 'collections'}` | undefined;
+interface UrlParams {
+    dbName?: string;
+    collectionName?: string;
+    slug?: string;
+    params?: Record<string, string>;
+    routeNamespace?: RouteNamespace;
+}
+interface RequestOptions<T> extends UrlParams {
+    baseUrl?: string;
+    method?: HttpMethod;
+    body?: T;
+    headers?: RequestInit['headers'];
+}
+declare class IdaeApiClientRequest {
+    private baseUrl;
+    private clientConfig;
+    constructor(clientConfig: IdaeApiClientConfigCore);
+    doRequest<T>({ baseUrl, method, body, headers, dbName, collectionName, slug, params, routeNamespace }: RequestOptions<T>): Promise<Response>;
+    private buildUrl;
+}
+export { IdaeApiClientRequest, type HttpMethod, type RouteNamespace, type UrlParams, type RequestOptions };

package/dist/client/IdaeApiClientRequest.js

@@ -0,0 +1,47 @@
+// packages\idae-api\src\lib\client\IdaeApiClientRequest.ts
+import { IdaeApiClientConfigCore } from './IdaeApiClientConfig';
+class IdaeApiClientRequest {
+    constructor(clientConfig) {
+        this.clientConfig = clientConfig;
+        this.baseUrl = `${this.clientConfig.method}:${this.clientConfig.separator}${this.clientConfig.host}:${this.clientConfig.port}`;
+    }
+    async doRequest({ baseUrl = this.baseUrl, method = 'GET', body, headers = {
+        'Content-Type': 'application/json'
+    }, dbName = this.clientConfig.defaultDb, collectionName, slug, params, routeNamespace }) {
+        const url = this.buildUrl({
+            routeNamespace,
+            dbName,
+            collectionName,
+            slug,
+            params
+        }).replace('//', '/');
+        const response = await fetch(`${baseUrl}${url}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        try {
+            return response.json();
+        }
+        catch (e) {
+            console.error(e);
+            throw new Error(`Invalid returned type`);
+        }
+    }
+    buildUrl({ dbName, collectionName, slug, params, routeNamespace }) {
+        const urls = [`/`];
+        if (routeNamespace)
+            urls.push(routeNamespace);
+        if (dbName ?? collectionName)
+            urls.push([dbName, collectionName].filter((x) => x).join('.'));
+        if (slug)
+            urls.push(slug);
+        if (params)
+            urls.push(`?${new URLSearchParams(params).toString()}`);
+        return urls.join('/').replace('//', '/');
+    }
+}
+export { IdaeApiClientRequest };

package/dist/config/routeDefinitions.d.ts

@@ -0,0 +1,10 @@
+import { DBaseService } from '../server/services/DBaseService';
+type RouteHandler = (service: DBaseService<any>, params: any, body?: any) => Promise<any>;
+export interface RouteDefinition {
+    method: string | string[];
+    path: string;
+    handler: RouteHandler;
+    disabled?: boolean;
+}
+export declare const routes: RouteDefinition[];
+export {};

package/dist/config/routeDefinitions.js

@@ -0,0 +1,48 @@
+// packages\idae-api\src\lib\config\routeDefinitions.ts
+import { DBaseService } from '../server/services/DBaseService';
+export const routes = [
+    {
+        method: 'get',
+        path: '/:collectionName',
+        handler: async (service, params) => service.where(params)
+    },
+    {
+        method: 'get',
+        path: '/:collectionName/:id',
+        handler: async (service, params) => service.findById(params.id)
+    },
+    {
+        method: 'post',
+        path: '/:collectionName',
+        handler: async (service, params, body) => service.create(body)
+    },
+    {
+        method: 'put',
+        path: '/:collectionName/:id',
+        handler: async (service, params, body) => service.update(params.id, body)
+    },
+    {
+        method: 'delete',
+        path: '/:collectionName/:id',
+        handler: async (service, params) => service.deleteById(params.id)
+    },
+    {
+        method: 'delete',
+        path: '/:collectionName',
+        handler: async (service, params) => service.deleteManyByQuery(params)
+    },
+    {
+        method: ['where', 'create', 'update', 'deleteById', 'deleteManyByQuery'], // default method is then GET or OPTIONS (set further)
+        path: '/query/:collectionName/:command/:parameters?',
+        handler: async (service, params, body) => {
+            const decodedParams = params.body ? service.decodeUrlParams(params.body) : {};
+            console.log(params.command, 'params --- ', { body });
+            return service?.[params.command]?.({ query: body });
+        }
+    },
+    {
+        method: ['dbs', 'collections'], // default method is then GET or OPTIONS (set further)
+        path: '/methods/:methodName/:params?',
+        handler: async (service, params) => { }
+    }
+];

package/dist/idae-api.d.ts

@@ -0,0 +1,15 @@
+// packages\idae-api\src\lib\idae-api.d.ts
+
+import mongoose from 'mongoose';
+
+declare global {
+	namespace Express {
+		interface Request {
+			dbConnection?: mongoose.Connection;
+			collectionName?: string;
+			dbName?: string;
+		}
+	}
+}
+
+export {};

package/dist/index.d.ts

@@ -1 +1,5 @@
-export { ApiServe } from './ApiServe.js';
+export * from './server/IdaeApi.js';
+export * from './client/IdaeApiClient.js';
+export * from './client/IdaeApiClientCollection.js';
+export * from './client/IdaeApiClientConfig.js';
+export * from './client/IdaeApiClientRequest.js';

package/dist/index.js

@@ -1,2 +1,6 @@
 // Reexport your entry components here
-export { ApiServe } from './ApiServe.js';
+export * from './server/IdaeApi.js';
+export * from './client/IdaeApiClient.js';
+export * from './client/IdaeApiClientCollection.js';
+export * from './client/IdaeApiClientConfig.js';
+export * from './client/IdaeApiClientRequest.js';

package/dist/server/IdaeApi.d.ts

@@ -0,0 +1,38 @@
+import express from 'express';
+import { type RouteDefinition } from '../config/routeDefinitions';
+import { RouteManager } from './engine/routeManager';
+interface IdaeApiOptions {
+    port?: number;
+    routes?: RouteDefinition[];
+    onInUse?: 'reboot' | 'fail' | 'replace';
+    enableAuth?: boolean;
+    jwtSecret?: string;
+    tokenExpiration?: string;
+}
+declare class IdaeApi {
+    private static instance;
+    private _app;
+    private options;
+    private routeManager;
+    private serverInstance;
+    private _state;
+    private authMiddleware;
+    private constructor();
+    static getInstance(): IdaeApi;
+    get state(): 'stopped' | 'running';
+    get app(): express.Express;
+    setOptions(options: IdaeApiOptions): void;
+    private initializeAuth;
+    configureIdaeApi(): void;
+    private configureMiddleware;
+    private configureRoutes;
+    private configureErrorHandling;
+    start(): void;
+    private handleServerError;
+    stop(): void;
+    private addRouteToExpress;
+    private handleRequest;
+    get router(): RouteManager;
+}
+declare const idaeApi: IdaeApi;
+export { idaeApi };