@airoom/nextmin-node 1.4.6 → 2.0.1

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

@@ -23,6 +23,7 @@ export declare class APIRouter {
     private liveSchemas;
     private notFoundHandler?;
     private fileStorage?;
+    private realtimeService?;
     private fileRoutesMounted;
     constructor(options: APIRouterOptions);
     getRouter(): express.Router;
@@ -32,6 +33,7 @@ export declare class APIRouter {
     private setLiveSchemas;
     private rebuildModels;
     private mountSchemasEndpointOnce;
+    private mountCleanupEndpointOnce;
     private mountRoutes;
     private mountFindRoutes;
     private mountSearchRoutes;

package/dist/api/apiRouter.js

@@ -9,9 +9,9 @@ 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 setupFileRoutes_1 = require("./router/setupFileRoutes");
 const setupAuthRoutes_1 = require("./router/setupAuthRoutes");
 const mountCrudRoutes_1 = require("./router/mountCrudRoutes");
@@ -101,6 +101,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 ----------
@@ -174,16 +185,16 @@ class APIRouter {
         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,6 +207,7 @@ class APIRouter {
             }
             this.rebuildModels(Object.values(initialSchemas));
             this.mountSchemasEndpointOnce();
+            this.mountCleanupEndpointOnce();
             this.mountRoutes(initialSchemas);
             this.mountFindRoutes();
             this.mountSearchRoutes();
@@ -206,6 +218,7 @@ 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);
@@ -260,6 +273,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 +324,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());
@@ -412,10 +449,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 +487,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;
     }