@airoom/nextmin-node 1.4.6 → 2.0.2

package/README.md

@@ -12,13 +12,15 @@ Read the full documentation at: https://nextmin.gscodes.dev/
 ## Highlights
 
 - Express router factory: mount a complete REST API in a few lines
+- **Native Realtime Support**: Built-in Socket.io integration for instant schema updates and data synchronization
+- **Event-Driven Architecture**: Lifecycle hooks (`before:create`, `after:update`, etc.) for custom business logic
 - Auth built in: register, login, me, change‑password, forgot‑password
 - CRUD per model with read masks, write restrictions, and role/owner policies
 - Advanced list endpoint: filter, multi‑field search, date ranges, multi‑field sort, paginate
 - Relationship endpoints: forward and reverse lookups without autopopulate
 - Schemas hot‑reload during development; automatic model wiring
 - File uploads via pluggable storage (e.g., S3/MinIO); delete by key
-- Database adapters: MongoDB (with index sync) and in‑memory for tests
+- Database adapters: **NMAdapter (Recommended)** supports SQL (Postgres/SQLite/MySQL) and MongoDB via TypeORM. The standalone `MongoAdapter` and `InMemoryAdapter` are now deprecated.
 - Emits a trusted API key stored in your Settings model for client access
 
 ## Installation
@@ -42,7 +44,7 @@ import express from 'express';
 import http from 'http';
 import {
   createNextMinRouter,
-  MongoAdapter,
+  NMAdapter,
   S3FileStorageAdapter,
 } from '@airoom/nextmin-node';
 import cors from 'cors';
@@ -55,8 +57,12 @@ async function start() {
 
   app.use(cors());
 
-  // 1) Database
-  const db = new MongoAdapter(process.env.MONGO_URL!, process.env.MONGO_DB!);
+  // 1) Database (NMAdapter supports SQL and MongoDB)
+  const db = new NMAdapter({
+    type: 'postgres', // or 'mongodb', 'sqlite', 'mysql'
+    url: process.env.DATABASE_URL,
+    synchronize: true, // typical for development
+  });
   await db.connect();
 
   // 2) Optional: file storage adapter (S3/MinIO)
@@ -77,7 +83,12 @@ async function start() {
   });
 
   // 3) Mount NextMin REST router
-  const router = createNextMinRouter({ dbAdapter: db, server, fileStorageAdapter: files });
+  // Pass the 'server' instance to enable native Realtime/WebSockets
+  const router = createNextMinRouter({ 
+    dbAdapter: db, 
+    server: server, // REQUIRED for realtime
+    fileStorageAdapter: files 
+  });
   app.use('/rest', router);
 
   // 4) Listen with the same server instance
@@ -115,6 +126,38 @@ Base: `/rest`
   - Upload: `POST /files` (multipart form, fields named `file`)
   - Delete: `DELETE /files/:key(*)`
 
+## Event System (Hooks)
+
+NextMin provides a powerful event-driven system to inject custom logic before or after database operations.
+
+```ts
+import { events, Events, getModelEvent } from '@airoom/nextmin-node';
+
+// Global hook: Run logic after any document is created
+events.on(Events.AFTER_CREATE, ({ modelName, data }) => {
+    console.log(`Document created in ${modelName}:`, data.id);
+});
+
+// Model-specific hook: Send email after a User registers
+events.on(getModelEvent('User', 'create', 'after'), ({ data }) => {
+    sendWelcomeEmail(data.email);
+});
+
+// Validation hook: Prevent deletion if certain conditions aren't met
+events.on(getModelEvent('Post', 'delete', 'before'), ({ id }) => {
+    if (isSystemProtected(id)) {
+        throw new Error("This post cannot be deleted.");
+    }
+});
+```
+
+### Available Events
+- `before:doc:create`, `after:doc:create`
+- `before:doc:update`, `after:doc:update`
+- `before:doc:delete`, `after:doc:delete`
+- `before:doc:read`, `after:doc:read`
+- `auth:login`, `auth:signup`, `schema:update`
+
 See full examples in documentation and the `examples/node` app inside this monorepo.
 
 ## Headers and auth

package/dist/api/apiRouter.d.ts

@@ -6,6 +6,10 @@ export interface APIRouterOptions {
     dbAdapter: DatabaseAdapter;
     server?: HttpServer;
     fileStorageAdapter?: FileStorageAdapter;
+    imageProxy?: {
+        originalBase?: string;
+        proxyBase?: string;
+    };
 }
 export declare class APIRouter {
     private router;
@@ -14,16 +18,19 @@ export declare class APIRouter {
     private jwtSecret;
     private trustedApiKey;
     private schemaLoader;
-    private isDevelopment;
+    private get isDevelopment();
     private findRoutesMounted;
     private searchRoutesMounted;
+    private batchRoutesMounted;
     private authRoutesInitialized;
     private schemasRouteRegistered;
     private registeredModels;
     private liveSchemas;
     private notFoundHandler?;
     private fileStorage?;
+    private realtimeService?;
     private fileRoutesMounted;
+    private aggregateService?;
     constructor(options: APIRouterOptions);
     getRouter(): express.Router;
     private wireSchemaHotReload;
@@ -32,9 +39,11 @@ export declare class APIRouter {
     private setLiveSchemas;
     private rebuildModels;
     private mountSchemasEndpointOnce;
+    private mountCleanupEndpointOnce;
     private mountRoutes;
     private mountFindRoutes;
     private mountSearchRoutes;
+    private mountBatchRoutes;
     private mountFileRoutes;
     private createCtx;
     private getSchema;

package/dist/api/apiRouter.js

@@ -9,19 +9,26 @@ const BaseModel_1 = require("../models/BaseModel");
 const Logger_1 = __importDefault(require("../utils/Logger"));
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const SchemaLoader_1 = require("../utils/SchemaLoader");
-const InMemoryAdapter_1 = require("../database/InMemoryAdapter");
 const DefaultDataInitializer_1 = require("../utils/DefaultDataInitializer");
-const SchemaService_1 = require("../services/SchemaService");
+const RealtimeService_1 = require("../services/RealtimeService");
+const Events_1 = require("../utils/Events");
+const AggregateService_1 = require("../services/AggregateService");
 const setupFileRoutes_1 = require("./router/setupFileRoutes");
 const setupAuthRoutes_1 = require("./router/setupAuthRoutes");
 const mountCrudRoutes_1 = require("./router/mountCrudRoutes");
 const mountFindRoutes_1 = require("./router/mountFindRoutes");
 const mountSearchRoutes_1 = require("./router/mountSearchRoutes");
+const mountBatchRoutes_1 = require("./router/mountBatchRoutes");
 class APIRouter {
+    get isDevelopment() {
+        return (process.env.APP_MODE?.toLowerCase() !== 'production' &&
+            process.env.NODE_ENV?.toLowerCase() !== 'production');
+    }
     constructor(options) {
         this.models = {};
         this.findRoutesMounted = false;
         this.searchRoutesMounted = false;
+        this.batchRoutesMounted = false;
         this.authRoutesInitialized = false;
         this.schemasRouteRegistered = false;
         this.registeredModels = new Set();
@@ -101,6 +108,17 @@ class APIRouter {
                     return n ? n.toLowerCase() : null;
                 }
             }
+            // Handle numeric IDs (common in SQL databases like SQLite)
+            if (typeof value === 'number' && rolesModel) {
+                try {
+                    const docs = await rolesModel.read({ id: value }, 1, 0, true);
+                    const n = docs?.[0]?.name;
+                    return typeof n === 'string' ? n.toLowerCase() : null;
+                }
+                catch {
+                    return null;
+                }
+            }
             return null;
         };
         // ---------- auth middlewares ----------
@@ -171,19 +189,18 @@ class APIRouter {
             }
             return missing;
         };
-        this.isDevelopment = process.env.APP_MODE !== 'production';
         this.router = express_1.default.Router();
         this.fileStorage = options.fileStorageAdapter;
-        this.dbAdapter = options.dbAdapter || new InMemoryAdapter_1.InMemoryAdapter();
+        this.dbAdapter = options.dbAdapter;
         this.jwtSecret = process.env.JWT_SECRET || 'default_jwt_secret';
-        if (this.isDevelopment && options.server) {
-            (0, SchemaService_1.startSchemaService)(options.server, {
+        if (options.server) {
+            this.realtimeService = new RealtimeService_1.RealtimeService(options.server, {
                 getApiKey: () => this.trustedApiKey,
             });
             options.server.on('listening', () => {
                 // @ts-ignore
                 const addr = options.server.address();
-                Logger_1.default.info('SchemaService', `[schema-service] started at /__nextmin__/schema ns /schema on ${typeof addr === 'string' ? addr : `${addr?.address}:${addr?.port}`}`);
+                Logger_1.default.info('RealtimeService', `Started at /__nextmin__/realtime ns /realtime on ${typeof addr === 'string' ? addr : `${addr?.address}:${addr?.port}`}`);
             });
         }
         this.schemaLoader =
@@ -196,9 +213,11 @@ class APIRouter {
             }
             this.rebuildModels(Object.values(initialSchemas));
             this.mountSchemasEndpointOnce();
+            this.mountCleanupEndpointOnce();
             this.mountRoutes(initialSchemas);
             this.mountFindRoutes();
             this.mountSearchRoutes();
+            this.mountBatchRoutes();
             this.mountFileRoutes();
             await this.syncAllIndexes(initialSchemas);
             const initializer = new DefaultDataInitializer_1.DefaultDataInitializer(this.dbAdapter, this.models);
@@ -206,11 +225,13 @@ class APIRouter {
                 await initializer.initialize();
                 this.trustedApiKey = initializer.getApiKey() || '';
                 Logger_1.default.info('APIRouter', `Trusted API key set: ${this.trustedApiKey ? '[hidden]' : 'none'}`);
+                Events_1.events.emitEvent(Events_1.Events.SERVER_START, { trustedApiKey: this.trustedApiKey });
             }
             catch (err) {
                 Logger_1.default.error('APIRouter', 'Failed to initialize default data', err);
             }
             this.setupNotFoundMiddleware();
+            this.aggregateService = new AggregateService_1.AggregateService(this.createCtx());
             this.wireSchemaHotReload();
         };
         if (typeof this.dbAdapter.registerSchemas === 'function') {
@@ -260,6 +281,7 @@ class APIRouter {
                 this.mountRoutes(newSchemas);
                 await this.syncAllIndexes(newSchemas);
                 Logger_1.default.info('APIRouter', `Schemas reloaded (added/updated: ${Object.keys(newSchemas).length}, removed: ${removed.join(', ') || 'none'})`);
+                Events_1.events.emitEvent(Events_1.Events.SCHEMA_UPDATE, { schemas: newSchemas, removed });
             }
             catch (err) {
                 Logger_1.default.error('APIRouter', 'Failed to refresh after schemasChanged', err);
@@ -310,15 +332,38 @@ class APIRouter {
             return;
         this.schemasRouteRegistered = true;
         this.router.get('/_schemas', this.optionalAuthMiddleware, async (req, res) => {
-            const role = await this.normalizeRoleName(this.getUserRoleFromReq(req));
-            // Typically admin/superadmin can see clinical/private fields in schema
-            const showPrivate = role === 'admin' || role === 'superadmin';
+            // Typically admin/superadmin can see clinical/private fields in schema.
+            // We now always include them in metadata so the frontend can decide visibility.
             res.json({
                 success: true,
-                data: this.schemaLoader.getPublicSchemaList(showPrivate),
+                data: this.schemaLoader.getPublicSchemaList(true),
             });
         });
     }
+    mountCleanupEndpointOnce() {
+        this.router.post('/_cleanup', this.optionalAuthMiddleware, async (req, res) => {
+            try {
+                if (typeof this.dbAdapter.cleanupUnusedFields !== 'function') {
+                    return res.status(501).json({
+                        success: false,
+                        message: 'Database adapter does not support cleanup',
+                    });
+                }
+                const report = await this.dbAdapter.cleanupUnusedFields(this.schemaLoader.getSchemas());
+                res.json({
+                    success: true,
+                    data: report,
+                });
+            }
+            catch (err) {
+                Logger_1.default.error('APIRouter', 'Cleanup failed', err);
+                res.status(500).json({
+                    success: false,
+                    message: err.message || 'Cleanup failed',
+                });
+            }
+        });
+    }
     mountRoutes(schemas) {
         if (!this.authRoutesInitialized && this.liveSchemas['users']) {
             (0, setupAuthRoutes_1.setupAuthRoutes)(this.createCtx());
@@ -347,6 +392,13 @@ class APIRouter {
         (0, mountSearchRoutes_1.mountSearchRoutes)(this.createCtx());
         this.ensureNotFoundLast();
     }
+    mountBatchRoutes() {
+        if (this.batchRoutesMounted)
+            return;
+        this.batchRoutesMounted = true;
+        (0, mountBatchRoutes_1.mountBatchRoutes)(this.createCtx());
+        this.ensureNotFoundLast();
+    }
     mountFileRoutes() {
         if (this.fileRoutesMounted)
             return;
@@ -412,10 +464,13 @@ class APIRouter {
             return;
         }
         if (error?.code === 11000) {
-            const field = Object.keys(error.keyPattern || {})[0];
-            res
-                .status(400)
-                .json({ error: true, message: `Duplicate value for field: ${field}` });
+            const field = Object.keys(error.keyPattern || error.keyValue || {}).find((k) => k !== '_id') ||
+                Object.keys(error.keyPattern || error.keyValue || {})[0] ||
+                'unknown';
+            res.status(400).json({
+                error: true,
+                message: `Duplicate value for field: ${field}. ${error.message || ''}`,
+            });
         }
         else {
             res.status(400).json({ error: true, message: error?.message || 'Error' });
@@ -447,14 +502,20 @@ class APIRouter {
             .map(([key]) => key);
         const conflictingFields = [];
         for (const field of uniqueFields) {
-            if (data[field] !== undefined) {
-                const query = { [field]: data[field] };
-                if (excludeId)
-                    query.id = { $ne: excludeId };
-                const existingRecords = await this.getModel(schema.modelName.toLowerCase()).read(query);
-                if (existingRecords.length > 0)
-                    conflictingFields.push(field);
+            const val = data[field];
+            const attr = schema.attributes?.[field];
+            const isRequired = Array.isArray(attr) ? attr[0]?.required : attr?.required;
+            // Sparse uniqueness: skip checking if value is empty/null AND the field is not required
+            if (val === undefined || val === null || (typeof val === 'string' && val.trim() === '')) {
+                if (!isRequired)
+                    continue;
             }
+            const query = { [field]: val };
+            if (excludeId)
+                query.id = { $ne: excludeId };
+            const existingRecords = await this.getModel(schema.modelName.toLowerCase()).read(query);
+            if (existingRecords.length > 0)
+                conflictingFields.push(field);
         }
         return conflictingFields.length > 0 ? conflictingFields : null;
     }

package/dist/api/router/mountBatchRoutes.d.ts

@@ -0,0 +1,2 @@
+import type { RouterCtx } from './ctx';
+export declare function mountBatchRoutes(ctx: RouterCtx): void;

package/dist/api/router/mountBatchRoutes.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountBatchRoutes = mountBatchRoutes;
+const authorize_1 = require("../../policy/authorize");
+const QueryEngine_1 = require("../../database/QueryEngine");
+const utils_1 = require("./utils");
+function mountBatchRoutes(ctx) {
+    const { router } = ctx;
+    router.post('/_batch', ctx.optionalAuthMiddleware, async (req, res) => {
+        try {
+            const batchRequest = req.body;
+            if (!batchRequest || typeof batchRequest !== 'object') {
+                return res.status(400).json({ error: true, message: 'Invalid batch request' });
+            }
+            const results = {};
+            for (const [key, config] of Object.entries(batchRequest)) {
+                try {
+                    const { path, query: queryParams } = config;
+                    if (!path) {
+                        results[key] = { error: true, message: 'Missing path' };
+                        continue;
+                    }
+                    // Path is usually something like "/doctors" or "/doctors?slug=... "
+                    // We need to extract the model name
+                    const modelMatch = path.match(/^\/([^/?]+)/);
+                    if (!modelMatch) {
+                        results[key] = { error: true, message: 'Invalid path' };
+                        continue;
+                    }
+                    const modelName = modelMatch[1].toLowerCase();
+                    const schema = ctx.getSchema(modelName);
+                    const model = ctx.getModel(modelName);
+                    // Prepare pseudo-request for parseQuery
+                    const pseudoReq = {
+                        query: queryParams || {},
+                        user: req.user,
+                    };
+                    const { limit, page, skip, sort, projection, sample, _populate } = (0, utils_1.parseQuery)(pseudoReq);
+                    const filter = QueryEngine_1.QueryEngine.parse(pseudoReq.query, schema);
+                    const roleStr = req.user?.role;
+                    const pctx = {
+                        isAuthenticated: !!req.user,
+                        role: typeof roleStr === 'string' ? roleStr.toLowerCase() : null,
+                        userId: req.user?.id || req.user?._id || null,
+                        isSuperadmin: roleStr?.toLowerCase() === 'superadmin',
+                        apiKeyOk: true,
+                    };
+                    const rdec = (0, authorize_1.authorize)(modelName, 'read', { allowedMethods: schema.allowedMethods, access: schema.access }, pctx);
+                    if (!rdec.allow) {
+                        results[key] = { error: true, message: 'Forbidden' };
+                        continue;
+                    }
+                    const finalFilter = { ...filter, ...(rdec.queryFilter || {}) };
+                    // Handle countBy if present in query
+                    const countBy = String(pseudoReq.query.countBy || '').trim();
+                    if (countBy && schema.attributes[countBy]) {
+                        const counts = await ctx.dbAdapter.countBy(schema.modelName, countBy, finalFilter, schema);
+                        results[key] = { success: true, counts };
+                        continue;
+                    }
+                    const totalRows = await model.count(finalFilter);
+                    const rows = await model.read(finalFilter, limit, skip, !!rdec.exposePrivate, {
+                        sort,
+                        projection,
+                        sample,
+                        _populate,
+                    });
+                    const data = rdec.exposePrivate
+                        ? (0, authorize_1.applyReadMaskMany)(rows, rdec.sensitiveMask)
+                        : (0, authorize_1.applyReadMaskMany)(rows, rdec.readMask);
+                    results[key] = {
+                        success: true,
+                        data,
+                        pagination: { totalRows, page, limit },
+                    };
+                }
+                catch (err) {
+                    results[key] = { error: true, message: err.message || 'Error' };
+                }
+            }
+            return res.status(200).json({
+                success: true,
+                results,
+            });
+        }
+        catch (err) {
+            return res.status(500).json({ error: true, message: err.message || 'Batch execution failed' });
+        }
+    });
+}