Idae API

Overview

Express-based Node.js API framework for the Idae ecosystem. Handles auth, security middleware, routing, and MongoDB connections with minimal config. Entry point is the idaeApi singleton — configure it with setOptions, then call start/stop.

Install

pnpm add @medyll/idae-api

Core API

• idaeApi — singleton instance; the single entry point for the entire framework
• idaeApi.setOptions(config) — configure CORS, helmet, rate limiting, JWT secret, DB URI, port, etc.
• idaeApi.start() — boot the Express server (applies middleware, mounts routes, opens DB connection)
• idaeApi.stop() — gracefully shut down the server and close DB connections
• RouteDefinition[] — array of route descriptors passed to setOptions({ routes }) to register endpoints
• Route handler signature: (service, params, body) => result — no raw req/res; the framework maps inputs and serialises the return value automatically

Usage

Minimal server

import { idaeApi } from '@medyll/idae-api';

idaeApi.setOptions({
  port: 3000,
  cors: true,
  helmet: true,
  rateLimit: 100,
  mongoUri: process.env.MONGO_URI,
  jwtSecret: process.env.JWT_SECRET,
  routes: [],
});

await idaeApi.start();

Defining routes

import type { RouteDefinition } from '@medyll/idae-api';

const routes: RouteDefinition[] = [
  {
    path: '/users',
    method: 'get',
    handler: async (service, params, body) => {
      return service.userService.findAll();
    },
  },
  {
    path: '/users/:id',
    method: 'get',
    handler: async (service, params, body) => {
      return service.userService.findById(params.id);
    },
  },
  {
    path: '/users',
    method: 'post',
    handler: async (service, params, body) => {
      return service.userService.create(body);
    },
  },
];

idaeApi.setOptions({ routes });
await idaeApi.start();

Graceful shutdown

process.on('SIGTERM', async () => {
  await idaeApi.stop();
  process.exit(0);
});

Key concepts

• Singleton pattern: import idaeApi and call setOptions before start — never instantiate directly
• setOptions is additive: call it multiple times to layer configuration (routes, middleware options, etc.)
• Handler signature (service, params, body): handlers never touch req/res; the framework extracts route params and request body, injects the service container, and serialises the return value as JSON
• RouteDefinition[]: pass the full array of route descriptors via setOptions({ routes }) — each entry declares path, method, optional middleware, and handler
• DB connection is managed internally by start/stop — no manual connectDb call needed
• JWT middleware is activated automatically when jwtSecret is set in setOptions
• Rate limiting is per-IP by default; set rateLimit (requests per window) in setOptions

Source: medyll/idae — distributed by TomeVault.